devops-infra-argo-config-gcp/skills/infra/upgrade-chart-version.md

Skill: Upgrade Chart Version

Parameterized agent task for changing the chartDir of an appSpec entry to reference a new chart version, across one or more clusters.

Layer: 1-T (Tool-Mediated). Agent generates the diff and opens a PR.

Procedure: docs/platform/procedures/upgrade-chart-version.md

---

When to use

Trigger on requests like:

• "Upgrade <tool> to <version> on <cluster>"
• "Bump <tool> chart to <newChartDir>"
• "Roll out <tool> chart upgrade across all prd clusters"
• "Pin <tool> back to <oldChartDir>"

---

Inputs

Parameter	Required	Example	Source
tool_name	yes	contour-internal-0	User request (name field in appSpec)
new_chart_dir	yes	contour-v1.33.3	User request or devops-infra-helm-charts PR
clusters	yes	k8s-central-prd-ase1 or all-prd	User request
env	yes	prd	Derived from cluster name

---

Steps (deterministic)

Step 0: Resolve target values files

Single cluster:

values/<env>/incubator-infra-<cluster>-values.yaml

All prd clusters:

ls values/prd/

Halt if any values file doesn't exist.

Step 1: Verify new chartDir exists in devops-infra-helm-charts

ls /path/to/devops-infra-helm-charts/helm-templates/<new_chart_dir>/

Halt if missing. The chart must be created in the sister repo first.

Step 2: Find the appSpec entry in each values file

grep -n -A 5 "^\s*- name: <tool_name>$" values/<env>/incubator-infra-<cluster>-values.yaml

Record the line number and current chartDir value.

Halt if the tool is not in the values file — it may not be deployed on this cluster.

Step 3: Update the chartDir

Change chartDir: <old> to chartDir: <new_chart_dir> in each target values file.

Do not change name, namespace, valuesDir, or nameOverride.

Step 4: Validate each modified file

helm template generic-argo-apps-chart/ \
  -f values/<env>/incubator-infra-<cluster>-values.yaml \
  | grep -B 2 -A 30 "name: <tool_name>"

yamllint values/<env>/incubator-infra-<cluster>-values.yaml

Every file must render cleanly before proceeding.

Step 5: Open PR

Title: upgrade <tool_name> chartDir to <new_chart_dir> [on <cluster> | across prd clusters]

PR body checklist:

• New chartDir exists in devops-infra-helm-charts/helm-templates/
• Previous chartDir: <old_chart_dir> (for easy rollback reference)
• helm template renders correctly for each cluster
• Pre-commit hooks pass
• custom-values.yaml compatibility confirmed

---

Output

One or more modified values/<env>/incubator-infra-<cluster>-values.yaml files with updated chartDir.

---

Gotchas

1. valuesDir compatibility: Some chart upgrades require changes to custom-values.yaml in devops-infra-helm-charts. If the new chart version has breaking value key changes, that must be a separate PR in the sister repo first.
2. Auto-sync on merge: All changed clusters deploy simultaneously on merge to the env branch (main for prd, develop for stg, pre-prod for int). For large fleet upgrades, consider staged rollout (separate PRs per cluster group).
3. name field ≠ chartDir: The name field is the appSpec identifier and is NOT changed during a chart upgrade. Only chartDir changes.
4. Rollback: Simply change chartDir back to the previous value in a new PR.