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

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.
This commit is contained in:
Martin Atkins 2021-04-07 12:25:59 -07:00
parent 95b86bf7ad
commit 6bed3008a5
7 changed files with 430 additions and 306 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
website/docs/cli/commands/apply.html.md
View File

@ -3,73 +3,88 @@ layout: "docs"
page_title: "Command: apply" page_title: "Command: apply"
sidebar_current: "docs-commands-apply" sidebar_current: "docs-commands-apply"
description: |- 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 # 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. > **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 The `terraform apply` command executes the actions proposed in a Terraform
to reach the desired state of the configuration, or the pre-determined plan.
set of actions generated by a `terraform plan` execution 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
Usage: `terraform apply [options] [plan]` Usage: `terraform apply [options] [plan]`
By default, `apply` scans the current directory for the configuration The behavior of `terraform apply` differs significantly depending on whether
and applies the changes appropriately. However, you can optionally give the you pass it the filename of a previously-saved plan file.
path to a saved plan file that was previously created with
[`terraform plan`](plan.html).
If you don't give a plan file on the command line, `terraform apply` will In the default case, with no saved plan file, `terraform apply` effectively
create a new plan automatically and then prompt for approval to apply it. If the runs [`terraform plan`](./plan.html) internally itself in order to propose a
created plan does not include any changes to resources or to root module new plan. In that case, `terraform apply` supports all of the same
output values then `terraform apply` will exit immediately, without prompting. [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 The following options allow you to change various details about how the
accompanied by errors, show them in a more compact form that includes only apply command executes and reports on the apply operation. If you are running
the summary messages. `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 * `-parallelism=n` - Limit the number of concurrent operation as Terraform
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to
10. 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 For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform apply` also accepts the legacy options `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 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 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 That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15.
plan to remove it in Terraform v0.15. If your workflow relies on overriding If your workflow relies on overriding the root module directory, use
the root module directory, use
[the `-chdir` global option](./#switching-working-directory-with-chdir) [the `-chdir` global option](./#switching-working-directory-with-chdir)
instead, which works across all commands and makes Terraform consistently look 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 in the given directory for all files it would normally read or write in the

43
website/docs/cli/commands/destroy.html.md
View File

@ -3,29 +3,46 @@ layout: "docs"
page_title: "Command: destroy" page_title: "Command: destroy"
sidebar_current: "docs-commands-destroy" sidebar_current: "docs-commands-destroy"
description: |- 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 # Command: destroy
The `terraform destroy` command is used to destroy the Terraform-managed The `terraform destroy` command is a convenient way to destroy all remote
infrastructure. 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
Usage: `terraform destroy [options]` Usage: `terraform destroy [options]`
Infrastructure managed by Terraform will be destroyed. This will ask for This command is just a convenience alias for the following command:
confirmation before destroying.
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 terraform apply -destroy
argument. ```
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 You can also create a speculative destroy plan, to see what the effect of
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). 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`.

291
website/docs/cli/commands/plan.html.md
View File

@ -3,30 +3,55 @@ layout: "docs"
page_title: "Command: plan" page_title: "Command: plan"
sidebar_current: "docs-commands-plan" sidebar_current: "docs-commands-plan"
description: |- 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 # 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. > **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 The `terraform plan` command creates an execution plan. By default, creating
performs a refresh, unless explicitly disabled, and then determines what a plan consists of:
actions are necessary to achieve the desired state specified in the
configuration files.
This command is a convenient way to check whether the execution plan for a * Reading the current state of any already-existing remote objects to make sure
set of changes matches your expectations without making any changes to that the Terraform state is up-to-date.
real resources or to the state. For example, `terraform plan` might be run * Comparing the current configuration to the prior state and noting any
before committing a change to version control, to create confidence that it differences.
will behave as expected. * 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 The plan command alone will not actually carry out the proposed changes, and
for later execution with `terraform apply`, which can be useful when 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). [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, If you run `terraform plan` without the `-out=FILE` option then it will create
`terraform plan` will indicate that no changes are required. 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 ## Usage
@ -35,80 +60,133 @@ Usage: `terraform plan [options]`
The `plan` subcommand looks in the current working directory for the root module The `plan` subcommand looks in the current working directory for the root module
configuration. 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 The remaining sections on this page describe the various options:
accompanied by errors, show them in a more compact form that includes only
the summary messages.
* `-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. ## Planning Modes
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=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 In situations where we need to discuss the default planning mode that Terraform
can then be used with `terraform apply` to be certain that only the uses when none of the alternative modes are selected, we refer to it as
changes shown in this plan are applied. Read the warning on saved "Normal mode". Because these alternative modes are for specialized situations
plans below. only, some other Terraform documentation only discusses the normal planning
mode.
* `-parallelism=n` - Limit the number of concurrent operation as Terraform The planning modes are all mutually-exclusive, so activating any non-default
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults planning mode disables the "normal" planning mode, and you can't use more than
to 10. 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 ## Planning Options
Address](/docs/cli/state/resource-addressing.html) to target. This flag can
be used multiple times. See below for more information.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag In addition to the planning _modes_ described above, there are also several
can be set multiple times. Variable values are interpreted as additional options that can modify details of the behavior of the planning
[literal expressions](/docs/language/expressions/types.html) in the step.
Terraform language, so list and map values can be specified via this flag.
* `-var-file=foo` - Set variables in the Terraform configuration from When you use `terraform apply` without passing it a saved plan file, it
a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If incorporates the `terraform plan` command functionality and so the planning
a `terraform.tfvars` or any `.auto.tfvars` files are present in the current options in this section, along with the planning mode selection options in
directory, they will be automatically loaded. `terraform.tfvars` is loaded the previous section, are also available with the same meanings on
first and the `.auto.tfvars` files after in alphabetical order. Any files `terraform apply`.
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 * `-refresh=false` - Disables the default behavior of synchronizing the
[the `local` backend](/docs/language/settings/backends/local.html) only, Terraform state with remote objects before checking for configuration changes.
`terraform plan` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local.html#command-line-arguments).
## 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. > **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. subset of resources.
[Resource Address](/docs/cli/state/resource-addressing.html) syntax is used You can use [resource address syntax](/docs/cli/state/resource-addressing.html)
to specify the constraint. The resource address is interpreted as follows: to specify the constraint. Terraform interprets the resource address as follows:
* If the given address has a _resource spec_, only the specified resource * If the given address identifies one specific resource instance, Terraform
is targeted. If the named resource uses `count` and no explicit index will select that instance alone. For resources with either `count` or
is specified in the address (i.e. aws_instance.example[3]), all of the instances sharing the given `for_each` set, a resource instance address must include the instance index
resource name are targeted. part, like `aws_instance.example[0]`.
* If the given address _does not_ have a resource spec, and instead just * If the given address identifies a resource as a whole, Terraform will select
specifies a module path, the target applies to all resources in the all of the instances of that resource. For resources with either `count`
specified module _and_ all of the descendent modules of the specified or `for_each` set, this means selecting _all_ instance indexes currently
module. 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 This targeting capability is provided for exceptional circumstances, such
as recovering from mistakes or working around Terraform limitations. It 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 a complex system architecture to be broken down into more manageable parts
that can be updated independently. that can be updated independently.
## Security Warning ## Other Options
Saved plan files (with the `-out` flag) encode the configuration, The `terraform plan` command also has some other options that are related to
state, diff, and _variables_. Variables are often used to store secrets. the input and output of the planning command, rather than customizing what
Therefore, the plan file can potentially store secrets. 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 The available options are:
recommended to encrypt the plan file if you intend to transfer it
or keep it at rest for an extended period of time.
Future versions of Terraform will make plan files more * `-compact-warnings` - Shows any warning messages in a compact form which
secure. 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 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 a directory path, in which case Terraform would use that directory as the root
module instead of the current working directory. module instead of the current working directory.
That usage is still supported in Terraform v0.14, but is now deprecated and we That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15.
plan to remove it in Terraform v0.15. If your workflow relies on overriding If your workflow relies on overriding the root module directory, use
the root module directory, use
[the `-chdir` global option](./#switching-working-directory-with-chdir) [the `-chdir` global option](./#switching-working-directory-with-chdir)
instead, which works across all commands and makes Terraform consistently look 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 in the given directory for all files it would normally read or write in the

87
website/docs/cli/commands/refresh.html.md
View File

@ -3,61 +3,66 @@ layout: "docs"
page_title: "Command: refresh" page_title: "Command: refresh"
sidebar_current: "docs-commands-refresh" sidebar_current: "docs-commands-refresh"
description: |- 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 # Command: refresh
The `terraform refresh` command is used to reconcile the state Terraform The `terraform refresh` command reads the current settings from all managed
knows about (via its state file) with the real-world infrastructure. remote objects and updates the Terraform state to match.
This can be used to detect any drift from the last-known state, and to
update the state file.
This does not modify infrastructure, but does modify the state file. ~> *Warning:* This command is deprecated, because its default behavior is
If the state is changed, this may cause changes to occur during the next unsafe if you have misconfigured credentials for any of your providers.
plan or apply. 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
Usage: `terraform refresh [options]` 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 terraform apply -refresh-only -auto-approve
the summary messages. ```
* `-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 This alternative command will present an interactive prompt for you to confirm
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults the detected changes.
to 10.
* `-target=resource` - A [Resource The `-refresh-only` option for `terraform plan` and `terraform apply` was
Address](/docs/cli/state/resource-addressing.html) to target. Operation will introduced in Terraform v1.0. For prior versions you must use
be limited to this resource and its dependencies. This flag can be used `terraform refresh` directly if you need this behavior, while taking into
multiple times. account the warnings above. Wherever possible, avoid using `terraform refresh`
explicitly and instead rely on Terraform's behavior of automatically refreshing
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag existing objects as part of creating a normal plan.
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).

