feat!: common chart v2.0.0

.github/workflows/pull-request.yml

@@ -13,39 +13,62 @@ jobs:
     uses: entur/gha-meta/.github/workflows/verify-pr.yml@v1
 
   unittest-common-chart:
-    uses: entur/gha-helm/.github/workflows/unittest.yml@v1
-    with:
-      chart: charts/common
+    name: unittest (helm ${{ matrix.helm-version }})
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        helm-version: [v3.20.0, v4.1.3]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Helm
+        uses: azure/setup-helm@dda3372f752e03dde6b3237bc9431cdc2f7a02a2 # v5.0.0
+        with:
+          version: ${{ matrix.helm-version }}
+
+      - name: Install helm-unittest plugin
+        run: helm plugin install https://github.com/helm-unittest/helm-unittest.git || helm plugin install --verify=false https://github.com/helm-unittest/helm-unittest.git
+
+      - name: Run unit tests
+        run: helm unittest ./charts/common
 
   helm-install-test:
-    name: helm install
+    name: helm install (helm ${{ matrix.helm-version }})
     runs-on: ubuntu-24.04
     needs: unittest-common-chart
+    strategy:
+      matrix:
+        helm-version: [v3.20.0, v4.1.3]
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Helm
-        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
+        uses: azure/setup-helm@dda3372f752e03dde6b3237bc9431cdc2f7a02a2 # v5.0.0
+        with:
+          version: ${{ matrix.helm-version }}
 
       - name: Create kind cluster
         uses: helm/kind-action@ef37e7f390d99f746eb8b610417061a60e82a6cc # v1.14.0
         with:
-          node_image: kindest/node:v1.32.3
+          node_image: kindest/node:v1.35.1
 
-      - name: Configure metrics and VPA
+      - name: Configure metrics, VPA and StartupCPUBoost
         run: |
           helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
+          helm repo add cowboysysop https://cowboysysop.github.io/charts/
+          helm repo add kube-startup-cpu-boost https://google.github.io/kube-startup-cpu-boost
           helm repo update
           helm install --set args={--kubelet-insecure-tls} metrics-server metrics-server/metrics-server --namespace kube-system
-          helm repo add cowboysysop https://cowboysysop.github.io/charts/
           helm -n kube-system install vertical-pod-autoscaler cowboysysop/vertical-pod-autoscaler
+          helm install kube-startup-cpu-boost kube-startup-cpu-boost/kube-startup-cpu-boost --namespace kube-startup-cpu-boost-system --create-namespace --wait --timeout 5m0s
 
       - name: Install helm chart
         run: |
-          helm install --generate-name --dependency-update --wait --timeout 5m0s charts/common --values fixture/helm/ci/values-ci-tests.yaml
-          helm install --generate-name --dependency-update --wait --timeout 5m0s charts/common --values fixture/helm/ci/values-ci-cronjob-tests.yaml
+          helm install ci-deployment --dependency-update --wait --timeout 5m0s charts/common --values fixture/helm/ci/values-ci-tests.yaml
+          helm install ci-cronjob --dependency-update --wait --timeout 5m0s charts/common --values fixture/helm/ci/values-ci-cronjob-tests.yaml
 
   validate-examples:
+    name: examples (${{ matrix.example }}/${{ matrix.env }}/helm ${{ matrix.helm-version }})
     runs-on: ubuntu-24.04
     strategy:
       matrix:
@@ -56,8 +79,11 @@ jobs:
             typical-frontend,
             multi-container,
             multi-deploy,
+            cronjob,
+            grpc-app,
           ]
         env: [dev, tst, prd]
+        helm-version: [v3.20.0, v4.1.3]
     steps:
       - name: Check out the repo
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -66,9 +92,14 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Helm
-        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
+        uses: azure/setup-helm@dda3372f752e03dde6b3237bc9431cdc2f7a02a2 # v5.0.0
+        with:
+          version: ${{ matrix.helm-version }}
 
       - name: Helm verify examples
         working-directory: examples/common/${{ matrix.example }}
         run: |
