Terraform workflow: survive a provider major version upgrade

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.

Provider version constraints gate major upgrades; init -upgrade reinstalls; validate catches removed arguments statically. Verified against live docs 2026-09-26.