Chapter 37: Terraform Import Moved and Removed Blocks

37.2 moved block — rename without destroy

By Ravindra Bagale · Last updated: 25 October 2026

Story. A Netflix-style team renamed aws_instance.server to aws_instance.web for clarity, and the plan wanted to destroy one server and create another. The code changed, not the cloud. A moved block tells Terraform the old address and the new one are the same object. It works for renames, for moving a resource into a module, and for switching count to for_each.

moved {
  from = aws_instance.server
  to   = aws_instance.web
}

moved {
  from = aws_instance.web
  to   = module.web.aws_instance.this
}

moved {
  from = aws_s3_bucket.svc[0]
  to   = aws_s3_bucket.svc["auth"]
}

What each line does

• moved { — Declares a refactor that Terraform should apply to state.
• from = aws_instance.server — The old address still recorded in state.
• to = aws_instance.web — The new address in your code.
• to = module.web.aws_instance.this — Moves a root resource into a child module.
• from = aws_s3_bucket.svc[0] — A count-based address.
• to = aws_s3_bucket.svc["auth"] — The matching for_each key after switching to for_each.

When it is green.

  # aws_instance.server has moved to aws_instance.web
    resource "aws_instance" "web" { id = "i-0abc..." }

Plan: 0 to add, 0 to change, 0 to destroy.

When it is red.

Error: Moved object still exists
  on moved.tf line 1: moved {
This statement declares a move from aws_instance.server, but that resource is still declared in main.tf.

Fix. You renamed by copying. Delete the old resource block so only the new one remains. Keep moved blocks for a release or two so every environment picks them up.

What: every term in plain English

• address — The name of a resource inside Terraform, such as aws_instance.web or module.app.aws_instance.this.
• refactor — Changing how code is organised without changing what is built.
• moved block — Tells Terraform an object at the old address is now at the new address.
• from — The old address still in state.
• to — The new address in code.
• count index — A number key like [0]. It shifts when you remove an item from the middle.
• for_each key — A string key like ["auth"]. It stays stable when other items change.

Example 1: Rename a resource with no downtime

A Netflix-style team renamed aws_instance.server to aws_instance.web. Without a moved block, plan destroys the live server.

1. Apply a server named aws_instance.server.
2. Rename it to web in main.tf.
3. Run plan and see the destroy.
4. Add the moved block and plan again.

resource "aws_instance" "web" {
  ami           = "ami-0123456789abcdef0"
  instance_type = "t3.micro"
  tags = {
    Name = "web-1"
  }
}

moved {
  from = aws_instance.server
  to   = aws_instance.web
}

terraform plan
terraform apply
terraform state list

Output

  # aws_instance.server has moved to aws_instance.web
    resource "aws_instance" "web" {
        id = "i-0123456789abcdef0"
    }

Plan: 0 to add, 0 to change, 0 to destroy.
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
aws_instance.web

What it shows: Same server id, new name. No downtime and no new IP address.

Example 2: Move a resource into a module

A Flipkart-style team turned the web server into a reusable module. The address now has a module prefix.

1. Create modules/web/main.tf with resource aws_instance.this.
2. Call the module from root.
3. Add a moved block from the root address to the module address.

# modules/web/main.tf
variable "ami" { type = string }
resource "aws_instance" "this" {
  ami           = var.ami
  instance_type = "t3.micro"
}

# main.tf
module "web" {
  source = "./modules/web"
  ami    = "ami-0123456789abcdef0"
}

moved {
  from = aws_instance.web
  to   = module.web.aws_instance.this
}

terraform init
terraform plan

Output

  # aws_instance.web has moved to module.web.aws_instance.this

Plan: 0 to add, 0 to change, 0 to destroy.

What it shows: init is needed because a new module was added. The server itself is untouched.

Example 3: Switch count to for_each safely

With count, removing item 0 shifts every other item and Terraform recreates them. for_each keys stay stable. Moved blocks make the switch free.

1. Old code used count = 2 on aws_s3_bucket.svc.
2. New code uses for_each with keys auth and billing.
3. Add one moved block per item.

resource "aws_s3_bucket" "svc" {
  for_each = toset(["auth", "billing"])
  bucket   = "demo-${each.key}-1234"
}

moved {
  from = aws_s3_bucket.svc[0]
  to   = aws_s3_bucket.svc["auth"]
}

moved {
  from = aws_s3_bucket.svc[1]
  to   = aws_s3_bucket.svc["billing"]
}

terraform plan

Output

  # aws_s3_bucket.svc[0] has moved to aws_s3_bucket.svc["auth"]
  # aws_s3_bucket.svc[1] has moved to aws_s3_bucket.svc["billing"]

Plan: 0 to add, 0 to change, 0 to destroy.

What it shows: Make sure index 0 really was auth. Check with terraform state show before you write the blocks.

Example 4: Rename a whole module

Module web was renamed to frontend. Every resource inside moves at once with one block.

1. Rename module "web" to module "frontend".
2. Add one moved block for the module.
3. Plan.

module "frontend" {
  source = "./modules/web"
  ami    = "ami-0123456789abcdef0"
}

moved {
  from = module.web
  to   = module.frontend
}

terraform init
terraform plan

Output

  # module.web.aws_instance.this has moved to module.frontend.aws_instance.this

Plan: 0 to add, 0 to change, 0 to destroy.

What it shows: One block moved everything inside the module.

Command cheat sheet

Verify: did it work?

1. New address in state

   terraform state list
   

   Output

   aws_instance.web
   

2. Nothing destroyed

   terraform plan
   

   Output

   No changes. Your infrastructure matches the configuration.
   

When it is red 1

  # aws_instance.server will be destroyed
  # aws_instance.web will be created
Plan: 1 to add, 0 to change, 1 to destroy.

Cause. You renamed the resource but did not add a moved block.

Fix, step by step

1. Do not apply.
2. Add moved from the old to the new address.
3. Plan again and expect 0 to destroy.

When it is red 2

Error: Moved object still exists
This statement declares a move from aws_instance.server, but that resource is still declared in main.tf.

Cause. Both the old and the new resource blocks are in code.

Fix, step by step

1. Delete the old block.
2. Keep only the new one plus the moved block.

When it is red 3

Error: Ambiguous move statements
A statement at moved.tf:5 declared that aws_instance.web moved to module.web.aws_instance.this, but this statement instead declares that it moved to aws_instance.app.

Cause. Two moved blocks send the same address to two places.

Fix, step by step

1. Keep one destination.
2. Chain moves in order: A to B, then B to C.

Cleanup

terraform destroy

Practice tasks

Homework: try at home

Recap

• A rename without moved means destroy and create.
• moved changes state only, never AWS.
• It works for renames, modules and count to for_each.
• Check index mapping with state show before writing blocks.
• Keep moved blocks for a while so every environment catches up.

FAQ

When can I delete a moved block?

After every workspace and environment has applied it. Many teams keep them for one or two releases.

Does moved work across state files?

No. It works inside one state. For moving between states, use removed in one and import in the other.

Is moved better than terraform state mv?

Yes. It is code, it is reviewed, and it runs the same in every environment.

Can I move to a different resource type?

Only for a few types the provider supports. Usually no.

Which version do I need?

Terraform 1.1 or later.

Interview questions

1. You renamed a resource and plan wants to destroy it. What do you do?

   Add a moved block from the old address to the new one and plan again.

2. How do you move a resource into a module without downtime?

   A moved block with to = module.NAME.TYPE.NAME, then init and plan.

3. Why is count risky for lists?

   Removing a middle item shifts indexes and Terraform replaces the later items. for_each keys avoid this.

4. moved vs state mv?

   moved is declarative and reviewed in a pull request. state mv changes state at once on one machine.

5. How do you check the moved worked?

   plan shows has moved to and 0 to destroy; state list shows the new address.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards