HashiCorp Certified: Terraform Associate
moved, removed and terraform state mv for Terraform Associate
By default Terraform treats a renamed or moved resource block as a request to destroy the old object and create a new one. A moved block in the configuration, or terraform state mv on the command line, attaches the existing object to the new address instead. To stop managing an object without destroying it, use a removed block with destroy = false, or terraform state rm.
Why a rename destroys by default
State binds each real object to a resource address such as aws_instance.a. If you rename the block to aws_instance.b, the configuration no longer has anything at aws_instance.a, and nothing in state exists at aws_instance.b. Terraform reads that as: destroy the first object, create a second one.
Both tools below fix this by changing the address recorded in state, so the plan shows no destroy.
moved blocks
A moved block has two arguments, from and to. Before planning, Terraform checks state for an object at from. If one exists, Terraform renames it to to and then plans as if the object had been created there. Pointing at a whole resource covers all its instances, so aws_instance.a[0] and aws_instance.a[1] become aws_instance.b[0] and aws_instance.b[1].
Uses include renaming a resource, moving a resource or module, renaming a module call, splitting a module, and adding count or for_each to a resource while keeping the existing object at a chosen key.
Because the block is part of the configuration, it is reviewed in the plan and takes effect for everyone who runs the configuration. This makes it the tool for a published module: each consumer gets the move on their next plan without running a command. Instances that never had the old address ignore the block.
moved blocks need Terraform v1.1 or later. Removing a moved block later is a breaking change. A moved block cannot turn a managed resource into a data resource.
terraform state mv
terraform state mv SOURCE DESTINATION changes the address of an object in state directly, for example terraform state mv packet_device.worker packet_device.helper. Both addresses must be the same kind of object, and a resource can only move to an address of the same resource type. -dry-run lists what would move.
It is a one-off command against one state. In a team, make sure nobody plans or applies between your configuration change and the state mv, or their plan may destroy the old object and create a new one.
removed blocks and terraform state rm
A removed block takes from and a lifecycle block with destroy. By default Terraform removes the resource from state and also destroys the real object. Set destroy = false to remove it from state and leave the object running, for example to hand it to another team or tool. removed blocks need Terraform v1.7 or later.
terraform state rm ADDRESS also removes the binding without destroying the object. If the resource block is still in the configuration, the next plan proposes to create a new object, which can fail if the name clashes with the old one. HashiCorp suggests removed blocks instead, because they can remove several resources at once and are reviewed in the normal plan and apply.
Where the exam catches people
- Believing a removed block leaves the object running by default: by default it destroys the object. Set
destroy = falsein its lifecycle block. - Believing
terraform state mvis the right fix inside a published module: every consumer would have to run it. A moved block travels with the module. - Believing
terraform state rmdeletes the object: the object keeps running and Terraform stops tracking it. - Believing a moved block can be deleted once applied without effect: HashiCorp calls removing a moved block a breaking change.
- Believing a moved block can turn a resource into a data source: it cannot move a managed resource to a data resource.