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

Merge pull request #30173 from hashicorp/ds.mdx-migration-main 

Migrate docs to MDX (main)
This commit is contained in:
Dylan Staley 2021-12-14 18:58:19 -08:00 committed by GitHub
parent c4d46e7c6b 21cbb5b392
commit 58e4676aea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
358 changed files with 5048 additions and 5862 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
website/README.md
View File

@ -8,39 +8,36 @@ The files in this directory are intended to be used in conjunction with
different documentation sources together and contains the scripts for testing and building the site as different documentation sources together and contains the scripts for testing and building the site as
a whole. a whole.
## Modifying Sidebar Navigation
Updates to the sidebar navigation of Terraform docs need to be made in the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository (preferrably in a PR also updating the submodule commit). You can read more about how to make modifications to the navigation in the [README for `terraform-website`](https://github.com/hashicorp/terraform-website#editing-navigation-sidebars).
## Previewing Changes ## Previewing Changes
You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site. If `terraform-website` isn't in your `GOPATH`, the preview command will clone it to your machine. You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site.
**Set Up Local Environment** **Set Up Local Environment**
1. [Install Docker](https://docs.docker.com/get-docker/). 1. [Install Docker](https://docs.docker.com/get-docker/).
2. Create a `~/go` directory manually or by [installing Go](https://golang.org/doc/install). 1. Restart your terminal or command line session.
3. Open terminal and set `GOPATH` as an environment variable:
Bash: `export $GOPATH=~/go`(bash)
Zsh: `echo -n 'export GOPATH=~/go' >> ~/.zshrc`
4. Restart your terminal or command line session.
**Launch Site Locally** **Launch Site Locally**
1. Navigate into your local `terraform` top-level directory and run `make website`. 1. Navigate into your local `terraform` top-level directory and run `make website`.
2. Open `http://localhost:4567` in your web browser. While the preview is running, you can edit pages and Middleman will automatically rebuild them. 1. Open `http://localhost:4567` in your web browser. While the preview is running, you can edit pages and Next.js will automatically rebuild them.
3. When you're done with the preview, press `ctrl-C` in your terminal to stop the server. 1. When you're done with the preview, press `ctrl-C` in your terminal to stop the server.
## Deploying Changes ## Deploying Changes
Merge the PR to main. The changes will appear in the next major Terraform release. Merge the PR to main. The changes will appear in the next major Terraform release.
If you need your changes to be deployed sooner, cherry-pick them to: If you need your changes to be deployed sooner, cherry-pick them to:
- the current release branch (e.g. `v1.0`) and push. They will be deployed in the next minor version release (once every two weeks).
- the `stable-website` branch and push. They will be included in the next site deploy (see below). Note that the release process resets `stable-website` to match the release tag, removing any additional commits. So, we recommend always cherry-picking to the version branch first and then to `stable-website` when needed. - the current release branch (e.g. `v1.1`) and push. They will be deployed in the next minor version release (once every two weeks).
- the `stable-website` branch and push. They will be included in the next site deploy (see below). Note that the release process resets `stable-website` to match the release tag, removing any additional commits. So, we recommend always cherry-picking to the version branch first and then to `stable-website` when needed.
Once your PR to `stable-website` is merged, open a PR bumping the submodule commit in [`terraform-website`](https://github.com/hashicorp/terraform-website).
### Deployment ### Deployment
Currently, HashiCorp uses a CircleCI job to deploy the [terraform.io](terraform.io) site. This job can be run manually by many people within HashiCorp, and also runs automatically whenever a user in the HashiCorp GitHub org merges changes to master in the `terraform-website` repository.
New commits in this repository don't automatically deploy the [terraform.io][] site, but an unrelated site deploy will usually happen within a day. If you can't wait that long, you can do a manual CircleCI build or ask someone in the #proj-terraform-docs channel to do so: New commits in `hashicorp/terraform` and `hashicorp/terraform-cdk` don't automatically deploy the site. To use the latest upstream content, you'll need to open a PR bumping the submodule commit. If your changes aren't being deployed, it's very likely that you need to open a PR to update the submodule commit.
- Log in to circleci.com, and make sure you're viewing the HashiCorp organization.
- Go to the terraform-website project's list of workflows.
- Find the most recent "website-deploy" workflow, and click the "Rerun workflow from start" button (which looks like a refresh button with a numeral "1" inside).

17
website/docs/cli/auth/index.html.md → website/docs/cli/auth/index.mdx
View File

@ -1,21 +1,22 @@
--- ---
layout: "docs" page_title: Authentication - Terraform CLI
page_title: "Authentication - Terraform CLI" description: >-
description: "Documentation about the login and logout commands that help automate getting an API token for your Terraform Cloud account." Documentation about the login and logout commands that help automate getting
an API token for your Terraform Cloud account.
--- ---
# CLI Authentication # CLI Authentication
> **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-login?in=terraform/cloud&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. > **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-login?in=terraform/cloud&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
[Terraform Cloud](/docs/cloud/index.html) and [Terraform Cloud](/cloud) and
[Terraform Enterprise](/docs/enterprise/index.html) are platforms that perform [Terraform Enterprise](/enterprise) are platforms that perform
Terraform runs to provision infrastructure, offering a collaboration-focused Terraform runs to provision infrastructure, offering a collaboration-focused
environment that makes it easier for teams to use Terraform together. (For environment that makes it easier for teams to use Terraform together. (For
expediency, the content below refers to both products as "Terraform Cloud.") expediency, the content below refers to both products as "Terraform Cloud.")
Terraform CLI integrates with Terraform Cloud in several ways — it can be a Terraform CLI integrates with Terraform Cloud in several ways — it can be a
front-end for [CLI-driven runs](/docs/cloud/run/cli.html) in Terraform Cloud, front-end for [CLI-driven runs](/cloud-docs/run/cli) in Terraform Cloud,
and can also use Terraform Cloud as a state backend and a private module and can also use Terraform Cloud as a state backend and a private module
registry. All of these integrations require you to authenticate Terraform CLI registry. All of these integrations require you to authenticate Terraform CLI
with your Terraform Cloud account. with your Terraform Cloud account.
@ -26,5 +27,5 @@ Terraform Cloud user account.
For details, see: For details, see:
- [The `terraform login` command](/docs/cli/commands/login.html) - [The `terraform login` command](/cli/commands/login)
- [The `terraform logout` command](/docs/cli/commands/logout.html) - [The `terraform logout` command](/cli/commands/logout)

26
website/docs/cli/cloud/command-line-arguments.html.md
View File

@ -1,26 +0,0 @@
---
layout: "docs"
page_title: "Command Line Arguments"
description: "Command Line Arguments"
---
# Command Line Arguments
When your configuration includes a `cloud` block, commands that
make local modifications to Terraform state and then push them back up to the remote workspace
accept the following option to modify that behavior:
- `-ignore-remote-version` - Override checking that the local and remote
Terraform versions agree, making an operation proceed even when there is
a mismatch.
State-modification operations usually require using a local version of the
Terraform CLI that is compatible with the Terraform version selected
in the remote workspace settings. This prevents the
local operation from creating a new state snapshot that the workspace's
remote execution environment cannot decode.
We recommend against using this option unless absolutely necessary. Overriding this check can result
in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently
selected version of Terraform.

24
website/docs/cli/cloud/command-line-arguments.mdx Normal file
View File

@ -0,0 +1,24 @@
---
page_title: Command Line Arguments
description: Command Line Arguments
---
# Command Line Arguments
When your configuration includes a `cloud` block, commands that
make local modifications to Terraform state and then push them back up to the remote workspace
accept the following option to modify that behavior:
- `-ignore-remote-version` - Override checking that the local and remote
Terraform versions agree, making an operation proceed even when there is
a mismatch.
State-modification operations usually require using a local version of the
Terraform CLI that is compatible with the Terraform version selected
in the remote workspace settings. This prevents the
local operation from creating a new state snapshot that the workspace's
remote execution environment cannot decode.
We recommend against using this option unless absolutely necessary. Overriding this check can result
in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently
selected version of Terraform.

28
website/docs/cli/cloud/index.html.md
View File

@ -1,28 +0,0 @@
---
layout: "docs"
page_title: "Using Terraform Cloud - Terraform CLI"
---
# Using Terraform Cloud with Terraform CLI
The Terraform CLI's integration with Terraform Cloud lets you to use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated.
Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/docs/cloud/run/cli.html). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking.
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
Workspaces can also be configured for local execution, in which case only state is stored in
Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend.
-> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/docs/language/settings/backends/remote.html). Refer to [Migrating from the remote
backend](/docs/cli/cloud/migrating.html) for details about switching to the CLI integration.
## Documentation Summary
- [Terraform Cloud Settings](/docs/cli/cloud/settings.html) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support.
- [Initializing and Migrating](/docs/cli/cloud/migrating.html) describes
how to start using Terraform Cloud with a working directory that already has state data.
- [Command Line Arguments](/docs/cli/cloud/command-line-arguments.html) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud.
Refer to the [CLI-driven Run Workflow](/docs/cloud/run/cli.html) for more details about how to use Terraform Cloud from the command line.

26
website/docs/cli/cloud/index.mdx Normal file
View File

@ -0,0 +1,26 @@
---
page_title: Using Terraform Cloud - Terraform CLI
---
# Using Terraform Cloud with Terraform CLI
The Terraform CLI's integration with Terraform Cloud lets you to use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated.
Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/cloud-docs/run/cli). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking.
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
Workspaces can also be configured for local execution, in which case only state is stored in
Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend.
-> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/language/settings/backends/remote). Refer to [Migrating from the remote
backend](/cli/cloud/migrating) for details about switching to the CLI integration.
## Documentation Summary
- [Terraform Cloud Settings](/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support.
- [Initializing and Migrating](/cli/cloud/migrating) describes
how to start using Terraform Cloud with a working directory that already has state data.
- [Command Line Arguments](/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud.
Refer to the [CLI-driven Run Workflow](/cloud-docs/run/cli) for more details about how to use Terraform Cloud from the command line.

15
website/docs/cli/cloud/migrating.html.md → website/docs/cli/cloud/migrating.mdx
View File

@ -1,24 +1,23 @@
--- ---
layout: "docs" page_title: Initializing and Migrating to Terraform Cloud - Terraform CLI
page_title: "Initializing and Migrating to Terraform Cloud - Terraform CLI"
--- ---
# Initializing and Migrating # Initializing and Migrating
After [configuring Terraform Cloud settings](/docs/cli/cloud/settings.html) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/docs/cloud/run/cli.html) for more details. After [configuring Terraform Cloud settings](/cli/cloud/settings) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/cloud-docs/run/cli) for more details.
When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces. When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces.
1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces. 1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces.
2. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block. 1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block.
## Migrating from Local State or State Backends ## Migrating from Local State or State Backends
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
If the working directory already has state data available (using either local state or a [state If the working directory already has state data available (using either local state or a [state
backend](/docs/language/settings/backends/index.html)), Terraform will ask your approval to migrate backend](/language/settings/backends)), Terraform will ask your approval to migrate
that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles
moving between state backends. moving between state backends.
@ -32,13 +31,13 @@ Because of this, Terraform will prompt you to rename the working directory's wor
according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`, `<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`,
`networking-staging-us-east`). Refer to [Workspace `networking-staging-us-east`). Refer to [Workspace
Naming](/docs/cloud/workspaces/naming.html) in the Terraform Cloud documentation for more detail. Naming](/cloud-docs/workspaces/naming) in the Terraform Cloud documentation for more detail.
## Migrating from the `remote` Backend ## Migrating from the `remote` Backend
If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names. If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names.
The [`remote` backend](/docs/language/settings/backends/remote.html) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. The [`remote` backend](/language/settings/backends/remote) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/cloud-docs/run/cli) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements.
### Block Replacement ### Block Replacement
@ -49,7 +48,7 @@ block.
#### Single Workspace #### Single Workspace
If you were using a single workspace with the `name` argument, change the block If you were using a single workspace with the `name` argument, change the block
label to `cloud`. label to `cloud`.
```diff ```diff
terraform { terraform {

37
website/docs/cli/cloud/settings.html.md → website/docs/cli/cloud/settings.mdx
View File

@ -1,19 +1,18 @@
--- ---
layout: "docs" page_title: Terraform Cloud Settings - Terraform CLI
page_title: "Terraform Cloud Settings - Terraform CLI"
--- ---
# Terraform Cloud Settings # Terraform Cloud Settings
Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's
[CLI-driven run workflow](https://www.terraform.io/docs/cloud/run/cli.html). [CLI-driven run workflow](/cloud-docs/run/cli).
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
You must configure the following settings to use Terraform Cloud for a particular working directory: You must configure the following settings to use Terraform Cloud for a particular working directory:
- Provide credentials to access Terraform Cloud, preferably by using the - Provide credentials to access Terraform Cloud, preferably by using the
[`terraform login`](/docs/cli/commands/login.html) command. [`terraform login`](/cli/commands/login) command.
- Add a `cloud` block to the directory's Terraform configuration, to specify - Add a `cloud` block to the directory's Terraform configuration, to specify
which organization and workspace(s) to use. which organization and workspace(s) to use.
- Optionally, use a `.terraformignore` file to specify files that shouldn't be - Optionally, use a `.terraformignore` file to specify files that shouldn't be
@ -43,7 +42,7 @@ terraform {
The `cloud` block also has some special restrictions: The `cloud` block also has some special restrictions:
- A configuration can only provide one `cloud` block. - A configuration can only provide one `cloud` block.
- A `cloud` block cannot be used with [state backends](/docs/language/settings/backends/index.html). - A `cloud` block cannot be used with [state backends](/language/settings/backends).
A configuration can use one or the other, but not both. A configuration can use one or the other, but not both.
- A `cloud` block cannot refer to named values (like input variables, locals, or - A `cloud` block cannot refer to named values (like input variables, locals, or
data source attributes). data source attributes).
@ -60,32 +59,32 @@ The `cloud` block supports the following configuration arguments:
workspace(s) the current configuration should use. workspace(s) the current configuration should use.
- `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to - `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to
use for the current configuration. The `workspaces` block must contain **exactly one** of the use for the current configuration. The `workspaces` block must contain **exactly one** of the
following arguments, each denoting a strategy for how workspaces should be mapped: following arguments, each denoting a strategy for how workspaces should be mapped:
- `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use
this working directory with any workspaces that have all of the specified tags, this working directory with any workspaces that have all of the specified tags,
and can use [the `terraform workspace` commands](/docs/cli/workspaces/index.html) and can use [the `terraform workspace` commands](/cli/workspaces)
to switch between them or create new workspaces. New workspaces will automatically have to switch between them or create new workspaces. New workspaces will automatically have
the specified tags. This option conflicts with `name`. the specified tags. This option conflicts with `name`.
- `name` - (Optional) The name of a single Terraform Cloud workspace. You will - `name` - (Optional) The name of a single Terraform Cloud workspace. You will
only be able to use the workspace specified in the configuration with this working only be able to use the workspace specified in the configuration with this working
directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or
`terraform workspace new`). This option conflicts with `tags`. `terraform workspace new`). This option conflicts with `tags`.
- `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform - `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
Enterprise. Defaults to Terraform Cloud (app.terraform.io). Enterprise. Defaults to Terraform Cloud (app.terraform.io).
- `token` - (Optional) The token used to authenticate with Terraform Cloud. - `token` - (Optional) The token used to authenticate with Terraform Cloud.
We recommend omitting the token from the configuration, and instead using We recommend omitting the token from the configuration, and instead using
[`terraform login`](/docs/cli/commands/login.html) or manually configuring [`terraform login`](/cli/commands/login) or manually configuring
`credentials` in the `credentials` in the
[CLI config file](/docs/cli/config/config-file.html#credentials). [CLI config file](/cli/config/config-file#credentials).
## Excluding Files from Upload with .terraformignore ## Excluding Files from Upload with .terraformignore
When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli),
a copy of your configuration directory is uploaded to Terraform Cloud. You can define a copy of your configuration directory is uploaded to Terraform Cloud. You can define
paths to exclude from upload by adding a `.terraformignore` file at the root of your paths to exclude from upload by adding a `.terraformignore` file at the root of your
configuration directory. If this file is not present, the upload will exclude configuration directory. If this file is not present, the upload will exclude

24
website/docs/cli/code/index.html.md → website/docs/cli/code/index.mdx
View File

@ -1,12 +1,13 @@
--- ---
layout: "docs" page_title: Writing and Modifying Code - Terraform CLI
page_title: "Writing and Modifying Code - Terraform CLI" description: >-
description: "Learn commands that help validate, format, and upgrade code written in the Terraform Configuration Language." Learn commands that help validate, format, and upgrade code written in the
Terraform Configuration Language.
--- ---
# Writing and Modifying Terraform Code # Writing and Modifying Terraform Code
The [Terraform language](/docs/language/index.html) is Terraform's primary The [Terraform language](/language) is Terraform's primary
user interface, and all of Terraform's workflows rely on configurations written user interface, and all of Terraform's workflows rely on configurations written
in the Terraform language. in the Terraform language.
@ -14,18 +15,17 @@ Terraform CLI includes several commands to make Terraform code more convenient
to work with. Integrating these commands into your editing workflow can to work with. Integrating these commands into your editing workflow can
potentially save you time and effort. potentially save you time and effort.
- [The `terraform console` command](/docs/cli/commands/console.html) starts an - [The `terraform console` command](/cli/commands/console) starts an
interactive shell for evaluating Terraform interactive shell for evaluating Terraform
[expressions](/docs/language/expressions/index.html), which can be a faster way [expressions](/language/expressions), which can be a faster way
to verify that a particular resource argument results in the value you expect. to verify that a particular resource argument results in the value you expect.
- [The `terraform fmt` command](/cli/commands/fmt) rewrites Terraform
- [The `terraform fmt` command](/docs/cli/commands/fmt.html) rewrites Terraform
configuration files to a canonical format and style, so you don't have to configuration files to a canonical format and style, so you don't have to
waste time making minor adjustments for readability and consistency. It works waste time making minor adjustments for readability and consistency. It works
well as a pre-commit hook in your version control system. well as a pre-commit hook in your version control system.
- [The `terraform validate` command](/docs/cli/commands/validate.html) validates the - [The `terraform validate` command](/cli/commands/validate) validates the
syntax and arguments of the Terraform configuration files in a directory, syntax and arguments of the Terraform configuration files in a directory,
including argument and attribute names and types for resources and modules. including argument and attribute names and types for resources and modules.
The `plan` and `apply` commands automatically validate a configuration before The `plan` and `apply` commands automatically validate a configuration before
@ -33,12 +33,12 @@ potentially save you time and effort.
workflow, but it can be very useful as a pre-commit hook or as part of a workflow, but it can be very useful as a pre-commit hook or as part of a
continuous integration pipeline. continuous integration pipeline.
- [The `0.13upgrade` command](/docs/cli/commands/0.13upgrade.html) and - [The `0.13upgrade` command](/cli/commands/0.13upgrade) and
[the `0.12upgrade` command](/docs/cli/commands/0.12upgrade.html) can automatically [the `0.12upgrade` command](/cli/commands/0.12upgrade) can automatically
modify the configuration files in a Terraform module to help deal with major modify the configuration files in a Terraform module to help deal with major
syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both
of these commands are only available in the Terraform version they are of these commands are only available in the Terraform version they are
associated with, and you are expected to upgrade older code to be compatible associated with, and you are expected to upgrade older code to be compatible
with 0.12 before attempting to make it compatible with 0.13. For more detailed with 0.12 before attempting to make it compatible with 0.13. For more detailed
information about updating code for new Terraform versions, see the [upgrade information about updating code for new Terraform versions, see the [upgrade
guides](/upgrade-guides/index.html) in the Terraform language docs. guides](/language/upgrade-guides) in the Terraform language docs.