103
website/docs/cli/commands/taint.html.md
View File

@ -3,33 +3,16 @@ layout: "docs"
page_title: "Command: taint" page_title: "Command: taint"
sidebar_current: "docs-commands-taint" sidebar_current: "docs-commands-taint"
description: |- 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 # Command: taint
The `terraform taint` command manually marks a Terraform-managed resource The `terraform taint` command informs Terraform that a particular object has
as tainted, forcing it to be destroyed and recreated on the next apply. become degraded or damaged. Terraform represents this by marking the
object as "tainted" in the Terraform state, in which case Terraform will
This command _will not_ modify infrastructure, but does modify the propose to replace it in the next plan you create.
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.
## Usage ## Usage
@ -42,74 +25,30 @@ as shown in the output from other commands, such as:
* `aws_instance.foo` * `aws_instance.foo`
* `aws_instance.bar[1]` * `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` * `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) * `-allow-missing` - If specified, the command will succeed (exit code 0)
even if the resource is missing. The command can still error, but only even if the resource is missing. The command might still return an error
in critically erroneous cases. 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 * `-lock=false` - Disables Terraform's default behavior of attempting to take
the ".backup" extension. Disabled by setting to "-". 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
* `-lock-timeout=0s` - Duration to retry a state lock. returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
* `-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.
* `-ignore-remote-version` - When using the enhanced remote backend with * `-ignore-remote-version` - When using the enhanced remote backend with
Terraform Cloud, continue even if remote and local Terraform versions differ. Terraform Cloud, continue even if remote and local Terraform versions differ.
This may result in an unusable Terraform Cloud workspace, and should be used This may result in an unusable Terraform Cloud workspace, and should be used
with extreme caution. with extreme caution.
## Example: Tainting a Single Resource For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
This example will taint a single resource: `terraform taint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
```
$ 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.
```

71
website/docs/cli/commands/untaint.html.md
View File

@ -3,56 +3,63 @@ layout: "docs"
page_title: "Command: untaint" page_title: "Command: untaint"
sidebar_current: "docs-commands-untaint" sidebar_current: "docs-commands-untaint"
description: |- 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 # Command: untaint
The `terraform untaint` command manually unmarks a Terraform-managed resource Terraform has a marker called "tainted" which it uses to track that an object
as tainted, restoring it as the primary instance in the state. This reverses might be damaged and so a future Terraform plan ought to replace it.
either a manual `terraform taint` or the result of provisioners failing on a
resource.
This command _will not_ modify infrastructure, but does modify the state file Terraform automatically marks an object as "tainted" if an error occurs during
in order to unmark a resource as tainted. 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 You can also manually mark an object as "tainted" using the deprecated command
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 [`terraform taint`](./taint.html), although we no longer recommend that
determine which index holds the instance you'd like to restore. In the vast workflow.
majority of cases, there will only be one tainted instance, and the `-index`
flag can be omitted. 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
Usage: `terraform untaint [options] name` Usage: `terraform untaint [options] address`
The `name` argument is the name of the resource to mark as untainted. The The `address` argument is a [resource address](/docs/cli/state/resource-addressing.html)
format of this argument is `TYPE.NAME`, such as `aws_instance.foo`. identifying a particular resource instance which is currently tainted.
The command-line flags are all optional (with the exception of `-index` in This command also accepts the following options:
certain cases, see above note). The list of available flags are:
* `-allow-missing` - If specified, the command will succeed (exit code 0) * `-allow-missing` - If specified, the command will succeed (exit code 0)
even if the resource is missing. The command can still error, but only even if the resource is missing. The command might still return an error
in critically erroneous cases. 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 * `-lock=false` - Disables Terraform's default behavior of attempting to take
the ".backup" extension. Disabled by setting to "-". 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 terminal formatting sequences in the output. Use this
if you are running Terraform in a context where its output will be
* `-no-color` - Disables output with coloring rendered by a system that cannot interpret terminal formatting.
* `-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.
* `-ignore-remote-version` - When using the enhanced remote backend with * `-ignore-remote-version` - When using the enhanced remote backend with
Terraform Cloud, continue even if remote and local Terraform versions differ. Terraform Cloud, continue even if remote and local Terraform versions differ.
This may result in an unusable Terraform Cloud workspace, and should be used This may result in an unusable Terraform Cloud workspace, and should be used
with extreme caution. 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).

