You rename a Terraform resource and move it inside a module, and the plan now shows a destroy and a create. How do you make the refactor without touching the real infrastructure?

## Why a rename looks like a destroy State maps **addresses** to real objects. `aws_instance.web` is an address; so is `module.app.aws_instance.web`; so is `aws_instance.web["blue"]`. Terraform has no memory of what you *meant* — when it compares configuration to state and finds an address in state that is no longer in the configuration, the only conclusion available is that you want the object gone. Meanwhile the new address has no state entry, so Terraform proposes creating it. A purely cosmetic rename therefore renders as a destroy and a create, and on a database, a load balancer or anything with data or a fixed address, that is an outage. ## The moved block ```hcl moved { from = aws_instance.web to = module.app.aws_instance.web } ``` This is configuration, not a command. During plan, Terraform reads the `moved` blocks and re-keys matching state entries before it computes the diff, so the plan output reports that the resource has moved to the new address and — assuming nothing else changed — proposes no other action. The state rewrite is committed as part of apply. It works for the address shapes that refactors actually produce: - renaming a resource: `aws_instance.web` to `aws_instance.frontend` - moving a resource into or out of a module: `aws_instance.web` to `module.app.aws_instance.web` - moving an entire module call: `module.app` to `module.frontend` - changing instance keys: `aws_instance.web[0]` to `aws_instance.web["blue"]` Moves can be chained across releases — if a resource moved from A to B in one version and B to C in the next, keeping both blocks means a consumer jumping straight from A lands correctly on C. ## What it cannot do `moved` re-keys an existing entry; it does not convert one thing into another. The endpoints must be compatible — you cannot use it to change a resource's **type**, because a different type is a different provider schema and a genuinely different object. Migrating from one resource type to another is a real destroy-and-create, or an out-of-band creation plus an import. `moved` also lives inside a single configuration and its state: it cannot move a resource into a *different* state file, which is a separate operation entirely. And it is not a licence to ignore the plan. If you rename a resource *and* change an argument that forces replacement in the same commit, the moved block will re-key the entry and the plan will still show the replacement. Read what the plan actually says. ## moved versus terraform state mv ```bash terraform state mv aws_instance.web module.app.aws_instance.web ``` This achieves the same state rewrite immediately. It is the older way, and it still has uses — notably when no configuration exists to hang a block on. But as the default it is worse in every dimension that matters to a team: - **Not reviewable.** The refactor commit shows a rename; nothing in the repository says the state was fixed. A reviewer cannot tell a safe refactor from a destructive one. - **Not reproducible.** It affects whichever state the person's working directory pointed at. With a remote backend that is at least shared — but anyone on an older checkout, and any CI job that runs before the fix, plans a destroy. - **Order-sensitive and racy.** It mutates shared state outside the plan/apply cycle, taking the lock on its own. If a pipeline applies between the code merge and the manual `state mv`, it destroys the resource. - **Not idempotent in the same way.** Re-running it after the move errors, whereas a `moved` block that has already been applied is simply a no-op. The general principle in modern Terraform is that state surgery belongs in code: `moved` for refactors, `import` for adoption, `removed` for dropping management. The CLI subcommands are the escape hatch for cases the blocks do not cover. ## How long to keep the block A `moved` block is inert once every state that could contain the old address has been applied. In a single application repository with one state, that is the next apply, and you can delete it in a follow-up commit — though leaving it costs nothing but a few lines. In a shared module the calculus is different, because you do not control when consumers upgrade, and the block has to survive their deprecation window. ## Verify, do not trust The check is always the plan. `terraform plan` after adding the block should show the move and no destroy. If it still proposes destroying the old address, the `from` address is wrong — go back to `terraform state list` and copy the exact string, including index keys and module path.