Refactoring with moved and removed Blocks

The reference page describes the mechanism in two sentences. Before creating a plan for the resource at the to address, Terraform checks the state for an existing object at the from address. If there is one, Terraform treats it as if it had originally been created at the new address, so the plan has no reason to destroy it.

Four consequences follow, and they explain most of the behaviour you will see:

Source: Terraform Docs — Refactor modules, Terraform Docs — terraform state mv and Terraform Docs — JSON Output Format

The simplest case, and the one in the opening picture. Change the label of the resource block and record the old one:

Source: Terraform Docs — Refactor modules, Rename a resource

Because both addresses name the resource as a whole, the move covers all of its instances. The documentation uses a resource with count = 2 to make the point: aws_instance.a[0] is treated as aws_instance.b[0] and aws_instance.a[1] as aws_instance.b[1], without listing them.

The plan afterwards, abbreviated and illustrative, contains a single comment line and no actions:

Source: Terraform Tutorial — Use Configuration to Move Resources

A module call is renamed the same way, and every resource inside follows, because the module path is a prefix of every address in it:

Source: Terraform Docs — Refactor modules, Rename a module call

With this block module.redis.docker_container.this is treated as module.cache.docker_container.this, and, if the call used count or for_each, all instances move without being listed. After renaming a module call, run terraform init again so the working directory registers the new name; the tutorial does this after its own module rename.

Extracting resources into a module is the refactoring teams do most. The code that used to be in the root module becomes a child module, and each resource needs a moved block from its root address to its address inside the module:

Source: Terraform Docs — Refactor modules, Split a module

The destination may be renamed on the way (cache in the root became this in the module), as the example shows, because a moved block is just two addresses. The official tutorial moves an EC2 instance and its data source into a new child module in the same way and reports aws_instance.example has moved to module.ec2_instance.aws_instance.example.

Source: Terraform Tutorial — Use Configuration to Move Resources

The module resolution rule matters in larger trees: Terraform resolves module references in a moved block relative to the module instance in which the block is defined. If the block lives in a child module named module.original, the reference module.x.aws_instance.a means module.original.module.x.aws_instance.a, and a module may only make moved statements about its own objects and the objects of its child modules.

Adding count or for_each to a resource changes its addresses, because the instance gets a key. The existing single object is bound to the address without a key, so it has to be assigned a key. The documentation puts it directly: to preserve the object that was previously associated with the plain address, add a moved block that specifies which instance key the object takes in the new configuration.

Source: Terraform Docs — Refactor modules, Enable count or for_each for a resource

Terraform keeps the old container as primary and only plans to create secondary. Without the block the plan would destroy the old container and create two new ones.

The rule is that when at least one of the two addresses includes an instance key, Terraform reads both addresses as specific instances rather than whole resources. That one rule covers every switch, and the documentation lists these valid blocks:

Source: Terraform Docs — Refactor modules, Enable count or for_each for a resource

Applied to the Bookshelf, a count of replicas converted to named keys looks like this. Each index is mapped to a key explicitly, because there is no rule that could guess it:

Source: Terraform Docs — Refactor modules, Enable count or for_each for a resource

This is also the standard remedy for the weakness of count that Meta-Arguments: count, for_each and depends_on describes: indexes shift when an element is removed from the middle of a list, so teams move to for_each with stable keys, and the moved blocks carry the existing objects across without recreating any of them.

A detail worth knowing: when you add count to a resource that did not have it, and you write no moved block that mentions the resource, Terraform on its own proposes to move the original object to instance 0. The documentation still recommends writing the block explicitly, so that future readers of the module see the change.

The same works for module calls. This example moves the objects of a single module call to instance 2 of the new count, so that Terraform creates only module.a[0] and module.a[1]:

Source: Terraform Docs — Refactor modules, Enable count or for_each for a module call