35
website/docs/cli/state/resource-addressing.html.md
View File

@ -3,19 +3,27 @@ layout: "docs"
page_title: "Internals: Resource Address" page_title: "Internals: Resource Address"
sidebar_current: "docs-internals-resource-addressing" sidebar_current: "docs-internals-resource-addressing"
description: |- description: |-
Resource addressing is used to target specific resources in a larger A resource address is a string that identifies zero or more resource
infrastructure. instances in your overall configuration.
--- ---
# Resource Addressing # Resource Addressing
A __Resource Address__ is a string that references a specific resource in a A _resource address_ is a string that identifies zero or more resource
larger infrastructure. An address is made up of two parts: instances in your overall configuration.
An address is made up of two parts:
``` ```
[module path][resource spec] [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 ## Module path
A module path addresses a module within the tree of modules. It takes the form: 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` * `module` - Module keyword indicating a child module (non-root). Multiple `module`
keywords in a path indicate nesting. keywords in a path indicate nesting.
* `module_name` - User-defined name of the module. * `module_name` - User-defined name of the module.
* `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources) into a * `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources)
module with multiple instances, surrounded by square brace characters (`[` and `]`). 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 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. 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.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. versions of Terraform, a module could not have multiple instances.
## Resource spec ## 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_type` - Type of the resource being addressed.
* `resource_name` - User-defined name of the resource. * `resource_name` - User-defined name of the resource.
* `[resource index]` - (Optional) [Index](#index-values-for-modules-and-resources) * `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources)
into a resource with multiple instances, surrounded by square brace characters (`[` and `]`). 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 -> 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 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. in any descendent module.
## Index values for Modules and Resources ## Index values for Modules and Resources