Chapter 34: Terraform State Remote S3 Backend Locking and Workspaces

34.4 Move local state to S3 safely

By Ravindra Bagale · Last updated: 25 October 2026

Story. An Instagram-style feature team started a prototype with local state and then needed to share it. Copying the file into S3 by hand risks overwriting someone's newer copy. Terraform can migrate it for you: add the backend block and run init with -migrate-state. Terraform copies the state and checks that nothing is lost.

Steps

1. Save the current resource list.
2. Add backend.tf.
3. Run terraform init -migrate-state and answer yes.
4. Compare the lists.
5. Run terraform plan and expect No changes.
6. Delete the local terraform.tfstate files.

terraform state list > before.txt
terraform init -migrate-state
terraform state list > after.txt
diff before.txt after.txt
terraform plan

What each line does

• terraform state list > before.txt — Saves the list of tracked resources before the move.
• terraform init -migrate-state — Reads the new backend block and copies the local state into S3.
• terraform state list > after.txt — Lists resources again, now read from S3.
• diff before.txt after.txt — Shows nothing if the move kept every resource.
• terraform plan — Must show no changes, which proves state and AWS still agree.

When it is green.

Do you want to copy existing state to the new backend?
  Enter a value: yes
Successfully configured the backend "s3"!
No changes. Your infrastructure matches the configuration.

When it is red.

Error: Failed to get existing workspaces: S3 bucket "badge-tfstate-..." does not exist.

Fix. The bootstrap bucket was not created yet or is in another region. Apply the bootstrap project first and match the region in backend.tf.

What: every term in plain English

• migrate-state — The init flag that copies existing state from the old backend to the new one.
• state backup before migration — A dated copy of terraform.tfstate taken just before you change backends.
• reconfigure — The init flag that ignores the old backend without copying state. Wrong choice for a live project.
• backend change detection — Terraform notices backend.tf changed and refuses to plan until you run init.
• state mv — Moves one address inside state or into another state file.
• state push — Uploads a local file as the remote state. A last-resort tool.
• freeze window — A short time when nobody runs apply, so the move happens on a quiet state.

Example 1: Move a local project to S3 in five commands

A Freshworks-style team had one engineer applying from his laptop for months. The day he went on leave, they moved state to S3. This is the exact order.

1. Tell the team: no applies for 15 minutes.
2. Plan and confirm zero changes.
3. Copy the local state with the date.
4. Add backend.tf.
5. Run init -migrate-state and answer yes.

terraform plan | tail -1
cp terraform.tfstate state-backup-2026-10-25.tfstate
# add backend.tf now
terraform init -migrate-state

Output

No changes. Your infrastructure matches the configuration.
Initializing the backend...
Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "local" backend to the
  newly configured "s3" backend. No existing state was found in the newly
  configured "s3" backend. Do you want to copy this state to the new "s3"
  backend? Enter "yes" to copy and "no" to start with an empty state.

  Enter a value: yes

Successfully configured the backend "s3"!

What it shows: Starting from zero changes means any change you see later is caused by the move, not by old work.

Example 2: Prove the move worked

Never trust a migration without proof. Compare resource counts and plan again.

1. Count addresses from the backup.
2. Count addresses from remote state.
3. Plan.
4. Rename the local file so nobody uses it by mistake.

jq '.resources | length' state-backup-2026-10-25.tfstate
terraform state list | wc -l
terraform plan | tail -1
mv terraform.tfstate terraform.tfstate.migrated-do-not-use

Output

7
7
No changes. Your infrastructure matches the configuration.

What it shows: Same count, zero changes. Keep the backup in a private, encrypted place for a few weeks, then delete it.

Example 3: Move state between two keys in the same bucket

A Myntra project was renamed from shop-api to catalog-api. The key path had to change without touching AWS.

1. Change the key in backend.tf.
2. Run init -migrate-state.
3. Check both keys in S3.
4. Delete the old object after a week.

terraform {
  backend "s3" {
    bucket       = "badge-tfstate-123456789012"
    key          = "catalog-api/dev/terraform.tfstate"   # was shop-api/dev
    region       = "ap-south-1"
    encrypt      = true
    use_lockfile = true
  }
}

terraform init -migrate-state
aws s3 ls s3://badge-tfstate-123456789012/ --recursive | grep tfstate

Output

Successfully configured the backend "s3"!
2026-10-25 11:02:10       5120 catalog-api/dev/terraform.tfstate
2026-10-24 18:40:55       5120 shop-api/dev/terraform.tfstate

What it shows: The old object stays until you remove it. Leave it for a week as an extra safety copy.

Example 4: Move state back to local for a training lab

Sometimes you want to stop paying for a test project or hand it over. Removing the backend block and migrating brings state home.

1. Delete backend.tf.
2. Run init -migrate-state.
3. Check that terraform.tfstate exists locally.

rm backend.tf
terraform init -migrate-state
ls -l terraform.tfstate

Output

Do you want to copy existing state to the new backend?
  Enter a value: yes
Successfully unset the backend "s3". Terraform will now operate locally.
-rw-r--r-- 1 ravi ravi 5120 Oct 25 11:10 terraform.tfstate

What it shows: The same flag works in both directions. Use local state only for labs.

Command cheat sheet

Verify: did it work?

1. Counts match

   jq '.resources | length' state-backup-2026-10-25.tfstate; terraform state list | wc -l
   

   Output

   7
   7
   

2. Plan is clean

   terraform plan -detailed-exitcode; echo $?
   

   Output

   No changes. Your infrastructure matches the configuration.
   0
   

When it is red 1

Error: Backend initialization required, please run "terraform init"

Cause. You changed backend.tf and ran plan before init.

Fix, step by step

1. Run terraform init -migrate-state.
2. Answer yes to copy state.
3. Plan again.

When it is red 2

Plan: 7 to add, 0 to change, 0 to destroy.  (right after migration)

Cause. You ran init -reconfigure or answered no, so remote state is empty.

Fix, step by step

1. Do not apply.
2. Run terraform state push state-backup-2026-10-25.tfstate.
3. Plan and confirm zero changes.

When it is red 3

Error: Error acquiring the state lock (during migrate)

Cause. Someone else ran plan or apply during your freeze window.

Fix, step by step

1. Ask the team to stop.
2. Wait for their run to finish.
3. Run init -migrate-state again.

Cleanup

# after two to four weeks of clean plans
shred -u state-backup-2026-10-25.tfstate terraform.tfstate.migrated-do-not-use

Practice tasks

Homework: try at home

Recap

• Start from a zero-change plan.
• Take a dated backup of local state.
• Use init -migrate-state, never -reconfigure, on live projects.
• Prove with counts and a clean plan.
• Old copies stay for a while, then are deleted safely.

FAQ

What if I answered no by mistake?

Remote state is empty. Push your backup with terraform state push and plan again.

Does migration touch AWS resources?

No. Only the state file moves.

Can I migrate while Jenkins runs?

No. Pause the pipelines during the freeze window.

Can I move from one bucket to another?

Yes, change bucket in backend.tf and use -migrate-state.

Why rename the old local file?

So nobody runs Terraform against the outdated copy.

Interview questions

1. How do you move local state to S3?

   Clean plan, backup, add backend, init -migrate-state, then verify.

2. Difference between -migrate-state and -reconfigure?

   migrate-state copies state; reconfigure starts with whatever is in the new backend.

3. How do you prove a migration?

   Same resource count and a zero-change plan.

4. How do you recover if remote state is empty after a move?

   terraform state push with the backup file.

5. Why a freeze window?

   To avoid a lock clash or a half-moved state.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards