158 lines
5.6 KiB
Markdown
158 lines
5.6 KiB
Markdown
# Skill — `bump-chart-version`
|
|
|
|
> **Layer:** Layer 1 — agent generates diff and opens PR; platform team reviews; per-cluster Sync is the deploy.
|
|
> **Scope:** updating `helm-templates/<chart>/Chart.yaml` `dependencies[].version` and refreshing `Chart.lock`.
|
|
|
|
This skill is the agent-callable form of [docs/platform/procedures/update-chart-version.md](../../docs/platform/procedures/update-chart-version.md).
|
|
|
|
---
|
|
|
|
## When to use
|
|
|
|
Triggers like:
|
|
|
|
- "Bump `<chart>` from `<old>` to `<new>`."
|
|
- "Upgrade `argo-cd` to 7.8.0."
|
|
- "Apply CVE patch to `<chart>` — bump to <new>."
|
|
|
|
Do **not** use this skill for:
|
|
|
|
- Major-version bumps with breaking template changes (use `blue-green-chart-migration` procedure).
|
|
- Forking a chart (use `fork-upstream-chart` procedure).
|
|
- Bumping a chart's local version when it's already a fork (the `version:` field at the top of `Chart.yaml`, not `dependencies[].version`).
|
|
|
|
---
|
|
|
|
## Input
|
|
|
|
Required:
|
|
|
|
```yaml
|
|
chart: <chart-name> # must exist in helm-templates/
|
|
old_version: <semver> # current dependencies[].version
|
|
new_version: <semver> # target
|
|
```
|
|
|
|
Optional:
|
|
|
|
```yaml
|
|
representative_cluster: <cluster-folder> # for the test render; if omitted, skill picks one
|
|
sample_helm_diff: <bool> # if true, run helm diff against a live cluster (requires kube context)
|
|
```
|
|
|
|
---
|
|
|
|
## Steps (deterministic)
|
|
|
|
1. **Pre-conditions.**
|
|
```bash
|
|
ls helm-templates/<chart>/Chart.yaml
|
|
yq e '.dependencies[0].version' helm-templates/<chart>/Chart.yaml # confirm == <old_version>
|
|
```
|
|
|
|
2. **Read the changelog.** Output a one-line note with the changelog URL or an explicit "READ THE CHANGELOG: <url>" message. The skill does not auto-fetch; the user must confirm they've read it. If the user hasn't, **stop**.
|
|
|
|
3. **Update `Chart.yaml`.**
|
|
```bash
|
|
sed -i.bak "s/^ version: <old_version>$/ version: <new_version>/" \
|
|
helm-templates/<chart>/Chart.yaml
|
|
rm helm-templates/<chart>/Chart.yaml.bak
|
|
```
|
|
(Or use `yq` with a path expression — depending on `dependencies[]` shape.)
|
|
|
|
4. **Refresh `Chart.lock`.**
|
|
```bash
|
|
helm dependency update helm-templates/<chart>
|
|
```
|
|
On failure: surface the error and stop. Common causes: new version doesn't exist, repo URL changed, network issue.
|
|
|
|
5. **Render against the representative cluster.**
|
|
```bash
|
|
sibling=${representative_cluster:-$(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" > /tmp/render.yaml
|
|
```
|
|
On failure: surface the error and **roll back** (`git checkout helm-templates/<chart>/Chart.yaml helm-templates/<chart>/Chart.lock`); stop and report. The bump is incompatible with current values.
|
|
|
|
6. **(If `sample_helm_diff: true`)**
|
|
```bash
|
|
helm diff upgrade <release> helm-templates/<chart> \
|
|
-f helm-overrides/<sibling>/<chart>/custom-values.yaml \
|
|
--kube-context=<context>
|
|
```
|
|
Capture the diff and put it in the PR body.
|
|
|
|
7. **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 subchart .tgz refreshed
|
|
git commit -m "chart bump: <chart> <old_version> -> <new_version>"
|
|
git push origin chart-bump/<chart>-<new_version>
|
|
gh pr create --base main --title "chart bump: <chart> <old_version> -> <new_version>"
|
|
```
|
|
|
|
PR body (heredoc):
|
|
|
|
```markdown
|
|
## Summary
|
|
Bumps `<chart>` from `<old_version>` to `<new_version>`.
|
|
|
|
- Upstream changelog: <url>
|
|
- Procedure: `docs/platform/procedures/update-chart-version.md`
|
|
- Skill: `skills/infra/bump-chart-version.md`
|
|
|
|
## Affected clusters
|
|
<list from `grep -rl '<chart>' helm-overrides | sort -u`>
|
|
|
|
## Validation
|
|
- `helm dependency update` succeeded
|
|
- Render against `<representative_cluster>`'s overrides: clean
|
|
- (if sample_helm_diff) diff against live: <one-line summary>
|
|
|
|
## Approver
|
|
Platform team
|
|
|
|
## CMR
|
|
<ticket if applicable>
|
|
```
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
A PR diff with:
|
|
|
|
- `helm-templates/<chart>/Chart.yaml` updated (version line)
|
|
- `helm-templates/<chart>/Chart.lock` refreshed
|
|
- `helm-templates/<chart>/charts/*.tgz` (if the subchart was re-pulled)
|
|
|
|
The skill does **not**:
|
|
|
|
- Sync any cluster (manual per-cluster Sync after merge).
|
|
- Update any `helm-overrides/<cluster>/<app>/custom-values.yaml` to handle a values-shape change. If the bump requires that, **stop and surface a follow-up task** — don't bundle.
|
|
- Open per-cluster Sync recommendations as separate work items.
|
|
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
1. **`Chart.yaml` without `Chart.lock` is a no-op.** Argo CD reads the lockfile.
|
|
2. **The skill must roll back on render failure.** Otherwise a half-committed bump leaves the repo in a broken state.
|
|
3. **For wrapper charts whose `dependencies[]` has multiple entries**, the skill must operate on the right one. Don't bump the wrong dep.
|
|
4. **Major-version bumps are not this skill's job.** If `new_version` is a major increment (`7.x → 8.x`), refuse and recommend [blue-green-chart-migration](../../docs/platform/procedures/blue-green-chart-migration.md).
|
|
|
|
---
|
|
|
|
## Layer constraint
|
|
|
|
Layer 1. Open the PR; do not merge it; do not click Sync on any cluster.
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- Procedure: [update-chart-version.md](../../docs/platform/procedures/update-chart-version.md).
|
|
- Procedure: [blue-green-chart-migration.md](../../docs/platform/procedures/blue-green-chart-migration.md).
|
|
- ADR: [ADR-A1-cache-vs-upstream-charts.md](../../wiki/analyses/ADR-A1-cache-vs-upstream-charts.md).
|