Skip to content

Commit beb9432

Browse files
apparentlymartapparentlymart
committed
website: CLI state manipulation section de-emphasize old features
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.
1 parent 28671f9 commit beb9432

3 files changed

Lines changed: 67 additions & 20 deletions

File tree

‎website/docs/cli/state/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ infrastructure.
2222
Terraform CLI supports several workflows for interacting with state:
2323

2424
- [Inspecting State](/cli/state/inspect)
25-
- [Forcing Re-creation (Tainting)](/cli/state/taint)
25+
- [Forcing Re-creation](/cli/state/taint)
2626
- [Moving Resources](/cli/state/move)
2727
- Importing Pre-existing Resources (documented in the
2828
[Importing Infrastructure](/cli/import) section)

‎website/docs/cli/state/move.mdx‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,22 @@ In cases where it's important to preserve an existing infrastructure object, you
2121
can explicitly tell Terraform to associate it with a different configured
2222
resource.
2323

24+
For most cases we recommend using
25+
[the Terraform language's refactoring features](/language/modules/develop/refactoring)
26+
to document in your module exactly how the resource names have changed over
27+
time. Terraform will react to this information automatically during planning,
28+
and thus users of your module will not need to take any unusual extra steps.
29+
30+
> **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn.
31+
32+
There are some other situations which require explicit state modifications,
33+
though. For those, consider the following Terraform commands:
34+
2435
- [The `terraform state mv` command](/cli/commands/state/mv) changes
2536
which resource address in your configuration is associated with a particular
2637
real-world object. Use this to preserve an object when renaming a resource, or
2738
when moving a resource into or out of a child module.
2839

29-
> **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn.
30-
3140
- [The `terraform state rm` command](/cli/commands/state/rm) tells
3241
Terraform to stop managing a resource as part of the current working directory
3342
and workspace, _without_ destroying the corresponding real-world object. (You

‎website/docs/cli/state/taint.mdx‎

Lines changed: 55 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,63 @@
11
---
2-
page_title: Forcing Re-creation of Resources (Tainting) - Terraform CLI
2+
page_title: Forcing Re-creation of Resources - Terraform CLI
33
description: Commands that allow you to destroy and re-create resources manually.
44
---
55

6-
# Forcing Re-creation of Resources (Tainting)
6+
# Forcing Re-creation of Resources
77

8-
When a resource declaration is modified, Terraform usually attempts to update
9-
the existing resource in place (although some changes can require destruction
10-
and re-creation, usually due to upstream API limitations).
8+
During planning, by default Terraform retrieves the latest state of each
9+
existing object and compares it with the current configuration, planning
10+
actions only against objects whose current state does not match the
11+
configuration.
1112

12-
In some cases, you might want a resource to be destroyed and re-created even
13-
when Terraform doesn't think it's necessary. This is usually for objects that
14-
aren't fully described by their resource arguments due to side-effects that
15-
happen during creation; for example, a virtual machine that configures itself
16-
with `cloud-init` on startup might no longer meet your needs if the cloud-init
17-
configuration changes.
13+
However, in some cases a remote object may become damaged or degraded in a
14+
way that Terraform cannot automatically detect. For example, if software
15+
running inside a virtual machine crashes but the virtual machine itself is
16+
still running then Terraform will typically have no way to detect and respond
17+
to the problem, because Terraform only directly manages the machine as a whole.
1818

19-
- [The `terraform taint` command](/cli/commands/taint) tells Terraform to
20-
destroy and re-create a particular resource during the next apply, regardless
21-
of whether its resource arguments would normally require that.
19+
If you know that an object is damaged, or if you want to force Terraform to
20+
replace it for any other reason, you can override Terraform's default behavior
21+
using [the `-replace=...` planning option](/cli/commands/plan#replace-address)
22+
when you run either `terraform plan` or `terraform apply`:
2223

23-
- [The `terraform untaint` command](/cli/commands/untaint) undoes a
24-
previous taint, or can preserve a resource that was automatically tainted due
25-
to failed [provisioners](/language/resources/provisioners/syntax).
24+
```shellsession
25+
$ terraform apply -replace=aws_instance.example
26+
# ...
27+
28+
# aws_instance.example will be replaced, as requested
29+
-/+ resource "aws_instance" "example" {
30+
# ...
31+
}
32+
```
33+
34+
## The "tainted" status
35+
36+
Sometimes Terraform is able to infer automatically that an object is in an
37+
incomplete or degraded state. For example, if creation of a complex object
38+
fails in such a way that parts of it already exist in the remote system, or
39+
if object creation succeeded but a provisioner step subsequently failed,
40+
Terraform must remember that the object exists but may not be fully-functional.
41+
42+
Terraform represents this situation by marking an object in the state as
43+
"tainted". When an object is marked with this status, the next plan will force
44+
replacing that object in a similar way to if you had specified that object's
45+
address using `-replace=...` as described above.
46+
47+
```
48+
# aws_instance.example is tainted, so must be replaced
49+
-/+ resource "aws_instance" "example" {
50+
# ...
51+
}
52+
```
53+
54+
If Terraform has marked an object as tainted but you consider it to be working
55+
correctly and do not want to replace it, you can override Terraform's
56+
determination using [the `terraform untaint` command](/cli/commands/untaint),
57+
after which Terraform will consider the object to be ready for use by any
58+
downstream resource declarations.
59+
60+
You can also _force_ Terraform to mark a particular object as tainted using
61+
[the `terraform taint` command](/cli/commands/taint), but that approach is
62+
deprecated in favor of the `-replace=...` option, which avoids the need to
63+
create an interim state snapshot with a tainted object.

0 commit comments

Comments
 (0)