Terraform Core Version Upgrade Prompt
Plan a safe upgrade of the Terraform CLI/core version across many stacks — required_version constraints, deprecation handling, state compatibility, and a staged rollout that won't strand teams.
- Target user
- Platform teams upgrading the Terraform binary across an organization
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a platform engineer responsible for keeping the Terraform core version current across dozens of repos without breaking running pipelines. Plan the upgrade. I will provide: - Current and target Terraform core versions - How the binary is pinned (tfenv, CI image, asdf, Devbox) - Stack inventory and which are most critical - Known use of features deprecated or changed between versions Your job: 1. **Changelog triage** — walk the CHANGELOG between my current and target versions and extract only the breaking changes, deprecations, and state-format changes that affect my stacks. Ignore unrelated noise. 2. **required_version strategy** — recommend a constraint syntax (`~> 1.x` vs pessimistic pinning) and explain how upgrading state with a newer core makes it unreadable by older cores. Warn about the one-way state-version bump. 3. **Provider interplay** — check whether the target core forces provider minimums, and sequence core vs provider upgrades to avoid a double-break. 4. **Pinning rollout** — update the version pin in one place (CI image / tfenv `.terraform-version`) and describe a canary approach: upgrade a low-risk stack first, run plan, confirm empty diff or only expected changes. 5. **Deprecation fixes** — for each deprecated construct in my code (e.g. interpolation-only expressions, removed functions), provide the modern replacement and a search pattern to find every occurrence. 6. **State safety** — pre-upgrade state backup, and a rollback story given that state may have been written by the new core. Be explicit that rollback often means restoring the backup, not just re-pinning. 7. **Validation gate** — a CI step asserting all stacks run `terraform validate` and `plan` cleanly on the new version before the org-wide pin flips. Output as: (a) the filtered breaking-change list with per-item impact, (b) an upgrade-order plan from canary to org-wide, (c) code-fix diffs for each deprecation, (d) the state backup/rollback runbook, (e) the CI validation gate. Bias toward: one canary stack first, explicit about the irreversible state bump, no big-bang flips.