Terraform address refactoring: move state without recreating infrastructure

Last updated: 5 Oct 20266 min read

tutorial

A Terraform resource address identifies an object in state. Renaming a resource or moving it into a module changes that address even if the cloud object should stay the same. A moved block tells Terraform to associate the old state address with the new configuration address. It is a state mapping, not a command to rename a cloud object or to transfer ownership between separate state backends.

Operational decision

A payments team moves an audit bucket resource into a storage module. Keep the old and new addresses in a reviewed moved block, update configuration, and run a plan under the same state lock. The HCL fragment is only the address mapping; it assumes the destination resource exists in the module and refers to the same provider object. The plan should show a move, with no create or destroy for that bucket. Retain the block while older workspaces or branches may still hold the old address. If ownership must move between separate state files, use a planned remove-and-import procedure with state backups and one writer at a time. Do not edit remote state JSON by hand because a plan looks inconvenient.

moved {
  from = aws_s3_bucket.payment_audit
  to   = module.audit_storage.aws_s3_bucket.records
}

Cost and verification

A moved block is cheap at runtime but demands coordination across environments and branches. Removing it too early can turn a later plan into a destroy-and-create operation. State migration across backends is more expensive: it needs locks, backups, a checked import identifier, and a period when two configurations cannot both manage the object. For stateful resources, the cost of an accidental replacement can dwarf the review time. Reject any plan that unexpectedly replaces a bucket containing retained records.

Common Mistakes

Do not rename an address and assume Terraform recognizes the old object.
Do not use a moved block as a cross-backend ownership transfer.
Do not approve a stateful replacement because the source diff is small.

Connected lessons

Practice and check

Advanced follow-up

devops

operations