-          helm template --dependency-update . -f env/values-kub-ent-${{ matrix.env }}.yaml
+          mkdir -p charts
+          cp -r ../../../charts/common charts/common
+          helm lint . -f env/values-kub-ent-${{ matrix.env }}.yaml
+          helm template . -f env/values-kub-ent-${{ matrix.env }}.yaml

.gitignore

@@ -0,0 +1 @@
+.tool-versions

AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md — Entur Helm Charts
+
+## Project Overview
+
+This repository contains Entur's opinionated Helm charts for deploying applications to Kubernetes. The primary chart is `common` (in `charts/common/`), which provides a convention-over-configuration approach for Spring Boot apps and general workloads. Example charts in `examples/common/` demonstrate usage patterns.
+
+Compatible with Helm 3 and Helm 4.
+
+## Repository Structure
+
+```
+charts/common/           # The main Helm chart (source of truth)
+  templates/             # Kubernetes resource templates
+  tests/                 # helm-unittest test suites
+  tests/values/          # Shared test values
+  values.yaml            # Default values (heavily documented)
+  values.schema.json     # JSON Schema for values validation
+examples/common/         # 7 example charts showing usage patterns
+fixture/helm/            # Fixture values for template rendering validation
+.github/workflows/       # CI/CD (PR checks, release, docs generation)
+```
+
+## Tools
+
+- **`helm`** — render templates, manage dependencies, package charts
+- **`helm unittest`** — run YAML-based unit tests (plugin: helm-unittest)
+- **`helm template`** — render and inspect template output with fixture values
+- **`helm lint`** — validate chart structure and values against JSON Schema
+- **`helm-docs`** — auto-generate README.md from values.yaml comments and Chart.yaml description
+- **`gh`** — GitHub CLI for issues, PRs, releases, and CI status
+
+## Development Commands
+
+```bash
+# Run unit tests (primary validation step — always run after any template/values change)
+helm unittest ./charts/common
+
+# Run a single test file
+helm unittest ./charts/common -f tests/pdb_test.yaml
+
+# Lint chart with schema validation
+helm lint charts/common -f fixture/helm/values-minimal.yaml
+
+# Render templates with fixture values to verify output
+helm template charts/common -f fixture/helm/values-minimal.yaml
+helm template charts/common -f fixture/helm/values-cron.yaml
+helm template charts/common -f fixture/helm/values-secrets.yaml
+helm template charts/common -f fixture/helm/values-postgres.yaml
+
+# Render a single template
+helm template test charts/common -f fixture/helm/values-minimal.yaml --show-only templates/pdb.yaml
+
+# Render with value overrides (useful for testing specific scenarios)
+helm template test charts/common -f fixture/helm/values-minimal.yaml --set env=prd --set deployment.minReplicas=3
+
+# Regenerate chart documentation (README.md files) — run after changing values.yaml or Chart.yaml
+helm-docs
+
+# Update dependencies for example charts after version bump
+helm dependency update examples/common/<example-name>
+
+# View GitHub issues
+gh issue view <number> --repo entur/helm-charts
+gh issue view <number> --repo entur/helm-charts --comments
+```
+
+## Testing
+
+- **Framework**: [helm-unittest](https://github.com/helm-unittest/helm-unittest) — YAML-based declarative assertions
+- **Test location**: `charts/common/tests/*_test.yaml`
+- **Shared test values**: `charts/common/tests/values/common-test-values.yaml`
+- **Snapshots**: `charts/common/tests/__snapshot__/`
+- **Always run `helm unittest ./charts/common` after modifying any template or values**
+- Tests cover: deployment, service, ingress, HPA, PDB, VPA, configmap, secrets, cron, and v1 backward compatibility
+
+## Key Conventions
+
+### Commit Messages
+Uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+- `feat!:` — breaking change (major version bump)
+- `feat:` — new feature (minor version bump)
+- `fix:` — bug fix (patch version bump)
+- `docs:` / `ci:` / `chore:` — no version bump
+
+### Chart Design Principles
+- HPA is always enabled with `minReplicas: 2` by default (use `forceReplicas` to opt out)
+- Memory limit always equals memory request
+- Security: non-root, no privilege escalation, drop all capabilities, seccompProfile RuntimeDefault
+- Traffic types must be explicit: `api`, `public`, or `http2`
+- Template helpers are in `charts/common/templates/_helpers.tpl`
+- Deprecated values use `fail` to give clear migration messages
+- Scaling fields (minReplicas, maxReplicas, forceReplicas, minAvailable) belong under `deployment.*` only — not `container.*`
+- Container-specific fields (cpu, memory, image, probes, env, ports, lifecycle) belong under `container.*`
+
+### Values Patterns
+- Required fields: `app`, `appId`, `team`, `env`, `container.image`
+- Environment values: `sbx`, `dev`, `tst`, `prd`
+- Single container: use `container:` key
+- Multiple containers: use `containers:` list
+- Environment-specific overrides go in `env/values-kub-ent-{dev,tst,prd}.yaml`
+- Postgres/Cloud SQL: use `postgres.instances` with Secret Manager keys via External Secrets
+- gRPC: set `grpc: true` — native K8s gRPC probes are used automatically with `service.internalPort`
+- Custom HPA metrics: use `hpa.metrics` list to add Pods/External/Object metrics alongside default CPU
+
+### Documentation
+- `README.md` files in `charts/` and `examples/` are **auto-generated** by `helm-docs` — never edit them manually
+- To update documentation: edit `values.yaml` comments (use `# --` prefix for helm-docs) or `Chart.yaml` description, then run `helm-docs`
+- After any change to `values.yaml`, `Chart.yaml`, or `values.schema.json`: run `helm-docs` to regenerate README.md files
+- `values.schema.json` must be updated manually when adding/removing/renaming values fields
+
+## CI/CD
+
+- **PR checks**: lint, unit tests (Helm 3 + 4), kind cluster install tests (Helm 3 + 4), example validation (Helm 3 + 4)
+- **Release**: automated via release-please with semantic versioning; tags like `common-v2.0.0`
+- **Docs**: auto-generated on release branches via helm-docs workflow
+- **Ownership**: `@entur/team-plattform` (see CODEOWNERS)
+
+## Important Notes
+
+- `README.md` files in charts are **auto-generated** by helm-docs — do not edit them manually; edit `values.yaml` comments or `Chart.yaml` description instead
+- Example charts pin their dependency on `common` — update both `Chart.yaml` version and run `helm dependency update` when changing
+- The chart supports both Deployment and CronJob workloads (mutually exclusive via `deployment.enabled` / `cron.enabled`)
+- Fixture values in `fixture/helm/` are used for CI template rendering validation
+- `shortname` is removed — use `appId` (matches GoogleCloudApplication `metadata.id`)
+- `postgres.connectionConfig` is removed — use `postgres.instances` with Secret Manager keys
+- `deployment.replicas` is removed — use `deployment.minReplicas` (HPA controls pod count)
+- `container.memoryLimit` is removed — memory limit always equals memory request
+- `pdb.minAvailable` is removed — use `deployment.minAvailable`

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -10,6 +10,43 @@ Browse our [examples/common](./examples/common) folder for quick examples to get
 
 Full documentation on each chart you can find in the [charts/](./charts/) folders.
 
+## IDE Support
+
+The chart includes a [JSON Schema](./charts/common/values.schema.json) for `values.yaml` validation. This gives you autocompletion, inline documentation, and error highlighting in your IDE.
+
+### VS Code
+
+Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and add this to your `values.yaml`:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/entur/helm-charts/main/charts/common/values.schema.json
+common:
+  app: my-app
+  ...
+```
+
+Or configure it in `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/entur/helm-charts/main/charts/common/values.schema.json": ["values*.yaml", "env/values*.yaml"]
+  }
+}
+```
+
+### JetBrains (IntelliJ / GoLand)
+
+Go to **Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings**, add a new mapping:
+- **Schema URL**: `https://raw.githubusercontent.com/entur/helm-charts/main/charts/common/values.schema.json`
+- **File path pattern**: `values*.yaml`
+
+Note: Since the chart is used as a dependency, your values are nested under `common:`. The schema validates the properties under that key.
+
+## Upgrading
+
+See [UPGRADE.md](UPGRADE.md) for migration guides between major versions.
+
 ## Contributing
 
 For guidance on how to contribute, see our [contribution documentation](CONTRIBUTING.md).