Avoid Resource Recreation: Refactor Terraform with the moved Block

---

Table of Contents:

1. Introduction

2. What is the moved Block?

3. Real-World Problem: Resource Rename

4. Solution: Add a moved Block

5. Moving Across Modules

6. Important Considerations

7. When to use the moved Block?

8. Why It Matters?

9. Final Thoughts

---

Introduction

Refactoring infrastructure code in Terraform has traditionally come with a hidden cost: resource recreation. Rename a resource, move it to a new module, or even change its name slightly—and Terraform might assume it's a completely new resource, planning to destroy the old one and create a new one. This can lead to downtime, data loss, or unintended disruptions in production environments.

To address this long-standing challenge, HashiCorp introduced the moved block in Terraform v1.1, allowing you to safely refactor resources across modules and names without recreating them. In this post, we'll explore how the moved block works, when to use it, and how it simplifies resource management in Terraform.

What is the moved Block?

The moved block is a declarative instruction that tells Terraform:

“This resource used to be located at X, and now it’s at Y. Don’t destroy and recreate it—just update the state.”

This block enables state-aware resource moves during a plan or apply without the need for terraform state mv commands or manual state surgery.

Real-World Problem: Resource Rename

Let’s say you originally had this resource:

resource "aws_instance" "web_server" {
  ami           = "ami-1234567"
  instance_type = "t3.micro"
}

Now you decide to rename it to something more descriptive:

resource "aws_instance" "frontend_server" {
  ami           = "ami-1234567"
  instance_type = "t3.micro"
}

Without telling Terraform what happened, a terraform plan would show:

• - Destroy aws_instance.web_server

• + Create aws_instance.frontend_server

This leads to resource recreation—bad news in a live environment.

Solution: Add a moved Block

You can now tell Terraform what changed:

moved {
  from = aws_instance.web_server
  to   = aws_instance.frontend_server
}

Terraform now knows the resource is just being renamed and will move the state internally—without destroying or creating anything.

Moving Across Modules

The moved block also supports moving resources between modules, even nested ones:

Old Structure:

module "compute" {
  source = "./modules/compute"
}

Inside modules/compute/main.tf:

resource "aws_instance" "server" { ... }

You now move this resource to a new module, say modules/core. Add a moved block in the root:

moved {
  from = module.compute.aws_instance.server
  to   = module.core.aws_instance.server
}

Terraform handles the state transfer for you—no manual state editing needed.

Important Considerations

• The moved block must be in the root module, not inside the child module.

• It only takes effect during terraform apply, not just plan.

• You still need to keep the resource configurations identical (or compatible) for a smooth transition.

• For multiple moves, you can define multiple moved blocks.

When to Use the moved Block?

• Renaming resources (changing Terraform names).

• Splitting or reorganizing modules.

• Refactoring large monolith modules into smaller units.

• Avoiding terraform state mv, especially in CI/CD environments.

Why It Matters

The moved block helps Terraform users:

• Avoid downtime and resource recreation during refactoring.

• Make safe structural changes to their codebase.

• Achieve clean, maintainable Terraform configurations over time.

Combined with good version control and code review practices, it makes Terraform more robust for long-term use.

Final Thoughts

Refactoring is a natural part of infrastructure evolution. With the moved block, Terraform finally provides a first-class, declarative way to track and manage those changes—safely, and without risky workarounds.

If you're planning a large-scale refactor, or even a simple rename, take advantage of the moved block to keep your infrastructure stable, clean, and maintainable.

SPEAK TO OUR INFRASTRUCTURE EXPERT