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.

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

The new chart directory exists in devops-infra-helm-charts/helm-templates/<newChartDir>/.
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.
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:

grep -A 4 'name: <tool>' values/<env>/incubator-infra-<cluster>-values.yaml

Note the current chartDir.

Step 2: Verify the new chart directory exists

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

# 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:

# 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

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:

Update chartDir in all affected values files in the same PR.
Validate each cluster's values file independently with helm template.
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

3.9 KiB Raw Blame History