# 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](../../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:
```text
values/<env>/incubator-infra-<cluster>-values.yaml
```

All prd clusters:
```bash
ls values/prd/
```

Halt if any values file doesn't exist.

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

```bash
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

```bash
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

```bash
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.