devops-infra-helm-charts-gcp/docs/platform/procedures/update-chart-version.md

Procedure — Update a chart's pinned dependency version

Layer: Layer 1 — HIGH RISK (charts in helm-templates/ are consumed by every cluster that runs them). Blast radius: every cluster that has an Argo Application referencing this chart will pick up the new version on next sync. Approval: platform team. CMR mandatory for prod-fleet charts.

In this repo, charts in helm-templates/<chart>/ are typically thin wrappers — Chart.yaml declares an upstream chart as a dependency, and Chart.lock pins the resolved subchart. "Bumping the chart version" means:

1. Update dependencies[].version in Chart.yaml.
2. Run helm dependency update to refresh Chart.lock (and re-pull the subchart).
3. Test render with representative cluster overrides.

---

When to use this procedure

• Upgrading a wrapper chart's pinned subchart version (e.g. argo-cd 7.7.23 → 7.8.0).
• Following a security advisory in an upstream chart.

This is not the right procedure for:

• A blue-green migration to a new major version → use blue-green-chart-migration.md.
• Editing chart templates → use fork-upstream-chart.md.
• Changing values without a chart bump → that's per-cluster custom-values.yaml work, not this.

---

Pre-conditions

• The new upstream version exists and has a published changelog.
• You have read the changelog for breaking template / values changes.
• The bump is the explicit headline of the PR (not a side-effect of another change).
• CMR open if this is a prod-fleet chart (Argo CD, Contour, VictoriaMetrics, ingress, cert-manager).

---

Steps

1. Read the changelog

# For most upstream charts:
helm repo update
helm search repo <repo>/<chart> --versions | head -20
# Read the chart's CHANGELOG.md or release notes on GitHub.

Look specifically for:

• Removed values keys — would silently no-op overrides.
• Renamed values keys — same.
• CRD changes — might require manual kubectl apply of new CRDs.
• Breaking template changes (e.g. label selector immutability on Deployments).
• Required Kubernetes version bumps.

If any of these apply, this is not a simple version bump — escalate to a blue-green migration (blue-green-chart-migration.md).

2. Update Chart.yaml

$EDITOR helm-templates/<chart>/Chart.yaml

Find the dependencies[] entry and bump version:. Example:

 dependencies:
   - name: argo-cd
-    version: 7.7.23
+    version: 7.8.0
     repository: https://argoproj.github.io/argo-helm

3. Refresh Chart.lock

helm dependency update helm-templates/<chart>

This:

• Verifies the new version resolves.
• Updates Chart.lock with the new digest.
• Re-pulls the subchart .tgz into helm-templates/<chart>/charts/.

The lockfile must be committed alongside Chart.yaml. A bump without a refreshed lockfile is incomplete.

4. Render against a representative cluster's overrides

Pick a cluster that runs this chart with a non-trivial override set:

sibling=$(find helm-overrides -maxdepth 2 -type d -name '<chart>' \
            | grep -v '^helm-overrides/db-' | head -1)
helm template <chart> helm-templates/<chart> -f "$sibling/custom-values.yaml" | head -120

If the render errors → the chart bump introduced a values incompatibility. Stop. Either:

• Find the new values shape and update affected custom-values.yaml files in this PR, OR
• Defer the bump until those updates are scoped.

5. Spot-check helm diff against a live cluster (recommended)

helm diff upgrade <release> helm-templates/<chart> \
  -f helm-overrides/<cluster>/<app>/custom-values.yaml \
  --kube-context=<cluster-context>

What you want to see:

• Image tag bumps.
• Label updates (often helm.sh/chart).
• Possibly new CRDs or RBAC.

What's a red flag:

• Deployment selector changes (immutable; will fail to apply).
• StatefulSet volumeClaimTemplates changes.
• Resource removals you didn't expect.

6. Commit and open the PR

git checkout -b chart-bump/<chart>-<new-version>
git add helm-templates/<chart>/Chart.yaml helm-templates/<chart>/Chart.lock
git add helm-templates/<chart>/charts/   # if the .tgz was re-pulled
git commit
git push origin chart-bump/<chart>-<new-version>
gh pr create --base main --title "chart bump: <chart> <old> → <new>"

PR description:

• Procedure followed: this file.
• Old → new with a link to the upstream changelog.
• The list of clusters that consume this chart (grep -rl '<chart>' helm-overrides | head).
• The render(s) and diff(s) you ran.
• Whether any breaking-change fallout is bundled (preferably not — if so, scope to a separate PR).

7. After merge — Argo CD picks up the new chart on next sync

For each cluster running this chart:

• The cluster's Argo CD detects the chart hash change.
• The Application becomes OutOfSync.
• A human clicks Sync per ADR-A5.
• Watch rollout per cluster — don't sync 20 clusters simultaneously.

---

Anti-patterns

1. Bumping Chart.yaml without refreshing Chart.lock. Argo CD uses the lockfile; the bump silently no-ops.
2. Bundling a chart bump with values changes. Two separate PRs — one for the bump, one for any values that need to change because of the bump.
3. Bumping a major version (e.g. 7.x → 8.x) in place. Use blue-green-chart-migration.md — give yourself a sibling chart and migrate cluster-by-cluster.
4. Syncing every cluster simultaneously after merge. Stagger; one cluster at a time, with a soak between.
5. Skipping the changelog read. Surprises you'll regret.

---

Rollback

Open a follow-up PR that reverts Chart.yaml and Chart.lock to the previous versions. After merge, each cluster's Argo CD shows OutOfSync against the old chart; click Sync to roll back per cluster.

If the chart bump landed CRDs that are now incompatible with the old version, the rollback may require manual CRD cleanup — coordinate with the platform team.

---

Related

• Procedure: blue-green-chart-migration.md — for major-version bumps.
• Procedure: fork-upstream-chart.md — when the bump requires template edits.
• Skill: skills/infra/bump-chart-version.md.
• ADR: ADR-A1-cache-vs-upstream-charts.md.