terraform/website/docs/commands/taint.html.markdown

116 lines
4.6 KiB
Markdown
Raw Normal View History

2015-02-26 19:37:08 +01:00
---
layout: "docs"
page_title: "Command: taint"
sidebar_current: "docs-commands-taint"
description: |-
The `terraform taint` command manually marks a Terraform-managed resource as tainted, forcing it to be destroyed and recreated on the next apply.
---
# Command: taint
The `terraform taint` command manually marks a Terraform-managed resource
as tainted, forcing it to be destroyed and recreated on the next apply.
This command _will not_ modify infrastructure, but does modify the
state file in order to mark a resource as tainted. Once a resource is
marked as tainted, the next
[plan](/docs/commands/plan.html) will show that the resource will
be destroyed and recreated and the next
[apply](/docs/commands/apply.html) will implement this change.
Forcing the recreation of a resource is useful when you want a certain
side effect of recreation that is not visible in the attributes of a resource.
For example: re-running provisioners will cause the node to be different
or rebooting the machine from a base image will cause new startup scripts
to run.
Note that tainting a resource for recreation may affect resources that
depend on the newly tainted resource. For example, a DNS resource that
uses the IP address of a server may need to be modified to reflect
the potentially new IP address of a tainted server. The
[plan command](/docs/commands/plan.html) will show this if this is
the case.
## Usage
Usage: `terraform taint [options] address`
2015-02-26 19:37:08 +01:00
The `address` argument is the address of the resource to mark as tainted.
The address is in
[the resource address syntax](/docs/internals/resource-addressing.html) syntax,
as shown in the output from other commands, such as:
* `aws_instance.foo`
* `aws_instance.bar[1]`
2019-10-28 18:04:38 +01:00
* `aws_instance.baz``[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they are not interpreted by your shell)
* `module.foo.module.bar.aws_instance.qux`
2015-02-26 19:37:08 +01:00
The command-line flags are all optional. The list of available flags are:
2015-02-26 19:56:45 +01:00
* `-allow-missing` - If specified, the command will succeed (exit code 0)
even if the resource is missing. The command can still error, but only
in critically erroneous cases.
2015-02-26 19:37:08 +01:00
* `-backup=path` - Path to the backup file. Defaults to `-state-out` with
the ".backup" extension. Disabled by setting to "-".
2017-04-04 19:48:59 +02:00
* `-lock=true` - Lock the state file when locking is supported.
* `-lock-timeout=0s` - Duration to retry a state lock.
2015-02-26 19:37:08 +01:00
* `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/state/remote.html) is used.
2015-02-26 19:37:08 +01:00
* `-state-out=path` - Path to write updated state file. By default, the
`-state` path will be used. Ignored when
[remote state](/docs/state/remote.html) is used.
backend: Validate remote backend Terraform version When using the enhanced remote backend, a subset of all Terraform operations are supported. Of these, only plan and apply can be executed on the remote infrastructure (e.g. Terraform Cloud). Other operations run locally and use the remote backend for state storage. This causes problems when the local version of Terraform does not match the configured version from the remote workspace. If the two versions are incompatible, an `import` or `state mv` operation can cause the remote workspace to be unusable until a manual fix is applied. To prevent this from happening accidentally, this commit introduces a check that the local Terraform version and the configured remote workspace Terraform version are compatible. This check is skipped for commands which do not write state, and can also be disabled by the use of a new command-line flag, `-ignore-remote-version`. Terraform version compatibility is defined as: - For all releases before 0.14.0, local must exactly equal remote, as two different versions cannot share state; - 0.14.0 to 1.0.x are compatible, as we will not change the state version number until at least Terraform 1.1.0; - Versions after 1.1.0 must have the same major and minor versions, as we will not change the state version number in a patch release. If the two versions are incompatible, a diagnostic is displayed, advising that the error can be suppressed with `-ignore-remote-version`. When this flag is used, the diagnostic is still displayed, but as a warning instead of an error. Commands which will not write state can assert this fact by calling the helper `meta.ignoreRemoteBackendVersionConflict`, which will disable the checks. Those which can write state should instead call the helper `meta.remoteBackendVersionCheck`, which will return diagnostics for display. In addition to these explicit paths for managing the version check, we have an implicit check in the remote backend's state manager initialization method. Both of the above helpers will disable this check. This fallback is in place to ensure that future code paths which access state cannot accidentally skip the remote version check.
2020-11-13 22:43:56 +01:00
* `-ignore-remote-version` - When using the enhanced remote backend with
Terraform Cloud, continue even if remote and local Terraform versions differ.
This may result in an unusable Terraform Cloud workspace, and should be used
with extreme caution.
## Example: Tainting a Single Resource
This example will taint a single resource:
```
$ terraform taint aws_security_group.allow_all
2019-08-28 19:47:14 +02:00
The resource aws_security_group.allow_all in the module root has been marked as tainted.
```
## Example: Tainting a single resource created with for_each
This example will taint a single resource created with for_each:
```
$ terraform taint 'module.route_tables.azurerm_route_table.rt["DefaultSubnet"]'
The resource module.route_tables.azurerm_route_table.rt["DefaultSubnet"] in the module root has been marked as tainted.
```
~> Note: In most `sh` compatible shells, double quotes and spaces can be
escaped by wrapping the argument in single quotes. This however varies between
other shells and operating systems, and users should use the appropriate escape
characters based on the applicable quoting rules for their shell to pass the
address string, including quotes, to Terraform.
## Example: Tainting a Resource within a Module
This example will only taint a resource within a module:
```
$ terraform taint "module.couchbase.aws_instance.cb_node[9]"
2019-08-28 19:47:14 +02:00
Resource instance module.couchbase.aws_instance.cb_node[9] has been marked as tainted.
```
Although we recommend that most configurations use only one level of nesting
and employ [module composition](/docs/modules/composition.html), it's possible
to have multiple levels of nested modules. In that case the resource instance
address must include all of the steps to the target instance, as in the
following example:
```
$ terraform taint "module.child.module.grandchild.aws_instance.example[2]"
Resource instance module.child.module.grandchild.aws_instance.example[2] has been marked as tainted.
```