diff --git a/website/data/cli-nav-data.json b/website/data/cli-nav-data.json
index f7043dab651a..ead2c151431c 100644
--- a/website/data/cli-nav-data.json
+++ b/website/data/cli-nav-data.json
@@ -1,9 +1,21 @@
[
{ "heading": "Terraform CLI" },
{ "title": "Overview", "path": "" },
- { "title": "Basic CLI Features", "href": "/cli/commands" },
+ { "title": "Basic CLI features", "href": "/cli/commands" },
{
- "title": "Initializing Working Directories",
+ "title": "Configure CLI",
+ "routes": [
+ { "title": "Overview", "path": "config" },
+ { "title": "CLI configuration", "path": "config/config-file" },
+ {
+ "title": "Environment variables",
+ "path": "config/environment-variables"
+ }
+ ]
+ },
+ { "heading": "Fundamentals" },
+ {
+ "title": "Initialize working directories",
"routes": [
{ "title": "Overview", "path": "init" },
{ "title": "init", "href": "/cli/commands/init" },
@@ -11,7 +23,7 @@
]
},
{
- "title": "Provisioning Infrastructure",
+ "title": "Provision infrastructure",
"routes": [
{ "title": "Overview", "path": "run" },
{ "title": "plan", "href": "/cli/commands/plan" },
@@ -20,15 +32,7 @@
]
},
{
- "title": "Authenticating",
- "routes": [
- { "title": "Overview", "path": "auth" },
- { "title": "login", "href": "/cli/commands/login" },
- { "title": "logout", "href": "/cli/commands/logout" }
- ]
- },
- {
- "title": "Writing and Modifying Code",
+ "title": "Write and modify configuration",
"routes": [
{ "title": "Overview", "path": "code" },
{ "title": "console", "href": "/cli/commands/console" },
@@ -44,8 +48,34 @@
}
]
},
+
+ { "heading": "HCP Terraform" },
+ {
+ "title": "Use HCP Terraform",
+ "routes": [
+ { "title": "Overview", "path": "cloud" },
+ { "title": "HCP Terraform Settings", "path": "cloud/settings" },
+ {
+ "title": "Initialize and migrate",
+ "path": "cloud/migrating"
+ },
+ {
+ "title": "Command line arguments",
+ "path": "cloud/command-line-arguments"
+ }
+ ]
+ },
+ {
+ "title": "Authenticate to HCP Terraform",
+ "routes": [
+ { "title": "Overview", "path": "auth" },
+ { "title": "login", "href": "/cli/commands/login" },
+ { "title": "logout", "href": "/cli/commands/logout" }
+ ]
+ },
+ { "heading": "Advanced" },
{
- "title": "Inspecting Infrastructure",
+ "title": "Inspect resources",
"routes": [
{ "title": "Overview", "path": "inspect" },
{ "title": "graph", "href": "/cli/commands/graph" },
@@ -62,14 +92,14 @@
]
},
{
- "title": "Importing Infrastructure",
+ "title": "Import resources",
"routes": [
{ "title": "Overview", "path": "import" },
{
"title": "import",
"href": "/cli/commands/import"
},
- { "title": "Usage Tips", "path": "import/usage" },
+ { "title": "Usage tips", "path": "import/usage" },
{
"title": "Resource Importability",
"path": "import/importability"
@@ -77,16 +107,51 @@
]
},
{
- "title": "Manipulating State",
+ "title": "Test configuration",
+ "routes": [
+ { "title": "Overview", "path": "test" },
+ { "title": "test", "href": "/cli/commands/test"}
+ ]
+ },
+
+ {
+ "title": "Manage providers",
+ "routes": [
+ { "title": "Overview", "path": "plugins" },
+ { "title": "Plugin signing", "path": "plugins/signing" },
+ {
+ "title": "providers",
+ "href": "/cli/commands/providers"
+ },
+ {
+ "title": "version",
+ "href": "/cli/commands/version"
+ },
+ {
+ "title": "providers lock",
+ "href": "/cli/commands/providers/lock"
+ },
+ {
+ "title": "providers mirror",
+ "href": "/cli/commands/providers/mirror"
+ },
+ {
+ "title": "providers schema",
+ "href": "/cli/commands/providers/schema"
+ }
+ ]
+ },
+ {
+ "title": "Manipulate state",
"routes": [
{ "title": "Overview", "path": "state" },
{
- "title": "Resource Addressing",
+ "title": "Resource addressing",
"path": "state/resource-addressing"
},
{ "title": "state", "href": "/cli/commands/state" },
{
- "title": "Inspecting State",
+ "title": "Inspect state",
"routes": [
{ "title": "Overview", "path": "state/inspect" },
{
@@ -104,7 +169,7 @@
]
},
{
- "title": "Forcing Re-creation (Tainting)",
+ "title": "Forcing re-creation (tainting)",
"routes": [
{ "title": "Overview", "path": "state/taint" },
{
@@ -118,7 +183,7 @@
]
},
{
- "title": "Moving Resources",
+ "title": "Move resources",
"routes": [
{ "title": "Overview", "path": "state/move" },
{
@@ -136,7 +201,7 @@
]
},
{
- "title": "Disaster Recovery",
+ "title": "Disaster recovery",
"routes": [
{
"title": "Overview",
@@ -159,7 +224,20 @@
]
},
{
- "title": "Managing Workspaces",
+ "title": "Automate Terraform",
+ "routes": [
+ {
+ "title": "Run Terraform in automation",
+ "href": "/terraform/tutorials/automation/automate-terraform"
+ },
+ {
+ "title": "GitHub Actions",
+ "href": "/terraform/tutorials/automation/github-actions"
+ }
+ ]
+ },
+ {
+ "title": "Manage workspaces",
"routes": [
{ "title": "Overview", "path": "workspaces" },
{
@@ -190,81 +268,9 @@
}
]
},
+ { "divider": true },
{
- "title": "Managing Plugins",
- "routes": [
- { "title": "Overview", "path": "plugins" },
- { "title": "Plugin Signing", "path": "plugins/signing" },
- {
- "title": "providers",
- "href": "/cli/commands/providers"
- },
- {
- "title": "version",
- "href": "/cli/commands/version"
- },
- {
- "title": "providers lock",
- "href": "/cli/commands/providers/lock"
- },
- {
- "title": "providers mirror",
- "href": "/cli/commands/providers/mirror"
- },
- {
- "title": "providers schema",
- "href": "/cli/commands/providers/schema"
- }
- ]
- },
- {
- "title": "CLI Configuration",
- "routes": [
- { "title": "Overview", "path": "config" },
- { "title": "CLI Configuration", "path": "config/config-file" },
- {
- "title": "Environment Variables",
- "path": "config/environment-variables"
- }
- ]
- },
- {
- "title": "Using HCP Terraform",
- "routes": [
- { "title": "Overview", "path": "cloud" },
- { "title": "HCP Terraform Settings", "path": "cloud/settings" },
- {
- "title": "Initializing and Migrating",
- "path": "cloud/migrating"
- },
- {
- "title": "Command Line Arguments",
- "path": "cloud/command-line-arguments"
- }
- ]
- },
- {
- "title": "Testing Terraform",
- "routes": [
- { "title": "Overview", "path": "test" },
- { "title": "test", "href": "/cli/commands/test"}
- ]
- },
- {
- "title": "Automating Terraform",
- "routes": [
- {
- "title": "Running Terraform in Automation",
- "href": "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"
- },
- {
- "title": "GitHub Actions",
- "href": "https://learn.hashicorp.com/tutorials/terraform/github-actions?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS"
- }
- ]
- },
- {
- "title": "Alphabetical List of Commands",
+ "title": "Alphabetical list of commands",
"routes": [
{ "title": "Overview", "href": "/cli/commands" },
{ "title": "apply", "href": "/cli/commands/apply" },
diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx
index 7ac27004fc43..dbfae3b90902 100644
--- a/website/docs/cli/auth/index.mdx
+++ b/website/docs/cli/auth/index.mdx
@@ -1,11 +1,11 @@
---
-page_title: Authentication - Terraform CLI
+page_title: Authenticate CLI to HCP Terraform - Terraform CLI
description: >-
Documentation about the login and logout commands that help automate getting
an API token for your HCP Terraform account.
---
-# CLI Authentication
+# Authenticate CLI to HCP Terraform
> **Hands-on:** Try the [Authenticate the CLI with HCP Terraform](/terraform/tutorials/cloud/cloud-login?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx
index 8bdfd36f84e8..592da01a055c 100644
--- a/website/docs/cli/cloud/command-line-arguments.mdx
+++ b/website/docs/cli/cloud/command-line-arguments.mdx
@@ -1,9 +1,9 @@
---
-page_title: Command Line Arguments
-description: Command Line Arguments
+page_title: Command line arguments
+description: Command line arguments
---
-# 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
diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx
index 3f97f36dd67e..0246fe81b491 100644
--- a/website/docs/cli/cloud/index.mdx
+++ b/website/docs/cli/cloud/index.mdx
@@ -1,10 +1,10 @@
---
-page_title: Using HCP Terraform - Terraform CLI
+page_title: Use HCP Terraform - Terraform CLI
description: >-
Learn how to use HCP Terraform and Terraform Enterprise on the command line with the Terraform CLI.
---
-# Using HCP Terraform with Terraform CLI
+# Use HCP Terraform with Terraform CLI
The Terraform CLI integration with HCP Terraform lets you use HCP Terraform and Terraform Enterprise on the command line. In the documentation HCP Terraform instructions also apply to Terraform Enterprise, except where explicitly stated.
@@ -14,14 +14,18 @@ Using HCP Terraform through the command line is called the [CLI-driven run workf
Workspaces can also be configured for local execution, in which case HCP Terraform only stores state. In this mode, HCP Terraform 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](/terraform/language/settings/backends/remote). Refer to [Migrating from the remote
+
+
+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](/terraform/language/settings/backends/remote). Refer to [Migrating from the remote
backend](/terraform/cli/cloud/migrating) for details about switching to the CLI integration.
-## Documentation Summary
+
-- [HCP Terraform Settings](/terraform/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable HCP Terraform support.
-- [Initializing and Migrating](/terraform/cli/cloud/migrating) describes
+## Documentation summary
+
+- [HCP Terraform settings](/terraform/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable HCP Terraform support.
+- [Initialize and migrate](/terraform/cli/cloud/migrating) describes
how to start using HCP Terraform with a working directory that already has state data.
-- [Command Line Arguments](/terraform/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with HCP Terraform.
+- [Command Line arguments](/terraform/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with HCP Terraform.
Refer to the [CLI-driven Run Workflow](/terraform/cloud-docs/run/cli) for more details about how to use HCP Terraform from the command line.
diff --git a/website/docs/cli/cloud/migrating.mdx b/website/docs/cli/cloud/migrating.mdx
index 0949fef09318..a99ec6421e99 100644
--- a/website/docs/cli/cloud/migrating.mdx
+++ b/website/docs/cli/cloud/migrating.mdx
@@ -1,10 +1,10 @@
---
-page_title: Initializing and Migrating to HCP Terraform - Terraform CLI
+page_title: Initialize and migrate to HCP Terraform - Terraform CLI
description: >-
Learn how to use the Terraform CLI to migrate local or remote state to HCP Terraform.
---
-# Initializing and Migrating
+# Initialize and migrate to HCP Terraform
After [configuring HCP Terraform settings](/terraform/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 HCP Terraform right away. Refer to [CLI-driven run workflow](/terraform/cloud-docs/run/cli) for more details.
@@ -14,7 +14,7 @@ When you run `terraform init` in the following scenarios, Terraform will ask you
1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to HCP Terraform with the `remote` backend, Terraform can continue using the same HCP Terraform 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 HCP Terraform](/terraform/tutorials/cloud/cloud-migrate) tutorial.
@@ -35,19 +35,19 @@ according to a pattern relative to their existing names. This can indicate the f
`networking-staging-us-east`). Refer to [Workspace
Naming](/terraform/cloud-docs/workspaces/naming) in the HCP Terraform documentation for more detail.
-## Migrating from the `remote` Backend
+## Migrating from the `remote` backend
If the working directory was already connected to HCP Terraform with the `remote` backend, Terraform can continue using the same HCP Terraform workspaces. The local names shown for those workspaces will change to match their remote names.
The [`remote` backend](/terraform/language/settings/backends/remote) was the primary implementation of HCP Terraform's [CLI-driven run workflow](/terraform/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
When switching from the `remote` backend to a `cloud` block, Terraform will continue using the same
set of HCP Terraform workspaces. Replace your `backend "remote"` block with an equivalent `cloud`
block.
-#### Single Workspace
+#### Single workspace
If you were using a single workspace with the `name` argument, change the block
label to `cloud`.
@@ -65,7 +65,7 @@ terraform {
}
```
-#### Multiple Workspaces
+#### Multiple workspaces
If you were using multiple workspaces with the `prefix` argument, replace it with a `cloud` block that uses the `tags` argument. You may specify any number of tags to distinguish the workspaces for your working directory, but a good starting point may be to use whatever the prefix was before.
@@ -85,4 +85,8 @@ terraform {
}
```
-~> **Warning**: Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the Terraform CLI. For example, rather than `terraform workspace select prod`, you must run the command `terraform workspace select my-app-prod`.
+
+
+Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the Terraform CLI. For example, rather than `terraform workspace select prod`, you must run the command `terraform workspace select my-app-prod`.
+
+
diff --git a/website/docs/cli/cloud/settings.mdx b/website/docs/cli/cloud/settings.mdx
index 4d052fb64879..b5c0f22685f2 100644
--- a/website/docs/cli/cloud/settings.mdx
+++ b/website/docs/cli/cloud/settings.mdx
@@ -1,10 +1,10 @@
---
-page_title: HCP Terraform Settings - Terraform CLI
+page_title: HCP Terraform settings - Terraform CLI
description: >-
Configure the HCP Terraform CLI integration.
---
-# HCP Terraform Settings
+# HCP Terraform settings
Terraform CLI can integrate with HCP Terraform, acting as a client for HCP Terraform's
[CLI-driven run workflow](/terraform/cloud-docs/run/cli).
@@ -22,7 +22,7 @@ You must configure the following settings to use HCP Terraform for a particular
After adding or changing a `cloud` block, you must run `terraform init`.
-## The `cloud` Block
+## The `cloud` block
The `cloud` block is a nested block within the top-level `terraform` settings
block. It specifies which HCP Terraform workspaces to use for the current
@@ -89,13 +89,21 @@ The `cloud` block supports the following configuration arguments:
`credentials` in the
[CLI config file](/terraform/cli/config/config-file#credentials).
-### Environment Variables
+### Environment variables
--> **Note:** CLI integration environment variables are supported in Terraform v1.2.0 and later.
+
+
+CLI integration environment variables are supported in Terraform v1.2.0 and later.
+
+
You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure Terraform as part of a Continuous Integration (CI) pipeline. Terraform only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file.
-~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Refer to [Non-Interactive Workflows](/terraform/cloud-docs/run/cli#non-interactive-workflows) for details.
+
+
+Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Refer to [Non-Interactive Workflows](/terraform/cloud-docs/run/cli#non-interactive-workflows) for details.
+
+
Use the following environment variables to configure the `cloud` block:
@@ -107,7 +115,7 @@ Use the following environment variables to configure the `cloud` block:
- `TF_WORKSPACE` - The name of a single HCP Terraform workspace. Terraform reads this when `workspaces` is omitted from the `cloud` block. HCP Terraform will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/terraform/cli/config/environment-variables#tf_workspace) for details.
-## Excluding Files from Upload with .terraformignore
+## Exclude files from upload with .terraformignore
When executing a remote `plan` or `apply` in a [CLI-driven run](/terraform/cloud-docs/run/cli),
a copy of your configuration directory is uploaded to HCP Terraform. You can define
@@ -125,4 +133,8 @@ The rules in `.terraformignore` file resemble the rules allowed in a
- End a pattern with a forward slash `/` to specify a directory.
- Negate a pattern by starting it with an exclamation point `!`. When ignoring large directories, negation patterns can impact performance. Place negation rules as early as possible within `.terraformignore` or avoid using them if possible.
--> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.
+
+
+Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.
+
+
diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx
index 714f94227e5f..14f2ff6fe272 100644
--- a/website/docs/cli/code/index.mdx
+++ b/website/docs/cli/code/index.mdx
@@ -1,11 +1,11 @@
---
-page_title: Writing and Modifying Code - Terraform CLI
+page_title: Write and modify configuration - Terraform CLI
description: >-
Learn commands that help validate, format, and upgrade code written in the
Terraform Configuration Language.
---
-# Writing and Modifying Terraform Code
+# Write and modify Terraform configuration
The [Terraform language](/terraform/language) is Terraform's primary
user interface, and all of Terraform's workflows rely on configurations written
diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.mdx
index eb4acc2a2a23..3e77b36fd4d0 100644
--- a/website/docs/cli/commands/0.12upgrade.mdx
+++ b/website/docs/cli/commands/0.12upgrade.mdx
@@ -11,7 +11,11 @@ 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
with Terraform v0.12.
--> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12).
+
+
+**This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12).
+
+
## Usage
@@ -25,7 +29,7 @@ the same repository.
When run with no other options, the command will first explain what it is
going to do and prompt for confirmation:
-```
+```shell-session
$ terraform 0.12upgrade
This command will rewrite the configuration files in the given directory so
@@ -89,7 +93,7 @@ The command-line options are all optional. The available options are:
this command are not idempotent, so re-running against the same module may
change the meanings of some expressions in the module.
-## Batch Usage
+## Batch usage
After you've experimented with the `0.12upgrade` command in some confined
situations, if you have a repository containing multiple modules you may
@@ -97,14 +101,14 @@ wish to batch-upgrade them all and review them together. Recursive upgrades
are not supported by the tool itself, but if you are on a Unix-style system
you can achieve this using the `find` command as follows:
-```
-find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes
+```shell-session
+$ find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes
```
On Mac OS X, the `find` included with the system does not support the `-printf` argument. You can install GNU find using Homebrew in order to use that argument:
-```
-brew install findutils
+```shell-session
+$ brew install findutils
```
Once installed, run the above command line using `gfind` instead of `find`.
diff --git a/website/docs/cli/commands/0.13upgrade.mdx b/website/docs/cli/commands/0.13upgrade.mdx
index 51c5f451503a..dd3d68e66510 100644
--- a/website/docs/cli/commands/0.13upgrade.mdx
+++ b/website/docs/cli/commands/0.13upgrade.mdx
@@ -11,7 +11,11 @@ The `terraform 0.13upgrade` command updates existing configuration to add an
explicit `source` attribute for each provider used in a given module. The
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](/terraform/language/v1.1.x/upgrade-guides/0-13).
+
+
+**This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-13).
+
+
## Usage
@@ -24,7 +28,11 @@ providers where possible, and record this information in a
[required-providers]: /terraform/language/providers/requirements
-~> Note: the command ignores `.tf.json` files and override files in the module.
+
+
+The command ignores `.tf.json` files and override files in the module.
+
+
If the module already has a `required_providers` block, the command updates it
in-place. Otherwise, a new block is added to the `versions.tf` file.
@@ -37,7 +45,7 @@ the same repository.
When run with no other options, the command will first explain what it is
going to do and prompt for confirmation:
-```
+```shell-session
$ terraform 0.13upgrade
This command will update the configuration files in the given directory to use
@@ -74,13 +82,13 @@ wish to batch-upgrade them all and review them together. Recursive upgrades
are not supported by the tool itself, but if you are on a Unix-style system
you can achieve this using the `find` command as follows:
-```
+```shell-session
$ find . -name '*.tf' | xargs -n1 dirname | uniq | xargs -n1 terraform 0.13upgrade -yes
```
On a Windows system with PowerShell, you can use this command:
-```
+```shell
Get-Childitem -Recurse -Include *.tf | Split-Path | `
Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName }
```
diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx
index e5a23382acd2..60b30b56d7e9 100644
--- a/website/docs/cli/commands/apply.mdx
+++ b/website/docs/cli/commands/apply.mdx
@@ -16,18 +16,20 @@ plan.
Usage: `terraform apply [options] [plan file]`
-
-
-### Automatic Plan Mode
+### Automatic plan mode
When you run `terraform apply` without passing a saved plan file, Terraform automatically creates a new execution plan as if you had run [`terraform plan`](/terraform/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/terraform/cli/commands/plan#planning-modes) and
[planning options](/terraform/cli/commands/plan#planning-options) to customize how Terraform will create the plan.
You can pass the `-auto-approve` option to instruct Terraform to apply the plan without asking for confirmation.
-!> **Warning:** If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your Terraform workflow. This minimizes the risk of unpredictable changes and configuration drift.
+
+
+If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your Terraform workflow. This minimizes the risk of unpredictable changes and configuration drift.
+
+
-### Saved Plan Mode
+### Saved plan mode
When you pass a [saved plan file](/terraform/cli/commands/plan#out-filename) to `terraform apply`, Terraform takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when [running Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS).
@@ -37,14 +39,14 @@ When using a saved plan, you cannot specify any additional planning modes or opt
actions to take, and the plan file contains the final results of those
decisions.
-### Plan Options
+### Plan options
Without a saved plan file, `terraform apply` supports all planning modes and planning options available for `terraform plan`.
-- **[Planning Modes](/terraform/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update Terraform state and root module output values.
-- **[Planning Options](/terraform/cli/commands/plan#planning-options):** These include specifying which resource instances Terraform should replace (`-replace`), setting Terraform input variables (`-var` and `-var-file`), etc.
+- **[Planning modes](/terraform/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update Terraform state and root module output values.
+- **[Planning options](/terraform/cli/commands/plan#planning-options):** These include specifying which resource instances Terraform should replace (`-replace`), setting Terraform input variables (`-var` and `-var-file`), etc.
-### Apply Options
+### Apply options
The following options change how the apply command executes and reports on the apply operation.
@@ -86,7 +88,7 @@ The following options change how the apply command executes and reports on the a
rendered by a system that cannot interpret terminal formatting.
- `-parallelism=n` - Limit the number of concurrent operations as Terraform
- [walks the graph](/terraform/internals/graph#walking-the-graph). Defaults to
+ [walks the graph](/terraform/internals/graph#walk-the-graph). Defaults to
10\.
- All [planning modes](/terraform/cli/commands/plan#planning-modes) and
@@ -98,7 +100,7 @@ For configurations using
`terraform apply` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments).
-## Passing a Different Configuration Directory
+## Pass a different configuration directory
Terraform v0.13 and earlier also accepted a directory path in place of the
plan file argument to `terraform apply`, in which case Terraform would use
@@ -106,7 +108,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.
If your workflow relies on overriding the root module directory, use
-[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir)
+[the `-chdir` global option](/terraform/cli/commands#switch-working-directory-with-chdir)
instead, which works across all commands and makes Terraform consistently look
in the given directory for all files it would normally read or write in the
current working directory.
diff --git a/website/docs/cli/commands/console.mdx b/website/docs/cli/commands/console.mdx
index 1ebf64cccf7e..52b5b866735a 100644
--- a/website/docs/cli/commands/console.mdx
+++ b/website/docs/cli/commands/console.mdx
@@ -37,7 +37,7 @@ final command is printed unless an error occurs earlier.
For example:
-```shell
+```shell-session
$ echo 'split(",", "foo,bar,baz")' | terraform console
tolist([
"foo",
@@ -46,13 +46,13 @@ tolist([
])
```
-## Remote State
+## Remote state
If [remote state](/terraform/language/state/remote) is used by the current backend,
Terraform will read the state for the current workspace from the backend
before evaluating any expressions.
-## Evaluation against a Plan
+## Evaluation against a plan
By default, `terraform console` evaluates expressions against the current
Terraform state, and so the results are typically very limited for resource
@@ -112,8 +112,8 @@ can test interpolations to:
Print a value from a map:
-```
-> var.apps.foo
+```shell-session
+$ var.apps.foo
{
"region" = "us-east-1"
}
@@ -121,8 +121,8 @@ Print a value from a map:
Filter a map based on a specific value:
-```
-> { for key, value in var.apps : key => value if value.region == "us-east-1" }
+```shell-session
+$ { for key, value in var.apps : key => value if value.region == "us-east-1" }
{
"foo" = {
"region" = "us-east-1"
@@ -132,14 +132,14 @@ Filter a map based on a specific value:
Check if certain values may not be known until apply:
-```
-> random_pet.example
+```shell-session
+$ random_pet.example
(known after apply)
```
Test various functions:
-```
-> cidrnetmask("172.16.0.0/12")
+```shell-session
+$ cidrnetmask("172.16.0.0/12")
"255.240.0.0"
```
diff --git a/website/docs/cli/commands/destroy.mdx b/website/docs/cli/commands/destroy.mdx
index a7d26ab6c2d1..db99c598bc0a 100644
--- a/website/docs/cli/commands/destroy.mdx
+++ b/website/docs/cli/commands/destroy.mdx
@@ -22,8 +22,8 @@ Usage: `terraform destroy [options]`
This command is just a convenience alias for the following command:
-```
-terraform apply -destroy
+```shell-session
+$ terraform apply -destroy
```
For that reason, this command accepts most of the options that
@@ -34,17 +34,21 @@ planning mode.
You can also create a speculative destroy plan, to see what the effect of
destroying would be, by running the following command:
-```
-terraform plan -destroy
+```shell-session
+$ terraform plan -destroy
```
This will run [`terraform plan`](/terraform/cli/commands/plan) in _destroy_ mode, showing
you the proposed destroy changes without executing them.
--> **Note:** The `-destroy` option to `terraform apply` exists only in
+
+
+The `-destroy` option to `terraform apply` exists only in
Terraform v0.15.2 and later. For earlier versions, you _must_ use
`terraform destroy` to get the effect of `terraform apply -destroy`.
+
+
### Target a specific resource
You can use the `-target` option to destroy a particular resource and its dependencies:
diff --git a/website/docs/cli/commands/graph.mdx b/website/docs/cli/commands/graph.mdx
index 6ee59236ad88..10cef0f7d252 100644
--- a/website/docs/cli/commands/graph.mdx
+++ b/website/docs/cli/commands/graph.mdx
@@ -35,7 +35,7 @@ Options:
of the default resources-only simplified graph.
Can be: `plan`, `plan-refresh-only`, `plan-destroy`, or `apply`.
-## Generating Images
+## Generate images
The graph output uses
[the DOT language](https://en.wikipedia.org/wiki/DOT_(graph_description_language)),
@@ -47,7 +47,7 @@ third-party online graph rendering services which accept this format.
If you have the Graphviz `dot` command already installed, you can render
a PNG image by piping into that command:
-```shellsession
+```shell-session
$ terraform graph -type=plan | dot -Tpng >graph.png
```
diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx
index 808958f6f92c..37a1e2b79f89 100644
--- a/website/docs/cli/commands/import.mdx
+++ b/website/docs/cli/commands/import.mdx
@@ -27,7 +27,9 @@ it is the zone ID (`Z12ABC4UGMOZ2N`). Please reference the provider documentatio
on the ID format. If you're unsure, feel free to just try an ID. If the ID
is invalid, you'll just receive an error message.
-~> Warning: Terraform expects that each remote object it is managing will be
+
+
+Terraform expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by Terraform
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.
@@ -35,6 +37,8 @@ If you import the same object multiple times, Terraform may exhibit unwanted
behavior. For more information on this assumption, see
[the State section](/terraform/language/state).
+
+
Instead of manually importing resources, you can add the `import` block to your Terraform configurations so that Terraform imports resources when you run the `terraform apply` command. Using Terraform configurations lets you automate resource imports as part of your CI/CD pipelines. Refer to the [`import` block reference documentation](/terraform/language/import) for additional information.
The command-line flags are all optional. The following flags are available:
@@ -86,7 +90,7 @@ For configurations using
`terraform import` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments).
-## Provider Configuration
+## Provider configuration
Terraform will attempt to load configuration files that configure the
provider being used for import. If no configuration files are present or
@@ -113,50 +117,50 @@ provider "aws" {
}
```
-## Example: Import into Resource
+## Example: Import into resource
This example will import an AWS instance into the `aws_instance` resource named `foo`:
-```shell
+```shell-session
$ terraform import aws_instance.foo i-abcd1234
```
-## Example: Import into Module
+## Example: Import into module
The example below will import an AWS instance into the `aws_instance` resource named `bar` into a module named `foo`:
-```shell
+```shell-session
$ 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
[`count`](/terraform/language/meta-arguments/count):
-```shell
+```shell-session
$ 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
[`for_each`](/terraform/language/meta-arguments/for_each):
Linux, Mac OS, and UNIX:
-```shell
+```shell-session
$ terraform import 'aws_instance.baz["example"]' i-abcd1234
```
PowerShell:
-```shell
+```shell-session
$ terraform import 'aws_instance.baz[\"example\"]' i-abcd1234
```
Windows `cmd.exe`:
-```shell
+```shell-session
$ terraform import aws_instance.baz[\"example\"] i-abcd1234
```
diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx
index d9c026bec09d..f983bfefb763 100644
--- a/website/docs/cli/commands/index.mdx
+++ b/website/docs/cli/commands/index.mdx
@@ -1,9 +1,9 @@
---
-page_title: Basic CLI Features
+page_title: Basic CLI features
description: An introduction to the terraform command and its available subcommands.
---
-# Basic CLI Features
+# Basic CLI features
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials.
@@ -72,7 +72,7 @@ The inline help built in to Terraform CLI describes the most important
characteristics of each command. For more detailed information, refer to each
command's page for details.
-## Switching working directory with `-chdir`
+## Switch working directory with `-chdir`
The usual way to run Terraform is to first switch to the directory containing
the `.tf` files for your root module (for example, using the `cd` command), so
@@ -84,8 +84,8 @@ the root module directory. To allow that, Terraform supports a global option
`-chdir=...` which you can include before the name of the subcommand you intend
to run:
-```
-terraform -chdir=environments/production apply
+```shell-session
+$ terraform -chdir=environments/production apply
```
The `chdir` option instructs Terraform to change its working directory to the
@@ -105,15 +105,15 @@ even when you specify `-chdir=...`:
produce the original working directory instead of the overridden working
directory. Use `path.root` to get the root module directory.
-## Shell Tab-completion
+## Shell tab-completion
If you use either `bash` or `zsh` as your command shell, Terraform can provide
tab-completion support for all command names and some command arguments.
To add the necessary commands to your shell profile, run the following command:
-```bash
-terraform -install-autocomplete
+```shell-session
+$ terraform -install-autocomplete
```
After installation, it is necessary to restart your shell or to re-read its
@@ -122,11 +122,11 @@ profile script before completion will be activated.
To uninstall the completion hook, assuming that it has not been modified
manually in the shell profile, run the following command:
-```bash
-terraform -uninstall-autocomplete
+```shell-session
+$ terraform -uninstall-autocomplete
```
-## Upgrade and Security Bulletin Checks
+## Upgrade and security bulletin checks
The Terraform CLI commands interact with the HashiCorp service
[Checkpoint](https://checkpoint.hashicorp.com/) to check for the availability
diff --git a/website/docs/cli/commands/init.mdx b/website/docs/cli/commands/init.mdx
index 95f75ec96dd1..2d94cb3b4901 100644
--- a/website/docs/cli/commands/init.mdx
+++ b/website/docs/cli/commands/init.mdx
@@ -46,7 +46,7 @@ The following options apply to all of (or several of) the initialization steps:
* `-upgrade` Opt to upgrade modules and plugins as part of their respective
installation steps. See the sections below for more details.
-## Copy a Source Module
+## Copy a source module
By default, `terraform init` assumes that the working directory already
contains a configuration and will attempt to initialize that configuration.
@@ -71,7 +71,7 @@ it is possible to pass extra flags to the version control system when necessary,
and to perform other preparation steps (such as configuration generation, or
activating credentials) before running `terraform init`.
-## Backend Initialization
+## Initialize Backend
During init, the root configuration directory is consulted for
[backend configuration](/terraform/language/settings/backends/configuration) and the chosen backend
@@ -100,7 +100,7 @@ The `-backend-config=...` option can be used for
in situations where the backend settings are dynamic or sensitive and so cannot
be statically specified in the configuration file.
-## Child Module Installation
+## Install child module
During init, the configuration is searched for `module` blocks, and the source
code for referenced [modules](/terraform/language/modules/develop) is retrieved from the locations
@@ -116,7 +116,7 @@ steps can complete only when the module tree is complete, so it's recommended
to use this flag only when the working directory was already previously
initialized with its child modules.
-## Plugin Installation
+## Install plugin
Most Terraform providers are published separately from Terraform as plugins.
During init, Terraform searches the configuration for both direct and indirect
@@ -149,11 +149,16 @@ You can modify `terraform init`'s plugin behavior with the following options:
version constraints.
* `-get-plugins=false` — Skip plugin installation.
- -> Note: Since Terraform 0.13, this option has been superseded by the
+
+
+ Since Terraform 0.13, this option has been superseded by the
[`provider_installation`](/terraform/cli/config/config-file#provider-installation) and
[`plugin_cache_dir`](/terraform/cli/config/config-file#plugin_cache_dir) settings.
It should not be used in Terraform versions 0.13+, and this option
was removed in Terraform 0.15.
+
+
+
* `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from
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
@@ -183,7 +188,7 @@ including optionally making plugins available locally to avoid repeated
re-installation. For more information, see
the [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
-## Passing a Different Configuration Directory
+## Pass a different configuration directory
Terraform v0.13 and earlier also accepted a directory path in place of the
plan file argument to `terraform apply`, in which case Terraform would use
diff --git a/website/docs/cli/commands/login.mdx b/website/docs/cli/commands/login.mdx
index b2eb5372bbbd..aa3c4f578134 100644
--- a/website/docs/cli/commands/login.mdx
+++ b/website/docs/cli/commands/login.mdx
@@ -11,12 +11,16 @@ description: >-
The `terraform login` command can be used to automatically obtain and save an
API token for HCP Terraform, Terraform Enterprise, or any other host that offers Terraform services.
--> **Note:** This command is suitable only for use in interactive scenarios
+
+
+This command is suitable only for use in interactive scenarios
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,
you can
[configure credentials manually in the CLI configuration](/terraform/cli/config/config-file#credentials).
+
+
## Usage
Usage: `terraform login [hostname]`
@@ -24,7 +28,7 @@ Usage: `terraform login [hostname]`
If you don't provide an explicit hostname, Terraform will assume you want to
log in to HCP Terraform at `app.terraform.io`.
-## Credentials Storage
+## Credentials storage
By default, Terraform will obtain an API token and save it in plain text in a
local CLI configuration file called `credentials.tfrc.json`. When you run
@@ -38,7 +42,7 @@ optionally configure a
how to store and later retrieve credentials in some other system, such as
your organization's existing secrets management system.
-## Login Server Support
+## Login server support
The `terraform login` command works with any server supporting the
[login protocol](/terraform/internals/login-protocol), including HCP Terraform
diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.mdx
index f0158fa9a7cd..42f7cc3e4093 100644
--- a/website/docs/cli/commands/logout.mdx
+++ b/website/docs/cli/commands/logout.mdx
@@ -18,10 +18,14 @@ Usage: `terraform logout [hostname]`
If you don't provide an explicit hostname, Terraform will assume you want to
log out of HCP Terraform at `app.terraform.io`.
--> **Note:** the API token is only removed from local storage, not destroyed on
+
+
+The API token is only removed from local storage, not destroyed on
the remote server, so it will remain valid until manually revoked.
-## Credentials Storage
+
+
+## Credentials storage
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
diff --git a/website/docs/cli/commands/output.mdx b/website/docs/cli/commands/output.mdx
index 570c706636be..4327c3ec03e6 100644
--- a/website/docs/cli/commands/output.mdx
+++ b/website/docs/cli/commands/output.mdx
@@ -32,9 +32,13 @@ The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](/terraform/language/state/remote) is used.
--> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive
+
+
+When using the `-json` or `-raw` command-line flag, any sensitive
values in Terraform state will be displayed in plain text. For more information,
-see [Sensitive Data in State](/terraform/language/state/sensitive-data).
+see [Sensitive data in state](/terraform/language/state/sensitive-data).
+
+
## Examples
@@ -57,7 +61,7 @@ output "password" {
To list all outputs:
-```shellsession
+```shell-session
$ terraform output
instance_ips = [
"54.43.114.12",
@@ -70,21 +74,21 @@ password =
Note that Terraform does not redact the value when you specify the output by name:
-```shellsession
+```shell-session
$ terraform output password
password = notasecurepassword
```
To query for the DNS address of the load balancer:
-```shellsession
+```shell-session
$ terraform output lb_address
"my-app-alb-1657023003.us-east-1.elb.amazonaws.com"
```
To query for all instance IP addresses:
-```shellsession
+```shell-session
$ terraform output instance_ips
instance_ips = [
"54.43.114.12",
@@ -102,7 +106,7 @@ For scripting and automation, use `-json` to produce the stable JSON format.
You can parse the output using a JSON command-line parser such as
[jq](https://stedolan.github.io/jq/):
-```shellsession
+```shell-session
$ terraform output -json instance_ips | jq -r '.[0]'
54.43.114.12
```
@@ -111,7 +115,7 @@ For the common case of directly using a string value in a shell script, you
can use `-raw` instead, which will print the string directly with no extra
escaping or whitespace.
-```shellsession
+```shell-session
$ terraform output -raw lb_address
my-app-alb-1657023003.us-east-1.elb.amazonaws.com
```
diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx
index 7aa7b42cc43c..762b6d1bbb23 100644
--- a/website/docs/cli/commands/plan.mdx
+++ b/website/docs/cli/commands/plan.mdx
@@ -67,19 +67,19 @@ additional options for routine work.
The remaining sections on this page describe the various options:
-* **[Planning Modes](#planning-modes)**: There are some special alternative
+* **[Planning modes](#planning-modes)**: There are some special alternative
planning modes that you can use for some special situations where your goal
is not just to change the remote system to match your configuration.
-* **[Planning Options](#planning-options)**: Alongside the special planning
+* **[Planning options](#planning-options)**: Alongside the special planning
modes, there are also some options you can set in order to customize the
planning process for unusual needs.
- * **[Resource Targeting](#resource-targeting)** is one particular
+ * **[Resource targeting](#resource-targeting)** is one particular
special planning option that has some important caveats associated
with it.
-* **[Other Options](#other-options)**: These change the behavior of the planning
+* **[Other options](#other-options)**: These change the behavior of the planning
command itself, rather than customizing the content of the generated plan.
-## Planning Modes
+## Planning modes
The previous section describes Terraform's default planning behavior, which
changes the remote system to match the changes you make to
@@ -109,17 +109,20 @@ The planning modes are all mutually-exclusive, so activating any non-default
planning mode disables the "normal" planning mode, and you can't use more than
one alternative mode at the same time.
--> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is
+
+
+In Terraform v0.15 and earlier, the `-destroy` option is
supported only by the `terraform plan` command, and not by the
`terraform apply` command. To create and apply a plan in destroy mode in
earlier versions you must run [`terraform destroy`](/terraform/cli/commands/destroy).
--> **Note:** The `-refresh-only` option is available only in Terraform v0.15.4
-and later.
+
+
+The `-refresh-only` option is available only in Terraform v0.15.4 and later.
> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial.
-## Planning Options
+## Planning options
In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for both `terraform plan` and [`terraform apply`](/terraform/cli/commands/apply).
@@ -133,7 +136,11 @@ In addition to alternate [planning modes](#planning-modes), there are several op
on resource instances which match the given address and on any objects that
those instances depend on.
- -> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around Terraform limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
+
+
+ Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around Terraform limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
+
+
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](/terraform/language/values/variables) declared in the
@@ -151,7 +158,7 @@ There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](/terraform/language/values/variables#assigning-values-to-root-module-variables) for more information.
-### Input Variables on the Command Line
+### Input variables on the command line
You can use the `-var` command line option to specify values for
[input variables](/terraform/language/values/variables) declared in your
@@ -164,14 +171,18 @@ we recommend using the `-var-file` option instead, and write your actual values
in a separate file so that Terraform can parse them directly, rather than
interpreting the result of your shell's parsing.
-~> **Warning:** Terraform will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`).
+
+
+Terraform will error if you include a space before or after the equals sign (for example, `-var "length = 2"`).
+
+
To use `-var` on a Unix-style shell on a system like Linux or macOS we
recommend writing the option argument in single quotes `'` to ensure the
shell will interpret the value literally:
-```
-terraform plan -var 'name=value'
+```shell-session
+$ terraform plan -var 'name=value'
```
If your intended value also includes a single quote then you'll still need to
@@ -179,23 +190,23 @@ escape that for correct interpretation by your shell, which also requires
temporarily ending the quoted sequence so that the backslash escape character
will be significant:
-```
-terraform plan -var 'name=va'\''lue'
+```shell-session
+$ terraform plan -var 'name=va'\''lue'
```
When using Terraform on Windows, we recommend using the Windows Command Prompt
(`cmd.exe`). When you pass a variable value to Terraform from the Windows
Command Prompt, use double quotes `"` around the argument:
-```
-terraform plan -var "name=value"
+```shell-session
+$ terraform plan -var "name=value"
```
If your intended value includes literal double quotes then you'll need to
escape those with a backslash:
-```
-terraform plan -var "name=va\"lue"
+```shell-session
+$ terraform plan -var "name=va\"lue"
```
PowerShell on Windows cannot correctly pass literal quotes to external programs,
@@ -212,12 +223,12 @@ Terraform language expression representing the value, and write any necessary
quoting or escape characters to ensure it will pass through your shell
literally to Terraform. For example, for a `list(string)` type constraint:
-```
+```shell-session hideClipboard
# Unix-style shell
-terraform plan -var 'name=["a", "b", "c"]'
+$ terraform plan -var 'name=["a", "b", "c"]'
# Windows Command Prompt (do not use PowerShell on Windows)
-terraform plan -var "name=[\"a\", \"b\", \"c\"]"
+$ terraform plan -var "name=[\"a\", \"b\", \"c\"]"
```
Similar constraints apply when setting input variables using environment
@@ -225,7 +236,7 @@ variables. For more information on the various methods for setting root module
input variables, see
[Assigning Values to Root Module Variables](/terraform/language/values/variables#assigning-values-to-root-module-variables).
-### Resource Targeting
+### Resource targeting
> **Hands-on:** Try the [Target resources](/terraform/tutorials/state/resource-targeting?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
@@ -268,7 +279,7 @@ information about resources created in other configurations, allowing
a complex system architecture to be broken down into more manageable parts
that can be updated independently.
-## Other Options
+## Other options
The `terraform plan` command also has some other options that are related to
the input and output of the planning command, rather than customizing what
@@ -344,7 +355,7 @@ For configurations using
`terraform plan` accepts the legacy command line option
[`-state`](/terraform/language/settings/backends/local#command-line-arguments).
-### Passing a Different Configuration Directory
+### Pass a different configuration directory
Terraform v0.13 and earlier accepted an additional positional argument giving
a directory path, in which case Terraform would use that directory as the root
diff --git a/website/docs/cli/commands/providers/lock.mdx b/website/docs/cli/commands/providers/lock.mdx
index 3216618e2d49..bb1e3ee86b45 100644
--- a/website/docs/cli/commands/providers/lock.mdx
+++ b/website/docs/cli/commands/providers/lock.mdx
@@ -51,7 +51,9 @@ providers from their origin registries and then update
include a selected version for each provider and all of the package checksums
that are covered by the provider developer's cryptographic signature.
-~> **Warning:** The `terraform providers lock` command prints information
+
+
+The `terraform providers lock` command prints information
about what it has fetched and whether each package was signed using a
cryptographic signature, but it cannot automatically verify that the
providers are trustworthy and that they comply with your local system
@@ -59,6 +61,8 @@ policies or relevant regulations. Review the signing key information
in the output to confirm that you trust all of the signers before committing
the updated lock file to your version control system.
+
+
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,
leaving the lock entries for other providers (if any) unchanged.
@@ -95,7 +99,7 @@ You can customize the default behavior using the following additional option:
versions can be used installing the plugins from the cache is considered risky.
-## Specifying Target Platforms
+## Specify target platforms
In your environment you may, for example, have both developers who work with
your Terraform configuration on their Windows or macOS workstations _and_
@@ -106,8 +110,8 @@ all of those platforms, and to pre-populate the lock file with the necessary
checksums, by running `terraform providers lock` and specifying those three
platforms:
-```
-terraform providers lock \
+```shell-session
+$ terraform providers lock \
-platform=windows_amd64 \ # 64-bit Windows
-platform=darwin_amd64 \ # 64-bit macOS
-platform=linux_amd64 # 64-bit Linux
@@ -117,7 +121,7 @@ terraform providers lock \
you are running the command on Windows then you will need to put all of the
arguments on a single line, and remove the backslashes and comments.)
-## Lock Entries for In-house Providers
+## Lock entries for in-house providers
An _in-house provider_ is one that isn't published on a real Terraform provider
registry because it's developed and used only within a particular organization and
@@ -133,8 +137,8 @@ local mirror, you can use either the `-fs-mirror` or `-net-mirror` command
line options to override the default behavior of consulting the provider's
origin registry:
-```
-terraform providers lock \
+```shell-session
+$ terraform providers lock \
-fs-mirror=/usr/local/terraform/providers
-platform=windows_amd64 \
-platform=darwin_amd64 \
diff --git a/website/docs/cli/commands/providers/schema.mdx b/website/docs/cli/commands/providers/schema.mdx
index 1e5921a25ac9..1d35e5a9c476 100644
--- a/website/docs/cli/commands/providers/schema.mdx
+++ b/website/docs/cli/commands/providers/schema.mdx
@@ -11,7 +11,11 @@ description: >-
The `terraform providers schema` command is used to print detailed schemas for the providers used in the current configuration.
--> `terraform providers schema` requires **Terraform v0.12 or later**.
+
+
+`terraform providers schema` requires **Terraform v0.12 or later**.
+
+
## Usage
@@ -36,7 +40,7 @@ value `"1.0"`. The semantics of this version are:
We will introduce new major versions only within the bounds of
[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises).
-## Format Summary
+## Format summary
The following sections describe the JSON output format by example, using a pseudo-JSON notation.
Important elements are described with comments, which are prefixed with //.
@@ -50,7 +54,7 @@ The JSON output format consists of the following objects and sub-objects:
- [Function Representation](#function-representation) - a sub-object of functions that describes parameters, the return, and additional documentation
- [Parameter Representation](#parameter-representation) - a sub-object of function signatures that describes their type and additional documentation
-## Providers Schema Representation
+## Providers schema representation
```javascript
{
@@ -85,7 +89,7 @@ The JSON output format consists of the following objects and sub-objects:
}
```
-## Schema Representation
+## Schema representation
A schema representation pairs a provider or resource schema (in a "block") with that schema's version.
@@ -97,7 +101,7 @@ A schema representation pairs a provider or resource schema (in a "block") with
}
```
-## Block Representation
+## Block representation
A block representation contains "attributes" and "block_types" (which represent nested blocks).
@@ -158,7 +162,7 @@ A block representation contains "attributes" and "block_types" (which represent
}
```
-## Function Representation
+## Function representation
A function representation describes the definition of a function.
@@ -194,7 +198,7 @@ A function representation describes the definition of a function.
}
```
-## Parameter Representation
+## Parameter representation
A parameter representation describes a parameter to a function.
diff --git a/website/docs/cli/commands/push.mdx b/website/docs/cli/commands/push.mdx
index 1771d330e0c4..0895725d55be 100644
--- a/website/docs/cli/commands/push.mdx
+++ b/website/docs/cli/commands/push.mdx
@@ -7,7 +7,11 @@ description: >-
# Command: push
-!> **Important:** The `terraform push` command is no longer functional. We recommend the [HCP Terraform CLI integration](/terraform/cli/cloud) instead, which allows you to run remote operations in HCP Terraform directly from the command line.
+
+
+The `terraform push` command is no longer functional. We recommend the [HCP Terraform CLI integration](/terraform/cli/cloud) instead, which allows you to run remote operations in HCP Terraform directly from the command line.
+
+
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.
diff --git a/website/docs/cli/commands/refresh.mdx b/website/docs/cli/commands/refresh.mdx
index d44f4f1abf39..3a8e2b39869d 100644
--- a/website/docs/cli/commands/refresh.mdx
+++ b/website/docs/cli/commands/refresh.mdx
@@ -12,10 +12,14 @@ description: |-
The `terraform refresh` command reads the current settings from all managed
remote objects and updates the Terraform state to match.
-~> _Warning:_ This command is deprecated, because its default behavior is
+
+
+This command is deprecated, because its default behavior is
unsafe if you have misconfigured credentials for any of your providers.
See below for more information and recommended alternatives.
+
+
This won't modify your real remote objects, but it will modify the
[Terraform state](/terraform/language/state).
@@ -35,8 +39,8 @@ Usage: `terraform refresh [options]`
This command is effectively an alias for the following command:
-```
-terraform apply -refresh-only -auto-approve
+```shell-session
+$ terraform apply -refresh-only -auto-approve
```
Consequently, it supports all of the same options as
@@ -53,8 +57,8 @@ Instead, we recommend using the following command in order to get the same
effect but with the opportunity to review the changes that Terraform has
detected before committing them to the state:
-```
-terraform apply -refresh-only
+```shell-session
+$ terraform apply -refresh-only
```
This alternative command will present an interactive prompt for you to confirm
diff --git a/website/docs/cli/commands/show.mdx b/website/docs/cli/commands/show.mdx
index cbde69f54e58..636e4d65c922 100644
--- a/website/docs/cli/commands/show.mdx
+++ b/website/docs/cli/commands/show.mdx
@@ -17,11 +17,15 @@ as Terraform sees it.
Machine-readable output is generated by adding the `-json` command-line
flag.
--> **Note:** When using the `-json` command-line flag, any sensitive values in
+
+
+When using the `-json` command-line flag, any sensitive values in
Terraform state will be displayed in plain text. For more information, see
-[Sensitive Data in State](/terraform/language/state/sensitive-data).
+[Sensitive data in state](/terraform/language/state/sensitive-data).
-## JSON Output
+
+
+## JSON output
For Terraform state files (including when no path is provided),
`terraform show -json` will show a JSON representation of the state.
@@ -51,4 +55,4 @@ This command accepts the following options:
* `-json` - Displays machine-readable output from a state or plan file
--> JSON output via the `-json` option requires **Terraform v0.12 or later**.
+JSON output via the `-json` option requires **Terraform v0.12 or later**.
diff --git a/website/docs/cli/commands/state/index.mdx b/website/docs/cli/commands/state/index.mdx
index 0d5a46be8c9b..8287939ae7aa 100644
--- a/website/docs/cli/commands/state/index.mdx
+++ b/website/docs/cli/commands/state/index.mdx
@@ -3,7 +3,7 @@ page_title: 'Command: state'
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.
As your Terraform usage becomes more advanced, there are some cases where
@@ -20,7 +20,7 @@ Usage: `terraform state [options] [args]`
Please click a subcommand to the left for more information.
-## Remote State
+## Remote state
The Terraform state subcommands all work with remote state just as if it
was local state. Reads and writes may take longer than normal as each read
@@ -40,7 +40,7 @@ the sensitivity of the state file, Terraform forces every state modification
command to write a backup file. You'll have to remove these files manually
if you don't want to keep them around.
-## Command-Line Friendly
+## Command-Line friendly
The output and command-line structure of the state subcommands is
designed to be usable with Unix command-line tools such as grep, awk,
diff --git a/website/docs/cli/commands/state/list.mdx b/website/docs/cli/commands/state/list.mdx
index f3879ab6b6e8..fe81acbe9c86 100644
--- a/website/docs/cli/commands/state/list.mdx
+++ b/website/docs/cli/commands/state/list.mdx
@@ -32,11 +32,11 @@ The command-line flags are all optional. The following flags are available:
Ignored when [remote state](/terraform/language/state/remote) is used.
* `-id=id` - ID of resources to show. Ignored when unset.
-## Example: All Resources
+## Example: List all resources
This example will list all resources, including modules:
-```
+```shell-session
$ terraform state list
aws_instance.foo
aws_instance.bar[0]
@@ -44,33 +44,33 @@ aws_instance.bar[1]
module.elb.aws_elb.main
```
-## Example: Filtering by Resource
+## Example: Filter by resource
This example will only list resources for the given name:
-```
+```shell-session
$ terraform state list aws_instance.bar
aws_instance.bar[0]
aws_instance.bar[1]
```
-## Example: Filtering by Module
+## Example: Filter by module
This example will list resources in the given module and any submodules:
-```
+```shell-session
$ terraform state list module.elb
module.elb.aws_elb.main
module.elb.module.secgroups.aws_security_group.sg
```
-## Example: Filtering by ID
+## Example: Filter by ID
This example will only list the resource whose ID is specified on the
command line. This is useful to find where in your configuration a
specific resource is located.
-```
+```shell-session
$ terraform state list -id=sg-1234abcd
module.elb.aws_security_group.sg
```
diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.mdx
index f6b1c0264464..810b37ec8e15 100644
--- a/website/docs/cli/commands/state/mv.mdx
+++ b/website/docs/cli/commands/state/mv.mdx
@@ -44,7 +44,9 @@ 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
existing object to the new address in Terraform.
-~> _Warning:_ If you are using Terraform in a collaborative environment, you
+
+
+If you are using Terraform in a collaborative environment, you
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
makes any other changes between your configuration change and your
@@ -52,6 +54,8 @@ makes any other changes between your configuration change and your
a plan that will destroy the old object and create a new object at the new
address.
+
+
This command also accepts the following options:
- `-dry-run` - Report all of the resource instances that match the given
@@ -83,7 +87,7 @@ For configurations using
`terraform state mv` also accepts the legacy options
[`-state`, `-state-out`, `-backup`, and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments).
-## Example: Rename a Resource
+## Example: Rename a resource
Renaming a resource means making a configuration change like the following:
@@ -98,47 +102,47 @@ To tell Terraform that it should treat the new "helper" resource as a rename
of the old "worker" resource, you can pair the above configuration change
with the following command:
-```shell
-terraform state mv packet_device.worker packet_device.helper
+```shell-session
+$ terraform state mv packet_device.worker packet_device.helper
```
-## Example: Move a Resource Into a Module
+## Example: Move a resource into a module
If you originally wrote a resource in your root module but now wish to refactor
it into a child module, you can move the `resource` block into the child
module configuration, removing the original in the root module, and then
run the following command to tell Terraform to treat it as a move:
-```shell
-terraform state mv packet_device.worker module.worker.packet_device.worker
+```shell-session
+$ terraform state mv packet_device.worker module.worker.packet_device.worker
```
In the above example the new resource has the same name but a different module
address. You could also change the resource name at the same time, if the new
module organization suggests a different naming scheme:
-```shell
-terraform state mv packet_device.worker module.worker.packet_device.main
+```shell-session
+$ terraform state mv packet_device.worker module.worker.packet_device.main
```
-## Example: Move a Module Into a Module
+## Example: Move a module into a module
You can also refactor an entire module into a child module. In the
configuration, move the `module` block representing the module into a different
module and then pair that change with a command like the following:
-```shell
-terraform state mv module.app module.parent.module.app
+```shell-session
+$ 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](/terraform/language/meta-arguments/count)
has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given
address:
-```shell
+```shell-session
$ terraform state mv 'packet_device.worker[0]' 'packet_device.helper[0]'
```
@@ -148,7 +152,7 @@ move from an address not containing an index to an address containing an index,
or the opposite, as long as the address type you use matches whether and how
each resource is configured:
-```shell
+```shell-session
$ terraform state mv 'packet_device.main' 'packet_device.all[0]'
```
@@ -156,7 +160,7 @@ Brackets (`[`, `]`) have a special meaning in some shells, so you may need to
quote or escape the address in order to pass it literally to Terraform.
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](/terraform/language/meta-arguments/for_each)
has multiple instances that are each identified by an string. You can
@@ -169,20 +173,20 @@ quoting and/or escaping syntax for the shell you are using. For example:
Unix-style shells, such as on Linux or macOS:
-```shell
-terraform state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'
+```shell-session
+$ terraform state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'
```
Windows Command Prompt (`cmd.exe`):
-```shell
-terraform state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]
+```shell-session
+$ terraform state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]
```
PowerShell:
-```shell
-terraform state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'
+```shell-session
+$ terraform state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'
```
Aside from the use of strings instead of integers for instance keys, the
diff --git a/website/docs/cli/commands/state/pull.mdx b/website/docs/cli/commands/state/pull.mdx
index 115b5c6c3f2e..7cd14f6cb336 100644
--- a/website/docs/cli/commands/state/pull.mdx
+++ b/website/docs/cli/commands/state/pull.mdx
@@ -27,4 +27,8 @@ You cannot use this command to inspect the Terraform version of
the remote state, as it will always be converted to the current Terraform
version before output.
--> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state pull | sc terraform.tfstate`.
+
+
+Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state pull | sc terraform.tfstate`.
+
+
diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx
index b3a73175ec12..1ae1700f636d 100644
--- a/website/docs/cli/commands/state/push.mdx
+++ b/website/docs/cli/commands/state/push.mdx
@@ -23,7 +23,11 @@ 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.
--> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state push | sc terraform.tfstate`.
+
+
+Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state push | sc terraform.tfstate`.
+
+
Terraform will perform a number of safety checks to prevent you from
making changes that appear to be unsafe:
@@ -39,7 +43,7 @@ making changes that appear to be unsafe:
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
+**We do not recommend this.** If you disable the safety checks and are
pushing state, the destination state will be overwritten.
For configurations using the [HCP Terraform CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote)
diff --git a/website/docs/cli/commands/state/replace-provider.mdx b/website/docs/cli/commands/state/replace-provider.mdx
index 817a50030f0c..2075cc7fd730 100644
--- a/website/docs/cli/commands/state/replace-provider.mdx
+++ b/website/docs/cli/commands/state/replace-provider.mdx
@@ -46,6 +46,6 @@ For configurations using
The example below replaces the `hashicorp/aws` provider with a fork by `acme`, hosted at a private registry at `registry.acme.corp`:
-```shell
+```shell-session
$ terraform state replace-provider hashicorp/aws registry.acme.corp/acme/aws
```
diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.mdx
index 5c04116538a4..89f076ce1824 100644
--- a/website/docs/cli/commands/state/rm.mdx
+++ b/website/docs/cli/commands/state/rm.mdx
@@ -18,7 +18,11 @@ to remove a binding to an existing remote object without first destroying it,
which will effectively make Terraform "forget" the object while it continues
to exist in the remote system.
--> **Note:** Terraform v1.7.0 and later supports `removed` blocks. Unlike the `terraform state rm` command, you can use `removed` blocks to remove more than one resource at a time, and you can review removals as part of your normal plan and apply workflow. [Learn more about using `removed` blocks with resources](/terraform/language/resources/syntax#removing-resources) and [using `removed` blocks with modules](/terraform/language/modules/syntax#removing-modules).
+
+
+Terraform v1.7.0 and later supports `removed` blocks. Unlike the `terraform state rm` command, you can use `removed` blocks to remove more than one resource at a time, and you can review removals as part of your normal plan and apply workflow. [Learn more about using `removed` blocks with resources](/terraform/language/resources/syntax#removing-resources) and [using `removed` blocks with modules](/terraform/language/modules/syntax#removing-modules).
+
+
## Usage
@@ -61,45 +65,45 @@ For configurations using
`terraform state rm` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments).
-## Example: Remove all Instances of a Resource
+## Example: Remove all instances of a resource
The following example will cause Terraform to "forget" all of the instances
of the `packet_device` resource named "worker".
-```shell
+```shell-session
$ terraform state rm 'packet_device.worker'
```
A resource that doesn't use `count` or `for_each` has only one instance, so
this is also the appropriate syntax to select that single instance.
-## Example: Remove all Instances of a Resource in a Module
+## Example: Remove all instances of a resource in a module
To select a resource that you've defined in a child module you must specify
the path of that module as part of the resource address:
-```shell
+```shell-session
$ terraform state rm 'module.foo.packet_device.worker'
```
-## Example: Remove all Instances of all Resources in a Module
+## Example: Remove all instances of all resources in a module
The following example will cause Terraform to "forget" all of the instances
associated with all resources defined in all instances of the module named
`foo`:
-```shell
+```shell-session
$ 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](/terraform/language/meta-arguments/count)
has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given
address:
-```shell
+```shell-session
$ terraform state rm 'packet_device.worker[0]'
```
@@ -107,7 +111,7 @@ Brackets (`[`, `]`) have a special meaning in some shells, so you may need to
quote or escape the address in order to pass it literally to Terraform.
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](/terraform/language/meta-arguments/for_each)
has multiple instances that are each identified by an string. You can
@@ -120,18 +124,18 @@ quoting and/or escaping syntax for the shell you are using. For example:
Unix-style shells, such as on Linux or macOS:
-```shell
+```shell-session
$ terraform state rm 'packet_device.worker["example"]'
```
Windows Command Prompt (`cmd.exe`):
-```shell
+```shell-session
$ terraform state rm packet_device.worker[\"example\"]
```
PowerShell:
-```shell
+```shell-session
$ terraform state rm 'packet_device.worker[\"example\"]'
```
diff --git a/website/docs/cli/commands/state/show.mdx b/website/docs/cli/commands/state/show.mdx
index b64636200321..9cc9664f6749 100644
--- a/website/docs/cli/commands/state/show.mdx
+++ b/website/docs/cli/commands/state/show.mdx
@@ -32,7 +32,7 @@ programmatic consumption. To extract state data for use in other software, use
[`terraform show -json`](/terraform/cli/commands/show#json-output) and decode the result
using the documented structure.
-## Example: Show a Resource
+## Example: Show a resource
The example below shows a `packet_device` resource named `worker`:
@@ -49,41 +49,41 @@ resource "packet_device" "worker" {
}
```
-## Example: Show a Module Resource
+## Example: Show a module resource
The example below shows a `packet_device` resource named `worker` inside a module named `foo`:
-```shell
+```shell-session
$ 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
[`count`](/terraform/language/meta-arguments/count):
-```shell
+```shell-session
$ terraform state show 'packet_device.worker[0]'
```
-## Example: Show a Resource configured with for_each
+## Example: Show a resource configured with for_each
The following example shows the `"example"` instance of a `packet_device` resource named `worker` configured with the [`for_each`](/terraform/language/meta-arguments/for_each) meta-argument. You must place the resource name in single quotes when it contains special characters like double quotes.
Linux, Mac OS, and UNIX:
-```shell
+```shell-session
$ terraform state show 'packet_device.worker["example"]'
```
PowerShell:
-```shell
+```shell-session
$ terraform state show 'packet_device.worker[\"example\"]'
```
Windows `cmd.exe`:
-```shell
+```shell-session
$ terraform state show packet_device.worker[\"example\"]
```
diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx
index 3f9bb3e62281..47f37eae99f9 100644
--- a/website/docs/cli/commands/taint.mdx
+++ b/website/docs/cli/commands/taint.mdx
@@ -12,13 +12,17 @@ become degraded or damaged. Terraform represents this by marking the
object as "tainted" in the Terraform state, and Terraform will
propose to replace it in the next plan you create.
-~> **Warning:** This command is deprecated. For Terraform v0.15.2 and later, we recommend using the `-replace` option with `terraform apply` instead (details below).
+
-## Recommended Alternative
+This command is deprecated. For Terraform v0.15.2 and later, we recommend using the `-replace` option with `terraform apply` instead (details below).
+
+
+
+## Recommended alternative
For Terraform v0.15.2 and later, we recommend using the [`-replace` option](/terraform/cli/commands/plan#replace-address) with `terraform apply` to force Terraform to replace an object even though there are no configuration changes that would require it.
-```
+```shell-session
$ terraform apply -replace="aws_instance.example[0]"
```
@@ -26,7 +30,7 @@ We recommend the `-replace` option because the change will be reflected in the T
## Usage
-```
+```shell-session
$ terraform taint [options]
```
diff --git a/website/docs/cli/commands/test.mdx b/website/docs/cli/commands/test.mdx
index 6c6898ba6221..3d3e96ed42c0 100644
--- a/website/docs/cli/commands/test.mdx
+++ b/website/docs/cli/commands/test.mdx
@@ -18,9 +18,13 @@ This command searches the current directory and the specified testing directory
Terraform then executes a series of Terraform plan or apply commands according to the test files' specifications, and also validates the relevant plan and state files according to the test files' specifications.
-!> **Warning:** The Terraform test command can create real infrastructure than can cost you money. Refer to the [Terraform Test Cleanup](#terraform-test-cleanup) section for best practices on ensuring created infrastructure is destroyed.
+
+
+The Terraform test command can create real infrastructure than can cost you money. Refer to the [Terraform test cleanup](#terraform-test-cleanup) section for best practices on ensuring created infrastructure is destroyed.
-## General Options
+
+
+## General options
The following options apply to the Terraform `test` command:
@@ -34,11 +38,11 @@ The following options apply to the Terraform `test` command:
* `-verbose` - Prints out the plan or state for each `run` block within a test file, based on the `command` attribute of each `run` block.
-## State Management
+## State management
Each Terraform test file will maintain all Terraform state it requires within memory as it executes, starting empty. This state is entirely separate from any existing state for the configuration under test, so you can safely execute Terraform test commands without affecting any live infrastructure.
-### Terraform Test Cleanup
+### Terraform test cleanup
The Terraform `test` command creates _real_ infrastructure. Once Terraform fully executes each test file, Terraform attempts to destroy any remaining infrastructure. If it cannot do this, Terraform reports a list of resources it created but could not destroy.
@@ -56,11 +60,11 @@ You must provide a module from a _private_ registry, not the public Terraform re
You must execute [`terraform login`](/terraform/cli/commands/login) before using this option, and ensure that your `hostname` argument matches the private registry hostname of your target module.
-## Example: Test Directory Structure and Commands
+## Example: Test directory structure and commands
The following directory structure represents an example directory tree for a Terraform module with tests and a setup module.
-```
+```text hideClipboard
project/
|-- main.tf
|-- outputs.tf
@@ -87,27 +91,27 @@ Specific test files can be executed using the `-filter` option.
Linux, Mac OS, and UNIX:
-```shell
-terraform test -filter=tests/validations.tftest.hcl
+```shell-session
+$ terraform test -filter=tests/validations.tftest.hcl
```
PowerShell:
-```shell
-terraform test -filter='tests\validations.tftest.hcl'
+```shell-session
+$ terraform test -filter='tests\validations.tftest.hcl'
```
Windows `cmd.exe`:
-```shell
-terraform test -filter=tests\validations.tftest.hcl
+```shell-session
+$ terraform test -filter=tests\validations.tftest.hcl
```
-### Alternate Test Directories
+### Alternate test directories
In the above example the tests are in the default testing directory of `tests`. Test files can also be included directly within the main configuration directory:
-```
+```text hideClipboard
project/
|-- main.tf
|-- outputs.tf
@@ -129,6 +133,10 @@ You can also use the `-test-directory` argument to change the location of the te
The testing directory must be beneath the main configuration directory, but it can be nested many times.
-> Note: Test files within the root configuration directory are always loaded, regardless of the `-test-directory` value.
+
+
+Test files within the root configuration directory are always loaded, regardless of the `-test-directory` value.
+
+
We do not recommend changing the default test directory. The option for customization is included for configuration authors who may have included a `tests` submodule in their configuration before the `terraform test` command was released. In general, the default test directory of `tests` should always be used.
diff --git a/website/docs/cli/commands/untaint.mdx b/website/docs/cli/commands/untaint.mdx
index ed76a4bca460..fcc47af61725 100644
--- a/website/docs/cli/commands/untaint.mdx
+++ b/website/docs/cli/commands/untaint.mdx
@@ -30,8 +30,8 @@ If you remove the taint marker from an object but then later discover that it
was degraded after all, you can create and apply a plan to replace it without
first re-tainting the object, by using a command like the following:
-```
-terraform apply -replace="aws_instance.example[0]"
+```shell-session
+$ terraform apply -replace="aws_instance.example[0]"
```
## Usage
diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.mdx
index e9e78f685994..c52ed722d395 100644
--- a/website/docs/cli/commands/validate.mdx
+++ b/website/docs/cli/commands/validate.mdx
@@ -22,7 +22,7 @@ system.
Validation requires an initialized working directory with any referenced plugins and modules installed. To initialize a working directory for validation without accessing any configured backend, use:
-```
+```shell-session
$ terraform init -backend=false
```
@@ -42,7 +42,7 @@ This command accepts the following options:
* `-no-color` - If specified, output won't contain any color.
-## JSON Output Format
+## JSON output format
When you use the `-json` option, Terraform will produce validation results
in JSON format to allow using the validation result for tool integrations, such
@@ -178,7 +178,7 @@ The nested objects in `diagnostics` have the following properties:
which may be useful in understanding the source of a diagnostic in a
complex expression. These expression value objects are described below.
-### Source Position
+### Source position
A source position object, as used in the `range` property of a diagnostic
object, has the following properties:
@@ -195,7 +195,7 @@ A `start` position is inclusive while an `end` position is exclusive. The
exact positions used for particular error messages are intended for human
interpretation only.
-### Expression Value
+### Expression value
An expression value object gives additional information about a value that is
part of the expression which triggered the diagnostic. This is especially
diff --git a/website/docs/cli/commands/version.mdx b/website/docs/cli/commands/version.mdx
index 378ec3ae795a..e93f6d0a0fc2 100644
--- a/website/docs/cli/commands/version.mdx
+++ b/website/docs/cli/commands/version.mdx
@@ -29,7 +29,7 @@ This command has one optional flag:
Basic usage, with upgrade and security information shown if relevant:
-```shellsession
+```shell-session
$ terraform version
Terraform v0.15.0
on darwin_amd64
@@ -41,7 +41,7 @@ is X.Y.Z. You can update by downloading from https://www.terraform.io/downloads.
As JSON:
-```shellsession
+```shell-session
$ terraform version -json
{
"terraform_version": "0.15.0",
diff --git a/website/docs/cli/commands/workspace/delete.mdx b/website/docs/cli/commands/workspace/delete.mdx
index 8475440c6182..91e512efcf79 100644
--- a/website/docs/cli/commands/workspace/delete.mdx
+++ b/website/docs/cli/commands/workspace/delete.mdx
@@ -37,7 +37,7 @@ The command-line flags are all optional. The only supported flags are:
## Example
-```
+```shell-session
$ terraform workspace delete example
Deleted workspace "example".
```
diff --git a/website/docs/cli/commands/workspace/list.mdx b/website/docs/cli/commands/workspace/list.mdx
index d7d2e6eee285..68fd60dad562 100644
--- a/website/docs/cli/commands/workspace/list.mdx
+++ b/website/docs/cli/commands/workspace/list.mdx
@@ -16,7 +16,7 @@ indicated using an asterisk (`*`) marker.
## Example
-```
+```shell-session
$ terraform workspace list
default
* development
diff --git a/website/docs/cli/commands/workspace/new.mdx b/website/docs/cli/commands/workspace/new.mdx
index 28b4d1c30d4e..89903096ae34 100644
--- a/website/docs/cli/commands/workspace/new.mdx
+++ b/website/docs/cli/commands/workspace/new.mdx
@@ -27,7 +27,7 @@ The command-line flags are all optional. The supported flags are:
## Example: Create
-```
+```shell-session
$ terraform workspace new example
Created and switched to workspace "example"!
@@ -36,11 +36,11 @@ so if you run "terraform plan" Terraform will not see any existing state
for this configuration.
```
-## Example: Create from State
+## Example: Create from state
To create a new workspace from a pre-existing local state file:
-```
+```shell-session
$ terraform workspace new -state=old.terraform.tfstate example
Created and switched to workspace "example".
diff --git a/website/docs/cli/commands/workspace/select.mdx b/website/docs/cli/commands/workspace/select.mdx
index 497a56544623..41ef6d633184 100644
--- a/website/docs/cli/commands/workspace/select.mdx
+++ b/website/docs/cli/commands/workspace/select.mdx
@@ -21,7 +21,7 @@ The supported flags are:
## Example
-```
+```shell-session
$ terraform workspace list
default
* development
diff --git a/website/docs/cli/commands/workspace/show.mdx b/website/docs/cli/commands/workspace/show.mdx
index c6063f22fddc..8061f9cba599 100644
--- a/website/docs/cli/commands/workspace/show.mdx
+++ b/website/docs/cli/commands/workspace/show.mdx
@@ -15,7 +15,7 @@ The command will display the current workspace.
## Example
-```
+```shell-session
$ terraform workspace show
development
```
diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.mdx
index 2dec34a76e73..5a469dc7508a 100644
--- a/website/docs/cli/config/config-file.mdx
+++ b/website/docs/cli/config/config-file.mdx
@@ -1,11 +1,11 @@
---
-page_title: CLI Configuration
+page_title: CLI configuration file
description: >-
Learn to use the CLI configuration file to customize your CLI settings,
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,
which apply across all Terraform working directories. This is separate from
@@ -34,7 +34,7 @@ The location of the Terraform CLI configuration file can also be specified
using the `TF_CLI_CONFIG_FILE` [environment variable](/terraform/cli/config/environment-variables).
Any such file should follow the naming pattern `*.tfrc`.
-## Configuration File Syntax
+## Configuration file syntax
The configuration file uses the same _HCL_ syntax as `.tf` files, but with
different attributes and blocks. The following example illustrates the
@@ -46,7 +46,7 @@ plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
disable_checkpoint = true
```
-## Available Settings
+## Available settings
The following settings can be set in the CLI configuration file:
@@ -109,15 +109,23 @@ or a
[team token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens);
organization tokens cannot be used for command-line Terraform actions.
--> **Note:** The credentials hostname must match the hostname in your module
+
+
+The credentials hostname must match the hostname in your module
sources and/or backend configuration. If your Terraform Enterprise instance
is available at multiple hostnames, use only one of them consistently.
HCP Terraform responds to API calls at both its current hostname
`app.terraform.io`, and its historical hostname `atlas.hashicorp.com`.
-### Environment Variable Credentials
+
--> **Note:** Environment variable credentials are supported in Terraform v1.2.0 and later.
+### Environment variable credentials
+
+
+
+Environment variable credentials are supported in Terraform v1.2.0 and later.
+
+
If you would prefer not to store your API tokens directly in the CLI configuration, you may use
a host-specific environment variable. Environment variable names should have the prefix
@@ -135,7 +143,7 @@ may be encoded as double underscores. For example, you can set a token for the d
If multiple variables evaluate to the same hostname, Terraform will choose the one defined last
in the operating system's variable table.
-### Credentials Helpers
+### Credentials helpers
You can configure a `credentials_helper` to instruct Terraform to use a different credentials storage mechanism.
@@ -163,17 +171,21 @@ To learn how to write and install your own credentials helpers to integrate
with existing in-house credentials management systems, see
[the guide to Credentials Helper internals](/terraform/internals/credentials-helpers).
-### Credentials Source Priority Order
+### Credentials source priority order
Credentials found in an environment variable for a particular service host
as described above will be preferred over those in CLI config as set by `terraform login`.
If neither are set, any configured credentials helper will be consulted.
-~> **Note:** For users of [terraform-credentials-helper](https://github.com/apparentlymart/terraform-credentials-env), this priority has been effectively reversed following the
+
+
+For users of [terraform-credentials-helper](https://github.com/apparentlymart/terraform-credentials-env), this priority has been effectively reversed following the
release of Terraform 1.2. Previously, credentials found within CLI config or set by
`terraform login` were preferred to `TF_TOKEN_*` variables.
-## Provider Installation
+
+
+## Install provider
The default way to install provider plugins is from a provider registry. The
origin registry for a provider is encoded in the provider's source address,
@@ -191,7 +203,7 @@ To allow using Terraform providers in these situations, there are some
alternative options for making provider plugins available to Terraform which
we'll describe in the following sections.
-### Explicit Installation Method Configuration
+### Configure explicit installation method
A `provider_installation` block in the CLI configuration allows overriding
Terraform's default installation behaviors, so you can force Terraform to use
@@ -274,11 +286,15 @@ The following are the two supported installation method types:
which is designed to be relatively easy to implement using typical static
website hosting mechanisms.
-~> **Warning:** Don't configure `network_mirror` URLs that you do not trust.
+
+
+Don't configure `network_mirror` URLs that you do not trust.
Provider mirror servers are subject to TLS certificate checks to verify
identity, but a network mirror with a TLS certificate can potentially serve
modified copies of upstream providers with malicious content.
+
+
Terraform will try all of the specified methods whose include and exclude
patterns match a given provider, and select the newest version available across
all of those methods that matches the version constraint given in each
@@ -287,7 +303,7 @@ and intend Terraform to use that local mirror exclusively, you must either
remove the `direct` installation method altogether or use its `exclude`
argument to disable its use for specific providers.
-### Implied Local Mirror Directories
+### Implied local mirror directories
If your CLI configuration does not include a `provider_installation` block at
all, Terraform produces an _implied_ configuration. The implied configuration
@@ -326,7 +342,7 @@ automatically exclude all of those providers from the implied `direct` block.
if you use explicit `provider_installation` you will need to write the intended
exclusions out yourself.)
-### Provider Plugin Cache
+### Provider plugin cache
By default, `terraform init` downloads plugins into a subdirectory of the
working directory so that each working directory is self-contained. As a
@@ -358,8 +374,8 @@ persistent setting. Alternatively, the `TF_PLUGIN_CACHE_DIR` environment
variable can be used to enable caching or to override an existing cache
directory within a particular shell session:
-```bash
-export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
+```shell-session
+$ export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
```
When a plugin cache directory is enabled, the `terraform init` command will
@@ -383,16 +399,24 @@ Terraform will never itself delete a plugin from the plugin cache once it has
been placed there. Over time, as plugins are upgraded, the cache directory may
grow to contain several unused versions which you must delete manually.
--> **Note:** The plugin cache directory is not guaranteed to be concurrency
+
+
+The plugin cache directory is not guaranteed to be concurrency
safe. The provider installer's behavior in environments with multiple `terraform
init` calls is undefined.
+
+
### Allowing the Provider Plugin Cache to break the dependency lock file
-~> **Note:** The option described in is for unusual and exceptional situations
+
+
+The option described in is for unusual and exceptional situations
only. Do not set this option unless you are sure you need it and you fully
understand the consequences of enabling it.
+
+
By default Terraform will use packages from the global cache directory only
if they match at least one of the checksums recorded in the
[dependency lock file](/terraform/language/files/dependency-lock)
@@ -431,19 +455,27 @@ will always install a provider from upstream the first time you use it with
a particular configuration, but can then re-use the cache entry on later runs
once the dependency lock file records valid checksums for the provider package.
-~> **Note:** The Terraform team intends to improve the dependency lock file
+
+
+The Terraform team intends to improve the dependency lock file
mechanism in future versions so that it will be usable in more situations. At
that time this option will become silently ignored. If your workflow relies on
the use of this option, please open a GitHub issue to share details about your
situation so that we can consider how to support it without breaking the
dependency lock file.
-### Development Overrides for Provider Developers
+
+
+### Development overrides for provider developers
--> **Note:** Development overrides work only in Terraform v0.14 and later.
+
+
+Development overrides work only in Terraform v0.14 and later.
Using a `dev_overrides` block in your CLI configuration will cause Terraform
v0.13 to reject the configuration as invalid.
+
+
Normally Terraform verifies version selections and checksums for providers
in order to help ensure that all operations are made with the intended version
of a provider, and that authors can gradually upgrade to newer provider versions
@@ -502,8 +534,8 @@ directory, perhaps called `dev.tfrc` for the sake of example, and then use the
`TF_CLI_CONFIG_FILE` environment variable to instruct Terraform to use that
localized CLI configuration instead of the default one:
-```
-export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc
+```shell-session
+$ export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc
```
Development overrides are not intended for general use as a way to have
@@ -521,7 +553,7 @@ in future Terraform releases, including possible breaking changes. We therefore
recommend using development overrides only temporarily during provider
development work.
-## Removed Settings
+## Removed settings
The following settings are supported in Terraform 0.12 and earlier but are
no longer recommended for use:
diff --git a/website/docs/cli/config/environment-variables.mdx b/website/docs/cli/config/environment-variables.mdx
index d08bf2d1ca51..52bcc8d59855 100644
--- a/website/docs/cli/config/environment-variables.mdx
+++ b/website/docs/cli/config/environment-variables.mdx
@@ -1,11 +1,11 @@
---
-page_title: Environment Variables
+page_title: Environment variables
description: >-
Learn to use environment variables to change Terraform's default behavior.
Configure log content and output, set variables, and more.
---
-# Environment Variables
+# Environment variables
Terraform refers to a number of environment variables to customize various
aspects of its behavior. None of these environment variables are required
@@ -17,14 +17,14 @@ for debugging.
Enables detailed logs to appear on stderr which is useful for debugging. For example:
-```shell
-export TF_LOG=trace
+```shell-session
+$ export TF_LOG=trace
```
To disable, either unset it, or set it to `off`. For example:
-```shell
-export TF_LOG=off
+```shell-session
+$ export TF_LOG=off
```
For more on debugging Terraform, check out the section on [Debugging](/terraform/internals/debugging).
@@ -33,8 +33,8 @@ For more on debugging Terraform, check out the section on [Debugging](/terraform
This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running terraform from:
-```shell
-export TF_LOG_PATH=./terraform.log
+```shell-session
+$ export TF_LOG_PATH=./terraform.log
```
For more on debugging Terraform, check out the section on [Debugging](/terraform/internals/debugging).
@@ -43,19 +43,19 @@ For more on debugging Terraform, check out the section on [Debugging](/terraform
If set to "false" or "0", causes terraform commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example:
-```shell
-export TF_INPUT=0
+```shell-session
+$ export TF_INPUT=0
```
## TF_VAR_name
Environment variables can be used to set variables. The environment variables must be in the format `TF_VAR_name` and this will be checked last for a value. For example:
-```shell
-export TF_VAR_region=us-west-1
-export TF_VAR_ami=ami-049d8641
-export TF_VAR_alist='[1,2,3]'
-export TF_VAR_amap='{ foo = "bar", baz = "qux" }'
+```shell-session
+$ export TF_VAR_region=us-west-1 && \
+ export TF_VAR_ami=ami-049d8641 && \
+ export TF_VAR_alist='[1,2,3]' && \
+ 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](/terraform/language/values/variables).
@@ -108,8 +108,8 @@ For multi-environment deployment, in order to select a workspace, instead of doi
For example:
-```shell
-export TF_WORKSPACE=your_workspace
+```shell-session
+$ 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.
@@ -127,7 +127,7 @@ applications.
This is a purely cosmetic change to Terraform's human-readable output, and the
exact output differences can change between minor Terraform versions.
-For more details, see [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS).
+For more details, refer to [Running Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS).
## TF_REGISTRY_DISCOVERY_RETRY
@@ -139,24 +139,24 @@ the remote registry client will attempt for client connection errors or
The default client timeout for requests to the remote registry is 10s. `TF_REGISTRY_CLIENT_TIMEOUT` can be configured and increased during exceptional circumstances.
-```shell
-export TF_REGISTRY_CLIENT_TIMEOUT=15
+```shell-session
+$ export TF_REGISTRY_CLIENT_TIMEOUT=15
```
## TF_STATE_PERSIST_INTERVAL
The interval in seconds that Terraform attempts to persist state to a remote backend during an apply operation. The default minimum interval for all remote backends is 20 seconds. Backends may override the default minimum value. If the value of `TF_STATE_PERSIST_INTERVAL` is lower than the default interval specified by a remote backend, the default interval will be used.
-```shell
-export TF_STATE_PERSIST_INTERVAL=100
+```shell-session
+$ export TF_STATE_PERSIST_INTERVAL=100
```
## TF_CLI_CONFIG_FILE
The location of the [Terraform CLI configuration file](/terraform/cli/config/config-file).
-```shell
-export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-custom"
+```shell-session
+$ export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-custom"
```
Note that `TERRAFORM_CONFIG` is a deprecated alias for the `TF_CLI_CONFIG_FILE` variable. We recommend using `TF_CLI_CONFIG_FILE` instead of the deprecated `TERRAFORM_CONFIG` variable.
@@ -171,4 +171,4 @@ You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [t
The CLI integration with HCP Terraform lets you use HCP Terraform and Terraform Enterprise on the command line. The integration requires including a `cloud` block in your Terraform configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI).
-Refer to [HCP Terraform Settings](/terraform/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables.
+Refer to [HCP Terraform settings](/terraform/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables.
diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.mdx
index 77022d1335ae..7fb757e2b0da 100644
--- a/website/docs/cli/config/index.mdx
+++ b/website/docs/cli/config/index.mdx
@@ -1,11 +1,11 @@
---
-page_title: CLI Configuration - Terraform CLI
+page_title: Configure CLI - Terraform CLI
description: >-
Find documentation about the CLI config file and customizing Terraform
environment variables.
---
-# CLI Configuration
+# Configure CLI
Terraform CLI can be configured with some global settings, which are separate
from any Terraform configuration and which apply across all working directories.
diff --git a/website/docs/cli/import/importability.mdx b/website/docs/cli/import/importability.mdx
index fdc3fe91c059..d736305938f1 100644
--- a/website/docs/cli/import/importability.mdx
+++ b/website/docs/cli/import/importability.mdx
@@ -5,7 +5,7 @@ description: |-
importable. As a result, you cannot import all Terraform resources.
---
-# Resource Importability
+# Resource importability
Each resource in Terraform must implement some basic logic to become
importable. As a result, you cannot import all Terraform resources.
@@ -13,4 +13,4 @@ importable. As a result, you cannot import all Terraform resources.
The resources that you can import are documented at the bottom of
each resource documentation page in the [Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository.
-To make a resource importable, refer to [Extending Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import).
+To make a resource importable, refer to [Extending Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import).
diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx
index 68eba8ed4c8e..0b4cba338b7f 100644
--- a/website/docs/cli/import/index.mdx
+++ b/website/docs/cli/import/index.mdx
@@ -11,11 +11,19 @@ description: >-
Terraform can import existing infrastructure resources. This functionality lets you bring existing resources under Terraform management.
--> **Note:** Terraform v1.5.0 and later supports `import` blocks. Unlike the `terraform import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/terraform/language/import).
+
+
+Terraform v1.5.0 and later supports `import` blocks. Unlike the `terraform import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/terraform/language/import).
+
+
## State Only
-~> **Warning:** Terraform expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. See [State](/terraform/language/state) for more details.
+
+
+Terraform expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. See [State](/terraform/language/state) for more details.
+
+
The `terraform import` CLI command can only import resources into the [state](/terraform/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/terraform/language/import).
diff --git a/website/docs/cli/import/usage.mdx b/website/docs/cli/import/usage.mdx
index 9e2ced76ae62..1d314c130b6c 100644
--- a/website/docs/cli/import/usage.mdx
+++ b/website/docs/cli/import/usage.mdx
@@ -3,23 +3,26 @@ page_title: 'Import: Usage'
description: The `terraform import` command is used to import existing infrastructure.
---
-# Import Usage
+# Import usage
> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
-
Use the `terraform import` command to import existing infrastructure to Terraform state.
The `terraform import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC.
-~> Warning: Terraform expects that each remote object it is managing will be
+
+
+Terraform expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by Terraform
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.
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, refer to
[the State section](/terraform/language/state).
+
+
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:
@@ -40,7 +43,7 @@ return to fill it in once the instance is imported.
Now `terraform import` can be run to attach an existing instance to this
resource configuration:
-```shell
+```shell-session
$ terraform import aws_instance.example i-abcd1234
```
@@ -65,7 +68,7 @@ You can now run `terraform plan` to see how the configuration compares to
the imported resource, and make any adjustments to the configuration to
align with the current (or desired) state of the imported object.
-## Complex Imports
+## Complex imports
The above import is considered a "simple import": one resource is imported
into the state file. An import may also result in a "complex import" where
diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.mdx
index 2e26fe971019..37b4e0ee1518 100644
--- a/website/docs/cli/index.mdx
+++ b/website/docs/cli/index.mdx
@@ -5,7 +5,7 @@ description: >-
with HCP Terraform or Terraform Enterprise.
---
-# Terraform CLI Documentation
+# Terraform CLI documentation
> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials.
diff --git a/website/docs/cli/init/index.mdx b/website/docs/cli/init/index.mdx
index 5b763eb9dad4..809abc105711 100644
--- a/website/docs/cli/init/index.mdx
+++ b/website/docs/cli/init/index.mdx
@@ -1,12 +1,12 @@
---
-page_title: Initializing Working Directories - Terraform CLI
+page_title: Initialize working directories - Terraform CLI
description: >-
Working directories contain configurations, settings, cached plugins and
modules, and state data. Learn how to initialize and manage working
directories.
---
-# Initializing Working Directories
+# Initialize working directories
Terraform expects to be invoked from a working directory that contains
configuration files written in
@@ -17,7 +17,7 @@ settings, cached plugins and modules, and sometimes state data.
A working directory must be initialized before Terraform can perform any
operations in it (like provisioning infrastructure or modifying state).
-## Working Directory Contents
+## Working directory contents
A Terraform working directory typically contains:
@@ -66,7 +66,7 @@ effect if no changes are required.
If reinitialization is required, any commands that rely on initialization will
fail with an error and tell you so.
-## Reinitializing Only Modules
+## Reinitializing only modules
The `terraform get` command will download modules referenced in the
configuration, but will not perform the other required initialization tasks.
diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx
index 113594c58a5c..c55694fe183b 100644
--- a/website/docs/cli/inspect/index.mdx
+++ b/website/docs/cli/inspect/index.mdx
@@ -1,11 +1,11 @@
---
-page_title: Inspecting Infrastructure - Terraform CLI
+page_title: Inspect resources - Terraform CLI
description: >-
Learn commands to inspect dependency information, outputs, etc. Use them for
integration or to understand your infrastructure.
---
-# Inspecting Infrastructure
+# Inspect resources
Terraform configurations and state data include some highly structured
information about the resources they manage; this includes dependency
diff --git a/website/docs/cli/install/apt.mdx b/website/docs/cli/install/apt.mdx
index e8ca55f43189..eb05311eeaeb 100644
--- a/website/docs/cli/install/apt.mdx
+++ b/website/docs/cli/install/apt.mdx
@@ -1,11 +1,11 @@
---
-page_title: APT Packages for Debian and Ubuntu
+page_title: APT packages for Debian and Ubuntu
description: >-
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
The primary distribution packages for Terraform are `.zip` archives containing
single executable files that you can extract anywhere on your system. However,
@@ -17,7 +17,9 @@ Debian and Ubuntu systems, which allow you to install Terraform using the
If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you
might prefer to [install Terraform from our Yum repositories](/terraform/cli/install/yum).
--> **Note:** The APT repositories discussed on this page are generic HashiCorp
+
+
+The APT repositories discussed on this page are generic HashiCorp
repositories that contain packages for a variety of different HashiCorp
products, rather than just Terraform. Adding these repositories to your
system will, by default, therefore make several other non-Terraform
@@ -25,11 +27,13 @@ packages available for installation. That might then mask some packages that
are available for some HashiCorp products in the main Debian and Ubuntu
package repositories.
-## Repository Configuration
+
+
+## Repository configuration
Please follow the instructions in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide).
-## Supported Architectures
+## Supported architectures
The HashiCorp APT server has packages only for the `amd64`
architecture, which is also sometimes known as `x86_64`.
@@ -38,12 +42,12 @@ There are no official packages available for other architectures, such as
`arm64`. If you wish to use Terraform on a non-`amd64` system,
[download a normal release `.zip` file](/terraform/downloads) instead.
-## Supported Debian and Ubuntu Releases
+## Supported Debian and Ubuntu releases
The HashiCorp APT server contains release repositories for a variety of
supported distributions, which are outlined in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide).
-## Installing a Specific Version of Terraform
+## Install a specific version of Terraform
The HashiCorp APT repositories contain multiple versions of Terraform, but
because the packages are all named `terraform` it is impossible to install
@@ -54,8 +58,8 @@ It's often necessary to match your Terraform version with what a particular
configuration is currently expecting. You can use the following command to
see which versions are currently available in the repository index:
-```bash
-apt policy terraform
+```shell-session
+$ apt policy terraform
```
If your workflow requires using multiple versions of Terraform at the same
@@ -65,7 +69,7 @@ official release `.zip` files instead of the APT packages, so you can install
multiple versions at once and then select which to use for each command you
run.
-### Terraform 1.4.3 and Later
+### Terraform 1.4.3 and later
As of Terraform 1.4.3, all published packages include a revision number by
default, starting with `-1`. This change means that in the case that we need
@@ -76,15 +80,15 @@ in [the announcement](https://discuss.hashicorp.com/t/linux-packaging-debian-rev
You can install the latest revision for a particular version by including the
version in the `apt install` command, as follows:
-```bash
-sudo apt install terraform=1.4.4-*
+```shell-session
+$ sudo apt install terraform=1.4.4-*
```
-### Terraform 1.4.2 and Earlier
+### Terraform 1.4.2 and earlier
Terraform 1.4.2 and earlier did not include a revision number for the first
revision, so you can use the following pattern to install a specific version:
-```bash
-sudo apt install terraform=1.4.0
+```shell-session
+$ sudo apt install terraform=1.4.0
```
diff --git a/website/docs/cli/install/yum.mdx b/website/docs/cli/install/yum.mdx
index b6b4b809705d..3243bcd7761b 100644
--- a/website/docs/cli/install/yum.mdx
+++ b/website/docs/cli/install/yum.mdx
@@ -5,7 +5,7 @@ description: >-
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
The primary distribution packages for Terraform are `.zip` archives containing
single executable files that you can extract anywhere on your system. However,
@@ -17,14 +17,18 @@ install Terraform using the `yum install` or `dnf install` commands.
If you are instead using Debian or Ubuntu, you
might prefer to [install Terraform from our APT repositories](/terraform/cli/install/apt).
--> **Note:** The Yum repositories discussed on this page are generic HashiCorp
+
+
+The Yum repositories discussed on this page are generic HashiCorp
repositories that contain packages for a variety of different HashiCorp
products, rather than just Terraform. Adding these repositories to your
system will, by default, therefore make a number of other non-Terraform
packages available for installation. That might then mask the packages that are
available for some HashiCorp products in the main distribution repositories.
-## Repository Configuration
+
+
+## Repository configuration
Before adding a repository you must determine which distribution you are using.
The following command lines refer to a placeholder variable `$release` which
@@ -37,26 +41,26 @@ you must replace with the appropriate value from the following list:
If you are using a Yum-based distribution, add the repository using
`yum-config-manager` as follows:
-```bash
-sudo yum install -y yum-utils
-sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo
+```shell-session
+$ sudo yum install -y yum-utils && \
+ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo
```
If you are using a DNF-based distribution, add the repository using
`dnf config-manager` as follows:
-```bash
-sudo dnf install -y dnf-plugins-core
-sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo
+```shell-session
+$ sudo dnf install -y dnf-plugins-core && \
+ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo
```
In both cases, the Terraform package name is `terraform`. For example:
-```bash
-yum install terraform
+```shell-session
+$ yum install terraform
```
-## Supported Architectures
+## Supported architectures
The HashiCorp Yum/DNF server has packages only for the `x86_64`
architecture, which is also sometimes known as `amd64`.
@@ -65,7 +69,7 @@ There are no official packages available for other architectures, such as
`aarch64`. If you wish to use Terraform on a non-`x86_64` system,
[download a normal release `.zip` file](/terraform/downloads) instead.
-## Supported Distribution Releases
+## Supported distribution releases
The HashiCorp Yum server contains release repositories for the
following distribution releases:
@@ -88,26 +92,25 @@ Over time we will change the set of supported distributions, including both
adding support for new releases and ceasing to publish new Terraform versions
under older releases.
-## Choosing Terraform Versions
+## Choose Terraform versions
The HashiCorp Yum repositories contain multiple versions of Terraform, but
because the packages are all named `terraform` it is impossible to install
more than one version at a time, and `yum install` or `dnf install` will
default to selecting the latest version.
-It's often necessary to match your Terraform version with what a particular
-configuration is currently expecting. Use the following command to
-retrieve the available versions in the repository index:
+You may need to match your Terraform version to what the configuration is expecting.
+Use the following command to retrieve the available versions in the repository index:
-```bash
-yum --showduplicate list terraform
+```shell-session
+$ yum --showduplicate list terraform
```
You can select a specific version to install by including it in the
`yum install` command line, as follows:
-```bash
-yum install terraform-0.14.0-2.x86_64
+```shell-session
+$ yum install terraform-0.14.0-2.x86_64
```
If you are using a DNF-based distribution, similar use `dnf` instead of `yum`
diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.mdx
index 67f6db2fb4b5..5e4bb8f47cd1 100644
--- a/website/docs/cli/plugins/index.mdx
+++ b/website/docs/cli/plugins/index.mdx
@@ -1,20 +1,24 @@
---
-page_title: Managing Plugins - Terraform CLI
+page_title: Managing providers - Terraform CLI
description: >-
Commands to install, configure, and show information about providers. Also
commands to reduce install effort in air-gapped environments.
---
-# Managing Plugins
+# Manage providers
Terraform relies on plugins called providers to manage various types
of resources. For more information about providers, refer to
[Providers](/terraform/language/providers) in the Terraform
language docs.
--> **Note:** Providers are the only plugin type most Terraform users interact with. Terraform also supports third-party provisioner plugins, but
+
+
+Providers are the only plugin type most Terraform users interact with. Terraform also supports third-party provisioner plugins, but
we discourage their use.
+
+
Terraform installs any providers
[required](/terraform/language/providers/requirements) by a configuration
when [initializing](/terraform/cli/init) a working directory. By default,
@@ -27,13 +31,13 @@ networked source. Terraform also includes some commands to show information
about providers and to reduce the effort of installing providers in air-gapped
environments.
-## Configuring Plugin Installation
+## Configure plugin installation
Terraform's configuration file includes options for caching downloaded plugins,
or explicitly specifying a local or HTTPS mirror to install plugins from. For
more information, see [CLI Config File](/terraform/cli/config/config-file).
-## Getting Plugin Information
+## Get plugin information
Use the [`terraform providers`](/terraform/cli/commands/providers) command to get information
about the providers required by the current working directory's configuration.
@@ -46,7 +50,7 @@ Use the [`terraform providers schema`](/terraform/cli/commands/providers/schema)
get machine-readable information about the resources and configuration options
offered by each provider.
-## Managing Plugin Installation
+## Manage plugin installation
Use the [`terraform providers mirror`](/terraform/cli/commands/providers/mirror) command to
download local copies of every provider required by the current working
diff --git a/website/docs/cli/plugins/signing.mdx b/website/docs/cli/plugins/signing.mdx
index 7eac2efd3020..f2e69670f33a 100644
--- a/website/docs/cli/plugins/signing.mdx
+++ b/website/docs/cli/plugins/signing.mdx
@@ -1,5 +1,5 @@
---
-page_title: Plugin Signing
+page_title: Plugin signing
description: >-
Learn about the types of signatures providers can have on the Terraform
Registry.
@@ -7,9 +7,13 @@ description: >-
-# Plugin Signing
+# Plugin signing
-~> **Note** Terraform only authenticates provider plugins fetched from a registry.
+
+
+Terraform only authenticates provider plugins fetched from a registry.
+
+
Terraform providers installed from the Registry are cryptographically signed, and the signature is verified at time of installation. There are three types of provider signatures, each with different trust implications:
diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx
index 3fc3538f98d5..e2b623cebcc0 100644
--- a/website/docs/cli/run/index.mdx
+++ b/website/docs/cli/run/index.mdx
@@ -1,9 +1,9 @@
---
-page_title: Provisioning Infrastructure - Terraform CLI
+page_title: Provision resources - Terraform CLI
description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.'
---
-# Provisioning Infrastructure with Terraform
+# Provision resources with Terraform
Terraform's primary function is to create, modify, and destroy infrastructure
resources to match the desired state described in a
@@ -19,7 +19,7 @@ Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and
[initialized](/terraform/cli/init) working directory, and all of them act
only upon the currently selected [workspace](/terraform/cli/workspaces).
-## Planning
+## Plan
The `terraform plan` command evaluates a Terraform configuration to determine
the desired state of all the resources it declares, then compares that desired
@@ -40,7 +40,7 @@ exact changes.
For details, see [the `terraform plan` command](/terraform/cli/commands/plan).
-## Applying
+## Apply
The `terraform apply` command performs a plan just like `terraform plan` does,
but then actually carries out the planned changes to each resource using the
@@ -56,7 +56,7 @@ infrastructure has changed in the minutes since the original plan was created.
For details, see [the `terraform apply` command](/terraform/cli/commands/apply).
-## Destroying
+## Destroy
The `terraform destroy` command destroys all of the resources being managed by
the current working directory and workspace, using state data to determine which
diff --git a/website/docs/cli/state/index.mdx b/website/docs/cli/state/index.mdx
index b5d39bd52832..31f8425d695b 100644
--- a/website/docs/cli/state/index.mdx
+++ b/website/docs/cli/state/index.mdx
@@ -1,11 +1,11 @@
---
-page_title: Manipulating State - Terraform CLI
+page_title: Manipulate state - Terraform CLI
description: >-
State data tracks which real-world object corresponds to each resource.
Inspect state, move or import resources, and more.
---
-# Manipulating Terraform State
+# Manipulate Terraform state
> **Hands-on:** Try the [Manage Resources in Terraform State](/terraform/tutorials/state/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
@@ -21,12 +21,12 @@ infrastructure.
Terraform CLI supports several workflows for interacting with state:
-- [Inspecting State](/terraform/cli/state/inspect)
-- [Forcing Re-creation](/terraform/cli/state/taint)
-- [Moving Resources](/terraform/cli/state/move)
-- Importing Pre-existing Resources (documented in the
- [Importing Infrastructure](/terraform/cli/import) section)
-- [Disaster Recovery](/terraform/cli/state/recover)
+- [Inspect state](/terraform/cli/state/inspect)
+- [Forcing re-creation](/terraform/cli/state/taint)
+- [Move resources](/terraform/cli/state/move)
+- Import pre-existing resources (documented in the
+ [Import resources](/terraform/cli/import) section)
+- [Disaster recovery](/terraform/cli/state/recover)
~> **Important:** Modifying state data outside a normal plan or apply can cause
Terraform to lose track of managed resources, which might waste money, annoy
diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.mdx
index 439a0646f836..ccfb2b13a188 100644
--- a/website/docs/cli/state/inspect.mdx
+++ b/website/docs/cli/state/inspect.mdx
@@ -1,9 +1,9 @@
---
-page_title: Inspecting State - Terraform CLI
+page_title: Inspect state - Terraform CLI
description: Commands that allow you to read and update state.
---
-# Inspecting State
+# Inspect state
Terraform includes some commands for reading and updating state without taking
any other actions.
diff --git a/website/docs/cli/state/move.mdx b/website/docs/cli/state/move.mdx
index 326cd9f8fc20..b979e7abba2b 100644
--- a/website/docs/cli/state/move.mdx
+++ b/website/docs/cli/state/move.mdx
@@ -1,11 +1,11 @@
---
-page_title: Moving Resources - Terraform CLI
+page_title: Move resources - Terraform CLI
description: >-
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
+# Move resources
Terraform's state associates each real-world object with a configured resource
at a specific [resource address](/terraform/cli/state/resource-addressing). This
diff --git a/website/docs/cli/state/recover.mdx b/website/docs/cli/state/recover.mdx
index 07675491c033..b69702065ef6 100644
--- a/website/docs/cli/state/recover.mdx
+++ b/website/docs/cli/state/recover.mdx
@@ -1,11 +1,11 @@
---
-page_title: Recovering from State Disasters - Terraform CLI
+page_title: Recover from state disasters - Terraform CLI
description: >-
Learn how to restore state backups and override Terraform state protections to fix state errors with the Terraform CLI.
---
-# Recovering from State Disasters
+# Recover from state disasters
If something has gone horribly wrong (possibly due to accidents when performing
other state manipulation actions), you might need to take drastic actions with
diff --git a/website/docs/cli/state/resource-addressing.mdx b/website/docs/cli/state/resource-addressing.mdx
index 788b1a497617..cc5b1de2fdfe 100644
--- a/website/docs/cli/state/resource-addressing.mdx
+++ b/website/docs/cli/state/resource-addressing.mdx
@@ -5,14 +5,14 @@ description: |-
instances in your overall configuration.
---
-# Resource Addressing
+# Resource addressing
A _resource address_ is a string that identifies zero or more resource
instances in your overall configuration.
An address is made up of two parts:
-```
+```text hideClipboard
[module path][resource spec]
```
@@ -26,7 +26,7 @@ are using which parses resource addresses.
A module path addresses a module within the tree of modules. It takes the form:
-```
+```text hideClipboard
module.module_name[module index]
```
@@ -46,11 +46,11 @@ If the module path is omitted, the address applies to the root module.
An example of the `module` keyword delineating between two modules that have multiple instances:
-```
+```text hideClipboard
module.foo[0].module.bar["a"]
```
--> Module index only applies to modules in Terraform v0.13 or later. In earlier
+Module index only applies to modules in Terraform v0.13 or later. In earlier
versions of Terraform, a module could not have multiple instances.
## Resource spec
@@ -58,7 +58,7 @@ versions of Terraform, a module could not have multiple instances.
A resource spec addresses a specific resource instance in the selected module.
It has the following syntax:
-```
+```text hideClipboard
resource_type.resource_name[instance index]
```
@@ -86,7 +86,7 @@ The following specifications apply to index values on modules and resources with
## Examples
-### count Example
+### count example
Given a Terraform config that includes:
@@ -99,13 +99,13 @@ resource "aws_instance" "web" {
An address like this:
-```
+```text hideClipboard
aws_instance.web[3]
```
Refers to only the last instance in the config, and an address like this:
-```
+```text hideClipboard
aws_instance.web
```
@@ -129,7 +129,7 @@ resource "aws_instance" "web" {
An address like this:
-```
+```text hideClipboard
aws_instance.web["example"]
```
diff --git a/website/docs/cli/state/taint.mdx b/website/docs/cli/state/taint.mdx
index dbf1229b9876..e4ef077e1b1d 100644
--- a/website/docs/cli/state/taint.mdx
+++ b/website/docs/cli/state/taint.mdx
@@ -1,9 +1,9 @@
---
-page_title: Forcing Re-creation of Resources - Terraform CLI
+page_title: Force re-creation of resources - Terraform CLI
description: Commands that allow you to destroy and re-create resources manually.
---
-# Forcing Re-creation of Resources
+# Force re-creation of resources (taint)
During planning, by default Terraform retrieves the latest state of each
existing object and compares it with the current configuration, planning
@@ -21,7 +21,7 @@ replace it for any other reason, you can override Terraform's default behavior
using [the `-replace=...` planning option](/terraform/cli/commands/plan#replace-address)
when you run either `terraform plan` or `terraform apply`:
-```shellsession
+```shell-session
$ terraform apply -replace="aws_instance.example"
# ...
@@ -44,7 +44,7 @@ Terraform represents this situation by marking an object in the state as
replacing that object in a similar way to if you had specified that object's
address using `-replace=...` as described above.
-```
+```text hideClipboard
# aws_instance.example is tainted, so must be replaced
-/+ resource "aws_instance" "example" {
# ...
diff --git a/website/docs/cli/test/index.mdx b/website/docs/cli/test/index.mdx
index 19a874aba0a5..03127a09f39a 100644
--- a/website/docs/cli/test/index.mdx
+++ b/website/docs/cli/test/index.mdx
@@ -1,18 +1,18 @@
---
-page_title: Testing Terraform - Terraform CLI
+page_title: Test Terraform configuration - Terraform CLI
description: >-
Write structured tests and validations for your configuration to ensure
correctness in your infrastructure.
---
-# Testing Terraform
+# Test Terraform configuration
Terraform provides numerous testing capabilities to validate your infrastructure.
These testing capabilities fit into two main categories:
-1. Validating your configuration and infrastructure as part of your regular Terraform operations.
-2. Performing traditional unit and integration testing on your configuration.
+1. Validate your configuration and infrastructure as part of your regular Terraform operations.
+2. Perform traditional unit and integration testing on your configuration.
Refer to [Custom Conditions](/terraform/language/expressions/custom-conditions) and [Checks](/terraform/language/checks) to learn more about the first testing capability. Terraform's [`test`](/terraform/cli/commands/test) command provides the second capability.
@@ -49,7 +49,7 @@ Validations allow you to verify aspects of your configuration and infrastructure
The Terraform `test` command also executes any validations within your configuration as part of the tests it executes. For more information on the available validation, refer to [Checks](/terraform/language/checks) and [Custom Conditions](/terraform/language/expressions/custom-conditions).
-## Tests or Validations
+## Tests or validations
You can write many validations as test assertions, but there are specific use cases for both.
diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx
index d77d60e34b67..2fb769616445 100644
--- a/website/docs/cli/workspaces/index.mdx
+++ b/website/docs/cli/workspaces/index.mdx
@@ -1,11 +1,11 @@
---
-page_title: Managing Workspaces - Terraform CLI
+page_title: Manage workspaces - Terraform CLI
description: >-
Commands to list, select, create, and output workspaces. Workspaces help
manage different groups of resources with one configuration.
---
-# Managing Workspaces
+# Manage workspaces
Workspaces in the Terraform CLI refer to separate instances of [state data](/terraform/language/state) inside the same Terraform working directory. They are distinctly different from [workspaces in HCP Terraform](/terraform/cloud-docs/workspaces), which each have their own Terraform configuration and function as separate working directories.
@@ -13,8 +13,7 @@ Terraform relies on state to associate resources with real-world objects. When y
Workspaces can be helpful for specific [use cases](#use-cases), but they are not required to use the Terraform CLI. We recommend using [alternative approaches](#alternatives-to-workspaces) for complex deployments requiring separate credentials and access controls.
-
-## Managing CLI Workspaces
+## Manage CLI workspaces
Every [initialized working directory](/terraform/cli/init) starts with one workspace named `default`.
@@ -24,8 +23,7 @@ Use [the `terraform workspace select` command](/terraform/cli/commands/workspace
When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/terraform/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region.
-
-## Use Cases
+## Use cases
You can create multiple [working directories](/terraform/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, Terraform installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches.
@@ -35,8 +33,7 @@ a set of infrastructure to test a set of changes before modifying production inf
Non-default workspaces are often related to feature branches in version control.
The default workspace might correspond to the `main` or `trunk` branch, which describes the intended state of production infrastructure. When a developer creates a feature branch for a change, they might also create a corresponding workspace and deploy into it a temporary copy of the main infrastructure. They can then test changes on the copy without affecting the production infrastructure. Once the change is merged and deployed to the default workspace, they destroy the test infrastructure and delete the temporary workspace.
-
-### When Not to Use Multiple Workspaces
+### When not to use multiple workspaces
Workspaces let you quickly switch between multiple instances of a **single configuration** within its **single backend**. They are not designed to solve all problems.
@@ -46,7 +43,7 @@ In particular, organizations commonly want to create a strong separation
between multiple deployments of the same infrastructure serving different
development stages or different internal teams. In this case, the backend for each deployment often has different credentials and access controls. CLI workspaces within a working directory use the same backend, so they are not a suitable isolation mechanism for this scenario.
-## Alternatives to Workspaces
+## Alternatives to workspaces
Instead of creating CLI workspaces, you can use one or more [re-usable modules](/terraform/language/modules/develop) to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different [backend](/terraform/language/settings/backends/configuration). The root module of each configuration consists only of a backend configuration and a small number of `module` blocks with arguments describing any small differences between the deployments.
@@ -61,7 +58,7 @@ When multiple configurations represent distinct system components rather than mu
- If you store a Terraform state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/terraform/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system.
-## Interactions with HCP Terraform Workspaces
+## Interactions with HCP Terraform workspaces
HCP Terraform organizes infrastructure using workspaces, but its workspaces
act more like completely separate working directories. Each HCP Terraform