From 238396567d32e95a2e6159b6f8c33e72e9433bfa Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 27 Jan 2022 16:00:08 -0500 Subject: [PATCH 1/9] Making replace flag clearer and making plan options clearer --- website/docs/cli/commands/apply.mdx | 10 +++++----- website/docs/cli/commands/plan.mdx | 12 ++++++------ 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index ece491cdc..035176821 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -39,7 +39,7 @@ 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 `-auto-approve` option. -When performing its own plan, `terraform apply` supports all of the same +-> **Tip:** When performing its own plan, `terraform apply` supports all of the same [planning modes](/cli/commands/plan#planning-modes) and [planning options](/cli/commands/plan#planning-options) that `terraform plan` would accept, so you can customize how Terraform will create the plan. @@ -67,10 +67,7 @@ plan`'s planning modes and planning options. For details, see: ### Apply Options 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 -`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). +apply command executes and reports on the apply operation. * `-auto-approve` - Skips interactive approval of plan before applying. This option is ignored when you pass a previously-saved plan file, because @@ -114,6 +111,9 @@ _in addition to_ the planning modes and planning options described for [walks the graph](/internals/graph#walking-the-graph). Defaults to 10\. +- Planning modes and options available for +[`terraform plan`](/cli/commands/plan#planning-options) - Only available when you run `terraform apply` without a previously-saved plan file. + For configurations using [the `local` backend](/language/settings/backends/local) only, `terraform apply` also accepts the legacy options diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 8cb8112e1..57d2ed5f5 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -137,7 +137,7 @@ 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 +- `-refresh=false` - Disables the default behavior of synchronizing the Terraform state with remote objects before checking for configuration changes. This option can potentially make the planning operation faster by reducing @@ -149,7 +149,7 @@ the previous section, are also available with the same meanings on it would effectively disable the entirety of the planning operation in that case. -* `-replace=ADDRESS` - Instructs Terraform to plan to replace the single +- `-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. @@ -157,7 +157,7 @@ the previous section, are also available with the same meanings on 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. + malfunctioning object with a new object that has the same configuration. You can also replace multiple objects at once by adding multiple flags to the command. This option is allowed only in the normal planning mode, so this option is incompatible with the `-destroy` option. @@ -166,7 +166,7 @@ the previous section, are also available with the same meanings on 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 +- `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only on resource instances which match the given address and on any objects that those instances depend on. @@ -174,14 +174,14 @@ the previous section, are also available with the same meanings on [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 root module of the configuration. Use this option multiple times to set more than one variable. For more information see [Input Variables on the Command Line](#input-variables-on-the-command-line), 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 root module of the configuration, using definitions from a ["tfvars" file](/language/values/variables#variable-definitions-tfvars-files). From 1a66861aaff4de88b3db0008715a37d4cd0036d6 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 27 Jan 2022 16:53:25 -0500 Subject: [PATCH 2/9] A couple other tweaks --- website/docs/cli/commands/apply.mdx | 2 +- website/docs/cli/commands/taint.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index 035176821..d6a4c2994 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -112,7 +112,7 @@ apply command executes and reports on the apply operation. 10\. - Planning modes and options available for -[`terraform plan`](/cli/commands/plan#planning-options) - Only available when you run `terraform apply` without a previously-saved plan file. +[`terraform plan`](/cli/commands/plan#planning-options) - Only available when you run `terraform apply` without a saved plan file. For configurations using [the `local` backend](/language/settings/backends/local) only, diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index b37a34b3e..40ac0526d 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -16,7 +16,7 @@ propose to replace it in the next plan you create. ## 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. +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. ``` $ terraform apply -replace="aws_instance.example[0]" From aa3a046af3747256bdd3bd464234008775d5c431 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 27 Jan 2022 16:56:50 -0500 Subject: [PATCH 3/9] final nits --- website/docs/cli/commands/plan.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 57d2ed5f5..7a879a323 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -154,10 +154,9 @@ the previous section, are also available with the same meanings on 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. You can also replace multiple objects at once by adding multiple flags to the command. + You can use this option if you have learned that one or more remote objects + has become degraded in some way. Add multiple `-replace` flags to the command to replace several objects at once. If you are using immutable infrastructure + patterns, you may wish to replace the malfunctioning objects with new objects that have the same configuration. This option is allowed only in the normal planning mode, so this option is incompatible with the `-destroy` option. From dca94a9eaf4012250c9fe8ddbb15cea9ef84f8a7 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 27 Jan 2022 16:58:17 -0500 Subject: [PATCH 4/9] fix verb tense --- website/docs/cli/commands/plan.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 7a879a323..d36611f9a 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -155,8 +155,7 @@ the previous section, are also available with the same meanings on Terraform will choose a "replace" action instead. You can use this option if you have learned that one or more remote objects - has become degraded in some way. Add multiple `-replace` flags to the command to replace several objects at once. If you are using immutable infrastructure - patterns, you may wish to replace the malfunctioning objects with new objects that have the same configuration. + have become degraded in some way. Add multiple `-replace` flags to replace several objects at once. If you are using immutable infrastructure patterns, you may wish to replace the malfunctioning objects with new objects that have the same configuration. This option is allowed only in the normal planning mode, so this option is incompatible with the `-destroy` option. From f56c7c1c85fabdb9ddda02729516b5c785dadbc7 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 27 Jan 2022 17:05:45 -0500 Subject: [PATCH 5/9] Make language in callouts more user friendly --- website/docs/cli/commands/apply.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index d6a4c2994..3b7d148db 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -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 `-auto-approve` option. --> **Tip:** When performing its own plan, `terraform apply` supports all of the same -[planning modes](/cli/commands/plan#planning-modes) and -[planning options](/cli/commands/plan#planning-options) that `terraform plan` would -accept, so you can customize how Terraform will create the plan. +-> **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 options](/cli/commands/plan#planning-options) available for `terraform plan`. This lets you customize how Terraform will create the plan. ### Saved Plan Mode @@ -111,8 +109,9 @@ apply command executes and reports on the apply operation. [walks the graph](/internals/graph#walking-the-graph). Defaults to 10\. -- Planning modes and options available for -[`terraform plan`](/cli/commands/plan#planning-options) - Only available when you run `terraform apply` without a saved plan file. +- 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 [the `local` backend](/language/settings/backends/local) only, From 6e80276cc9dd11b42240c57e6441e852c92891fb Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 28 Jan 2022 14:44:56 -0500 Subject: [PATCH 6/9] Remove invisible space --- website/docs/cli/commands/taint.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index 40ac0526d..b37a34b3e 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -16,7 +16,7 @@ propose to replace it in the next plan you create. ## 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. +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. ``` $ terraform apply -replace="aws_instance.example[0]" From a2f83ef7b61e14d858c87f0b25b769852a6c86a3 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 28 Jan 2022 15:28:35 -0500 Subject: [PATCH 7/9] Try to fix wording so it's clearer and more cohesive --- website/docs/cli/commands/plan.mdx | 44 ++++++++---------------------- 1 file changed, 11 insertions(+), 33 deletions(-) diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index d36611f9a..e59297981 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -138,46 +138,25 @@ the previous section, are also available with the same meanings on `terraform apply`. - `-refresh=false` - Disables the default behavior of synchronizing the - Terraform state with remote objects before checking for configuration changes. + 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. - This option can potentially make the planning operation faster by reducing - 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. + -> **Note:** You cannot use `refresh=false` in "refresh only" planning mode, because it would effectively disable the entirety of the planning operation. - 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 + 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. Use this option multiple times to replace several objects at once. -- `-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 one or more remote objects - have become degraded in some way. Add multiple `-replace` flags to replace several objects at once. If you are using immutable infrastructure patterns, you may wish to replace the malfunctioning objects with new objects that have 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). + -> **Note:** 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. - `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only on resource instances which match the given address and on any objects that - those instances depend on. - - This command is for exceptional use only. See - [Resource Targeting](#resource-targeting) - below for more information. + those instances depend on. This command is for exceptional use only. Refer to + [Resource Targeting](#resource-targeting) for more information. - `-var 'NAME=VALUE'` - Sets a value for a single [input variable](/language/values/variables) declared in the root module of the configuration. Use this option multiple times to set - more than one variable. For more information see - [Input Variables on the Command Line](#input-variables-on-the-command-line), - below. + more than one variable. Refer to + [Input Variables on the Command Line](#input-variables-on-the-command-line) for more information. - `-var-file=FILENAME` - Sets values for potentially many [input variables](/language/values/variables) declared in the @@ -186,9 +165,8 @@ the previous section, are also available with the same meanings on 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 -module, aside from the `-var` and `-var-file` options. For more information, -see -[Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables). +module, aside from the `-var` and `-var-file` options. Refer to +[Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables) for more information. ### Input Variables on the Command Line From d14e04bf36139721284aa03e970916126f516915 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Mon, 31 Jan 2022 14:03:03 -0500 Subject: [PATCH 8/9] Fix notes according to PR feedback --- website/docs/cli/commands/plan.mdx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index e59297981..23c758120 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -138,19 +138,16 @@ the previous section, are also available with the same meanings on `terraform apply`. - `-refresh=false` - Disables the default behavior of synchronizing the - 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. - - -> **Note:** You cannot use `refresh=false` in "refresh only" planning mode, because it would effectively disable the entirety of the planning operation. + 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. - `-replace=ADDRESS` - Instructs Terraform to plan to replace the - 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. Use this option multiple times to replace several objects at once. - - -> **Note:** 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. + 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. - `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only on resource instances which match the given address and on any objects that - those instances depend on. This command is for exceptional use only. Refer to - [Resource Targeting](#resource-targeting) for more information. + those instances depend on. + + -> **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. - `-var 'NAME=VALUE'` - Sets a value for a single [input variable](/language/values/variables) declared in the From a794c80e0d6e9c0aa390f261b745c79cdad746eb Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Mon, 31 Jan 2022 14:17:36 -0500 Subject: [PATCH 9/9] final nits --- website/docs/cli/commands/plan.mdx | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 23c758120..7ae1152bc 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -82,12 +82,9 @@ The remaining sections on this page describe the various options: ## Planning Modes -The section above described Terraform's default planning behavior, which is -intended for changing the remote system to match with changes you've made to -your configuration. - -Terraform has two alternative planning modes, each of which creates a plan with -a different intended outcome: +The previous section describes Terraform's default planning behavior, which +changes the remote system to match the changes you make to +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). * **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 @@ -127,18 +124,10 @@ and later. ## Planning Options -In addition to the planning _modes_ described above, there are also several -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 -incorporates the `terraform plan` command functionality and so the planning -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`. +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). - `-refresh=false` - Disables the default behavior of synchronizing the - 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. + 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. - `-replace=ADDRESS` - Instructs Terraform to plan to replace the 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.