Skip to content

Commit

Permalink
website: Reworking of the "terraform plan" docs, and related pages
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@apparentlymart
apparentlymart committed Apr 30, 2021
1 parent 95b86bf commit 6bed300
Show file tree
Hide file tree
Showing 7 changed files with 455 additions and 331 deletions.
122 changes: 68 additions & 54 deletions website/docs/cli/commands/apply.html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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

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.

The command-line flags are all optional. The list of available flags are:

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

* `-lock=true` - Lock the state file when locking is supported.
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).

* `-lock-timeout=0s` - Duration to retry a state lock.

* `-input=true` - Ask for input for variables if not directly set.
## Usage

* `-auto-approve` - Skip interactive approval of plan before applying.
Usage: `terraform apply [options] [plan]`

* `-no-color` - Disables output with coloring.
The behavior of `terraform apply` differs significantly depending on whether
you pass it the filename of a previously-saved plan file.

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.

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.

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

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

* `-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=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.

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

* `-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
Expand All @@ -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
Expand Down
43 changes: 30 additions & 13 deletions website/docs/cli/commands/destroy.html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

```
terraform apply -destroy
```

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.

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.
You can also create a speculative destroy plan, to see what the effect of
destroying would be, by running the following command:

If `-auto-approve` is set, then the destroy confirmation will not be shown.
```
terraform plan -destroy
```

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).
This will run [`terraform plan`](./plan.html) in _destroy_ mode, showing
you the proposed destroy changes without executing them.

The behavior of any `terraform destroy` command can be previewed at any time
with an equivalent `terraform plan -destroy` command.
-> **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`.
Loading

0 comments on commit 6bed300

Please sign in to comment.