A module that has grown too large is split in two. The documentation’s recipe has three steps: write the new modules with copies of the resources they will contain, then edit the original so that it holds only a shim that calls the new modules, and put the moved blocks in the shim. For the Bookshelf, a platform module that created the network and the PostgreSQL volume together is split into network and data:

Source: Terraform Docs — Refactor modules, Split a module

When someone upgrades to the shim version, Terraform notices the moved blocks and behaves as if the objects had originally been created inside the new modules. New users can call either the shim or the two new modules directly. The documentation suggests telling existing users that the old module is now deprecated.

It also states the cost of the technique. A parent module normally sees a child as a closed box, unaware of which resources are inside it. Writing module.network.docker_network.this in a moved block breaks that rule, which is acceptable only because the three modules are maintained by the same people and distributed together in one module package.

If the destination is a module call that uses count or for_each, the to address must include the instance key of the call:

Source: Terraform Docs — Refactor modules, Split a module

Moving between modules, in the other direction too. The same two-address syntax covers a resource leaving a module for the root, one module’s resource going to a sibling module, or a whole module call going into another module, as long as the block is written in a module that contains both objects, because a module may only make statements about its own objects and those of its child modules. The simplest place for such a block is the root module, whose view includes everything. The release notes of Terraform 1.3 add that moved blocks can describe resources moving to and from modules that come from separate module packages.

Source: Terraform v1.3 CHANGELOG

Different resource types have different schemas, so objects of different types are normally not compatible. The refactoring page says you can always use moved to rename a resource, but that some providers also let you change an object from one resource type to another, and tells you to check the provider documentation for the supported pairs.

This was added in Terraform 1.8: a moved block can move between two resource types only if the provider of the target type declares that it can convert from the source type. OpenTofu added the same capability in 1.10, with automatic migration of the state data. Terraform 1.9 added one built-in case, moving the null_resource of the hashicorp/null provider to the terraform_data resource of the built-in provider:

Source: Terraform v1.9 CHANGELOG and Terraform Docs — The terraform_data managed resource type

Two limits apply. A moved block cannot turn a managed resource into a data source, and a pair of types that no provider documents as convertible is not made to work by the block. terraform_data itself is covered in Provisioners, Actions and Post-Apply Operations.

If the same object is renamed twice, the documentation recommends chaining the blocks rather than editing the first one:

Source: Terraform Docs — Refactor modules, Remove a move block

Chaining lets a configuration whose state still has docker_container.api and one that already has docker_container.catalog both end up at docker_container.catalog_api.

What about deleting old moved blocks? The documentation is clear on both sides. Removing a moved block is a breaking change: any configuration that still refers to the old address plans to delete the existing object instead of moving it, and it strongly recommends keeping all historical moved blocks from earlier versions to preserve the upgrade path of users of any previous version. It can be safe to remove them for private modules in an organisation when you are certain that every user has run terraform apply with the new module version.

A practical way to organise them is one moved.tf file per module (or per configuration) that only holds moved blocks, oldest first, each with a short comment saying why and in which release it happened. In a root configuration that only you run, the history can be removed after the change has been applied in every environment.

Since Terraform 1.10, moved blocks respect reserved keywords when parsing resource addresses. If a resource type name matches a top-level block or keyword of the moved block, you must prepend the resource. identifier to the reference. This only affects unusual type names, but a plan that suddenly fails to parse an old moved block after an upgrade points to it.

Source: Terraform v1.10 CHANGELOG

Source: Terraform Docs — removed block reference

The standard use is stop managing an object while it keeps running. The instructions for removing a resource from state list the steps: replace the resource block with a removed block, set from to the address, add the lifecycle block with destroy = false, delete references to the resource’s attributes (running terraform validate finds them), and apply. For the Bookshelf, suppose that the covers bucket is going to belong to a storage team:

Source: Terraform Docs — Remove a resource from state

The plan, abbreviated and illustrative, states the intent in the words quoted in the official refactoring page: the resource will no longer be managed by Terraform, but will not be destroyed, because destroy = false is set in the configuration. The reference to the bucket in other resources must have been removed first, otherwise validation fails.

