» Command: taint
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 will show that the resource will be destroyed and recreated and the next apply 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 will show this if this is the case.
terraform taint [options] address
address argument is the address of the resource to mark as tainted.
The address is in
the resource address syntax syntax,
as shown in the output from other commands, such as:
[\"key\"](quotes in resource addresses must be escaped on the command line, so that they are not interpreted by your shell)
The command-line flags are all optional. The list of available flags are:
-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.
-backup=path- Path to the backup file. Defaults to
-state-outwith the ".backup" extension. Disabled by setting to "-".
-lock=true- Lock the state file when locking is supported.
-lock-timeout=0s- Duration to retry a state lock.
-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 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" Resource instance module.couchbase.aws_instance.cb_node has been marked as tainted.
Although we recommend that most configurations use only one level of nesting and employ module composition, 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" Resource instance module.child.module.grandchild.aws_instance.example has been marked as tainted.