ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/cli/commands/taint.mdx

68 lines
2.9 KiB
Plaintext
Raw Normal View History

website: docs for tainted command
2015-02-26 19:37:08 +01:00
---
migrate docs to mdx
2021-12-15 03:41:17 +01:00
page_title: 'Command: taint'
website: docs for tainted command
2015-02-26 19:37:08 +01:00
description: |-
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
2021-04-07 21:25:59 +02:00
The `terraform taint` command informs Terraform that a particular object
is damaged or degraded.
website: docs for tainted command
2015-02-26 19:37:08 +01:00
---
# Command: taint
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
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
Update taint command page to make alternative clearer
2021-12-20 21:43:31 +01:00
object as "tainted" in the Terraform state, and Terraform will
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
2021-04-07 21:25:59 +02:00
propose to replace it in the next plan you create.
website: docs for tainted command
2015-02-26 19:37:08 +01:00
Update taint command page to make alternative clearer
2021-12-20 21:43:31 +01:00
~> **Warning:** This command is deprecated. For Terraform v0.15.2 and later, we recommend using the `-replace` option with `terraform apply` instead (details below).
command: New -replace=... planning option This allows a similar effect to pre-tainting an object but does the action within the context of a normal plan and apply, avoiding the need for an intermediate state where the old object still exists but is marked as tainted. The core functionality for this was already present, so this commit is just the UI-level changes to make that option available for use and to explain how it contributed to the resulting plan in Terraform's output.
2021-04-30 23:46:22 +02:00
Update taint command page to make alternative clearer
2021-12-20 21:43:31 +01:00
## Recommended Alternative
For Terraform v0.15.2 and later, we recommend using the [`-replace` option](/cli/commands/plan#replace-address) with `terraform apply` to force Terraform to replace an object even though there are no configuration changes that would require it.
command: New -replace=... planning option This allows a similar effect to pre-tainting an object but does the action within the context of a normal plan and apply, avoiding the need for an intermediate state where the old object still exists but is marked as tainted. The core functionality for this was already present, so this commit is just the UI-level changes to make that option available for use and to explain how it contributed to the resulting plan in Terraform's output.
2021-04-30 23:46:22 +02:00
```
Update taint command page to make alternative clearer
2021-12-20 21:43:31 +01:00
$ terraform apply -replace="aws_instance.example[0]"
command: New -replace=... planning option This allows a similar effect to pre-tainting an object but does the action within the context of a normal plan and apply, avoiding the need for an intermediate state where the old object still exists but is marked as tainted. The core functionality for this was already present, so this commit is just the UI-level changes to make that option available for use and to explain how it contributed to the resulting plan in Terraform's output.
2021-04-30 23:46:22 +02:00
```
Tweaks
2021-12-20 22:01:03 +01:00
We recommend the `-replace` option because the change will be reflected in the Terraform plan, letting you understand how it will affect your infrastructure before you take any externally-visible action. When you use `terraform taint`, other users could create a new plan against your tainted object before you can review the effects.
command: New -replace=... planning option This allows a similar effect to pre-tainting an object but does the action within the context of a normal plan and apply, avoiding the need for an intermediate state where the old object still exists but is marked as tainted. The core functionality for this was already present, so this commit is just the UI-level changes to make that option available for use and to explain how it contributed to the resulting plan in Terraform's output.
2021-04-30 23:46:22 +02:00
website: docs for tainted command
2015-02-26 19:37:08 +01:00
## Usage
Update taint command page to make alternative clearer
2021-12-20 21:43:31 +01:00
```
$ terraform taint [options] <address>
```
website: docs for tainted command
2015-02-26 19:37:08 +01:00
website: Update taint command docs to reflect new 0.12 usage
2019-06-04 00:36:38 +02:00
The `address` argument is the address of the resource to mark as tainted.
website: example of "terraform taint" with a grandchild module I've seen folks ask about how to express this in resource address syntax a number of times now, so adding this example here to illustrate how it looks when there are multiple levels of module to traverse through. This is redundant with other information further up the page, but having it as an entirely separate example gives an opportunity to include more introductory text to explain what the example is showing.
2019-11-09 01:25:36 +01:00
The address is in
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[the resource address syntax](/cli/state/resource-addressing) syntax,
website: example of "terraform taint" with a grandchild module I've seen folks ask about how to express this in resource address syntax a number of times now, so adding this example here to illustrate how it looks when there are multiple levels of module to traverse through. This is redundant with other information further up the page, but having it as an entirely separate example gives an opportunity to include more introductory text to explain what the example is showing.
2019-11-09 01:25:36 +01:00
as shown in the output from other commands, such as:
website: fix <ul> formatting in "taint" doc
2019-08-20 01:23:30 +02:00
migrate docs to mdx
2021-12-15 03:41:17 +01:00
* `aws_instance.foo`
* `aws_instance.bar[1]`
* `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)
* `module.foo.module.bar.aws_instance.qux`
website: docs for tainted command
2015-02-26 19:37:08 +01:00
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
2021-04-07 21:25:59 +02:00
This command accepts the following options:
website: docs for tainted command
2015-02-26 19:37:08 +01:00
command/taint: -allow-missing
2015-02-26 19:56:45 +01:00
* `-allow-missing` - If specified, the command will succeed (exit code 0)
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
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.
update command docs
2017-04-04 19:48:59 +02:00
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
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.
update command docs
2017-04-04 19:48:59 +02:00
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
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.
Provide example for terraform taint documentation (#15873) * Provide example to taint documentation Provides an example (with similar formatting as https://www.terraform.io/docs/commands/state/list.html#example-filtering-by-module) for tainting resources within a module. * Add documentation for tainting a single resource
2017-08-22 20:47:30 +02:00
cli+website: -ignore-remote-version docs and other cleanup We previously had only very short descriptions of what -ignore-remote-version does due to having the documentation for it inline on many different command pages and -help output. Instead, we'll now centralize the documentation about this argument on the remote backend page, and link to it or refer to it from all other locations. This then allows us to spend more words on discussing what Terraform normally does _without_ this option and warning about the consequences of using it. This continues earlier precedent for some local-backend-specific options which we also don't recommend for typical use. While this does make these options a little more "buried" than before, that feels justified given that they are all "exceptional use only" sort of options where users ought to learn about various caveats before using them. While there I also took this opportunity to fix some earlier omissions with the local-backend-specific options and a few other minor consistency tweaks.
2021-05-11 20:37:32 +02:00
For configurations using
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[the `remote` backend](/language/settings/backends/remote)
cli+website: -ignore-remote-version docs and other cleanup We previously had only very short descriptions of what -ignore-remote-version does due to having the documentation for it inline on many different command pages and -help output. Instead, we'll now centralize the documentation about this argument on the remote backend page, and link to it or refer to it from all other locations. This then allows us to spend more words on discussing what Terraform normally does _without_ this option and warning about the consequences of using it. This continues earlier precedent for some local-backend-specific options which we also don't recommend for typical use. While this does make these options a little more "buried" than before, that feels justified given that they are all "exceptional use only" sort of options where users ought to learn about various caveats before using them. While there I also took this opportunity to fix some earlier omissions with the local-backend-specific options and a few other minor consistency tweaks.
2021-05-11 20:37:32 +02:00
only, `terraform taint`
also accepts the option
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[`-ignore-remote-version`](/language/settings/backends/remote#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
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
2021-04-07 21:25:59 +02:00
For configurations using
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[the `local` backend](/language/settings/backends/local) only,
website: Reworking of the "terraform plan" docs, and related pages It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
2021-04-07 21:25:59 +02:00
`terraform taint` also accepts the legacy options
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).