177 lines
6.5 KiB
Markdown
177 lines
6.5 KiB
Markdown
# 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](blue-green-chart-migration.md).
|
|
- Editing chart templates → use [fork-upstream-chart.md](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
|
|
|
|
```bash
|
|
# 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](blue-green-chart-migration.md)).
|
|
|
|
### 2. Update `Chart.yaml`
|
|
|
|
```bash
|
|
$EDITOR helm-templates/<chart>/Chart.yaml
|
|
```
|
|
|
|
Find the `dependencies[]` entry and bump `version:`. Example:
|
|
|
|
```diff
|
|
dependencies:
|
|
- name: argo-cd
|
|
- version: 7.7.23
|
|
+ version: 7.8.0
|
|
repository: https://argoproj.github.io/argo-helm
|
|
```
|
|
|
|
### 3. Refresh `Chart.lock`
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](../../../wiki/analyses/ADR-A5-manual-sync-default-for-infra.md).
|
|
- 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](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](blue-green-chart-migration.md) — for major-version bumps.
|
|
- Procedure: [fork-upstream-chart.md](fork-upstream-chart.md) — when the bump requires template edits.
|
|
- Skill: [skills/infra/bump-chart-version.md](../../../skills/infra/bump-chart-version.md).
|
|
- ADR: [ADR-A1-cache-vs-upstream-charts.md](../../../wiki/analyses/ADR-A1-cache-vs-upstream-charts.md).
|