124 lines
3.9 KiB
Markdown
124 lines
3.9 KiB
Markdown
# Procedure: Upgrade a Chart Version
|
|
|
|
> Step-by-step guide for changing the `chartDir` of an `appSpec` entry to reference a new chart version.
|
|
>
|
|
> **Layer:** 1-T (Tool-Mediated). Agent generates the diff and opens a PR.
|
|
>
|
|
> **Blast radius:** Single cluster (if one values file) or fleet-wide (if multiple clusters). Auto-sync means changes deploy immediately after merge to the env branch (`main` for prd, `develop` for stg, `pre-prod` for int).
|
|
>
|
|
> Per AI Blitz Plan §5.2. Skill: [skills/infra/upgrade-chart-version.md](../../../skills/infra/upgrade-chart-version.md).
|
|
|
|
---
|
|
|
|
## When to use this procedure
|
|
|
|
- Upgrading a tool to a new version by switching `chartDir` (e.g., `contour` → `contour-v1.33.3`)
|
|
- Pinning a tool back to a previous chart directory
|
|
- Upgrading a tool across multiple clusters as part of a coordinated rollout
|
|
|
|
**Do not** use this procedure to change `teamSpec.source.targetRevision` — that's a HIGH RISK operation requiring explicit platform-team sign-off.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
1. The **new chart directory** exists in `devops-infra-helm-charts/helm-templates/<newChartDir>/`.
|
|
2. The **override values** for the new chart version are compatible — check `devops-infra-helm-charts/helm-overrides/<cluster>/<valuesDir>/custom-values.yaml` for any new required fields.
|
|
3. You know which clusters need upgrading.
|
|
|
|
---
|
|
|
|
## Single-cluster upgrade
|
|
|
|
### Step 1: Identify the target appSpec entry
|
|
|
|
Find the tool in the cluster's values file:
|
|
|
|
```bash
|
|
grep -A 4 'name: <tool>' values/<env>/incubator-infra-<cluster>-values.yaml
|
|
```
|
|
|
|
Note the current `chartDir`.
|
|
|
|
### Step 2: Verify the new chart directory exists
|
|
|
|
```bash
|
|
ls /path/to/devops-infra-helm-charts/helm-templates/<newChartDir>/
|
|
```
|
|
|
|
**Halt** if missing — the chart must be added to `devops-infra-helm-charts` first.
|
|
|
|
### Step 3: Check override compatibility
|
|
|
|
```bash
|
|
# Review the custom-values.yaml for any changed keys in the new chart
|
|
cat /path/to/devops-infra-helm-charts/helm-overrides/<cluster>/<valuesDir>/custom-values.yaml
|
|
```
|
|
|
|
If the new chart has breaking changes (renamed keys, removed defaults), the `custom-values.yaml` in `devops-infra-helm-charts` must be updated first — that is a separate PR in the sister repo.
|
|
|
|
### Step 4: Update the `chartDir`
|
|
|
|
Change the `chartDir` field in the values file:
|
|
|
|
```yaml
|
|
# Before:
|
|
- name: contour-internal-0
|
|
chartDir: contour
|
|
valuesDir: contour-internal
|
|
|
|
# After:
|
|
- name: contour-internal-0
|
|
chartDir: contour-v1.33.3
|
|
valuesDir: contour-internal
|
|
```
|
|
|
|
Do not change `name`, `namespace`, or `valuesDir` unless the upgrade specifically requires it.
|
|
|
|
### Step 5: Validate
|
|
|
|
```bash
|
|
helm template generic-argo-apps-chart/ \
|
|
-f values/<env>/incubator-infra-<cluster>-values.yaml \
|
|
| grep -B 2 -A 30 "name: <tool>"
|
|
|
|
yamllint values/<env>/incubator-infra-<cluster>-values.yaml
|
|
```
|
|
|
|
Verify the rendered Application points to the new chart path.
|
|
|
|
### Step 6: Open PR
|
|
|
|
- Title: `upgrade <tool> to <newChartDir> on <cluster>`
|
|
- Required: Platform team review
|
|
- Pre-commit hooks must pass
|
|
|
|
---
|
|
|
|
## Multi-cluster upgrade
|
|
|
|
When upgrading the same tool across multiple clusters:
|
|
|
|
1. Update `chartDir` in **all affected values files in the same PR**.
|
|
2. Validate each cluster's values file independently with `helm template`.
|
|
3. Title: `upgrade <tool> to <newChartDir> across [list of clusters or "all prd clusters"]`
|
|
|
|
**Ordering note:** ArgoCD auto-syncs all clusters on merge. There is no cluster-by-cluster rollout order. If you need a staged rollout (one cluster at a time), open separate PRs.
|
|
|
|
---
|
|
|
|
## Rollback
|
|
|
|
If the upgrade causes issues, create a revert PR changing `chartDir` back to the previous value. Do not force-push.
|
|
|
|
---
|
|
|
|
## Checklist
|
|
|
|
- [ ] New `chartDir` exists in `devops-infra-helm-charts/helm-templates/`
|
|
- [ ] `custom-values.yaml` is compatible with the new chart version
|
|
- [ ] `helm template` renders without errors for each updated cluster
|
|
- [ ] `yamllint` passes
|
|
- [ ] Pre-commit hooks pass
|
|
- [ ] For multi-cluster: all clusters validated before PR opens
|