diff --git a/website/data/cli-nav-data.json b/website/data/cli-nav-data.json index 439a5c9896a8..2bae97955caf 100644 --- a/website/data/cli-nav-data.json +++ b/website/data/cli-nav-data.json @@ -33,15 +33,7 @@ { "title": "Overview", "path": "code" }, { "title": "console", "href": "/cli/commands/console" }, { "title": "fmt", "href": "/cli/commands/fmt" }, - { "title": "validate", "href": "/cli/commands/validate" }, - { - "title": "0.13upgrade", - "href": "/cli/commands/0.13upgrade" - }, - { - "title": "0.12upgrade", - "href": "/cli/commands/0.12upgrade" - } + { "title": "validate", "href": "/cli/commands/validate" } ] }, { @@ -62,22 +54,18 @@ ] }, { - "title": "Importing Infrastructure", + "title": "Import Infrastructure", "routes": [ { "title": "Overview", "path": "import" }, + { "title": "Import existing resources", "path": "import/usage" }, { - "title": "import", + "title": "Reference", "href": "/cli/commands/import" - }, - { "title": "Usage Tips", "path": "import/usage" }, - { - "title": "Resource Importability", - "path": "import/importability" } ] }, { - "title": "Manipulating State", + "title": "Manually Update State", "routes": [ { "title": "Overview", "path": "state" }, { @@ -266,7 +254,6 @@ { "title": "apply", "href": "/cli/commands/apply" }, { "title": "console", "href": "/cli/commands/console" }, { "title": "destroy", "href": "/cli/commands/destroy" }, - { "title": "env", "href": "/cli/commands/env" }, { "title": "fmt", "href": "/cli/commands/fmt" }, { "title": "force-unlock", @@ -294,10 +281,6 @@ "title": "providers schema", "href": "/cli/commands/providers/schema" }, - { - "title": "push (deprecated)", - "href": "/cli/commands/push" - }, { "title": "refresh", "href": "/cli/commands/refresh" }, { "title": "show", "href": "/cli/commands/show" }, { "title": "state", "href": "/cli/commands/state" }, @@ -350,11 +333,11 @@ "href": "/cli/commands/workspace/show" }, { - "title": "0.12upgrade", + "title": "0.12upgrade", "href": "/cli/commands/0.12upgrade" }, { - "title": "0.13upgrade", + "title": "0.13upgrade", "href": "/cli/commands/0.13upgrade" } ] @@ -367,7 +350,6 @@ { "title": "apply", "path": "commands/apply" }, { "title": "console", "path": "commands/console" }, { "title": "destroy", "path": "commands/destroy" }, - { "title": "env", "path": "commands/env" }, { "title": "fmt", "path": "commands/fmt" }, { "title": "force-unlock", "path": "commands/force-unlock" }, { "title": "get", "path": "commands/get" }, @@ -388,7 +370,6 @@ { "title": "providers schema", "path": "commands/providers/schema" } ] }, - { "title": "push (deprecated)", "path": "commands/push" }, { "title": "refresh", "path": "commands/refresh" }, { "title": "show", "path": "commands/show" }, { @@ -426,8 +407,14 @@ { "title": "workspace show", "path": "commands/workspace/show" } ] }, - { "title": "0.12upgrade", "path": "commands/0.12upgrade" }, - { "title": "0.13upgrade", "path": "commands/0.13upgrade" } + { + "title": "0.12upgrade", + "path": "commands/0.12upgrade" + }, + { + "title": "0.13upgrade", + "path": "commands/0.13upgrade" + } ] }, { diff --git a/website/data/internals-nav-data.json b/website/data/internals-nav-data.json index b6b0479945eb..f9291d89916f 100644 --- a/website/data/internals-nav-data.json +++ b/website/data/internals-nav-data.json @@ -25,7 +25,7 @@ "path": "provider-registry-protocol" }, { - "title": "Resource Graph", + "title": "Dependency Graph", "path": "graph" }, { diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index 7ac27004fc43..dc783d43a7ee 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -1,31 +1,33 @@ --- -page_title: Authentication - Terraform CLI +page_title: Get an API token for HCP Terraform or Terraform Enterprise description: >- - Documentation about the login and logout commands that help automate getting - an API token for your HCP Terraform account. + Use the `terraform login` and `terraform logout` commands get + an API token for your HCP Terraform or Terraform Enterprise account. --- -# CLI Authentication +# Get an API token for HCP Terraform and Terraform Enterprise + +This topic describes how to use the `terraform login` and `terraform logout` to authenticate with HCP Terraform and Terraform Enterprise. > **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. +## Overview + [HCP Terraform](https://cloud.hashicorp.com/products/terraform) and [Terraform Enterprise](/terraform/enterprise) are platforms that perform Terraform runs to provision infrastructure, offering a collaboration-focused -environment that makes it easier for teams to use Terraform together. (For -expediency, the content below refers to both products as "HCP Terraform.") +environment that makes it easier for teams to use Terraform together. + +You can integrate the Terraform CLI with HCP Terraform and Terraform Enterprise in the following ways: + +- Use the Terraform CLI as a front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in HCP Terraform +- Use HCP Terraform or Terraform Enterprise as a state backend and a private module registry. -Terraform CLI integrates with HCP Terraform in several ways — it can be a -front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in HCP Terraform, -and can also use HCP Terraform as a state backend and a private module -registry. All of these integrations require you to authenticate Terraform CLI +These integrations require you to authenticate the Terraform CLI with your HCP Terraform account. -The best way to handle CLI authentication is with the `login` and `logout` -commands, which help automate the process of getting an API token for your -HCP Terraform user account. +## Authentication -For details, see: +Run the `terraform login` command to generate an API token for your HCP Terraform user account. Refer to the [`terraform login` command](/terraform/cli/commands/login) reference documentation for details. -- [The `terraform login` command](/terraform/cli/commands/login) -- [The `terraform logout` command](/terraform/cli/commands/logout) +Run the `terraform logout` command to end your HCP Terraform or Terraform Enterprise session. Refer to the [`terraform logout` command](/terraform/cli/commands/logout) reference documentation for details. diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx index 8bdfd36f84e8..8483a8adf262 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: -ignore-remote-version reference +description: Use the -ignore-remote-version flag to override CLI-driven commands for HCP Terraform runs. --- -# Command Line Arguments +# `-ignore-remote-version` reference 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 eaf6d3f7b867..a8c93cb532c7 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 or Terraform Enterprise with the 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 the 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. diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 714f94227e5f..bc681b34e535 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -1,16 +1,21 @@ --- -page_title: Writing and Modifying Code - Terraform CLI +page_title: Format and validate Terraform configuration using the Terraform CLI description: >- - Learn commands that help validate, format, and upgrade code written in the - Terraform Configuration Language. + Learn about the Terraform commands that validate, format, and upgrade code written in HCL. --- -# Writing and Modifying Terraform Code +# Write and modify Terrafrom configuration from the CLI + +This topic provides an overview of the Terraform CLI commands you can use to develop, format, and validate your Terraform configuration. + +## Introduction The [Terraform language](/terraform/language) is Terraform's primary user interface, and all of Terraform's workflows rely on configurations written in the Terraform language. +## Workflows + Terraform CLI includes several commands to make Terraform code more convenient to work with. Integrating these commands into your editing workflow can potentially save you time and effort. diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.mdx index eb4acc2a2a23..ef4cebb75ef7 100644 --- a/website/docs/cli/commands/0.12upgrade.mdx +++ b/website/docs/cli/commands/0.12upgrade.mdx @@ -1,11 +1,11 @@ --- -page_title: 'Command: 0.12upgrade' +page_title: terraform 0.12upgrade command reference description: >- - The 0.12upgrade subcommand automatically rewrites existing configurations for + The `terraform 0.12upgrade` command automatically rewrites existing configurations for Terraform 0.12 compatibility. --- -# Command: 0.12upgrade +# `terraform 0.12upgrade` command 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 @@ -114,4 +114,4 @@ prompt, so be sure you have a clean work tree before running it. Because upgrading requires access to the configuration's provider plugins, all of the directories must be initialized with `terraform init` prior to -running the above. +running the above. \ No newline at end of file diff --git a/website/docs/cli/commands/0.13upgrade.mdx b/website/docs/cli/commands/0.13upgrade.mdx index 51c5f451503a..0cc459b42bef 100644 --- a/website/docs/cli/commands/0.13upgrade.mdx +++ b/website/docs/cli/commands/0.13upgrade.mdx @@ -1,11 +1,11 @@ --- -page_title: 'Command: 0.13upgrade' +page_title: terraform 0.13upgrade command reference description: >- - The 0.13upgrade subcommand updates existing configurations to use the new + The `terraform 0.13upgrade` command updates existing configurations to use the new provider source features from Terraform 0.13. --- -# Command: 0.13upgrade +# `terraform 0.13upgrade` command The `terraform 0.13upgrade` command updates existing configuration to add an explicit `source` attribute for each provider used in a given module. The @@ -86,4 +86,4 @@ Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName ``` Note that the above commands include the `-yes` option to override the -interactive prompt, so be sure you have a clean work tree before running it. +interactive prompt, so be sure you have a clean work tree before running it. \ No newline at end of file diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index ae2a7cc14d12..2eb5a9a8c64a 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -1,11 +1,10 @@ --- -page_title: 'Command: apply' -description: >- - The terraform apply command executes the actions proposed in a Terraform plan +page_title: terraform apply command reference +description: The `terraform apply` command executes the actions proposed in a Terraform plan to create, update, or destroy infrastructure. --- -# Command: apply +# `terraform apply` command The `terraform apply` command executes the actions proposed in a Terraform plan. @@ -16,8 +15,6 @@ plan. Usage: `terraform apply [options] [plan file]` - - ### 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 diff --git a/website/docs/cli/commands/console.mdx b/website/docs/cli/commands/console.mdx index e5ad1e506d09..f740b2e6d555 100644 --- a/website/docs/cli/commands/console.mdx +++ b/website/docs/cli/commands/console.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: console' +page_title: terraform console command reference description: >- - The terraform console command provides an interactive console for evaluating + The `terraform console` command opens an interactive console for evaluating expressions. --- -# Command: console +# `terraform console` command -The `terraform console` command provides an interactive console for +The `terraform console` command opens an interactive console for evaluating [expressions](/terraform/language/expressions). ## Usage diff --git a/website/docs/cli/commands/destroy.mdx b/website/docs/cli/commands/destroy.mdx index a7d26ab6c2d1..376942ce39e7 100644 --- a/website/docs/cli/commands/destroy.mdx +++ b/website/docs/cli/commands/destroy.mdx @@ -1,14 +1,13 @@ --- -page_title: 'Command: destroy' +page_title: terraform destroy command reference description: >- - The terraform destroy command destroys all objects managed by a Terraform + The `terraform destroy` command deprovisions all objects managed by a Terraform configuration. --- -# Command: destroy +# `terraform destroy` command -The `terraform destroy` command is a convenient way to destroy all remote -objects managed by a particular Terraform configuration. +The `terraform destroy` command deprovisions all objects managed by a Terraform configuration. While you will typically not want to destroy long-lived objects in a production environment, Terraform is sometimes used to manage ephemeral infrastructure diff --git a/website/docs/cli/commands/env.mdx b/website/docs/cli/commands/env.mdx deleted file mode 100644 index bb98c9fd153f..000000000000 --- a/website/docs/cli/commands/env.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -page_title: 'Command: env' -description: >- - The terraform env command is a deprecated form of the terraform workspace - command. ---- - -# Command: env - -The `terraform env` command is deprecated. -[The `terraform workspace` command](/terraform/cli/commands/workspace) -should be used instead. diff --git a/website/docs/cli/commands/fmt.mdx b/website/docs/cli/commands/fmt.mdx index 33c72b60d564..871f800eb5c6 100644 --- a/website/docs/cli/commands/fmt.mdx +++ b/website/docs/cli/commands/fmt.mdx @@ -1,33 +1,32 @@ --- -page_title: 'Command: fmt' +page_title: terraform fmt command reference description: >- - The terraform fmt command rewrites configuration files to a canonical format + The `terraform fmt` command formats Terraform configuration contents so that it matches the canonical format and style. --- -# Command: fmt +# `terraform fmt` command -The `terraform fmt` command is used to rewrite Terraform configuration files -to a canonical format and style. This command applies a subset of +The `terraform fmt` command formats Terraform configuration file contents so that it matches the canonical format and style. This command applies a subset of the [Terraform language style conventions](/terraform/language/style#code-formatting), along with other minor adjustments for readability. -Other Terraform commands that generate Terraform configuration will produce -configuration files that conform to the style imposed by `terraform fmt`, so -using this style in your own files will ensure consistency. +## Introduction +Terraform commands that generate Terraform configuration produce +configuration files that conform to the style imposed by `terraform fmt`. Follow this style in your files to ensure consistency. The canonical format may change in minor ways between Terraform versions, so after upgrading Terraform we recommend to proactively run `terraform fmt` on your modules along with any other changes you are making to adopt the new version. -We don't consider new formatting rules in `terraform fmt` to be a breaking -change in new versions of Terraform, but we do aim to minimize changes for -configurations that are already following the style examples shown in the -Terraform documentation. When adding new formatting rules, they will usually -aim to apply more of the rules already shown in the configuration examples -in the documentation, and so we recommend following the documented style even -for decisions that `terraform fmt` doesn't yet apply automatically. +We do not consider new formatting rules in `terraform fmt` to be a breaking +change in new versions of Terraform, but we minimize changes for +configurations that already follow the style examples shown in the +Terraform documentation. New formatting rules programmed into the `terraform fmt` +command are usually expansions to include existing rules from the documentation. +We recommend following the documented style even for decisions that `terraform fmt` +does not yet apply automatically. Formatting decisions are always subjective and so you might disagree with the decisions that `terraform fmt` makes. This command is intentionally opinionated diff --git a/website/docs/cli/commands/force-unlock.mdx b/website/docs/cli/commands/force-unlock.mdx index 705d04427a74..b26eb3e1b80d 100644 --- a/website/docs/cli/commands/force-unlock.mdx +++ b/website/docs/cli/commands/force-unlock.mdx @@ -1,18 +1,17 @@ --- -page_title: 'Command: force-unlock' +page_title: terraform force-unlock command reference description: >- - The terraform force-unlock command unlocks the state for a configuration. It + The `terraform force-unlock` command unlocks the state for a configuration. It does not modify your infrastructure. --- -# Command: force-unlock +# `terraform force-unlock` command -Manually unlock the state for the defined configuration. +This topic provides reference information about the `terraform force-unlock` command. This command manually unlocks the state for the defined configuration. -This will not modify your infrastructure. This command removes the lock on the -state for the current configuration. The behavior of this lock is dependent +This command removes the lock on the state for the current configuration. The behavior of this lock is dependent on the backend being used. Local state files cannot be unlocked by another -process. +process. The `terraform force-unlock` command does not modify your infrastructure. ## Usage @@ -27,4 +26,4 @@ process. Options: -* `-force` - Don't ask for input for unlock confirmation. +- `-force` - Don't ask for input for unlock confirmation. diff --git a/website/docs/cli/commands/get.mdx b/website/docs/cli/commands/get.mdx index f46b8776b9d3..9b0254331c72 100644 --- a/website/docs/cli/commands/get.mdx +++ b/website/docs/cli/commands/get.mdx @@ -1,12 +1,12 @@ --- -page_title: 'Command: get' -description: The terraform get command downloads and updates modules. +page_title: terraform get command reference +description: The `terraform get` command downloads and updates modules. --- -# Command: get +# `terraform get` command -The `terraform get` command is used to download and update -[modules](/terraform/language/modules/develop) mentioned in the root module. +Run the `terraform get` command to download and update +[modules](/terraform/language/modules/develop) declared in the root module. ## Usage diff --git a/website/docs/cli/commands/graph.mdx b/website/docs/cli/commands/graph.mdx index 6ee59236ad88..12a471977f0f 100644 --- a/website/docs/cli/commands/graph.mdx +++ b/website/docs/cli/commands/graph.mdx @@ -1,15 +1,13 @@ --- -page_title: 'Command: graph' +page_title: terraform graph command reference description: >- - The terraform graph command generates a visual representation of a + The `terraform graph` command generates a visual representation of a configuration or execution plan that you can use to generate charts. --- -# Command: graph +# `terraform graph` command -The `terraform graph` command produces descriptions of the relationships -between objects in a Terraform configuration, using -[the DOT language](https://en.wikipedia.org/wiki/DOT_(graph_description_language)). +The `terraform graph` command generates a visual representation of a configuration or execution plan that you can use to generate charts. This command uses the DOT language generate graphs. Refer to the [GraphViz documentation](https://graphviz.org/doc/info/lang.html) for additional information. ## Usage diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx index 6f26f2d6a571..c3097e7394ff 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.mdx @@ -1,14 +1,15 @@ --- -page_title: 'Command: import' -description: The terraform import command brings existing resources into Terraform state. +page_title: terraform import command reference +description: The `terraform import` command imports existing resources into Terraform state. --- -# Command: import +# `terraform import` command reference + +The `terraform import` command imports existing resources into Terraform. Refer to [Import](/terraform/cli/import) for additional information. + > **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. -The `terraform import` command [imports existing resources](/terraform/cli/import) -into Terraform. ## Usage diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx index 3e3431c5c9d6..3f0c33948ecc 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.mdx @@ -1,12 +1,17 @@ --- -page_title: Basic CLI Features -description: An introduction to the terraform command and its available subcommands. +page_title: Terraform CLI overview +description: The Terrafrom CLI includes commands for provisioning infrastructure as code and managing the infrastructure lifecycle. Learn about Terraform CLI features. --- -# Basic CLI Features +# Terraform CLI Overview + +This topic provides an overview of the Terraform command line interface. > **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. + +## Introduction + The command line interface to Terraform is the `terraform` command, which accepts a variety of subcommands such as `terraform init` or `terraform plan`. diff --git a/website/docs/cli/commands/init.mdx b/website/docs/cli/commands/init.mdx index b139bdfbd4ba..08604186b880 100644 --- a/website/docs/cli/commands/init.mdx +++ b/website/docs/cli/commands/init.mdx @@ -1,19 +1,19 @@ --- -page_title: 'Command: init' +page_title: terraform init command reference description: >- - The terraform init command initializes a working directory containing + The `terraform init` command initializes a working directory containing configuration files and installs plugins for required providers. --- -# Command: init - -> **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. For more in-depth details on the `init` command, check out the [Initialize Terraform Configuration tutorial](/terraform/tutorials/cli/init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). +# `terraform init` command The `terraform init` command initializes a working directory -containing Terraform configuration files. This is the first command that should -be run after writing a new Terraform configuration or cloning an existing one +containing Terraform configuration files. This is the first command you should +run after writing a new Terraform configuration or cloning an existing configuration from version control. It is safe to run this command multiple times. +> **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. For more in-depth details on the `init` command, check out the [Initialize Terraform Configuration tutorial](/terraform/tutorials/cli/init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). + ## Usage Usage: `terraform init [options]` diff --git a/website/docs/cli/commands/login.mdx b/website/docs/cli/commands/login.mdx index b2eb5372bbbd..9a4cb535a7db 100644 --- a/website/docs/cli/commands/login.mdx +++ b/website/docs/cli/commands/login.mdx @@ -1,18 +1,16 @@ --- -page_title: 'Command: login' +page_title: terraform login command reference 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 + The `terraform login` command obtains an API token for HCP Terraform, Terraform Enterprise, or other host that offers Terraform services. --- -# Command: login +# `terraform login` command -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. +The `terraform login` command obtains an API token for HCP Terraform, Terraform Enterprise, or other host that + offers Terraform services. --> **Note:** 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 +You can only use this command in interactive scenarios because the command launches 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). diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.mdx index f0158fa9a7cd..8351a6a232fd 100644 --- a/website/docs/cli/commands/logout.mdx +++ b/website/docs/cli/commands/logout.mdx @@ -1,14 +1,18 @@ --- -page_title: 'Command: logout' +page_title: terraform logout command reference description: >- - The terraform logout command is used to remove credentials stored by terraform - login. + The `terraform logout` command removes credentials stored after using the terraform + login command. --- -# Command: logout +# `terraform logout` command -The `terraform logout` command is used to remove credentials stored by -`terraform login`. These credentials are API tokens for HCP Terraform, +This topic provides reference information about the `terraform logout` command. + +## Introduction + +Use the `terraform logout` command to remove credentials stored after running the +`terraform login` command. These credentials are API tokens for HCP Terraform, Terraform Enterprise, or any other host that offers Terraform services. ## Usage diff --git a/website/docs/cli/commands/modules.mdx b/website/docs/cli/commands/modules.mdx index f43ece9c6b56..2039a3bce9f2 100644 --- a/website/docs/cli/commands/modules.mdx +++ b/website/docs/cli/commands/modules.mdx @@ -1,7 +1,7 @@ --- -page_title: 'Command: modules' +page_title: terraform modules command reference description: >- - The terraform modules command prints source and version data about all declared + The `terraform modules` command prints source and version data about all declared modules in Terraform configuration. --- diff --git a/website/docs/cli/commands/output.mdx b/website/docs/cli/commands/output.mdx index b86fca55dbc9..fe2d9d104dbf 100644 --- a/website/docs/cli/commands/output.mdx +++ b/website/docs/cli/commands/output.mdx @@ -1,14 +1,12 @@ --- -page_title: 'Command: output' +page_title: terraform output command referenece description: >- - The `terraform output` command is used to extract the value of an output - variable from the state file. + The `terraform output` command extracts the value of an output variable from the state file. --- -# Command: output +# `terraform output` command -The `terraform output` command is used to extract the value of -an output variable from the state file. +The `terraform output` command extracts the value of an output variable from the state file. ## Usage diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 255175a853da..7cbbcf6fa222 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -1,15 +1,17 @@ --- -page_title: 'Command: plan' +page_title: terraform plan command reference description: >- - The terraform plan command creates an execution plan with a preview of the + The `terraform plan` command creates an execution plan with a preview of the changes that Terraform will make to your infrastructure. --- -# Command: plan +# `terraform plan` command The `terraform plan` command creates an execution plan, which lets you preview -the changes that Terraform plans to make to your infrastructure. By default, -when Terraform creates a plan it: +the changes that Terraform plans to make to your infrastructure. + +## Introduction +By default, Terraform performs the following operations when it creates a plan: * Reads the current state of any already-existing remote objects to make sure that the Terraform state is up-to-date. diff --git a/website/docs/cli/commands/providers.mdx b/website/docs/cli/commands/providers.mdx index 3222d8f637dc..c1a2f3315816 100644 --- a/website/docs/cli/commands/providers.mdx +++ b/website/docs/cli/commands/providers.mdx @@ -1,7 +1,7 @@ --- page_title: 'Command: providers' description: >- - The terraform providers command prints information about the providers + The `terraform providers` command prints information about the providers required in the current configuration. --- diff --git a/website/docs/cli/commands/providers/lock.mdx b/website/docs/cli/commands/providers/lock.mdx index 3216618e2d49..4ea85060ab79 100644 --- a/website/docs/cli/commands/providers/lock.mdx +++ b/website/docs/cli/commands/providers/lock.mdx @@ -1,15 +1,18 @@ --- -page_title: 'Command: providers lock' +page_title: terraform providers lock command reference description: |- The `terraform providers lock` command adds new provider selection information to the dependency lock file without initializing the referenced providers. --- -# Command: terraform providers lock +# `terraform providers lock` command -The `terraform providers lock` consults upstream registries (by default) in -order to write provider dependency information into -[the dependency lock file](/terraform/language/files/dependency-lock). +The `terraform providers lock` adds new provider selection information to the dependency lock file without initializing the referenced providers. + +## Introduction + +When you run the command, Terraform consults upstream registries and writes provider dependency information into the +the dependency lock file. Refer to [Dependency Lock File](/terraform/language/files/dependency-lock) in the Terraform configuration language reference documentation for additional information about the lock file. The common way to update the dependency lock file is as a side-effect of normal provider installation during @@ -37,8 +40,6 @@ automatic approach may not be sufficient: You can avoid that by pre-populating hashes for all of the platforms you intend to use, using the `terraform providers lock` command. --> `terraform providers lock` is available only in Terraform v0.14 or later. - ## Usage Usage: `terraform providers lock [options] [providers...]` diff --git a/website/docs/cli/commands/providers/mirror.mdx b/website/docs/cli/commands/providers/mirror.mdx index fb48ae6797b9..0ef8bc47cbd5 100644 --- a/website/docs/cli/commands/providers/mirror.mdx +++ b/website/docs/cli/commands/providers/mirror.mdx @@ -1,12 +1,12 @@ --- -page_title: 'Command: providers mirror' +page_title: terraform providers mirror command reference description: |- The `terraform providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local filesystem. --- -# Command: terraform providers mirror +# `terraform providers mirror` command The `terraform providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local diff --git a/website/docs/cli/commands/providers/schema.mdx b/website/docs/cli/commands/providers/schema.mdx index 052bb0f45ae7..af0cf6eb3a3d 100644 --- a/website/docs/cli/commands/providers/schema.mdx +++ b/website/docs/cli/commands/providers/schema.mdx @@ -1,40 +1,30 @@ --- -page_title: 'Command: providers schema' +page_title: terraform providers schema command description: >- - The `terraform providers schema` command prints detailed schemas for the - providers used - - in the current configuration. + The `terraform providers schema` command prints detailed schemas for the providers declared in the configuration. --- -# Command: terraform providers schema - -The `terraform providers schema` command is used to print detailed schemas for the providers used in the current configuration. +# `terraform providers schema` command --> `terraform providers schema` requires **Terraform v0.12 or later**. +The `terraform providers schema` command print detailed schemas for the providers used in the current configuration. ## Usage -Usage: `terraform providers schema [options]` +``` +$ terraform providers schema [options] +``` The following flags are available: -- `-json` - Displays the schemas in a machine-readable, JSON format. - -Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. +- `-json` - Displays the schemas in a machine-readable JSON format. The `-json` flag is required. -The output includes a `format_version` key, which as of Terraform 1.1.0 has -value `"1.0"`. The semantics of this version are: + The output includes a `format_version` key, which has a default value of `"1.0"`. The semantics of this version are: -- We will increment the minor version, e.g. `"1.1"`, for backward-compatible - changes or additions. Ignore any object properties with unrecognized names to + - Versions between `1.0` and `2.0` are backward-compatible. You should ignore any object properties with unrecognized names to remain forward-compatible with future minor versions. -- We will increment the major version, e.g. `"2.0"`, for changes that are not - backward-compatible. Reject any input which reports an unsupported major + - Major versions are not backward-compatible to older versions. You should reject any input that reports an unsupported major version. - -We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). + - Refer to [Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises) for additional information about version support. ## Format Summary diff --git a/website/docs/cli/commands/push.mdx b/website/docs/cli/commands/push.mdx deleted file mode 100644 index 1771d330e0c4..000000000000 --- a/website/docs/cli/commands/push.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -page_title: 'Command: push' -description: >- - DISCONTINUED. HCP Terraform and the modern "remote" backend have replaced - the old `terraform push` command. ---- - -# 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 was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise. - -The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional. diff --git a/website/docs/cli/commands/refresh.mdx b/website/docs/cli/commands/refresh.mdx index d44f4f1abf39..d58b385f7b1a 100644 --- a/website/docs/cli/commands/refresh.mdx +++ b/website/docs/cli/commands/refresh.mdx @@ -1,33 +1,19 @@ --- -page_title: 'Command: refresh' +page_title: terraform refresh command reference description: |- The `terraform refresh` command reads the current settings from all managed remote objects and updates the Terraform state to match. --- -# Command: refresh - -> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. +# `terraform refresh` command The `terraform refresh` command reads the current settings from all managed -remote objects and updates the Terraform state to match. +remote objects and updates the Terraform state to match. This command is deprecated. Instead, add the `-refresh-only` flag to [`terraform apply`](/terraform/cli/commands/apply) and [`terraform plan`](/terraform/cli/commands/plan) commands. -~> _Warning:_ This command is deprecated, because its default behavior is -unsafe if you have misconfigured credentials for any of your providers. -See below for more information and recommended alternatives. - -This won't modify your real remote objects, but it will modify the +This does not modify your real remote objects, but it modifies the [Terraform state](/terraform/language/state). -You shouldn't typically need to use this command, because Terraform -automatically performs the same refreshing actions as a part of creating -a plan in both the -[`terraform plan`](/terraform/cli/commands/plan) -and -[`terraform apply`](/terraform/cli/commands/apply) -commands. This command is here primarily for backward compatibility, but -we don't recommend using it because it provides no opportunity to review -the effects of the operation before updating the state. +> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. ## Usage diff --git a/website/docs/cli/commands/show.mdx b/website/docs/cli/commands/show.mdx index cbde69f54e58..cee62369cf02 100644 --- a/website/docs/cli/commands/show.mdx +++ b/website/docs/cli/commands/show.mdx @@ -1,21 +1,15 @@ --- -page_title: 'Command: show' -description: >- - The `terraform show` command is used to provide human-readable output from a - state or plan file. This can be used to inspect a plan to ensure that the - planned operations are expected, or to inspect the current state as Terraform - sees it. +page_title: terraform show command reference +description: The `terraform show` command provides human-readable output from a state or plan file. --- -# Command: show +# `terraform show` command -The `terraform show` command is used to provide human-readable output -from a state or plan file. This can be used to inspect a plan to ensure +The `terraform show` command provides human-readable output +from a state or plan file. Use the command to inspect a plan to ensure that the planned operations are expected, or to inspect the current state 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 Terraform state will be displayed in plain text. For more information, see @@ -23,14 +17,16 @@ Terraform state will be displayed in plain text. For more information, see ## JSON Output -For Terraform state files (including when no path is provided), -`terraform show -json` will show a JSON representation of the state. +Add the `-json` command-line flag to generate machine-readable output. -For Terraform plan files, `terraform show -json` will show a JSON representation +For Terraform state files, including when no path is provided, +`terraform show -json` shows a JSON representation of the state. + +For Terraform plan files, `terraform show -json` shows a JSON representation of the plan, configuration, and current state. -If you've updated providers which contain new schema versions since the state -was written, the state needs to be upgraded before it can be displayed with +If you updated providers that contain new schema versions since the state +was written, upgrade the state before so that Terraform can display it with `show -json`. If you are viewing a plan, it must be created without `-refresh=false`. If you are viewing a state file, run `terraform refresh` first. diff --git a/website/docs/cli/commands/state/index.mdx b/website/docs/cli/commands/state/index.mdx index 0d5a46be8c9b..0ba25c3bab1c 100644 --- a/website/docs/cli/commands/state/index.mdx +++ b/website/docs/cli/commands/state/index.mdx @@ -1,24 +1,28 @@ --- -page_title: 'Command: state' -description: The `terraform state` command is used for advanced state management. +page_title: terraform state commands reference +description: The `terraform state` group of commands enable advanced Terraform state management. --- -# State Command +# `terraform state` commands -The `terraform state` command is used for advanced state management. -As your Terraform usage becomes more advanced, there are some cases where -you may need to modify the [Terraform state](/terraform/language/state). -Rather than modify the state directly, the `terraform state` commands can -be used in many cases instead. +The `terraform state` commands enable advanced state management. -This command is a nested subcommand, meaning that it has further subcommands. -These subcommands are listed to the left. +## Introduction + +You can use the `terraform state` commands to modify the [Terraform state](/terraform/language/state) instead modifying the state directly. ## Usage Usage: `terraform state [options] [args]` -Please click a subcommand to the left for more information. +Refer to the following subcommands for additional information: + +- [`terraform state list`](/terraform/cli/commands/state/list) +- [`terraform state mv`](/terraform/cli/commands/state/mv) +- [`terraform state pull`](/terraform/cli/commands/state/pull) +- [`terraform state replace-provider`](/terraform/cli/commands/state/replace-provider) +- [`terraform state rm`](/terraform/cli/commands/state/rm) +- [`terraform state show`](/terraform/cli/commands/state/show) ## Remote State diff --git a/website/docs/cli/commands/state/list.mdx b/website/docs/cli/commands/state/list.mdx index f3879ab6b6e8..3da2091d9012 100644 --- a/website/docs/cli/commands/state/list.mdx +++ b/website/docs/cli/commands/state/list.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: state list' +page_title: terraform state list command reference description: >- - The terraform state list command is used to list resources within a Terraform + The terraform state list command lists resources within a Terraform state. --- -# Command: state list +# `terraform state list` command -The `terraform state list` command is used to list resources within a +The `terraform state list` command lists resources within a [Terraform state](/terraform/language/state). ## Usage diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.mdx index 46ac03e5448a..4c29c0157227 100644 --- a/website/docs/cli/commands/state/mv.mdx +++ b/website/docs/cli/commands/state/mv.mdx @@ -1,22 +1,18 @@ --- -page_title: 'Command: state mv' +page_title: terraform state mv command reference description: >- - The `terraform state mv` command changes bindings in Terraform state, - associating existing remote objects with new resource instances. + The `terraform state mv` command changes bindings in Terraform state so that existing remote objects bind to new resource instances. --- -# Command: state mv +# `terraform state mv` command -The main function of [Terraform state](/terraform/language/state) is -to track the bindings between resource instance addresses in your configuration -and the remote objects they represent. Normally Terraform automatically -updates the state in response to actions taken when applying a plan, such as -removing a binding for an remote object that has now been deleted. +The `terraform state mv` command changes bindings in Terraform state so that existing remote objects bind to new resource instances. -You can use `terraform state mv` in the less common situation where you wish +## Introduction + +Terraform automatically updates the state when you apply a plan, but you can use `terraform state mv` to retain an existing remote object but track it as a different resource -instance address in Terraform, such as if you have renamed a resource block -or you have moved it into a different module in your configuration. +instance address in Terraform. ## Usage diff --git a/website/docs/cli/commands/state/pull.mdx b/website/docs/cli/commands/state/pull.mdx index 115b5c6c3f2e..2d851fbc198a 100644 --- a/website/docs/cli/commands/state/pull.mdx +++ b/website/docs/cli/commands/state/pull.mdx @@ -1,15 +1,12 @@ --- -page_title: 'Command: state pull' +page_title: terraform state pull command reference description: >- - The `terraform state pull` command is used to manually download and output the - state from remote state. + The `terraform state pull` command downloads and outputs state information from a remote state or local state. --- -# Command: state pull +# `terraform state pull` command -The `terraform state pull` command is used to manually download and output -the state from [remote state](/terraform/language/state/remote). This command also -works with local state. +The `terraform state pull` downloads and outputs state information from a [remote state](/terraform/language/state/remote) or local state. ## Usage diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx index 3b4f1fee0e95..0f42379cfbf2 100644 --- a/website/docs/cli/commands/state/push.mdx +++ b/website/docs/cli/commands/state/push.mdx @@ -1,16 +1,11 @@ --- -page_title: 'Command: state push' -description: The `terraform state push` command pushes items to the Terraform state. +page_title: terraform state push command reference +description: The `terraform state push` command uploads a state file to the Terraform state. --- -# Command: state push +# `terraform state push` command -The `terraform state push` command is used to manually upload a local -state file to [remote state](/terraform/language/state/remote). This command also -works with local state. - -This command should rarely be used. It is meant only as a utility in case -manual intervention is necessary with the remote state. +The `terraform state push` command uploads a local state file to [remote state](/terraform/language/state/remote) or a local state. We only recommend using this command when you must manually modify the remote state. ## Usage diff --git a/website/docs/cli/commands/state/replace-provider.mdx b/website/docs/cli/commands/state/replace-provider.mdx index a409e9ee2e71..690277a04958 100644 --- a/website/docs/cli/commands/state/replace-provider.mdx +++ b/website/docs/cli/commands/state/replace-provider.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: state replace-provider' +page_title: terraform state replace-provider command reference description: >- The `terraform state replace-provider` command replaces the provider for resources in the Terraform state. --- -# Command: state replace-provider +# `terraform state replace-provider` command -The `terraform state replace-provider` command is used to replace the provider +The `terraform state replace-provider` command replaces the provider for resources in a [Terraform state](/terraform/language/state). ## Usage diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.mdx index e55a42e6e66f..92cd4ad36c85 100644 --- a/website/docs/cli/commands/state/rm.mdx +++ b/website/docs/cli/commands/state/rm.mdx @@ -1,24 +1,15 @@ --- -page_title: 'Command: state rm' +page_title: terraform state rm command reference description: >- - The `terraform state rm` command removes bindings from the Terraform state, - causing Terraform to "forget about" existing objects. + The `terraform state rm` command removes bindings between resource instances defined in the Terraform configuration and corresponding remote objects. --- -# Command: state rm +# `terraform state rm` command -The main function of [Terraform state](/terraform/language/state) is -to track the bindings between resource instance addresses in your configuration -and the remote objects they represent. Normally Terraform automatically -updates the state in response to actions taken when applying a plan, such as -removing a binding for a remote object that has now been deleted. +The `terraform state rm` command removes the binding to an existing remote object without first destroying it. The remote object continues +to exist but is no longer managed by Terraform. -You can use `terraform state rm` in the less common situation where you wish -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). +Instead of using the `terraform state rm` command, you can use `removed` blocks to remove resources. You can 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 diff --git a/website/docs/cli/commands/state/show.mdx b/website/docs/cli/commands/state/show.mdx index b64636200321..30c9036d3268 100644 --- a/website/docs/cli/commands/state/show.mdx +++ b/website/docs/cli/commands/state/show.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: state show' +page_title: terraform state show command reference description: >- - The `terraform state show` command is used to show the attributes of a single + The `terraform state show` command shows the attributes of a single resource in the Terraform state. --- -# Command: state show +# `terraform state show` command -The `terraform state show` command is used to show the attributes of a +The `terraform state show` command shows the attributes of a single resource in the [Terraform state](/terraform/language/state). diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index b3b2c296eb59..eede6b8d1818 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -1,18 +1,14 @@ --- -page_title: 'Command: taint' +page_title: terraform taint command reference description: |- - The `terraform taint` command informs Terraform that a particular object - is damaged or degraded. + The `terraform taint` command marks specified objects in the Terraform state as tainted. --- -# Command: taint +# `terraform taint` command -The `terraform taint` command informs Terraform that a particular object has -become degraded or damaged. Terraform represents this by marking the -object as "tainted" in the Terraform state, and Terraform will -propose to replace it in the next plan you create. +The `terraform taint` command marks specified objects in the Terraform state as tainted. Use the `terraform taint` command when objects become degraded or damaged. Terraform prompts you to replace the tainted objects 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). +This command is deprecated. Instead, add the `-replace` option to your [`terraform apply` command](/terraform/cli/commands/apply). ## Recommended Alternative diff --git a/website/docs/cli/commands/test.mdx b/website/docs/cli/commands/test.mdx index 6c6898ba6221..4e33e16b3165 100644 --- a/website/docs/cli/commands/test.mdx +++ b/website/docs/cli/commands/test.mdx @@ -1,20 +1,22 @@ --- -page_title: 'Command: test' +page_title: terraform test command reference description: >- The `terraform test` command loads and executes Terraform testing files. --- -# Command: test +# `terraform test` command -The `terraform test` command reads in Terraform testing files and executes the tests within. +The `terraform test` command loads and exectures Terraform testing files. -The `test` command, and the test file syntax, are particularly helpful for module authors who want to validate and test their shared modules. You can also use the `test` command to validate root modules. +## Introduction + +The `terraform test` command and the test file syntax help module authors validate and test their shared modules. You can also use the `terraform test` command to validate root modules. ## Usage Usage: `terraform test [options]` -This command searches the current directory and the specified testing directory (`tests`, by default) for any Terraform testing files, and executes the specified tests. Refer to [Tests](/terraform/language/tests) for more details on test files. +This command searches the current directory and the specified testing directory for Terraform testing files and executes the specified tests. By default, the directory containing test files is named `tests`. Refer to [Tests](/terraform/language/tests) for more details on test files. 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. @@ -22,7 +24,7 @@ Terraform then executes a series of Terraform plan or apply commands according t ## General Options -The following options apply to the Terraform `test` command: +The following options apply to the Terraform `terraform test` command: * `-cloud-run=` - This test run executes remotely on HCP Terraform within the specified Terraform [private registry](/terraform/language/modules/sources#terraform-registry) module. @@ -40,7 +42,7 @@ Each Terraform test file will maintain all Terraform state it requires within me ### 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. +The Terraform `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. You should monitor the output of the test command closely to ensure Terraform removes the infrastructure it created or perform manual cleanup if not. We recommend creating dedicated testing accounts within the target providers that you can routinely and safely purge to ensure any accidental and costly resources aren't left behind. diff --git a/website/docs/cli/commands/untaint.mdx b/website/docs/cli/commands/untaint.mdx index 61bb3ee4dae7..bd2163ae39c8 100644 --- a/website/docs/cli/commands/untaint.mdx +++ b/website/docs/cli/commands/untaint.mdx @@ -1,14 +1,16 @@ --- -page_title: 'Command: untaint' +page_title: terraform untaint command reference description: |- - The `terraform untaint` command tells Terraform that an object is functioning - correctly, even though its creation failed or it was previously manually - marked as degraded. + The `terraform untaint` command removes the `tainted` status from infrastructure objects tracked in the Terraform state data. --- -# Command: untaint +# `terraform untaint` command -Terraform has a marker called "tainted" which it uses to track that an object +This topic provides reference information about the `terraform untaint` command. + +## Introduction + +Terraform has a marker called `tainted` which it uses to track that an object might be damaged and so a future Terraform plan ought to replace it. Terraform automatically marks an object as "tainted" if an error occurs during diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.mdx index e9e78f685994..962875f0facd 100644 --- a/website/docs/cli/commands/validate.mdx +++ b/website/docs/cli/commands/validate.mdx @@ -1,15 +1,15 @@ --- -page_title: 'Command: validate' +page_title: terraform validate command reference description: >- - The `terraform validate` command is used to validate the syntax of the - terraform files. + The `terraform validate` command validates the syntax of Terraform configuration files in a directory. --- -# Command: validate +# `terraform validate` command The `terraform validate` command validates the configuration files in a -directory, referring only to the configuration and not accessing any remote -services such as remote state, provider APIs, etc. +directory. It does not validate remote services, such as remote state or provider APIs. + +## Introduction Validate runs checks that verify whether a configuration is syntactically valid and internally consistent, regardless of any provided variables or diff --git a/website/docs/cli/commands/version.mdx b/website/docs/cli/commands/version.mdx index 378ec3ae795a..3d776d5b60de 100644 --- a/website/docs/cli/commands/version.mdx +++ b/website/docs/cli/commands/version.mdx @@ -1,29 +1,28 @@ --- -page_title: 'Command: version' +page_title: terraform version command reference description: >- - The terraform version command displays the Terraform version and the version + The terraform version command prints the Terraform version and the version of all installed plugins. --- -# Command: version +# `terraform version` command -The `terraform version` displays the current version of Terraform and all +The `terraform version` command prints the current version of the Terraform binary and all installed plugins. ## Usage Usage: `terraform version [options]` -With no additional arguments, `version` will display the version of Terraform, -the platform it's installed on, installed providers, and the results of upgrade -and security checks [unless disabled](/terraform/cli/commands#upgrade-and-security-bulletin-checks). +With no additional arguments, `version` displays the version of Terraform, +the platform it is installed on, installed providers, and the results of upgrade +and security checks unless disabled. Refer to [Upgrade and Security Bulletin Checks](/terraform/cli/commands#upgrade-and-security-bulletin-checks) for additional information. -This command has one optional flag: +## Flags -* `-json` - If specified, the version information is formatted as a JSON object, - and no upgrade or security information is included. +This command has one optional flag: --> **Note:** Platform information was added to the `version` command in Terraform 0.15. +* `-json` - Formats version information as a JSON object. No upgrade or security information is included. ## Example diff --git a/website/docs/cli/commands/workspace/delete.mdx b/website/docs/cli/commands/workspace/delete.mdx index 3c7f54ea4f38..4b4f3f3c6c16 100644 --- a/website/docs/cli/commands/workspace/delete.mdx +++ b/website/docs/cli/commands/workspace/delete.mdx @@ -1,11 +1,11 @@ --- -page_title: 'Command: workspace delete' -description: The terraform workspace delete command is used to delete a workspace. +page_title: terraform workspace delete command reference +description: The terraform workspace delete command deletes the specified workspace. --- -# Command: workspace delete +# `terraform workspace delete` command -The `terraform workspace delete` command is used to delete an existing workspace. +The `terraform workspace delete` command deletes the specified workspace. ## Usage diff --git a/website/docs/cli/commands/workspace/index.mdx b/website/docs/cli/commands/workspace/index.mdx index d3a9798f6d60..c7d3dba49787 100644 --- a/website/docs/cli/commands/workspace/index.mdx +++ b/website/docs/cli/commands/workspace/index.mdx @@ -1,12 +1,11 @@ --- -page_title: 'Command: workspace' -description: The workspace command helps you manage workspaces. +page_title: terraform workspace command reference +description: The terraform workspace command helps you manage workspaces. --- -# Command: workspace +# `terraform workspace` command -The `terraform workspace` command is used to manage -[workspaces](/terraform/language/state/workspaces). +The `terraform workspace` command group helps you manage [workspaces](/terraform/language/state/workspaces). This command is a container for further subcommands that each have their own page in the documentation. diff --git a/website/docs/cli/commands/workspace/list.mdx b/website/docs/cli/commands/workspace/list.mdx index d7d2e6eee285..74a0b266e204 100644 --- a/website/docs/cli/commands/workspace/list.mdx +++ b/website/docs/cli/commands/workspace/list.mdx @@ -1,11 +1,11 @@ --- -page_title: 'Command: workspace list' -description: The terraform workspace list command is used to list all existing workspaces. +page_title: terraform workspace list command reference +description: The terraform workspace list command lists all existing workspaces. --- -# Command: workspace list +# `terraform workspace list` command -The `terraform workspace list` command is used to list all existing workspaces. +The `terraform workspace list` command lists all existing workspaces. ## Usage diff --git a/website/docs/cli/commands/workspace/new.mdx b/website/docs/cli/commands/workspace/new.mdx index 28b4d1c30d4e..5b07fae6de15 100644 --- a/website/docs/cli/commands/workspace/new.mdx +++ b/website/docs/cli/commands/workspace/new.mdx @@ -1,9 +1,9 @@ --- -page_title: 'Command: workspace new' -description: The terraform workspace new command is used to create a new workspace. +page_title: terraform workspace new command reference +description: The terraform workspace new command creates a new workspace with the specified name. --- -# Command: workspace new +# `terraform workspace new` command The `terraform workspace new` command is used to create a new workspace. diff --git a/website/docs/cli/commands/workspace/select.mdx b/website/docs/cli/commands/workspace/select.mdx index 497a56544623..17816e23beaf 100644 --- a/website/docs/cli/commands/workspace/select.mdx +++ b/website/docs/cli/commands/workspace/select.mdx @@ -1,12 +1,11 @@ --- -page_title: 'Command: workspace select' -description: The terraform workspace select command is used to choose a workspace. +page_title: terraform workspace select` command reference +description: The terraform workspace select command selects a workspace. --- -# Command: workspace select +# `terraform workspace select` command -The `terraform workspace select` command is used to choose a different -workspace to use for further operations. +The `terraform workspace select` selects a different workspace to use for further operations. ## Usage diff --git a/website/docs/cli/commands/workspace/show.mdx b/website/docs/cli/commands/workspace/show.mdx index c6063f22fddc..548573ebbab1 100644 --- a/website/docs/cli/commands/workspace/show.mdx +++ b/website/docs/cli/commands/workspace/show.mdx @@ -1,17 +1,17 @@ --- -page_title: 'Command: workspace show' -description: The terraform workspace show command is used to output the current workspace. +page_title: terraform workspace show command reference +description: The terraform workspace show command outputs the current workspace. --- -# Command: workspace show +# `terraform workspace show` command -The `terraform workspace show` command is used to output the current workspace. +The `terraform workspace show` command outputs the current workspace. ## Usage Usage: `terraform workspace show` -The command will display the current workspace. +The command displays the current workspace. ## Example diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.mdx index 2dec34a76e73..8b2923887d5c 100644 --- a/website/docs/cli/config/config-file.mdx +++ b/website/docs/cli/config/config-file.mdx @@ -1,15 +1,19 @@ --- -page_title: CLI Configuration +page_title: Create a Terraform CLI configuration file description: >- - Learn to use the CLI configuration file to customize your CLI settings, - including credentials, plugin caching, provider installation methods, etc. + Learn how to create a `.terraformrc` or `terraform.rc` file to define Terraform CLI settings, including credentials, plugin caching, and provider installation. --- -# CLI Configuration File (`.terraformrc` or `terraform.rc`) +# Create a Terraform CLI configuration file + +This topic describes how create a configuration file to customize the behavior of the Terraform CLI. + +## Introduction The CLI configuration file configures per-user settings for CLI behaviors, which apply across all Terraform working directories. This is separate from -[your infrastructure configuration](/terraform/language). +[your infrastructure configuration](/terraform/language). +You can define custom configurations in file with the `.terraformrc` extention a file named `terraform.rc`. ## Locations diff --git a/website/docs/cli/config/environment-variables.mdx b/website/docs/cli/config/environment-variables.mdx index d08bf2d1ca51..70144c6fdef8 100644 --- a/website/docs/cli/config/environment-variables.mdx +++ b/website/docs/cli/config/environment-variables.mdx @@ -1,17 +1,20 @@ --- -page_title: Environment Variables +page_title: Terraform CLI environment variables reference description: >- - Learn to use environment variables to change Terraform's default behavior. - Configure log content and output, set variables, and more. + Terraform environment variables let you customize the Terraform CLI's default behavior. + Learn about the Terraform CLI environment variables. --- -# Environment Variables +# Terraform CLI environment variables reference + +This topic contains reference information about the environment variables you can use with the Terraform CLI. + +## Introduction Terraform refers to a number of environment variables to customize various aspects of its behavior. None of these environment variables are required -when using Terraform, but they can be used to change some of Terraform's -default behaviors in unusual situations, or to increase output verbosity -for debugging. +when using Terraform, but you can use them to change some of Terraform's +default behaviors or to increase output verbosity for debugging. ## TF_LOG diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.mdx index 77022d1335ae..e329f751bdda 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.mdx @@ -1,19 +1,17 @@ --- -page_title: CLI Configuration - Terraform CLI +page_title: Terraform CLI configuration overview description: >- - Find documentation about the CLI config file and customizing Terraform - environment variables. + The CLI configuration file and supported Terraform environment variables let you customize Terraform CLI behavior. --- -# CLI Configuration +# Terraform CLI configuration overview -Terraform CLI can be configured with some global settings, which are separate +You can configure the Terraform CLI in global settings, which are separate from any Terraform configuration and which apply across all working directories. -We've designed Terraform such that an average user running Terraform CLI -interactively will not need to interact with any of these settings. As a result, +The default behavior of the Terraform CLI is suitable in most cases. As a result, most of the global settings relate to advanced or automated workflows, or -unusual environmental conditions like running Terraform on an airgapped +unusual environmental conditions, such as running Terraform on an air-gapped instance. - The [CLI config file](/terraform/cli/config/config-file) configures provider diff --git a/website/docs/cli/import/importability.mdx b/website/docs/cli/import/importability.mdx deleted file mode 100644 index fdc3fe91c059..000000000000 --- a/website/docs/cli/import/importability.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -page_title: 'Import: Resource Importability' -description: |- - Each resource in Terraform must implement some basic logic to become - importable. As a result, you cannot import all Terraform resources. ---- - -# Resource Importability - -Each resource in Terraform must implement some basic logic to become -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). diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx index 68eba8ed4c8e..6d1e7b13a316 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.mdx @@ -1,26 +1,42 @@ --- -page_title: Import +page_title: Import existing infrastructure resources description: >- - Terraform can import and manage existing infrastructure. This can help you - transition your infrastructure to Terraform. + Terraform lets you import existing infrastructure into state so that you can begin managing your infrastructure as code. --- -# Import +# Import existing resources overview + +This topic provides an overview of the Terraform commands that let you import existing infrastructure resources so that you can manage them with Terraform. > **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. -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). +## Workflows + +You can import an existing resource to state from the Terraform CLI. You can also perform import operations using HCP Terraform. To import multiple resources, use the `import` block. -## State Only +### Import to state -~> **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. +Before you run `terraform import` you must manually write a `resource` configuration block for the resource. The resource block describes where Terraform should map the imported object. 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). -Before you run `terraform import` you must manually write a `resource` configuration block for the resource. The resource block describes where Terraform should map the imported object. +Terraform expects each remote object to be bound to a single resource address. You should import each remote object to one Terraform resource address. Importing the same object multiple times may result in unwanted behavior. Refer to [State](/terraform/language/state) for more details. + +### HCP Terraform + +When you use Terraform on the command line with HCP Terraform, commands such as `apply` run inside your HCP Terraform environment. However, the `import` command runs locally, so it does not have access to information from HCP Terraform. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in HCP Terraform. + +### Import multiple resources + +You can specify multiple resources in the `import` block to import more than one resource at a time. You can also review imports as part of your normal plan and apply workflow. Refer to the [`import` block reference ](/terraform/language/import) in the Terraform configuration language documentation for addtitional information. + +## Resource importability + +Each resource in Terraform must implement some basic logic to become +importable. As a result, you cannot import all Terraform resources. -## HCP Terraform +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. -When you use Terraform on the command line with HCP Terraform, many commands like `apply` run inside your HCP Terraform environment. However, the `import` command runs locally, so it does not have access to information from HCP Terraform. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in HCP Terraform. +To make a resource importable, refer to [Extending Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import). \ No newline at end of file diff --git a/website/docs/cli/import/usage.mdx b/website/docs/cli/import/usage.mdx index 9e2ced76ae62..ea9ddc2def1c 100644 --- a/website/docs/cli/import/usage.mdx +++ b/website/docs/cli/import/usage.mdx @@ -1,16 +1,23 @@ --- -page_title: 'Import: Usage' -description: The `terraform import` command is used to import existing infrastructure. +page_title: Import existing resources +description: Learn now to use the `terraform import` command to import existing infrastructure resources. --- -# Import Usage +# Import existing resources + +This topic describes how to use the `terraform import` command to import existing infrastructure resources so that you can manage them as code. > **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. +## Overview + +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, such as an AWS VPC. + +Complete the following steps to import resources: -Use the `terraform import` command to import existing infrastructure to Terraform state. +1. Add the resource you want to manage with Terraform to your Terraform configuration. +1. Run the `terraform import` command. -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 bound to only one resource address, which is normally guaranteed by Terraform @@ -20,8 +27,12 @@ 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). -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: +## Add the resource to your configuration + +Write a resource block for the resource you want to import in your configuration. +Provide a name for the resource, which is a unique ID that you can use to reference the resource elsewhere in the configuration. + +In the following example, the imported resource is an AWS instance named `example`: ```hcl resource "aws_instance" "example" { @@ -29,15 +40,11 @@ resource "aws_instance" "example" { } ``` -The name "example" here is local to the module where it is declared and is -chosen by the configuration author. This is distinct from any ID issued by -the remote system, which may change over time while the resource name -remains constant. +You do not have to complete the body of the resource block. Instead, you can finish defining arguments after the instance is imported. -If desired, you can leave the body of the resource block blank for now and -return to fill it in once the instance is imported. +## Run the `terraform import` command -Now `terraform import` can be run to attach an existing instance to this +Run `terraform import` to attach an existing instance to the resource configuration: ```shell diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.mdx index 2e26fe971019..18bc09308216 100644 --- a/website/docs/cli/index.mdx +++ b/website/docs/cli/index.mdx @@ -9,11 +9,11 @@ description: >- > **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. -This is the documentation for Terraform CLI. It is relevant to anyone working -with Terraform's CLI-based workflows; this includes people who use Terraform CLI -by itself, as well as those who use Terraform CLI in conjunction with Terraform -Cloud or Terraform Enterprise. +This documentation provides reference information about Terraform CLI commands, +as well as instructions for using commands to provision infrastructure and manage the +infrastructure lifecyle. It is relevant to anyone working with Terraform's CLI-based +workflows, including people who use Terraform CLI by itself, as well as those who +use Terraform CLI in conjunction with HCTP Terraform or Terraform Enterprise. -Notably, this documentation does not cover the syntax and usage of the Terraform -language. For that, see the -[Terraform Language Documentation](/terraform/language). +For information about the Terraform configuration language syntax and coding patters, refer to the +[Terraform configuration language documentation](/terraform/language). diff --git a/website/docs/cli/init/index.mdx b/website/docs/cli/init/index.mdx index 5b763eb9dad4..f91c7c089761 100644 --- a/website/docs/cli/init/index.mdx +++ b/website/docs/cli/init/index.mdx @@ -1,12 +1,10 @@ --- -page_title: Initializing Working Directories - Terraform CLI +page_title: Initialize the Terraform working directory description: >- - Working directories contain configurations, settings, cached plugins and - modules, and state data. Learn how to initialize and manage working - directories. + Learn how to initialize the working directory with the terraform init command, which installs plugins and modules defined in the configuration and retrieves state data. --- -# Initializing Working Directories +# Initialize the Working Directory Terraform expects to be invoked from a working directory that contains configuration files written in @@ -29,10 +27,9 @@ A Terraform working directory typically contains: record the last known backend configuration in case it needs to migrate state on the next run. This directory is automatically managed by Terraform, and is created during initialization. -- State data, if the configuration uses the default `local` backend. This is - managed by Terraform in a `terraform.tfstate` file (if the directory only uses - the default workspace) or a `terraform.tfstate.d` directory (if the directory - uses multiple workspaces). +- State data when the configuration uses the default `local` backend. Terraform manages state in a `terraform.tfstate` file when the directory only uses + the default workspace or a `terraform.tfstate.d` directory when the directory + uses multiple workspaces. ## Initialization diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx index 113594c58a5c..cd323c1724b1 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 infrastructure description: >- - Learn commands to inspect dependency information, outputs, etc. Use them for - integration or to understand your infrastructure. + The terraform inspect commands return dependency information and outputs. Learn how to use terraform inspect commands + to understand your infrastructure. --- -# Inspecting Infrastructure +# Inspect Infrastructure Commands Overview 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..492d238ea2e0 100644 --- a/website/docs/cli/install/apt.mdx +++ b/website/docs/cli/install/apt.mdx @@ -1,11 +1,10 @@ --- -page_title: APT Packages for Debian and Ubuntu +page_title: Install Terraform using APT packages for Debian and Ubuntu description: >- - The HashiCorp APT repositories contain distribution-specific Terraform - packages for both Debian and Ubuntu systems. + Learn how to install Terraform using HashiCorp APT packages for Debian and Ubuntu systems. --- -# APT Packages for Debian and Ubuntu +# Install Terraform Using 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, diff --git a/website/docs/cli/install/yum.mdx b/website/docs/cli/install/yum.mdx index 96e557ee279a..11c8ce2a53a7 100644 --- a/website/docs/cli/install/yum.mdx +++ b/website/docs/cli/install/yum.mdx @@ -1,11 +1,10 @@ --- -page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux' +page_title: Install Terraform using yum packages for Linux distributions description: >- - The HashiCorp Yum repositories contain distribution-specific Terraform - packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems. + Learn how to install Terraform using HashiCorp yum packages for Red Hat Enterprise Linux (RHEL), Fedora, CentOS, and Amazon Linux systems. --- -# Yum/DNF Packages for RHEL, CentOS, and Fedora +# Install Terraform Using Yum Packages for Linux Distributions The primary distribution packages for Terraform are `.zip` archives containing single executable files that you can extract anywhere on your system. However, diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.mdx index 67f6db2fb4b5..82f8bb3203ce 100644 --- a/website/docs/cli/plugins/index.mdx +++ b/website/docs/cli/plugins/index.mdx @@ -1,30 +1,27 @@ --- -page_title: Managing Plugins - Terraform CLI +page_title: Manage Terraform plugins description: >- - Commands to install, configure, and show information about providers. Also - commands to reduce install effort in air-gapped environments. + Providers are types of plugins for Terraform that manage infrastructure resources. Learn about managing plugins using the Terraform CLI. --- -# Managing Plugins +# Manage plugins overview -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. +This topic provides an overview of the how to manage plugins that Terraform relies on to manage various types +of resources. Providers are the only plugin type Terraform users interact with. Refer to [Providers](/terraform/language/providers) in the Terraform +language docs for additional information about providers. --> **Note:** Providers are the only plugin type most Terraform users interact with. Terraform also supports third-party provisioner plugins, but -we discourage their use. +## Workflow -Terraform installs any providers -[required](/terraform/language/providers/requirements) by a configuration -when [initializing](/terraform/cli/init) a working directory. By default, -this works without any additional interaction but requires network access to +When you initialize a working directory, Terraform installs any providers the Terraform configuration requires. Refer to +[Provider Requirements](/terraform/language/providers/requirements) in the Terraform configuration language information about requiring providers. Refer to the [`terraform init` command documentation](/terraform/cli/init) for additional information about how initialize the working directory. + +By default, Terraform initializes the working directory without any additional interaction, but you must have network access to download providers from their source registry. You can configure Terraform's provider installation behavior to limit or skip -network access, and to enable use of providers that aren't available through a -networked source. Terraform also includes some commands to show information -about providers and to reduce the effort of installing providers in air-gapped +network access, and to enable use of providers that are not available through a +networked source. Terraform also includes commands that show information +about providers and commands that reduce the effort of installing providers in air-gapped environments. ## Configuring Plugin Installation diff --git a/website/docs/cli/plugins/signing.mdx b/website/docs/cli/plugins/signing.mdx index 7eac2efd3020..bb2e69e92d5e 100644 --- a/website/docs/cli/plugins/signing.mdx +++ b/website/docs/cli/plugins/signing.mdx @@ -1,27 +1,29 @@ --- -page_title: Plugin Signing +page_title: Plugin signatures description: >- - Learn about the types of signatures providers can have on the Terraform - Registry. + Signatures help you determine the authenticity of the plugins you want to install. Learn about the types of signatures providers can have on the Terraform registry. --- -# Plugin Signing +# Plugin signatures -~> **Note** Terraform only authenticates provider plugins fetched from a registry. +This topic provides information about the types of signatures that can be built into plugins you install. 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: +## Types of plugin signatures -* **Signed by HashiCorp** - are built, signed, and supported by HashiCorp. -* **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has - verified the ownership of the private key and we provide a chain of trust to the CLI to verify this - programatically. -* **Self-signed** - are built, signed, and supported by a third party. HashiCorp does not provide a +Terraform providers installed from the registry are cryptographically signed. Terraform verifies the signature during installation. There are three types of signatures: + +* Providers signed by HashiCorp: HashiCorp builds, signs, and supports these providers. +* Providers signed by trusted partners: A third party builds, signs, and supports these providers. HashiCorp verifies the ownership of the private key and provides a chain of trust to the CLI to verify ownership programatically. +* Self-signed providers: A third party builds, signs, and supports these providers. HashiCorp does not provide a verification or chain of trust for the signature. You may obtain and validate fingerprints manually if you want to ensure you are using a binary you can trust. -Terraform does **NOT** support fetching and using unsigned binaries, but you can manually install -unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed. +## Unsigned binaries + +You cannot fetch and use unsigned binaries from the registry, but you can manually install unsigned binaries. We strongly recommend that you thoroughly vetting providers that you manually install so that these providers do not programatically authenticate. + +## Registry terms of use -Usage of plugins from the registry is subject to the Registry's [Terms of Use](https://registry.terraform.io/terms). +Use of plugins from the registry is subject to the registry's [terms of use](https://registry.terraform.io/terms). diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx index 3fc3538f98d5..bc57c38cd613 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.mdx @@ -1,25 +1,28 @@ --- -page_title: Provisioning Infrastructure - Terraform CLI -description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.' +page_title: Terraform workflow for provisioning infrastructure +description: Learn how to use the Terraform CLI to provision infrastructure. --- -# Provisioning Infrastructure with Terraform +# Terraform workflow for provisioning infrastructure -Terraform's primary function is to create, modify, and destroy infrastructure +This topic provides overview information about the Terraform workflow for provisioning infrastructure using the Terraform CLI. + +## Workflows + +You can use Terraform to create, modify, and destroy infrastructure resources to match the desired state described in a -[Terraform configuration](/terraform/language). +[Terraform configuration](/terraform/language). The +Terraform binary includes commands and subcommands for a wide variety of infrastructure lifecycle management +actions, but the following commands provide basic provisioning tasks: -When people refer to "running Terraform," they generally mean performing these -provisioning actions in order to affect real infrastructure objects. The -Terraform binary has many other subcommands for a wide variety of administrative -actions, but these basic provisioning tasks are the core of Terraform. +- `terrafrom plan` +- `terraform apply` +- `terraform destroy` -Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and -`destroy`. All of these commands require an -[initialized](/terraform/cli/init) working directory, and all of them act +All of these commands require an [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 +43,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 +59,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..1e419491d8f8 100644 --- a/website/docs/cli/state/index.mdx +++ b/website/docs/cli/state/index.mdx @@ -1,34 +1,32 @@ --- -page_title: Manipulating State - Terraform CLI +page_title: Update Terraform state manually description: >- - State data tracks which real-world object corresponds to each resource. - Inspect state, move or import resources, and more. + State data is the record of how real-world objects map to resources in the Terraform configuration. Learn how to manually update with state data. --- -# Manipulating Terraform State +# Update Terraform state manually overview + +This topic provides overview information about how to manually update state in Terraform. > **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. -Terraform uses [state data](/terraform/language/state) to remember which -real-world object corresponds to each resource in the configuration; -this allows it to modify an existing object when its resource declaration -changes. - -Terraform updates state automatically during plans and applies. However, it's -sometimes necessary to make deliberate adjustments to Terraform's state data, -usually to compensate for changes to the configuration or the real managed -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) - -~> **Important:** Modifying state data outside a normal plan or apply can cause -Terraform to lose track of managed resources, which might waste money, annoy -your colleagues, or even compromise the security of your operations. Make sure -to keep backups of your state data when modifying state out-of-band. +## Introduction + +Terraform stores information about real-world object that correspond to resources in the configuration as [state data](/terraform/language/state). +Doing so allows Terraform to modify an existing object when its resource declaration changes. + +Terraform automatically updates state when you run the `terraform plan` and `terraform apply` commands, but you may need to manually adjustment state data as a result of changes to the configuration or the real managed infrastructure. + +## Workflow + +Modifying state data outside of normal `terraform plan` or `terraform apply` operations can cause Terraform to lose track of managed resources, leading to increased costs, reduced productivity, or compromised security. Make sure to keep backups of your state data if you choose to manually modify state. + +You can use the Terraform CLI to perform the following state interations: + +- [Inspect state](/terraform/cli/state/inspect) +- [Re-create resources](/terraform/cli/state/taint) +- [Move resources](/terraform/cli/state/move) +- [Import existing resources](/terraform/cli/import) +- [Recover state from backup](/terraform/cli/state/recover) + + diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.mdx index 439a0646f836..74f200ca5089 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 -description: Commands that allow you to read and update state. +page_title: Inspect Terraform state +description: The `terraform state` group of commands help you inspect Terraform state. Learn how inspecting Terraform state can help you read and update state. --- -# Inspecting State +# Inspect Terraform State Overview 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..252184d103e8 100644 --- a/website/docs/cli/state/move.mdx +++ b/website/docs/cli/state/move.mdx @@ -1,11 +1,10 @@ --- -page_title: Moving Resources - Terraform CLI +page_title: Move resources description: >- - Commands that allow you to manage the way that resources are tracked in state. - They are helpful when you move or change resources. + Terraform state commands can move and remove resources and transfer existing resources to a different provider. Learn how about changing or moving 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..8189731d8892 100644 --- a/website/docs/cli/state/recover.mdx +++ b/website/docs/cli/state/recover.mdx @@ -1,25 +1,19 @@ --- -page_title: Recovering from State Disasters - Terraform CLI +page_title: Recover state from backup 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 state from backup overview + +This topic provides overview information about recovering Terraform state from a backup after a disaster, such as an accident when performing +other state manipulation actions. -If something has gone horribly wrong (possibly due to accidents when performing -other state manipulation actions), you might need to take drastic actions with -your state data. +## Workflow -- [The `terraform force-unlock` command](/terraform/cli/commands/force-unlock) can - override the protections Terraform uses to prevent two processes from - modifying state at the same time. You might need this if a Terraform process - (like a normal apply) is unexpectedly terminated (like by the complete - destruction of the VM it's running in) before it can release its lock on the - state backend. Do not run this until you are completely certain what happened - to the process that caused the lock to get stuck. +1. **Unlock Terraform**: You may need to unlock Terraform when a `terraform apply` or other process unexpectedly terminates before Terraform can release its lock on the state backend. Unlocking Terraform overrides protectionsthat prevent two processes from modifying state at the same time. We do not recommend unlocking until you determine what caused the lock to get stuck. -- [The `terraform state pull` command](/terraform/cli/commands/state/pull) and - [the `terraform state push` command](/terraform/cli/commands/state/push) can - directly read and write entire state files from and to the configured backend. - You might need this for obtaining or restoring a state backup. + Refer to the [`terraform force-unlock` command](/terraform/cli/commands/force-unlock) documentation for additional information. + +1. **Read state data**: Run the [`terraform state pull` command](/terraform/cli/commands/state/pull) to read the state files from the configured backend. +1. **Write state data**: Run the [`terraform state push` command](/terraform/cli/commands/state/push) to write state files to the configured backend. \ No newline at end of file diff --git a/website/docs/cli/state/resource-addressing.mdx b/website/docs/cli/state/resource-addressing.mdx index 48e3609a6539..04e4b756decb 100644 --- a/website/docs/cli/state/resource-addressing.mdx +++ b/website/docs/cli/state/resource-addressing.mdx @@ -1,11 +1,13 @@ --- -page_title: 'Internals: Resource Address' -description: |- - A resource address is a string that identifies zero or more resource - instances in your overall configuration. +page_title: Resource address reference +description: Use the resource address to reference specific instances of resources elsewhere in the configuration. Learn how Terraform creates addresses for resources. --- -# Resource Addressing +# Resource Address Reference + +This topic provides reference information about resource addresses in Terraform. + +## Syntax A _resource address_ is a string that identifies zero or more resource instances in your overall configuration. diff --git a/website/docs/cli/state/taint.mdx b/website/docs/cli/state/taint.mdx index dbf1229b9876..cb3e06d7dce3 100644 --- a/website/docs/cli/state/taint.mdx +++ b/website/docs/cli/state/taint.mdx @@ -1,25 +1,35 @@ --- -page_title: Forcing Re-creation of Resources - Terraform CLI -description: Commands that allow you to destroy and re-create resources manually. +page_title: Recreate resources +description: The -replace flag and taint command help you replace infrastructure objects. Learn how the -replace flag and taint command can help you recreate resources. --- -# Forcing Re-creation of Resources +# Recreate resources overview -During planning, by default Terraform retrieves the latest state of each -existing object and compares it with the current configuration, planning -actions only against objects whose current state does not match the -configuration. +This topic provides an overview of how to recreate resources in Terraform. -However, in some cases a remote object may become damaged or degraded in a -way that Terraform cannot automatically detect. For example, if software -running inside a virtual machine crashes but the virtual machine itself is -still running then Terraform will typically have no way to detect and respond -to the problem, because Terraform only directly manages the machine as a whole. +## Introduction -If you know that an object is damaged, or if you want to force Terraform to -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`: +By default, Terraform retrieves the latest state of each existing object and compares it with the current configuration when you run the `terraform apply` command. Terraform only takes action on objects that do not match the configuration. + +When remote objects become damaged or degraded, such as when software +running inside a virtual machine crashes but the virtual machine is +still running, Terraform does not have no way to detect and respond +to the problem. This is because Terraform only directly manages the machine as a whole. + +In some cases, Terraform can automatically infer that an object is in an +incomplete or degraded state. For example, when a complex object is partially created in the remote system or +when a provisioner step failed. When this occurs, Terraform automatically flags resources to recreate. + +You can manually replace objects when Terraform is unable to infer that an object should be replaced. + +## Workflows + +When you meed to replace an object, you can use the following methods. + +### Manually replace resources + +Add the [`-replace` flag](/terraform/cli/commands/plan#replace-address) +to your `terraform plan` or `terraform apply` command: ```shellsession $ terraform apply -replace="aws_instance.example" @@ -31,18 +41,9 @@ $ terraform apply -replace="aws_instance.example" } ``` -## The "tainted" status - -Sometimes Terraform is able to infer automatically that an object is in an -incomplete or degraded state. For example, if creation of a complex object -fails in such a way that parts of it already exist in the remote system, or -if object creation succeeded but a provisioner step subsequently failed, -Terraform must remember that the object exists but may not be fully-functional. +### Replace resource in `tainted` state -Terraform represents this situation by marking an object in the state as -"tainted". When an object is marked with this status, the next plan will force -replacing that object in a similar way to if you had specified that object's -address using `-replace=...` as described above. +Terraform applies the `tainted` status to objects in the state data when Terraform is able to infer that the object is in a degraded or damaged state. This status indicates that the object exists but may not be fully-functional. Terraform replaces objects in a `tainted` states during the next `plan` or `apply` operation. ``` # aws_instance.example is tainted, so must be replaced @@ -57,7 +58,7 @@ determination using [the `terraform untaint` command](/terraform/cli/commands/un after which Terraform will consider the object to be ready for use by any downstream resource declarations. -You can also _force_ Terraform to mark a particular object as tainted using +You can force Terraform to mark a particular object as tainted using [the `terraform taint` command](/terraform/cli/commands/taint), but that approach is deprecated in favor of the `-replace=...` option, which avoids the need to create an interim state snapshot with a tainted object. diff --git a/website/docs/cli/test/index.mdx b/website/docs/cli/test/index.mdx index 19a874aba0a5..08177edce984 100644 --- a/website/docs/cli/test/index.mdx +++ b/website/docs/cli/test/index.mdx @@ -1,43 +1,37 @@ --- -page_title: Testing Terraform - Terraform CLI +page_title: Testing features in Terraform description: >- - Write structured tests and validations for your configuration to ensure + Learn about the terraform test command, which runs structured tests and validations for your configuration to ensure correctness in your infrastructure. --- -# Testing Terraform +# Testing features in Terraform overview -Terraform provides numerous testing capabilities to validate your infrastructure. +This topic provides an overview of the testing features in Terraform to help you validate your infrastructure. -These testing capabilities fit into two main categories: +## Introduction -1. Validating your configuration and infrastructure as part of your regular Terraform operations. -2. Performing traditional unit and integration testing on your configuration. +Terraform provides the following types of testing capabilities: -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. +1. Configuration and infrastructure validation as part of your regular Terraform operations. Refer to [Custom Conditions](/terraform/language/expressions/custom-conditions) and [Checks](/terraform/language/checks) to learn more about these types of testing capabilities. +1. Traditional unit and integration testing on your configuration. Refer to the [`terraform test` command](/terraform/cli/commands/test) documentation to learn more about this testing capability. -## A brief history +### Additional testing and validation features -The various testing capabilities were introduced in the following versions: +- [Input Variable Validation](/terraform/language/expressions/custom-conditions#input-variable-validation) +- [Pre and Post-conditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) +- [Checks](/terraform/language/checks) -- Terraform v0.13.0 introduced [Input Variable Validation](/terraform/language/expressions/custom-conditions#input-variable-validation). -- Terraform v0.15.0 introduced an experimental Terraform [`test`](/terraform/language/v1.5.x/modules/testing-experiment) command. -- Terraform v1.2.0 introduced [Pre and Post-conditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions). -- Terraform v1.5.0 introduced [Checks](/terraform/language/checks). -- Terraform v1.6.0 deprecated the experimental Terraform `test` command, and released an updated and finalized Terraform [`test`](/terraform/cli/commands/test) command. +## How the `terraform test` command works -Note the introduction and deprecation of the experimental `test` command, followed by the introduction of the finalized `test` command. Refer to the [v1.6.x Upgrade Guide](/terraform/language/v1.6.x/upgrade-guides) for a summary of the changes between the experimental and finalized command. - -## The `test` command - -The Terraform `test` command: +The `test` command performs the following actions: - Locates Terraform testing files within your configuration directory. - Provisions the infrastructure within your configuration as specified by each testing file. - Runs the assertions from the test file against the provisioned infrastructure. - Destroys the provisioned infrastructure at the end of the test. -The `test` command, along with command-line flags and options, is discussed in detail within [Command: test](/terraform/cli/commands/test). +For details about using the `test` command, refer to the [`test` command reference documentation](/terraform/cli/commands/test). ### Write configuration for tests @@ -49,7 +43,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 versus 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 77feaba78437..3baca17bd462 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -1,11 +1,10 @@ --- -page_title: Managing Workspaces - Terraform CLI +page_title: Manage workspaces description: >- - Commands to list, select, create, and output workspaces. Workspaces help - manage different groups of resources with one configuration. + Workspaces are separate instances of Terraform state data. Learn commands for managing workspaces. --- -# Managing Workspaces +# Manage Workspaces Overview 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. diff --git a/website/docs/internals/credentials-helpers.mdx b/website/docs/internals/credentials-helpers.mdx index c9caa6ceb72d..a65d63921b74 100644 --- a/website/docs/internals/credentials-helpers.mdx +++ b/website/docs/internals/credentials-helpers.mdx @@ -1,11 +1,17 @@ --- -page_title: Credentials Helpers +page_title: Create Credentials Helpers description: >- - Credentials helpers are external programs that know how to store and retrieve - API tokens for remote Terraform services. + Credentials helpers are external programs that can store and retrieve + API tokens for remote Terraform services. Learn how to create credentials helpers. --- -# Credentials Helpers +# Create Credentials Helpers + +This topic describes how to write and install a credentials helper so that you can customize how Terraform obtains credentials. To learn +how to configure a credentials helper that was already installed, refer to +[Credentials Helpers](/terraform/cli/config/config-file#credentials-helpers) in the Terraform CLI documentation. + +## Introduction For Terraform-specific features that interact with remote network services, such as [module registries](/terraform/registry) and @@ -17,10 +23,6 @@ Credentials helpers offer an alternative approach that allows you to customize how Terraform obtains credentials using an external program, which can then directly access an existing secrets management system in your organization. -This page is about how to write and install a credentials helper. To learn -how to configure a credentials helper that was already installed, see -[the CLI config Credentials Helpers section](/terraform/cli/config/config-file#credentials-helpers). - ## How Terraform finds Credentials Helpers A credentials helper is a normal executable program that is installed in a diff --git a/website/docs/internals/debugging.mdx b/website/docs/internals/debugging.mdx index 7734519d9520..31e9ba4d750f 100644 --- a/website/docs/internals/debugging.mdx +++ b/website/docs/internals/debugging.mdx @@ -1,15 +1,17 @@ --- -page_title: Debugging +page_title: Enable logs to debug Terraform description: >- - Terraform has detailed logs which can be enabled by setting the TF_LOG - environment variable to any value. This will cause detailed logs to appear on - stderr + Enable Terraform to generate logs so that you can debug unexpected behaviors. --- -# Debugging Terraform +# Enable Terraform logs + +This topic describes how to enable Terraform logs so that you can debug unexpected behaviors. > **Hands-on:** Try the [Create Dynamic Expressions](/terraform/tutorials/configuration-language/troubleshooting-workflow#bug-reporting-best-practices?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +## Set the `TF_LOG` variable + Terraform has detailed logs that you can enable by setting the `TF_LOG` environment variable to any value. Enabling this setting causes detailed logs to appear on `stderr`. You can set `TF_LOG` to one of the log levels (in order of decreasing verbosity) `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR` to change the verbosity of the logs. @@ -18,6 +20,8 @@ Setting `TF_LOG` to `JSON` outputs logs at the `TRACE` level or higher, and uses ~> **Warning:** The JSON encoding of log files is not considered a stable interface. It may change at any time, without warning. It is meant to support tooling that will be forthcoming, and that tooling is the only supported way to interact with JSON formatted logs. +## Set the `TF_LOG_CORE` variable + Logging can be enabled separately for Terraform itself and the provider plugins using the `TF_LOG_CORE` or `TF_LOG_PROVIDER` environment variables. These take the same level arguments as `TF_LOG`, but only activate a subset of the logs. diff --git a/website/docs/internals/functions-meta.mdx b/website/docs/internals/functions-meta.mdx index 734a341d25db..b227843f72a4 100644 --- a/website/docs/internals/functions-meta.mdx +++ b/website/docs/internals/functions-meta.mdx @@ -1,13 +1,13 @@ --- -page_title: Functions Metadata +page_title: terraform metadata functions command reference description: >- The `terraform metadata functions` command prints signatures for all the functions available in the current Terraform version. --- -# Functions Metadata +# `terraform metadata functions` command -The `terraform metadata functions` command is used to print signatures for the functions available in the current Terraform version. +The `terraform metadata functions` command prints signatures for the functions available in the current Terraform version. -> `terraform metadata functions` requires **Terraform v1.4 or later**. diff --git a/website/docs/internals/graph.mdx b/website/docs/internals/graph.mdx index 77b99a7f6d97..087be693da64 100644 --- a/website/docs/internals/graph.mdx +++ b/website/docs/internals/graph.mdx @@ -1,38 +1,24 @@ --- -page_title: Resource Graph +page_title: Dependency Graph description: >- - Terraform builds a dependency graph from the Terraform configurations, and - walks this graph to generate plans, refresh state, and more. This page - documents the details of what are contained in this graph, what types of nodes - there are, and how the edges of the graph are determined. + Learn how Terraform builds a dependency graph from the Terraform configurations and + uses the graph to generate plans, refresh state, perform other operations. --- -# Resource Graph +# Dependency Graph -Terraform builds a -[dependency graph](https://en.wikipedia.org/wiki/Dependency_graph) -from the Terraform configurations, and walks this graph to -generate plans, refresh state, and more. This page documents -the details of what are contained in this graph, what types -of nodes there are, and how the edges of the graph are determined. +This topic explains the dependency graph Terraform builds from Terraform configurations. This is an advanced topic and not required to understand how to use Terraform. -~> **Advanced Topic!** This page covers technical details -of Terraform. You don't need to understand these details to -effectively use Terraform. The details are documented here for -those who wish to learn about them without having to go -spelunking through the source code. +## Introduction -For some background on graph theory, and a summary of how -Terraform applies it, see the HashiCorp 2016 presentation +Terraform builds a dependency graph and uses it to perform operations, such as generate plans and refresh state. +For background on graph theory and a summary of how +Terraform applies it, refer the HashiCorp 2016 presentation [_Applying Graph Theory to Infrastructure as Code_](https://www.youtube.com/watch?v=Ce3RNfRbdZ0). -This presentation also covers some similar ideas to the following -guide. ## Graph Nodes -There are only a handful of node types that can exist within the -graph. We'll cover these first before explaining how they're -determined and built: +The following node types can exist within the graph: - **Resource Node** - Represents a single resource. If you have the `count` metaparameter set, then there will be one resource diff --git a/website/docs/internals/index.mdx b/website/docs/internals/index.mdx index eebfa5bb0114..f025c4b7d09f 100644 --- a/website/docs/internals/index.mdx +++ b/website/docs/internals/index.mdx @@ -1,17 +1,11 @@ --- -page_title: Internals +page_title: Terraform internals description: >- - Learn how Terraform generates the resource dependency graph and executes other internal processes. + Learn about internal Terraform processes, such as generating the resource dependency graph. --- -# Terraform Internals +# Terraform internals overview -This section covers the internals of Terraform and explains how -plans are generated, the lifecycle of a provider, etc. The goal -of this section is to remove any notion of "magic" from Terraform. -We want you to be able to trust and understand what Terraform is -doing to function. - --> **Note:** Knowledge of Terraform internals is not -required to use Terraform. If you aren't interested in the internals -of Terraform, you may safely skip this section. +This topic provides overview information about the internals of Terraform. +Topics in this section explain how Terraform generates plans and describe the provider lifecycle. +You do not have to understand Terraform internals to use Terraform. diff --git a/website/docs/internals/json-format.mdx b/website/docs/internals/json-format.mdx index d4cedf2c12e1..815f89afab10 100644 --- a/website/docs/internals/json-format.mdx +++ b/website/docs/internals/json-format.mdx @@ -1,17 +1,18 @@ --- -page_title: 'Internals: JSON Output Format' +page_title: JSON output format description: >- - Terraform provides a machine-readable JSON representation of state, - configuration and plan. + Learn how to configure Terraform to print JSON-formatted details about state, configuration, and proposed infrastructure plans. --- -# JSON Output Format +# JSON Output Format Overview --> **Note:** This format is available in Terraform 0.12 and later. +This topic provides overview information about the JSON output Terraform prints to the terminal. + +## Introduction When Terraform plans to make changes, it prints a human-readable summary to the terminal. It can also, when run with `-out=`, write a much more detailed binary plan file, which can later be used to apply those changes. -Since the format of plan files isn't suited for use with external tools (and likely never will be), Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. +Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. Use `terraform show -json ` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/terraform/cli/commands/show) for more details. @@ -25,9 +26,6 @@ value `"1.0"`. The semantics of this version are: backward-compatible. Reject any input which reports an unsupported major version. -We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). - ## Format Summary The following sections describe the JSON output format by example, using a pseudo-JSON notation. diff --git a/website/docs/internals/login-protocol.mdx b/website/docs/internals/login-protocol.mdx index 1350239f54e3..c3394866deb5 100644 --- a/website/docs/internals/login-protocol.mdx +++ b/website/docs/internals/login-protocol.mdx @@ -1,16 +1,14 @@ --- -page_title: Login Protocol +page_title: Login protocol reference description: >- - The login protocol is used for authenticating Terraform against servers - providing Terraform-native services. + The login protocol authenticates Terraform against servers that provide Terraform-native services. Learn about the login protocol. --- -# Server-side Login Protocol +# Login Protocol Reference -~> **Note:** You don't need to read these docs to _use_ -[`terraform login`](/terraform/cli/commands/login). The information below is for -anyone intending to implement the server side of `terraform login` in order to -offer Terraform-native services in a third-party system. +This topic provides reference information about the login protocol Terraform uses for authentication against servers that profide Terraform-native services. You can use this reference information to offer Terraform-native services in a third-party system. + +## Introduction The `terraform login` command supports performing an OAuth 2.0 authorization request using configuration provided by the target host. You may wish to @@ -18,11 +16,12 @@ implement this protocol if you are producing a third-party implementation of any [Terraform-native services](/terraform/internals/remote-service-discovery), such as a Terraform module registry. -First, Terraform uses -[remote service discovery](/terraform/internals/remote-service-discovery) to +## OAuth Configuration + +Terraform uses [remote service discovery](/terraform/internals/remote-service-discovery) to find the OAuth configuration for the host. The host must support the service name `login.v1` and define for it an object containing OAuth client -configuration values, like this: +configuration values. The following example describes a client that authenticates at ports `10000` and `10010`: ```json { diff --git a/website/docs/internals/machine-readable-ui.mdx b/website/docs/internals/machine-readable-ui.mdx index a2979246f9e3..05f4c20fb2da 100644 --- a/website/docs/internals/machine-readable-ui.mdx +++ b/website/docs/internals/machine-readable-ui.mdx @@ -1,17 +1,18 @@ --- -page_title: 'Internals: Machine-Readable UI' +page_title: Machine-readable output reference description: >- - Terraform provides a machine-readable streaming JSON UI output for plan, - apply, and refresh operations. + Terraform streams machine-readable output in JSON format, letting you use third-party tools to monitor operations. --- -# Machine-Readable UI +# Machine-readable UI Output Reference --> **Note:** This format is available in Terraform 0.15.3 and later. +This topic provides reference information about the machine-readable output Terraform prints. -By default, many Terraform commands display UI output as unstructured text, intended to be read by a user via a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface. +## Introduction -For long-running commands such as `plan`, `apply`, `refresh`, and `test`, the `-json` flag outputs a stream of JSON UI messages, one per line. These can be processed one message at a time, with integrating software filtering, combining, or modifying the output as desired. +By default, many Terraform commands display UI output as unstructured text that is intended to be read in a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface. + +For long-running commands such as `plan`, `apply`, `refresh`, and `test`, the `-json` flag outputs a stream of JSON UI messages. The ouptut messages appear one per line so that you can process the messages by integrating software filtering, combining, or modifying the output as desired. The first message output has type `version`, and includes a `ui` key, which as of Terraform 1.1.0 has value `"1.0"`. The semantics of this version are: @@ -23,8 +24,8 @@ value `"1.0"`. The semantics of this version are: backward-compatible. Reject any input which reports an unsupported major version. -We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). +Refer to +[Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises) for additional information. ## Sample JSON Output diff --git a/website/docs/internals/module-registry-protocol.mdx b/website/docs/internals/module-registry-protocol.mdx index 8edd97b084d5..71ceff93a93d 100644 --- a/website/docs/internals/module-registry-protocol.mdx +++ b/website/docs/internals/module-registry-protocol.mdx @@ -1,16 +1,18 @@ --- -page_title: Module Registry Protocol +page_title: Module registry protocol reference description: |- - The module registry protocol is implemented by a host intending to be the - host of one or more Terraform modules, specifying which modules are available - and where to find their distribution packages. + Terraform discovers modules available for installation using the module registry protocol. Learn about the module registry protocol so consumers can find your modules. --- -# Module Registry Protocol +# Module Registry Protocol Reference + +This topic provides reference information about the module registry protocol. -> Third-party module registries are supported only in Terraform CLI 0.11 and later. Prior versions do not support this protocol. -The module registry protocol is what Terraform CLI uses to discover metadata +## Introduction + +The Terraform CLI uses the module registry protocol to discover metadata about modules available for installation and to locate the distribution package for a selected module. diff --git a/website/docs/internals/provider-meta.mdx b/website/docs/internals/provider-meta.mdx index 0e25a8f41208..50bb31dbf393 100644 --- a/website/docs/internals/provider-meta.mdx +++ b/website/docs/internals/provider-meta.mdx @@ -1,39 +1,36 @@ --- -page_title: Provider Metadata +page_title: Collect Provider Metadata description: >- - For advanced use cases, modules can provide some pre-defined metadata for - providers. + Provider developers can enable the modules created for the their providers to collect provider metadata. --- -# Provider Metadata +# Collect Provider Metadata -In some situations it's beneficial for a provider to offer an interface +This topic describes how to create an inferface in the providers you develop that allows you to collect metadata that is unrelated to the resources in the module, such as usage statistics. This is an advanced topic and is not required to use Terraform. + +## Introduction + +In some situations it is beneficial for a provider to offer an interface through which modules can pass it information unrelated to the resources in the module, but scoped on a per-module basis. -Provider Metadata allows a provider to declare metadata fields it expects, +Provider metadata allows a provider to declare metadata fields it expects, which individual modules can then populate independently of any provider configuration. While provider configurations are often shared between modules, provider metadata is always module-specific. -Provider Metadata is intended primarily for the situation where an official +Provider metadata is intended primarily for the situation where an official module is developed by the same vendor that produced the provider it is intended to work with, to allow the vendor to indirectly obtain usage statistics for each module via the provider. For that reason, this documentation is presented from the perspective of the provider developer rather than the module developer. -~> **Advanced Topic!** This page covers technical details -of Terraform. You don't need to understand these details to -effectively use Terraform. The details are documented here for -module authors and provider developers working on advanced -functionality. -~> **Experimental Feature!** This functionality is still considered -experimental, and anyone taking advantage of it should [coordinate +~> **Experimental Feature:** This functionality is +experimental. You should [coordinate with the Terraform team](https://github.com/hashicorp/terraform/issues/new) -to help the team understand how the feature is being used and to make -sure their use case is taken into account as the feature develops. +so that they can understand how you are using this functionality. Doing so ensures that your use cases are taken into account as the feature evolves. ## Defining the Schema diff --git a/website/docs/internals/provider-network-mirror-protocol.mdx b/website/docs/internals/provider-network-mirror-protocol.mdx index 89ea2652620b..7178de4725e9 100644 --- a/website/docs/internals/provider-network-mirror-protocol.mdx +++ b/website/docs/internals/provider-network-mirror-protocol.mdx @@ -1,19 +1,16 @@ --- -page_title: Provider Network Mirror Protocol +page_title: Provider network mirror protocol reference description: |- - The provider network mirror protocol is implemented by a server intending - to provide a mirror or read-through caching proxy for Terraform providers, - as an alternative distribution source from the provider's origin provider - registry. + The provider network mirror protocol lets you provide an alternate installation source for your providers. Learn about the provider network mirror protocol. --- -# Provider Network Mirror Protocol +# Provider Network Mirror Protocol Reference + +This topic provides reference information about the provider network mirror protocol. You can implement an alternative installation source for Terraform providers and make the source available over the provider network mirror protocol, regardless of their origin registries. -> Provider network mirrors are supported only in Terraform CLI v0.13.2 and later. Prior versions do not support this protocol. -The provider network mirror protocol is an optional protocol which you can -implement to provide an alternative installation source for Terraform providers, -regardless of their origin registries. +## Introduction Terraform uses network mirrors only if you activate them explicitly in [the CLI configuration's `provider_installation` block](/terraform/cli/config/config-file#provider-installation). diff --git a/website/docs/internals/provider-registry-protocol.mdx b/website/docs/internals/provider-registry-protocol.mdx index e344d88e7fe7..a8acc4e948a4 100644 --- a/website/docs/internals/provider-registry-protocol.mdx +++ b/website/docs/internals/provider-registry-protocol.mdx @@ -1,18 +1,14 @@ --- -page_title: Provider Registry Protocol +page_title: Provider registry protocol reference description: |- - The provider registry protocol is implemented by a host intending to be the - origin host for one or more Terraform providers, specifying which providers - are available and where to find their distribution packages. + Use the provider registry protocol to enable Terraform to discover metadata about available providers and locate their distribution packages. --- -# Provider Registry Protocol +# Provider Registry Protocol Reference --> Third-party provider registries are supported only in Terraform CLI 0.13 and later. Prior versions do not support this protocol. +This topic provides reference information about the provider registry protocol. The protocol allows the Terraform CLI to discover metadata about the providers available for installation and to locate the distribution packages for a selected provider. -The provider registry protocol is what Terraform CLI uses to discover metadata -about providers available for installation and to locate the distribution -packages for a selected provider. +## Introduction The primary implementation of this protocol is the public [Terraform Registry](https://registry.terraform.io/) at `registry.terraform.io`. diff --git a/website/docs/internals/remote-service-discovery.mdx b/website/docs/internals/remote-service-discovery.mdx index 04c2a9847817..5aeb17888c3c 100644 --- a/website/docs/internals/remote-service-discovery.mdx +++ b/website/docs/internals/remote-service-discovery.mdx @@ -1,22 +1,23 @@ --- -page_title: 'Internals: Remote Service Discovery' +page_title: Remote service discovery protocol reference description: |- - Remote service discovery is a protocol used to locate Terraform-native - services provided at a user-friendly hostname. + The remote service discovery protocol presents Terraform-native services at a human-readable hostname. Learn about the remote service discovery protocol. --- -# Remote Service Discovery +# Remote Service Discovery Protocol Reference -Terraform implements much of its functionality in terms of remote services. -While in many cases these are generic third-party services that are useful -to many applications, some of these services are tailored specifically to -Terraform's needs. We call these _Terraform-native services_, and Terraform -interacts with them via the remote service discovery protocol described below. +This topic provides reference information about the remote service discovery protocol in Terraform. + +## Introduction + +Terraform implements much of its functionality as remote services. +Some of these are native services that Terraform +interacts with through the remote service discovery protocol. ## User-facing Hostname -Terraform-native services are provided, from a user's perspective, at a -user-facing "friendly hostname" which serves as the key for configuration and +Terraform provides native services at a +human-readable hostname. The hostname is the key for configuration and for any authentication credentials required. The discovery protocol's purpose is to map from a user-provided hostname to diff --git a/website/docs/intro/core-workflow.mdx b/website/docs/intro/core-workflow.mdx index de38b00aeaf0..3d49b7db394c 100644 --- a/website/docs/intro/core-workflow.mdx +++ b/website/docs/intro/core-workflow.mdx @@ -1,9 +1,9 @@ --- -page_title: The Core Terraform Workflow - Guides -description: 'An overview of how individuals, teams, and organizations can use Terraform. ' +page_title: Overview of the core Terraform workflow +description: Learn how to provision and manage infrastructure using the core Terraform workflow for individuals, teams, and organizations. --- -# The Core Terraform Workflow +# Core Terraform Workflow Overview The core Terraform workflow has three steps: diff --git a/website/docs/intro/index.mdx b/website/docs/intro/index.mdx index a9e48c790932..8d3172ded3bf 100644 --- a/website/docs/intro/index.mdx +++ b/website/docs/intro/index.mdx @@ -1,6 +1,6 @@ --- layout: "intro" -page_title: "What is Terraform" +page_title: What is Terraform sidebar_current: "what" description: |- Terraform is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently. diff --git a/website/docs/intro/terraform-editions.mdx b/website/docs/intro/terraform-editions.mdx index c8c2305ea7c9..0d3962b153af 100644 --- a/website/docs/intro/terraform-editions.mdx +++ b/website/docs/intro/terraform-editions.mdx @@ -3,10 +3,10 @@ layout: "intro" page_title: "Terraform Editions" sidebar_current: "what" description: |- - Terraform Community Edition, HCP Terraform, and Terraform Enterprise solve increasingly complex infrastructure and collaboration challenges. + Learn how Terraform Community Edition, HCP Terraform, and Terraform Enterprise solve increasingly complex infrastructure and collaboration challenges. --- -# Terraform Editions +# Terraform Editions Overview As your organization adopts infrastructure as code (IaC), you will encounter increasingly complex technical and collaboration challenges. We offer three Terraform editions designed to help you solve them. diff --git a/website/docs/intro/use-cases.mdx b/website/docs/intro/use-cases.mdx index a306acef1279..b858238e2e22 100644 --- a/website/docs/intro/use-cases.mdx +++ b/website/docs/intro/use-cases.mdx @@ -3,10 +3,10 @@ layout: "intro" page_title: "Use Cases" sidebar_current: "use-cases" description: |- - Learn how Terraform enables multi-cloud deployments, application management, policy compliance, and self-service infrastructure. + Learn about Terraform use cases, such as enabling multi-cloud deployments, application management, policy compliance, and self-service infrastructure. --- -# Use Cases +# Terraform Use Cases [HashiCorp Terraform](/terraform/intro) is an infrastructure as code tool that lets you define infrastructure resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to safely and efficiently provision and manage your infrastructure throughout its lifecycle. diff --git a/website/docs/intro/vs/boto.mdx b/website/docs/intro/vs/boto.mdx index de008b8dced4..698e10a28dc4 100644 --- a/website/docs/intro/vs/boto.mdx +++ b/website/docs/intro/vs/boto.mdx @@ -1,9 +1,9 @@ --- -page_title: 'Terraform vs. Boto, Fog, etc.' -description: 'How Terraform compares to cloud provider client libraries like Boto and Fog. ' +page_title: Terraform versus Boto, Fog, and other cloud provider client libraries +description: Learn how Terraform's syntax compares to Boto, Flog, and other cloud provider client libraries. --- -# Terraform vs. Boto, Fog, etc. +# Terraform versus Boto, Fog, and other cloud provider client libraries Libraries like Boto, Fog, etc. are used to provide native access to cloud providers and services by using their APIs. Some diff --git a/website/docs/intro/vs/cloudformation.mdx b/website/docs/intro/vs/cloudformation.mdx index a677ec089a3b..eaa57524da43 100644 --- a/website/docs/intro/vs/cloudformation.mdx +++ b/website/docs/intro/vs/cloudformation.mdx @@ -1,15 +1,13 @@ --- -page_title: 'Terraform vs. CloudFormation, Heat, etc.' +page_title: Terraform versus CloudFormation, Heat, and other infrastructure as code tools description: >- - How Terraform compares to other infrastructure as code tools like - CloudFormation and Heat. Terraform can simultaneously manage multiple cloud - providers (AWS, OpenStack, etc.) and services (Cloudflare, DNSimple, etc.). + Learn how Terraform manages various cloud providers and services, such as AWS, OpenStack, Cloudflare, and DNSimple, versus CloudFormation, Heat, and other tools. --- -# Terraform vs. CloudFormation, Heat, etc. +# Terraform versus CloudFormation, Heat, and other infrastructure as code tools -Tools like CloudFormation, Heat, etc. allow the details of an infrastructure -to be codified into a configuration file. The configuration files allow +CloudFormation, Heat, and other infrastructure as code tools allow you to codify the details of infrastructure +into a configuration file. The configuration files allow the infrastructure to be elastically created, modified and destroyed. Terraform is inspired by the problems they solve. diff --git a/website/docs/intro/vs/custom.mdx b/website/docs/intro/vs/custom.mdx index dbc96e480ad7..32b18d6eb840 100644 --- a/website/docs/intro/vs/custom.mdx +++ b/website/docs/intro/vs/custom.mdx @@ -1,11 +1,10 @@ --- -page_title: Terraform vs. Custom Solutions +page_title: Terraform versus Custom Solutions description: >- - Why Terraform is easier to use and maintain than custom, internal - infrastructure solutions. + Learn how the Terraform syntax enables to Terraform binary to overcome challenges of custom infrastructure as code solutions. --- -# Terraform vs. Custom Solutions +# Terraform versus Custom Solutions Most organizations start by manually managing infrastructure through simple scripts or web-based interfaces. As the infrastructure grows, diff --git a/website/docs/intro/vs/index.mdx b/website/docs/intro/vs/index.mdx index 0a809d77f3d1..3504ffacb41e 100644 --- a/website/docs/intro/vs/index.mdx +++ b/website/docs/intro/vs/index.mdx @@ -1,9 +1,9 @@ --- -page_title: Terraform vs. Alternatives -description: An overview of how Terraform compares to alternative software and tools. +page_title: Terraform versus alternatives overview +description: Terraform lets you define infrastructure as code and automate infrastructure lifecycle management. Learn how Terraform compares to other cloud infrastructure tools. --- -# Terraform vs. Alternatives +# Terraform versus Alternatives Overview Terraform provides a flexible abstraction of resources and providers. This model allows for representing everything from physical hardware, virtual machines, and