mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-16 16:00:37 -05:00
beb9432155
Previously the "terraform state ..." subcommands were the only way to perform various manipulations of the state, but in recent Terraform versions we have replaced these with better options. Since these pages seem to already have pretty good search engine optimization for the use-cases they are describing, we'll prioritize mentioning the new approaches and only mention the now-deprecated or de-emphasized features as a secondary approach. Specifically: - Describe the -replace=... planning option in preference to "terraform taint", and present taint as primarily a mechanism for Terraform to use itself, as opposed to something end-users should typically use directly. - Introduce the config-based refactoring features before describing "terraform state mv". The older features here are still applicable in some situations and are required for those still using older versions of Terraform, so we will retain the information about them for now while aiming to be clearer in each case about which is our preferred, modern approach.
49 lines
2.3 KiB
Plaintext
49 lines
2.3 KiB
Plaintext
---
|
|
page_title: Moving Resources - Terraform CLI
|
|
description: >-
|
|
Commands that allow you to manage the way that resources are tracked in state.
|
|
They are helpful when you move or change resources.
|
|
---
|
|
|
|
# Moving Resources
|
|
|
|
Terraform's state associates each real-world object with a configured resource
|
|
at a specific [resource address](/cli/state/resource-addressing). 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](/language/modules/develop/refactoring)
|
|
to document in your module exactly how the resource names have changed over
|
|
time. Terraform will react to this information automatically during planning,
|
|
and thus users of your module will not need to take any unusual extra steps.
|
|
|
|
> **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn.
|
|
|
|
There are some other situations which require explicit state modifications,
|
|
though. For those, consider the following Terraform commands:
|
|
|
|
- [The `terraform state mv` command](/cli/commands/state/mv) changes
|
|
which resource address in your configuration is associated with a particular
|
|
real-world object. Use this to preserve an object when renaming a resource, or
|
|
when moving a resource into or out of a child module.
|
|
|
|
- [The `terraform state rm` command](/cli/commands/state/rm) tells
|
|
Terraform to stop managing a resource as part of the current working directory
|
|
and workspace, _without_ destroying the corresponding real-world object. (You
|
|
can later use `terraform import` to start managing that resource in a
|
|
different workspace or a different Terraform configuration.)
|
|
|
|
- [The `terraform state replace-provider` command](/cli/commands/state/replace-provider)
|
|
transfers existing resources to a new provider without requiring them to be
|
|
re-created.
|