From 6bed3008a5d993bd89b2dafa101ebcd9cbced5a0 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Wed, 7 Apr 2021 12:25:59 -0700 Subject: [PATCH] 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. --- website/docs/cli/commands/apply.html.md | 106 ++++--- website/docs/cli/commands/destroy.html.md | 43 ++- website/docs/cli/commands/plan.html.md | 291 +++++++++++++----- website/docs/cli/commands/refresh.html.md | 87 +++--- website/docs/cli/commands/taint.html.md | 103 ++----- website/docs/cli/commands/untaint.html.md | 71 +++-- .../cli/state/resource-addressing.html.md | 35 ++- 7 files changed, 430 insertions(+), 306 deletions(-) diff --git a/website/docs/cli/commands/apply.html.md b/website/docs/cli/commands/apply.html.md index 6b87bf6d9..f5454bb71 100644 --- a/website/docs/cli/commands/apply.html.md +++ b/website/docs/cli/commands/apply.html.md @@ -3,73 +3,88 @@ layout: "docs" page_title: "Command: apply" sidebar_current: "docs-commands-apply" description: |- - The `terraform apply` command is used to apply the changes required to reach the desired state of the configuration, or the pre-determined set of actions generated by a `terraform plan` execution plan. + The `terraform apply` command executes the actions proposed in a Terraform plan. --- # Command: apply > **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn. -The `terraform apply` command is used to apply the changes required -to reach the desired state of the configuration, or the pre-determined -set of actions generated by a `terraform plan` execution plan. +The `terraform apply` command executes the actions proposed in a Terraform +plan. + +The most straightforward way to use `terraform apply` is to run it without +any arguments at all, in which case it will automatically create a new +execution plan (as if you had run `terraform plan`) and then prompt you to +approve that plan, before taking the indicated actions. + +Another way to use `terraform apply` is to pass it the filename of a saved +plan file you created earlier with `terraform plan -out=...`, in which case +Terraform will apply the changes in the plan without any confirmation prompt. +This two-step workflow is primarily intended for when +[running Terraform in automation](https://learn.hashicorp.com/tutorials/terraform/automate-terraform?in=terraform/automation&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). ## Usage Usage: `terraform apply [options] [plan]` -By default, `apply` scans the current directory for the configuration -and applies the changes appropriately. However, you can optionally give the -path to a saved plan file that was previously created with -[`terraform plan`](plan.html). +The behavior of `terraform apply` differs significantly depending on whether +you pass it the filename of a previously-saved plan file. -If you don't give a plan file on the command line, `terraform apply` will -create a new plan automatically and then prompt for approval to apply it. If the -created plan does not include any changes to resources or to root module -output values then `terraform apply` will exit immediately, without prompting. +In the default case, with no saved plan file, `terraform apply` effectively +runs [`terraform plan`](./plan.html) internally itself in order to propose a +new plan. In that case, `terraform apply` supports all of the same +[Planning Modes](./plan.html#planning-modes) and +[Planning Options](./plan.html#planning-options) that `terraform plan` +would accept, so you can customize how Terraform will create the plan. +Terraform will prompt you to approve the plan before taking the described +actions, unless you override that prompt using the `-auto-approve` option. -The command-line flags are all optional. The list of available flags are: +If you pass the filename of a previously-saved plan file, none of the options +related to planning modes and planning options are supported, because Terraform +will instead use the options that you set on the earlier `terraform plan` call +that created the plan file. -* `-compact-warnings` - If Terraform produces any warnings that are not - accompanied by errors, show them in a more compact form that includes only - the summary messages. +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`](./plan.html). -* `-lock=true` - Lock the state file when locking is supported. +* `-auto-approve` - Skips interactive approval of plan before applying. This + option is ignored when you pass a previously-saved plan file, because + Terraform considers you passing the plan file as the approval and so + will never prompt in that case. -* `-lock-timeout=0s` - Duration to retry a state lock. +* `-compact-warnings` - Shows any warning messages in a compact form which + includes only the summary messages, unless the warnings are accompanied by + at least one error and thus the warning text might be useful context for + the errors. -* `-input=true` - Ask for input for variables if not directly set. +* `-input=false` - Disables all of Terraform's interactive prompts. Note that + this also prevents Terraform from prompting for interactive approval of a + plan, so Terraform will conservatively assume that you do not wish to + apply the plan, causing the operation to fail. If you wish to run Terraform + in a non-interactive context, see + [Running Terraform in Automation](https://learn.hashicorp.com/tutorials/terraform/automate-terraform?in=terraform/automation&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) for some + different approaches. -* `-auto-approve` - Skip interactive approval of plan before applying. +* `-lock=false` - Disables Terraform's default behavior of attempting to take + a read/write lock on the state for the duration of the operation. -* `-no-color` - Disables output with coloring. +* `-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. + +* `-no-color` - Disables terminal formatting sequences in the output. Use this + if you are running Terraform in a context where its output will be + rendered by a system that cannot interpret terminal formatting. * `-parallelism=n` - Limit the number of concurrent operation as Terraform [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to 10. -* `-refresh=true` - Update the state for each resource prior to planning - and applying. This has no effect if a plan file is given directly to - apply. - -* `-target=resource` - A [Resource - Address](/docs/cli/state/resource-addressing.html) to target. For more - information, see - [the targeting docs from `terraform plan`](/docs/cli/commands/plan.html#resource-targeting). - -* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag - can be set multiple times. Variable values are interpreted as - [literal expressions](/docs/language/expressions/types.html) in the - Terraform language, so list and map values can be specified via this flag. - -* `-var-file=foo` - Set variables in the Terraform configuration from - a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If - a `terraform.tfvars` or any `.auto.tfvars` files are present in the current - directory, they will be automatically loaded. `terraform.tfvars` is loaded - first and the `.auto.tfvars` files after in alphabetical order. Any files - specified by `-var-file` override any values set automatically from files in - the working directory. This flag can be used multiple times. - For configurations using [the `local` backend](/docs/language/settings/backends/local.html) only, `terraform apply` also accepts the legacy options @@ -81,9 +96,8 @@ Terraform v0.13 and earlier also accepted a directory path in place of the plan file argument to `terraform apply`, in which case Terraform would use that directory as the root module instead of the current working directory. -That usage is still supported in Terraform v0.14, but is now deprecated and we -plan to remove it in Terraform v0.15. If your workflow relies on overriding -the root module directory, use +That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. +If your workflow relies on overriding the root module directory, use [the `-chdir` global option](./#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the diff --git a/website/docs/cli/commands/destroy.html.md b/website/docs/cli/commands/destroy.html.md index dd490aa63..fc82a4550 100644 --- a/website/docs/cli/commands/destroy.html.md +++ b/website/docs/cli/commands/destroy.html.md @@ -3,29 +3,46 @@ layout: "docs" page_title: "Command: destroy" sidebar_current: "docs-commands-destroy" description: |- - The `terraform destroy` command is used to destroy the Terraform-managed infrastructure. + The `terraform destroy` command is a convenient way to destroy all objects + managed by a particular Terraform configuration. --- # Command: destroy -The `terraform destroy` command is used to destroy the Terraform-managed -infrastructure. +The `terraform destroy` command is a convenient way to destroy all remote +objects managed by a particular Terraform configuration. + +While you will typically not want to destroy long-lived objects in a production +environment, Terraform is sometimes used to manage ephemeral infrastructure +for development purposes, in which case you can use `terraform destroy` to +conveniently clean up all of those temporary objects once you are finished +with your work. ## Usage Usage: `terraform destroy [options]` -Infrastructure managed by Terraform will be destroyed. This will ask for -confirmation before destroying. +This command is just a convenience alias for the following command: -This command accepts all the arguments and options that the [apply -command](/docs/cli/commands/apply.html) accepts, with the exception of a plan file -argument. +``` +terraform apply -destroy +``` -If `-auto-approve` is set, then the destroy confirmation will not be shown. +For that reason, this command accepts most of the options that +[`terraform apply`](./apply.html) accepts, although it does +not accept a plan file argument and forces the selection of the "destroy" +planning mode. -The `-target` flag, instead of affecting "dependencies" will instead also -destroy any resources that _depend on_ the target(s) specified. For more information, see [the targeting docs from `terraform plan`](/docs/cli/commands/plan.html#resource-targeting). +You can also create a speculative destroy plan, to see what the effect of +destroying would be, by running the following command: -The behavior of any `terraform destroy` command can be previewed at any time -with an equivalent `terraform plan -destroy` command. +``` +terraform plan -destroy +``` + +This will run [`terraform plan`](./plan.html) in _destroy_ mode, showing +you the proposed destroy changes without executing them. + +-> **Note:** The `-destroy` option to `terraform apply` exists only in +Terraform v1.0 and later. For earlier versions, you _must_ use +`terraform destroy` to get the effect of `terraform apply -destroy`. diff --git a/website/docs/cli/commands/plan.html.md b/website/docs/cli/commands/plan.html.md index b9f04e84b..36fb5b361 100644 --- a/website/docs/cli/commands/plan.html.md +++ b/website/docs/cli/commands/plan.html.md @@ -3,30 +3,55 @@ layout: "docs" page_title: "Command: plan" sidebar_current: "docs-commands-plan" description: |- - The `terraform plan` command is used to create an execution plan. Terraform performs a refresh, unless explicitly disabled, and then determines what actions are necessary to achieve the desired state specified in the configuration files. The plan can be saved using `-out`, and then provided to `terraform apply` to ensure only the pre-planned actions are executed. + The terraform plan command creates an execution plan. --- # Command: plan > **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn. -The `terraform plan` command is used to create an execution plan. Terraform -performs a refresh, unless explicitly disabled, and then determines what -actions are necessary to achieve the desired state specified in the -configuration files. +The `terraform plan` command creates an execution plan. By default, creating +a plan consists of: -This command is a convenient way to check whether the execution plan for a -set of changes matches your expectations without making any changes to -real resources or to the state. For example, `terraform plan` might be run -before committing a change to version control, to create confidence that it -will behave as expected. +* Reading the current state of any already-existing remote objects to make sure + that the Terraform state is up-to-date. +* Comparing the current configuration to the prior state and noting any + differences. +* Proposing a set of change actions that should, if applied, make the remote + objects match the configuration. -The optional `-out` argument can be used to save the generated plan to a file -for later execution with `terraform apply`, which can be useful when +The plan command alone will not actually carry out the proposed changes, and +so you can use this command to check whether the proposed changes match what +you expected before you apply the changes or share your changes with your +team for broader review. + +If Terraform detects that no changes are needed to resource instances or to +root module output values, `terraform plan` will report that no actions need +to be taken. + +If you are using Terraform directly in an interactive terminal and you expect +to apply the changes Terraform proposes, you can alternatively run +[`terraform apply`](./apply.html) directly. By default, the "apply" command +automatically generates a new plan and prompts for you to approve it. + +You can use the optional `-out=FILE` option to save the generated plan to a +file on disk, which you can later execute by passing the file to +[`terraform apply`](./apply.html) as an extra argument. This two-step workflow +is primarily intended for when [running Terraform in automation](https://learn.hashicorp.com/tutorials/terraform/automate-terraform?in=terraform/automation&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). -If Terraform detects no changes to resource or to root module output values, -`terraform plan` will indicate that no changes are required. +If you run `terraform plan` without the `-out=FILE` option then it will create +a _speculative plan_, which is a description of a the effect of the plan but +without any intent to actually apply it. + +In teams that use a version control and code review workflow for making changes +to real infrastructure, developers can use speculative plans to verify the +effect of their changes before submitting them for code review. However, it's +important to consider that other changes made to the target system in the +meantime might cause the final effect of a configuration change to be different +than what an earlier speculative plan indicated, so you should always re-check +the final non-speculative plan before applying to make sure that it still +matches your intent. ## Usage @@ -35,80 +60,133 @@ Usage: `terraform plan [options]` The `plan` subcommand looks in the current working directory for the root module configuration. -The available options are: +Because the plan command is one of the main commands of Terraform, it has +a variety of different options, described in the following sections. However, +most of the time you should not need to set any of these options, because +a Terraform configuration should typically be designed to work with no special +additional options for routine work. -* `-compact-warnings` - If Terraform produces any warnings that are not - accompanied by errors, show them in a more compact form that includes only - the summary messages. +The remaining sections on this page describe the various options: -* `-destroy` - If set, generates a plan to destroy all the known resources. +* **[Planning Modes](#planning-modes)**: There are some special alternative + planning modes that you can use for some special situations where your goal + is not just to change the remote system to match your configuration. +* **[Planning Options](#planning-options)**: Alongside the special planning + modes, there are also some options you can set in order to customize the + planning process for unusual needs. + * **[Resource Targeting](#resource-targeting)** is one particular + special planning option that has some important caveats associated + with it. +* **[Other Options](#other-options)**: These change the behavior of the planning + command itself, rather than customizing the content of the generated plan. -* `-detailed-exitcode` - Return a detailed exit code when the command exits. - When provided, this argument changes the exit codes and their meanings to - provide more granular information about what the resulting plan contains: - * 0 = Succeeded with empty diff (no changes) - * 1 = Error - * 2 = Succeeded with non-empty diff (changes present) +## Planning Modes -* `-input=true` - Ask for input for variables if not directly set. +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. -* `-lock=true` - Lock the state file when locking is supported. +Terraform has one alternative planning mode, which creates a plan with +a different intended outcome: -* `-lock-timeout=0s` - Duration to retry a state lock. +* **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 + for situations like transient development environments, where the managed + objects cease to be useful once the development task is complete. -* `-no-color` - Disables output with coloring. + Activate destroy mode using the `-destroy` command line option. -* `-out=path` - The path to save the generated execution plan. This plan - can then be used with `terraform apply` to be certain that only the - changes shown in this plan are applied. Read the warning on saved - plans below. +In situations where we need to discuss the default planning mode that Terraform +uses when none of the alternative modes are selected, we refer to it as +"Normal mode". Because these alternative modes are for specialized situations +only, some other Terraform documentation only discusses the normal planning +mode. -* `-parallelism=n` - Limit the number of concurrent operation as Terraform - [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults - to 10. +The planning modes are all mutually-exclusive, so activating any non-default +planning mode disables the "normal" planning mode, and you can't use more than +one alternative mode at the same time. -* `-refresh=true` - Update the state prior to checking for differences. +-> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is +supported only by the `terraform plan` command, and not by the +`terraform apply` command. To create and apply a plan in destroy mode in +earlier versions you must run [`terraform destroy`](./destroy.html). -* `-target=resource` - A [Resource - Address](/docs/cli/state/resource-addressing.html) to target. This flag can - be used multiple times. See below for more information. +## Planning Options -* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag - can be set multiple times. Variable values are interpreted as - [literal expressions](/docs/language/expressions/types.html) in the - Terraform language, so list and map values can be specified via this flag. +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. -* `-var-file=foo` - Set variables in the Terraform configuration from - a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If - a `terraform.tfvars` or any `.auto.tfvars` files are present in the current - directory, they will be automatically loaded. `terraform.tfvars` is loaded - first and the `.auto.tfvars` files after in alphabetical order. Any files - specified by `-var-file` override any values set automatically from files in - the working directory. This flag can be used multiple times. +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`. -For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, -`terraform plan` accepts the legacy command line option -[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). +* `-refresh=false` - Disables the default behavior of synchronizing the + Terraform state with remote objects before checking for configuration changes. -## Resource Targeting + 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. + + 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. + +* `-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. + +* `-var 'NAME=VALUE` - Sets a value for a single + [input variable](/docs/language/values/variables.html) declared in the + root module of the configuration. Use this option multiple times to set + more than one variable. + +* `-var-file=FILENAME` - Sets values for potentially many + [input variables](/docs/language/values/variables.html) declared in the + root module of the configuration, using definitions from a + ["tfvars" file](/docs/language/values/variables.html#variable-definitions-tfvars-files). + 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](/docs/language/values/variables.html#assigning-values-to-root-module-variables). + +### Resource Targeting > **Hands-on:** Try the [Target resources](https://learn.hashicorp.com/tutorials/terraform/resource-targeting?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. -The `-target` option can be used to focus Terraform's attention on only a +You can use the `-target` option to focus Terraform's attention on only a subset of resources. -[Resource Address](/docs/cli/state/resource-addressing.html) syntax is used -to specify the constraint. The resource address is interpreted as follows: +You can use [resource address syntax](/docs/cli/state/resource-addressing.html) +to specify the constraint. Terraform interprets the resource address as follows: -* If the given address has a _resource spec_, only the specified resource - is targeted. If the named resource uses `count` and no explicit index - is specified in the address (i.e. aws_instance.example[3]), all of the instances sharing the given - resource name are targeted. +* If the given address identifies one specific resource instance, Terraform + will select that instance alone. For resources with either `count` or + `for_each` set, a resource instance address must include the instance index + part, like `aws_instance.example[0]`. -* If the given address _does not_ have a resource spec, and instead just - specifies a module path, the target applies to all resources in the - specified module _and_ all of the descendent modules of the specified - module. +* If the given address identifies a resource as a whole, Terraform will select + all of the instances of that resource. For resources with either `count` + or `for_each` set, this means selecting _all_ instance indexes currently + associated with that resource. For single-instance resources (without + either `count` or `for_each`), the resource address and the resource instance + address are identical, so this possibility does not apply. + +* If the given address identifies an entire module instance, Terraform will + select all instances of all resources that belong to that module instance + and all of its child module instances. + +Once Terraform has selected one or more resource instances that you've directly +targeted, it will also then extend the selection to include all other objects +that those selections depend on either directly or indirectly. This targeting capability is provided for exceptional circumstances, such as recovering from mistakes or working around Terraform limitations. It @@ -124,28 +202,81 @@ information about resources created in other configurations, allowing a complex system architecture to be broken down into more manageable parts that can be updated independently. -## Security Warning +## Other Options -Saved plan files (with the `-out` flag) encode the configuration, -state, diff, and _variables_. Variables are often used to store secrets. -Therefore, the plan file can potentially store secrets. +The `terraform plan` command also has some other options that are related to +the input and output of the planning command, rather than customizing what +sort of plan Terraform will create. These commands are not necessarily also +available on `terraform apply`, unless otherwise stated in the documentation +for that command. -Terraform itself does not encrypt the plan file. It is highly -recommended to encrypt the plan file if you intend to transfer it -or keep it at rest for an extended period of time. +The available options are: -Future versions of Terraform will make plan files more -secure. +* `-compact-warnings` - Shows any warning messages in a compact form which + includes only the summary messages, unless the warnings are accompanied by + at least one error and thus the warning text might be useful context for + the errors. -## Passing a Different Configuration Directory +* `-detailed-exitcode` - Returns a detailed exit code when the command exits. + When provided, this argument changes the exit codes and their meanings to + provide more granular information about what the resulting plan contains: + * 0 = Succeeded with empty diff (no changes) + * 1 = Error + * 2 = Succeeded with non-empty diff (changes present) + +* `-input=false` - Disables Terraform's default behavior of prompting for + input for root module input variables that have not otherwise been assigned + a value. This option is particular useful when running Terraform in + non-interactive automation systems. + +* `-lock=false` - Disables Terraform's default behavior of attempting to take + a read/write lock on the state for the duration of the operation. + +* `-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. + +* `-no-color` - Disables terminal formatting sequences in the output. Use this + if you are running Terraform in a context where its output will be + rendered by a system that cannot interpret terminal formatting. + +* `-out=FILENAME` - Writes the generated plan to the given filename in an + opaque file format that you can later pass to `terraform apply` to execute + the planned changes, and to some other Terraform commands that can work with + saved plan files. + + Terraform will allow any filename for the plan file, but a typical + convention is to name it `tfplan`. **Do not** name the file with a suffix + that Terraform recognizes as another file format; if you use a `.tf` suffix + then Terraform will try to interpret the file as a configuration source + file, which will then cause syntax errors for subsequent commands. + + The generated file is not in any standard format intended for consumption + by other software, but the file _does_ contain your full configuration, + all of the values associated with planned changes, and all of the plan + options including the input variables. If your plan includes any sort of + sensitive data, even if obscured in Terraform's terminal output, it will + be saved in cleartext in the plan file. You should therefore treat any + saved plan files as potentially-sensitive artifacts. + +* `-parallelism=n` - Limit the number of concurrent operation as Terraform + [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults + to 10. + +For configurations using +[the `local` backend](/docs/language/settings/backends/local.html) only, +`terraform plan` accepts the legacy command line option +[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). + +### Passing a Different Configuration Directory Terraform v0.13 and earlier accepted an additional positional argument giving a directory path, in which case Terraform would use that directory as the root module instead of the current working directory. -That usage is still supported in Terraform v0.14, but is now deprecated and we -plan to remove it in Terraform v0.15. If your workflow relies on overriding -the root module directory, use +That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. +If your workflow relies on overriding the root module directory, use [the `-chdir` global option](./#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the diff --git a/website/docs/cli/commands/refresh.html.md b/website/docs/cli/commands/refresh.html.md index 7aa1c9285..a171162eb 100644 --- a/website/docs/cli/commands/refresh.html.md +++ b/website/docs/cli/commands/refresh.html.md @@ -3,61 +3,66 @@ layout: "docs" page_title: "Command: refresh" sidebar_current: "docs-commands-refresh" description: |- - The `terraform refresh` command is used to reconcile the state Terraform knows about (via its state file) with the real-world infrastructure. This can be used to detect any drift from the last-known state, and to update the state file. + The `terraform refresh` command reads the current settings from all managed + remote objects and updates the Terraform state to match. --- # Command: refresh -The `terraform refresh` command is used to reconcile the state Terraform -knows about (via its state file) with the real-world infrastructure. -This can be used to detect any drift from the last-known state, and to -update the state file. +The `terraform refresh` command reads the current settings from all managed +remote objects and updates the Terraform state to match. -This does not modify infrastructure, but does modify the state file. -If the state is changed, this may cause changes to occur during the next -plan or apply. +~> *Warning:* This command is deprecated, because its default behavior is +unsafe if you have misconfigured credentials for any of your providers. +See below for more information and recommended alternatives. + +This won't modify your real remote objects, but it will modify the +[the Terraform state](/docs/language/state/). + +You shouldn't typically need to use this command, because Terraform +automatically performs the same refreshing actions as a part of creating +a plan in both the +[`terraform plan`](./plan.html) +and +[`terraform apply`](./apply.html) +commands. This command is here primarily for backward compatibility, but +we don't recommend using it because it provides no opportunity to review +the effects of the operation before updating the state. ## Usage Usage: `terraform refresh [options]` -The `terraform refresh` command accepts the following options: +This command is effectively an alias for the following command: -* `-compact-warnings` - If Terraform produces any warnings that are not - accompanied by errors, show them in a more compact form that includes only - the summary messages. +``` +terraform apply -refresh-only -auto-approve +``` -* `-input=true` - Ask for input for variables if not directly set. +Consequently, it supports all of the same options as +[`terraform apply`](./apply.html) except that it does not accept a saved +plan file, it doesn't allow selecting a planning mode other than "refresh only", +and `-auto-approve` is always enabled. -* `-lock=true` - Lock the state file when locking is supported. +Automatically applying the effect of a refresh is risky, because if you have +misconfigured credentials for one or more providers then the provider may +be misled into thinking that all of the managed objects have been deleted, +and thus remove all of the tracked objects without any confirmation prompt. -* `-lock-timeout=0s` - Duration to retry a state lock. +Instead, we recommend using the following command in order to get the same +effect but with the opportunity to review the the changes that Terraform has +detected before committing them to the state: -* `-no-color` - If specified, output won't contain any color. +``` +terraform apply -refresh-only +``` -* `-parallelism=n` - Limit the number of concurrent operation as Terraform - [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults - to 10. +This alternative command will present an interactive prompt for you to confirm +the detected changes. -* `-target=resource` - A [Resource - Address](/docs/cli/state/resource-addressing.html) to target. Operation will - be limited to this resource and its dependencies. This flag can be used - multiple times. - -* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag - can be set multiple times. Variable values are interpreted as - [literal expressions](/docs/language/expressions/types.html) in the - Terraform language, so list and map values can be specified via this flag. - -* `-var-file=foo` - Set variables in the Terraform configuration from - a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If - a `terraform.tfvars` or any `.auto.tfvars` files are present in the current - directory, they will be automatically loaded. `terraform.tfvars` is loaded - first and the `.auto.tfvars` files after in alphabetical order. Any files - specified by `-var-file` override any values set automatically from files in - the working directory. This flag can be used multiple times. - -For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, -`terraform refresh` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). +The `-refresh-only` option for `terraform plan` and `terraform apply` was +introduced in Terraform v1.0. For prior versions you must use +`terraform refresh` directly if you need this behavior, while taking into +account the warnings above. Wherever possible, avoid using `terraform refresh` +explicitly and instead rely on Terraform's behavior of automatically refreshing +existing objects as part of creating a normal plan. diff --git a/website/docs/cli/commands/taint.html.md b/website/docs/cli/commands/taint.html.md index 9ef2982fa..b3b3ccaa7 100644 --- a/website/docs/cli/commands/taint.html.md +++ b/website/docs/cli/commands/taint.html.md @@ -3,33 +3,16 @@ layout: "docs" page_title: "Command: taint" sidebar_current: "docs-commands-taint" description: |- - The `terraform taint` command manually marks a Terraform-managed resource as tainted, forcing it to be destroyed and recreated on the next apply. + The `terraform taint` command informs Terraform that a particular object + is damaged or degraded. --- # Command: taint -The `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](/docs/cli/commands/plan.html) will show that the resource will -be destroyed and recreated and the next -[apply](/docs/cli/commands/apply.html) 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](/docs/cli/commands/plan.html) will show this if this is -the case. +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. ## Usage @@ -42,74 +25,30 @@ as shown in the output from other commands, such as: * `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 are not interpreted by your shell) + * `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` -The command-line flags are all optional. The list of available flags are: +This command accepts the following options: * `-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. + 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. -* `-backup=path` - Path to the backup file. Defaults to `-state-out` with - the ".backup" extension. Disabled by setting to "-". +* `-lock=false` - Disables Terraform's default behavior of attempting to take + a read/write lock on the state for the duration of the operation. -* `-lock=true` - Lock the state file when locking is supported. - -* `-lock-timeout=0s` - Duration to retry a state lock. - -* `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. - -* `-state-out=path` - Path to write updated state file. By default, the - `-state` path will be used. Ignored when - [remote state](/docs/language/state/remote.html) is used. +* `-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. * `-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[9]" -Resource instance module.couchbase.aws_instance.cb_node[9] has been marked as tainted. -``` - -Although we recommend that most configurations use only one level of nesting -and employ [module composition](/docs/language/modules/develop/composition.html), 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[2]" -Resource instance module.child.module.grandchild.aws_instance.example[2] has been marked as tainted. -``` +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). diff --git a/website/docs/cli/commands/untaint.html.md b/website/docs/cli/commands/untaint.html.md index 69b414982..835ed6223 100644 --- a/website/docs/cli/commands/untaint.html.md +++ b/website/docs/cli/commands/untaint.html.md @@ -3,56 +3,63 @@ layout: "docs" page_title: "Command: untaint" sidebar_current: "docs-commands-untaint" description: |- - The `terraform untaint` command manually unmarks a Terraform-managed resource as tainted, restoring it as the primary instance in the state. + The `terraform untaint` command tells Terraform that an object is functioning + correctly, even though its creation failed or it was previously manually + marked as degraded. --- # Command: untaint -The `terraform untaint` command manually unmarks a Terraform-managed resource -as tainted, restoring it as the primary instance in the state. This reverses -either a manual `terraform taint` or the result of provisioners failing on a -resource. +Terraform has a marker called "tainted" which it uses to track that an object +might be damaged and so a future Terraform plan ought to replace it. -This command _will not_ modify infrastructure, but does modify the state file -in order to unmark a resource as tainted. +Terraform automatically marks an object as "tainted" if an error occurs during +a multi-step "create" action, because Terraform can't be sure that the object +was left in a fully-functional state. -~> **NOTE on Tainted Indexes:** In certain edge cases, more than one tainted -instance can be present for a single resource. When this happens, you need to specify the index after the resources, e.g. `my-resource-example[2]`. You can use the `terraform show` command to inspect the state and -determine which index holds the instance you'd like to restore. In the vast -majority of cases, there will only be one tainted instance, and the `-index` -flag can be omitted. +You can also manually mark an object as "tainted" using the deprecated command +[`terraform taint`](./taint.html), although we no longer recommend that +workflow. + +If Terraform currently considers a particular object as tainted but you've +determined that it's actually functioning correctly and need _not_ be replaced, +you can use `terraform untaint` to remove the taint marker from that object. + +This command _will not_ modify any real remote objects, but will modify the +state in order to remove the tainted status. ## Usage -Usage: `terraform untaint [options] name` +Usage: `terraform untaint [options] address` -The `name` argument is the name of the resource to mark as untainted. The -format of this argument is `TYPE.NAME`, such as `aws_instance.foo`. +The `address` argument is a [resource address](/docs/cli/state/resource-addressing.html) +identifying a particular resource instance which is currently tainted. -The command-line flags are all optional (with the exception of `-index` in -certain cases, see above note). The list of available flags are: +This command also accepts the following options: * `-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. + 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. -* `-backup=path` - Path to the backup file. Defaults to `-state-out` with - the ".backup" extension. Disabled by setting to "-". +* `-lock=false` - Disables Terraform's default behavior of attempting to take + a read/write lock on the state for the duration of the operation. -* `-lock=true` - Lock the state file when locking is supported. +* `-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. -* `-lock-timeout=0s` - Duration to retry a state lock. - -* `-no-color` - Disables output with coloring - -* `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. - -* `-state-out=path` - Path to write updated state file. By default, the - `-state` path will be used. Ignored when - [remote state](/docs/language/state/remote.html) is used. +* `-no-color` - Disables terminal formatting sequences in the output. Use this + if you are running Terraform in a context where its output will be + rendered by a system that cannot interpret terminal formatting. * `-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. + +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). diff --git a/website/docs/cli/state/resource-addressing.html.md b/website/docs/cli/state/resource-addressing.html.md index 51ff80c97..72b987a83 100644 --- a/website/docs/cli/state/resource-addressing.html.md +++ b/website/docs/cli/state/resource-addressing.html.md @@ -3,19 +3,27 @@ layout: "docs" page_title: "Internals: Resource Address" sidebar_current: "docs-internals-resource-addressing" description: |- - Resource addressing is used to target specific resources in a larger - infrastructure. + A resource address is a string that identifies zero or more resource + instances in your overall configuration. --- # Resource Addressing -A __Resource Address__ is a string that references a specific resource in a -larger infrastructure. An address is made up of two parts: +A _resource address_ is a string that identifies zero or more resource +instances in your overall configuration. + +An address is made up of two parts: ``` [module path][resource spec] ``` +In some contexts Terraform might allow for an incomplete resource address that +only refers to a module as a whole, or that omits the index for a +multi-instance resource. In those cases, the meaning depends on the context, +so you'll need to refer to the documentation for the specific feature you +are using which parses resource addresses. + ## Module path A module path addresses a module within the tree of modules. It takes the form: @@ -27,8 +35,9 @@ module.module_name[module index] * `module` - Module keyword indicating a child module (non-root). Multiple `module` keywords in a path indicate nesting. * `module_name` - User-defined name of the module. - * `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources) into a - module with multiple instances, surrounded by square brace characters (`[` and `]`). + * `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources) + to select an instance from a module call that has multiple instances, + surrounded by square bracket characters (`[` and `]`). An address without a resource spec, i.e. `module.foo` applies to every resource within the module if a single module, or all instances of a module if a module has multiple instances. @@ -43,25 +52,27 @@ An example of the `module` keyword delineating between two modules that have mul module.foo[0].module.bar["a"] ``` --> Module index only applies to modules in Terraform v0.13 or later, as in earlier +-> Module index only applies to modules in Terraform v0.13 or later. In earlier versions of Terraform, a module could not have multiple instances. ## Resource spec -A resource spec addresses a specific resource in the config. It takes the form: +A resource spec addresses a specific resource instance in the selected module. +It has the following syntax: ``` -resource_type.resource_name[resource index] +resource_type.resource_name[instance index] ``` * `resource_type` - Type of the resource being addressed. * `resource_name` - User-defined name of the resource. - * `[resource index]` - (Optional) [Index](#index-values-for-modules-and-resources) - into a resource with multiple instances, surrounded by square brace characters (`[` and `]`). + * `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources) + to select an instance from a resource that has multiple instances, + surrounded by square bracket characters (`[` and `]`). -> In Terraform v0.12 and later, a resource spec without a module path prefix matches only resources in the root module. In earlier versions, a resource spec -without a module path prefix will match resources with the same type and name +without a module path prefix would match resources with the same type and name in any descendent module. ## Index values for Modules and Resources