added repo
This commit is contained in:
Your Name
@@ -0,0 +1,176 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user