19
website/docs/cli/commands/0.12upgrade.html.md → website/docs/cli/commands/0.12upgrade.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: 0.12upgrade'
page_title: "Command: 0.12upgrade" description: >-
sidebar_current: "docs-commands-012upgrade" The 0.12upgrade subcommand automatically rewrites existing configurations for
description: |- Terraform 0.12 compatibility.
The 0.12upgrade subcommand automatically rewrites existing configurations for Terraform 0.12 compatibility.
--- ---
# Command: 0.12upgrade # Command: 0.12upgrade
@ -12,7 +11,7 @@ The `terraform 0.12upgrade` command applies several automatic upgrade rules to
help prepare a module that was written for Terraform v0.11 to be used help prepare a module that was written for Terraform v0.11 to be used
with Terraform v0.12. with Terraform v0.12.
-> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](https://www.terraform.io/upgrade-guides/0-12.html). -> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/language/upgrade-guides/0-12).
## Usage ## Usage
@ -71,13 +70,13 @@ the change.
Once upgraded the configuration will no longer be compatible with Terraform Once upgraded the configuration will no longer be compatible with Terraform
v0.11 and earlier. When upgrading a shared module that is called from multiple v0.11 and earlier. When upgrading a shared module that is called from multiple
configurations, you may need to configurations, you may need to
[fix existing configurations to a previous version](/docs/language/modules/syntax.html#version) [fix existing configurations to a previous version](/language/modules/syntax#version)
to allow for a gradual upgrade. If the module is published via to allow for a gradual upgrade. If the module is published via
[a Terraform registry](/docs/registry/), assign a new _major_ version number [a Terraform registry](/registry), assign a new _major_ version number
to the upgraded module source to represent the fact that this is a breaking to the upgraded module source to represent the fact that this is a breaking
change for v0.11 callers. If a module is installed directly from a version change for v0.11 callers. If a module is installed directly from a version
control system such as Git, control system such as Git,
[use specific revisions](https://www.terraform.io/docs/language/modules/sources.html#selecting-a-revision) [use specific revisions](/language/modules/sources#selecting-a-revision)
to control which version is used by which caller. to control which version is used by which caller.
The command-line options are all optional. The available options are: The command-line options are all optional. The available options are:
@ -107,8 +106,8 @@ On Mac OS X, the `find` included with the system does not support the `-printf`
``` ```
brew install findutils brew install findutils
``` ```
Once installed, run the above command line using `gfind` instead of `find`.
Once installed, run the above command line using `gfind` instead of `find`.
Note that the above includes the `-yes` option to override the interactive Note that the above includes the `-yes` option to override the interactive
prompt, so be sure you have a clean work tree before running it. prompt, so be sure you have a clean work tree before running it.

13
website/docs/cli/commands/0.13upgrade.html.md → website/docs/cli/commands/0.13upgrade.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: 0.13upgrade'
page_title: "Command: 0.13upgrade" description: >-
sidebar_current: "docs-commands-013upgrade" The 0.13upgrade subcommand updates existing configurations to use the new
description: |- provider source features from Terraform 0.13.
The 0.13upgrade subcommand updates existing configurations to use the new provider source features from Terraform 0.13.
--- ---
# Command: 0.13upgrade # Command: 0.13upgrade
@ -12,7 +11,7 @@ The `terraform 0.13upgrade` command updates existing configuration to add an
explicit `source` attribute for each provider used in a given module. The explicit `source` attribute for each provider used in a given module. The
provider source settings are stored in a `required_providers` block. provider source settings are stored in a `required_providers` block.
-> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](https://www.terraform.io/upgrade-guides/0-13.html). -> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/language/upgrade-guides/0-13).
## Usage ## Usage
@ -23,7 +22,7 @@ providers are in use for a module, detect the source address for those
providers where possible, and record this information in a providers where possible, and record this information in a
[`required_providers` block][required-providers]. [`required_providers` block][required-providers].
[required-providers]: /docs/language/providers/requirements.html [required-providers]: /language/providers/requirements
~> Note: the command ignores `.tf.json` files and override files in the module. ~> Note: the command ignores `.tf.json` files and override files in the module.

40
website/docs/cli/commands/apply.html.md → website/docs/cli/commands/apply.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: apply'
page_title: "Command: apply" description: >-
sidebar_current: "docs-commands-apply" The terraform apply command executes the actions proposed in a Terraform plan
description: "The terraform apply command executes the actions proposed in a Terraform plan to create, update, or destroy infrastructure." to create, update, or destroy infrastructure.
--- ---
# Command: apply # Command: apply
@ -33,15 +33,15 @@ you pass it the filename of a previously-saved plan file.
### Automatic Plan Mode ### Automatic Plan Mode
In the default case, with no saved plan file, `terraform apply` creates its own In the default case, with no saved plan file, `terraform apply` creates its own
plan of action, in the same way that [`terraform plan`](./plan.html) would. plan of action, in the same way that [`terraform plan`](/cli/commands/plan) would.
Terraform will propose the plan to you and prompt you to approve it before Terraform will propose the plan to you and prompt you to approve it before
taking the described actions, unless you waive that prompt by using the taking the described actions, unless you waive that prompt by using the
`-auto-approve` option. `-auto-approve` option.
When performing its own plan, `terraform apply` supports all of the same When performing its own plan, `terraform apply` supports all of the same
[planning modes](./plan.html#planning-modes) and [planning modes](/cli/commands/plan#planning-modes) and
[planning options](./plan.html#planning-options) that `terraform plan` would [planning options](/cli/commands/plan#planning-options) that `terraform plan` would
accept, so you can customize how Terraform will create the plan. accept, so you can customize how Terraform will create the plan.
### Saved Plan Mode ### Saved Plan Mode
@ -49,7 +49,7 @@ accept, so you can customize how Terraform will create the plan.
If you pass the filename of a previously-saved plan file, `terraform apply` If you pass the filename of a previously-saved plan file, `terraform apply`
performs exactly the steps specified by that plan file. It does not prompt for performs exactly the steps specified by that plan file. It does not prompt for
approval; if you want to inspect a plan file before applying it, you can use approval; if you want to inspect a plan file before applying it, you can use
[`terraform show`](./show.html). [`terraform show`](/cli/commands/show).
When using a saved plan, none of the planning modes or planning options linked When using a saved plan, none of the planning modes or planning options linked
above are supported; these options only affect Terraform's decisions about which above are supported; these options only affect Terraform's decisions about which
@ -61,8 +61,8 @@ decisions.
When run without a saved plan file, `terraform apply` supports all of `terraform When run without a saved plan file, `terraform apply` supports all of `terraform
plan`'s planning modes and planning options. For details, see: plan`'s planning modes and planning options. For details, see:
- [Planning Modes](./plan.html#planning-modes) * [Planning Modes](/cli/commands/plan#planning-modes)
- [Planning Options](./plan.html#planning-options) * [Planning Options](/cli/commands/plan#planning-options)
### Apply Options ### Apply Options
@ -70,7 +70,7 @@ 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 apply command executes and reports on the apply operation. If you are running
`terraform apply` _without_ a previously-saved plan file, these options are `terraform apply` _without_ a previously-saved plan file, these options are
_in addition to_ the planning modes and planning options described for _in addition to_ the planning modes and planning options described for
[`terraform plan`](./plan.html). [`terraform plan`](/cli/commands/plan).
* `-auto-approve` - Skips interactive approval of plan before applying. This * `-auto-approve` - Skips interactive approval of plan before applying. This
option is ignored when you pass a previously-saved plan file, because option is ignored when you pass a previously-saved plan file, because
@ -95,11 +95,11 @@ _in addition to_ the planning modes and planning options described for
variable values to continue. To enable this flag, you must also either enable variable values to continue. To enable this flag, you must also either enable
the `-auto-approve` flag or specify a previously-saved plan. the `-auto-approve` flag or specify a previously-saved plan.
[machine-readable-ui]: /docs/internals/machine-readable-ui.html [machine-readable-ui]: /internals/machine-readable-ui
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before
@ -111,13 +111,13 @@ _in addition to_ the planning modes and planning options described for
rendered by a system that cannot interpret terminal formatting. 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](/internals/graph#walking-the-graph). Defaults to
10. 10\.
For configurations using For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/language/settings/backends/local) only,
`terraform apply` also accepts the legacy options `terraform apply` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).
## Passing a Different Configuration Directory ## Passing a Different Configuration Directory
@ -127,7 +127,7 @@ that directory as the root module instead of the current working directory.
That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. 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 If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](./#switching-working-directory-with-chdir) [the `-chdir` global option](/cli/commands/#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
current working directory. current working directory.
@ -135,6 +135,6 @@ current working directory.
If your previous use of this legacy pattern was also relying on Terraform If your previous use of this legacy pattern was also relying on Terraform
writing the `.terraform` subdirectory into the current working directory even writing the `.terraform` subdirectory into the current working directory even
though the root module directory was overridden, use though the root module directory was overridden, use
[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#tf_data_dir) [the `TF_DATA_DIR` environment variable](/cli/config/environment-variables#tf_data_dir)
to direct Terraform to write the `.terraform` directory to a location other to direct Terraform to write the `.terraform` directory to a location other
than the current working directory. than the current working directory.

23
website/docs/cli/commands/console.html.md → website/docs/cli/commands/console.mdx
View File

@ -1,37 +1,36 @@
--- ---
layout: "docs" page_title: 'Command: console'
page_title: "Command: console" description: >-
sidebar_current: "docs-commands-console" The terraform console command provides an interactive console for evaluating
description: "The terraform console command provides an interactive console for expressions.
evaluating expressions."
--- ---
# Command: console # Command: console
The `terraform console` command provides an interactive console for The `terraform console` command provides an interactive console for
evaluating [expressions](/docs/language/expressions/index.html). evaluating [expressions](/language/expressions).
## Usage ## Usage
Usage: `terraform console [options]` Usage: `terraform console [options]`
This command provides an interactive command-line console for evaluating and This command provides an interactive command-line console for evaluating and
experimenting with [expressions](/docs/language/expressions/index.html). experimenting with [expressions](/language/expressions).
This is useful for testing interpolations before using them in configurations, This is useful for testing interpolations before using them in configurations,
and for interacting with any values currently saved in and for interacting with any values currently saved in
[state](/docs/language/state/index.html). [state](/language/state).
If the current state is empty or has not yet been created, the console can be If the current state is empty or has not yet been created, the console can be
used to experiment with the expression syntax and used to experiment with the expression syntax and
[built-in functions](/docs/language/functions/index.html). [built-in functions](/language/functions).
You can close the console with the `exit` command or by pressing Control-C You can close the console with the `exit` command or by pressing Control-C
or Control-D. or Control-D.
For configurations using For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/language/settings/backends/local) only,
`terraform console` accepts the legacy command line option `terraform console` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`](/language/settings/backends/local#command-line-arguments).
## Scripting ## Scripting
@ -52,7 +51,7 @@ tolist([
## Remote State ## Remote State
If [remote state](/docs/language/state/remote.html) is used by the current backend, If [remote state](/language/state/remote) is used by the current backend,
Terraform will read the state for the current workspace from the backend Terraform will read the state for the current workspace from the backend
before evaluating any expressions. before evaluating any expressions.

12
website/docs/cli/commands/destroy.html.md → website/docs/cli/commands/destroy.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: destroy'
page_title: "Command: destroy" description: >-
sidebar_current: "docs-commands-destroy" The terraform destroy command destroys all objects managed by a Terraform
description: "The terraform destroy command destroys all objects managed by a Terraform configuration." configuration.
--- ---
# Command: destroy # Command: destroy
@ -27,7 +27,7 @@ terraform apply -destroy
``` ```
For that reason, this command accepts most of the options that For that reason, this command accepts most of the options that
[`terraform apply`](./apply.html) accepts, although it does [`terraform apply`](/cli/commands/apply) accepts, although it does
not accept a plan file argument and forces the selection of the "destroy" not accept a plan file argument and forces the selection of the "destroy"
planning mode. planning mode.
@ -38,7 +38,7 @@ destroying would be, by running the following command:
terraform plan -destroy terraform plan -destroy
``` ```
This will run [`terraform plan`](./plan.html) in _destroy_ mode, showing This will run [`terraform plan`](/cli/commands/plan) in _destroy_ mode, showing
you the proposed destroy changes without executing them. you the proposed destroy changes without executing them.
-> **Note:** The `-destroy` option to `terraform apply` exists only in -> **Note:** The `-destroy` option to `terraform apply` exists only in

12
website/docs/cli/commands/env.html.md
View File

@ -1,12 +0,0 @@
---
layout: "docs"
page_title: "Command: env"
sidebar_current: "docs-commands-envcmd"
description: "The terraform env command is a deprecated form of the terraform workspace command."
---
# Command: env
The `terraform env` command is deprecated.
[The `terraform workspace` command](/docs/cli/commands/workspace/index.html)
should be used instead.

12
website/docs/cli/commands/env.mdx Normal file
View File

@ -0,0 +1,12 @@
---
page_title: 'Command: env'
description: >-
The terraform env command is a deprecated form of the terraform workspace
command.
---
# Command: env
The `terraform env` command is deprecated.
[The `terraform workspace` command](/cli/commands/workspace)
should be used instead.

12
website/docs/cli/commands/fmt.html.md → website/docs/cli/commands/fmt.mdx
View File

@ -1,15 +1,15 @@
--- ---
layout: "docs" page_title: 'Command: fmt'
page_title: "Command: fmt" description: >-
sidebar_current: "docs-commands-fmt" The terraform fmt command rewrites configuration files to a canonical format
description: "The terraform fmt command rewrites configuration files to a canonical format and style." and style.
--- ---
# Command: fmt # Command: fmt
The `terraform fmt` command is used to rewrite Terraform configuration files The `terraform fmt` command is used to rewrite Terraform configuration files
to a canonical format and style. This command applies a subset of to a canonical format and style. This command applies a subset of
the [Terraform language style conventions](/docs/language/syntax/style.html), the [Terraform language style conventions](/language/syntax/style),
along with other minor adjustments for readability. along with other minor adjustments for readability.
Other Terraform commands that generate Terraform configuration will produce Other Terraform commands that generate Terraform configuration will produce
@ -58,5 +58,5 @@ The command-line flags are all optional. The list of available flags are:
* `-write=false` - Don't overwrite the input files. (This is implied by `-check` or when the input is STDIN.) * `-write=false` - Don't overwrite the input files. (This is implied by `-check` or when the input is STDIN.)
* `-diff` - Display diffs of formatting changes * `-diff` - Display diffs of formatting changes
* `-check` - Check if the input is formatted. Exit status will be 0 if * `-check` - Check if the input is formatted. Exit status will be 0 if
all input is properly formatted and non-zero otherwise. all input is properly formatted and non-zero otherwise.
* `-recursive` - Also process files in subdirectories. By default, only the given directory (or current directory) is processed. * `-recursive` - Also process files in subdirectories. By default, only the given directory (or current directory) is processed.

10
website/docs/cli/commands/force-unlock.html.md → website/docs/cli/commands/force-unlock.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: force-unlock'
page_title: "Command: force-unlock" description: >-
sidebar_current: "docs-commands-force-unlock" The terraform force-unlock command unlocks the state for a configuration. It
description: "The terraform force-unlock command unlocks the state for a configuration. It does not modify your infrastructure." does not modify your infrastructure.
--- ---
# Command: force-unlock # Command: force-unlock
@ -27,4 +27,4 @@ process.
Options: Options:
* `-force` - Don't ask for input for unlock confirmation. * `-force` - Don't ask for input for unlock confirmation.

10
website/docs/cli/commands/get.html.md → website/docs/cli/commands/get.mdx
View File

@ -1,14 +1,12 @@
--- ---
layout: "docs" page_title: 'Command: get'
page_title: "Command: get" description: The terraform get command downloads and updates modules.
sidebar_current: "docs-commands-get"
description: "The terraform get command downloads and updates modules."
--- ---
# Command: get # Command: get
The `terraform get` command is used to download and update The `terraform get` command is used to download and update
[modules](/docs/language/modules/develop/index.html) mentioned in the root module. [modules](/language/modules/develop) mentioned in the root module.
## Usage ## Usage
@ -21,6 +19,6 @@ repository.
The `get` command supports the following option: The `get` command supports the following option:
* `-update` - If specified, modules that are already downloaded will be * `-update` - If specified, modules that are already downloaded will be
checked for updates and the updates will be downloaded if present. checked for updates and the updates will be downloaded if present.
* `-no-color` - Disable text coloring in the output. * `-no-color` - Disable text coloring in the output.

19
website/docs/cli/commands/graph.html.md → website/docs/cli/commands/graph.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: graph'
page_title: "Command: graph" description: >-
sidebar_current: "docs-commands-graph" The terraform graph command generates a visual representation of a
description: "The terraform graph command generates a visual representation of a configuration or execution plan that you can use to generate charts." configuration or execution plan that you can use to generate charts.
--- ---
# Command: graph # Command: graph
@ -12,7 +12,6 @@ representation of either a configuration or execution plan.
The output is in the DOT format, which can be used by The output is in the DOT format, which can be used by
[GraphViz](http://www.graphviz.org) to generate charts. [GraphViz](http://www.graphviz.org) to generate charts.
## Usage ## Usage
Usage: `terraform graph [options]` Usage: `terraform graph [options]`
@ -33,16 +32,16 @@ argument.
Options: Options:
* `-plan=tfplan` - Render graph using the specified plan file instead of the * `-plan=tfplan` - Render graph using the specified plan file instead of the
configuration in the current directory. configuration in the current directory.
* `-draw-cycles` - Highlight any cycles in the graph with colored edges. * `-draw-cycles` - Highlight any cycles in the graph with colored edges.
This helps when diagnosing cycle errors. This helps when diagnosing cycle errors.
* `-type=plan` - Type of graph to output. Can be: `plan`, `plan-destroy`, `apply`, * `-type=plan` - Type of graph to output. Can be: `plan`, `plan-destroy`, `apply`,
`validate`, `input`, `refresh`. `validate`, `input`, `refresh`.
* `-module-depth=n` - (deprecated) In prior versions of Terraform, specified the * `-module-depth=n` - (deprecated) In prior versions of Terraform, specified the
depth of modules to show in the output. depth of modules to show in the output.
## Generating Images ## Generating Images
@ -55,4 +54,4 @@ $ terraform graph | dot -Tsvg > graph.svg
``` ```
Here is an example graph output: Here is an example graph output:
![Graph Example](docs/graph-example.png) ![Graph Example](/img/docs/graph-example.png)

38
website/docs/cli/commands/import.html.md → website/docs/cli/commands/import.mdx
View File

@ -1,8 +1,6 @@
--- ---
layout: "docs" page_title: 'Command: import'
page_title: "Command: import" description: The terraform import command brings existing resources into Terraform state.
sidebar_current: "docs-commands-import"
description: "The terraform import command brings existing resources into Terraform state."
--- ---
# Command: import # Command: import
@ -10,7 +8,7 @@ description: "The terraform import command brings existing resources into Terraf
> **Hands-on:** Try the [Import Terraform Configuration](https://learn.hashicorp.com/tutorials/terraform/state-import?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 [Import Terraform Configuration](https://learn.hashicorp.com/tutorials/terraform/state-import?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
The `terraform import` command is used to The `terraform import` command is used to
[import existing resources](/docs/cli/import/index.html) [import existing resources](/cli/import)
into Terraform. into Terraform.
## Usage ## Usage
@ -20,7 +18,7 @@ Usage: `terraform import [options] ADDRESS ID`
Import will find the existing resource from ID and import it into your Terraform Import will find the existing resource from ID and import it into your Terraform
state at the given ADDRESS. state at the given ADDRESS.
ADDRESS must be a valid [resource address](/docs/cli/state/resource-addressing.html). ADDRESS must be a valid [resource address](/cli/state/resource-addressing).
Because any resource address is valid, the import command can import resources Because any resource address is valid, the import command can import resources
into modules as well as directly into the root of your state. into modules as well as directly into the root of your state.
@ -36,7 +34,7 @@ itself having created all objects. If you import existing objects into Terraform
be careful to import each remote object to only one Terraform resource address. be careful to import each remote object to only one Terraform resource address.
If you import the same object multiple times, Terraform may exhibit unwanted If you import the same object multiple times, Terraform may exhibit unwanted
behavior. For more information on this assumption, see behavior. For more information on this assumption, see
[the State section](/docs/language/state/index.html). [the State section](/language/state).
The command-line flags are all optional. The list of available flags are: The command-line flags are all optional. The list of available flags are:
@ -48,29 +46,29 @@ The command-line flags are all optional. The list of available flags are:
* `-input=true` - Whether to ask for input for provider configuration. * `-input=true` - Whether to ask for input for provider configuration.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=0s` - Duration to retry a state lock. * `-lock-timeout=0s` - Duration to retry a state lock.
* `-no-color` - If specified, output won't contain any color. * `-no-color` - If specified, output won't contain any color.
* `-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 [walks the graph](/internals/graph#walking-the-graph). Defaults
to 10. to 10.
* `-provider=provider` - **Deprecated** Override the provider configuration to * `-provider=provider` - **Deprecated** Override the provider configuration to
use when importing the object. By default, Terraform uses the provider specified use when importing the object. By default, Terraform uses the provider specified
in the configuration for the target resource, and that is the best behavior in most cases. in the configuration for the target resource, and that is the best behavior in most cases.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as can be set multiple times. Variable values are interpreted as
[literal expressions](/docs/language/expressions/types.html) in the [literal expressions](/language/expressions/types) in the
Terraform language, so list and map values can be specified via this flag. Terraform language, so list and map values can be specified via this flag.
This is only useful with the `-config` flag. This is only useful with the `-config` flag.
* `-var-file=foo` - Set variables in the Terraform configuration from * `-var-file=foo` - Set variables in the Terraform configuration from
a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If a [variable file](/language/values/variables#variable-definitions-tfvars-files). If
a `terraform.tfvars` or any `.auto.tfvars` files are present in the current a `terraform.tfvars` or any `.auto.tfvars` files are present in the current
directory, they will be automatically loaded. `terraform.tfvars` is loaded directory, they will be automatically loaded. `terraform.tfvars` is loaded
first and the `.auto.tfvars` files after in alphabetical order. Any files first and the `.auto.tfvars` files after in alphabetical order. Any files
@ -79,15 +77,15 @@ in the configuration for the target resource, and that is the best behavior in m
useful with the `-config` flag. useful with the `-config` flag.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
only, `terraform import` only, `terraform import`
also accepts the option also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). [`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
For configurations using For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/language/settings/backends/local) only,
`terraform import` also accepts the legacy options `terraform import` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).
## Provider Configuration ## Provider Configuration
@ -135,7 +133,7 @@ $ terraform import module.foo.aws_instance.bar i-abcd1234
## Example: Import into Resource configured with count ## Example: Import into Resource configured with count
The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with
[`count`](/docs/language/meta-arguments/count.html): [`count`](/language/meta-arguments/count):
```shell ```shell
$ terraform import 'aws_instance.baz[0]' i-abcd1234 $ terraform import 'aws_instance.baz[0]' i-abcd1234
@ -144,7 +142,7 @@ $ terraform import 'aws_instance.baz[0]' i-abcd1234
## Example: Import into Resource configured with for_each ## Example: Import into Resource configured with for_each
The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with
[`for_each`](/docs/language/meta-arguments/for_each.html): [`for_each`](/language/meta-arguments/for_each):
Linux, Mac OS, and UNIX: Linux, Mac OS, and UNIX:

14
website/docs/cli/commands/index.html.md → website/docs/cli/commands/index.mdx
View File

@ -1,8 +1,6 @@
--- ---
layout: "docs" page_title: Basic CLI Features
page_title: "Basic CLI Features" description: An introduction to the terraform command and its available subcommands.
sidebar_current: "docs-commands"
description: "An introduction to the terraform command and its available subcommands."
--- ---
# Basic CLI Features # Basic CLI Features
@ -17,8 +15,8 @@ of this page.
We refer to the `terraform` command line tool as "Terraform CLI" elsewhere We refer to the `terraform` command line tool as "Terraform CLI" elsewhere
in the documentation. This terminology is often used to distinguish it from in the documentation. This terminology is often used to distinguish it from
other components you might use in the Terraform product family, such as other components you might use in the Terraform product family, such as
[Terraform Cloud](/docs/cloud/) or [Terraform Cloud](/cloud-docs) or
the various [Terraform providers](/docs/language/providers/index.html), which the various [Terraform providers](/language/providers), which
are developed and released separately from Terraform CLI. are developed and released separately from Terraform CLI.
To view a list of the commands available in your current Terraform version, To view a list of the commands available in your current Terraform version,
@ -100,7 +98,7 @@ will be read or written in the given directory instead.
There are two exceptions where Terraform will use the original working directory There are two exceptions where Terraform will use the original working directory
even when you specify `-chdir=...`: even when you specify `-chdir=...`:
* Settings in the [CLI Configuration](/docs/cli/config/config-file.html) are not for a specific * Settings in the [CLI Configuration](/cli/config/config-file) are not for a specific
subcommand and Terraform processes them before acting on the `-chdir` subcommand and Terraform processes them before acting on the `-chdir`
option. option.
@ -153,7 +151,7 @@ Checkpoint itself can be entirely disabled for all HashiCorp products by
setting the environment variable `CHECKPOINT_DISABLE` to any non-empty value. setting the environment variable `CHECKPOINT_DISABLE` to any non-empty value.
Alternatively, settings in Alternatively, settings in
[the CLI configuration file](/docs/cli/config/config-file.html) can be used to [the CLI configuration file](/cli/config/config-file) can be used to
disable checkpoint features. The following checkpoint-related settings are disable checkpoint features. The following checkpoint-related settings are
supported in this file: supported in this file:

46
website/docs/cli/commands/init.html.md → website/docs/cli/commands/init.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: init'
page_title: "Command: init" description: >-
sidebar_current: "docs-commands-init" The terraform init command initializes a working directory containing
description: "The terraform init command initializes a working directory containing configuration files and installs plugins for required providers." configuration files and installs plugins for required providers.
--- ---
# Command: init # Command: init
@ -74,7 +74,7 @@ activating credentials) before running `terraform init`.
## Backend Initialization ## Backend Initialization
During init, the root configuration directory is consulted for During init, the root configuration directory is consulted for
[backend configuration](/docs/language/settings/backends/configuration.html) and the chosen backend [backend configuration](/language/settings/backends/configuration) and the chosen backend
is initialized using the given configuration settings. is initialized using the given configuration settings.
Re-running init with an already-initialized backend will update the working Re-running init with an already-initialized backend will update the working
@ -96,14 +96,14 @@ when the working directory was already previously initialized for a particular
backend. backend.
The `-backend-config=...` option can be used for The `-backend-config=...` option can be used for
[partial backend configuration](/docs/language/settings/backends/configuration.html#partial-configuration), [partial backend configuration](/language/settings/backends/configuration#partial-configuration),
in situations where the backend settings are dynamic or sensitive and so cannot in situations where the backend settings are dynamic or sensitive and so cannot
be statically specified in the configuration file. be statically specified in the configuration file.
## Child Module Installation ## Child Module Installation
During init, the configuration is searched for `module` blocks, and the source During init, the configuration is searched for `module` blocks, and the source
code for referenced [modules](/docs/language/modules/develop/index.html) is retrieved from the locations code for referenced [modules](/language/modules/develop) is retrieved from the locations
given in their `source` arguments. given in their `source` arguments.
Re-running init with modules already installed will install the sources for Re-running init with modules already installed will install the sources for
@ -128,13 +128,13 @@ third-party provider registry, `terraform init` will automatically find,
download, and install the necessary provider plugins. If you cannot or do not download, and install the necessary provider plugins. If you cannot or do not
wish to install providers from their origin registries, you can customize how wish to install providers from their origin registries, you can customize how
Terraform installs providers using Terraform installs providers using
[the provider installation settings in the CLI configuration](/docs/cli/config/config-file.html#provider-installation). [the provider installation settings in the CLI configuration](/cli/config/config-file#provider-installation).
For more information about specifying which providers are required for each For more information about specifying which providers are required for each
of your modules, see [Provider Requirements](/docs/language/providers/requirements.html). of your modules, see [Provider Requirements](/language/providers/requirements).
After successful installation, Terraform writes information about the selected After successful installation, Terraform writes information about the selected
providers to [the dependency lock file](/docs/language/dependency-lock.html). providers to [the dependency lock file](/language/files/dependency-lock).
You should commit this file to your version control system to ensure that You should commit this file to your version control system to ensure that
when you run `terraform init` again in future Terraform will select exactly when you run `terraform init` again in future Terraform will select exactly
the same provider versions. Use the `-upgrade` option if you want Terraform the same provider versions. Use the `-upgrade` option if you want Terraform
@ -142,31 +142,31 @@ to ignore the dependency lock file and consider installing newer versions.
You can modify `terraform init`'s plugin behavior with the following options: You can modify `terraform init`'s plugin behavior with the following options:
- `-upgrade` Upgrade all previously-selected plugins to the newest version * `-upgrade` Upgrade all previously-selected plugins to the newest version
that complies with the configuration's version constraints. This will that complies with the configuration's version constraints. This will
cause Terraform to ignore any selections recorded in the dependency lock cause Terraform to ignore any selections recorded in the dependency lock
file, and to take the newest available version matching the configured file, and to take the newest available version matching the configured
version constraints. version constraints.
- `-get-plugins=false` — Skip plugin installation. * `-get-plugins=false` — Skip plugin installation.
-> Note: Since Terraform 0.13, this option has been superseded by the -> Note: Since Terraform 0.13, this option has been superseded by the
[`provider_installation`](/docs/cli/config/config-file.html#provider-installation) and [`provider_installation`](/cli/config/config-file#provider-installation) and
[`plugin_cache_dir`](/docs/cli/config/config-file.html#plugin_cache_dir) settings. [`plugin_cache_dir`](/cli/config/config-file#plugin_cache_dir) settings.
It should not be used in Terraform versions 0.13+, and this option It should not be used in Terraform versions 0.13+, and this option
was removed in Terraform 0.15. was removed in Terraform 0.15.
- `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from * `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from
the specified directory, as if it had been configured as a `filesystem_mirror` the specified directory, as if it had been configured as a `filesystem_mirror`
in the CLI configuration. If you intend to routinely use a particular in the CLI configuration. If you intend to routinely use a particular
filesystem mirror then we recommend filesystem mirror then we recommend
[configuring Terraform's installation methods globally](/docs/cli/config/config-file.html#provider-installation). [configuring Terraform's installation methods globally](/cli/config/config-file#provider-installation).
You can use `-plugin-dir` as a one-time override for exceptional situations, You can use `-plugin-dir` as a one-time override for exceptional situations,
such as if you are testing a local build of a provider plugin you are such as if you are testing a local build of a provider plugin you are
currently developing. currently developing.
- `-lockfile=MODE` Set a dependency lockfile mode. * `-lockfile=MODE` Set a dependency lockfile mode.
The valid values for the lockfile mode are as follows: The valid values for the lockfile mode are as follows:
- readonly: suppress the lockfile changes, but verify checksums against the * readonly: suppress the lockfile changes, but verify checksums against the
information already recorded. It conflicts with the `-upgrade` flag. If you information already recorded. It conflicts with the `-upgrade` flag. If you
update the lockfile with third-party dependency management tools, it would be update the lockfile with third-party dependency management tools, it would be
useful to control when it changes explicitly. useful to control when it changes explicitly.
@ -192,7 +192,7 @@ 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 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 plan to remove it in Terraform v0.15. 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](/cli/commands/#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
current working directory. current working directory.
@ -200,6 +200,6 @@ current working directory.
If your previous use of this legacy pattern was also relying on Terraform If your previous use of this legacy pattern was also relying on Terraform
writing the `.terraform` subdirectory into the current working directory even writing the `.terraform` subdirectory into the current working directory even
though the root module directory was overridden, use though the root module directory was overridden, use
[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#tf_data_dir) [the `TF_DATA_DIR` environment variable](/cli/config/environment-variables#tf_data_dir)
to direct Terraform to write the `.terraform` directory to a location other to direct Terraform to write the `.terraform` directory to a location other
than the current working directory. than the current working directory.

16
website/docs/cli/commands/login.html.md → website/docs/cli/commands/login.mdx
View File

@ -1,9 +1,9 @@
--- ---
layout: "docs" page_title: 'Command: login'
page_title: "Command: login" description: >-
sidebar_current: "docs-commands-login" The terraform login command can be used to automatically obtain and save an
description: |- API token for Terraform Cloud, Terraform Enterprise, or any other host that
The terraform login command can be used to automatically obtain and save an API token for Terraform Cloud, Terraform Enterprise, or any other host that offers Terraform services. offers Terraform services.
--- ---
# Command: login # Command: login
@ -15,7 +15,7 @@ API token for Terraform Cloud, Terraform Enterprise, or any other host that offe
where it is possible to launch a web browser on the same host where Terraform where it is possible to launch a web browser on the same host where Terraform
is running. If you are running Terraform in an unattended automation scenario, is running. If you are running Terraform in an unattended automation scenario,
you can you can
[configure credentials manually in the CLI configuration](https://www.terraform.io/docs/cli/config/config-file.html#credentials). [configure credentials manually in the CLI configuration](/cli/config/config-file#credentials).
## Usage ## Usage
@ -34,12 +34,12 @@ not as desired.
If you don't wish to store your API token in the default location, you can If you don't wish to store your API token in the default location, you can
optionally configure a optionally configure a
[credentials helper program](/docs/cli/config/config-file.html#credentials-helpers) which knows [credentials helper program](/cli/config/config-file#credentials-helpers) which knows
how to store and later retrieve credentials in some other system, such as how to store and later retrieve credentials in some other system, such as
your organization's existing secrets management system. your organization's existing secrets management system.
## Login Server Support ## Login Server Support
The `terraform login` command works with any server supporting the The `terraform login` command works with any server supporting the
[login protocol](/docs/internals/login-protocol.html), including Terraform Cloud [login protocol](/internals/login-protocol), including Terraform Cloud
and Terraform Enterprise. and Terraform Enterprise.

11
website/docs/cli/commands/logout.html.md → website/docs/cli/commands/logout.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: logout'
page_title: "Command: logout" description: >-
sidebar_current: "docs-commands-logout" The terraform logout command is used to remove credentials stored by terraform
description: |- login.
The terraform logout command is used to remove credentials stored by terraform login.
--- ---
# Command: logout # Command: logout
@ -26,5 +25,5 @@ the remote server, so it will remain valid until manually revoked.
By default, Terraform will remove the token stored in plain text in a local CLI By default, Terraform will remove the token stored in plain text in a local CLI
configuration file called `credentials.tfrc.json`. If you have configured a configuration file called `credentials.tfrc.json`. If you have configured a
[credentials helper program](/docs/cli/config/config-file.html#credentials-helpers), Terraform [credentials helper program](/cli/config/config-file#credentials-helpers), Terraform
will use the helper's `forget` command to remove it. will use the helper's `forget` command to remove it.

25
website/docs/cli/commands/output.html.md → website/docs/cli/commands/output.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: output'
page_title: "Command: output" description: >-
sidebar_current: "docs-commands-output" The `terraform output` command is used to extract the value of an output
description: |- variable from the state file.
The `terraform output` command is used to extract the value of an output variable from the state file.
--- ---
# Command: output # Command: output
@ -22,20 +21,20 @@ output is printed.
The command-line flags are all optional. The list of available flags are: The command-line flags are all optional. The list of available flags are:
* `-json` - If specified, the outputs are formatted as a JSON object, with * `-json` - If specified, the outputs are formatted as a JSON object, with
a key per output. If `NAME` is specified, only the output specified will be a key per output. If `NAME` is specified, only the output specified will be
returned. This can be piped into tools such as `jq` for further processing. returned. This can be piped into tools such as `jq` for further processing.
* `-raw` - If specified, Terraform will convert the specified output value to a * `-raw` - If specified, Terraform will convert the specified output value to a
string and print that string directly to the output, without any special string and print that string directly to the output, without any special
formatting. This can be convenient when working with shell scripts, but formatting. This can be convenient when working with shell scripts, but
it only supports string, number, and boolean values. Use `-json` instead it only supports string, number, and boolean values. Use `-json` instead
for processing complex data types. for processing complex data types.
* `-no-color` - If specified, output won't contain any color. * `-no-color` - If specified, output won't contain any color.
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/language/state/remote.html) is used. Ignored when [remote state](/language/state/remote) is used.
-> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive -> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive
values in Terraform state will be displayed in plain text. For more information, values in Terraform state will be displayed in plain text. For more information,
see [Sensitive Data in State](/docs/language/state/sensitive-data.html). see [Sensitive Data in State](/language/state/sensitive-data).
## Examples ## Examples

123
website/docs/cli/commands/plan.html.md → website/docs/cli/commands/plan.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: plan'
page_title: "Command: plan" description: >-
sidebar_current: "docs-commands-plan" The terraform plan command creates an execution plan with a preview of the
description: "The terraform plan command creates an execution plan with a preview of the changes that Terraform will make to your infrastructure." changes that Terraform will make to your infrastructure.
--- ---
# Command: plan # Command: plan
@ -31,12 +31,12 @@ to be taken.
If you are using Terraform directly in an interactive terminal and you expect If you are using Terraform directly in an interactive terminal and you expect
to apply the changes Terraform proposes, you can alternatively run to apply the changes Terraform proposes, you can alternatively run
[`terraform apply`](./apply.html) directly. By default, the "apply" command [`terraform apply`](/cli/commands/apply) directly. By default, the "apply" command
automatically generates a new plan and prompts for you to approve it. 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 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 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 [`terraform apply`](/cli/commands/apply) as an extra argument. This two-step workflow
is primarily intended for when 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).
@ -74,9 +74,9 @@ The remaining sections on this page describe the various options:
* **[Planning Options](#planning-options)**: Alongside the special planning * **[Planning Options](#planning-options)**: Alongside the special planning
modes, there are also some options you can set in order to customize the modes, there are also some options you can set in order to customize the
planning process for unusual needs. planning process for unusual needs.
* **[Resource Targeting](#resource-targeting)** is one particular * **[Resource Targeting](#resource-targeting)** is one particular
special planning option that has some important caveats associated special planning option that has some important caveats associated
with it. with it.
* **[Other Options](#other-options)**: These change the behavior of the planning * **[Other Options](#other-options)**: These change the behavior of the planning
command itself, rather than customizing the content of the generated plan. command itself, rather than customizing the content of the generated plan.
@ -94,7 +94,7 @@ a different intended outcome:
for situations like transient development environments, where the managed for situations like transient development environments, where the managed
objects cease to be useful once the development task is complete. objects cease to be useful once the development task is complete.
Activate destroy mode using the `-destroy` command line option. Activate destroy mode using the `-destroy` command line option.
* **Refresh-only mode:** creates a plan whose goal is only to update the * **Refresh-only mode:** creates a plan whose goal is only to update the
Terraform state and any root module output values to match changes made to Terraform state and any root module output values to match changes made to
@ -103,7 +103,7 @@ a different intended outcome:
workflow (e.g. while responding to an incident) and you now need to reconcile workflow (e.g. while responding to an incident) and you now need to reconcile
Terraform's records with those changes. Terraform's records with those changes.
Activate refresh-only mode using the `-refresh-only` command line option. Activate refresh-only mode using the `-refresh-only` command line option.
In situations where we need to discuss the default planning mode that Terraform 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 uses when none of the alternative modes are selected, we refer to it as
@ -118,7 +118,7 @@ one alternative mode at the same time.
-> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is -> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is
supported only by the `terraform plan` command, and not by the supported only by the `terraform plan` command, and not by the
`terraform apply` command. To create and apply a plan in destroy mode in `terraform apply` command. To create and apply a plan in destroy mode in
earlier versions you must run [`terraform destroy`](./destroy.html). earlier versions you must run [`terraform destroy`](/cli/commands/destroy).
-> **Note:** The `-refresh-only` option is available only in Terraform v0.15.4 -> **Note:** The `-refresh-only` option is available only in Terraform v0.15.4
and later. and later.
@ -140,62 +140,62 @@ the previous section, are also available with the same meanings on
* `-refresh=false` - Disables the default behavior of synchronizing the * `-refresh=false` - Disables the default behavior of synchronizing the
Terraform state with remote objects before checking for configuration changes. Terraform state with remote objects before checking for configuration changes.
This option can potentially make the planning operation faster by reducing 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 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 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. 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 This option is not available in the "refresh only" planning mode, because
it would effectively disable the entirety of the planning operation in that it would effectively disable the entirety of the planning operation in that
case. case.
* `-replace=ADDRESS` - Instructs Terraform to plan to replace the single * `-replace=ADDRESS` - Instructs Terraform to plan to replace the single
resource instance with the given address. If the given instance would resource instance with the given address. If the given instance would
normally have caused only an "update" action, or no action at all, then normally have caused only an "update" action, or no action at all, then
Terraform will choose a "replace" action instead. Terraform will choose a "replace" action instead.
You can use this option if you have learned that a particular remote object You can use this option if you have learned that a particular remote object
has become degraded in some way. If you are using immutable infrastructure has become degraded in some way. If you are using immutable infrastructure
patterns then you may wish to respond to that by replacing the patterns then you may wish to respond to that by replacing the
malfunctioning object with a new object that has the same configuration. malfunctioning object with a new object that has the same configuration.
This option is allowed only in the normal planning mode, so this option This option is allowed only in the normal planning mode, so this option
is incompatible with the `-destroy` option. is incompatible with the `-destroy` option.
The `-replace=...` option is available only from Terraform v0.15.2 onwards. The `-replace=...` option is available only from Terraform v0.15.2 onwards.
For earlier versions, you can achieve a similar effect (with some caveats) For earlier versions, you can achieve a similar effect (with some caveats)
using [`terraform taint`](./taint.html). using [`terraform taint`](/cli/commands/taint).
* `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only * `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only
on resource instances which match the given address and on any objects that on resource instances which match the given address and on any objects that
those instances depend on. those instances depend on.
This command is for exceptional use only. See This command is for exceptional use only. See
[Resource Targeting](#resource-targeting) [Resource Targeting](#resource-targeting)
below for more information. below for more information.
* `-var 'NAME=VALUE'` - Sets a value for a single * `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](/docs/language/values/variables.html) declared in the [input variable](/language/values/variables) declared in the
root module of the configuration. Use this option multiple times to set root module of the configuration. Use this option multiple times to set
more than one variable. For more information see more than one variable. For more information see
[Input Variables on the Command Line](#input-variables-on-the-command-line), [Input Variables on the Command Line](#input-variables-on-the-command-line),
below. below.
* `-var-file=FILENAME` - Sets values for potentially many * `-var-file=FILENAME` - Sets values for potentially many
[input variables](/docs/language/values/variables.html) declared in the [input variables](/language/values/variables) declared in the
root module of the configuration, using definitions from a root module of the configuration, using definitions from a
["tfvars" file](/docs/language/values/variables.html#variable-definitions-tfvars-files). ["tfvars" file](/language/values/variables#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file. 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 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, module, aside from the `-var` and `-var-file` options. For more information,
see see
[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables). [Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables).
### Input Variables on the Command Line ### Input Variables on the Command Line
You can use the `-var` command line option to specify values for You can use the `-var` command line option to specify values for
[input variables](/docs/language/values/variables.html) declared in your [input variables](/language/values/variables) declared in your
root module. root module.
However, to do so will require writing a command line that is parsable both However, to do so will require writing a command line that is parsable both
@ -242,7 +242,7 @@ so we do not recommend using Terraform with PowerShell when you are on Windows.
Use Windows Command Prompt instead. Use Windows Command Prompt instead.
The appropriate syntax for writing the variable value is different depending The appropriate syntax for writing the variable value is different depending
on the variable's [type constraint](/docs/language/expressions/type-constraints.html). on the variable's [type constraint](/language/expressions/type-constraints).
The primitive types `string`, `number`, and `bool` all expect a direct string The primitive types `string`, `number`, and `bool` all expect a direct string
value with no special punctuation except that required by your shell, as value with no special punctuation except that required by your shell, as
shown in the above examples. For all other type constraints, including list, shown in the above examples. For all other type constraints, including list,
@ -262,8 +262,7 @@ terraform plan -var "name=[\"a\", \"b\", \"c\"]"
Similar constraints apply when setting input variables using environment Similar constraints apply when setting input variables using environment
variables. For more information on the various methods for setting root module variables. For more information on the various methods for setting root module
input variables, see input variables, see
[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables). [Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables).
### Resource Targeting ### Resource Targeting
@ -271,7 +270,7 @@ input variables, see
You can use the `-target` option 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.
You can use [resource address syntax](/docs/cli/state/resource-addressing.html) You can use [resource address syntax](/cli/state/resource-addressing)
to specify the constraint. Terraform interprets the resource address as follows: to specify the constraint. Terraform interprets the resource address as follows:
* If the given address identifies one specific resource instance, Terraform * If the given address identifies one specific resource instance, Terraform
@ -296,14 +295,14 @@ 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
is *not recommended* to use `-target` for routine operations, since this can is _not recommended_ to use `-target` for routine operations, since this can
lead to undetected configuration drift and confusion about how the true state lead to undetected configuration drift and confusion about how the true state
of resources relates to configuration. of resources relates to configuration.
Instead of using `-target` as a means to operate on isolated portions of very Instead of using `-target` as a means to operate on isolated portions of very
large configurations, prefer instead to break large configurations into large configurations, prefer instead to break large configurations into
several smaller configurations that can each be independently applied. several smaller configurations that can each be independently applied.
[Data sources](/docs/language/data-sources/index.html) can be used to access [Data sources](/language/data-sources) can be used to access
information about resources created in other configurations, allowing 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.
@ -339,11 +338,11 @@ The available options are:
This implies `-input=false`, so the configuration must have no unassigned This implies `-input=false`, so the configuration must have no unassigned
variable values to continue. variable values to continue.
[machine-readable-ui]: /docs/internals/machine-readable-ui.html [machine-readable-ui]: /internals/machine-readable-ui
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before
@ -359,28 +358,28 @@ The available options are:
the planned changes, and to some other Terraform commands that can work with the planned changes, and to some other Terraform commands that can work with
saved plan files. saved plan files.
Terraform will allow any filename for the plan file, but a typical 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 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 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 then Terraform will try to interpret the file as a configuration source
file, which will then cause syntax errors for subsequent commands. file, which will then cause syntax errors for subsequent commands.
The generated file is not in any standard format intended for consumption The generated file is not in any standard format intended for consumption
by other software, but the file _does_ contain your full configuration, by other software, but the file _does_ contain your full configuration,
all of the values associated with planned changes, and all of the plan 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 options including the input variables. If your plan includes any sort of
sensitive data, even if obscured in Terraform's terminal output, it will 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 be saved in cleartext in the plan file. You should therefore treat any
saved plan files as potentially-sensitive artifacts. saved plan files as potentially-sensitive artifacts.
* `-parallelism=n` - Limit the number of concurrent operations as Terraform * `-parallelism=n` - Limit the number of concurrent operations as Terraform
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults [walks the graph](/internals/graph#walking-the-graph). Defaults
to 10. to 10.
For configurations using For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/language/settings/backends/local) only,
`terraform plan` accepts the legacy command line option `terraform plan` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`](/language/settings/backends/local#command-line-arguments).
### Passing a Different Configuration Directory ### Passing a Different Configuration Directory
@ -390,7 +389,7 @@ module instead of the current working directory.
That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. 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 If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](./#switching-working-directory-with-chdir) [the `-chdir` global option](/cli/commands/#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
current working directory. current working directory.
@ -398,6 +397,6 @@ current working directory.
If your previous use of this legacy pattern was also relying on Terraform If your previous use of this legacy pattern was also relying on Terraform
writing the `.terraform` subdirectory into the current working directory even writing the `.terraform` subdirectory into the current working directory even
though the root module directory was overridden, use though the root module directory was overridden, use
[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#tf_data_dir) [the `TF_DATA_DIR` environment variable](/cli/config/environment-variables#tf_data_dir)
to direct Terraform to write the `.terraform` directory to a location other to direct Terraform to write the `.terraform` directory to a location other
than the current working directory. than the current working directory.

10
website/docs/cli/commands/providers.html.md → website/docs/cli/commands/providers.mdx
View File

@ -1,14 +1,14 @@
--- ---
layout: "docs" page_title: 'Command: providers'
page_title: "Command: providers" description: >-
sidebar_current: "docs-commands-providers" The terraform providers command prints information about the providers
description: "The terraform providers command prints information about the providers required in the current configuration." required in the current configuration.
--- ---
# Command: providers # Command: providers
The `terraform providers` command shows information about the The `terraform providers` command shows information about the
[provider requirements](/docs/language/providers/requirements.html) of the [provider requirements](/language/providers/requirements) of the
configuration in the current working directory, as an aid to understanding configuration in the current working directory, as an aid to understanding
where each requirement was detected from. where each requirement was detected from.

56
website/docs/cli/commands/providers/lock.html.md → website/docs/cli/commands/providers/lock.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Command: providers lock'
page_title: "Command: providers lock"
sidebar_current: "docs-commands-providers-lock"
description: |- description: |-
The `terraform providers lock` command adds new provider selection information The `terraform providers lock` command adds new provider selection information
to the dependency lock file without initializing the referenced providers. to the dependency lock file without initializing the referenced providers.
@ -11,31 +9,31 @@ description: |-
The `terraform providers lock` consults upstream registries (by default) in The `terraform providers lock` consults upstream registries (by default) in
order to write provider dependency information into order to write provider dependency information into
[the dependency lock file](/docs/language/dependency-lock.html). [the dependency lock file](/language/files/dependency-lock).
The common way to update the dependency lock file is as a side-effect of normal The common way to update the dependency lock file is as a side-effect of normal
provider installation during provider installation during
[`terraform init`](/docs/cli/commands/init.html), but there are several situations where that [`terraform init`](/cli/commands/init), but there are several situations where that
automatic approach may not be sufficient: automatic approach may not be sufficient:
* If you are running Terraform in an environment that uses * If you are running Terraform in an environment that uses
[alternative provider installation methods](/docs/cli/config/config-file.html#provider-installation), [alternative provider installation methods](/cli/config/config-file#provider-installation),
such as filesystem or network mirrors, normal provider installation will not such as filesystem or network mirrors, normal provider installation will not
access the origin registry for a provider and therefore Terraform will not access the origin registry for a provider and therefore Terraform will not
be able to populate all of the possible package checksums for the selected be able to populate all of the possible package checksums for the selected
provider versions. provider versions.
If you use `terraform lock` to write the official release checksums for a If you use `terraform lock` to write the official release checksums for a
provider into the dependency lock file then future `terraform init` runs provider into the dependency lock file then future `terraform init` runs
will verify the packages available in your selected mirror against the will verify the packages available in your selected mirror against the
official checksums previously recorded, giving additional certainty that official checksums previously recorded, giving additional certainty that
the mirror is serving the provider packages it is claiming to. the mirror is serving the provider packages it is claiming to.
* If your team runs Terraform across a number of different platforms (e.g. * If your team runs Terraform across a number of different platforms (e.g.
on both Windows and Linux) and the upstream registry for a provider is unable on both Windows and Linux) and the upstream registry for a provider is unable
to provide signed checksums using the latest hashing scheme, subsequent runs to provide signed checksums using the latest hashing scheme, subsequent runs
of Terraform on other platforms may of Terraform on other platforms may
[add additional checksums to the lock file](/docs/language/dependency-lock.html#new-provider-package-checksums). [add additional checksums to the lock file](/language/files/dependency-lock#new-provider-package-checksums).
You can avoid that by pre-populating hashes for all of the platforms you You can avoid that by pre-populating hashes for all of the platforms you
intend to use, using the `terraform providers lock` command. intend to use, using the `terraform providers lock` command.
@ -49,17 +47,17 @@ With no additional command line arguments, `terraform providers lock` will
analyze the configuration in the current working directory to find all of analyze the configuration in the current working directory to find all of
the providers it depends on, and it will fetch the necessary data about those the providers it depends on, and it will fetch the necessary data about those
providers from their origin registries and then update providers from their origin registries and then update
[the dependency lock file](/docs/language/dependency-lock.html) to [the dependency lock file](/language/files/dependency-lock) to
include a selected version for each provider and all of the package checksums include a selected version for each provider and all of the package checksums
that are covered by the provider developer's cryptographic signature. that are covered by the provider developer's cryptographic signature.
~> **Warning:** The `terraform providers lock` command prints information ~> **Warning:** The `terraform providers lock` command prints information
about what it has fetched and whether each package was signed using a about what it has fetched and whether each package was signed using a
cryptographic signature, but it cannot automatically verify that the cryptographic signature, but it cannot automatically verify that the
providers are trustworthy and that they comply with your local system providers are trustworthy and that they comply with your local system
policies or relevant regulations. Review the signing key information policies or relevant regulations. Review the signing key information
in the output to confirm that you trust all of the signers before committing in the output to confirm that you trust all of the signers before committing
the updated lock file to your version control system. the updated lock file to your version control system.
If you list one or more provider source addresses on the command line then If you list one or more provider source addresses on the command line then
`terraform providers lock` will restrict its work only to those providers, `terraform providers lock` will restrict its work only to those providers,
@ -74,21 +72,21 @@ You can customize the default behavior using the following additional option:
* `-net-mirror=URL` - Direct Terraform to look for provider packages in the * `-net-mirror=URL` - Direct Terraform to look for provider packages in the
given network mirror service, instead of in upstream registries. The given network mirror service, instead of in upstream registries. The
given URL must implement given URL must implement
[the Terraform provider network mirror protocol](/docs/internals/provider-network-mirror-protocol.html). [the Terraform provider network mirror protocol](/internals/provider-network-mirror-protocol).
* `-platform=OS_ARCH` - Specify a platform you intend to use to work with this * `-platform=OS_ARCH` - Specify a platform you intend to use to work with this
Terraform configuration. Terraform will ensure that the providers are all Terraform configuration. Terraform will ensure that the providers are all
available for the given platform and will save enough package checksums in available for the given platform and will save enough package checksums in
the lock file to support _at least_ the specified platforms. the lock file to support _at least_ the specified platforms.
Use this option multiple times to include checksums for multiple target
systems.
Target platform names consist of an operating system and a CPU Use this option multiple times to include checksums for multiple target
architecture. For example, `linux_amd64` selects the Linux operating system systems.
running on an AMD64 or x86_64 CPU.
There is more detail on this option in the following section. Target platform names consist of an operating system and a CPU
architecture. For example, `linux_amd64` selects the Linux operating system
running on an AMD64 or x86_64 CPU.
There is more detail on this option in the following section.
## Specifying Target Platforms ## Specifying Target Platforms
@ -150,7 +148,7 @@ multiple times and specify a different subset of your providers each time.
The `-fs-mirror` and `-net-mirror` options have the same meaning as The `-fs-mirror` and `-net-mirror` options have the same meaning as
`filesystem_mirror` and `network_mirror` blocks in `filesystem_mirror` and `network_mirror` blocks in
[the provider installation methods configuration](/docs/cli/config/config-file.html#provider-installation), [the provider installation methods configuration](/cli/config/config-file#provider-installation),
but specify only a single method in order to be explicit about where you but specify only a single method in order to be explicit about where you
intend to derive the package checksum information from. intend to derive the package checksum information from.
@ -167,4 +165,4 @@ If you wish, you can publish your in-house providers via an in-house provider
registry, which will then allow locking and installation of those providers registry, which will then allow locking and installation of those providers
without any special options or additional CLI configuration. For more without any special options or additional CLI configuration. For more
information, see information, see
[the provider registry protocol](/docs/internals/provider-registry-protocol.html). [the provider registry protocol](/internals/provider-registry-protocol).

8
website/docs/cli/commands/providers/mirror.html.md → website/docs/cli/commands/providers/mirror.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Command: providers mirror'
page_title: "Command: providers mirror"
sidebar_current: "docs-commands-providers-mirror"
description: |- description: |-
The `terraform providers mirror` command downloads the providers required The `terraform providers mirror` command downloads the providers required
for the current configuration and copies them into a directory in the local for the current configuration and copies them into a directory in the local
@ -19,7 +17,7 @@ from provider registries as part of initializing the current working directory.
Sometimes Terraform is running in an environment where that isn't possible, Sometimes Terraform is running in an environment where that isn't possible,
such as on an isolated network without access to the Terraform Registry. In such as on an isolated network without access to the Terraform Registry. In
that case, that case,
[explicit installation method configuration](/docs/cli/config/config-file.html#explicit-installation-method-configuration) [explicit installation method configuration](/cli/config/config-file#explicit-installation-method-configuration)
allows you to configure Terraform, when running on a particular system, to allows you to configure Terraform, when running on a particular system, to
consult only a local filesystem directory where you've created a local mirror consult only a local filesystem directory where you've created a local mirror
of the necessary plugins, and to skip accessing the upstream registry at all. of the necessary plugins, and to skip accessing the upstream registry at all.
@ -41,7 +39,7 @@ themselves.
Terraform will also generate various `.json` index files which contain suitable Terraform will also generate various `.json` index files which contain suitable
responses to implement responses to implement
[the network mirror protocol](/docs/internals/provider-network-mirror-protocol.html), [the network mirror protocol](/internals/provider-network-mirror-protocol),
if you upload the resulting directory to a static website host. Terraform if you upload the resulting directory to a static website host. Terraform
ignores those index files when using the directory as a filesystem mirror, ignores those index files when using the directory as a filesystem mirror,
because the directory entries themselves are authoritative in that case. because the directory entries themselves are authoritative in that case.

14
website/docs/cli/commands/providers/schema.html.md → website/docs/cli/commands/providers/schema.mdx
View File

@ -1,9 +1,9 @@
--- ---
layout: "docs" page_title: 'Command: providers schema'
page_title: "Command: providers schema" description: >-
sidebar_current: "docs-commands-providers-schema" The `terraform providers schema` command prints detailed schemas for the
description: |- providers used
The `terraform providers schema` command prints detailed schemas for the providers used
in the current configuration. in the current configuration.
--- ---
@ -19,7 +19,7 @@ Usage: `terraform providers schema [options]`
The list of available flags are: The list of available flags are:
* `-json` - Displays the schemas in a machine-readable, JSON format. - `-json` - Displays the schemas in a machine-readable, JSON format.
Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options.
@ -34,7 +34,7 @@ value `"1.0"`. The semantics of this version are:
version. version.
We will introduce new major versions only within the bounds of We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). [the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises).
## Format Summary ## Format Summary

12
website/docs/cli/commands/push.html.md → website/docs/cli/commands/push.mdx
View File

@ -1,16 +1,14 @@
--- ---
layout: "docs" page_title: 'Command: push'
page_title: "Command: push" description: >-
sidebar_current: "docs-commands-push" DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced
description: |- the old `terraform push` command.
DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced the old `terraform push` command.
--- ---
# Command: push # Command: push
!> **Important:** The `terraform push` command is no longer functional. Its functionality was replaced and surpassed by [the `remote` backend](/docs/language/settings/backends/remote.html), which works with current versions of Terraform Cloud. The `remote` backend allows you to run remote operations directly from the command line, and displays real-time output from the remote run environment. !> **Important:** The `terraform push` command is no longer functional. Its functionality was replaced and surpassed by [the `remote` backend](/language/settings/backends/remote), which works with current versions of Terraform Cloud. The `remote` backend allows you to run remote operations directly from the command line, and displays real-time output from the remote run environment.
The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise. The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise.
The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional. The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional.

14
website/docs/cli/commands/refresh.html.md → website/docs/cli/commands/refresh.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Command: refresh'
page_title: "Command: refresh"
sidebar_current: "docs-commands-refresh"
description: |- description: |-
The `terraform refresh` command reads the current settings from all managed The `terraform refresh` command reads the current settings from all managed
remote objects and updates the Terraform state to match. remote objects and updates the Terraform state to match.
@ -14,19 +12,19 @@ description: |-
The `terraform refresh` command reads the current settings from all managed The `terraform refresh` command reads the current settings from all managed
remote objects and updates the Terraform state to match. remote objects and updates the Terraform state to match.
~> *Warning:* This command is deprecated, because its default behavior is ~> _Warning:_ This command is deprecated, because its default behavior is
unsafe if you have misconfigured credentials for any of your providers. unsafe if you have misconfigured credentials for any of your providers.
See below for more information and recommended alternatives. See below for more information and recommended alternatives.
This won't modify your real remote objects, but it will modify the This won't modify your real remote objects, but it will modify the
[Terraform state](/docs/language/state/). [Terraform state](/language/state).
You shouldn't typically need to use this command, because Terraform You shouldn't typically need to use this command, because Terraform
automatically performs the same refreshing actions as a part of creating automatically performs the same refreshing actions as a part of creating
a plan in both the a plan in both the
[`terraform plan`](./plan.html) [`terraform plan`](/cli/commands/plan)
and and
[`terraform apply`](./apply.html) [`terraform apply`](/cli/commands/apply)
commands. This command is here primarily for backward compatibility, but commands. This command is here primarily for backward compatibility, but
we don't recommend using it because it provides no opportunity to review we don't recommend using it because it provides no opportunity to review
the effects of the operation before updating the state. the effects of the operation before updating the state.
@ -42,7 +40,7 @@ terraform apply -refresh-only -auto-approve
``` ```
Consequently, it supports all of the same options as Consequently, it supports all of the same options as
[`terraform apply`](./apply.html) except that it does not accept a saved [`terraform apply`](/cli/commands/apply) except that it does not accept a saved
plan file, it doesn't allow selecting a planning mode other than "refresh only", plan file, it doesn't allow selecting a planning mode other than "refresh only",
and `-auto-approve` is always enabled. and `-auto-approve` is always enabled.

15
website/docs/cli/commands/show.html.md → website/docs/cli/commands/show.mdx
View File

@ -1,9 +1,10 @@
--- ---
layout: "docs" page_title: 'Command: show'
page_title: "Command: show" description: >-
sidebar_current: "docs-commands-show" The `terraform show` command is used to provide human-readable output from a
description: |- state or plan file. This can be used to inspect a plan to ensure that the
The `terraform show` command is used to provide human-readable output from a state or plan file. This can be used to inspect a plan to ensure that the planned operations are expected, or to inspect the current state as Terraform sees it. planned operations are expected, or to inspect the current state as Terraform
sees it.
--- ---
# Command: show # Command: show
@ -18,7 +19,7 @@ flag.
-> **Note:** When using the `-json` command-line flag, any sensitive values in -> **Note:** When using the `-json` command-line flag, any sensitive values in
Terraform state will be displayed in plain text. For more information, see Terraform state will be displayed in plain text. For more information, see
[Sensitive Data in State](/docs/language/state/sensitive-data.html). [Sensitive Data in State](/language/state/sensitive-data).
## JSON Output ## JSON Output
@ -34,7 +35,7 @@ was written, the state needs to be upgraded before it can be displayed with
`-refresh=false`. If you are viewing a state file, run `terraform refresh` `-refresh=false`. If you are viewing a state file, run `terraform refresh`
first. first.
The output format is covered in detail in [JSON Output Format](/docs/internals/json-format.html). The output format is covered in detail in [JSON Output Format](/internals/json-format).
## Usage ## Usage

11
website/docs/cli/commands/state/index.html.md → website/docs/cli/commands/state/index.mdx
View File

@ -1,16 +1,13 @@
--- ---
layout: "docs" page_title: 'Command: state'
page_title: "Command: state" description: The `terraform state` command is used for advanced state management.
sidebar_current: "docs-commands-state-index"
description: |-
The `terraform state` command is used for advanced state management.
--- ---
# State Command # State Command
The `terraform state` command is used for advanced state management. The `terraform state` command is used for advanced state management.
As your Terraform usage becomes more advanced, there are some cases where As your Terraform usage becomes more advanced, there are some cases where
you may need to modify the [Terraform state](/docs/language/state/index.html). you may need to modify the [Terraform state](/language/state).
Rather than modify the state directly, the `terraform state` commands can Rather than modify the state directly, the `terraform state` commands can
be used in many cases instead. be used in many cases instead.
@ -35,7 +32,7 @@ written to disk and the CLI usage is the same as if it were local state.
All `terraform state` subcommands that modify the state write backup All `terraform state` subcommands that modify the state write backup
files. The path of these backup file can be controlled with `-backup`. files. The path of these backup file can be controlled with `-backup`.
Subcommands that are read-only (such as [list](/docs/cli/commands/state/list.html)) Subcommands that are read-only (such as [list](/cli/commands/state/list))
do not write any backup files since they aren't modifying the state. do not write any backup files since they aren't modifying the state.
Note that backups for state modification _can not be disabled_. Due to Note that backups for state modification _can not be disabled_. Due to

15
website/docs/cli/commands/state/list.html.md → website/docs/cli/commands/state/list.mdx
View File

@ -1,15 +1,14 @@
--- ---
layout: "docs" page_title: 'Command: state list'
page_title: "Command: state list" description: >-
sidebar_current: "docs-commands-state-sub-list" The terraform state list command is used to list resources within a Terraform
description: |- state.
The terraform state list command is used to list resources within a Terraform state.
--- ---
# Command: state list # Command: state list
The `terraform state list` command is used to list resources within a The `terraform state list` command is used to list resources within a
[Terraform state](/docs/language/state/index.html). [Terraform state](/language/state).
## Usage ## Usage
@ -25,12 +24,12 @@ within modules are listed last.
For complex infrastructures, the state can contain thousands of resources. For complex infrastructures, the state can contain thousands of resources.
To filter these, provide one or more patterns to the command. Patterns are To filter these, provide one or more patterns to the command. Patterns are
in [resource addressing format](/docs/cli/state/resource-addressing.html). in [resource addressing format](/cli/state/resource-addressing).
The command-line flags are all optional. The list of available flags are: The command-line flags are all optional. The list of available flags are:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/language/state/remote.html) is used. Ignored when [remote state](/language/state/remote) is used.
* `-id=id` - ID of resources to show. Ignored when unset. * `-id=id` - ID of resources to show. Ignored when unset.
## Example: All Resources ## Example: All Resources

40
website/docs/cli/commands/state/mv.html.md → website/docs/cli/commands/state/mv.mdx
View File

@ -1,14 +1,13 @@
--- ---
layout: "docs" page_title: 'Command: state mv'
page_title: "Command: state mv" description: >-
sidebar_current: "docs-commands-state-sub-mv" The `terraform state mv` command changes bindings in Terraform state,
description: |- associating existing remote objects with new resource instances.
The `terraform state mv` command changes bindings in Terraform state, associating existing remote objects with new resource instances.
--- ---
# Command: state mv # Command: state mv
The main function of [Terraform state](/docs/language/state/index.html) is The main function of [Terraform state](/language/state) is
to track the bindings between resource instance addresses in your configuration to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally Terraform automatically and the remote objects they represent. Normally Terraform automatically
updates the state in response to actions taken when applying a plan, such as updates the state in response to actions taken when applying a plan, such as
@ -29,7 +28,7 @@ remote objects currently associated with the source to be tracked instead
by the destination. by the destination.
Both the source and destination addresses must use Both the source and destination addresses must use
[resource address syntax](/docs/cli/state/resource-addressing.html), and [resource address syntax](/cli/state/resource-addressing), and
they must both refer to the same kind of object: you can only move a resource they must both refer to the same kind of object: you can only move a resource
instance to another resource instance, a whole module instance to another instance to another resource instance, a whole module instance to another
whole module instance, etc. Furthermore, if you are moving a resource or whole module instance, etc. Furthermore, if you are moving a resource or
@ -45,7 +44,7 @@ object and create a new object at the new address, and so `terraform state mv`
allows you to override that interpretation by pre-emptively attaching the allows you to override that interpretation by pre-emptively attaching the
existing object to the new address in Terraform. existing object to the new address in Terraform.
~> *Warning:* If you are using Terraform in a collaborative environment, you ~> _Warning:_ If you are using Terraform in a collaborative environment, you
must ensure that when you are using `terraform state mv` for a code refactoring must ensure that when you are using `terraform state mv` for a code refactoring
purpose you communicate carefully with your coworkers to ensure that nobody purpose you communicate carefully with your coworkers to ensure that nobody
makes any other changes between your configuration change and your makes any other changes between your configuration change and your
@ -59,8 +58,8 @@ This command also accepts the following options:
address without actually "forgetting" any of them. address without actually "forgetting" any of them.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before
@ -68,23 +67,22 @@ This command also accepts the following options:
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
only, `terraform state mv` only, `terraform state mv`
also accepts the option also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). [`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
The legacy options [`-backup` and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments) The legacy options [`-backup` and `-backup-out`](/language/settings/backends/local#command-line-arguments)
operate on a local state file only. Configurations using operate on a local state file only. Configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
must specify a local state file with the [`-state`](/docs/language/settings/backends/local.html#command-line-arguments) must specify a local state file with the [`-state`](/language/settings/backends/local#command-line-arguments)
option in order to use the [`-backup` and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments) option in order to use the [`-backup` and `-backup-out`](/language/settings/backends/local#command-line-arguments)
options. options.
For configurations using For configurations using
[the `local` state mv](/docs/language/settings/backends/local.html) only, [the `local` state mv](/language/settings/backends/local) only,
`terraform state mv` also accepts the legacy options `terraform state mv` also accepts the legacy options
[`-state`, `-state-out`, `-backup`, and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, `-backup`, and `-backup-out`](/language/settings/backends/local#command-line-arguments).
## Example: Rename a Resource ## Example: Rename a Resource
@ -136,7 +134,7 @@ terraform state mv module.app module.parent.module.app
## Example: Move a Particular Instance of a Resource using `count` ## Example: Move a Particular Instance of a Resource using `count`
A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html) A resource defined with [the `count` meta-argument](/language/meta-arguments/count)
has multiple instances that are each identified by an integer. You can has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given select a particular instance by including an explicit index in your given
address: address:
@ -161,7 +159,7 @@ The above examples show the typical quoting syntax for Unix-style shells.
## Example: Move a Resource configured with for_each ## Example: Move a Resource configured with for_each
A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html) A resource defined with [the `for_each` meta-argument](/language/meta-arguments/for_each)
has multiple instances that are each identified by an string. You can has multiple instances that are each identified by an string. You can
select a particular instance by including an explicit key in your given select a particular instance by including an explicit key in your given
address. address.

11
website/docs/cli/commands/state/pull.html.md → website/docs/cli/commands/state/pull.mdx
View File

@ -1,15 +1,14 @@
--- ---
layout: "docs" page_title: 'Command: state pull'
page_title: "Command: state pull" description: >-
sidebar_current: "docs-commands-state-sub-pull" The `terraform state pull` command is used to manually download and output the
description: |- state from remote state.
The `terraform state pull` command is used to manually download and output the state from remote state.
--- ---
# Command: state pull # Command: state pull
The `terraform state pull` command is used to manually download and output The `terraform state pull` command is used to manually download and output
the state from [remote state](/docs/language/state/remote.html). This command also the state from [remote state](/language/state/remote). This command also
works with local state. works with local state.
## Usage ## Usage

50
website/docs/cli/commands/state/push.html.md
View File

@ -1,50 +0,0 @@
---
layout: "docs"
page_title: "Command: state push"
sidebar_current: "docs-commands-state-sub-push"
description: |-
The `terraform state push` command pushes items to the Terraform state.
---
# Command: state push
The `terraform state push` command is used to manually upload a local
state file to [remote state](/docs/language/state/remote.html). This command also
works with local state.
This command should rarely be used. It is meant only as a utility in case
manual intervention is necessary with the remote state.
## Usage
Usage: `terraform state push [options] PATH`
This command will push the state specified by PATH to the currently
configured [backend](/docs/language/settings/backends/index.html).
If PATH is "-" then the state data to push is read from stdin. This data
is loaded completely into memory and verified prior to being written to
the destination state.
Terraform will perform a number of safety checks to prevent you from
making changes that appear to be unsafe:
* **Differing lineage**: If the "lineage" value in the state differs,
Terraform will not allow you to push the state. A differing lineage
suggests that the states are completely different and you may lose
data.
* **Higher remote serial**: If the "serial" value in the destination state
is higher than the state being pushed, Terraform will prevent the push.
A higher serial suggests that data is in the destination state that isn't
accounted for in the local state being pushed.
Both of these safety checks can be disabled with the `-force` flag.
**This is not recommended.** If you disable the safety checks and are
pushing state, the destination state will be overwritten.
For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html)
only, `terraform state push`
also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).

47
website/docs/cli/commands/state/push.mdx Normal file
View File

@ -0,0 +1,47 @@
---
page_title: 'Command: state push'
description: The `terraform state push` command pushes items to the Terraform state.
---
# Command: state push
The `terraform state push` command is used to manually upload a local
state file to [remote state](/language/state/remote). This command also
works with local state.
This command should rarely be used. It is meant only as a utility in case
manual intervention is necessary with the remote state.
## Usage
Usage: `terraform state push [options] PATH`
This command will push the state specified by PATH to the currently
configured [backend](/language/settings/backends).
If PATH is "-" then the state data to push is read from stdin. This data
is loaded completely into memory and verified prior to being written to
the destination state.
Terraform will perform a number of safety checks to prevent you from
making changes that appear to be unsafe:
- **Differing lineage**: If the "lineage" value in the state differs,
Terraform will not allow you to push the state. A differing lineage
suggests that the states are completely different and you may lose
data.
- **Higher remote serial**: If the "serial" value in the destination state
is higher than the state being pushed, Terraform will prevent the push.
A higher serial suggests that data is in the destination state that isn't
accounted for in the local state being pushed.
Both of these safety checks can be disabled with the `-force` flag.
**This is not recommended.** If you disable the safety checks and are
pushing state, the destination state will be overwritten.
For configurations using
[the `remote` backend](/language/settings/backends/remote)
only, `terraform state push`
also accepts the option
[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).

24
website/docs/cli/commands/state/replace-provider.html.md → website/docs/cli/commands/state/replace-provider.mdx
View File

@ -1,15 +1,14 @@
--- ---
layout: "docs" page_title: 'Command: state replace-provider'
page_title: "Command: state replace-provider" description: >-
sidebar_current: "docs-commands-state-sub-replace-provider" The `terraform state replace-provider` command replaces the provider for
description: |- resources in the Terraform state.
The `terraform state replace-provider` command replaces the provider for resources in the Terraform state.
--- ---
# Command: state replace-provider # Command: state replace-provider
The `terraform state replace-provider` command is used to replace the provider The `terraform state replace-provider` command is used to replace the provider
for resources in a [Terraform state](/docs/language/state/index.html). for resources in a [Terraform state](/language/state).
## Usage ## Usage
@ -28,22 +27,21 @@ This command also accepts the following options:
* `-auto-approve` - Skip interactive approval. * `-auto-approve` - Skip interactive approval.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=0s` - Duration to retry a state lock. * `-lock-timeout=0s` - Duration to retry a state lock.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
only, `terraform state replace-provider` only, `terraform state replace-provider`
also accepts the option also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). [`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
For configurations using For configurations using
[the `local` state rm](/docs/language/settings/backends/local.html) only, [the `local` state rm](/language/settings/backends/local) only,
`terraform state replace-provider` also accepts the legacy options `terraform state replace-provider` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).
## Example ## Example

31
website/docs/cli/commands/state/rm.html.md → website/docs/cli/commands/state/rm.mdx
View File

@ -1,14 +1,13 @@
--- ---
layout: "docs" page_title: 'Command: state rm'
page_title: "Command: state rm" description: >-
sidebar_current: "docs-commands-state-sub-rm" The `terraform state rm` command removes bindings from the Terraform state,
description: |- causing Terraform to "forget about" existing objects.
The `terraform state rm` command removes bindings from the Terraform state, causing Terraform to "forget about" existing objects.
--- ---
# Command: state rm # Command: state rm
The main function of [Terraform state](/docs/language/state/index.html) is The main function of [Terraform state](/language/state) is
to track the bindings between resource instance addresses in your configuration to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally Terraform automatically and the remote objects they represent. Normally Terraform automatically
updates the state in response to actions taken when applying a plan, such as updates the state in response to actions taken when applying a plan, such as
@ -24,13 +23,13 @@ to exist in the remote system.
Usage: `terraform state rm [options] ADDRESS...` Usage: `terraform state rm [options] ADDRESS...`
Terraform will search the state for any instances matching the given Terraform will search the state for any instances matching the given
[resource address](/docs/cli/state/resource-addressing.html), and remove [resource address](/cli/state/resource-addressing), and remove
the record of each one so that Terraform will no longer be tracking the the record of each one so that Terraform will no longer be tracking the
corresponding remote objects. corresponding remote objects.
This means that although the objects will still continue to exist in the This means that although the objects will still continue to exist in the
remote system, a subsequent remote system, a subsequent
[`terraform plan`](../plan.html) [`terraform plan`](/cli/commands/plan)
will include an action to create a new object for each of the "forgotten" will include an action to create a new object for each of the "forgotten"
instances. Depending on the constraints imposed by the remote system, creating instances. Depending on the constraints imposed by the remote system, creating
those objects might fail if their names or other identifiers conflict with those objects might fail if their names or other identifiers conflict with
@ -42,8 +41,8 @@ This command also accepts the following options:
address without actually "forgetting" any of them. address without actually "forgetting" any of them.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before
@ -51,15 +50,15 @@ This command also accepts the following options:
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
only, `terraform state rm` only, `terraform state rm`
also accepts the option also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). [`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
For configurations using For configurations using
[the `local` state rm](/docs/language/settings/backends/local.html) only, [the `local` state rm](/language/settings/backends/local) only,
`terraform state rm` also accepts the legacy options `terraform state rm` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).
## Example: Remove all Instances of a Resource ## Example: Remove all Instances of a Resource
@ -94,7 +93,7 @@ $ terraform state rm 'module.foo'
## Example: Remove a Particular Instance of a Resource using `count` ## Example: Remove a Particular Instance of a Resource using `count`
A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html) A resource defined with [the `count` meta-argument](/language/meta-arguments/count)
has multiple instances that are each identified by an integer. You can has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given select a particular instance by including an explicit index in your given
address: address:
@ -109,7 +108,7 @@ The above shows the typical quoting syntax for Unix-style shells.
## Example: Remove a Particular Instance of a Resource using `for_each` ## Example: Remove a Particular Instance of a Resource using `for_each`
A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html) A resource defined with [the `for_each` meta-argument](/language/meta-arguments/for_each)
has multiple instances that are each identified by an string. You can has multiple instances that are each identified by an string. You can
select a particular instance by including an explicit key in your given select a particular instance by including an explicit key in your given
address. address.

21
website/docs/cli/commands/state/show.html.md → website/docs/cli/commands/state/show.mdx
View File

@ -1,16 +1,15 @@
--- ---
layout: "docs" page_title: 'Command: state show'
page_title: "Command: state show" description: >-
sidebar_current: "docs-commands-state-sub-show" The `terraform state show` command is used to show the attributes of a single
description: |- resource in the Terraform state.
The `terraform state show` command is used to show the attributes of a single resource in the Terraform state.
--- ---
# Command: state show # Command: state show
The `terraform state show` command is used to show the attributes of a The `terraform state show` command is used to show the attributes of a
single resource in the single resource in the
[Terraform state](/docs/language/state/index.html). [Terraform state](/language/state).
## Usage ## Usage
@ -21,16 +20,16 @@ state file that matches the given address.
This command requires an address that points to a single resource in the This command requires an address that points to a single resource in the
state. Addresses are state. Addresses are
in [resource addressing format](/docs/cli/state/resource-addressing.html). in [resource addressing format](/cli/state/resource-addressing).
The command-line flags are all optional. The list of available flags are: The command-line flags are all optional. The list of available flags are:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/language/state/remote.html) is used. Ignored when [remote state](/language/state/remote) is used.
The output of `terraform state show` is intended for human consumption, not The output of `terraform state show` is intended for human consumption, not
programmatic consumption. To extract state data for use in other software, use programmatic consumption. To extract state data for use in other software, use
[`terraform show -json`](/docs/cli/commands/show.html#json-output) and decode the result [`terraform show -json`](/cli/commands/show#json-output) and decode the result
using the documented structure. using the documented structure.
## Example: Show a Resource ## Example: Show a Resource
@ -61,7 +60,7 @@ $ terraform state show 'module.foo.packet_device.worker'
## Example: Show a Resource configured with count ## Example: Show a Resource configured with count
The example below shows the first instance of a `packet_device` resource named `worker` configured with The example below shows the first instance of a `packet_device` resource named `worker` configured with
[`count`](/docs/language/meta-arguments/count.html): [`count`](/language/meta-arguments/count):
```shell ```shell
$ terraform state show 'packet_device.worker[0]' $ terraform state show 'packet_device.worker[0]'
@ -70,7 +69,7 @@ $ terraform state show 'packet_device.worker[0]'
## Example: Show a Resource configured with for_each ## Example: Show a Resource configured with for_each
The example below shows the `"example"` instance of a `packet_device` resource named `worker` configured with The example below shows the `"example"` instance of a `packet_device` resource named `worker` configured with
[`for_each`](/docs/language/meta-arguments/for_each.html): [`for_each`](/language/meta-arguments/for_each):
Linux, Mac OS, and UNIX: Linux, Mac OS, and UNIX:

26
website/docs/cli/commands/taint.html.md → website/docs/cli/commands/taint.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Command: taint'
page_title: "Command: taint"
sidebar_current: "docs-commands-taint"
description: |- description: |-
The `terraform taint` command informs Terraform that a particular object The `terraform taint` command informs Terraform that a particular object
is damaged or degraded. is damaged or degraded.
@ -14,12 +12,12 @@ become degraded or damaged. Terraform represents this by marking the
object as "tainted" in the Terraform state, in which case Terraform will object as "tainted" in the Terraform state, in which case Terraform will
propose to replace it in the next plan you create. propose to replace it in the next plan you create.
~> *Warning:* This command is deprecated, because there are better alternatives ~> _Warning:_ This command is deprecated, because there are better alternatives
available in Terraform v0.15.2 and later. See below for more details. available in Terraform v0.15.2 and later. See below for more details.
If your intent is to force replacement of a particular object even though If your intent is to force replacement of a particular object even though
there are no configuration changes that would require it, we recommend instead there are no configuration changes that would require it, we recommend instead
to use the `-replace` option with [`terraform apply`](./apply.html). to use the `-replace` option with [`terraform apply`](/cli/commands/apply).
For example: For example:
``` ```
@ -44,13 +42,13 @@ Usage: `terraform taint [options] address`
The `address` argument is the address of the resource to mark as tainted. The `address` argument is the address of the resource to mark as tainted.
The address is in The address is in
[the resource address syntax](/docs/cli/state/resource-addressing.html) syntax, [the resource address syntax](/cli/state/resource-addressing) syntax,
as shown in the output from other commands, such as: 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 will not be 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`
This command accepts the following options: This command accepts the following options:
@ -68,12 +66,12 @@ This command accepts the following options:
unit letter, such as "3s" for three seconds. unit letter, such as "3s" for three seconds.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
only, `terraform taint` only, `terraform taint`
also accepts the option also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). [`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
For configurations using For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/language/settings/backends/local) only,
`terraform taint` also accepts the legacy options `terraform taint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).

9
website/docs/cli/commands/test.html.md → website/docs/cli/commands/test.mdx
View File

@ -1,15 +1,12 @@
--- ---
layout: "docs" page_title: 'Command: test'
page_title: "Command: test" description: Part of the ongoing design research for module integration testing.
sidebar_current: "docs-commands-test"
description: |-
Part of the ongoing design research for module integration testing.
--- ---
# Command: test # Command: test
The `terraform test` command is currently serving as part of The `terraform test` command is currently serving as part of
[the module integration testing experiment](/docs/language/modules/testing-experiment.html). [the module integration testing experiment](/language/modules/testing-experiment).
It's not ready for routine use, but if you'd be interested in trying the It's not ready for routine use, but if you'd be interested in trying the
prototype functionality then we'd love to hear your feedback. See the prototype functionality then we'd love to hear your feedback. See the

20
website/docs/cli/commands/untaint.html.md → website/docs/cli/commands/untaint.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Command: untaint'
page_title: "Command: untaint"
sidebar_current: "docs-commands-untaint"
description: |- description: |-
The `terraform untaint` command tells Terraform that an object is functioning The `terraform untaint` command tells Terraform that an object is functioning
correctly, even though its creation failed or it was previously manually correctly, even though its creation failed or it was previously manually
@ -18,7 +16,7 @@ a multi-step "create" action, because Terraform can't be sure that the object
was left in a fully-functional state. was left in a fully-functional state.
You can also manually mark an object as "tainted" using the deprecated command You can also manually mark an object as "tainted" using the deprecated command
[`terraform taint`](./taint.html), although we no longer recommend that [`terraform taint`](/cli/commands/taint), although we no longer recommend that
workflow. workflow.
If Terraform currently considers a particular object as tainted but you've If Terraform currently considers a particular object as tainted but you've
@ -40,7 +38,7 @@ terraform apply -replace="aws_instance.example[0]"
Usage: `terraform untaint [options] address` Usage: `terraform untaint [options] address`
The `address` argument is a [resource address](/docs/cli/state/resource-addressing.html) The `address` argument is a [resource address](/cli/state/resource-addressing)
identifying a particular resource instance which is currently tainted. identifying a particular resource instance which is currently tainted.
This command also accepts the following options: This command also accepts the following options:
@ -51,8 +49,8 @@ This command also accepts the following options:
the state. the state.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs Terraform to retry acquiring a lock for a period of time before instructs Terraform to retry acquiring a lock for a period of time before
@ -64,12 +62,12 @@ This command also accepts the following options:
rendered by a system that cannot interpret terminal formatting. rendered by a system that cannot interpret terminal formatting.
For configurations using For configurations using
[the `remote` backend](/docs/language/settings/backends/remote.html) [the `remote` backend](/language/settings/backends/remote)
only, `terraform untaint` only, `terraform untaint`
also accepts the option also accepts the option
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). [`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
For configurations using For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only, [the `local` backend](/language/settings/backends/local) only,
`terraform untaint` also accepts the legacy options `terraform untaint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). [`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).

137
website/docs/cli/commands/validate.html.md → website/docs/cli/commands/validate.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: validate'
page_title: "Command: validate" description: >-
sidebar_current: "docs-commands-validate" The `terraform validate` command is used to validate the syntax of the
description: |- terraform files.
The `terraform validate` command is used to validate the syntax of the terraform files.
--- ---
# Command: validate # Command: validate
@ -39,11 +38,11 @@ Usage: `terraform validate [options]`
This command accepts the following options: This command accepts the following options:
- `-json` - Produce output in a machine-readable JSON format, suitable for * `-json` - Produce output in a machine-readable JSON format, suitable for
use in text editor integrations and other automated systems. Always disables use in text editor integrations and other automated systems. Always disables
color. color.
- `-no-color` - If specified, output won't contain any color. * `-no-color` - If specified, output won't contain any color.
## JSON Output Format ## JSON Output Format
@ -60,15 +59,15 @@ JSON, which it should then treat as a generic error case.
The output includes a `format_version` key, which as of Terraform 1.1.0 has The output includes a `format_version` key, which as of Terraform 1.1.0 has
value `"1.0"`. The semantics of this version are: value `"1.0"`. The semantics of this version are:
- We will increment the minor version, e.g. `"1.1"`, for backward-compatible * We will increment the minor version, e.g. `"1.1"`, for backward-compatible
changes or additions. Ignore any object properties with unrecognized names to changes or additions. Ignore any object properties with unrecognized names to
remain forward-compatible with future minor versions. remain forward-compatible with future minor versions.
- We will increment the major version, e.g. `"2.0"`, for changes that are not * We will increment the major version, e.g. `"2.0"`, for changes that are not
backward-compatible. Reject any input which reports an unsupported major backward-compatible. Reject any input which reports an unsupported major
version. version.
We will introduce new major versions only within the bounds of We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). [the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises).
In the normal case, Terraform will print a JSON object to the standard output In the normal case, Terraform will print a JSON object to the standard output
stream. The top-level JSON object will have the following properties: stream. The top-level JSON object will have the following properties:
@ -95,93 +94,93 @@ The nested objects in `diagnostics` have the following properties:
* `severity` (string): A string keyword, currently either `"error"` or * `severity` (string): A string keyword, currently either `"error"` or
`"warning"`, indicating the diagnostic severity. `"warning"`, indicating the diagnostic severity.
The presence of errors causes Terraform to consider a configuration to be The presence of errors causes Terraform to consider a configuration to be
invalid, while warnings are just advice or caveats to the user which do not invalid, while warnings are just advice or caveats to the user which do not
block working with the configuration. Later versions of Terraform may block working with the configuration. Later versions of Terraform may
introduce new severity keywords, so consumers should be prepared to accept introduce new severity keywords, so consumers should be prepared to accept
and ignore severity values they don't understand. and ignore severity values they don't understand.
* `summary` (string): A short description of the nature of the problem that * `summary` (string): A short description of the nature of the problem that
the diagnostic is reporting. the diagnostic is reporting.
In Terraform's usual human-oriented diagnostic messages, the summary serves In Terraform's usual human-oriented diagnostic messages, the summary serves
as a sort of "heading" for the diagnostic, printed after the "Error:" or as a sort of "heading" for the diagnostic, printed after the "Error:" or
"Warning:" indicator. "Warning:" indicator.
Summaries are typically short, single sentences, but can sometimes be longer Summaries are typically short, single sentences, but can sometimes be longer
as a result of returning errors from subsystems that are not designed to as a result of returning errors from subsystems that are not designed to
return full diagnostics, where the entire error message therefore becomes the return full diagnostics, where the entire error message therefore becomes the
summary. In those cases, the summary might include newline characters which summary. In those cases, the summary might include newline characters which
a renderer should honor when presenting the message visually to a user. a renderer should honor when presenting the message visually to a user.
* `detail` (string): An optional additional message giving more detail about * `detail` (string): An optional additional message giving more detail about
the problem. the problem.
In Terraform's usual human-oriented diagnostic messages, the detail provides In Terraform's usual human-oriented diagnostic messages, the detail provides
the paragraphs of text that appear after the heading and the source location the paragraphs of text that appear after the heading and the source location
reference. reference.
Detail messages are often multiple paragraphs and possibly interspersed with Detail messages are often multiple paragraphs and possibly interspersed with
non-paragraph lines, so tools which aim to present detail messages to the non-paragraph lines, so tools which aim to present detail messages to the
user should distinguish between lines without leading spaces, treating them user should distinguish between lines without leading spaces, treating them
as paragraphs, and lines with leading spaces, treating them as preformatted as paragraphs, and lines with leading spaces, treating them as preformatted
text. Renderers should then soft-wrap the paragraphs to fit the width of the text. Renderers should then soft-wrap the paragraphs to fit the width of the
rendering container, but leave the preformatted lines unwrapped. rendering container, but leave the preformatted lines unwrapped.
Some Terraform detail messages currently contain an approximation of bullet Some Terraform detail messages currently contain an approximation of bullet
lists using ASCII characters to mark the bullets. This is not currently a lists using ASCII characters to mark the bullets. This is not currently a
contractural formatting convention and so renderers should avoid depending on contractural formatting convention and so renderers should avoid depending on
it and should instead treat those lines as either paragraphs or preformatted it and should instead treat those lines as either paragraphs or preformatted
text per the rules above. A future version of this format may define some text per the rules above. A future version of this format may define some
additional rules for processing other text conventions, but will do so within additional rules for processing other text conventions, but will do so within
the bounds of the rules above to achieve backward-compatibility. the bounds of the rules above to achieve backward-compatibility.
* `range` (object): An optional object referencing a portion of the configuration * `range` (object): An optional object referencing a portion of the configuration
source code that the diagnostic message relates to. For errors, this will source code that the diagnostic message relates to. For errors, this will
typically indicate the bounds of the specific block header, attribute, or typically indicate the bounds of the specific block header, attribute, or
expression which was detected as invalid. expression which was detected as invalid.
A source range is an object with a property `filename` which gives the A source range is an object with a property `filename` which gives the
filename as a relative path from the current working directory, and then filename as a relative path from the current working directory, and then
two properties `start` and `end` which are both themselves objects two properties `start` and `end` which are both themselves objects
describing source positions, as described below. describing source positions, as described below.
Not all diagnostic messages are connected with specific portions of the Not all diagnostic messages are connected with specific portions of the
configuration, so `range` will be omitted or `null` for diagnostic messages configuration, so `range` will be omitted or `null` for diagnostic messages
where it isn't relevant. where it isn't relevant.
* `snippet` (object): An optional object including an excerpt of the * `snippet` (object): An optional object including an excerpt of the
configuration source code that the diagnostic message relates to. configuration source code that the diagnostic message relates to.
The snippet information includes: The snippet information includes:
* `context` (string): An optional summary of the root context of the * `context` (string): An optional summary of the root context of the
diagnostic. For example, this might be the resource block containing the diagnostic. For example, this might be the resource block containing the
expression which triggered the diagnostic. For some diagnostics this expression which triggered the diagnostic. For some diagnostics this
information is not available, and then this property will be `null`. information is not available, and then this property will be `null`.
* `code` (string): A snippet of Terraform configuration including the * `code` (string): A snippet of Terraform configuration including the
source of the diagnostic. This can be multiple lines and may include source of the diagnostic. This can be multiple lines and may include
additional configuration source code around the expression which additional configuration source code around the expression which
triggered the diagnostic. triggered the diagnostic.
* `start_line` (number): A one-based line count representing the position * `start_line` (number): A one-based line count representing the position
in the source file at which the `code` excerpt begins. This is not in the source file at which the `code` excerpt begins. This is not
necessarily the same value as `range.start.line`, as it is possible for necessarily the same value as `range.start.line`, as it is possible for
`code` to include one or more lines of context before the source of the `code` to include one or more lines of context before the source of the
diagnostic. diagnostic.
* `highlight_start_offset` (number): A zero-based character offset into the * `highlight_start_offset` (number): A zero-based character offset into the
`code` string, pointing at the start of the expression which triggered `code` string, pointing at the start of the expression which triggered
the diagnostic. the diagnostic.
* `highlight_end_offset` (number): A zero-based character offset into the * `highlight_end_offset` (number): A zero-based character offset into the
`code` string, pointing at the end of the expression which triggered the `code` string, pointing at the end of the expression which triggered the
diagnostic. diagnostic.
* `values` (array of objects): Contains zero or more expression values * `values` (array of objects): Contains zero or more expression values
which may be useful in understanding the source of a diagnostic in a which may be useful in understanding the source of a diagnostic in a
complex expression. These expression value objects are described below. complex expression. These expression value objects are described below.
### Source Position ### Source Position

14
website/docs/cli/commands/version.html.md → website/docs/cli/commands/version.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: 'Command: version'
page_title: "Command: version" description: >-
sidebar_current: "docs-commands-version" The terraform version command displays the Terraform version and the version
description: "The terraform version command displays the Terraform version and the version of all installed plugins." of all installed plugins.
--- ---
# Command: version # Command: version
@ -16,12 +16,12 @@ Usage: `terraform version [options]`
With no additional arguments, `version` will display the version of Terraform, With no additional arguments, `version` will display the version of Terraform,
the platform it's installed on, installed providers, and the results of upgrade the platform it's installed on, installed providers, and the results of upgrade
and security checks [unless disabled](/docs/cli/commands/index.html#upgrade-and-security-bulletin-checks). and security checks [unless disabled](/cli/commands#upgrade-and-security-bulletin-checks).
This command has one optional flag: This command has one optional flag:
* `-json` - If specified, the version information is formatted as a JSON object, * `-json` - If specified, the version information is formatted as a JSON object,
and no upgrade or security information is included. and no upgrade or security information is included.
-> **Note:** Platform information was added to the `version` command in Terraform 0.15. -> **Note:** Platform information was added to the `version` command in Terraform 0.15.
@ -51,4 +51,4 @@ $ terraform version -json
}, },
"terraform_outdated": true "terraform_outdated": true
} }
``` ```

11
website/docs/cli/commands/workspace/delete.html.md → website/docs/cli/commands/workspace/delete.mdx
View File

@ -1,9 +1,6 @@
--- ---
layout: "docs" page_title: 'Command: workspace delete'
page_title: "Command: workspace delete" description: The terraform workspace delete command is used to delete a workspace.
sidebar_current: "docs-commands-workspace-sub-delete"
description: |-
The terraform workspace delete command is used to delete a workspace.
--- ---
# Command: workspace delete # Command: workspace delete
@ -31,8 +28,8 @@ The command-line flags are all optional. The only supported flag is:
* `-force` - Delete the workspace even if its state is not empty. Defaults to false. * `-force` - Delete the workspace even if its state is not empty. Defaults to false.
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s. * `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
## Example ## Example

9
website/docs/cli/commands/workspace/index.html.md → website/docs/cli/commands/workspace/index.mdx
View File

@ -1,15 +1,12 @@
--- ---
layout: "docs" page_title: 'Command: workspace'
page_title: "Command: workspace" description: The workspace command helps you manage workspaces.
sidebar_current: "docs-commands-workspace-index"
description: "The workspace command helps you manage workspaces."
--- ---
# Command: workspace # Command: workspace
The `terraform workspace` command is used to manage The `terraform workspace` command is used to manage
[workspaces](/docs/language/state/workspaces.html). [workspaces](/language/state/workspaces).
This command is a container for further subcommands. These subcommands are This command is a container for further subcommands. These subcommands are
listed in the navigation bar. listed in the navigation bar.

7
website/docs/cli/commands/workspace/list.html.md → website/docs/cli/commands/workspace/list.mdx
View File

@ -1,9 +1,6 @@
--- ---
layout: "docs" page_title: 'Command: workspace list'
page_title: "Command: workspace list" description: The terraform workspace list command is used to list all existing workspaces.
sidebar_current: "docs-commands-workspace-sub-list"
description: |-
The terraform workspace list command is used to list all existing workspaces.
--- ---
# Command: workspace list # Command: workspace list

11
website/docs/cli/commands/workspace/new.html.md → website/docs/cli/commands/workspace/new.mdx
View File

@ -1,9 +1,6 @@
--- ---
layout: "docs" page_title: 'Command: workspace new'
page_title: "Command: workspace new" description: The terraform workspace new command is used to create a new workspace.
sidebar_current: "docs-commands-workspace-sub-new"
description: |-
The terraform workspace new command is used to create a new workspace.
--- ---
# Command: workspace new # Command: workspace new
@ -23,8 +20,8 @@ will be copied to initialize the state for this new workspace.
The command-line flags are all optional. The supported flags are: The command-line flags are all optional. The supported flags are:
* `-lock=false` - Don't hold a state lock during the operation. This is * `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same dangerous if others might concurrently run commands against the same
workspace. workspace.
* `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s. * `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
* `-state=path` - Path to an existing state file to initialize the state of this environment. * `-state=path` - Path to an existing state file to initialize the state of this environment.

7
website/docs/cli/commands/workspace/select.html.md → website/docs/cli/commands/workspace/select.mdx
View File

@ -1,9 +1,6 @@
--- ---
layout: "docs" page_title: 'Command: workspace select'
page_title: "Command: workspace select" description: The terraform workspace select command is used to choose a workspace.
sidebar_current: "docs-commands-workspace-sub-select"
description: |-
The terraform workspace select command is used to choose a workspace.
--- ---
# Command: workspace select # Command: workspace select

7
website/docs/cli/commands/workspace/show.html.md → website/docs/cli/commands/workspace/show.mdx
View File

@ -1,9 +1,6 @@
--- ---
layout: "docs" page_title: 'Command: workspace show'
page_title: "Command: workspace show" description: The terraform workspace show command is used to output the current workspace.
sidebar_current: "docs-commands-workspace-sub-show"
description: |-
The terraform workspace show command is used to output the current workspace.
--- ---
# Command: workspace show # Command: workspace show

84
website/docs/cli/config/config-file.html.md → website/docs/cli/config/config-file.mdx
View File

@ -1,15 +1,15 @@
--- ---
layout: "docs" page_title: CLI Configuration
page_title: "CLI Configuration" description: >-
sidebar_current: "docs-commands-cli-config" Learn to use the CLI configuration file to customize your CLI settings,
description: "Learn to use the CLI configuration file to customize your CLI settings, including credentials, plugin caching, provider installation methods, etc." including credentials, plugin caching, provider installation methods, etc.
--- ---
# CLI Configuration File (`.terraformrc` or `terraform.rc`) # CLI Configuration File (`.terraformrc` or `terraform.rc`)
The CLI configuration file configures per-user settings for CLI behaviors, The CLI configuration file configures per-user settings for CLI behaviors,
which apply across all Terraform working directories. This is separate from which apply across all Terraform working directories. This is separate from
[your infrastructure configuration](/docs/language/index.html). [your infrastructure configuration](/language).
## Locations ## Locations
@ -31,7 +31,7 @@ as just `terraform.rc`. Use `dir` from PowerShell or Command Prompt to
confirm the filename. confirm the filename.
The location of the Terraform CLI configuration file can also be specified The location of the Terraform CLI configuration file can also be specified
using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/cli/config/environment-variables.html). using the `TF_CLI_CONFIG_FILE` [environment variable](/cli/config/environment-variables).
Any such file should follow the naming pattern `*.tfrc`. Any such file should follow the naming pattern `*.tfrc`.
## Configuration File Syntax ## Configuration File Syntax
@ -50,38 +50,38 @@ disable_checkpoint = true
The following settings can be set in the CLI configuration file: The following settings can be set in the CLI configuration file:
- `credentials` - configures credentials for use with Terraform Cloud or * `credentials` - configures credentials for use with Terraform Cloud or
Terraform Enterprise. See [Credentials](#credentials) below for more Terraform Enterprise. See [Credentials](#credentials) below for more
information. information.
- `credentials_helper` - configures an external helper program for the storage * `credentials_helper` - configures an external helper program for the storage
and retrieval of credentials for Terraform Cloud or Terraform Enterprise. and retrieval of credentials for Terraform Cloud or Terraform Enterprise.
See [Credentials Helpers](#credentials-helpers) below for more information. See [Credentials Helpers](#credentials-helpers) below for more information.
- `disable_checkpoint` — when set to `true`, disables * `disable_checkpoint` — when set to `true`, disables
[upgrade and security bulletin checks](/docs/cli/commands/index.html#upgrade-and-security-bulletin-checks) [upgrade and security bulletin checks](/cli/commands#upgrade-and-security-bulletin-checks)
that require reaching out to HashiCorp-provided network services. that require reaching out to HashiCorp-provided network services.
- `disable_checkpoint_signature` — when set to `true`, allows the upgrade and * `disable_checkpoint_signature` — when set to `true`, allows the upgrade and
security bulletin checks described above but disables the use of an anonymous security bulletin checks described above but disables the use of an anonymous
id used to de-duplicate warning messages. id used to de-duplicate warning messages.
- `plugin_cache_dir` — enables * `plugin_cache_dir` — enables
[plugin caching](#provider-plugin-cache) [plugin caching](#provider-plugin-cache)
and specifies, as a string, the location of the plugin cache directory. and specifies, as a string, the location of the plugin cache directory.
- `provider_installation` - customizes the installation methods used by * `provider_installation` - customizes the installation methods used by
`terraform init` when installing provider plugins. See `terraform init` when installing provider plugins. See
[Provider Installation](#provider-installation) below for more information. [Provider Installation](#provider-installation) below for more information.
## Credentials ## Credentials
[Terraform Cloud](/docs/cloud/index.html) provides a number of remote network [Terraform Cloud](/cloud) provides a number of remote network
services for use with Terraform, and services for use with Terraform, and
[Terraform Enterprise](/docs/enterprise/index.html) allows hosting those [Terraform Enterprise](/enterprise) allows hosting those
services inside your own infrastructure. For example, these systems offer both services inside your own infrastructure. For example, these systems offer both
[remote operations](/docs/cloud/run/cli.html) and a [remote operations](/cloud-docs/run/cli) and a
[private module registry](/docs/cloud/registry/index.html). [private module registry](/cloud-docs/registry).
When interacting with Terraform-specific network services, Terraform expects When interacting with Terraform-specific network services, Terraform expects
to find API tokens in CLI configuration files in `credentials` blocks: to find API tokens in CLI configuration files in `credentials` blocks:
@ -92,7 +92,7 @@ credentials "app.terraform.io" {
} }
``` ```
If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/docs/cli/commands/login.html) If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/cli/commands/login)
to get credentials and automatically save them in the CLI configuration. If to get credentials and automatically save them in the CLI configuration. If
not, you can manually write `credentials` blocks. not, you can manually write `credentials` blocks.
@ -104,9 +104,9 @@ giving the API token to use for that host.
~> **Important:** If you are using Terraform Cloud or Terraform Enterprise, ~> **Important:** If you are using Terraform Cloud or Terraform Enterprise,
the token provided must be either a the token provided must be either a
[user token](/docs/cloud/users-teams-organizations/users.html#api-tokens) [user token](/cloud-docs/users-teams-organizations/users#api-tokens)
or a or a
[team token](/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens); [team token](/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens);
organization tokens cannot be used for command-line Terraform actions. organization tokens cannot be used for command-line Terraform actions.
-> **Note:** The credentials hostname must match the hostname in your module -> **Note:** The credentials hostname must match the hostname in your module
@ -144,7 +144,7 @@ for a specific hostname by writing a `credentials` block alongside the
Terraform does not include any credentials helpers in the main distribution. Terraform does not include any credentials helpers in the main distribution.
To learn how to write and install your own credentials helpers to integrate To learn how to write and install your own credentials helpers to integrate
with existing in-house credentials management systems, see with existing in-house credentials management systems, see
[the guide to Credentials Helper internals](/docs/internals/credentials-helpers.html). [the guide to Credentials Helper internals](/internals/credentials-helpers).
## Provider Installation ## Provider Installation
@ -216,36 +216,36 @@ The following are the two supported installation method types:
providers. This method requires the additional argument `path` to indicate providers. This method requires the additional argument `path` to indicate
which directory to look in. which directory to look in.
Terraform expects the given directory to contain a nested directory structure Terraform expects the given directory to contain a nested directory structure
where the path segments together provide metadata about the available where the path segments together provide metadata about the available
providers. The following two directory structures are supported: providers. The following two directory structures are supported:
* Packed layout: `HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip` * Packed layout: `HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip`
is the distribution zip file obtained from the provider's origin registry. is the distribution zip file obtained from the provider's origin registry.
* Unpacked layout: `HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET` is a directory * Unpacked layout: `HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET` is a directory
containing the result of extracting the provider's distribution zip file. containing the result of extracting the provider's distribution zip file.
In both layouts, the `VERSION` is a string like `2.0.0` and the `TARGET` In both layouts, the `VERSION` is a string like `2.0.0` and the `TARGET`
specifies a particular target platform using a format like `darwin_amd64`, specifies a particular target platform using a format like `darwin_amd64`,
`linux_arm`, `windows_amd64`, etc. `linux_arm`, `windows_amd64`, etc.
If you use the unpacked layout, Terraform will attempt to create a symbolic If you use the unpacked layout, Terraform will attempt to create a symbolic
link to the mirror directory when installing the provider, rather than link to the mirror directory when installing the provider, rather than
creating a deep copy of the directory. The packed layout prevents this creating a deep copy of the directory. The packed layout prevents this
because Terraform must extract the zip file during installation. because Terraform must extract the zip file during installation.
You can include multiple `filesystem_mirror` blocks in order to specify You can include multiple `filesystem_mirror` blocks in order to specify
several different directories to search. several different directories to search.
* `network_mirror`: consult a particular HTTPS server for copies of providers, * `network_mirror`: consult a particular HTTPS server for copies of providers,
regardless of which registry host they belong to. This method requires the regardless of which registry host they belong to. This method requires the
additional argument `url` to indicate the mirror base URL, which should additional argument `url` to indicate the mirror base URL, which should
use the `https:` scheme and end with a trailing slash. use the `https:` scheme and end with a trailing slash.
Terraform expects the given URL to be a base URL for an implementation of Terraform expects the given URL to be a base URL for an implementation of
[the provider network mirror protocol](/docs/internals/provider-network-mirror-protocol.html), [the provider network mirror protocol](/internals/provider-network-mirror-protocol),
which is designed to be relatively easy to implement using typical static which is designed to be relatively easy to implement using typical static
website hosting mechanisms. website hosting mechanisms.
~> **Warning:** Don't configure `network_mirror` URLs that you do not trust. ~> **Warning:** Don't configure `network_mirror` URLs that you do not trust.
Provider mirror servers are subject to TLS certificate checks to verify Provider mirror servers are subject to TLS certificate checks to verify
@ -402,7 +402,7 @@ provider_installation {
With development overrides in effect, the `terraform init` command will still With development overrides in effect, the `terraform init` command will still
attempt to select a suitable published version of your provider to install and attempt to select a suitable published version of your provider to install and
record in record in
[the dependency lock file](/docs/language/dependency-lock.html) [the dependency lock file](/language/files/dependency-lock)
for future use, but other commands like for future use, but other commands like
`terraform apply` will disregard the lock file's entry for `hashicorp/null` and `terraform apply` will disregard the lock file's entry for `hashicorp/null` and
will use the given directory instead. Once your new changes are included in a will use the given directory instead. Once your new changes are included in a

22
website/docs/cli/config/environment-variables.html.md → website/docs/cli/config/environment-variables.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: Environment Variables
page_title: "Environment Variables" description: >-
sidebar_current: "docs-commands-environment-variables" Learn to use environment variables to change Terraform's default behavior.
description: "Learn to use environment variables to change Terraform's default behavior. Configure log content and output, set variables, and more." Configure log content and output, set variables, and more.
--- ---
# Environment Variables # Environment Variables
@ -27,7 +27,7 @@ To disable, either unset it, or set it to `off`. For example:
export TF_LOG=off export TF_LOG=off
``` ```
For more on debugging Terraform, check out the section on [Debugging](/docs/internals/debugging.html). For more on debugging Terraform, check out the section on [Debugging](/internals/debugging).
## TF_LOG_PATH ## TF_LOG_PATH
@ -37,7 +37,7 @@ This specifies where the log should persist its output to. Note that even when `
export TF_LOG_PATH=./terraform.log export TF_LOG_PATH=./terraform.log
``` ```
For more on debugging Terraform, check out the section on [Debugging](/docs/internals/debugging.html). For more on debugging Terraform, check out the section on [Debugging](/internals/debugging).
## TF_INPUT ## TF_INPUT
@ -58,9 +58,10 @@ export TF_VAR_alist='[1,2,3]'
export TF_VAR_amap='{ foo = "bar", baz = "qux" }' export TF_VAR_amap='{ foo = "bar", baz = "qux" }'
``` ```
For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/docs/language/values/variables.html). For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/language/values/variables).
## TF_CLI_ARGS and TF_CLI_ARGS_name ## TF_CLI_ARGS and TF_CLI_ARGS_name
<a id="tf-cli-args"></a> <a id="tf-cli-args"></a>
The value of `TF_CLI_ARGS` will specify additional arguments to the The value of `TF_CLI_ARGS` will specify additional arguments to the
@ -113,8 +114,7 @@ export TF_WORKSPACE=your_workspace
Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state. Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state.
For more information regarding workspaces, check out the section on [Using Workspaces] For more information regarding workspaces, check out the section on [Using Workspaces](/language/state/workspaces).
(https://www.terraform.io/docs/language/state/workspaces.html).
## TF_IN_AUTOMATION ## TF_IN_AUTOMATION
@ -145,7 +145,7 @@ export TF_REGISTRY_CLIENT_TIMEOUT=15
## TF_CLI_CONFIG_FILE ## TF_CLI_CONFIG_FILE
The location of the [Terraform CLI configuration file](/docs/cli/config/config-file.html). The location of the [Terraform CLI configuration file](/cli/config/config-file).
```shell ```shell
export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-custom" export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-custom"
@ -159,4 +159,4 @@ If `TF_IGNORE` is set to "trace", Terraform will output debug messages to displa
export TF_IGNORE=trace export TF_IGNORE=trace
``` ```
For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/docs/language/settings/backends/remote.html#excluding-files-from-upload-with-terraformignore). For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore).

11
website/docs/cli/config/index.html.md → website/docs/cli/config/index.mdx
View File

@ -1,7 +1,8 @@
--- ---
layout: "docs" page_title: CLI Configuration - Terraform CLI
page_title: "CLI Configuration - Terraform CLI" description: >-
description: "Find documentation about the CLI config file and customizing Terraform environment variables." Find documentation about the CLI config file and customizing Terraform
environment variables.
--- ---
# CLI Configuration # CLI Configuration
@ -15,9 +16,9 @@ most of the global settings relate to advanced or automated workflows, or
unusual environmental conditions like running Terraform on an airgapped unusual environmental conditions like running Terraform on an airgapped
instance. instance.
- The [CLI config file](/docs/cli/config/config-file.html) configures provider - The [CLI config file](/cli/config/config-file) configures provider
installation and security features. installation and security features.
- Several [environment variables](/docs/cli/config/environment-variables.html) can - Several [environment variables](/cli/config/environment-variables) can
configure Terraform's inputs and outputs; this includes some alternate ways to configure Terraform's inputs and outputs; this includes some alternate ways to
provide information that is usually passed on the command line or read from provide information that is usually passed on the command line or read from
the state of the shell. the state of the shell.

6
website/docs/cli/import/importability.html.md → website/docs/cli/import/importability.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Import: Resource Importability'
page_title: "Import: Resource Importability"
sidebar_current: "docs-import-importability"
description: |- description: |-
Each resource in Terraform must implement some basic logic to become Each resource in Terraform must implement some basic logic to become
importable. As a result, not all Terraform resources are currently importable. importable. As a result, not all Terraform resources are currently importable.
@ -21,4 +19,4 @@ you're interested in contributing that functionality, the Terraform team
would be grateful. would be grateful.
To make a resource importable, please see To make a resource importable, please see
[Extending Terraform: Resources — Import](/docs/extend/resources/import.html). [Extending Terraform: Resources — Import](/plugin/sdkv2/resources/import).

14
website/docs/cli/import/index.html.md → website/docs/cli/import/index.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: Import
page_title: "Import" description: >-
sidebar_current: "docs-import" Terraform can import and manage existing infrastructure. This can help you
description: "Terraform can import and manage existing infrastructure. This can help you transition your infrastructure to Terraform." transition your infrastructure to Terraform.
--- ---
# Import # Import
@ -23,12 +23,12 @@ itself having created all objects. If you import existing objects into Terraform
be careful to import each remote object to only one Terraform resource address. be careful to import each remote object to only one Terraform resource address.
If you import the same object multiple times, Terraform may exhibit unwanted If you import the same object multiple times, Terraform may exhibit unwanted
behavior. For more information on this assumption, see behavior. For more information on this assumption, see
[the State section](/docs/language/state/index.html). [the State section](/language/state).
## Currently State Only ## Currently State Only
The current implementation of Terraform import can only import resources The current implementation of Terraform import can only import resources
into the [state](/docs/language/state/index.html). It does not generate configuration. A future into the [state](/language/state). It does not generate configuration. A future
version of Terraform will also generate configuration. version of Terraform will also generate configuration.
Because of this, prior to running `terraform import` it is necessary to write Because of this, prior to running `terraform import` it is necessary to write
@ -41,7 +41,7 @@ importing existing resources.
## Remote Backends ## Remote Backends
When using Terraform import on the command line with a [remote When using Terraform import on the command line with a [remote
backend](/docs/language/settings/backends/remote.html), such as Terraform Cloud, the import backend](/language/settings/backends/remote), such as Terraform Cloud, the import
command runs locally, unlike commands such as apply, which run inside your command runs locally, unlike commands such as apply, which run inside your
Terraform Cloud environment. Because of this, the import command will not have Terraform Cloud environment. Because of this, the import command will not have
access to information from the remote backend, such as workspace variables. access to information from the remote backend, such as workspace variables.

13
website/docs/cli/import/usage.html.md → website/docs/cli/import/usage.mdx
View File

@ -1,9 +1,6 @@
--- ---
layout: "docs" page_title: 'Import: Usage'
page_title: "Import: Usage" description: The `terraform import` command is used to import existing infrastructure.
sidebar_current: "docs-import-usage"
description: |-
The `terraform import` command is used to import existing infrastructure.
--- ---
# Import Usage # Import Usage
@ -23,7 +20,7 @@ itself having created all objects. If you import existing objects into Terraform
be careful to import each remote object to only one Terraform resource address. be careful to import each remote object to only one Terraform resource address.
If you import the same object multiple times, Terraform may exhibit unwanted If you import the same object multiple times, Terraform may exhibit unwanted
behavior. For more information on this assumption, see behavior. For more information on this assumption, see
[the State section](/docs/language/state/index.html). [the State section](/language/state).
To import a resource, first write a resource block for it in your To import a resource, first write a resource block for it in your
configuration, establishing the name by which it will be known to Terraform: configuration, establishing the name by which it will be known to Terraform:
@ -57,7 +54,7 @@ Terraform state.
It is also possible to import to resources in child modules, using their paths, It is also possible to import to resources in child modules, using their paths,
and to single instances of a resource with `count` or `for_each` set. See and to single instances of a resource with `count` or `for_each` set. See
[_Resource Addressing_](/docs/cli/state/resource-addressing.html) for more [_Resource Addressing_](/cli/state/resource-addressing) for more
details on how to specify a target resource. details on how to specify a target resource.
The syntax of the given ID is dependent on the resource type being imported. The syntax of the given ID is dependent on the resource type being imported.
@ -83,4 +80,4 @@ a `resource` block in configuration for each secondary resource. If this is
not done, Terraform will plan to destroy the imported objects on the next run. not done, Terraform will plan to destroy the imported objects on the next run.
If you want to rename or otherwise move the imported resources, the If you want to rename or otherwise move the imported resources, the
[state management commands](/docs/cli/commands/state/index.html) can be used. [state management commands](/cli/commands/state) can be used.

10
website/docs/cli/index.html.md → website/docs/cli/index.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: Terraform CLI Documentation
page_title: "Terraform CLI Documentation" description: >-
sidebar_current: "docs-home" Learn how to use Terraform's CLI-based workflows. You can use the CLI alone or
description: "Learn how to use Terraform's CLI-based workflows. You can use the CLI alone or in conjunction with Terraform Cloud or Terraform Enterprise." in conjunction with Terraform Cloud or Terraform Enterprise.
--- ---
# Terraform CLI Documentation # Terraform CLI Documentation
@ -16,4 +16,4 @@ Cloud or Terraform Enterprise.
Notably, this documentation does not cover the syntax and usage of the Terraform Notably, this documentation does not cover the syntax and usage of the Terraform
language. For that, see the language. For that, see the
[Terraform Language Documentation](/docs/language/index.html). [Terraform Language Documentation](/language).

14
website/docs/cli/init/index.html.md → website/docs/cli/init/index.mdx
View File

@ -1,14 +1,16 @@
--- ---
layout: "docs" page_title: Initializing Working Directories - Terraform CLI
page_title: "Initializing Working Directories - Terraform CLI" description: >-
description: "Working directories contain configurations, settings, cached plugins and modules, and state data. Learn how to initialize and manage working directories." Working directories contain configurations, settings, cached plugins and
modules, and state data. Learn how to initialize and manage working
directories.
--- ---
# Initializing Working Directories # Initializing Working Directories
Terraform expects to be invoked from a working directory that contains Terraform expects to be invoked from a working directory that contains
configuration files written in configuration files written in
[the Terraform language](/docs/language/index.html). Terraform uses [the Terraform language](/language). Terraform uses
configuration content from this directory, and also uses the directory to store configuration content from this directory, and also uses the directory to store
settings, cached plugins and modules, and sometimes state data. settings, cached plugins and modules, and sometimes state data.
@ -23,7 +25,7 @@ A Terraform working directory typically contains:
configuration is expected to change over time. configuration is expected to change over time.
- A hidden `.terraform` directory, which Terraform uses to manage cached - A hidden `.terraform` directory, which Terraform uses to manage cached
provider plugins and modules, record which provider plugins and modules, record which
[workspace](/docs/cli/workspaces/index.html) is currently active, and [workspace](/cli/workspaces) is currently active, and
record the last known backend configuration in case it needs to migrate state record the last known backend configuration in case it needs to migrate state
on the next run. This directory is automatically managed by Terraform, and is on the next run. This directory is automatically managed by Terraform, and is
created during initialization. created during initialization.
@ -48,7 +50,7 @@ plugins, and downloading modules. Under some conditions (usually when changing
from one backend to another), it might ask the user for guidance or from one backend to another), it might ask the user for guidance or
confirmation. confirmation.
For details, see [the `terraform init` command](/docs/cli/commands/init.html). For details, see [the `terraform init` command](/cli/commands/init).
## Reinitialization ## Reinitialization

19
website/docs/cli/inspect/index.html.md → website/docs/cli/inspect/index.mdx
View File

@ -1,7 +1,8 @@
--- ---
layout: "docs" page_title: Inspecting Infrastructure - Terraform CLI
page_title: "Inspecting Infrastructure - Terraform CLI" description: >-
description: "Learn commands to inspect dependency information, outputs, etc. Use them for integration or to understand your infrastructure." Learn commands to inspect dependency information, outputs, etc. Use them for
integration or to understand your infrastructure.
--- ---
# Inspecting Infrastructure # Inspecting Infrastructure
@ -16,19 +17,19 @@ Terraform CLI includes some commands for inspecting or transforming this data.
You can use these to integrate other tools with Terraform's infrastructure data, You can use these to integrate other tools with Terraform's infrastructure data,
or just to gain a deeper or more holistic understanding of your infrastructure. or just to gain a deeper or more holistic understanding of your infrastructure.
- [The `terraform graph` command](/docs/cli/commands/graph.html) creates a visual - [The `terraform graph` command](/cli/commands/graph) creates a visual
representation of a configuration or a set of planned changes. representation of a configuration or a set of planned changes.
- [The `terraform output` command](/docs/cli/commands/output.html) can get the - [The `terraform output` command](/cli/commands/output) can get the
values for the top-level [output values](/docs/language/values/outputs.html) of values for the top-level [output values](/language/values/outputs) of
a configuration, which are often helpful when making use of the infrastructure a configuration, which are often helpful when making use of the infrastructure
Terraform has provisioned. Terraform has provisioned.
- [The `terraform show` command](/docs/cli/commands/show.html) can generate - [The `terraform show` command](/cli/commands/show) can generate
human-readable versions of a state file or plan file, or generate human-readable versions of a state file or plan file, or generate
machine-readable versions that can be integrated with other tools. machine-readable versions that can be integrated with other tools.
- [The `terraform state list` command](/docs/cli/commands/state/list.html) can list - [The `terraform state list` command](/cli/commands/state/list) can list
the resources being managed by the current working directory and workspace, the resources being managed by the current working directory and workspace,
providing a complete or filtered list. providing a complete or filtered list.
- [The `terraform state show` command](/docs/cli/commands/state/show.html) can print - [The `terraform state show` command](/cli/commands/state/show) can print
all of the attributes of a given resource being managed by the current working all of the attributes of a given resource being managed by the current working
directory and workspace, including generated read-only attributes like the directory and workspace, including generated read-only attributes like the
unique ID assigned by the cloud provider. unique ID assigned by the cloud provider.

13
website/docs/cli/install/apt.html.md → website/docs/cli/install/apt.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "downloads" page_title: APT Packages for Debian and Ubuntu
page_title: "APT Packages for Debian and Ubuntu" description: >-
sidebar_current: "docs-cli-install-apt" The HashiCorp APT repositories contain distribution-specific Terraform
description: |- packages for both Debian and Ubuntu systems.
The HashiCorp APT repositories contain distribution-specific Terraform packages for both Debian and Ubuntu systems.
--- ---
# APT Packages for Debian and Ubuntu # APT Packages for Debian and Ubuntu
@ -16,7 +15,7 @@ Debian and Ubuntu systems, which allow you to install Terraform using the
`apt install` command or any other APT frontend. `apt install` command or any other APT frontend.
If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you
might prefer to [install Terraform from our Yum repositories](yum.html). might prefer to [install Terraform from our Yum repositories](/cli/install/yum).
-> **Note:** The APT repositories discussed on this page are generic HashiCorp -> **Note:** The APT repositories discussed on this page are generic HashiCorp
repositories that contain packages for a variety of different HashiCorp repositories that contain packages for a variety of different HashiCorp
@ -64,7 +63,7 @@ architecture, which is also sometimes known as `x86_64`.
There are no official packages available for other architectures, such as There are no official packages available for other architectures, such as
`arm64`. If you wish to use Terraform on a non-`amd64` system, `arm64`. If you wish to use Terraform on a non-`amd64` system,
[download a normal release `.zip` file](/downloads.html) instead. [download a normal release `.zip` file](/downloads) instead.
## Supported Debian and Ubuntu Releases ## Supported Debian and Ubuntu Releases

13
website/docs/cli/install/yum.html.md → website/docs/cli/install/yum.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "downloads" page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux'
page_title: "Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux" description: >-
sidebar_current: "docs-cli-install-yum" The HashiCorp Yum repositories contain distribution-specific Terraform
description: |- packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems.
The HashiCorp Yum repositories contain distribution-specific Terraform packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems.
--- ---
# Yum/DNF Packages for RHEL, CentOS, and Fedora # Yum/DNF Packages for RHEL, CentOS, and Fedora
@ -16,7 +15,7 @@ RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to
install Terraform using the `yum install` or `dnf install` commands. install Terraform using the `yum install` or `dnf install` commands.
If you are instead using Debian or Ubuntu, you If you are instead using Debian or Ubuntu, you
might prefer to [install Terraform from our APT repositories](apt.html). might prefer to [install Terraform from our APT repositories](/cli/install/apt).
-> **Note:** The Yum repositories discussed on this page are generic HashiCorp -> **Note:** The Yum repositories discussed on this page are generic HashiCorp
repositories that contain packages for a variety of different HashiCorp repositories that contain packages for a variety of different HashiCorp
@ -64,7 +63,7 @@ architecture, which is also sometimes known as `amd64`.
There are no official packages available for other architectures, such as There are no official packages available for other architectures, such as
`aarch64`. If you wish to use Terraform on a non-`x86_64` system, `aarch64`. If you wish to use Terraform on a non-`x86_64` system,
[download a normal release `.zip` file](/downloads.html) instead. [download a normal release `.zip` file](/downloads) instead.
## Supported Distribution Releases ## Supported Distribution Releases

25
website/docs/cli/plugins/index.html.md → website/docs/cli/plugins/index.mdx
View File

@ -1,14 +1,15 @@
--- ---
layout: "docs" page_title: Managing Plugins - Terraform CLI
page_title: "Managing Plugins - Terraform CLI" description: >-
description: "Commands to install, configure, and show information about providers. Also commands to reduce install effort in air-gapped environments." Commands to install, configure, and show information about providers. Also
commands to reduce install effort in air-gapped environments.
--- ---
# Managing Plugins # Managing Plugins
Terraform relies on plugins called "providers" in order to manage various types Terraform relies on plugins called "providers" in order to manage various types
of resources. (For more information about providers, see of resources. (For more information about providers, see
[Providers](/docs/language/providers/index.html) in the Terraform [Providers](/language/providers) in the Terraform
language docs.) language docs.)
-> **Note:** Providers are currently the only plugin type most Terraform users -> **Note:** Providers are currently the only plugin type most Terraform users
@ -16,8 +17,8 @@ will interact with. Terraform also supports third-party provisioner plugins, but
we discourage their use. we discourage their use.
Terraform downloads and/or installs any providers Terraform downloads and/or installs any providers
[required](/docs/language/providers/requirements.html) by a configuration [required](/language/providers/requirements) by a configuration
when [initializing](/docs/cli/init/index.html) a working directory. By default, when [initializing](/cli/init) a working directory. By default,
this works without any additional interaction but requires network access to this works without any additional interaction but requires network access to
download providers from their source registry. download providers from their source registry.
@ -31,29 +32,29 @@ environments.
Terraform's configuration file includes options for caching downloaded plugins, Terraform's configuration file includes options for caching downloaded plugins,
or explicitly specifying a local or HTTPS mirror to install plugins from. For or explicitly specifying a local or HTTPS mirror to install plugins from. For
more information, see [CLI Config File](/docs/cli/config/config-file.html). more information, see [CLI Config File](/cli/config/config-file).
## Getting Plugin Information ## Getting Plugin Information
Use the [`terraform providers`](/docs/cli/commands/providers.html) command to get information Use the [`terraform providers`](/cli/commands/providers) command to get information
about the providers required by the current working directory's configuration. about the providers required by the current working directory's configuration.
Use the [`terraform version`](/docs/cli/commands/version.html) command (or Use the [`terraform version`](/cli/commands/version) command (or
`terraform -version`) to show the specific provider versions installed for the `terraform -version`) to show the specific provider versions installed for the
current working directory. current working directory.
Use the [`terraform providers schema`](/docs/cli/commands/providers/schema.html) command to Use the [`terraform providers schema`](/cli/commands/providers/schema) command to
get machine-readable information about the resources and configuration options get machine-readable information about the resources and configuration options
offered by each provider. offered by each provider.
## Managing Plugin Installation ## Managing Plugin Installation
Use the [`terraform providers mirror`](/docs/cli/commands/providers/mirror.html) command to Use the [`terraform providers mirror`](/cli/commands/providers/mirror) command to
download local copies of every provider required by the current working download local copies of every provider required by the current working
directory's configuration. This directory will use the nested directory layout directory's configuration. This directory will use the nested directory layout
that Terraform expects when installing plugins from a local source, so you can that Terraform expects when installing plugins from a local source, so you can
transfer it directly to an airgapped system that runs Terraform. transfer it directly to an airgapped system that runs Terraform.
Use the [`terraform providers lock`](/docs/cli/commands/providers/lock.html) command Use the [`terraform providers lock`](/cli/commands/providers/lock) command
to update the lock file that Terraform uses to ensure predictable runs when to update the lock file that Terraform uses to ensure predictable runs when
using ambiguous provider version constraints. using ambiguous provider version constraints.

15
website/docs/cli/plugins/signing.html.md → website/docs/cli/plugins/signing.mdx
View File

@ -1,7 +1,8 @@
--- ---
layout: "docs" page_title: Plugin Signing
page_title: "Plugin Signing" description: >-
description: "Learn about the types of signatures providers can have on the Terraform Registry." Learn about the types of signatures providers can have on the Terraform
Registry.
--- ---
<!-- THIS PAGED IS LINKED TO IN THE CLI --> <!-- THIS PAGED IS LINKED TO IN THE CLI -->
@ -14,11 +15,11 @@ Terraform providers installed from the Registry are cryptographically signed, an
* **Signed by HashiCorp** - are built, signed, and supported by HashiCorp. * **Signed by HashiCorp** - are built, signed, and supported by HashiCorp.
* **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has * **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has
verified the ownership of the private key and we provide a chain of trust to the CLI to verify this verified the ownership of the private key and we provide a chain of trust to the CLI to verify this
programatically. programatically.
* **Self-signed** - are built, signed, and supported by a third party. HashiCorp does not provide a * **Self-signed** - are built, signed, and supported by a third party. HashiCorp does not provide a
verification or chain of trust for the signature. You may obtain and validate fingerprints manually verification or chain of trust for the signature. You may obtain and validate fingerprints manually
if you want to ensure you are using a binary you can trust. if you want to ensure you are using a binary you can trust.
Terraform does **NOT** support fetching and using unsigned binaries, but you can manually install Terraform does **NOT** support fetching and using unsigned binaries, but you can manually install
unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed. unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed.

17
website/docs/cli/run/index.html.md → website/docs/cli/run/index.mdx
View File

@ -1,14 +1,13 @@
--- ---
layout: "docs" page_title: Provisioning Infrastructure - Terraform CLI
page_title: "Provisioning Infrastructure - Terraform CLI" description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.'
description: "Learn about commands for core provisioning tasks: plan, apply, and destroy."
--- ---
# Provisioning Infrastructure with Terraform # Provisioning Infrastructure with Terraform
Terraform's primary function is to create, modify, and destroy infrastructure Terraform's primary function is to create, modify, and destroy infrastructure
resources to match the desired state described in a resources to match the desired state described in a
[Terraform configuration](/docs/language/index.html). [Terraform configuration](/language).
When people refer to "running Terraform," they generally mean performing these When people refer to "running Terraform," they generally mean performing these
provisioning actions in order to affect real infrastructure objects. The provisioning actions in order to affect real infrastructure objects. The
@ -17,8 +16,8 @@ actions, but these basic provisioning tasks are the core of Terraform.
Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and
`destroy`. All of these commands require an `destroy`. All of these commands require an
[initialized](/docs/cli/init/index.html) working directory, and all of them act [initialized](/cli/init) working directory, and all of them act
only upon the currently selected [workspace](/docs/cli/workspaces/index.html). only upon the currently selected [workspace](/cli/workspaces).
## Planning ## Planning
@ -39,7 +38,7 @@ resulting actions are as expected. However, `terraform plan` can also save its
plan as a runnable artifact, which `terraform apply` can use to carry out those plan as a runnable artifact, which `terraform apply` can use to carry out those
exact changes. exact changes.
For details, see [the `terraform plan` command](/docs/cli/commands/plan.html). For details, see [the `terraform plan` command](/cli/commands/plan).
## Applying ## Applying
@ -55,7 +54,7 @@ running a new plan. You can use this to reliably perform an exact set of
pre-approved changes, even if the configuration or the state of the real pre-approved changes, even if the configuration or the state of the real
infrastructure has changed in the minutes since the original plan was created. infrastructure has changed in the minutes since the original plan was created.
For details, see [the `terraform apply` command](/docs/cli/commands/apply.html). For details, see [the `terraform apply` command](/cli/commands/apply).
## Destroying ## Destroying
@ -69,4 +68,4 @@ and then running an apply, except that it doesn't require editing the
configuration. This is more convenient if you intend to provision similar configuration. This is more convenient if you intend to provision similar
resources at a later date. resources at a later date.
For details, see [the `terraform destroy` command](/docs/cli/commands/destroy.html). For details, see [the `terraform destroy` command](/cli/commands/destroy).

19
website/docs/cli/state/index.html.md → website/docs/cli/state/index.mdx
View File

@ -1,14 +1,15 @@
--- ---
layout: "docs" page_title: Manipulating State - Terraform CLI
page_title: "Manipulating State - Terraform CLI" description: >-
description: "State data tracks which real-world object corresponds to each resource. Inspect state, move or import resources, and more." State data tracks which real-world object corresponds to each resource.
Inspect state, move or import resources, and more.
--- ---
# Manipulating Terraform State # Manipulating Terraform State
> **Hands-on:** Try the [Manage Resources in Terraform State](https://learn.hashicorp.com/tutorials/terraform/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. > **Hands-on:** Try the [Manage Resources in Terraform State](https://learn.hashicorp.com/tutorials/terraform/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
Terraform uses [state data](/docs/language/state/index.html) to remember which Terraform uses [state data](/language/state) to remember which
real-world object corresponds to each resource in the configuration; real-world object corresponds to each resource in the configuration;
this allows it to modify an existing object when its resource declaration this allows it to modify an existing object when its resource declaration
changes. changes.
@ -20,12 +21,12 @@ infrastructure.
Terraform CLI supports several workflows for interacting with state: Terraform CLI supports several workflows for interacting with state:
- [Inspecting State](/docs/cli/state/inspect.html) - [Inspecting State](/cli/state/inspect)
- [Forcing Re-creation (Tainting)](/docs/cli/state/taint.html) - [Forcing Re-creation (Tainting)](/cli/state/taint)
- [Moving Resources](/docs/cli/state/move.html) - [Moving Resources](/cli/state/move)
- Importing Pre-existing Resources (documented in the - Importing Pre-existing Resources (documented in the
[Importing Infrastructure](/docs/cli/import/index.html) section) [Importing Infrastructure](/cli/import) section)
- [Disaster Recovery](/docs/cli/state/recover.html) - [Disaster Recovery](/cli/state/recover)
~> **Important:** Modifying state data outside a normal plan or apply can cause ~> **Important:** Modifying state data outside a normal plan or apply can cause
Terraform to lose track of managed resources, which might waste money, annoy Terraform to lose track of managed resources, which might waste money, annoy

11
website/docs/cli/state/inspect.html.md → website/docs/cli/state/inspect.mdx
View File

@ -1,7 +1,6 @@
--- ---
layout: "docs" page_title: Inspecting State - Terraform CLI
page_title: "Inspecting State - Terraform CLI" description: Commands that allow you to read and update state.
description: "Commands that allow you to read and update state."
--- ---
# Inspecting State # Inspecting State
@ -9,14 +8,14 @@ description: "Commands that allow you to read and update state."
Terraform includes some commands for reading and updating state without taking Terraform includes some commands for reading and updating state without taking
any other actions. any other actions.
- [The `terraform state list` command](/docs/cli/commands/state/list.html) - [The `terraform state list` command](/cli/commands/state/list)
shows the resource addresses for every resource Terraform knows about in a shows the resource addresses for every resource Terraform knows about in a
configuration, optionally filtered by partial resource address. configuration, optionally filtered by partial resource address.
- [The `terraform state show` command](/docs/cli/commands/state/show.html) - [The `terraform state show` command](/cli/commands/state/show)
displays detailed state data about one resource. displays detailed state data about one resource.
- [The `terraform refresh` command](/docs/cli/commands/refresh.html) updates - [The `terraform refresh` command](/cli/commands/refresh) updates
state data to match the real-world condition of the managed resources. This is state data to match the real-world condition of the managed resources. This is
done automatically during plans and applies, but not when interacting with done automatically during plans and applies, but not when interacting with
state directly. state directly.

17
website/docs/cli/state/move.html.md → website/docs/cli/state/move.mdx
View File

@ -1,13 +1,14 @@
--- ---
layout: "docs" page_title: Moving Resources - Terraform CLI
page_title: "Moving Resources - Terraform CLI" description: >-
description: "Commands that allow you to manage the way that resources are tracked in state. They are helpful when you move or change resources." Commands that allow you to manage the way that resources are tracked in state.
They are helpful when you move or change resources.
--- ---
# Moving Resources # Moving Resources
Terraform's state associates each real-world object with a configured resource Terraform's state associates each real-world object with a configured resource
at a specific [resource address](/docs/cli/state/resource-addressing.html). This at a specific [resource address](/cli/state/resource-addressing). This
is seamless when changing a resource's attributes, but Terraform will lose track is seamless when changing a resource's attributes, but Terraform will lose track
of a resource if you change its name, move it to a different module, or change of a resource if you change its name, move it to a different module, or change
its provider. its provider.
@ -20,19 +21,19 @@ In cases where it's important to preserve an existing infrastructure object, you
can explicitly tell Terraform to associate it with a different configured can explicitly tell Terraform to associate it with a different configured
resource. resource.
- [The `terraform state mv` command](/docs/cli/commands/state/mv.html) changes - [The `terraform state mv` command](/cli/commands/state/mv) changes
which resource address in your configuration is associated with a particular which resource address in your configuration is associated with a particular
real-world object. Use this to preserve an object when renaming a resource, or real-world object. Use this to preserve an object when renaming a resource, or
when moving a resource into or out of a child module. when moving a resource into or out of a child module.
> **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn. > **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn.
- [The `terraform state rm` command](/docs/cli/commands/state/rm.html) tells - [The `terraform state rm` command](/cli/commands/state/rm) tells
Terraform to stop managing a resource as part of the current working directory Terraform to stop managing a resource as part of the current working directory
and workspace, _without_ destroying the corresponding real-world object. (You and workspace, _without_ destroying the corresponding real-world object. (You
can later use `terraform import` to start managing that resource in a can later use `terraform import` to start managing that resource in a
different workspace or a different Terraform configuration.) different workspace or a different Terraform configuration.)
- [The `terraform state replace-provider` command](/docs/cli/commands/state/replace-provider.html) - [The `terraform state replace-provider` command](/cli/commands/state/replace-provider)
transfers existing resources to a new provider without requiring them to be transfers existing resources to a new provider without requiring them to be
re-created. re-created.

14
website/docs/cli/state/recover.html.md → website/docs/cli/state/recover.mdx
View File

@ -1,7 +1,8 @@
--- ---
layout: "docs" page_title: Recovering from State Disasters - Terraform CLI
page_title: "Recovering from State Disasters - Terraform CLI" descriptin: >-
descriptin: "Commands that allow you to restore state backups and override Terraform state protections." Commands that allow you to restore state backups and override Terraform state
protections.
--- ---
# Recovering from State Disasters # Recovering from State Disasters
@ -10,7 +11,7 @@ If something has gone horribly wrong (possibly due to accidents when performing
other state manipulation actions), you might need to take drastic actions with other state manipulation actions), you might need to take drastic actions with
your state data. your state data.
- [The `terraform force-unlock` command](/docs/cli/commands/force-unlock.html) can - [The `terraform force-unlock` command](/cli/commands/force-unlock) can
override the protections Terraform uses to prevent two processes from override the protections Terraform uses to prevent two processes from
modifying state at the same time. You might need this if a Terraform process modifying state at the same time. You might need this if a Terraform process
(like a normal apply) is unexpectedly terminated (like by the complete (like a normal apply) is unexpectedly terminated (like by the complete
@ -18,8 +19,7 @@ your state data.
state backend. Do not run this until you are completely certain what happened state backend. Do not run this until you are completely certain what happened
to the process that caused the lock to get stuck. to the process that caused the lock to get stuck.
- [The `terraform state pull` command](/docs/cli/commands/state/pull.html) and - [The `terraform state pull` command](/cli/commands/state/pull) and
[the `terraform state push` command](/docs/cli/commands/state/push.html) can [the `terraform state push` command](/cli/commands/state/push) can
directly read and write entire state files from and to the configured backend. directly read and write entire state files from and to the configured backend.
You might need this for obtaining or restoring a state backup. You might need this for obtaining or restoring a state backup.

38
website/docs/cli/state/resource-addressing.html.md → website/docs/cli/state/resource-addressing.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Internals: Resource Address'
page_title: "Internals: Resource Address"
sidebar_current: "docs-internals-resource-addressing"
description: |- description: |-
A resource address is a string that identifies zero or more resource A resource address is a string that identifies zero or more resource
instances in your overall configuration. instances in your overall configuration.
@ -32,12 +30,12 @@ A module path addresses a module within the tree of modules. It takes the form:
module.module_name[module index] 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) - `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources)
to select an instance from a module call that has multiple instances, to select an instance from a module call that has multiple instances,
surrounded by square bracket characters (`[` and `]`). 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.
@ -64,11 +62,11 @@ It has the following syntax:
resource_type.resource_name[instance 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.
* `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources) - `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources)
to select an instance from a resource that has multiple instances, to select an instance from a resource that has multiple instances,
surrounded by square bracket characters (`[` and `]`). 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
@ -79,12 +77,12 @@ in any descendent module.
The following specifications apply to index values on modules and resources with multiple instances: The following specifications apply to index values on modules and resources with multiple instances:
* `[N]` where `N` is a `0`-based numerical index into a resource with multiple - `[N]` where `N` is a `0`-based numerical index into a resource with multiple
instances specified by the `count` meta-argument. Omitting an index when instances specified by the `count` meta-argument. Omitting an index when
addressing a resource where `count > 1` means that the address references addressing a resource where `count > 1` means that the address references
all instances. all instances.
* `["INDEX"]` where `INDEX` is a alphanumerical key index into a resource with - `["INDEX"]` where `INDEX` is a alphanumerical key index into a resource with
multiple instances specified by the `for_each` meta-argument. multiple instances specified by the `for_each` meta-argument.
## Examples ## Examples

11
website/docs/cli/state/taint.html.md → website/docs/cli/state/taint.mdx
View File

@ -1,7 +1,6 @@
--- ---
layout: "docs" page_title: Forcing Re-creation of Resources (Tainting) - Terraform CLI
page_title: "Forcing Re-creation of Resources (Tainting) - Terraform CLI" description: Commands that allow you to destroy and re-create resources manually.
description: "Commands that allow you to destroy and re-create resources manually."
--- ---
# Forcing Re-creation of Resources (Tainting) # Forcing Re-creation of Resources (Tainting)
@ -17,10 +16,10 @@ happen during creation; for example, a virtual machine that configures itself
with `cloud-init` on startup might no longer meet your needs if the cloud-init with `cloud-init` on startup might no longer meet your needs if the cloud-init
configuration changes. configuration changes.
- [The `terraform taint` command](/docs/cli/commands/taint.html) tells Terraform to - [The `terraform taint` command](/cli/commands/taint) tells Terraform to
destroy and re-create a particular resource during the next apply, regardless destroy and re-create a particular resource during the next apply, regardless
of whether its resource arguments would normally require that. of whether its resource arguments would normally require that.
- [The `terraform untaint` command](/docs/cli/commands/untaint.html) undoes a - [The `terraform untaint` command](/cli/commands/untaint) undoes a
previous taint, or can preserve a resource that was automatically tainted due previous taint, or can preserve a resource that was automatically tainted due
to failed [provisioners](/docs/language/resources/provisioners/syntax.html). to failed [provisioners](/language/resources/provisioners/syntax).

35
website/docs/cli/workspaces/index.html.md → website/docs/cli/workspaces/index.mdx
View File

@ -1,28 +1,29 @@
--- ---
layout: "docs" page_title: Managing Workspaces - Terraform CLI
page_title: "Managing Workspaces - Terraform CLI" description: >-
description: "Commands to list, select, create, and output workspaces. Workspaces help manage different groups of resources with one configuration." Commands to list, select, create, and output workspaces. Workspaces help
manage different groups of resources with one configuration.
--- ---
# Managing Workspaces # Managing Workspaces
In Terraform CLI, _workspaces_ are separate instances of In Terraform CLI, _workspaces_ are separate instances of
[state data](/docs/language/state/index.html) that can be used from the same working [state data](/language/state) that can be used from the same working
directory. You can use workspaces to manage multiple non-overlapping groups of directory. You can use workspaces to manage multiple non-overlapping groups of
resources with the same configuration. resources with the same configuration.
- Every [initialized working directory](/docs/cli/init/index.html) has at least - Every [initialized working directory](/cli/init) has at least
one workspace. (If you haven't created other workspaces, it is a workspace one workspace. (If you haven't created other workspaces, it is a workspace
named `default`.) named `default`.)
- For a given working directory, only one workspace can be _selected_ at a time. - For a given working directory, only one workspace can be _selected_ at a time.
- Most Terraform commands (including [provisioning](/docs/cli/run/index.html) - Most Terraform commands (including [provisioning](/cli/run)
and [state manipulation](/docs/cli/state/index.html) commands) only interact and [state manipulation](/cli/state) commands) only interact
with the currently selected workspace. with the currently selected workspace.
- Use [the `terraform workspace select` command](/docs/cli/commands/workspace/select.html) - Use [the `terraform workspace select` command](/cli/commands/workspace/select)
to change the currently selected workspace. to change the currently selected workspace.
- Use the [`terraform workspace list`](/docs/cli/commands/workspace/list.html), - Use the [`terraform workspace list`](/cli/commands/workspace/list),
[`terraform workspace new`](/docs/cli/commands/workspace/new.html), and [`terraform workspace new`](/cli/commands/workspace/new), and
[`terraform workspace delete`](/docs/cli/commands/workspace/delete.html) commands [`terraform workspace delete`](/cli/commands/workspace/delete) commands
to manage the available workspaces in the current working directory. to manage the available workspaces in the current working directory.
-> **Note:** Terraform Cloud and Terraform CLI both have features called -> **Note:** Terraform Cloud and Terraform CLI both have features called
@ -35,19 +36,19 @@ Since most of the resources you can manage with Terraform don't include a unique
name as part of their configuration, it's common to use the same Terraform name as part of their configuration, it's common to use the same Terraform
configuration to provision multiple groups of similar resources. configuration to provision multiple groups of similar resources.
Terraform relies on [state](/docs/language/state/index.html) to associate resources with Terraform relies on [state](/language/state) to associate resources with
real-world objects, so if you run the same configuration multiple times with real-world objects, so if you run the same configuration multiple times with
completely separate state data, Terraform can manage many non-overlapping groups completely separate state data, Terraform can manage many non-overlapping groups
of resources. In some cases you'll want to change of resources. In some cases you'll want to change
[variable values](/docs/language/values/variables.html) for these different [variable values](/language/values/variables) for these different
resource collections (like when specifying differences between staging and resource collections (like when specifying differences between staging and
production deployments), and in other cases you might just want many instances production deployments), and in other cases you might just want many instances
of a particular infrastructure pattern. of a particular infrastructure pattern.
The simplest way to maintain multiple instances of a configuration with The simplest way to maintain multiple instances of a configuration with
completely separate state data is to use multiple completely separate state data is to use multiple
[working directories](/docs/cli/init/index.html) (with different [working directories](/cli/init) (with different
[backend](/docs/language/settings/backends/configuration.html) configurations per directory, if you [backend](/language/settings/backends/configuration) configurations per directory, if you
aren't using the default `local` backend). aren't using the default `local` backend).
However, this isn't always the most _convenient_ way to handle separate states. However, this isn't always the most _convenient_ way to handle separate states.
@ -69,9 +70,9 @@ workspace has its own Terraform configuration, set of variable values, state
data, run history, and settings. data, run history, and settings.
These two kinds of workspaces are different, but related. When [using Terraform These two kinds of workspaces are different, but related. When [using Terraform
CLI as a frontend for Terraform Cloud](/docs/cli/cloud/index.html), you can associate the current working CLI as a frontend for Terraform Cloud](/cli/cloud), you can associate the current working
directory with one or more remote workspaces. If you associate the directory with one or more remote workspaces. If you associate the
directory with multiple workspaces (using workspace tags), you can use the directory with multiple workspaces (using workspace tags), you can use the
`terraform workspace` commands to select which remote workspace to use. `terraform workspace` commands to select which remote workspace to use.
Refer to [CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud. Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud.

570
website/docs/configuration-0-11/interpolation.html.md
View File

@ -1,570 +0,0 @@
---
layout: "language"
page_title: "Interpolation Syntax - 0.11 Configuration Language"
sidebar_current: "docs-conf-old-interpolation"
description: |-
Embedded within strings in Terraform, whether you're using the Terraform syntax or JSON syntax, you can interpolate other values into strings. These interpolations are wrapped in `${}`, such as `${var.foo}`.
---
# Interpolation Syntax
-> **Note:** This page is about Terraform 0.11 and earlier. For Terraform 0.12
and later, see
[Configuration Language: Expressions](/docs/language/expressions/index.html) and
[Configuration Language: Functions](/docs/language/functions/index.html).
Embedded within strings in Terraform, whether you're using the
Terraform syntax or JSON syntax, you can interpolate other values. These
interpolations are wrapped in `${}`, such as `${var.foo}`.
The interpolation syntax is powerful and allows you to reference
variables, attributes of resources, call functions, etc.
You can perform [simple math](#math) in interpolations, allowing
you to write expressions such as `${count.index + 1}`. And you can
also use [conditionals](#conditionals) to determine a value based
on some logic.
You can escape interpolation with double dollar signs: `$${foo}`
will be rendered as a literal `${foo}`.
## Available Variables
There are a variety of available variable references you can use.
#### User string variables
Use the `var.` prefix followed by the variable name. For example,
`${var.foo}` will interpolate the `foo` variable value.
#### User map variables
The syntax is `var.<MAP>["<KEY>"]`. For example, `${var.amis["us-east-1"]}`
would get the value of the `us-east-1` key within the `amis` map
variable.
#### User list variables
The syntax is `"${var.<LIST>}"`. For example, `"${var.subnets}"`
would get the value of the `subnets` list, as a list. You can also
return list elements by index: `${var.subnets[idx]}`.
#### Attributes of your own resource
The syntax is `self.<ATTRIBUTE>`. For example `${self.private_ip}`
will interpolate that resource's private IP address.
-> **Note**: The `self.<ATTRIBUTE>` syntax is only allowed and valid within
provisioners.
#### Attributes of other resources
The syntax is `<TYPE>.<NAME>.<ATTRIBUTE>`. For example,
`${aws_instance.web.id}` will interpolate the ID attribute from the
`aws_instance` resource named `web`. If the resource has a `count`
attribute set, you can access individual attributes with a zero-based
index, such as `${aws_instance.web.0.id}`. You can also use the splat
syntax to get a list of all the attributes: `${aws_instance.web.*.id}`.
#### Attributes of a data source
The syntax is `data.<TYPE>.<NAME>.<ATTRIBUTE>`. For example. `${data.aws_ami.ubuntu.id}` will interpolate the `id` attribute from the `aws_ami` [data source](./data-sources.html) named `ubuntu`. If the data source has a `count`
attribute set, you can access individual attributes with a zero-based
index, such as `${data.aws_subnet.example.0.cidr_block}`. You can also use the splat
syntax to get a list of all the attributes: `${data.aws_subnet.example.*.cidr_block}`.
#### Outputs from a module
The syntax is `module.<NAME>.<OUTPUT>`. For example `${module.foo.bar}` will
interpolate the `bar` output from the `foo`
[module](/docs/language/modules/develop/index.html).
#### Count information
The syntax is `count.index`. For example, `${count.index}` will
interpolate the current index in a multi-count resource. For more
information on `count`, see the [resource configuration
page](./resources.html).
#### Path information
The syntax is `path.<TYPE>`. TYPE can be `cwd`, `module`, or `root`.
`cwd` will interpolate the current working directory. `module` will
interpolate the path to the current module. `root` will interpolate the
path of the root module. In general, you probably want the
`path.module` variable.
#### Terraform meta information
The syntax is `terraform.<FIELD>`. This variable type contains metadata about
the currently executing Terraform run. FIELD can currently only be `env` to
reference the currently active workspace.
## Conditionals
Interpolations may contain conditionals to branch on the final value.
```hcl
resource "aws_instance" "web" {
subnet = "${var.env == "production" ? var.prod_subnet : var.dev_subnet}"
}
```
The conditional syntax is the well-known ternary operation:
```text
CONDITION ? TRUEVAL : FALSEVAL
```
The condition can be any valid interpolation syntax, such as variable
access, a function call, or even another conditional. The true and false
value can also be any valid interpolation syntax. The returned types by
the true and false side must be the same.
The supported operators are:
* Equality: `==` and `!=`
* Numerical comparison: `>`, `<`, `>=`, `<=`
* Boolean logic: `&&`, `||`, unary `!`
A common use case for conditionals is to enable/disable a resource by
conditionally setting the count:
```hcl
resource "aws_instance" "vpn" {
count = "${var.something ? 1 : 0}"
}
```
In the example above, the "vpn" resource will only be included if
"var.something" evaluates to true. Otherwise, the VPN resource will
not be created at all.
## Built-in Functions
Terraform ships with built-in functions. Functions are called with the
syntax `name(arg, arg2, ...)`. For example, to read a file:
`${file("path.txt")}`.
~> **Note**: Proper escaping is required for JSON field values containing quotes
(`"`) such as `environment` values. If directly setting the JSON, they should be
escaped as `\"` in the JSON, e.g. `"value": "I \"love\" escaped quotes"`. If
using a Terraform variable value, they should be escaped as `\\\"` in the
variable, e.g. `value = "I \\\"love\\\" escaped quotes"` in the variable and
`"value": "${var.myvariable}"` in the JSON.
### Supported built-in functions
The supported built-in functions are:
* `abs(float)` - Returns the absolute value of a given float.
Example: `abs(1)` returns `1`, and `abs(-1)` would also return `1`,
whereas `abs(-3.14)` would return `3.14`. See also the `signum` function.
* `basename(path)` - Returns the last element of a path.
* `base64decode(string)` - Given a base64-encoded string, decodes it and
returns the original string.
* `base64encode(string)` - Returns a base64-encoded representation of the
given string.
* `base64gzip(string)` - Compresses the given string with gzip and then
encodes the result to base64. This can be used with certain resource
arguments that allow binary data to be passed with base64 encoding, since
Terraform strings are required to be valid UTF-8.
* `base64sha256(string)` - Returns a base64-encoded representation of raw
SHA-256 sum of the given string.
**This is not equivalent** of `base64encode(sha256(string))`
since `sha256()` returns hexadecimal representation.
* `base64sha512(string)` - Returns a base64-encoded representation of raw
SHA-512 sum of the given string.
**This is not equivalent** of `base64encode(sha512(string))`
since `sha512()` returns hexadecimal representation.
* `bcrypt(password, cost)` - Returns the Blowfish encrypted hash of the string
at the given cost. A default `cost` of 10 will be used if not provided.
* `ceil(float)` - Returns the least integer value greater than or equal
to the argument.
* `chomp(string)` - Removes trailing newlines from the given string.
* `chunklist(list, size)` - Returns the `list` items chunked by `size`.
Examples:
* `chunklist(aws_subnet.foo.*.id, 1)`: will outputs `[["id1"], ["id2"], ["id3"]]`
* `chunklist(var.list_of_strings, 2)`: will outputs `[["id1", "id2"], ["id3", "id4"], ["id5"]]`
* `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation
and creates an IP address with the given host number. If given host
number is negative, the count starts from the end of the range.
For example, `cidrhost("10.0.0.0/8", 2)` returns `10.0.0.2` and
`cidrhost("10.0.0.0/8", -2)` returns `10.255.255.254`.
* `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation
and returns the address-formatted subnet mask format that some
systems expect for IPv4 interfaces. For example,
`cidrnetmask("10.0.0.0/8")` returns `255.0.0.0`. Not applicable
to IPv6 networks since CIDR notation is the only valid notation for
IPv6.
* `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in
CIDR notation (like `10.0.0.0/8`) and extends its prefix to include an
additional subnet number. For example,
`cidrsubnet("10.0.0.0/8", 8, 2)` returns `10.2.0.0/16`;
`cidrsubnet("2607:f298:6051:516c::/64", 8, 2)` returns
`2607:f298:6051:516c:200::/72`.
* `coalesce(string1, string2, ...)` - Returns the first non-empty value from
the given arguments. At least two arguments must be provided.
* `coalescelist(list1, list2, ...)` - Returns the first non-empty list from
the given arguments. At least two arguments must be provided.
* `compact(list)` - Removes empty string elements from a list. This can be
useful in some cases, for example when passing joined lists as module
variables or when parsing module outputs.
Example: `compact(module.my_asg.load_balancer_names)`
* `concat(list1, list2, ...)` - Combines two or more lists into a single list.
Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)`
* `contains(list, element)` - Returns *true* if a list contains the given element
and returns *false* otherwise. Examples: `contains(var.list_of_strings, "an_element")`
* `dirname(path)` - Returns all but the last element of path, typically the path's directory.
* `distinct(list)` - Removes duplicate items from a list. Keeps the first
occurrence of each element, and removes subsequent occurrences. This
function is only valid for flat lists. Example: `distinct(var.usernames)`
* `element(list, index)` - Returns a single element from a list
at the given index. If the index is greater than the number of
elements, this function will wrap using a standard mod algorithm.
This function only works on flat lists. Examples:
* `element(aws_subnet.foo.*.id, count.index)`
* `element(var.list_of_strings, 2)`
* `file(path)` - Reads the contents of a file into the string. Variables
in this file are _not_ interpolated. The contents of the file are
read as-is. The `path` is interpreted relative to the working directory.
[Path variables](#path-information) can be used to reference paths relative
to other base locations. For example, when using `file()` from inside a
module, you generally want to make the path relative to the module base,
like this: `file("${path.module}/file")`.
* `floor(float)` - Returns the greatest integer value less than or equal to
the argument.
* `flatten(list of lists)` - Flattens lists of lists down to a flat list of
primitive values, eliminating any nested lists recursively. Examples:
* `flatten(data.github_user.user.*.gpg_keys)`
* `format(format, args, ...)` - Formats a string according to the given
format. The syntax for the format is standard `sprintf` syntax.
Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/).
Example to zero-prefix a count, used commonly for naming servers:
`format("web-%03d", count.index + 1)`.
* `formatlist(format, args, ...)` - Formats each element of a list
according to the given format, similarly to `format`, and returns a list.
Non-list arguments are repeated for each list element.
For example, to convert a list of DNS addresses to a list of URLs, you might use:
`formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`.
If multiple args are lists, and they have the same number of elements, then the formatting is applied to the elements of the lists in parallel.
Example:
`formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`.
Passing lists with different lengths to formatlist results in an error.
* `indent(numspaces, string)` - Prepends the specified number of spaces to all but the first
line of the given multi-line string. May be useful when inserting a multi-line string
into an already-indented context. The first line is not indented, to allow for the
indented string to be placed after some sort of already-indented preamble.
Example: `" \"items\": ${ indent(4, "[\n \"item1\"\n]") },"`
* `index(list, elem)` - Finds the index of a given element in a list.
This function only works on flat lists.
Example: `index(aws_instance.foo.*.tags.Name, "foo-test")`
* `join(delim, list)` - Joins the list with the delimiter for a resultant string.
This function works only on flat lists.
Examples:
* `join(",", aws_instance.foo.*.id)`
* `join(",", var.ami_list)`
* `jsonencode(value)` - Returns a JSON-encoded representation of the given
value, which can contain arbitrarily-nested lists and maps. Note that if
the value is a string then its value will be placed in quotes.
* `keys(map)` - Returns a lexically sorted list of the map keys.
* `length(list)` - Returns the number of members in a given list or map, or the number of characters in a given string.
* `${length(split(",", "a,b,c"))}` = 3
* `${length("a,b,c")}` = 5
* `${length(map("key", "val"))}` = 1
* `list(items, ...)` - Returns a list consisting of the arguments to the function.
This function provides a way of representing list literals in interpolation.
* `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`.
* `${list()}` returns an empty list.
* `log(x, base)` - Returns the logarithm of `x`.
* `lookup(map, key, [default])` - Performs a dynamic lookup into a map
variable. The `map` parameter should be another variable, such
as `var.amis`. If `key` does not exist in `map`, the interpolation will
fail unless you specify a third argument, `default`, which should be a
string value to return if no `key` is found in `map`. This function
only works on flat maps and will return an error for maps that
include nested lists or maps.
* `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case.
* `map(key, value, ...)` - Returns a map consisting of the key/value pairs
specified as arguments. Every odd argument must be a string key, and every
even argument must have the same type as the other values specified.
Duplicate keys are not allowed. Examples:
* `map("hello", "world")`
* `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))`
* `matchkeys(values, keys, searchset)` - For two lists `values` and `keys` of
equal length, returns all elements from `values` where the corresponding
element from `keys` exists in the `searchset` list. E.g.
`matchkeys(aws_instance.example.*.id,
aws_instance.example.*.availability_zone, list("us-west-2a"))` will return a
list of the instance IDs of the `aws_instance.example` instances in
`"us-west-2a"`. No match will result in empty list. Items of `keys` are
processed sequentially, so the order of returned `values` is preserved.
* `max(float1, float2, ...)` - Returns the largest of the floats.
* `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps
are consumed in the order provided, and duplicate keys overwrite previous
entries.
* `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}`
* `min(float1, float2, ...)` - Returns the smallest of the floats.
* `md5(string)` - Returns a (conventional) hexadecimal representation of the
MD5 hash of the given string.
* `pathexpand(string)` - Returns a filepath string with `~` expanded to the home directory. Note:
This will create a plan diff between two different hosts, unless the filepaths are the same.
* `pow(x, y)` - Returns the base `x` of exponential `y` as a float.
Example:
* `${pow(3,2)}` = 9
* `${pow(4,0)}` = 1
* `replace(string, search, replace)` - Does a search and replace on the
given string. All instances of `search` are replaced with the value
of `replace`. If `search` is wrapped in forward slashes, it is treated
as a regular expression. If using a regular expression, `replace`
can reference subcaptures in the regular expression by using `$n` where
`n` is the index or name of the subcapture. If using a regular expression,
the syntax conforms to the [re2 regular expression syntax](https://github.com/google/re2/wiki/Syntax).
* `rsadecrypt(string, key)` - Decrypts `string` using RSA. The padding scheme
PKCS #1 v1.5 is used. The `string` must be base64-encoded. `key` must be an
RSA private key in PEM format. You may use `file()` to load it from a file.
* `sha1(string)` - Returns a (conventional) hexadecimal representation of the
SHA-1 hash of the given string.
Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"`
* `sha256(string)` - Returns a (conventional) hexadecimal representation of the
SHA-256 hash of the given string.
Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"`
* `sha512(string)` - Returns a (conventional) hexadecimal representation of the
SHA-512 hash of the given string.
Example: `"${sha512("${aws_vpc.default.tags.customer}-s3-bucket")}"`
* `signum(integer)` - Returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers.
This function is useful when you need to set a value for the first resource and
a different value for the rest of the resources.
Example: `element(split(",", var.r53_failover_policy), signum(count.index))`
where the 0th index points to `PRIMARY` and 1st to `FAILOVER`
* `slice(list, from, to)` - Returns the portion of `list` between `from` (inclusive) and `to` (exclusive).
Example: `slice(var.list_of_strings, 0, length(var.list_of_strings) - 1)`
* `sort(list)` - Returns a lexicographically sorted list of the strings contained in
the list passed as an argument. Sort may only be used with lists which contain only
strings.
Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)`
* `split(delim, string)` - Returns a list by splitting the string based on
the delimiter. This is useful for pushing lists through module
outputs since they currently only support string values. Depending on the
use, the string this is being performed within may need to be wrapped
in brackets to indicate that the output is actually a list, e.g.
`a_resource_param = ["${split(",", var.CSV_STRING)}"]`.
Example: `split(",", module.amod.server_ids)`
* `substr(string, offset, length)` - Extracts a substring from the input string. A negative offset is interpreted as being equivalent to a positive offset measured backwards from the end of the string. A length of `-1` is interpreted as meaning "until the end of the string".
* `timestamp()` - Returns a UTC timestamp string in RFC 3339 format. This string will change with every
invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the
[`ignore_changes`](./resources.html#ignore_changes) lifecycle attribute.
* `timeadd(time, duration)` - Returns a UTC timestamp string corresponding to adding a given `duration` to `time` in RFC 3339 format.
For example, `timeadd("2017-11-22T00:00:00Z", "10m")` produces a value `"2017-11-22T00:10:00Z"`.
* `title(string)` - Returns a copy of the string with the first characters of all the words capitalized.
* `transpose(map)` - Swaps the keys and list values in a map of lists of strings. For example, transpose(map("a", list("1", "2"), "b", list("2", "3")) produces a value equivalent to map("1", list("a"), "2", list("a", "b"), "3", list("b")).
* `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed.
* `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case.
* `urlencode(string)` - Returns an URL-safe copy of the string.
* `uuid()` - Returns a random UUID string. This string will change with every invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the [`ignore_changes`](./resources.html#ignore_changes) lifecycle attribute.
* `values(map)` - Returns a list of the map values, in the order of the keys
returned by the `keys` function. This function only works on flat maps and
will return an error for maps that include nested lists or maps.
* `zipmap(list, list)` - Creates a map from a list of keys and a list of
values. The keys must all be of type string, and the length of the lists
must be the same.
For example, to output a mapping of AWS IAM user names to the fingerprint
of the key used to encrypt their initial password, you might use:
`zipmap(aws_iam_user.users.*.name, aws_iam_user_login_profile.users.*.key_fingerprint)`.
The hashing functions `base64sha256`, `base64sha512`, `md5`, `sha1`, `sha256`,
and `sha512` all have variants with a `file` prefix, like `filesha1`, which
interpret their first argument as a path to a file on disk rather than as a
literal string. This allows safely creating hashes of binary files that might
otherwise be corrupted in memory if loaded into Terraform strings (which are
assumed to be UTF-8). `filesha1(filename)` is equivalent to `sha1(file(filename))`
in Terraform 0.11 and earlier, but the latter will fail for binary files in
Terraform 0.12 and later.
## Templates
Long strings can be managed using templates.
[Templates](https://registry.terraform.io/providers/hashicorp/template/latest/docs) are
[data-sources](./data-sources.html) defined by a
string with interpolation tokens (usually loaded from a file) and some variables
to use during interpolation. They have a computed `rendered` attribute
containing the result.
A template data source looks like:
```hcl
# templates/greeting.tpl
${hello} ${world}!
```
```hcl
data "template_file" "example" {
template = "${file("templates/greeting.tpl")}"
vars {
hello = "goodnight"
world = "moon"
}
}
output "rendered" {
value = "${data.template_file.example.rendered}"
}
```
Then the rendered value would be `goodnight moon!`.
-> **Note:** If you specify the template as a literal string instead of loading
a file, the inline template must use double dollar signs (like `$${hello}`) to
prevent Terraform from interpolating values from the configuration into the
string. This is because `template_file` creates its own instance of the
interpolation system, with values provided by its nested `vars` block instead of
by the surrounding scope of the configuration.
You may use any of the built-in functions in your template. For more
details on template usage, please see the
[template_file documentation](https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file).
### Using Templates with Count
Here is an example that combines the capabilities of templates with the interpolation
from `count` to give us a parameterized template, unique to each resource instance:
```hcl
variable "hostnames" {
default = {
"0" = "example1.org"
"1" = "example2.net"
}
}
data "template_file" "web_init" {
# Render the template once for each instance
count = "${length(var.hostnames)}"
template = "${file("templates/web_init.tpl")}"
vars {
# count.index tells us the index of the instance we are rendering
hostname = "${var.hostnames[count.index]}"
}
}
resource "aws_instance" "web" {
# Create one instance for each hostname
count = "${length(var.hostnames)}"
# Pass each instance its corresponding template_file
user_data = "${data.template_file.web_init.*.rendered[count.index]}"
}
```
With this, we will build a list of `template_file.web_init` data resources
which we can use in combination with our list of `aws_instance.web` resources.
## Math
Simple math can be performed in interpolations:
```hcl
variable "count" {
default = 2
}
resource "aws_instance" "web" {
# ...
count = "${var.count}"
# Tag the instance with a counter starting at 1, ie. web-001
tags {
Name = "${format("web-%03d", count.index + 1)}"
}
}
```
The supported operations are:
- *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types
- *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types
Operator precedences is the standard mathematical order of operations:
*Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) have precedence over
*Add* (`+`) and *Subtract* (`-`). Parenthesis can be used to force ordering.
```text
"${2 * 4 + 3 * 3}" # computes to 17
"${3 * 3 + 2 * 4}" # computes to 17
"${2 * (4 + 3) * 3}" # computes to 42
```
You can use the [terraform console](/docs/cli/commands/console.html) command to
try the math operations.
-> **Note:** Since Terraform allows hyphens in resource and variable names,
it's best to use spaces between math operators to prevent confusion or unexpected
behavior. For example, `${var.instance-count - 1}` will subtract **1** from the
`instance-count` variable value, while `${var.instance-count-1}` will interpolate
the `instance-count-1` variable value.

157
website/docs/configuration/expressions.html.md
View File

@ -1,157 +0,0 @@
---
layout: "language"
page_title: "Expressions Landing Page - Configuration Language"
sidebar_current: "docs-config-expressions"
---
# Expressions Landing Page
To improve navigation, we've split the old Expressions page into several smaller
pages.
<a id="types-and-values"></a>
<a id="advanced-type-details"></a>
<a id="type-conversion"></a>
<a id="literal-expressions"></a>
<a id="indices-and-attributes"></a>
## Types and Values, Literal Expressions, Indices and Attributes
Terraform's types are `string`, `number`, `bool`, `list`, `tuple`, `map`,
`object`, and `null`.
This information has moved to
[Types and Values](/docs/language/expressions/types.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="references-to-named-values"></a>
<a id="local-named-values"></a>
<a id="named-values-and-dependencies"></a>
<a id="references-to-resource-attributes"></a>
<a id="local-named-values-1"></a>
<a id="values-not-yet-known"></a>
## References to Named Values (Resource Attributes, Variables, etc.)
You can refer to certain values by name, like `var.some_variable` or
`aws_instance.example.ami`.
This information has moved to
[References to Values](/docs/language/expressions/references.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="arithmetic-operators"></a>
<a id="equality-operators"></a>
<a id="comparison-operators"></a>
<a id="logical-operators"></a>
## Arithmetic and Logical Operators
Operators are expressions that transform other expressions, like adding two
numbers (`+`) or comparing two values to get a bool (`==`, `>=`, etc.).
This information has moved to
[Operators](/docs/language/expressions/operators.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
## Conditional Expressions
The `condition ? true_val : false_val` expression chooses between two
expressions based on a bool condition.
This information has moved to
[Conditional Expressions](/docs/language/expressions/conditionals.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="expanding-function-arguments"></a>
<a id="available-functions"></a>
## Function Calls
Terraform's functions can be called like `function_name(arg1, arg2)`.
This information has moved to
[Function Calls](/docs/language/expressions/function-calls.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="for-expressions"></a>
## `for` Expressions
Expressions like `[for s in var.list : upper(s)]` can transform a complex type
value into another complex type value.
This information has moved to
[For Expressions](/docs/language/expressions/for.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="splat-expressions"></a>
<a id="legacy-attribute-only-splat-expressions"></a>
## Splat Expressions
Expressions like `var.list[*].id` can extract simpler collections from complex
collections.
This information has moved to
[Splat Expressions](/docs/language/expressions/splat.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="dynamic-blocks"></a>
<a id="best-practices-for-dynamic-blocks"></a>
## `dynamic` Blocks
The special `dynamic` block type serves the same purpose as a `for` expression,
except it creates multiple repeatable nested blocks instead of a complex value.
This information has moved to
[Dynamic Blocks](/docs/language/expressions/dynamic-blocks.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>
<a id="string-literals"></a>
<a id="string-templates"></a>
<a id="interpolation"></a>
<a id="directives"></a>
## String Literals and String Templates
Strings can be `"double-quoted"` or
```hcl
<<EOT
heredocs
EOT
```
Strings can also include escape sequences like `\n`, interpolation sequences
(`${ ... }`), and template sequences (`%{ ... }`).
This information has moved to
[Strings and Templates](/docs/language/expressions/strings.html).
<div style="height: 30vh; margin: 0; padding: 0;"></div>

121
website/docs/configuration/expressions.mdx Normal file
View File

@ -0,0 +1,121 @@
---
page_title: Expressions Landing Page - Configuration Language
---
# Expressions Landing Page
To improve navigation, we've split the old Expressions page into several smaller
pages.
<a id="types-and-values"></a> <a id="advanced-type-details"></a> <a id="type-conversion"></a> <a id="literal-expressions"></a> <a id="indices-and-attributes"></a>
## Types and Values, Literal Expressions, Indices and Attributes
Terraform's types are `string`, `number`, `bool`, `list`, `tuple`, `map`,
`object`, and `null`.
This information has moved to
[Types and Values](/language/expressions/types).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="references-to-named-values"></a> <a id="local-named-values"></a> <a id="named-values-and-dependencies"></a> <a id="references-to-resource-attributes"></a> <a id="local-named-values-1"></a> <a id="values-not-yet-known"></a>
## References to Named Values (Resource Attributes, Variables, etc.)
You can refer to certain values by name, like `var.some_variable` or
`aws_instance.example.ami`.
This information has moved to
[References to Values](/language/expressions/references).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="arithmetic-operators"></a> <a id="equality-operators"></a> <a id="comparison-operators"></a> <a id="logical-operators"></a>
## Arithmetic and Logical Operators
Operators are expressions that transform other expressions, like adding two
numbers (`+`) or comparing two values to get a bool (`==`, `>=`, etc.).
This information has moved to
[Operators](/language/expressions/operators).
<div style={{height: '30vh', margin: 0, padding: 0}} />
## Conditional Expressions
The `condition ? true_val : false_val` expression chooses between two
expressions based on a bool condition.
This information has moved to
[Conditional Expressions](/language/expressions/conditionals).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="expanding-function-arguments"></a> <a id="available-functions"></a>
## Function Calls
Terraform's functions can be called like `function_name(arg1, arg2)`.
This information has moved to
[Function Calls](/language/expressions/function-calls).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="for-expressions"></a>
## `for` Expressions
Expressions like `[for s in var.list : upper(s)]` can transform a complex type
value into another complex type value.
This information has moved to
[For Expressions](/language/expressions/for).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="splat-expressions"></a> <a id="legacy-attribute-only-splat-expressions"></a>
## Splat Expressions
Expressions like `var.list[*].id` can extract simpler collections from complex
collections.
This information has moved to
[Splat Expressions](/language/expressions/splat).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="dynamic-blocks"></a> <a id="best-practices-for-dynamic-blocks"></a>
## `dynamic` Blocks
The special `dynamic` block type serves the same purpose as a `for` expression,
except it creates multiple repeatable nested blocks instead of a complex value.
This information has moved to
[Dynamic Blocks](/language/expressions/dynamic-blocks).
<div style={{height: '30vh', margin: 0, padding: 0}} />
<a id="string-literals"></a> <a id="string-templates"></a> <a id="interpolation"></a> <a id="directives"></a>
## String Literals and String Templates
Strings can be `"double-quoted"` or
```hcl
<<EOT
heredocs
EOT
```
Strings can also include escape sequences like `\n`, interpolation sequences
(`${ ... }`), and template sequences (`%{ ... }`).
This information has moved to
[Strings and Templates](/language/expressions/strings).
<div style={{height: '30vh', margin: 0, padding: 0}} />

5
website/docs/configuration/index.mdx Normal file
View File

@ -0,0 +1,5 @@
---
page_title: Terraform Configuration
---
# Terraform Configuration

54
website/docs/configuration/modules.html.md
View File

@ -1,54 +0,0 @@
---
layout: "language"
page_title: "Modules Landing Page - Configuration Language"
---
# Modules Landing Page
To improve navigation, we've split the old Modules page into several smaller
pages.
<a id="calling-a-child-module"></a>
<a id="accessing-module-output-values"></a>
<a id="transferring-resource-state-into-modules"></a>
<a id="tainting-resources-within-a-module"></a>
<a id="module-versions"></a>
<a id="other-meta-arguments"></a>
## Syntax and Elements of Module Blocks
This information has moved to
[Module Blocks](/docs/language/modules/syntax.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="multiple-instances-of-a-module"></a>
## Multiple Instances with `count` and `for_each`
This information has moved to
[`count`](/docs/language/meta-arguments/count.html) and
[`for_each`](/docs/language/meta-arguments/for_each.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="providers-within-modules"></a>
<a id="provider-version-constraints-in-modules"></a>
<a id="implicit-provider-inheritance"></a>
<a id="passing-providers-explicitly"></a>
<a id="proxy-configuration-blocks"></a>
<a id="legacy-shared-modules-with-provider-configurations"></a>
## Handling Provider Configurations in Re-usable Modules
This information has moved to
[The `providers` Meta-Argument](/docs/language/meta-arguments/module-providers.html)
(for users of re-usable modules) and
[Providers Within Modules](/docs/language/modules/develop/providers.html)
(for module developers).
<div style="height: 100vh; margin: 0; padding: 0;"></div>

39
website/docs/configuration/modules.mdx Normal file
View File

@ -0,0 +1,39 @@
---
page_title: Modules Landing Page - Configuration Language
---
# Modules Landing Page
To improve navigation, we've split the old Modules page into several smaller
pages.
<a id="calling-a-child-module"></a> <a id="accessing-module-output-values"></a> <a id="transferring-resource-state-into-modules"></a> <a id="tainting-resources-within-a-module"></a> <a id="module-versions"></a> <a id="other-meta-arguments"></a>
## Syntax and Elements of Module Blocks
This information has moved to
[Module Blocks](/language/modules/syntax).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="multiple-instances-of-a-module"></a>
## Multiple Instances with `count` and `for_each`
This information has moved to
[`count`](/language/meta-arguments/count) and
[`for_each`](/language/meta-arguments/for_each).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="providers-within-modules"></a> <a id="provider-version-constraints-in-modules"></a> <a id="implicit-provider-inheritance"></a> <a id="passing-providers-explicitly"></a> <a id="proxy-configuration-blocks"></a> <a id="legacy-shared-modules-with-provider-configurations"></a>
## Handling Provider Configurations in Re-usable Modules
This information has moved to
[The `providers` Meta-Argument](/language/meta-arguments/module-providers)
(for users of re-usable modules) and
[Providers Within Modules](/language/modules/develop/providers)
(for module developers).
<div style={{height: '100vh', margin: 0, padding: 0}} />

135
website/docs/configuration/resources.html.md
View File

@ -1,135 +0,0 @@
---
layout: "language"
page_title: "Resources Landing Page - Configuration Language"
---
# Resources Landing Page
To improve navigation, we've split the old Resources page into several smaller
pages.
<a id="resource-syntax"></a>
<a id="resource-types"></a>
<a id="providers"></a>
<a id="resource-arguments"></a>
<a id="documentation-for-resource-types"></a>
<a id="meta-arguments"></a>
<a id="timeouts"></a>
<a id="operation-timeouts"></a>
## Syntax and Elements of Resource Blocks
This information has moved to
[Resource Blocks](/docs/language/resources/syntax.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="resource-behavior"></a>
<a id="accessing-resource-attributes"></a>
<a id="resource-dependencies"></a>
<a id="local-only-resources"></a>
## Details of Resource Behavior
This information has moved to
[Resource Behavior](/docs/language/resources/behavior.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
## Resource Meta-Arguments
Each resource meta-argument has moved to its own page:
- [`depends_on`](/docs/language/meta-arguments/depends_on.html)
- [`count`](/docs/language/meta-arguments/count.html)
- [`for_each`](/docs/language/meta-arguments/for_each.html)
- [`provider`](/docs/language/meta-arguments/resource-provider.html)
- [`lifecycle`](/docs/language/meta-arguments/lifecycle.html)
- [Provisioners](/docs/language/resources/provisioners/index.html)
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="depends_on-explicit-resource-dependencies"></a>
### `depends_on`
This information has moved to
[`depends_on`](/docs/language/meta-arguments/depends_on.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="count-multiple-resource-instances-by-count"></a>
<a id="count-multiple-resource-instances"></a>
<a id="the-count-object"></a>
<a id="count-index"></a>
<a id="referring-to-instances"></a>
<a id="using-expressions-in-count"></a>
<a id="when-to-use-for_each-instead-of-count"></a>
### `count`
This information has moved to
[`count`](/docs/language/meta-arguments/count.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings"></a>
<a id="the-each-object"></a>
<a id="each-key"></a>
<a id="each-value"></a>
<a id="using-expressions-in-for_each"></a>
<a id="referring-to-instances-1"></a>
<a id="using-sets"></a>
### `for_each`
This information has moved to
[`for_each`](/docs/language/meta-arguments/for_each.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="provider-selecting-a-non-default-provider-configuration"></a>
### `provider`
This information has moved to
[`provider`](/docs/language/meta-arguments/resource-provider.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="lifecycle-lifecycle-customizations"></a>
<a id="prevent_destroy"></a>
<a id="create_before_destroy"></a>
<a id="ignore_changes"></a>
### `lifecycle`
This information has moved to
[`lifecycle`](/docs/language/meta-arguments/lifecycle.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>
<a id="provisioner-and-connection-resource-provisioners"></a>
### Provisioners
This information has moved to
[Provisioners](/docs/language/resources/provisioners/index.html).
<div style="height: 100vh; margin: 0; padding: 0;"></div>

93
website/docs/configuration/resources.mdx Normal file
View File

@ -0,0 +1,93 @@
---
page_title: Resources Landing Page - Configuration Language
---
# Resources Landing Page
To improve navigation, we've split the old Resources page into several smaller
pages.
<a id="resource-syntax"></a> <a id="resource-types"></a> <a id="providers"></a> <a id="resource-arguments"></a> <a id="documentation-for-resource-types"></a> <a id="meta-arguments"></a> <a id="timeouts"></a> <a id="operation-timeouts"></a>
## Syntax and Elements of Resource Blocks
This information has moved to
[Resource Blocks](/language/resources/syntax).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="resource-behavior"></a> <a id="accessing-resource-attributes"></a> <a id="resource-dependencies"></a> <a id="local-only-resources"></a>
## Details of Resource Behavior
This information has moved to
[Resource Behavior](/language/resources/behavior).
<div style={{height: '100vh', margin: 0, padding: 0}} />
## Resource Meta-Arguments
Each resource meta-argument has moved to its own page:
- [`depends_on`](/language/meta-arguments/depends_on)
- [`count`](/language/meta-arguments/count)
- [`for_each`](/language/meta-arguments/for_each)
- [`provider`](/language/meta-arguments/resource-provider)
- [`lifecycle`](/language/meta-arguments/lifecycle)
- [Provisioners](/language/resources/provisioners)
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="depends_on-explicit-resource-dependencies"></a>
### `depends_on`
This information has moved to
[`depends_on`](/language/meta-arguments/depends_on).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="count-multiple-resource-instances-by-count"></a> <a id="count-multiple-resource-instances"></a> <a id="the-count-object"></a> <a id="count-index"></a> <a id="referring-to-instances"></a> <a id="using-expressions-in-count"></a> <a id="when-to-use-for_each-instead-of-count"></a>
### `count`
This information has moved to
[`count`](/language/meta-arguments/count).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings"></a> <a id="the-each-object"></a> <a id="each-key"></a> <a id="each-value"></a> <a id="using-expressions-in-for_each"></a> <a id="referring-to-instances-1"></a> <a id="using-sets"></a>
### `for_each`
This information has moved to
[`for_each`](/language/meta-arguments/for_each).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="provider-selecting-a-non-default-provider-configuration"></a>
### `provider`
This information has moved to
[`provider`](/language/meta-arguments/resource-provider).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="lifecycle-lifecycle-customizations"></a> <a id="prevent_destroy"></a> <a id="create_before_destroy"></a> <a id="ignore_changes"></a>
### `lifecycle`
This information has moved to
[`lifecycle`](/language/meta-arguments/lifecycle).
<div style={{height: '100vh', margin: 0, padding: 0}} />
<a id="provisioner-and-connection-resource-provisioners"></a>
### Provisioners
This information has moved to
[Provisioners](/language/resources/provisioners).
<div style={{height: '100vh', margin: 0, padding: 0}} />

12
website/docs/internals/archiving.html.md → website/docs/internals/archiving.mdx
View File

@ -1,9 +1,9 @@
--- ---
layout: "docs" page_title: Archiving Providers
page_title: "Archiving Providers" description: >-
sidebar_current: "docs-internals" Terraform is built on a plugin-based architecture, much of which is maintained
description: |- by our user community. Occasionally, unmaintained providers may archived to
Terraform is built on a plugin-based architecture, much of which is maintained by our user community. Occasionally, unmaintained providers may archived to reduce confusion for users and developers. reduce confusion for users and developers.
--- ---
<!-- <!--
@ -25,4 +25,4 @@ What does archiving mean?
HashiCorp may archive a provider when we or the community are not able to support it at a level consistent with our open source guidelines and community expectations. HashiCorp may archive a provider when we or the community are not able to support it at a level consistent with our open source guidelines and community expectations.
Archiving is reversible. If anyone from the community is willing to maintain an archived provider, please reach out to the [Terraform Provider Development Program](https://www.terraform.io/guides/terraform-provider-development-program.html) at *terraform-provider-dev@hashicorp.com*. Archiving is reversible. If anyone from the community is willing to maintain an archived provider, please reach out to the [Terraform Provider Development Program](/docs/partnerships) at _<terraform-provider-dev@hashicorp.com>_.

23
website/docs/internals/credentials-helpers.html.md → website/docs/internals/credentials-helpers.mdx
View File

@ -1,18 +1,17 @@
--- ---
layout: "docs" page_title: Credentials Helpers
page_title: "Credentials Helpers" description: >-
sidebar_current: "docs-internals-credentials-helpers" Credentials helpers are external programs that know how to store and retrieve
description: |- API tokens for remote Terraform services.
Credentials helpers are external programs that know how to store and retrieve API tokens for remote Terraform services.
--- ---
# Credentials Helpers # Credentials Helpers
For Terraform-specific features that interact with remote network services, For Terraform-specific features that interact with remote network services,
such as [module registries](/docs/registry/) and such as [module registries](/registry) and
[remote operations](/docs/cloud/run/cli.html), Terraform by default looks for [remote operations](/cloud-docs/run/cli), Terraform by default looks for
API credentials to use in these calls in API credentials to use in these calls in
[the CLI configuration](/docs/cli/config/config-file.html). [the CLI configuration](/cli/config/config-file).
Credentials helpers offer an alternative approach that allows you to customize Credentials helpers offer an alternative approach that allows you to customize
how Terraform obtains credentials using an external program, which can then how Terraform obtains credentials using an external program, which can then
@ -20,7 +19,7 @@ directly access an existing secrets management system in your organization.
This page is about how to write and install a credentials helper. To learn This page is about how to write and install a credentials helper. To learn
how to configure a credentials helper that was already installed, see how to configure a credentials helper that was already installed, see
[the CLI config Credentials Helpers section](/docs/cli/config/config-file.html#credentials-helpers). [the CLI config Credentials Helpers section](/cli/config/config-file#credentials-helpers).
## How Terraform finds Credentials Helpers ## How Terraform finds Credentials Helpers
@ -30,7 +29,7 @@ particular location and whose name follows a specific naming convention.
A credentials helper called "credstore", for example, would be implemented as A credentials helper called "credstore", for example, would be implemented as
an executable program named `terraform-credentials-credstore` (with an `.exe` an executable program named `terraform-credentials-credstore` (with an `.exe`
extension on Windows only), and installed in one of the extension on Windows only), and installed in one of the
[default plugin search locations](/docs/extend/how-terraform-works.html#plugin-locations). [default plugin search locations](/plugin/how-terraform-works#plugin-locations).
## How Terraform runs Credentials Helpers ## How Terraform runs Credentials Helpers
@ -57,7 +56,7 @@ The current set of verbs are:
To represent credentials, the credentials helper protocol uses a JSON object To represent credentials, the credentials helper protocol uses a JSON object
whose contents correspond with the contents of whose contents correspond with the contents of
[`credentials` blocks in the CLI configuration](/docs/cli/config/config-file.html#credentials). [`credentials` blocks in the CLI configuration](/cli/config/config-file#credentials).
To represent an API token, the object contains a property called "token" whose To represent an API token, the object contains a property called "token" whose
value is the token string: value is the token string:
@ -160,7 +159,7 @@ other properties as described above.
Terraform does not have any automatic installation mechanism for credentials Terraform does not have any automatic installation mechanism for credentials
helpers. Instead, the user must extract the helper program executable into helpers. Instead, the user must extract the helper program executable into
one of the [default plugin search locations](/docs/extend/how-terraform-works.html#plugin-locations). one of the [default plugin search locations](/plugin/how-terraform-works#plugin-locations).
If you are packaging a credentials helper for distribution, place it in an If you are packaging a credentials helper for distribution, place it in an
named with the expected naming scheme (`terraform-credentials-example`) and, named with the expected naming scheme (`terraform-credentials-example`) and,

11
website/docs/internals/debugging.html.md → website/docs/internals/debugging.mdx
View File

@ -1,15 +1,14 @@
--- ---
layout: "docs" page_title: Debugging
page_title: "Debugging" description: >-
sidebar_current: "docs-internals-debug" Terraform has detailed logs which can be enabled by setting the TF_LOG
description: |- environment variable to any value. This will cause detailed logs to appear on
Terraform has detailed logs which can be enabled by setting the TF_LOG environment variable to any value. This will cause detailed logs to appear on stderr stderr
--- ---
# Debugging Terraform # Debugging Terraform
> **Hands-on:** Try the [Create Dynamic Expressions](https://learn.hashicorp.com/tutorials/terraform/troubleshooting-workflow#bug-reporting-best-practices?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. > **Hands-on:** Try the [Create Dynamic Expressions](https://learn.hashicorp.com/tutorials/terraform/troubleshooting-workflow#bug-reporting-best-practices?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
Terraform has detailed logs which can be enabled by setting the `TF_LOG` environment variable to any value. This will cause detailed logs to appear on stderr. Terraform has detailed logs which can be enabled by setting the `TF_LOG` environment variable to any value. This will cause detailed logs to appear on stderr.

121
website/docs/internals/graph.html.md
View File

@ -1,121 +0,0 @@
---
layout: "docs"
page_title: "Resource Graph"
sidebar_current: "docs-internals-graph"
description: |-
Terraform builds a dependency graph from the Terraform configurations, and walks this graph to generate plans, refresh state, and more. This page documents the details of what are contained in this graph, what types of nodes there are, and how the edges of the graph are determined.
---
# Resource Graph
Terraform builds a
[dependency graph](https://en.wikipedia.org/wiki/Dependency_graph)
from the Terraform configurations, and walks this graph to
generate plans, refresh state, and more. This page documents
the details of what are contained in this graph, what types
of nodes there are, and how the edges of the graph are determined.
~> **Advanced Topic!** This page covers technical details
of Terraform. You don't need to understand these details to
effectively use Terraform. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code.
For some background on graph theory, and a summary of how
Terraform applies it, see the HashiCorp 2016 presentation
[_Applying Graph Theory to Infrastructure as Code_](https://www.youtube.com/watch?v=Ce3RNfRbdZ0).
This presentation also covers some similar ideas to the following
guide.
## Graph Nodes
There are only a handful of node types that can exist within the
graph. We'll cover these first before explaining how they're
determined and built:
* **Resource Node** - Represents a single resource. If you have
the `count` metaparameter set, then there will be one resource
node for each count. The configuration, diff, state, etc. of
the resource under change is attached to this node.
* **Provider Configuration Node** - Represents the time to fully
configure a provider. This is when the provider configuration
block is given to a provider, such as AWS security credentials.
* **Resource Meta-Node** - Represents a group of resources, but
does not represent any action on its own. This is done for
convenience on dependencies and making a prettier graph. This
node is only present for resources that have a `count`
parameter greater than 1.
When visualizing a configuration with `terraform graph`, you can
see all of these nodes present.
## Building the Graph
Building the graph is done in a series of sequential steps:
1. Resources nodes are added based on the configuration. If a
diff (plan) or state is present, that meta-data is attached
to each resource node.
1. Resources are mapped to provisioners if they have any
defined. This must be done after all resource nodes are
created so resources with the same provisioner type can
share the provisioner implementation.
1. Explicit dependencies from the `depends_on` meta-parameter
are used to create edges between resources.
1. If a state is present, any "orphan" resources are added to
the graph. Orphan resources are any resources that are no
longer present in the configuration but are present in the
state file. Orphans never have any configuration associated
with them, since the state file does not store configuration.
1. Resources are mapped to providers. Provider configuration
nodes are created for these providers, and edges are created
such that the resources depend on their respective provider
being configured.
1. Interpolations are parsed in resource and provider configurations
to determine dependencies. References to resource attributes
are turned into dependencies from the resource with the interpolation
to the resource being referenced.
1. Create a root node. The root node points to all resources and
is created so there is a single root to the dependency graph. When
traversing the graph, the root node is ignored.
1. If a diff is present, traverse all resource nodes and find resources
that are being destroyed. These resource nodes are split into two:
one node that destroys the resource and another that creates
the resource (if it is being recreated). The reason the nodes must
be split is because the destroy order is often different from the
create order, and so they can't be represented by a single graph
node.
1. Validate the graph has no cycles and has a single root.
## Walking the Graph
<a id="walking-the-graph"></a>
To walk the graph, a standard depth-first traversal is done. Graph
walking is done in parallel: a node is walked as soon as all of its
dependencies are walked.
The amount of parallelism is limited using a semaphore to prevent too many
concurrent operations from overwhelming the resources of the machine running
Terraform. By default, up to 10 nodes in the graph will be processed
concurrently. This number can be set using the `-parallelism` flag on the
[plan](/docs/cli/commands/plan.html), [apply](/docs/cli/commands/apply.html), and
[destroy](/docs/cli/commands/destroy.html) commands.
Setting `-parallelism` is considered an advanced operation and should not be
necessary for normal usage of Terraform. It may be helpful in certain special
use cases or to help debug Terraform issues.
Note that some providers (AWS, for example), handle API rate limiting issues at
a lower level by implementing graceful backoff/retry in their respective API
clients. For this reason, Terraform does not use this `parallelism` feature to
address API rate limits directly.

123
website/docs/internals/graph.mdx Normal file
View File

@ -0,0 +1,123 @@
---
page_title: Resource Graph
description: >-
Terraform builds a dependency graph from the Terraform configurations, and
walks this graph to generate plans, refresh state, and more. This page
documents the details of what are contained in this graph, what types of nodes
there are, and how the edges of the graph are determined.
---
# Resource Graph
Terraform builds a
[dependency graph](https://en.wikipedia.org/wiki/Dependency_graph)
from the Terraform configurations, and walks this graph to
generate plans, refresh state, and more. This page documents
the details of what are contained in this graph, what types
of nodes there are, and how the edges of the graph are determined.
~> **Advanced Topic!** This page covers technical details
of Terraform. You don't need to understand these details to
effectively use Terraform. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code.
For some background on graph theory, and a summary of how
Terraform applies it, see the HashiCorp 2016 presentation
[_Applying Graph Theory to Infrastructure as Code_](https://www.youtube.com/watch?v=Ce3RNfRbdZ0).
This presentation also covers some similar ideas to the following
guide.
## Graph Nodes
There are only a handful of node types that can exist within the
graph. We'll cover these first before explaining how they're
determined and built:
- **Resource Node** - Represents a single resource. If you have
the `count` metaparameter set, then there will be one resource
node for each count. The configuration, diff, state, etc. of
the resource under change is attached to this node.
- **Provider Configuration Node** - Represents the time to fully
configure a provider. This is when the provider configuration
block is given to a provider, such as AWS security credentials.
- **Resource Meta-Node** - Represents a group of resources, but
does not represent any action on its own. This is done for
convenience on dependencies and making a prettier graph. This
node is only present for resources that have a `count`
parameter greater than 1.
When visualizing a configuration with `terraform graph`, you can
see all of these nodes present.
## Building the Graph
Building the graph is done in a series of sequential steps:
1. Resources nodes are added based on the configuration. If a
diff (plan) or state is present, that meta-data is attached
to each resource node.
1. Resources are mapped to provisioners if they have any
defined. This must be done after all resource nodes are
created so resources with the same provisioner type can
share the provisioner implementation.
1. Explicit dependencies from the `depends_on` meta-parameter
are used to create edges between resources.
1. If a state is present, any "orphan" resources are added to
the graph. Orphan resources are any resources that are no
longer present in the configuration but are present in the
state file. Orphans never have any configuration associated
with them, since the state file does not store configuration.
1. Resources are mapped to providers. Provider configuration
nodes are created for these providers, and edges are created
such that the resources depend on their respective provider
being configured.
1. Interpolations are parsed in resource and provider configurations
to determine dependencies. References to resource attributes
are turned into dependencies from the resource with the interpolation
to the resource being referenced.
1. Create a root node. The root node points to all resources and
is created so there is a single root to the dependency graph. When
traversing the graph, the root node is ignored.
1. If a diff is present, traverse all resource nodes and find resources
that are being destroyed. These resource nodes are split into two:
one node that destroys the resource and another that creates
the resource (if it is being recreated). The reason the nodes must
be split is because the destroy order is often different from the
create order, and so they can't be represented by a single graph
node.
1. Validate the graph has no cycles and has a single root.
## Walking the Graph
<a id="walking-the-graph"></a>
To walk the graph, a standard depth-first traversal is done. Graph
walking is done in parallel: a node is walked as soon as all of its
dependencies are walked.
The amount of parallelism is limited using a semaphore to prevent too many
concurrent operations from overwhelming the resources of the machine running
Terraform. By default, up to 10 nodes in the graph will be processed
concurrently. This number can be set using the `-parallelism` flag on the
[plan](/cli/commands/plan), [apply](/cli/commands/apply), and
[destroy](/cli/commands/destroy) commands.
Setting `-parallelism` is considered an advanced operation and should not be
necessary for normal usage of Terraform. It may be helpful in certain special
use cases or to help debug Terraform issues.
Note that some providers (AWS, for example), handle API rate limiting issues at
a lower level by implementing graceful backoff/retry in their respective API
clients. For this reason, Terraform does not use this `parallelism` feature to
address API rate limits directly.

8
website/docs/internals/index.html.md → website/docs/internals/index.mdx
View File

@ -1,8 +1,8 @@
--- ---
layout: "docs" page_title: Internals
page_title: "Internals" description: >-
sidebar_current: "docs-internals" Learn the technical details of how Terraform generates and executes
description: "Learn the technical details of how Terraform generates and executes infrastructure plans, works with plugins, obtains credentials, etc." infrastructure plans, works with plugins, obtains credentials, etc.
--- ---
# Terraform Internals # Terraform Internals

19
website/docs/internals/json-format.html.md → website/docs/internals/json-format.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Internals: JSON Output Format'
page_title: "Internals: JSON Output Format" description: >-
sidebar_current: "docs-internals-json" Terraform provides a machine-readable JSON representation of state,
description: |- configuration and plan.
Terraform provides a machine-readable JSON representation of state, configuration and plan.
--- ---
# JSON Output Format # JSON Output Format
@ -14,7 +13,7 @@ When Terraform plans to make changes, it prints a human-readable summary to the
Since the format of plan files isn't suited for use with external tools (and likely never will be), Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. Since the format of plan files isn't suited for use with external tools (and likely never will be), Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility.
Use `terraform show -json <FILE>` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/docs/cli/commands/show.html) for more details. Use `terraform show -json <FILE>` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/cli/commands/show) for more details.
The output includes a `format_version` key, which as of Terraform 1.1.0 has The output includes a `format_version` key, which as of Terraform 1.1.0 has
value `"1.0"`. The semantics of this version are: value `"1.0"`. The semantics of this version are:
@ -27,7 +26,7 @@ value `"1.0"`. The semantics of this version are:
version. version.
We will introduce new major versions only within the bounds of We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). [the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises).
## Format Summary ## Format Summary
@ -43,8 +42,8 @@ The JSON output format consists of the following objects and sub-objects:
- [Plan Representation](#plan-representation) — The complete top-level object returned by `terraform show -json <PLAN FILE>`. - [Plan Representation](#plan-representation) — The complete top-level object returned by `terraform show -json <PLAN FILE>`.
- [Values Representation](#values-representation) — A sub-object of both plan and state output that describes current state or planned state. - [Values Representation](#values-representation) — A sub-object of both plan and state output that describes current state or planned state.
- [Configuration Representation](#configuration-representation) — A sub-object of plan output that describes a parsed Terraform configuration. - [Configuration Representation](#configuration-representation) — A sub-object of plan output that describes a parsed Terraform configuration.
- [Expression Representation](#expression-representation) — A sub-object of a configuration representation that describes an unevaluated expression. - [Expression Representation](#expression-representation) — A sub-object of a configuration representation that describes an unevaluated expression.
- [Block Expressions Representation](#block-expressions-representation) — A sub-object of a configuration representation that describes the expressions nested inside a block. - [Block Expressions Representation](#block-expressions-representation) — A sub-object of a configuration representation that describes the expressions nested inside a block.
- [Change Representation](#change-representation) — A sub-object of plan output that describes planned changes to an object. - [Change Representation](#change-representation) — A sub-object of plan output that describes planned changes to an object.
## State Representation ## State Representation
@ -306,7 +305,7 @@ The following example illustrates the structure of a `<values-representation>`:
} }
``` ```
The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by Terraform's [`jsonencode`](/docs/language/functions/jsonencode.html) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null. The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by Terraform's [`jsonencode`](/language/functions/jsonencode) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null.
Only the "current" object for each resource instance is described. "Deposed" objects are not reflected in this structure at all; in plan representations, you can refer to the change representations for further details. Only the "current" object for each resource instance is described. "Deposed" objects are not reflected in this structure at all; in plan representations, you can refer to the change representations for further details.

58
website/docs/internals/lifecycle.html.md
View File

@ -1,58 +0,0 @@
---
layout: "docs"
page_title: "Resource Lifecycle"
sidebar_current: "docs-internals-lifecycle"
description: |-
Resources have a strict lifecycle, and can be thought of as basic state machines. Understanding this lifecycle can help better understand how Terraform generates an execution plan, how it safely executes that plan, and what the resource provider is doing throughout all of this.
---
# Resource Lifecycle
Resources have a strict lifecycle, and can be thought of as basic
state machines. Understanding this lifecycle can help better understand
how Terraform generates an execution plan, how it safely executes that
plan, and what the resource provider is doing throughout all of this.
~> **Advanced Topic!** This page covers technical details
of Terraform. You don't need to understand these details to
effectively use Terraform. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code.
## Lifecycle
A resource roughly follows the steps below:
1. `ValidateResource` is called to do a high-level structural
validation of a resource's configuration. The configuration
at this point is raw and the interpolations have not been processed.
The value of any key is not guaranteed and is just meant to be
a quick structural check.
1. `Diff` is called with the current state and the configuration.
The resource provider inspects this and returns a diff, outlining
all the changes that need to occur to the resource. The diff includes
details such as whether or not the resource is being destroyed, what
attribute necessitates the destroy, old values and new values, whether
a value is computed, etc. It is up to the resource provider to
have this knowledge.
1. `Apply` is called with the current state and the diff. Apply does
not have access to the configuration. This is a safety mechanism
that limits the possibility that a provider changes a diff on the
fly. `Apply` must apply a diff as prescribed and do nothing else
to remain true to the Terraform execution plan. Apply returns the
new state of the resource (or nil if the resource was destroyed).
1. If a resource was just created and did not exist before, and the
apply succeeded without error, then the provisioners are executed
in sequence. If any provisioner errors, the resource is marked as
_tainted_, so that it will be destroyed on the next apply.
## Partial State and Error Handling
If an error happens at any stage in the lifecycle of a resource,
Terraform stores a partial state of the resource. This behavior is
critical for Terraform to ensure that you don't end up with any
_zombie_ resources: resources that were created by Terraform but
no longer managed by Terraform due to a loss of state.

59
website/docs/internals/lifecycle.mdx Normal file
View File

@ -0,0 +1,59 @@
---
page_title: Resource Lifecycle
description: >-
Resources have a strict lifecycle, and can be thought of as basic state
machines. Understanding this lifecycle can help better understand how
Terraform generates an execution plan, how it safely executes that plan, and
what the resource provider is doing throughout all of this.
---
# Resource Lifecycle
Resources have a strict lifecycle, and can be thought of as basic
state machines. Understanding this lifecycle can help better understand
how Terraform generates an execution plan, how it safely executes that
plan, and what the resource provider is doing throughout all of this.
~> **Advanced Topic!** This page covers technical details
of Terraform. You don't need to understand these details to
effectively use Terraform. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code.
## Lifecycle
A resource roughly follows the steps below:
1. `ValidateResource` is called to do a high-level structural
validation of a resource's configuration. The configuration
at this point is raw and the interpolations have not been processed.
The value of any key is not guaranteed and is just meant to be
a quick structural check.
1. `Diff` is called with the current state and the configuration.
The resource provider inspects this and returns a diff, outlining
all the changes that need to occur to the resource. The diff includes
details such as whether or not the resource is being destroyed, what
attribute necessitates the destroy, old values and new values, whether
a value is computed, etc. It is up to the resource provider to
have this knowledge.
1. `Apply` is called with the current state and the diff. Apply does
not have access to the configuration. This is a safety mechanism
that limits the possibility that a provider changes a diff on the
fly. `Apply` must apply a diff as prescribed and do nothing else
to remain true to the Terraform execution plan. Apply returns the
new state of the resource (or nil if the resource was destroyed).
1. If a resource was just created and did not exist before, and the
apply succeeded without error, then the provisioners are executed
in sequence. If any provisioner errors, the resource is marked as
_tainted_, so that it will be destroyed on the next apply.
## Partial State and Error Handling
If an error happens at any stage in the lifecycle of a resource,
Terraform stores a partial state of the resource. This behavior is
critical for Terraform to ensure that you don't end up with any
_zombie_ resources: resources that were created by Terraform but
no longer managed by Terraform due to a loss of state.

17
website/docs/internals/login-protocol.html.markdown → website/docs/internals/login-protocol.mdx
View File

@ -1,26 +1,25 @@
--- ---
layout: "docs" page_title: Login Protocol
page_title: "Login Protocol" description: >-
sidebar_current: "docs-internals-login-protocol" The login protocol is used for authenticating Terraform against servers
description: |- providing Terraform-native services.
The login protocol is used for authenticating Terraform against servers providing Terraform-native services.
--- ---
# Server-side Login Protocol # Server-side Login Protocol
~> **Note:** You don't need to read these docs to _use_ ~> **Note:** You don't need to read these docs to _use_
[`terraform login`](/docs/cli/commands/login.html). The information below is for [`terraform login`](/cli/commands/login). The information below is for
anyone intending to implement the server side of `terraform login` in order to anyone intending to implement the server side of `terraform login` in order to
offer Terraform-native services in a third-party system. offer Terraform-native services in a third-party system.
The `terraform login` command supports performing an OAuth 2.0 authorization The `terraform login` command supports performing an OAuth 2.0 authorization
request using configuration provided by the target host. You may wish to request using configuration provided by the target host. You may wish to
implement this protocol if you are producing a third-party implementation of implement this protocol if you are producing a third-party implementation of
any [Terraform-native services](/docs/internals/remote-service-discovery.html), any [Terraform-native services](/internals/remote-service-discovery),
such as a Terraform module registry. such as a Terraform module registry.
First, Terraform uses First, Terraform uses
[remote service discovery](/docs/internals/remote-service-discovery.html) to [remote service discovery](/internals/remote-service-discovery) to
find the OAuth configuration for the host. The host must support the service find the OAuth configuration for the host. The host must support the service
name `login.v1` and define for it an object containing OAuth client name `login.v1` and define for it an object containing OAuth client
configuration values, like this: configuration values, like this:
@ -108,7 +107,7 @@ authorization errors once the token expires, after which the user can run
-> **Note:** As a special case, Terraform can use a -> **Note:** As a special case, Terraform can use a
[Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) [Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3)
only when interacting with `app.terraform.io` ([Terraform Cloud](/docs/cloud/index.html)), only when interacting with `app.terraform.io` ([Terraform Cloud](/cloud)),
under the recommendation in the OAuth specification to use this grant type only under the recommendation in the OAuth specification to use this grant type only
when the client and server are closely related. The `password` grant type is when the client and server are closely related. The `password` grant type is
not supported for any other hostname and will be ignored. not supported for any other hostname and will be ignored.

33
website/docs/internals/machine-readable-ui.html.md → website/docs/internals/machine-readable-ui.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: 'Internals: Machine-Readable UI'
page_title: "Internals: Machine-Readable UI" description: >-
sidebar_current: "docs-internals-machine-readable-ui" Terraform provides a machine-readable streaming JSON UI output for plan,
description: |- apply, and refresh operations.
Terraform provides a machine-readable streaming JSON UI output for plan, apply, and refresh operations.
--- ---
# Machine-Readable UI # Machine-Readable UI
@ -25,7 +24,7 @@ value `"1.0"`. The semantics of this version are:
version. version.
We will introduce new major versions only within the bounds of We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). [the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises).
## Sample JSON Output ## Sample JSON Output
@ -61,7 +60,7 @@ The following message types are supported:
- `version`: information about the Terraform version and the version of the schema used for the following messages - `version`: information about the Terraform version and the version of the schema used for the following messages
- `log`: unstructured human-readable log lines - `log`: unstructured human-readable log lines
- `diagnostic`: diagnostic warning or error messages; [see the `terraform validate` docs for more details on the format](/docs/cli/commands/validate.html#json) - `diagnostic`: diagnostic warning or error messages; [see the `terraform validate` docs for more details on the format](/cli/commands/validate#json)
### Operation Results ### Operation Results
@ -104,7 +103,7 @@ If drift is detected during planning, Terraform will emit a `resource_drift` mes
- `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details - `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details
- `action`: the action planned to be taken for the resource. Values: `update`, `delete`. - `action`: the action planned to be taken for the resource. Values: `update`, `delete`.
This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](./json-format.html). This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](/internals/json-format).
### Example ### Example
@ -138,16 +137,16 @@ At the end of a plan or before an apply, Terraform will emit a `planned_change`
- `previous_resource`: object describing the previous address of the resource, if this change includes a configuration-driven move - `previous_resource`: object describing the previous address of the resource, if this change includes a configuration-driven move
- `action`: the action planned to be taken for the resource. Values: `noop`, `create`, `read`, `update`, `replace`, `delete`, `move`. - `action`: the action planned to be taken for the resource. Values: `noop`, `create`, `read`, `update`, `replace`, `delete`, `move`.
- `reason`: an optional reason for the change, currently only used when the action is `replace` or `delete`. Values: - `reason`: an optional reason for the change, currently only used when the action is `replace` or `delete`. Values:
- `tainted`: resource was marked as tainted - `tainted`: resource was marked as tainted
- `requested`: user requested that the resource be replaced, for example via the `-replace` plan flag - `requested`: user requested that the resource be replaced, for example via the `-replace` plan flag
- `cannot_update`: changes to configuration force the resource to be deleted and created rather than updated - `cannot_update`: changes to configuration force the resource to be deleted and created rather than updated
- `delete_because_no_resource_config`: no matching resource in configuration - `delete_because_no_resource_config`: no matching resource in configuration
- `delete_because_wrong_repetition`: resource instance key has no corresponding `count` or `for_each` in configuration - `delete_because_wrong_repetition`: resource instance key has no corresponding `count` or `for_each` in configuration
- `delete_because_count_index`: resource instance key is outside the range of the `count` argument - `delete_because_count_index`: resource instance key is outside the range of the `count` argument
- `delete_because_each_key`: resource instance key is not included in the `for_each` argument - `delete_because_each_key`: resource instance key is not included in the `for_each` argument
- `delete_because_no_module`: enclosing module instance is not in configuration - `delete_because_no_module`: enclosing module instance is not in configuration
This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](./json-format.html). This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](/internals/json-format).
### Example ### Example

36
website/docs/internals/module-registry-protocol.html.md → website/docs/internals/module-registry-protocol.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: Module Registry Protocol
page_title: "Module Registry Protocol"
sidebar_current: "docs-internals-module-registry-protocol"
description: |- description: |-
The module registry protocol is implemented by a host intending to be the The module registry protocol is implemented by a host intending to be the
host of one or more Terraform modules, specifying which modules are available host of one or more Terraform modules, specifying which modules are available
@ -25,7 +23,7 @@ publishing them on the public Terraform Registry.
The public Terraform Registry implements a superset of the API described on The public Terraform Registry implements a superset of the API described on
this page, in order to capture additional information used in the registry UI. this page, in order to capture additional information used in the registry UI.
For information on those extensions, see For information on those extensions, see
[Terraform Registry HTTP API](/docs/registry/api.html). Third-party registry [Terraform Registry HTTP API](/registry/api-docs). Third-party registry
implementations may choose to implement those extensions if desired, but implementations may choose to implement those extensions if desired, but
Terraform CLI itself does not use them. Terraform CLI itself does not use them.
@ -34,14 +32,14 @@ Terraform CLI itself does not use them.
Each Terraform module has an associated address. A module address has the Each Terraform module has an associated address. A module address has the
syntax `hostname/namespace/name/system`, where: syntax `hostname/namespace/name/system`, where:
* `hostname` is the hostname of the module registry that serves this module. - `hostname` is the hostname of the module registry that serves this module.
* `namespace` is the name of a namespace, unique on a particular hostname, that - `namespace` is the name of a namespace, unique on a particular hostname, that
can contain one or more modules that are somehow related. On the public can contain one or more modules that are somehow related. On the public
Terraform Registry the "namespace" represents the organization that is Terraform Registry the "namespace" represents the organization that is
packaging and distributing the module. packaging and distributing the module.
* `name` is the module name, which generally names the abstraction that the - `name` is the module name, which generally names the abstraction that the
module is intending to create. module is intending to create.
* `system` is the name of a remote system that the module is primarily written - `system` is the name of a remote system that the module is primarily written
to target. For multi-cloud abstractions, there can be multiple modules with to target. For multi-cloud abstractions, there can be multiple modules with
addresses that differ only in "system" to reflect provider-specific addresses that differ only in "system" to reflect provider-specific
implementations of the abstraction, like implementations of the abstraction, like
@ -57,10 +55,10 @@ is optional, and if omitted defaults to `registry.terraform.io/`.
For example: For example:
* `hashicorp/consul/aws` is a shorthand for - `hashicorp/consul/aws` is a shorthand for
`registry.terraform.io/hashicorp/consul/aws`, which is a module on the `registry.terraform.io/hashicorp/consul/aws`, which is a module on the
public registry for deploying Consul clusters in Amazon Web Services. public registry for deploying Consul clusters in Amazon Web Services.
* `example.com/awesomecorp/consul/happycloud` is a hypothetical module published - `example.com/awesomecorp/consul/happycloud` is a hypothetical module published
on a third-party registry. on a third-party registry.
If you intend to share a module you've developed for use by all Terraform If you intend to share a module you've developed for use by all Terraform
@ -83,7 +81,7 @@ blocks have the same source address.
## Service Discovery ## Service Discovery
The module registry protocol begins with Terraform CLI using The module registry protocol begins with Terraform CLI using
[Terraform's remote service discovery protocol](./remote-service-discovery.html), [Terraform's remote service discovery protocol](/internals/remote-service-discovery),
with the hostname in the module address acting as the "User-facing Hostname". with the hostname in the module address acting as the "User-facing Hostname".
The service identifier for the module registry protocol is `modules.v1`. The service identifier for the module registry protocol is `modules.v1`.
@ -123,9 +121,9 @@ the string "versions".
This is the primary endpoint for resolving module sources, returning the This is the primary endpoint for resolving module sources, returning the
available versions for a given fully-qualified module. available versions for a given fully-qualified module.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ------------------------------------- | -------------------------- | | ------ | ------------------------------------- | ------------------ |
| `GET` | `:namespace/:name/:provider/versions` | `application/json` | | `GET` | `:namespace/:name/:provider/versions` | `application/json` |
### Parameters ### Parameters
@ -177,9 +175,9 @@ requested namespace, name, and provider
This endpoint downloads the specified version of a module for a single provider. This endpoint downloads the specified version of a module for a single provider.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ------------------------------------------------------ | -------------------------- | | ------ | -------------------------------------------- | ------------------ |
| `GET` | `:namespace/:name/:system/:version/download` | `application/json` | | `GET` | `:namespace/:name/:system/:version/download` | `application/json` |
### Parameters ### Parameters
@ -213,10 +211,10 @@ A successful response has no body, and includes the location from which the
module version's source can be downloaded in the `X-Terraform-Get` header. module version's source can be downloaded in the `X-Terraform-Get` header.
The value of this header accepts the same values as the `source` argument The value of this header accepts the same values as the `source` argument
in a `module` block in Terraform configuration, as described in in a `module` block in Terraform configuration, as described in
[Module Sources](https://www.terraform.io/docs/language/modules/sources.html), [Module Sources](/language/modules/sources),
except that it may not recursively refer to another module registry address. except that it may not recursively refer to another module registry address.
The value of `X-Terraform-Get` may instead be a relative URL, indicated by The value of `X-Terraform-Get` may instead be a relative URL, indicated by
beginning with `/`, `./` or `../`, in which case it is resolved relative to beginning with `/`, `./` or `../`, in which case it is resolved relative to
the full URL of the download endpoint to produce the full URL of the download endpoint to produce
[an HTTP URL module source](/docs/language/modules/sources.html#http-urls). [an HTTP URL module source](/language/modules/sources#http-urls).

9
website/docs/internals/provider-meta.html.md → website/docs/internals/provider-meta.mdx
View File

@ -1,9 +1,8 @@
--- ---
layout: "docs" page_title: Provider Metadata
page_title: "Provider Metadata" description: >-
sidebar_current: "docs-internals-provider-meta" For advanced use cases, modules can provide some pre-defined metadata for
description: |- providers.
For advanced use cases, modules can provide some pre-defined metadata for providers.
--- ---
# Provider Metadata # Provider Metadata

42
website/docs/internals/provider-network-mirror-protocol.html.md → website/docs/internals/provider-network-mirror-protocol.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: Provider Network Mirror Protocol
page_title: "Provider Network Mirror Protocol"
sidebar_current: "docs-internals-provider-network-mirror-protocol"
description: |- description: |-
The provider network mirror protocol is implemented by a server intending The provider network mirror protocol is implemented by a server intending
to provide a mirror or read-through caching proxy for Terraform providers, to provide a mirror or read-through caching proxy for Terraform providers,
@ -18,7 +16,7 @@ implement to provide an alternative installation source for Terraform providers,
regardless of their origin registries. regardless of their origin registries.
Terraform uses network mirrors only if you activate them explicitly in Terraform uses network mirrors only if you activate them explicitly in
[the CLI configuration's `provider_installation` block](/docs/cli/config/config-file.html#provider-installation). [the CLI configuration's `provider_installation` block](/cli/config/config-file#provider-installation).
When enabled, a network mirror can serve providers belonging to any registry When enabled, a network mirror can serve providers belonging to any registry
hostname, which can allow an organization to serve all of the Terraform hostname, which can allow an organization to serve all of the Terraform
providers they intend to use from an internal server, rather than from each providers they intend to use from an internal server, rather than from each
@ -28,7 +26,7 @@ This is _not_ the protocol that should be implemented by a host intending to
serve as an origin registry for Terraform Providers. To provide an origin serve as an origin registry for Terraform Providers. To provide an origin
registry (whose hostname would then be included in the source addresses of the registry (whose hostname would then be included in the source addresses of the
providers it hosts), implement providers it hosts), implement
[the provider registry protocol](./provider-registry-protocol.html) [the provider registry protocol](/internals/provider-registry-protocol)
instead. instead.
## Provider Addresses ## Provider Addresses
@ -36,7 +34,7 @@ instead.
Each Terraform provider has an associated address which uniquely identifies it Each Terraform provider has an associated address which uniquely identifies it
within Terraform. A provider address has the syntax `hostname/namespace/type`, within Terraform. A provider address has the syntax `hostname/namespace/type`,
which is described in more detail in which is described in more detail in
[the Provider Requirements documentation](/docs/language/providers/requirements.html). [the Provider Requirements documentation](/language/providers/requirements).
By default, the `hostname` portion of a provider address serves both as part By default, the `hostname` portion of a provider address serves both as part
of its unique identifier _and_ as the location of the registry to retrieve it of its unique identifier _and_ as the location of the registry to retrieve it
@ -54,7 +52,7 @@ the hostname where the provider network mirror is deployed.
## Protocol Base URL ## Protocol Base URL
Most Terraform-native services use Most Terraform-native services use
[the remote service discovery protocol](./remote-service-discovery.html) so [the remote service discovery protocol](/internals/remote-service-discovery) so
that the physical location of the endpoints can potentially be separated from that the physical location of the endpoints can potentially be separated from
the hostname used in identifiers. The Provider Network Mirror protocol does the hostname used in identifiers. The Provider Network Mirror protocol does
_not_ use the service discovery indirection, because a network mirror location _not_ use the service discovery indirection, because a network mirror location
@ -96,7 +94,7 @@ base URL from the above CLI configuration example.
### Authentication ### Authentication
If the CLI configuration includes If the CLI configuration includes
[credentials](/docs/cli/config/config-file.html#credentials) for the hostname [credentials](/cli/config/config-file#credentials) for the hostname
given in the network mirror base URL, Terraform will include those credentials given in the network mirror base URL, Terraform will include those credentials
in its requests for operations described below. in its requests for operations described below.
@ -117,7 +115,7 @@ This operation determines which versions are currently available for a
particular provider. particular provider.
| Method | Path | Produces | | Method | Path | Produces |
|--------|-----------------------------------------|--------------------| | ------ | --------------------------------------- | ------------------ |
| `GET` | `:hostname/:namespace/:type/index.json` | `application/json` | | `GET` | `:hostname/:namespace/:type/index.json` | `application/json` |
### Parameters ### Parameters
@ -175,7 +173,7 @@ version matching the configured version constraints, in order to find a zip
archive containing the plugin itself. archive containing the plugin itself.
| Method | Path | Produces | | Method | Path | Produces |
|--------|--------------------------------------------|--------------------| | ------ | ------------------------------------------ | ------------------ |
| `GET` | `:hostname/:namespace/:type/:version.json` | `application/json` | | `GET` | `:hostname/:namespace/:type/:version.json` | `application/json` |
### Parameters ### Parameters
@ -231,13 +229,13 @@ the following properties:
* `url` (required): a string specifying the URL from which Terraform should * `url` (required): a string specifying the URL from which Terraform should
download the `.zip` archive containing the requested provider plugin version. download the `.zip` archive containing the requested provider plugin version.
Terraform resolves the URL relative to the URL from which the current Terraform resolves the URL relative to the URL from which the current
JSON document was returned, so the examples above containing only a JSON document was returned, so the examples above containing only a
filename would cause Terraform to construct a URL like: filename would cause Terraform to construct a URL like:
``` ```
https://terraform.example.com/providers/registry.terraform.io/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip https://terraform.example.com/providers/registry.terraform.io/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip
``` ```
* `hashes` (optional): a JSON array of strings containing one or more hash * `hashes` (optional): a JSON array of strings containing one or more hash
values for the indicated archive. These hashes use Terraform's provider values for the indicated archive. These hashes use Terraform's provider
@ -246,11 +244,11 @@ the following properties:
command, as described in a later section, which will include the calculated command, as described in a later section, which will include the calculated
hashes of each provider. hashes of each provider.
If the response includes at least one hash, Terraform will select the hash If the response includes at least one hash, Terraform will select the hash
whose algorithm it considers to be strongest and verify that the downloaded whose algorithm it considers to be strongest and verify that the downloaded
package matches that hash. If the response does not include a `hashes` package matches that hash. If the response does not include a `hashes`
property then Terraform will install the indicated archive with no property then Terraform will install the indicated archive with no
verification. verification.
Terraform CLI will only attempt to download versions that it has previously Terraform CLI will only attempt to download versions that it has previously
seen in response to [List Available Versions](#list-available-versions). seen in response to [List Available Versions](#list-available-versions).
@ -264,7 +262,7 @@ in the appropriate nested subdirectories, and ensure that your system is
configured to serve `.json` files with the `application/json` media type. configured to serve `.json` files with the `application/json` media type.
As a convenience, Terraform CLI includes As a convenience, Terraform CLI includes
[the `terraform providers mirror` subcommand](https://www.terraform.io/docs/cli/commands/providers/mirror.html), [the `terraform providers mirror` subcommand](/cli/commands/providers/mirror),
which will analyze the current configuration for the providers it requires, which will analyze the current configuration for the providers it requires,
download the packages for those providers from their origin registries, and download the packages for those providers from their origin registries, and
place them into a local directory suitable for use as a mirror. place them into a local directory suitable for use as a mirror.

76
website/docs/internals/provider-registry-protocol.html.md → website/docs/internals/provider-registry-protocol.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: Provider Registry Protocol
page_title: "Provider Registry Protocol"
sidebar_current: "docs-internals-provider-registry-protocol"
description: |- description: |-
The provider registry protocol is implemented by a host intending to be the The provider registry protocol is implemented by a host intending to be the
origin host for one or more Terraform providers, specifying which providers origin host for one or more Terraform providers, specifying which providers
@ -42,7 +40,7 @@ where:
* `hostname` is the registry host that the provider is considered to have * `hostname` is the registry host that the provider is considered to have
originated from, and the default location Terraform will consult for originated from, and the default location Terraform will consult for
information about the provider information about the provider
[unless overridden in the CLI configuration](/docs/cli/config/config-file.html#provider-installation). [unless overridden in the CLI configuration](/cli/config/config-file#provider-installation).
* `namespace` is the name of a namespace, unique on a particular hostname, that * `namespace` is the name of a namespace, unique on a particular hostname, that
can contain one or more providers that are somehow related. On the public can contain one or more providers that are somehow related. On the public
Terraform Registry the "namespace" represents the organization that is Terraform Registry the "namespace" represents the organization that is
@ -78,7 +76,7 @@ to see it as an entirely separate provider that will _not_ be usable by modules
that declare a dependency on `hashicorp/azurerm`. If your goal is to create that declare a dependency on `hashicorp/azurerm`. If your goal is to create
an alternative local distribution source for an existing provider -- that is, an alternative local distribution source for an existing provider -- that is,
a _mirror_ of the provider -- refer to a _mirror_ of the provider -- refer to
[the provider installation method configuration](/docs/cli/config/config-file.html#provider-installation) [the provider installation method configuration](/cli/config/config-file#provider-installation)
instead. instead.
## Provider Versions ## Provider Versions
@ -98,7 +96,7 @@ version selection.
## Service Discovery ## Service Discovery
The providers protocol begins with Terraform CLI using The providers protocol begins with Terraform CLI using
[Terraform's remote service discovery protocol](./remote-service-discovery.html), [Terraform's remote service discovery protocol](/internals/remote-service-discovery),
with the hostname in the provider address acting as the "User-facing Hostname". with the hostname in the provider address acting as the "User-facing Hostname".
The service identifier for the provider registry protocol is `providers.v1`. The service identifier for the provider registry protocol is `providers.v1`.
@ -139,7 +137,7 @@ This operation determines which versions are currently available for a
particular provider. particular provider.
| Method | Path | Produces | | Method | Path | Produces |
|--------|-----------------------------|--------------------| | ------ | --------------------------- | ------------------ |
| `GET` | `:namespace/:type/versions` | `application/json` | | `GET` | `:namespace/:type/versions` | `application/json` |
### Parameters ### Parameters
@ -198,29 +196,29 @@ with the following properties:
version supported. For example, `5.1` means that the provider supports both version supported. For example, `5.1` means that the provider supports both
protocol `5.0` and protocol `5.1`. protocol `5.0` and protocol `5.1`.
Terraform uses this information, when available, to provide hints to users Terraform uses this information, when available, to provide hints to users
about upgrading or downgrading their version of a particular provider to about upgrading or downgrading their version of a particular provider to
work with their current version of Terraform, if their currently-selected work with their current version of Terraform, if their currently-selected
versions are not compatible. versions are not compatible.
Which API versions are supported is, for most providers, decided by which Which API versions are supported is, for most providers, decided by which
version of the Terraform SDK they are built against. Consult the Terraform version of the Terraform SDK they are built against. Consult the Terraform
SDK documentation for more information. SDK documentation for more information.
Only Terraform 0.13 and later support third-party provider registries and Only Terraform 0.13 and later support third-party provider registries and
that Terraform version requires API version `5.0` or later, so in practice that Terraform version requires API version `5.0` or later, so in practice
it isn't useful to list major versions 4 or earlier in a third-party it isn't useful to list major versions 4 or earlier in a third-party
provider registry. provider registry.
* `platforms` (recommended): an array of objects describing platforms that have * `platforms` (recommended): an array of objects describing platforms that have
packages available for this version. packages available for this version.
Terraform may use this information, when available, to provide hints to Terraform may use this information, when available, to provide hints to
users about upgrading or downgrading their version of a particular provider users about upgrading or downgrading their version of a particular provider
for compatibility with their current platform. for compatibility with their current platform.
The `platforms` objects have properties `os` and `arch`, whose values match The `platforms` objects have properties `os` and `arch`, whose values match
the properties of the same name in the response to the properties of the same name in the response to
[Find a Provider Package](#find-a-provider-package). [Find a Provider Package](#find-a-provider-package).
Return `404 Not Found` to signal that the registry does not have a provider Return `404 Not Found` to signal that the registry does not have a provider
with the given namespace and type. with the given namespace and type.
@ -236,7 +234,7 @@ version matching the configured version constraints, in order to find the zip
archive containing the plugin itself. archive containing the plugin itself.
| Method | Path | Produces | | Method | Path | Produces |
|--------|------------------------------------------------|--------------------| | ------ | ---------------------------------------------- | ------------------ |
| `GET` | `:namespace/:type/:version/download/:os/:arch` | `application/json` | | `GET` | `:namespace/:type/:version/download/:os/:arch` | `application/json` |
### Parameters ### Parameters
@ -292,9 +290,9 @@ A successful result is a JSON object with the following properties:
the provider supports, in the same format as for the provider supports, in the same format as for
[List Available Versions](#list-available-versions). [List Available Versions](#list-available-versions).
While this property is optional when listing available options, it is While this property is optional when listing available options, it is
_required_ for describing an individual provider package so that Terraform _required_ for describing an individual provider package so that Terraform
CLI can avoid downloading a package that will not be compatible with it. CLI can avoid downloading a package that will not be compatible with it.
* `os` (required): this must currently echo back the `os` parameter from the * `os` (required): this must currently echo back the `os` parameter from the
request. Other possibilities may come in later versions of this protocol. request. Other possibilities may come in later versions of this protocol.
@ -314,9 +312,9 @@ A successful result is a JSON object with the following properties:
document recording expected SHA256 checksums for this package and possibly document recording expected SHA256 checksums for this package and possibly
other packages for the same provider version on other platforms. other packages for the same provider version on other platforms.
The indicated document must be in the format generated by the `sha256` The indicated document must be in the format generated by the `sha256`
command available on many Unix systems, with one entry recording the command available on many Unix systems, with one entry recording the
same filename given in the `filename` property (case sensitive). same filename given in the `filename` property (case sensitive).
* `shasums_signature_url` (required): a URL from which Terraform can retrieve * `shasums_signature_url` (required): a URL from which Terraform can retrieve
a binary, detached GPG signature for the document at `shasums_url`, signed a binary, detached GPG signature for the document at `shasums_url`, signed
@ -326,16 +324,16 @@ A successful result is a JSON object with the following properties:
provider package, one of which must have been used to produce the signature provider package, one of which must have been used to produce the signature
at `shasums_signature_url`. The object has the following nested properties: at `shasums_signature_url`. The object has the following nested properties:
* `gpg_public_keys` (required): an array of objects, each describing one * `gpg_public_keys` (required): an array of objects, each describing one
GPG signing key that is allowed to sign the checksums for this provider GPG signing key that is allowed to sign the checksums for this provider
version. At least one element must be included, representing the key that version. At least one element must be included, representing the key that
produced the signature at `shasums_signature_url`. These objects have produced the signature at `shasums_signature_url`. These objects have
the following nested properties: the following nested properties:
* `key_id` (required): uppercase-hexadecimal-formatted ID for this GPG key * `key_id` (required): uppercase-hexadecimal-formatted ID for this GPG key
* `ascii_armor` (required): an "ascii-armor" encoding of the **public key** * `ascii_armor` (required): an "ascii-armor" encoding of the **public key**
associated with this GPG key. associated with this GPG key.
Return `404 Not Found` to signal that the given provider version isn't Return `404 Not Found` to signal that the given provider version isn't
available for the requested operating system and/or architecture. Terraform available for the requested operating system and/or architecture. Terraform

12
website/docs/internals/remote-service-discovery.html.md → website/docs/internals/remote-service-discovery.mdx
View File

@ -1,7 +1,5 @@
--- ---
layout: "docs" page_title: 'Internals: Remote Service Discovery'
page_title: "Internals: Remote Service Discovery"
sidebar_current: "docs-internals-remote-service-discovery"
description: |- description: |-
Remote service discovery is a protocol used to locate Terraform-native Remote service discovery is a protocol used to locate Terraform-native
services provided at a user-friendly hostname. services provided at a user-friendly hostname.
@ -85,14 +83,14 @@ version 1 of the module registry protocol:
At present, the following service identifiers are in use: At present, the following service identifiers are in use:
* `login.v1`: [login protocol version 1](/docs/cli/commands/login.html) * `login.v1`: [login protocol version 1](/cli/commands/login)
* `modules.v1`: [module registry API version 1](module-registry-protocol.html) * `modules.v1`: [module registry API version 1](/internals/module-registry-protocol)
* `providers.v1`: [provider registry API version 1](provider-registry-protocol.html) * `providers.v1`: [provider registry API version 1](/internals/provider-registry-protocol)
## Authentication ## Authentication
If credentials for the given hostname are available in If credentials for the given hostname are available in
[the CLI config](/docs/cli/config/config-file.html) then they will be included [the CLI config](/cli/config/config-file) then they will be included
in the request for the discovery document. in the request for the discovery document.
The credentials may also be provided to endpoints declared in the discovery The credentials may also be provided to endpoints declared in the discovery

24
website/docs/language/attr-as-blocks.html.md → website/docs/language/attr-as-blocks.mdx
View File

@ -1,9 +1,9 @@
--- ---
layout: "language" page_title: Attributes as Blocks - Configuration Language
page_title: "Attributes as Blocks - Configuration Language" description: >-
sidebar_current: "docs-config-attr-as-blocks" For historical reasons, certain arguments within resource blocks can use
description: |- either
For historical reasons, certain arguments within resource blocks can use either
block or attribute syntax. block or attribute syntax.
--- ---
@ -25,28 +25,28 @@ is set to an empty list (`<ATTR> = []`).
Most users do not need to know any further details of this "nested block or Most users do not need to know any further details of this "nested block or
empty list" behavior. However, read further if you need to: empty list" behavior. However, read further if you need to:
- Use Terraform's [JSON syntax](/docs/language/syntax/json.html) with this - Use Terraform's [JSON syntax](/language/syntax/json) with this
type of resource. type of resource.
- Create a reusable module that wraps this type of resource. - Create a reusable module that wraps this type of resource.
## Details ## Details
In Terraform v0.12 and later, the language makes a distinction between In Terraform v0.12 and later, the language makes a distinction between
[argument syntax and nested block syntax](/docs/language/syntax/configuration.html#arguments-and-blocks) [argument syntax and nested block syntax](/language/syntax/configuration#arguments-and-blocks)
within blocks: within blocks:
* Argument syntax sets a named argument for the containing object. If the - Argument syntax sets a named argument for the containing object. If the
attribute has a default value then an explicitly-specified value entirely attribute has a default value then an explicitly-specified value entirely
overrides that default. overrides that default.
* Nested block syntax represents a related child object of the container that - Nested block syntax represents a related child object of the container that
has its own set of arguments. Where multiple such objects are possible, multiple has its own set of arguments. Where multiple such objects are possible, multiple
blocks of the same type can be present. If the nested attributes themselves blocks of the same type can be present. If the nested attributes themselves
have default values, they are honored for each nested block separately, have default values, they are honored for each nested block separately,
merging in with any explicitly-defined arguments. merging in with any explicitly-defined arguments.
The distinction between these is particularly important for The distinction between these is particularly important for
[JSON syntax](/docs/language/syntax/json.html) [JSON syntax](/language/syntax/json)
because the same primitive JSON constructs (lists and objects) will be because the same primitive JSON constructs (lists and objects) will be
interpreted differently depending on whether a particular name is an argument interpreted differently depending on whether a particular name is an argument
or a nested block type. or a nested block type.
@ -153,7 +153,7 @@ example = [
For the arguments that use the attributes-as-blocks usage mode, the above is For the arguments that use the attributes-as-blocks usage mode, the above is
a better pattern than using a better pattern than using
[`dynamic` blocks](/docs/language/expressions/dynamic-blocks.html) [`dynamic` blocks](/language/expressions/dynamic-blocks)
because the case where the because the case where the
caller provides an empty list will result in explicitly assigning an empty caller provides an empty list will result in explicitly assigning an empty
list value, rather than assigning no value at all and thus retaining and list value, rather than assigning no value at all and thus retaining and
@ -163,7 +163,7 @@ dynamically-generating _normal_ nested blocks, though.
## In JSON syntax ## In JSON syntax
Arguments that use this special mode are specified in JSON syntax always using Arguments that use this special mode are specified in JSON syntax always using
the [JSON expression mapping](/docs/language/syntax/json.html#expression-mapping) the [JSON expression mapping](/language/syntax/json#expression-mapping)
to produce a list of objects. to produce a list of objects.
The interpretation of these values in JSON syntax is, therefore, equivalent The interpretation of these values in JSON syntax is, therefore, equivalent

Some files were not shown because too many files have changed in this diff Show More