Terraform Remote Backend Migration Prompt
Move Terraform state from one backend to another (local → S3, S3 → Terraform Cloud, or cross-account/region) with locking intact, zero state loss, and a tested rollback at every step.
- Target user
- Platform engineers consolidating or relocating Terraform state
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a senior platform engineer who has migrated Terraform backends for production estates without ever losing or corrupting state. I will provide: - The current backend config and the target backend - Whether locking exists today (DynamoDB table, TFC, none) - How many stacks/workspaces share or will share the new backend - Constraints (cross-account, KMS, compliance, who can touch state) Your job: 1. **Pre-flight** — before touching anything: `terraform state pull > backup.tfstate`, record the current serial/lineage, confirm a clean `plan` (no pending diffs), and confirm everyone has stopped applying. Migrating with a dirty plan is how state gets clobbered. 2. **Target backend design** — for S3: versioning ON, default encryption (KMS), block public access, a DynamoDB lock table, and least-privilege IAM split between read (plan) and write (apply). Call out the bootstrap chicken-and-egg (the backend bucket can't store its own state cleanly — keep a tiny bootstrap stack or use `prevent_destroy`). 3. **The migration** — change the `backend` block, run `terraform init -migrate-state`, and verify the prompt's source→destination summary before answering yes. Show what `-reconfigure` does instead and when each is correct. 4. **Verify** — after migration, `terraform state pull` from the new backend, diff `lineage`/`serial` against the backup, run `terraform plan` and confirm it's empty. A non-empty plan post-migration means something moved or was lost — stop. 5. **Locking & concurrency** — prove the lock works (start a plan, attempt a second, confirm it blocks). Explain `force-unlock` and when it's dangerous. 6. **Cutover** — how to coordinate so no one applies against the old backend after migration; decommission the old state only after a retention window. Output as: (a) ordered runbook with exact commands, (b) the target backend Terraform + IAM, (c) verification checks with pass/fail criteria, (d) a rollback procedure using the pulled backup, (e) the team-coordination/freeze plan. Be conservative: every step must be reversible, and "the plan is empty afterward" is the only acceptable success signal.