The documentation also recommends removed over the terraform state rm command because it lets you preview the result, which makes it the safer way. If you want to manage the object again later, it must be imported back, as described in Import and Query.

Removing a module. The module documentation says the same of a whole module. Deleting a module block makes Terraform destroy every resource the module manages and remove it from state; replacing the call with a removed block that has destroy = false keeps all of the real objects:

Source: Terraform Docs — Configure modules, Remove a module

With destroy = true the block is not useless. It documents the removal in code and, since Terraform 1.9, it can carry destroy-time provisioners: actions to run when the object is destroyed, even though the resource block that originally declared them is gone. The official example prints a message on the machine that runs Terraform:

Source: Terraform Docs — removed block reference

The Bookshelf version retires the reviews-api container and deregisters it from a service list through a script. The provisioner can read the removed object’s attributes through self:

Source: Terraform Docs — removed block reference

The reference page adds cautions that apply here too. HashiCorp recommends configuration management tools over provisioners, SSH host keys are not validated unless you set host_key, and the command argument should not be built from Terraform variables by substitution, because that invites shell injection; pass values through environment as above. The release notes of Terraform 1.9 also record a fix for removed blocks with provisioners that did not execute when the resource was in a nested module, which is a reason to use at least a current patch release. Provisioners and their alternatives are covered in Provisioners, Actions and Post-Apply Operations.

The most important use of the pair is a move between states, the job that a moved block cannot do. The official refactoring page recommends it over the command line because the blocks keep a record of the configuration history. It requires Terraform 1.7 or newer. The procedure, adapted to the Bookshelf (the covers bucket goes from the platform configuration to a new storage configuration):

Source: Terraform Docs — Refactor Terraform state, Remove and import and AWS provider — aws_s3_bucket, Import

The order matters. Remove from the source state first and apply, then import into the destination; if both states claimed the bucket at once, two bindings would point to one object, which breaks the one-to-one rule from the state page. After the migration you can keep the removed and import blocks as a record of the lifecycle or delete them; the documentation allows both. Resources in the source configuration that referred to the bucket must switch to a data source or to an output read through terraform_remote_state, which is exactly the "identify dependencies" step of the same page. The backends that allow this are described in Backends and Remote State.

OpenTofu has the same block and extended it in 1.10 so that it can include lifecycle and provisioner configuration. The differences that matter:

Source: OpenTofu Docs — Resource syntax and OpenTofu v1.10 CHANGELOG

The following sequence applies the pieces of this page in a life cycle of three releases. It is a convention, not a requirement of the tool.

Consumers pin a range such as version = "~> 1.5" and move to the next major version deliberately. For a version that cannot be applied directly, the module can offer both shapes for a while: the shim technique from the split example, in which the old module becomes a thin wrapper around the new ones.

On the consumer side, a major upgrade is a refactoring of the root configuration and deserves the same discipline:

Source: Terraform Docs — Refactor modules and Terraform Docs — terraform init

The same applies to provider major versions: the upgrade is an external change, and a required_providers constraint change is followed by terraform init -upgrade and a plan that you read before apply. The provider’s own upgrade guide lists the arguments that were renamed or removed. The tests that guard modules against regressions are the subject of Testing.

Teaching material written before Terraform 1.1 refactors with terraform state mv only, and material written before 1.7 removes objects with terraform state rm. Both commands still work, but the official documentation now presents the blocks as the recommended approach. One of the two books used as a source for this section does not cover import blocks or moved and removed refactoring at all, so its state-editing recipes are the legacy ones; the other treats internal and external refactoring, including moved blocks and major versions, and remains the better guide to the concepts. Neither can mention the deprecated attribute of Terraform 1.15, the cross-type moves of 1.8, or destroy-time provisioners in removed blocks (1.9), which postdate them. When a book and the official page disagree, follow the official page for your version.