feat!: common chart v2.0.0

.claude/skills/upgrade-common-chart/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: upgrade-common-chart
+description: >
+  Upgrade Entur common Helm chart dependency from v1 to v2. Use this skill when
+  the user wants to migrate their Helm values files to the v2 common chart, asks
+  about upgrading to common chart v2, mentions "common chart upgrade", or has
+  schema validation errors after bumping the common chart version. Also trigger
+  when the user mentions deprecated fields like shortname, container.replicas,
+  connectionConfig, memoryLimit, or postgres.instances with raw string values.
+---
+
+# Upgrade Entur Common Helm Chart (v1 to v2)
+
+You are upgrading a Helm chart that depends on `entur/common` from v1 to v2. This is a breaking change that requires migrating values files and updating the chart dependency.
+
+## Step 1: Understand the project
+
+Find all relevant files:
+1. `Chart.yaml` — contains the `common` dependency version to update
+2. All `values*.yaml` files — contain the values to migrate (check `env/` subdirectories too)
+3. Any `values-kub-ent-*.yaml` files — environment-specific overrides
+
+Read each file before making changes. The common chart is typically referenced as a dependency under the `common:` key in values files.
+
+## Step 2: Update Chart.yaml
+
+Bump the common chart dependency version to `2.0.0`:
+
+```yaml
+dependencies:
+  - name: common
+    version: 2.0.0
+    repository: "https://entur.github.io/helm-charts"
+```
+
+## Step 3: Apply migrations to every values file
+
+Work through each migration in order. Skip any that don't apply to the file.
+
+### 3.1 Rename `shortname` to `appId`
+
+```yaml
+# Before
+common:
+  shortname: myapp
+
+# After
+common:
+  appId: myapp
+```
+
+### 3.2 Move scaling fields from `container.*` to `deployment.*`
+
+| Removed (v1) | Replacement (v2) |
+|---|---|
+| `container.replicas` | `deployment.minReplicas` |
+| `deployment.replicas` | `deployment.minReplicas` |
+| `container.maxReplicas` | `deployment.maxReplicas` |
+| `container.forceReplicas` | `deployment.forceReplicas` |
+| `container.minAvailable` | `deployment.minAvailable` |
+| `container.terminationGracePeriodSeconds` | `deployment.terminationGracePeriodSeconds` |
+
+HPA is now always enabled (unless `forceReplicas` is set). The Deployment never emits a `replicas` field — HPA controls pod count. To pin replicas, use `deployment.forceReplicas`.
+
+### 3.3 Remove `container.memoryLimit` and `postgres.memoryLimit`
+
+Memory limit now always equals memory request. Remove `memoryLimit` and set `memory` to the value you need for both.
+
+### 3.4 Migrate postgres configuration
+
+This is the most significant change. The postgres integration now uses `secretKeyPrefix` as the contract with the `entur/terraform-google-sql-db` Terraform module.
+
+**Remove deprecated fields:** `postgres.connectionConfig`, `postgres.memoryLimit`, `postgres.termTimeout`
+
+**Migrate `postgres.instances`:** Items changed from raw Secret Manager key names (strings) to objects with `secretKeyPrefix`. When `enabled: true` with no `instances`, the chart defaults to `[{secretKeyPrefix: PG}]`.
+
+```yaml
+# v1
+common:
+  postgres:
+    enabled: true
+    connectionConfig: my-app-psql-connection
+
+# v2 (simplest — default PG prefix)
+common:
+  postgres:
+    enabled: true
+
+# v2 (explicit prefix)
+common:
+  postgres:
+    enabled: true
+    instances:
+      - secretKeyPrefix: PG
+
+# v2 (multiple instances)
+common:
+  postgres:
+    enabled: true
+    instances:
+      - secretKeyPrefix: PG
+      - secretKeyPrefix: ANALYTICS_PG
+```
+
+If `postgres.termTimeout` was set, rename it to `postgres.maxSigtermDelay` (maps to the Cloud SQL Proxy v2 `--max-sigterm-delay` flag).
+
+### 3.5 Remove `configmap.toEnv`
+
+The configmap is automatically mounted via `envFrom` when `configmap.enabled: true`.
+
+```yaml
+# v1
+common:
+  configmap:
+    enabled: true
+    toEnv: true
+
+# v2
+common:
+  configmap:
+    enabled: true
+```
+
+### 3.6 Update ingress if using `ingress.class`
+
+The `kubernetes.io/ingress.class` annotation is removed. Ingress now uses `spec.ingressClassName` (defaults to `traefik`). If you had a custom `ingress.class` annotation, use `ingress.ingressClassName` instead.
+
+### 3.7 Update gRPC probe configuration
+
+If using gRPC, explicit `probes.*.grpc.port` settings are no longer needed — they default to `service.internalPort`. Remove them unless you need a non-default port.
+
+## Step 4: Verify
+
+Run these commands and fix any issues:
+
+```bash
+helm dependency update
+helm lint . -f env/values-kub-ent-dev.yaml
+helm template . -f env/values-kub-ent-dev.yaml
+```
+
+If lint reports unknown properties, you likely missed a renamed or removed field. Check the migration steps above.
+
+## Step 5: Summary
+
+After completing all changes, provide the user with a summary of what was changed, organized by file. Mention any fields that were removed or renamed.

