2015-02-26 19:37:08 +01:00
|
|
|
---
|
|
|
|
layout: "docs"
|
|
|
|
page_title: "Command: taint"
|
|
|
|
sidebar_current: "docs-commands-taint"
|
|
|
|
description: |-
|
2021-04-07 21:25:59 +02:00
|
|
|
The `terraform taint` command informs Terraform that a particular object
|
|
|
|
is damaged or degraded.
|
2015-02-26 19:37:08 +01:00
|
|
|
---
|
|
|
|
|
|
|
|
# Command: taint
|
|
|
|
|
2021-04-07 21:25:59 +02:00
|
|
|
The `terraform taint` command informs Terraform that a particular object has
|
|
|
|
become degraded or damaged. Terraform represents this by marking the
|
|
|
|
object as "tainted" in the Terraform state, in which case Terraform will
|
|
|
|
propose to replace it in the next plan you create.
|
2015-02-26 19:37:08 +01:00
|
|
|
|
2021-04-30 23:46:22 +02:00
|
|
|
~> *Warning:* This command is deprecated, because there are better alternatives
|
|
|
|
available in Terraform v1.0 and later. See below for more details.
|
|
|
|
|
|
|
|
If your intent is to force replacement of a particular object even though
|
|
|
|
there are no configuration changes that would require it, we recommend instead
|
|
|
|
to use the `-replace` option with [`terraform apply`](./apply.html).
|
|
|
|
For example:
|
|
|
|
|
|
|
|
```
|
|
|
|
terraform apply -replace="aws_instance.example[0]"
|
|
|
|
```
|
|
|
|
|
|
|
|
Creating a plan with the "replace" option is superior to using `terraform taint`
|
|
|
|
because it will allow you to see the full effect of that change before you take
|
|
|
|
any externally-visible action. When you use `terraform taint` to get a similar
|
|
|
|
effect, you risk someone else on your team creating a new plan against your
|
|
|
|
tainted object before you've had a chance to review the consequences of that
|
|
|
|
change yourself.
|
|
|
|
|
|
|
|
The `-replace=...` option to `terraform apply` is only available from
|
|
|
|
Terraform v1.0 onwards, so if you are using an earlier version you will need to
|
|
|
|
use `terraform taint` to force object replacement, while considering the
|
|
|
|
caveats described above.
|
|
|
|
|
2015-02-26 19:37:08 +01:00
|
|
|
## Usage
|
|
|
|
|
2019-06-04 00:36:38 +02:00
|
|
|
Usage: `terraform taint [options] address`
|
2015-02-26 19:37:08 +01:00
|
|
|
|
2019-06-04 00:36:38 +02:00
|
|
|
The `address` argument is the address of the resource to mark as tainted.
|
2019-11-09 01:25:36 +01:00
|
|
|
The address is in
|
2021-01-19 22:43:01 +01:00
|
|
|
[the resource address syntax](/docs/cli/state/resource-addressing.html) syntax,
|
2019-11-09 01:25:36 +01:00
|
|
|
as shown in the output from other commands, such as:
|
2019-08-20 01:23:30 +02:00
|
|
|
|
2019-06-04 00:36:38 +02:00
|
|
|
* `aws_instance.foo`
|
|
|
|
* `aws_instance.bar[1]`
|
2021-04-07 21:25:59 +02:00
|
|
|
* `aws_instance.baz[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they will not be interpreted by your shell)
|
2019-09-19 19:40:29 +02:00
|
|
|
* `module.foo.module.bar.aws_instance.qux`
|
2015-02-26 19:37:08 +01:00
|
|
|
|
2021-04-07 21:25:59 +02:00
|
|
|
This command accepts the following options:
|
2015-02-26 19:37:08 +01:00
|
|
|
|
2015-02-26 19:56:45 +01:00
|
|
|
* `-allow-missing` - If specified, the command will succeed (exit code 0)
|
2021-04-07 21:25:59 +02:00
|
|
|
even if the resource is missing. The command might still return an error
|
|
|
|
for other situations, such as if there is a problem reading or writing
|
|
|
|
the state.
|
2017-04-04 19:48:59 +02:00
|
|
|
|
2021-04-07 21:25:59 +02:00
|
|
|
* `-lock=false` - Disables Terraform's default behavior of attempting to take
|
|
|
|
a read/write lock on the state for the duration of the operation.
|
2017-04-04 19:48:59 +02:00
|
|
|
|
2021-04-07 21:25:59 +02:00
|
|
|
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
|
|
|
|
instructs Terraform to retry acquiring a lock for a period of time before
|
|
|
|
returning an error. The duration syntax is a number followed by a time
|
|
|
|
unit letter, such as "3s" for three seconds.
|
2017-08-22 20:47:30 +02:00
|
|
|
|
2021-05-11 20:37:32 +02:00
|
|
|
For configurations using
|
|
|
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
|
|
|
only, `terraform taint`
|
|
|
|
also accepts the option
|
|
|
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
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
|
|
|
|
2021-04-07 21:25:59 +02:00
|
|
|
For configurations using
|
|
|
|
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
|
|
|
`terraform taint` also accepts the legacy options
|
|
|
|
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
|