ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages 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"
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

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

@ -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`.

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

@ -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

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

@ -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.

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

@ -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).

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

@ -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).

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

@ -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