# Terraform workflow: survive a provider major version upgrade

## When

A provider you depend on releases a new major (e.g. AWS provider 5.x to 6.x). The old major will eventually stop receiving updates; upgrading is a matter of scheduling, not if.

## Steps

1. Read the provider's upgrade guide end to end. Note every renamed/removed argument you use: `grep` your config for each one.
2. Update config for the breaking changes first, while still pinned to the old major. `terraform validate` should pass on the old version with the new-style config where the guide allows it.
3. Bump the version constraint to the new major. `terraform init -upgrade`. Read the lock file diff.
4. `terraform plan` in the lowest environment. Expect diffs from changed defaults; classify each as intended or suspicious.
5. Apply non-prod, bake, then promote. One environment at a time, with plan review at each step.

## Rules for agents

1. Never bump the major and "see what the plan says" without reading the guide. The plan shows diffs; the guide explains which diffs are dangerous.
2. Deprecated arguments removed in the major will fail `validate` immediately. Fix all of them before planning; a half-migrated config plans misleadingly.
3. Changed defaults are the silent killers: a default that flips from false to true will not error, it will just change your infrastructure. The upgrade guide lists them; check each against your config.
4. Keep the old-major pin in a branch until the upgrade is fully promoted. Rollback is "revert the bump", which only works if the revert is ready.