mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-17 19: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.
64 lines
2.6 KiB
Plaintext
64 lines
2.6 KiB
Plaintext
---
|
|
page_title: Forcing Re-creation of Resources - Terraform CLI
|
|
description: Commands that allow you to destroy and re-create resources manually.
|
|
---
|
|
|
|
# Forcing Re-creation of Resources
|
|
|
|
During planning, by default Terraform retrieves the latest state of each
|
|
existing object and compares it with the current configuration, planning
|
|
actions only against objects whose current state does not match the
|
|
configuration.
|
|
|
|
However, in some cases a remote object may become damaged or degraded in a
|
|
way that Terraform cannot automatically detect. For example, if software
|
|
running inside a virtual machine crashes but the virtual machine itself is
|
|
still running then Terraform will typically have no way to detect and respond
|
|
to the problem, because Terraform only directly manages the machine as a whole.
|
|
|
|
If you know that an object is damaged, or if you want to force Terraform to
|
|
replace it for any other reason, you can override Terraform's default behavior
|
|
using [the `-replace=...` planning option](/cli/commands/plan#replace-address)
|
|
when you run either `terraform plan` or `terraform apply`:
|
|
|
|
```shellsession
|
|
$ terraform apply -replace=aws_instance.example
|
|
# ...
|
|
|
|
# aws_instance.example will be replaced, as requested
|
|
-/+ resource "aws_instance" "example" {
|
|
# ...
|
|
}
|
|
```
|
|
|
|
## The "tainted" status
|
|
|
|
Sometimes Terraform is able to infer automatically that an object is in an
|
|
incomplete or degraded state. For example, if creation of a complex object
|
|
fails in such a way that parts of it already exist in the remote system, or
|
|
if object creation succeeded but a provisioner step subsequently failed,
|
|
Terraform must remember that the object exists but may not be fully-functional.
|
|
|
|
Terraform represents this situation by marking an object in the state as
|
|
"tainted". When an object is marked with this status, the next plan will force
|
|
replacing that object in a similar way to if you had specified that object's
|
|
address using `-replace=...` as described above.
|
|
|
|
```
|
|
# aws_instance.example is tainted, so must be replaced
|
|
-/+ resource "aws_instance" "example" {
|
|
# ...
|
|
}
|
|
```
|
|
|
|
If Terraform has marked an object as tainted but you consider it to be working
|
|
correctly and do not want to replace it, you can override Terraform's
|
|
determination using [the `terraform untaint` command](/cli/commands/untaint),
|
|
after which Terraform will consider the object to be ready for use by any
|
|
downstream resource declarations.
|
|
|
|
You can also _force_ Terraform to mark a particular object as tainted using
|
|
[the `terraform taint` command](/cli/commands/taint), but that approach is
|
|
deprecated in favor of the `-replace=...` option, which avoids the need to
|
|
create an interim state snapshot with a tainted object.
|