ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #30431 from hashicorp/replace-flag-clarifications 

Make -replace flag clearer
This commit is contained in:
Laura Pacilio 2022-02-01 10:47:04 -05:00 committed by GitHub
parent 0900c7e0bb a794c80e0d
commit d3bc3a63dd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 23 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
website/docs/cli/commands/apply.mdx
View File

@ -39,10 +39,8 @@ Terraform will propose the plan to you and prompt you to approve it before
taking the described actions, unless you waive that prompt by using the taking the described actions, unless you waive that prompt by using the
`-auto-approve` option. `-auto-approve` option.
When performing its own plan, `terraform apply` supports all of the same -> **Tip:** When you run `terraform apply` without a saved plan file, you can use all of the [planning modes](/cli/commands/plan#planning-modes) and
[planning modes](/cli/commands/plan#planning-modes) and [planning options](/cli/commands/plan#planning-options) available for `terraform plan`. This lets you customize how Terraform will create the plan.
[planning options](/cli/commands/plan#planning-options) that `terraform plan` would
accept, so you can customize how Terraform will create the plan.
### Saved Plan Mode ### Saved Plan Mode
@ -67,10 +65,7 @@ plan`'s planning modes and planning options. For details, see:
### Apply Options ### Apply Options
The following options allow you to change various details about how the The following options allow you to change various details about how the
apply command executes and reports on the apply operation. If you are running apply command executes and reports on the apply operation.
`terraform apply` _without_ a previously-saved plan file, these options are
_in addition to_ the planning modes and planning options described for
[`terraform plan`](/cli/commands/plan).
* `-auto-approve` - Skips interactive approval of plan before applying. This * `-auto-approve` - Skips interactive approval of plan before applying. This
option is ignored when you pass a previously-saved plan file, because option is ignored when you pass a previously-saved plan file, because
@ -114,6 +109,10 @@ _in addition to_ the planning modes and planning options described for
[walks the graph](/internals/graph#walking-the-graph). Defaults to [walks the graph](/internals/graph#walking-the-graph). Defaults to
10\. 10\.
- All [planning modes](/cli/commands/plan#planning-modes) and
[planning options](/cli/commands/plan#planning-options) for
`terraform plan` - Customize how Terraform will create the plan. Only available when you run `terraform apply` without a saved plan file.
For configurations using For configurations using
[the `local` backend](/language/settings/backends/local) only, [the `local` backend](/language/settings/backends/local) only,
`terraform apply` also accepts the legacy options `terraform apply` also accepts the legacy options

70
website/docs/cli/commands/plan.mdx
View File

@ -82,12 +82,9 @@ The remaining sections on this page describe the various options:
## Planning Modes ## Planning Modes
The section above described Terraform's default planning behavior, which is The previous section describes Terraform's default planning behavior, which
intended for changing the remote system to match with changes you've made to changes the remote system to match the changes you make to
your configuration. your configuration. Terraform has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `terraform plan` and [`terraform apply`](/cli/commands/apply).
Terraform has two alternative planning modes, each of which creates a plan with
a different intended outcome:
* **Destroy mode:** creates a plan whose goal is to destroy all remote objects * **Destroy mode:** creates a plan whose goal is to destroy all remote objects
that currently exist, leaving an empty Terraform state. This can be useful that currently exist, leaving an empty Terraform state. This can be useful
@ -127,70 +124,35 @@ and later.
## Planning Options ## Planning Options
In addition to the planning _modes_ described above, there are also several In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for both `terraform plan` and [`terraform apply`](/cli/commands/apply).
additional options that can modify details of the behavior of the planning
step.
When you use `terraform apply` without passing it a saved plan file, it - `-refresh=false` - Disables the default behavior of synchronizing the
incorporates the `terraform plan` command functionality and so the planning Terraform state with remote objects before checking for configuration changes. This can make the planning operation faster by reducing the number of remote API requests. However, setting `refresh=false` causes Terraform to ignore external changes, which could result in an incomplete or incorrect plan. You cannot use `refresh=false` in refresh-only planning mode because it would effectively disable the entirety of the planning operation.
options in this section, along with the planning mode selection options in
the previous section, are also available with the same meanings on
`terraform apply`.
* `-refresh=false` - Disables the default behavior of synchronizing the - `-replace=ADDRESS` - Instructs Terraform to plan to replace the
Terraform state with remote objects before checking for configuration changes. resource instance with the given address. This is helpful when one or more remote objects have become degraded, and you can use replacement objects with the same configuratation to align with immutable infrastructure patterns. Terraform will use a "replace" action if the specified resource would normally cause an "update" action or no action at all. Include this option multiple times to replace several objects at once. You cannot use `-replace` with the `-destroy` option, and it is only available from Terraform v0.15.2 onwards. For earlier versions, use [`terraform taint`](/cli/commands/taint) to achieve a similar result.
This option can potentially make the planning operation faster by reducing - `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only
the number of remote API requests, but it comes at the expense of having
Terraform not take into account any changes that might've happened outside
of Terraform, and thus the resulting plan may not be complete or correct.
This option is not available in the "refresh only" planning mode, because
it would effectively disable the entirety of the planning operation in that
case.
* `-replace=ADDRESS` - Instructs Terraform to plan to replace the single
resource instance with the given address. If the given instance would
normally have caused only an "update" action, or no action at all, then
Terraform will choose a "replace" action instead.
You can use this option if you have learned that a particular remote object
has become degraded in some way. If you are using immutable infrastructure
patterns then you may wish to respond to that by replacing the
malfunctioning object with a new object that has the same configuration.
This option is allowed only in the normal planning mode, so this option
is incompatible with the `-destroy` option.
The `-replace=...` option is available only from Terraform v0.15.2 onwards.
For earlier versions, you can achieve a similar effect (with some caveats)
using [`terraform taint`](/cli/commands/taint).
* `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only
on resource instances which match the given address and on any objects that on resource instances which match the given address and on any objects that
those instances depend on. those instances depend on.
This command is for exceptional use only. See -> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around Terraform limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
[Resource Targeting](#resource-targeting)
below for more information.
* `-var 'NAME=VALUE'` - Sets a value for a single - `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](/language/values/variables) declared in the [input variable](/language/values/variables) declared in the
root module of the configuration. Use this option multiple times to set root module of the configuration. Use this option multiple times to set
more than one variable. For more information see more than one variable. Refer to
[Input Variables on the Command Line](#input-variables-on-the-command-line), [Input Variables on the Command Line](#input-variables-on-the-command-line) for more information.
below.
* `-var-file=FILENAME` - Sets values for potentially many - `-var-file=FILENAME` - Sets values for potentially many
[input variables](/language/values/variables) declared in the [input variables](/language/values/variables) declared in the
root module of the configuration, using definitions from a root module of the configuration, using definitions from a
["tfvars" file](/language/values/variables#variable-definitions-tfvars-files). ["tfvars" file](/language/values/variables#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file. Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. For more information, module, aside from the `-var` and `-var-file` options. Refer to
see [Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables) for more information.
[Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables).
### Input Variables on the Command Line ### Input Variables on the Command Line