.github/workflows/helm-docs.yml

@@ -2,54 +2,48 @@ name: helm-docs-and-examples-update
 
 on:
   pull_request:
-    branches:
-      - "release-please--branches--**"
+    branches: [main]
   workflow_dispatch:
 
+concurrency:
+  group: helm-docs-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
 jobs:
   helm-doc-example-update:
     name: Update helm chart versions in examples and docs
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please--branches--')
     runs-on: ubuntu-24.04
     permissions:
       contents: write
     steps:
       - name: Checkout source code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          ref: ${{ github.ref }}
+          ref: ${{ github.head_ref }}
           fetch-depth: 0
-      - name: Add helm-docs common changes to release branch
-        env:
-          RELEASE_BRANCH: ${{ github.ref_name }}
+      - name: Update examples and regenerate docs
         run: |
           CUR_CHART="common" # TODO get from release-please manifest output
-
-          printf "Updating Helm chart %s documentation for version %s\n" $CUR_CHART $VERSION
           git config --global user.email "actions@github.com"
           git config --global user.name "GitHub Actions"
-          git switch $RELEASE_BRANCH
 
-          # get version from release-please-manifest.json
-          export VERSION=$(jq -r '.["charts/'"$CUR_CHART"'"]' .github/release-please-manifest.json)
-          printf "Version: %s\n" $VERSION
+          export VERSION=$(jq -r --arg c "$CUR_CHART" '.["charts/" + $c]' .github/release-please-manifest.json)
+          printf "Updating Helm chart %s documentation for version %s\n" "$CUR_CHART" "$VERSION"
 
-          # Update the version in examples directory
-          all_charts=$(find ./examples/$CUR_CHART -name Chart.yaml)
+          all_charts=$(find "./examples/$CUR_CHART" -name Chart.yaml)
           for chart in $all_charts; do
-            yq -e -i '(.dependencies[] | select(.name == "'$CUR_CHART'") | .version) = env(VERSION)' "${chart}"
+            CUR_CHART="$CUR_CHART" yq -e -i '(.dependencies[] | select(.name == strenv(CUR_CHART)) | .version) = env(VERSION)' "${chart}"
           done
 
-          # Install and run helm-docs
           go install github.com/norwoodj/helm-docs/cmd/helm-docs@37d3055fece566105cf8cff7c17b7b2355a01677 # 1.14.2
-          export PATH=${PATH}:`go env GOPATH`/bin
+          export PATH=${PATH}:$(go env GOPATH)/bin
           helm-docs
 
-          if [ -n "$(git status --porcelain '*.md')" ]; then
-            git add \*README.md
-            git add \*Chart.yaml
+          if [ -n "$(git status --porcelain '*.md' '*Chart.yaml')" ]; then
+            git add \*README.md \*Chart.yaml
             git commit -m "docs: update Helm chart documentation"
             git push
           else
             echo "Helm versions are up to date"
-            exit 0
           fi

.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@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
@@ -67,8 +93,13 @@ jobs:
 
       - name: Set up Helm
         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