# 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