Refactoring with moved Blocks

When you rename a resource, move it into a module, or restructure your code, Terraform sees the old address vanish and a new one appear — and by default it plans to destroy the old object and create a new one. For a stateless resource that is wasteful; for a database or a volume it is an outage or data loss from what was meant to be a pure code cleanup.

The moved block (1.1+) tells Terraform "this is the same object under a new address." With it, a refactor becomes a no-op apply that just updates state's bookkeeping — the resource is never touched in AWS.

The Refactor Problem

Suppose you rename aws_instance.web to aws_instance.api to better reflect its role. Terraform compares state (which still has web) against config (which now has api) and reads it as two unrelated facts: web is gone, so destroy it; api is new, so create it. The plan shows one to destroy and one to add. Apply that and you have torn down a running instance and replaced it with a fresh one, for a change that was only ever a name.

The moved Block

A moved block records the rename so state follows the new address. You add it alongside the renamed resource, and the next plan reads zero changes instead of a destroy and a create — Terraform recognizes that web and api are the same object and simply re-keys it in state.

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

resource "aws_instance" "api" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
}

Moving Into and Between Modules

The same block handles the bigger refactor of extracting resources into a module. When you move aws_instance.api inside a new web module, its address becomes module.web.aws_instance.this, and a moved block from the old root address to the new module address keeps state in step. This is what makes the common "we should pull this into a reusable module" cleanup safe instead of a destroy-and-recreate of everything you extract.

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

moved vs State Surgery

Before moved blocks, the same re-keying was done with terraform state mv — an imperative local command. The block is the declarative replacement: it lives in code, shows up in the plan, and applies automatically for everyone who runs it, including CI. state mv bypasses all of that. It runs on one person's machine against the shared state and is invisible to review, which is why a shared refactor belongs in a moved block and surgery is reserved for genuine one-off fixes.

Lifecycle of a moved Block

A moved block is transitional. Keep it through the apply that performs the move and long enough for every teammate and every pipeline to have applied it — because anyone whose state still has the old address needs the block to avoid the destroy-and-recreate you dodged locally. Once you are confident all states have caught up, prune it; a stale moved block referencing addresses that no longer exist is harmless but is dead code cluttering the config.