Moving Resources

Terraform's state associates each real-world object with a configured resource at a specific resource address. This is seamless when changing a resource's attributes, but Terraform will lose track of a resource if you change its name, move it to a different module, or change its provider.

Usually that's fine: Terraform will destroy the old resource, replace it with a new one (using the new resource address), and update any resources that rely on its attributes.

In cases where it's important to preserve an existing infrastructure object, you can explicitly tell Terraform to associate it with a different configured resource.

For most cases we recommend using the Terraform language's refactoring features to document in your module exactly how the resource names have changed over time. Terraform reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps.

Hands On: Try the Use Configuration to Move Resources tutorial.

There are some other situations which require explicit state modifications, though. For those, consider the following Terraform commands: