diff --git a/website/README.md b/website/README.md index 53a5d9be5..036fa3c35 100644 --- a/website/README.md +++ b/website/README.md @@ -8,39 +8,36 @@ The files in this directory are intended to be used in conjunction with different documentation sources together and contains the scripts for testing and building the site as a whole. +## Modifying Sidebar Navigation + +Updates to the sidebar navigation of Terraform docs need to be made in the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository (preferrably in a PR also updating the submodule commit). You can read more about how to make modifications to the navigation in the [README for `terraform-website`](https://github.com/hashicorp/terraform-website#editing-navigation-sidebars). + ## Previewing Changes -You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site. If `terraform-website` isn't in your `GOPATH`, the preview command will clone it to your machine. +You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site. **Set Up Local Environment** 1. [Install Docker](https://docs.docker.com/get-docker/). -2. Create a `~/go` directory manually or by [installing Go](https://golang.org/doc/install). -3. Open terminal and set `GOPATH` as an environment variable: - - Bash: `export $GOPATH=~/go`(bash) - - Zsh: `echo -n 'export GOPATH=~/go' >> ~/.zshrc` -4. Restart your terminal or command line session. +1. Restart your terminal or command line session. **Launch Site Locally** 1. Navigate into your local `terraform` top-level directory and run `make website`. -2. Open `http://localhost:4567` in your web browser. While the preview is running, you can edit pages and Middleman will automatically rebuild them. -3. When you're done with the preview, press `ctrl-C` in your terminal to stop the server. +1. Open `http://localhost:4567` in your web browser. While the preview is running, you can edit pages and Next.js will automatically rebuild them. +1. When you're done with the preview, press `ctrl-C` in your terminal to stop the server. ## Deploying Changes Merge the PR to main. The changes will appear in the next major Terraform release. If you need your changes to be deployed sooner, cherry-pick them to: -- the current release branch (e.g. `v1.0`) and push. They will be deployed in the next minor version release (once every two weeks). -- the `stable-website` branch and push. They will be included in the next site deploy (see below). Note that the release process resets `stable-website` to match the release tag, removing any additional commits. So, we recommend always cherry-picking to the version branch first and then to `stable-website` when needed. + +- the current release branch (e.g. `v1.1`) and push. They will be deployed in the next minor version release (once every two weeks). +- the `stable-website` branch and push. They will be included in the next site deploy (see below). Note that the release process resets `stable-website` to match the release tag, removing any additional commits. So, we recommend always cherry-picking to the version branch first and then to `stable-website` when needed. + +Once your PR to `stable-website` is merged, open a PR bumping the submodule commit in [`terraform-website`](https://github.com/hashicorp/terraform-website). ### Deployment -Currently, HashiCorp uses a CircleCI job to deploy the [terraform.io](terraform.io) site. This job can be run manually by many people within HashiCorp, and also runs automatically whenever a user in the HashiCorp GitHub org merges changes to master in the `terraform-website` repository. -New commits in this repository don't automatically deploy the [terraform.io][] site, but an unrelated site deploy will usually happen within a day. If you can't wait that long, you can do a manual CircleCI build or ask someone in the #proj-terraform-docs channel to do so: -- Log in to circleci.com, and make sure you're viewing the HashiCorp organization. -- Go to the terraform-website project's list of workflows. -- Find the most recent "website-deploy" workflow, and click the "Rerun workflow from start" button (which looks like a refresh button with a numeral "1" inside). +New commits in `hashicorp/terraform` and `hashicorp/terraform-cdk` don't automatically deploy the site. To use the latest upstream content, you'll need to open a PR bumping the submodule commit. If your changes aren't being deployed, it's very likely that you need to open a PR to update the submodule commit. diff --git a/website/docs/cli/auth/index.html.md b/website/docs/cli/auth/index.mdx similarity index 64% rename from website/docs/cli/auth/index.html.md rename to website/docs/cli/auth/index.mdx index cb61fbcdf..0b2247365 100644 --- a/website/docs/cli/auth/index.html.md +++ b/website/docs/cli/auth/index.mdx @@ -1,21 +1,22 @@ --- -layout: "docs" -page_title: "Authentication - Terraform CLI" -description: "Documentation about the login and logout commands that help automate getting an API token for your Terraform Cloud account." +page_title: Authentication - Terraform CLI +description: >- + Documentation about the login and logout commands that help automate getting + an API token for your Terraform Cloud account. --- # CLI Authentication > **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-login?in=terraform/cloud&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. -[Terraform Cloud](/docs/cloud/index.html) and -[Terraform Enterprise](/docs/enterprise/index.html) are platforms that perform +[Terraform Cloud](/cloud) and +[Terraform Enterprise](/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 "Terraform Cloud.") Terraform CLI integrates with Terraform Cloud in several ways — it can be a -front-end for [CLI-driven runs](/docs/cloud/run/cli.html) in Terraform Cloud, +front-end for [CLI-driven runs](/cloud-docs/run/cli) in Terraform Cloud, and can also use Terraform Cloud as a state backend and a private module registry. All of these integrations require you to authenticate Terraform CLI with your Terraform Cloud account. @@ -26,5 +27,5 @@ Terraform Cloud user account. For details, see: -- [The `terraform login` command](/docs/cli/commands/login.html) -- [The `terraform logout` command](/docs/cli/commands/logout.html) +- [The `terraform login` command](/cli/commands/login) +- [The `terraform logout` command](/cli/commands/logout) diff --git a/website/docs/cli/cloud/command-line-arguments.html.md b/website/docs/cli/cloud/command-line-arguments.html.md deleted file mode 100644 index aceebbbd1..000000000 --- a/website/docs/cli/cloud/command-line-arguments.html.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: "docs" -page_title: "Command Line Arguments" -description: "Command Line Arguments" ---- - -# Command Line Arguments - -When your configuration includes a `cloud` block, commands that -make local modifications to Terraform state and then push them back up to the remote workspace -accept the following option to modify that behavior: - -- `-ignore-remote-version` - Override checking that the local and remote - Terraform versions agree, making an operation proceed even when there is - a mismatch. - - State-modification operations usually require using a local version of the - Terraform CLI that is compatible with the Terraform version selected - in the remote workspace settings. This prevents the - local operation from creating a new state snapshot that the workspace's - remote execution environment cannot decode. - - We recommend against using this option unless absolutely necessary. Overriding this check can result - in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently - selected version of Terraform. - diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx new file mode 100644 index 000000000..81897cfe6 --- /dev/null +++ b/website/docs/cli/cloud/command-line-arguments.mdx @@ -0,0 +1,24 @@ +--- +page_title: Command Line Arguments +description: Command Line Arguments +--- + +# Command Line Arguments + +When your configuration includes a `cloud` block, commands that +make local modifications to Terraform state and then push them back up to the remote workspace +accept the following option to modify that behavior: + +- `-ignore-remote-version` - Override checking that the local and remote + Terraform versions agree, making an operation proceed even when there is + a mismatch. + + State-modification operations usually require using a local version of the + Terraform CLI that is compatible with the Terraform version selected + in the remote workspace settings. This prevents the + local operation from creating a new state snapshot that the workspace's + remote execution environment cannot decode. + + We recommend against using this option unless absolutely necessary. Overriding this check can result + in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently + selected version of Terraform. diff --git a/website/docs/cli/cloud/index.html.md b/website/docs/cli/cloud/index.html.md deleted file mode 100644 index 30b5744fe..000000000 --- a/website/docs/cli/cloud/index.html.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: "docs" -page_title: "Using Terraform Cloud - Terraform CLI" ---- - -# Using Terraform Cloud with Terraform CLI - -The Terraform CLI's integration with Terraform Cloud lets you to use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated. - -Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/docs/cloud/run/cli.html). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking. - -> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. - -Workspaces can also be configured for local execution, in which case only state is stored in -Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend. - --> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/docs/language/settings/backends/remote.html). Refer to [Migrating from the remote -backend](/docs/cli/cloud/migrating.html) for details about switching to the CLI integration. - - -## Documentation Summary - -- [Terraform Cloud Settings](/docs/cli/cloud/settings.html) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support. -- [Initializing and Migrating](/docs/cli/cloud/migrating.html) describes -how to start using Terraform Cloud with a working directory that already has state data. -- [Command Line Arguments](/docs/cli/cloud/command-line-arguments.html) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud. - -Refer to the [CLI-driven Run Workflow](/docs/cloud/run/cli.html) for more details about how to use Terraform Cloud from the command line. diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx new file mode 100644 index 000000000..d9b741851 --- /dev/null +++ b/website/docs/cli/cloud/index.mdx @@ -0,0 +1,26 @@ +--- +page_title: Using Terraform Cloud - Terraform CLI +--- + +# Using Terraform Cloud with Terraform CLI + +The Terraform CLI's integration with Terraform Cloud lets you to use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated. + +Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/cloud-docs/run/cli). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking. + +> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. + +Workspaces can also be configured for local execution, in which case only state is stored in +Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend. + +-> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/language/settings/backends/remote). Refer to [Migrating from the remote +backend](/cli/cloud/migrating) for details about switching to the CLI integration. + +## Documentation Summary + +- [Terraform Cloud Settings](/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support. +- [Initializing and Migrating](/cli/cloud/migrating) describes + how to start using Terraform Cloud with a working directory that already has state data. +- [Command Line Arguments](/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud. + +Refer to the [CLI-driven Run Workflow](/cloud-docs/run/cli) for more details about how to use Terraform Cloud from the command line. diff --git a/website/docs/cli/cloud/migrating.html.md b/website/docs/cli/cloud/migrating.mdx similarity index 76% rename from website/docs/cli/cloud/migrating.html.md rename to website/docs/cli/cloud/migrating.mdx index 5547b43b9..7aa5572c3 100644 --- a/website/docs/cli/cloud/migrating.html.md +++ b/website/docs/cli/cloud/migrating.mdx @@ -1,24 +1,23 @@ --- -layout: "docs" -page_title: "Initializing and Migrating to Terraform Cloud - Terraform CLI" +page_title: Initializing and Migrating to Terraform Cloud - Terraform CLI --- # Initializing and Migrating -After [configuring Terraform Cloud settings](/docs/cli/cloud/settings.html) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/docs/cloud/run/cli.html) for more details. +After [configuring Terraform Cloud settings](/cli/cloud/settings) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/cloud-docs/run/cli) for more details. When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces. 1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces. -2. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block. +1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block. ## Migrating from Local State or State Backends > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. If the working directory already has state data available (using either local state or a [state -backend](/docs/language/settings/backends/index.html)), Terraform will ask your approval to migrate +backend](/language/settings/backends)), Terraform will ask your approval to migrate that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles moving between state backends. @@ -32,13 +31,13 @@ Because of this, Terraform will prompt you to rename the working directory's wor according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is `--` (e.g., `networking-prod-us-east`, `networking-staging-us-east`). Refer to [Workspace -Naming](/docs/cloud/workspaces/naming.html) in the Terraform Cloud documentation for more detail. +Naming](/cloud-docs/workspaces/naming) in the Terraform Cloud documentation for more detail. ## Migrating from the `remote` Backend If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names. -The [`remote` backend](/docs/language/settings/backends/remote.html) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. +The [`remote` backend](/language/settings/backends/remote) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/cloud-docs/run/cli) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. ### Block Replacement @@ -49,7 +48,7 @@ block. #### Single Workspace If you were using a single workspace with the `name` argument, change the block - label to `cloud`. +label to `cloud`. ```diff terraform { diff --git a/website/docs/cli/cloud/settings.html.md b/website/docs/cli/cloud/settings.mdx similarity index 70% rename from website/docs/cli/cloud/settings.html.md rename to website/docs/cli/cloud/settings.mdx index 5ffc2dd8b..74835e2b2 100644 --- a/website/docs/cli/cloud/settings.html.md +++ b/website/docs/cli/cloud/settings.mdx @@ -1,19 +1,18 @@ --- -layout: "docs" -page_title: "Terraform Cloud Settings - Terraform CLI" +page_title: Terraform Cloud Settings - Terraform CLI --- # Terraform Cloud Settings Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's -[CLI-driven run workflow](https://www.terraform.io/docs/cloud/run/cli.html). +[CLI-driven run workflow](/cloud-docs/run/cli). > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. You must configure the following settings to use Terraform Cloud for a particular working directory: - Provide credentials to access Terraform Cloud, preferably by using the - [`terraform login`](/docs/cli/commands/login.html) command. + [`terraform login`](/cli/commands/login) command. - Add a `cloud` block to the directory's Terraform configuration, to specify which organization and workspace(s) to use. - Optionally, use a `.terraformignore` file to specify files that shouldn't be @@ -43,7 +42,7 @@ terraform { The `cloud` block also has some special restrictions: - A configuration can only provide one `cloud` block. -- A `cloud` block cannot be used with [state backends](/docs/language/settings/backends/index.html). +- A `cloud` block cannot be used with [state backends](/language/settings/backends). A configuration can use one or the other, but not both. - A `cloud` block cannot refer to named values (like input variables, locals, or data source attributes). @@ -60,32 +59,32 @@ The `cloud` block supports the following configuration arguments: workspace(s) the current configuration should use. - `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to -use for the current configuration. The `workspaces` block must contain **exactly one** of the -following arguments, each denoting a strategy for how workspaces should be mapped: + use for the current configuration. The `workspaces` block must contain **exactly one** of the + following arguments, each denoting a strategy for how workspaces should be mapped: - - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use - this working directory with any workspaces that have all of the specified tags, - and can use [the `terraform workspace` commands](/docs/cli/workspaces/index.html) - to switch between them or create new workspaces. New workspaces will automatically have - the specified tags. This option conflicts with `name`. + - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use + this working directory with any workspaces that have all of the specified tags, + and can use [the `terraform workspace` commands](/cli/workspaces) + to switch between them or create new workspaces. New workspaces will automatically have + the specified tags. This option conflicts with `name`. - - `name` - (Optional) The name of a single Terraform Cloud workspace. You will - only be able to use the workspace specified in the configuration with this working - directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or - `terraform workspace new`). This option conflicts with `tags`. + - `name` - (Optional) The name of a single Terraform Cloud workspace. You will + only be able to use the workspace specified in the configuration with this working + directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or + `terraform workspace new`). This option conflicts with `tags`. - `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform Enterprise. Defaults to Terraform Cloud (app.terraform.io). - `token` - (Optional) The token used to authenticate with Terraform Cloud. We recommend omitting the token from the configuration, and instead using - [`terraform login`](/docs/cli/commands/login.html) or manually configuring + [`terraform login`](/cli/commands/login) or manually configuring `credentials` in the - [CLI config file](/docs/cli/config/config-file.html#credentials). + [CLI config file](/cli/config/config-file#credentials). ## Excluding Files from Upload with .terraformignore -When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), +When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli), a copy of your configuration directory is uploaded to Terraform Cloud. You can define paths to exclude from upload by adding a `.terraformignore` file at the root of your configuration directory. If this file is not present, the upload will exclude diff --git a/website/docs/cli/code/index.html.md b/website/docs/cli/code/index.mdx similarity index 65% rename from website/docs/cli/code/index.html.md rename to website/docs/cli/code/index.mdx index bf858dd6b..ec06e20ab 100644 --- a/website/docs/cli/code/index.html.md +++ b/website/docs/cli/code/index.mdx @@ -1,12 +1,13 @@ --- -layout: "docs" -page_title: "Writing and Modifying Code - Terraform CLI" -description: "Learn commands that help validate, format, and upgrade code written in the Terraform Configuration Language." +page_title: Writing and Modifying Code - Terraform CLI +description: >- + Learn commands that help validate, format, and upgrade code written in the + Terraform Configuration Language. --- # Writing and Modifying Terraform Code -The [Terraform language](/docs/language/index.html) is Terraform's primary +The [Terraform language](/language) is Terraform's primary user interface, and all of Terraform's workflows rely on configurations written in the Terraform language. @@ -14,18 +15,17 @@ Terraform CLI includes several commands to make Terraform code more convenient to work with. Integrating these commands into your editing workflow can potentially save you time and effort. -- [The `terraform console` command](/docs/cli/commands/console.html) starts an +- [The `terraform console` command](/cli/commands/console) starts an interactive shell for evaluating Terraform - [expressions](/docs/language/expressions/index.html), which can be a faster way + [expressions](/language/expressions), which can be a faster way to verify that a particular resource argument results in the value you expect. - -- [The `terraform fmt` command](/docs/cli/commands/fmt.html) rewrites Terraform +- [The `terraform fmt` command](/cli/commands/fmt) rewrites Terraform configuration files to a canonical format and style, so you don't have to waste time making minor adjustments for readability and consistency. It works well as a pre-commit hook in your version control system. -- [The `terraform validate` command](/docs/cli/commands/validate.html) validates the +- [The `terraform validate` command](/cli/commands/validate) validates the syntax and arguments of the Terraform configuration files in a directory, including argument and attribute names and types for resources and modules. The `plan` and `apply` commands automatically validate a configuration before @@ -33,12 +33,12 @@ potentially save you time and effort. workflow, but it can be very useful as a pre-commit hook or as part of a continuous integration pipeline. -- [The `0.13upgrade` command](/docs/cli/commands/0.13upgrade.html) and - [the `0.12upgrade` command](/docs/cli/commands/0.12upgrade.html) can automatically +- [The `0.13upgrade` command](/cli/commands/0.13upgrade) and + [the `0.12upgrade` command](/cli/commands/0.12upgrade) can automatically modify the configuration files in a Terraform module to help deal with major syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both of these commands are only available in the Terraform version they are associated with, and you are expected to upgrade older code to be compatible with 0.12 before attempting to make it compatible with 0.13. For more detailed information about updating code for new Terraform versions, see the [upgrade - guides](/upgrade-guides/index.html) in the Terraform language docs. + guides](/language/upgrade-guides) in the Terraform language docs. diff --git a/website/docs/cli/commands/0.12upgrade.html.md b/website/docs/cli/commands/0.12upgrade.mdx similarity index 90% rename from website/docs/cli/commands/0.12upgrade.html.md rename to website/docs/cli/commands/0.12upgrade.mdx index 59ff0de44..73068ad71 100644 --- a/website/docs/cli/commands/0.12upgrade.html.md +++ b/website/docs/cli/commands/0.12upgrade.mdx @@ -1,9 +1,8 @@ --- -layout: "docs" -page_title: "Command: 0.12upgrade" -sidebar_current: "docs-commands-012upgrade" -description: |- - The 0.12upgrade subcommand automatically rewrites existing configurations for Terraform 0.12 compatibility. +page_title: 'Command: 0.12upgrade' +description: >- + The 0.12upgrade subcommand automatically rewrites existing configurations for + Terraform 0.12 compatibility. --- # Command: 0.12upgrade @@ -12,7 +11,7 @@ The `terraform 0.12upgrade` command applies several automatic upgrade rules to help prepare a module that was written for Terraform v0.11 to be used with Terraform v0.12. --> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](https://www.terraform.io/upgrade-guides/0-12.html). +-> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/language/upgrade-guides/0-12). ## Usage @@ -71,13 +70,13 @@ the change. Once upgraded the configuration will no longer be compatible with Terraform v0.11 and earlier. When upgrading a shared module that is called from multiple configurations, you may need to -[fix existing configurations to a previous version](/docs/language/modules/syntax.html#version) +[fix existing configurations to a previous version](/language/modules/syntax#version) to allow for a gradual upgrade. If the module is published via -[a Terraform registry](/docs/registry/), assign a new _major_ version number +[a Terraform registry](/registry), assign a new _major_ version number to the upgraded module source to represent the fact that this is a breaking change for v0.11 callers. If a module is installed directly from a version control system such as Git, -[use specific revisions](https://www.terraform.io/docs/language/modules/sources.html#selecting-a-revision) +[use specific revisions](/language/modules/sources#selecting-a-revision) to control which version is used by which caller. The command-line options are all optional. The available options are: @@ -107,8 +106,8 @@ On Mac OS X, the `find` included with the system does not support the `-printf` ``` brew install findutils ``` -Once installed, run the above command line using `gfind` instead of `find`. +Once installed, run the above command line using `gfind` instead of `find`. Note that the above includes the `-yes` option to override the interactive prompt, so be sure you have a clean work tree before running it. diff --git a/website/docs/cli/commands/0.13upgrade.html.md b/website/docs/cli/commands/0.13upgrade.mdx similarity index 92% rename from website/docs/cli/commands/0.13upgrade.html.md rename to website/docs/cli/commands/0.13upgrade.mdx index 52ff42067..7322129aa 100644 --- a/website/docs/cli/commands/0.13upgrade.html.md +++ b/website/docs/cli/commands/0.13upgrade.mdx @@ -1,9 +1,8 @@ --- -layout: "docs" -page_title: "Command: 0.13upgrade" -sidebar_current: "docs-commands-013upgrade" -description: |- - The 0.13upgrade subcommand updates existing configurations to use the new provider source features from Terraform 0.13. +page_title: 'Command: 0.13upgrade' +description: >- + The 0.13upgrade subcommand updates existing configurations to use the new + provider source features from Terraform 0.13. --- # Command: 0.13upgrade @@ -12,7 +11,7 @@ The `terraform 0.13upgrade` command updates existing configuration to add an explicit `source` attribute for each provider used in a given module. The provider source settings are stored in a `required_providers` block. --> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](https://www.terraform.io/upgrade-guides/0-13.html). +-> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/language/upgrade-guides/0-13). ## Usage @@ -23,7 +22,7 @@ providers are in use for a module, detect the source address for those providers where possible, and record this information in a [`required_providers` block][required-providers]. -[required-providers]: /docs/language/providers/requirements.html +[required-providers]: /language/providers/requirements ~> Note: the command ignores `.tf.json` files and override files in the module. diff --git a/website/docs/cli/commands/apply.html.md b/website/docs/cli/commands/apply.mdx similarity index 82% rename from website/docs/cli/commands/apply.html.md rename to website/docs/cli/commands/apply.mdx index 09172c542..ece491cdc 100644 --- a/website/docs/cli/commands/apply.html.md +++ b/website/docs/cli/commands/apply.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: apply" -sidebar_current: "docs-commands-apply" -description: "The terraform apply command executes the actions proposed in a Terraform plan to create, update, or destroy infrastructure." +page_title: 'Command: apply' +description: >- + The terraform apply command executes the actions proposed in a Terraform plan + to create, update, or destroy infrastructure. --- # Command: apply @@ -33,15 +33,15 @@ you pass it the filename of a previously-saved plan file. ### Automatic Plan Mode In the default case, with no saved plan file, `terraform apply` creates its own -plan of action, in the same way that [`terraform plan`](./plan.html) would. +plan of action, in the same way that [`terraform plan`](/cli/commands/plan) would. Terraform will propose the plan to you and prompt you to approve it before taking the described actions, unless you waive that prompt by using the `-auto-approve` option. When performing its own plan, `terraform apply` supports all of the same -[planning modes](./plan.html#planning-modes) and -[planning options](./plan.html#planning-options) that `terraform plan` would +[planning modes](/cli/commands/plan#planning-modes) and +[planning options](/cli/commands/plan#planning-options) that `terraform plan` would accept, so you can customize how Terraform will create the plan. ### Saved Plan Mode @@ -49,7 +49,7 @@ accept, so you can customize how Terraform will create the plan. If you pass the filename of a previously-saved plan file, `terraform apply` performs exactly the steps specified by that plan file. It does not prompt for approval; if you want to inspect a plan file before applying it, you can use -[`terraform show`](./show.html). +[`terraform show`](/cli/commands/show). When using a saved plan, none of the planning modes or planning options linked above are supported; these options only affect Terraform's decisions about which @@ -61,8 +61,8 @@ decisions. When run without a saved plan file, `terraform apply` supports all of `terraform plan`'s planning modes and planning options. For details, see: -- [Planning Modes](./plan.html#planning-modes) -- [Planning Options](./plan.html#planning-options) +* [Planning Modes](/cli/commands/plan#planning-modes) +* [Planning Options](/cli/commands/plan#planning-options) ### Apply Options @@ -70,7 +70,7 @@ The following options allow you to change various details about how the apply command executes and reports on the apply operation. If you are running `terraform apply` _without_ a previously-saved plan file, these options are _in addition to_ the planning modes and planning options described for -[`terraform plan`](./plan.html). +[`terraform plan`](/cli/commands/plan). * `-auto-approve` - Skips interactive approval of plan before applying. This option is ignored when you pass a previously-saved plan file, because @@ -95,11 +95,11 @@ _in addition to_ the planning modes and planning options described for variable values to continue. To enable this flag, you must also either enable the `-auto-approve` flag or specify a previously-saved plan. - [machine-readable-ui]: /docs/internals/machine-readable-ui.html + [machine-readable-ui]: /internals/machine-readable-ui * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before @@ -111,13 +111,13 @@ _in addition to_ the planning modes and planning options described for rendered by a system that cannot interpret terminal formatting. * `-parallelism=n` - Limit the number of concurrent operation as Terraform - [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to - 10. + [walks the graph](/internals/graph#walking-the-graph). Defaults to + 10\. For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, +[the `local` backend](/language/settings/backends/local) only, `terraform apply` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). ## Passing a Different Configuration Directory @@ -127,7 +127,7 @@ that directory as the root module instead of the current working directory. That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](./#switching-working-directory-with-chdir) +[the `-chdir` global option](/cli/commands/#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the current working directory. @@ -135,6 +135,6 @@ current working directory. If your previous use of this legacy pattern was also relying on Terraform writing the `.terraform` subdirectory into the current working directory even though the root module directory was overridden, use -[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#tf_data_dir) +[the `TF_DATA_DIR` environment variable](/cli/config/environment-variables#tf_data_dir) to direct Terraform to write the `.terraform` directory to a location other than the current working directory. diff --git a/website/docs/cli/commands/console.html.md b/website/docs/cli/commands/console.mdx similarity index 77% rename from website/docs/cli/commands/console.html.md rename to website/docs/cli/commands/console.mdx index 23682b562..2f7edcfa5 100644 --- a/website/docs/cli/commands/console.html.md +++ b/website/docs/cli/commands/console.mdx @@ -1,37 +1,36 @@ --- -layout: "docs" -page_title: "Command: console" -sidebar_current: "docs-commands-console" -description: "The terraform console command provides an interactive console for - evaluating expressions." +page_title: 'Command: console' +description: >- + The terraform console command provides an interactive console for evaluating + expressions. --- # Command: console The `terraform console` command provides an interactive console for -evaluating [expressions](/docs/language/expressions/index.html). +evaluating [expressions](/language/expressions). ## Usage Usage: `terraform console [options]` This command provides an interactive command-line console for evaluating and -experimenting with [expressions](/docs/language/expressions/index.html). +experimenting with [expressions](/language/expressions). This is useful for testing interpolations before using them in configurations, and for interacting with any values currently saved in -[state](/docs/language/state/index.html). +[state](/language/state). If the current state is empty or has not yet been created, the console can be used to experiment with the expression syntax and -[built-in functions](/docs/language/functions/index.html). +[built-in functions](/language/functions). You can close the console with the `exit` command or by pressing Control-C or Control-D. For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, +[the `local` backend](/language/settings/backends/local) only, `terraform console` accepts the legacy command line option -[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`](/language/settings/backends/local#command-line-arguments). ## Scripting @@ -52,7 +51,7 @@ tolist([ ## Remote State -If [remote state](/docs/language/state/remote.html) is used by the current backend, +If [remote state](/language/state/remote) is used by the current backend, Terraform will read the state for the current workspace from the backend before evaluating any expressions. diff --git a/website/docs/cli/commands/destroy.html.md b/website/docs/cli/commands/destroy.mdx similarity index 78% rename from website/docs/cli/commands/destroy.html.md rename to website/docs/cli/commands/destroy.mdx index 4e45bbe3d..beb9782eb 100644 --- a/website/docs/cli/commands/destroy.html.md +++ b/website/docs/cli/commands/destroy.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: destroy" -sidebar_current: "docs-commands-destroy" -description: "The terraform destroy command destroys all objects managed by a Terraform configuration." +page_title: 'Command: destroy' +description: >- + The terraform destroy command destroys all objects managed by a Terraform + configuration. --- # Command: destroy @@ -27,7 +27,7 @@ terraform apply -destroy ``` For that reason, this command accepts most of the options that -[`terraform apply`](./apply.html) accepts, although it does +[`terraform apply`](/cli/commands/apply) accepts, although it does not accept a plan file argument and forces the selection of the "destroy" planning mode. @@ -38,7 +38,7 @@ destroying would be, by running the following command: terraform plan -destroy ``` -This will run [`terraform plan`](./plan.html) in _destroy_ mode, showing +This will run [`terraform plan`](/cli/commands/plan) in _destroy_ mode, showing you the proposed destroy changes without executing them. -> **Note:** The `-destroy` option to `terraform apply` exists only in diff --git a/website/docs/cli/commands/env.html.md b/website/docs/cli/commands/env.html.md deleted file mode 100644 index bbaacc530..000000000 --- a/website/docs/cli/commands/env.html.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: "docs" -page_title: "Command: env" -sidebar_current: "docs-commands-envcmd" -description: "The terraform env command is a deprecated form of the terraform workspace command." ---- - -# Command: env - -The `terraform env` command is deprecated. -[The `terraform workspace` command](/docs/cli/commands/workspace/index.html) -should be used instead. diff --git a/website/docs/cli/commands/env.mdx b/website/docs/cli/commands/env.mdx new file mode 100644 index 000000000..611354068 --- /dev/null +++ b/website/docs/cli/commands/env.mdx @@ -0,0 +1,12 @@ +--- +page_title: 'Command: env' +description: >- + The terraform env command is a deprecated form of the terraform workspace + command. +--- + +# Command: env + +The `terraform env` command is deprecated. +[The `terraform workspace` command](/cli/commands/workspace) +should be used instead. diff --git a/website/docs/cli/commands/fmt.html.md b/website/docs/cli/commands/fmt.mdx similarity index 89% rename from website/docs/cli/commands/fmt.html.md rename to website/docs/cli/commands/fmt.mdx index b25a476b4..c6868d733 100644 --- a/website/docs/cli/commands/fmt.html.md +++ b/website/docs/cli/commands/fmt.mdx @@ -1,15 +1,15 @@ --- -layout: "docs" -page_title: "Command: fmt" -sidebar_current: "docs-commands-fmt" -description: "The terraform fmt command rewrites configuration files to a canonical format and style." +page_title: 'Command: fmt' +description: >- + The terraform fmt command rewrites configuration files to a canonical format + and style. --- # Command: fmt 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 language style conventions](/docs/language/syntax/style.html), +the [Terraform language style conventions](/language/syntax/style), along with other minor adjustments for readability. Other Terraform commands that generate Terraform configuration will produce @@ -58,5 +58,5 @@ The command-line flags are all optional. The list of available flags are: * `-write=false` - Don't overwrite the input files. (This is implied by `-check` or when the input is STDIN.) * `-diff` - Display diffs of formatting changes * `-check` - Check if the input is formatted. Exit status will be 0 if - all input is properly formatted and non-zero otherwise. + all input is properly formatted and non-zero otherwise. * `-recursive` - Also process files in subdirectories. By default, only the given directory (or current directory) is processed. diff --git a/website/docs/cli/commands/force-unlock.html.md b/website/docs/cli/commands/force-unlock.mdx similarity index 71% rename from website/docs/cli/commands/force-unlock.html.md rename to website/docs/cli/commands/force-unlock.mdx index 0ad7a6285..735eec489 100644 --- a/website/docs/cli/commands/force-unlock.html.md +++ b/website/docs/cli/commands/force-unlock.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: force-unlock" -sidebar_current: "docs-commands-force-unlock" -description: "The terraform force-unlock command unlocks the state for a configuration. It does not modify your infrastructure." +page_title: 'Command: force-unlock' +description: >- + The terraform force-unlock command unlocks the state for a configuration. It + does not modify your infrastructure. --- # Command: force-unlock @@ -27,4 +27,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.html.md b/website/docs/cli/commands/get.mdx similarity index 60% rename from website/docs/cli/commands/get.html.md rename to website/docs/cli/commands/get.mdx index 47f4e6cfa..bf9b9f970 100644 --- a/website/docs/cli/commands/get.html.md +++ b/website/docs/cli/commands/get.mdx @@ -1,14 +1,12 @@ --- -layout: "docs" -page_title: "Command: get" -sidebar_current: "docs-commands-get" -description: "The terraform get command downloads and updates modules." +page_title: 'Command: get' +description: The terraform get command downloads and updates modules. --- # Command: get The `terraform get` command is used to download and update -[modules](/docs/language/modules/develop/index.html) mentioned in the root module. +[modules](/language/modules/develop) mentioned in the root module. ## Usage @@ -21,6 +19,6 @@ repository. The `get` command supports the following option: * `-update` - If specified, modules that are already downloaded will be - checked for updates and the updates will be downloaded if present. + checked for updates and the updates will be downloaded if present. * `-no-color` - Disable text coloring in the output. diff --git a/website/docs/cli/commands/graph.html.md b/website/docs/cli/commands/graph.mdx similarity index 74% rename from website/docs/cli/commands/graph.html.md rename to website/docs/cli/commands/graph.mdx index cfc915667..969c6e5db 100644 --- a/website/docs/cli/commands/graph.html.md +++ b/website/docs/cli/commands/graph.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: graph" -sidebar_current: "docs-commands-graph" -description: "The terraform graph command generates a visual representation of a configuration or execution plan that you can use to generate charts." +page_title: 'Command: graph' +description: >- + The terraform graph command generates a visual representation of a + configuration or execution plan that you can use to generate charts. --- # Command: graph @@ -12,7 +12,6 @@ representation of either a configuration or execution plan. The output is in the DOT format, which can be used by [GraphViz](http://www.graphviz.org) to generate charts. - ## Usage Usage: `terraform graph [options]` @@ -33,16 +32,16 @@ argument. Options: * `-plan=tfplan` - Render graph using the specified plan file instead of the - configuration in the current directory. + configuration in the current directory. * `-draw-cycles` - Highlight any cycles in the graph with colored edges. - This helps when diagnosing cycle errors. + This helps when diagnosing cycle errors. * `-type=plan` - Type of graph to output. Can be: `plan`, `plan-destroy`, `apply`, - `validate`, `input`, `refresh`. + `validate`, `input`, `refresh`. * `-module-depth=n` - (deprecated) In prior versions of Terraform, specified the - depth of modules to show in the output. + depth of modules to show in the output. ## Generating Images @@ -55,4 +54,4 @@ $ terraform graph | dot -Tsvg > graph.svg ``` Here is an example graph output: -![Graph Example](docs/graph-example.png) +![Graph Example](/img/docs/graph-example.png) diff --git a/website/docs/cli/commands/import.html.md b/website/docs/cli/commands/import.mdx similarity index 79% rename from website/docs/cli/commands/import.html.md rename to website/docs/cli/commands/import.mdx index 7c26b1758..42e1eaa60 100644 --- a/website/docs/cli/commands/import.html.md +++ b/website/docs/cli/commands/import.mdx @@ -1,8 +1,6 @@ --- -layout: "docs" -page_title: "Command: import" -sidebar_current: "docs-commands-import" -description: "The terraform import command brings existing resources into Terraform state." +page_title: 'Command: import' +description: The terraform import command brings existing resources into Terraform state. --- # Command: import @@ -10,7 +8,7 @@ description: "The terraform import command brings existing resources into Terraf > **Hands-on:** Try the [Import Terraform Configuration](https://learn.hashicorp.com/tutorials/terraform/state-import?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. The `terraform import` command is used to -[import existing resources](/docs/cli/import/index.html) +[import existing resources](/cli/import) into Terraform. ## Usage @@ -20,7 +18,7 @@ Usage: `terraform import [options] ADDRESS ID` Import will find the existing resource from ID and import it into your Terraform state at the given ADDRESS. -ADDRESS must be a valid [resource address](/docs/cli/state/resource-addressing.html). +ADDRESS must be a valid [resource address](/cli/state/resource-addressing). Because any resource address is valid, the import command can import resources into modules as well as directly into the root of your state. @@ -36,7 +34,7 @@ itself having created all objects. If you import existing objects into Terraform be careful to import each remote object to only one Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. For more information on this assumption, see -[the State section](/docs/language/state/index.html). +[the State section](/language/state). The command-line flags are all optional. The list of available flags are: @@ -48,29 +46,29 @@ The command-line flags are all optional. The list of available flags are: * `-input=true` - Whether to ask for input for provider configuration. * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=0s` - Duration to retry a state lock. * `-no-color` - If specified, output won't contain any color. * `-parallelism=n` - Limit the number of concurrent operation as Terraform - [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults + [walks the graph](/internals/graph#walking-the-graph). Defaults to 10. * `-provider=provider` - **Deprecated** Override the provider configuration to -use when importing the object. By default, Terraform uses the provider specified -in the configuration for the target resource, and that is the best behavior in most cases. + use when importing the object. By default, Terraform uses the provider specified + in the configuration for the target resource, and that is the best behavior in most cases. * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag can be set multiple times. Variable values are interpreted as - [literal expressions](/docs/language/expressions/types.html) in the + [literal expressions](/language/expressions/types) in the Terraform language, so list and map values can be specified via this flag. This is only useful with the `-config` flag. * `-var-file=foo` - Set variables in the Terraform configuration from - a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If + a [variable file](/language/values/variables#variable-definitions-tfvars-files). If a `terraform.tfvars` or any `.auto.tfvars` files are present in the current directory, they will be automatically loaded. `terraform.tfvars` is loaded first and the `.auto.tfvars` files after in alphabetical order. Any files @@ -79,15 +77,15 @@ in the configuration for the target resource, and that is the best behavior in m useful with the `-config` flag. For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) +[the `remote` backend](/language/settings/backends/remote) only, `terraform import` also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, +[the `local` backend](/language/settings/backends/local) only, `terraform import` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). ## Provider Configuration @@ -135,7 +133,7 @@ $ terraform import module.foo.aws_instance.bar i-abcd1234 ## Example: Import into Resource configured with count The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with -[`count`](/docs/language/meta-arguments/count.html): +[`count`](/language/meta-arguments/count): ```shell $ terraform import 'aws_instance.baz[0]' i-abcd1234 @@ -144,7 +142,7 @@ $ terraform import 'aws_instance.baz[0]' i-abcd1234 ## Example: Import into Resource configured with for_each The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with -[`for_each`](/docs/language/meta-arguments/for_each.html): +[`for_each`](/language/meta-arguments/for_each): Linux, Mac OS, and UNIX: diff --git a/website/docs/cli/commands/index.html.md b/website/docs/cli/commands/index.mdx similarity index 93% rename from website/docs/cli/commands/index.html.md rename to website/docs/cli/commands/index.mdx index 6fb5919a7..f7dd9c74f 100644 --- a/website/docs/cli/commands/index.html.md +++ b/website/docs/cli/commands/index.mdx @@ -1,8 +1,6 @@ --- -layout: "docs" -page_title: "Basic CLI Features" -sidebar_current: "docs-commands" -description: "An introduction to the terraform command and its available subcommands." +page_title: Basic CLI Features +description: An introduction to the terraform command and its available subcommands. --- # Basic CLI Features @@ -17,8 +15,8 @@ of this page. We refer to the `terraform` command line tool as "Terraform CLI" elsewhere in the documentation. This terminology is often used to distinguish it from other components you might use in the Terraform product family, such as -[Terraform Cloud](/docs/cloud/) or -the various [Terraform providers](/docs/language/providers/index.html), which +[Terraform Cloud](/cloud-docs) or +the various [Terraform providers](/language/providers), which are developed and released separately from Terraform CLI. To view a list of the commands available in your current Terraform version, @@ -100,7 +98,7 @@ will be read or written in the given directory instead. There are two exceptions where Terraform will use the original working directory even when you specify `-chdir=...`: -* Settings in the [CLI Configuration](/docs/cli/config/config-file.html) are not for a specific +* Settings in the [CLI Configuration](/cli/config/config-file) are not for a specific subcommand and Terraform processes them before acting on the `-chdir` option. @@ -153,7 +151,7 @@ Checkpoint itself can be entirely disabled for all HashiCorp products by setting the environment variable `CHECKPOINT_DISABLE` to any non-empty value. Alternatively, settings in -[the CLI configuration file](/docs/cli/config/config-file.html) can be used to +[the CLI configuration file](/cli/config/config-file) can be used to disable checkpoint features. The following checkpoint-related settings are supported in this file: diff --git a/website/docs/cli/commands/init.html.md b/website/docs/cli/commands/init.mdx similarity index 83% rename from website/docs/cli/commands/init.html.md rename to website/docs/cli/commands/init.mdx index 6a62906a5..d9e7b8ce6 100644 --- a/website/docs/cli/commands/init.html.md +++ b/website/docs/cli/commands/init.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: init" -sidebar_current: "docs-commands-init" -description: "The terraform init command initializes a working directory containing configuration files and installs plugins for required providers." +page_title: 'Command: init' +description: >- + The terraform init command initializes a working directory containing + configuration files and installs plugins for required providers. --- # Command: init @@ -74,7 +74,7 @@ activating credentials) before running `terraform init`. ## Backend Initialization During init, the root configuration directory is consulted for -[backend configuration](/docs/language/settings/backends/configuration.html) and the chosen backend +[backend configuration](/language/settings/backends/configuration) and the chosen backend is initialized using the given configuration settings. Re-running init with an already-initialized backend will update the working @@ -96,14 +96,14 @@ when the working directory was already previously initialized for a particular backend. The `-backend-config=...` option can be used for -[partial backend configuration](/docs/language/settings/backends/configuration.html#partial-configuration), +[partial backend configuration](/language/settings/backends/configuration#partial-configuration), in situations where the backend settings are dynamic or sensitive and so cannot be statically specified in the configuration file. ## Child Module Installation During init, the configuration is searched for `module` blocks, and the source -code for referenced [modules](/docs/language/modules/develop/index.html) is retrieved from the locations +code for referenced [modules](/language/modules/develop) is retrieved from the locations given in their `source` arguments. Re-running init with modules already installed will install the sources for @@ -128,13 +128,13 @@ third-party provider registry, `terraform init` will automatically find, download, and install the necessary provider plugins. If you cannot or do not wish to install providers from their origin registries, you can customize how Terraform installs providers using -[the provider installation settings in the CLI configuration](/docs/cli/config/config-file.html#provider-installation). +[the provider installation settings in the CLI configuration](/cli/config/config-file#provider-installation). For more information about specifying which providers are required for each -of your modules, see [Provider Requirements](/docs/language/providers/requirements.html). +of your modules, see [Provider Requirements](/language/providers/requirements). After successful installation, Terraform writes information about the selected -providers to [the dependency lock file](/docs/language/dependency-lock.html). +providers to [the dependency lock file](/language/files/dependency-lock). You should commit this file to your version control system to ensure that when you run `terraform init` again in future Terraform will select exactly the same provider versions. Use the `-upgrade` option if you want Terraform @@ -142,31 +142,31 @@ to ignore the dependency lock file and consider installing newer versions. You can modify `terraform init`'s plugin behavior with the following options: -- `-upgrade` Upgrade all previously-selected plugins to the newest version +* `-upgrade` Upgrade all previously-selected plugins to the newest version that complies with the configuration's version constraints. This will cause Terraform to ignore any selections recorded in the dependency lock file, and to take the newest available version matching the configured version constraints. -- `-get-plugins=false` — Skip plugin installation. +* `-get-plugins=false` — Skip plugin installation. - -> Note: Since Terraform 0.13, this option has been superseded by the - [`provider_installation`](/docs/cli/config/config-file.html#provider-installation) and - [`plugin_cache_dir`](/docs/cli/config/config-file.html#plugin_cache_dir) settings. - It should not be used in Terraform versions 0.13+, and this option - was removed in Terraform 0.15. -- `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from + -> Note: Since Terraform 0.13, this option has been superseded by the + [`provider_installation`](/cli/config/config-file#provider-installation) and + [`plugin_cache_dir`](/cli/config/config-file#plugin_cache_dir) settings. + It should not be used in Terraform versions 0.13+, and this option + was removed in Terraform 0.15. +* `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from the specified directory, as if it had been configured as a `filesystem_mirror` in the CLI configuration. If you intend to routinely use a particular filesystem mirror then we recommend - [configuring Terraform's installation methods globally](/docs/cli/config/config-file.html#provider-installation). + [configuring Terraform's installation methods globally](/cli/config/config-file#provider-installation). You can use `-plugin-dir` as a one-time override for exceptional situations, such as if you are testing a local build of a provider plugin you are currently developing. -- `-lockfile=MODE` Set a dependency lockfile mode. +* `-lockfile=MODE` Set a dependency lockfile mode. The valid values for the lockfile mode are as follows: -- readonly: suppress the lockfile changes, but verify checksums against the +* readonly: suppress the lockfile changes, but verify checksums against the information already recorded. It conflicts with the `-upgrade` flag. If you update the lockfile with third-party dependency management tools, it would be useful to control when it changes explicitly. @@ -192,7 +192,7 @@ that directory as the root module instead of the current working directory. That usage is still supported in Terraform v0.14, but is now deprecated and we plan to remove it in Terraform v0.15. If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](./#switching-working-directory-with-chdir) +[the `-chdir` global option](/cli/commands/#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the current working directory. @@ -200,6 +200,6 @@ current working directory. If your previous use of this legacy pattern was also relying on Terraform writing the `.terraform` subdirectory into the current working directory even though the root module directory was overridden, use -[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#tf_data_dir) +[the `TF_DATA_DIR` environment variable](/cli/config/environment-variables#tf_data_dir) to direct Terraform to write the `.terraform` directory to a location other than the current working directory. diff --git a/website/docs/cli/commands/login.html.md b/website/docs/cli/commands/login.mdx similarity index 72% rename from website/docs/cli/commands/login.html.md rename to website/docs/cli/commands/login.mdx index 8af1ef7a4..86e1fcfee 100644 --- a/website/docs/cli/commands/login.html.md +++ b/website/docs/cli/commands/login.mdx @@ -1,9 +1,9 @@ --- -layout: "docs" -page_title: "Command: login" -sidebar_current: "docs-commands-login" -description: |- - The terraform login command can be used to automatically obtain and save an API token for Terraform Cloud, Terraform Enterprise, or any other host that offers Terraform services. +page_title: 'Command: login' +description: >- + The terraform login command can be used to automatically obtain and save an + API token for Terraform Cloud, Terraform Enterprise, or any other host that + offers Terraform services. --- # Command: login @@ -15,7 +15,7 @@ API token for Terraform Cloud, Terraform Enterprise, or any other host that offe where it is possible to launch a web browser on the same host where Terraform is running. If you are running Terraform in an unattended automation scenario, you can -[configure credentials manually in the CLI configuration](https://www.terraform.io/docs/cli/config/config-file.html#credentials). +[configure credentials manually in the CLI configuration](/cli/config/config-file#credentials). ## Usage @@ -34,12 +34,12 @@ not as desired. If you don't wish to store your API token in the default location, you can optionally configure a -[credentials helper program](/docs/cli/config/config-file.html#credentials-helpers) which knows +[credentials helper program](/cli/config/config-file#credentials-helpers) which knows how to store and later retrieve credentials in some other system, such as your organization's existing secrets management system. ## Login Server Support The `terraform login` command works with any server supporting the -[login protocol](/docs/internals/login-protocol.html), including Terraform Cloud +[login protocol](/internals/login-protocol), including Terraform Cloud and Terraform Enterprise. diff --git a/website/docs/cli/commands/logout.html.md b/website/docs/cli/commands/logout.mdx similarity index 79% rename from website/docs/cli/commands/logout.html.md rename to website/docs/cli/commands/logout.mdx index 15656fba9..dbec4bc75 100644 --- a/website/docs/cli/commands/logout.html.md +++ b/website/docs/cli/commands/logout.mdx @@ -1,9 +1,8 @@ --- -layout: "docs" -page_title: "Command: logout" -sidebar_current: "docs-commands-logout" -description: |- - The terraform logout command is used to remove credentials stored by terraform login. +page_title: 'Command: logout' +description: >- + The terraform logout command is used to remove credentials stored by terraform + login. --- # Command: logout @@ -26,5 +25,5 @@ the remote server, so it will remain valid until manually revoked. By default, Terraform will remove the token stored in plain text in a local CLI configuration file called `credentials.tfrc.json`. If you have configured a -[credentials helper program](/docs/cli/config/config-file.html#credentials-helpers), Terraform +[credentials helper program](/cli/config/config-file#credentials-helpers), Terraform will use the helper's `forget` command to remove it. diff --git a/website/docs/cli/commands/output.html.md b/website/docs/cli/commands/output.mdx similarity index 81% rename from website/docs/cli/commands/output.html.md rename to website/docs/cli/commands/output.mdx index a09725e21..2fe970ba7 100644 --- a/website/docs/cli/commands/output.html.md +++ b/website/docs/cli/commands/output.mdx @@ -1,9 +1,8 @@ --- -layout: "docs" -page_title: "Command: output" -sidebar_current: "docs-commands-output" -description: |- - The `terraform output` command is used to extract the value of an output variable from the state file. +page_title: 'Command: output' +description: >- + The `terraform output` command is used to extract the value of an output + variable from the state file. --- # Command: output @@ -22,20 +21,20 @@ output is printed. The command-line flags are all optional. The list of available flags are: * `-json` - If specified, the outputs are formatted as a JSON object, with - a key per output. If `NAME` is specified, only the output specified will be - returned. This can be piped into tools such as `jq` for further processing. + a key per output. If `NAME` is specified, only the output specified will be + returned. This can be piped into tools such as `jq` for further processing. * `-raw` - If specified, Terraform will convert the specified output value to a - string and print that string directly to the output, without any special - formatting. This can be convenient when working with shell scripts, but - it only supports string, number, and boolean values. Use `-json` instead - for processing complex data types. + string and print that string directly to the output, without any special + formatting. This can be convenient when working with shell scripts, but + it only supports string, number, and boolean values. Use `-json` instead + for processing complex data types. * `-no-color` - If specified, output won't contain any color. * `-state=path` - Path to the state file. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. + Ignored when [remote state](/language/state/remote) is used. -> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive values in Terraform state will be displayed in plain text. For more information, -see [Sensitive Data in State](/docs/language/state/sensitive-data.html). +see [Sensitive Data in State](/language/state/sensitive-data). ## Examples diff --git a/website/docs/cli/commands/plan.html.md b/website/docs/cli/commands/plan.mdx similarity index 78% rename from website/docs/cli/commands/plan.html.md rename to website/docs/cli/commands/plan.mdx index cdb3bbe27..8cb8112e1 100644 --- a/website/docs/cli/commands/plan.html.md +++ b/website/docs/cli/commands/plan.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: plan" -sidebar_current: "docs-commands-plan" -description: "The terraform plan command creates an execution plan with a preview of the changes that Terraform will make to your infrastructure." +page_title: 'Command: plan' +description: >- + The terraform plan command creates an execution plan with a preview of the + changes that Terraform will make to your infrastructure. --- # Command: plan @@ -31,12 +31,12 @@ to be taken. If you are using Terraform directly in an interactive terminal and you expect to apply the changes Terraform proposes, you can alternatively run -[`terraform apply`](./apply.html) directly. By default, the "apply" command +[`terraform apply`](/cli/commands/apply) directly. By default, the "apply" command automatically generates a new plan and prompts for you to approve it. You can use the optional `-out=FILE` option to save the generated plan to a file on disk, which you can later execute by passing the file to -[`terraform apply`](./apply.html) as an extra argument. This two-step workflow +[`terraform apply`](/cli/commands/apply) as an extra argument. This two-step workflow is primarily intended for when [running Terraform in automation](https://learn.hashicorp.com/tutorials/terraform/automate-terraform?in=terraform/automation&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). @@ -74,9 +74,9 @@ The remaining sections on this page describe the various options: * **[Planning Options](#planning-options)**: Alongside the special planning modes, there are also some options you can set in order to customize the planning process for unusual needs. - * **[Resource Targeting](#resource-targeting)** is one particular - special planning option that has some important caveats associated - with it. + * **[Resource Targeting](#resource-targeting)** is one particular + special planning option that has some important caveats associated + with it. * **[Other Options](#other-options)**: These change the behavior of the planning command itself, rather than customizing the content of the generated plan. @@ -94,7 +94,7 @@ a different intended outcome: for situations like transient development environments, where the managed objects cease to be useful once the development task is complete. - Activate destroy mode using the `-destroy` command line option. + Activate destroy mode using the `-destroy` command line option. * **Refresh-only mode:** creates a plan whose goal is only to update the Terraform state and any root module output values to match changes made to @@ -103,7 +103,7 @@ a different intended outcome: workflow (e.g. while responding to an incident) and you now need to reconcile Terraform's records with those changes. - Activate refresh-only mode using the `-refresh-only` command line option. + Activate refresh-only mode using the `-refresh-only` command line option. In situations where we need to discuss the default planning mode that Terraform uses when none of the alternative modes are selected, we refer to it as @@ -118,7 +118,7 @@ one alternative mode at the same time. -> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is supported only by the `terraform plan` command, and not by the `terraform apply` command. To create and apply a plan in destroy mode in -earlier versions you must run [`terraform destroy`](./destroy.html). +earlier versions you must run [`terraform destroy`](/cli/commands/destroy). -> **Note:** The `-refresh-only` option is available only in Terraform v0.15.4 and later. @@ -140,62 +140,62 @@ the previous section, are also available with the same meanings on * `-refresh=false` - Disables the default behavior of synchronizing the Terraform state with remote objects before checking for configuration changes. - This option can potentially make the planning operation faster by reducing - the number of remote API requests, but it comes at the expense of having - Terraform not take into account any changes that might've happened outside - of Terraform, and thus the resulting plan may not be complete or correct. + This option can potentially make the planning operation faster by reducing + the number of remote API requests, but it comes at the expense of having + Terraform not take into account any changes that might've happened outside + of Terraform, and thus the resulting plan may not be complete or correct. - This option is not available in the "refresh only" planning mode, because - it would effectively disable the entirety of the planning operation in that - case. + This option is not available in the "refresh only" planning mode, because + it would effectively disable the entirety of the planning operation in that + case. * `-replace=ADDRESS` - Instructs Terraform to plan to replace the single resource instance with the given address. If the given instance would normally have caused only an "update" action, or no action at all, then Terraform will choose a "replace" action instead. - You can use this option if you have learned that a particular remote object - has become degraded in some way. If you are using immutable infrastructure - patterns then you may wish to respond to that by replacing the - malfunctioning object with a new object that has the same configuration. + You can use this option if you have learned that a particular remote object + has become degraded in some way. If you are using immutable infrastructure + patterns then you may wish to respond to that by replacing the + malfunctioning object with a new object that has the same configuration. - This option is allowed only in the normal planning mode, so this option - is incompatible with the `-destroy` option. + This option is allowed only in the normal planning mode, so this option + is incompatible with the `-destroy` option. - The `-replace=...` option is available only from Terraform v0.15.2 onwards. - For earlier versions, you can achieve a similar effect (with some caveats) - using [`terraform taint`](./taint.html). + The `-replace=...` option is available only from Terraform v0.15.2 onwards. + For earlier versions, you can achieve a similar effect (with some caveats) + using [`terraform taint`](/cli/commands/taint). * `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only on resource instances which match the given address and on any objects that those instances depend on. - This command is for exceptional use only. See - [Resource Targeting](#resource-targeting) - below for more information. + This command is for exceptional use only. See + [Resource Targeting](#resource-targeting) + below for more information. * `-var 'NAME=VALUE'` - Sets a value for a single - [input variable](/docs/language/values/variables.html) declared in the + [input variable](/language/values/variables) declared in the root module of the configuration. Use this option multiple times to set more than one variable. For more information see [Input Variables on the Command Line](#input-variables-on-the-command-line), below. * `-var-file=FILENAME` - Sets values for potentially many - [input variables](/docs/language/values/variables.html) declared in the + [input variables](/language/values/variables) declared in the root module of the configuration, using definitions from a - ["tfvars" file](/docs/language/values/variables.html#variable-definitions-tfvars-files). + ["tfvars" file](/language/values/variables#variable-definitions-tfvars-files). Use this option multiple times to include values from more than one file. There are several other ways to set values for input variables in the root module, aside from the `-var` and `-var-file` options. For more information, see -[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables). +[Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables). ### Input Variables on the Command Line You can use the `-var` command line option to specify values for -[input variables](/docs/language/values/variables.html) declared in your +[input variables](/language/values/variables) declared in your root module. However, to do so will require writing a command line that is parsable both @@ -242,7 +242,7 @@ so we do not recommend using Terraform with PowerShell when you are on Windows. Use Windows Command Prompt instead. The appropriate syntax for writing the variable value is different depending -on the variable's [type constraint](/docs/language/expressions/type-constraints.html). +on the variable's [type constraint](/language/expressions/type-constraints). The primitive types `string`, `number`, and `bool` all expect a direct string value with no special punctuation except that required by your shell, as shown in the above examples. For all other type constraints, including list, @@ -262,8 +262,7 @@ terraform plan -var "name=[\"a\", \"b\", \"c\"]" Similar constraints apply when setting input variables using environment variables. For more information on the various methods for setting root module input variables, see -[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables). - +[Assigning Values to Root Module Variables](/language/values/variables#assigning-values-to-root-module-variables). ### Resource Targeting @@ -271,7 +270,7 @@ input variables, see You can use the `-target` option to focus Terraform's attention on only a subset of resources. -You can use [resource address syntax](/docs/cli/state/resource-addressing.html) +You can use [resource address syntax](/cli/state/resource-addressing) to specify the constraint. Terraform interprets the resource address as follows: * If the given address identifies one specific resource instance, Terraform @@ -296,14 +295,14 @@ that those selections depend on either directly or indirectly. This targeting capability is provided for exceptional circumstances, such as recovering from mistakes or working around Terraform limitations. It -is *not recommended* to use `-target` for routine operations, since this can +is _not recommended_ to use `-target` for routine operations, since this can lead to undetected configuration drift and confusion about how the true state of resources relates to configuration. Instead of using `-target` as a means to operate on isolated portions of very large configurations, prefer instead to break large configurations into several smaller configurations that can each be independently applied. -[Data sources](/docs/language/data-sources/index.html) can be used to access +[Data sources](/language/data-sources) can be used to access information about resources created in other configurations, allowing a complex system architecture to be broken down into more manageable parts that can be updated independently. @@ -339,11 +338,11 @@ The available options are: This implies `-input=false`, so the configuration must have no unassigned variable values to continue. - [machine-readable-ui]: /docs/internals/machine-readable-ui.html + [machine-readable-ui]: /internals/machine-readable-ui * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before @@ -359,28 +358,28 @@ The available options are: the planned changes, and to some other Terraform commands that can work with saved plan files. - Terraform will allow any filename for the plan file, but a typical - convention is to name it `tfplan`. **Do not** name the file with a suffix - that Terraform recognizes as another file format; if you use a `.tf` suffix - then Terraform will try to interpret the file as a configuration source - file, which will then cause syntax errors for subsequent commands. + Terraform will allow any filename for the plan file, but a typical + convention is to name it `tfplan`. **Do not** name the file with a suffix + that Terraform recognizes as another file format; if you use a `.tf` suffix + then Terraform will try to interpret the file as a configuration source + file, which will then cause syntax errors for subsequent commands. - The generated file is not in any standard format intended for consumption - by other software, but the file _does_ contain your full configuration, - all of the values associated with planned changes, and all of the plan - options including the input variables. If your plan includes any sort of - sensitive data, even if obscured in Terraform's terminal output, it will - be saved in cleartext in the plan file. You should therefore treat any - saved plan files as potentially-sensitive artifacts. + The generated file is not in any standard format intended for consumption + by other software, but the file _does_ contain your full configuration, + all of the values associated with planned changes, and all of the plan + options including the input variables. If your plan includes any sort of + sensitive data, even if obscured in Terraform's terminal output, it will + be saved in cleartext in the plan file. You should therefore treat any + saved plan files as potentially-sensitive artifacts. * `-parallelism=n` - Limit the number of concurrent operations as Terraform - [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults + [walks the graph](/internals/graph#walking-the-graph). Defaults to 10. For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, +[the `local` backend](/language/settings/backends/local) only, `terraform plan` accepts the legacy command line option -[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`](/language/settings/backends/local#command-line-arguments). ### Passing a Different Configuration Directory @@ -390,7 +389,7 @@ module instead of the current working directory. That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](./#switching-working-directory-with-chdir) +[the `-chdir` global option](/cli/commands/#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the current working directory. @@ -398,6 +397,6 @@ current working directory. If your previous use of this legacy pattern was also relying on Terraform writing the `.terraform` subdirectory into the current working directory even though the root module directory was overridden, use -[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#tf_data_dir) +[the `TF_DATA_DIR` environment variable](/cli/config/environment-variables#tf_data_dir) to direct Terraform to write the `.terraform` directory to a location other than the current working directory. diff --git a/website/docs/cli/commands/providers.html.md b/website/docs/cli/commands/providers.mdx similarity index 55% rename from website/docs/cli/commands/providers.html.md rename to website/docs/cli/commands/providers.mdx index a39d0ee0f..9d2b6c722 100644 --- a/website/docs/cli/commands/providers.html.md +++ b/website/docs/cli/commands/providers.mdx @@ -1,14 +1,14 @@ --- -layout: "docs" -page_title: "Command: providers" -sidebar_current: "docs-commands-providers" -description: "The terraform providers command prints information about the providers required in the current configuration." +page_title: 'Command: providers' +description: >- + The terraform providers command prints information about the providers + required in the current configuration. --- # Command: providers The `terraform providers` command shows information about the -[provider requirements](/docs/language/providers/requirements.html) of the +[provider requirements](/language/providers/requirements) of the configuration in the current working directory, as an aid to understanding where each requirement was detected from. diff --git a/website/docs/cli/commands/providers/lock.html.md b/website/docs/cli/commands/providers/lock.mdx similarity index 76% rename from website/docs/cli/commands/providers/lock.html.md rename to website/docs/cli/commands/providers/lock.mdx index b9a48fae7..9a6de3ff9 100644 --- a/website/docs/cli/commands/providers/lock.html.md +++ b/website/docs/cli/commands/providers/lock.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Command: providers lock" -sidebar_current: "docs-commands-providers-lock" +page_title: 'Command: providers lock' description: |- The `terraform providers lock` command adds new provider selection information to the dependency lock file without initializing the referenced providers. @@ -11,31 +9,31 @@ description: |- The `terraform providers lock` consults upstream registries (by default) in order to write provider dependency information into -[the dependency lock file](/docs/language/dependency-lock.html). +[the dependency lock file](/language/files/dependency-lock). The common way to update the dependency lock file is as a side-effect of normal provider installation during -[`terraform init`](/docs/cli/commands/init.html), but there are several situations where that +[`terraform init`](/cli/commands/init), but there are several situations where that automatic approach may not be sufficient: * If you are running Terraform in an environment that uses - [alternative provider installation methods](/docs/cli/config/config-file.html#provider-installation), + [alternative provider installation methods](/cli/config/config-file#provider-installation), such as filesystem or network mirrors, normal provider installation will not access the origin registry for a provider and therefore Terraform will not be able to populate all of the possible package checksums for the selected provider versions. - If you use `terraform lock` to write the official release checksums for a - provider into the dependency lock file then future `terraform init` runs - will verify the packages available in your selected mirror against the - official checksums previously recorded, giving additional certainty that - the mirror is serving the provider packages it is claiming to. + If you use `terraform lock` to write the official release checksums for a + provider into the dependency lock file then future `terraform init` runs + will verify the packages available in your selected mirror against the + official checksums previously recorded, giving additional certainty that + the mirror is serving the provider packages it is claiming to. * If your team runs Terraform across a number of different platforms (e.g. on both Windows and Linux) and the upstream registry for a provider is unable to provide signed checksums using the latest hashing scheme, subsequent runs of Terraform on other platforms may - [add additional checksums to the lock file](/docs/language/dependency-lock.html#new-provider-package-checksums). + [add additional checksums to the lock file](/language/files/dependency-lock#new-provider-package-checksums). You can avoid that by pre-populating hashes for all of the platforms you intend to use, using the `terraform providers lock` command. @@ -49,17 +47,17 @@ With no additional command line arguments, `terraform providers lock` will analyze the configuration in the current working directory to find all of the providers it depends on, and it will fetch the necessary data about those providers from their origin registries and then update -[the dependency lock file](/docs/language/dependency-lock.html) to +[the dependency lock file](/language/files/dependency-lock) to include a selected version for each provider and all of the package checksums that are covered by the provider developer's cryptographic signature. ~> **Warning:** The `terraform providers lock` command prints information - about what it has fetched and whether each package was signed using a - cryptographic signature, but it cannot automatically verify that the - providers are trustworthy and that they comply with your local system - policies or relevant regulations. Review the signing key information - in the output to confirm that you trust all of the signers before committing - the updated lock file to your version control system. +about what it has fetched and whether each package was signed using a +cryptographic signature, but it cannot automatically verify that the +providers are trustworthy and that they comply with your local system +policies or relevant regulations. Review the signing key information +in the output to confirm that you trust all of the signers before committing +the updated lock file to your version control system. If you list one or more provider source addresses on the command line then `terraform providers lock` will restrict its work only to those providers, @@ -74,21 +72,21 @@ You can customize the default behavior using the following additional option: * `-net-mirror=URL` - Direct Terraform to look for provider packages in the given network mirror service, instead of in upstream registries. The given URL must implement - [the Terraform provider network mirror protocol](/docs/internals/provider-network-mirror-protocol.html). + [the Terraform provider network mirror protocol](/internals/provider-network-mirror-protocol). * `-platform=OS_ARCH` - Specify a platform you intend to use to work with this Terraform configuration. Terraform will ensure that the providers are all available for the given platform and will save enough package checksums in the lock file to support _at least_ the specified platforms. - - Use this option multiple times to include checksums for multiple target - systems. - Target platform names consist of an operating system and a CPU - architecture. For example, `linux_amd64` selects the Linux operating system - running on an AMD64 or x86_64 CPU. + Use this option multiple times to include checksums for multiple target + systems. - There is more detail on this option in the following section. + Target platform names consist of an operating system and a CPU + architecture. For example, `linux_amd64` selects the Linux operating system + running on an AMD64 or x86_64 CPU. + + There is more detail on this option in the following section. ## Specifying Target Platforms @@ -150,7 +148,7 @@ multiple times and specify a different subset of your providers each time. The `-fs-mirror` and `-net-mirror` options have the same meaning as `filesystem_mirror` and `network_mirror` blocks in -[the provider installation methods configuration](/docs/cli/config/config-file.html#provider-installation), +[the provider installation methods configuration](/cli/config/config-file#provider-installation), but specify only a single method in order to be explicit about where you intend to derive the package checksum information from. @@ -167,4 +165,4 @@ If you wish, you can publish your in-house providers via an in-house provider registry, which will then allow locking and installation of those providers without any special options or additional CLI configuration. For more information, see -[the provider registry protocol](/docs/internals/provider-registry-protocol.html). +[the provider registry protocol](/internals/provider-registry-protocol). diff --git a/website/docs/cli/commands/providers/mirror.html.md b/website/docs/cli/commands/providers/mirror.mdx similarity index 89% rename from website/docs/cli/commands/providers/mirror.html.md rename to website/docs/cli/commands/providers/mirror.mdx index b0827837e..d6f9c8c8c 100644 --- a/website/docs/cli/commands/providers/mirror.html.md +++ b/website/docs/cli/commands/providers/mirror.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Command: providers mirror" -sidebar_current: "docs-commands-providers-mirror" +page_title: 'Command: providers mirror' description: |- The `terraform providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local @@ -19,7 +17,7 @@ from provider registries as part of initializing the current working directory. Sometimes Terraform is running in an environment where that isn't possible, such as on an isolated network without access to the Terraform Registry. In that case, -[explicit installation method configuration](/docs/cli/config/config-file.html#explicit-installation-method-configuration) +[explicit installation method configuration](/cli/config/config-file#explicit-installation-method-configuration) allows you to configure Terraform, when running on a particular system, to consult only a local filesystem directory where you've created a local mirror of the necessary plugins, and to skip accessing the upstream registry at all. @@ -41,7 +39,7 @@ themselves. Terraform will also generate various `.json` index files which contain suitable responses to implement -[the network mirror protocol](/docs/internals/provider-network-mirror-protocol.html), +[the network mirror protocol](/internals/provider-network-mirror-protocol), if you upload the resulting directory to a static website host. Terraform ignores those index files when using the directory as a filesystem mirror, because the directory entries themselves are authoritative in that case. diff --git a/website/docs/cli/commands/providers/schema.html.md b/website/docs/cli/commands/providers/schema.mdx similarity index 93% rename from website/docs/cli/commands/providers/schema.html.md rename to website/docs/cli/commands/providers/schema.mdx index 2a3dddc13..fbdeafc70 100644 --- a/website/docs/cli/commands/providers/schema.html.md +++ b/website/docs/cli/commands/providers/schema.mdx @@ -1,9 +1,9 @@ --- -layout: "docs" -page_title: "Command: providers schema" -sidebar_current: "docs-commands-providers-schema" -description: |- - The `terraform providers schema` command prints detailed schemas for the providers used +page_title: 'Command: providers schema' +description: >- + The `terraform providers schema` command prints detailed schemas for the + providers used + in the current configuration. --- @@ -19,7 +19,7 @@ Usage: `terraform providers schema [options]` The list of available flags are: -* `-json` - Displays the schemas in a machine-readable, JSON format. +- `-json` - Displays the schemas in a machine-readable, JSON format. Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. @@ -34,7 +34,7 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). +[the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises). ## Format Summary diff --git a/website/docs/cli/commands/push.html.md b/website/docs/cli/commands/push.mdx similarity index 61% rename from website/docs/cli/commands/push.html.md rename to website/docs/cli/commands/push.mdx index bc093a85c..7eb66776e 100644 --- a/website/docs/cli/commands/push.html.md +++ b/website/docs/cli/commands/push.mdx @@ -1,16 +1,14 @@ --- -layout: "docs" -page_title: "Command: push" -sidebar_current: "docs-commands-push" -description: |- - DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced the old `terraform push` command. +page_title: 'Command: push' +description: >- + DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced + the old `terraform push` command. --- # Command: push -!> **Important:** The `terraform push` command is no longer functional. Its functionality was replaced and surpassed by [the `remote` backend](/docs/language/settings/backends/remote.html), which works with current versions of Terraform Cloud. The `remote` backend allows you to run remote operations directly from the command line, and displays real-time output from the remote run environment. +!> **Important:** The `terraform push` command is no longer functional. Its functionality was replaced and surpassed by [the `remote` backend](/language/settings/backends/remote), which works with current versions of Terraform Cloud. The `remote` backend allows you to run remote operations directly from the command line, and displays real-time output from the remote run environment. The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise. The 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.html.md b/website/docs/cli/commands/refresh.mdx similarity index 88% rename from website/docs/cli/commands/refresh.html.md rename to website/docs/cli/commands/refresh.mdx index 55a007f38..898457fd8 100644 --- a/website/docs/cli/commands/refresh.html.md +++ b/website/docs/cli/commands/refresh.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Command: refresh" -sidebar_current: "docs-commands-refresh" +page_title: 'Command: refresh' description: |- The `terraform refresh` command reads the current settings from all managed remote objects and updates the Terraform state to match. @@ -14,19 +12,19 @@ description: |- The `terraform refresh` command reads the current settings from all managed remote objects and updates the Terraform state to match. -~> *Warning:* This command is deprecated, because its default behavior is +~> _Warning:_ This command is deprecated, because its default behavior is unsafe if you have misconfigured credentials for any of your providers. See below for more information and recommended alternatives. This won't modify your real remote objects, but it will modify the -[Terraform state](/docs/language/state/). +[Terraform state](/language/state). You shouldn't typically need to use this command, because Terraform automatically performs the same refreshing actions as a part of creating a plan in both the -[`terraform plan`](./plan.html) +[`terraform plan`](/cli/commands/plan) and -[`terraform apply`](./apply.html) +[`terraform apply`](/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. @@ -42,7 +40,7 @@ terraform apply -refresh-only -auto-approve ``` Consequently, it supports all of the same options as -[`terraform apply`](./apply.html) except that it does not accept a saved +[`terraform apply`](/cli/commands/apply) except that it does not accept a saved plan file, it doesn't allow selecting a planning mode other than "refresh only", and `-auto-approve` is always enabled. diff --git a/website/docs/cli/commands/show.html.md b/website/docs/cli/commands/show.mdx similarity index 81% rename from website/docs/cli/commands/show.html.md rename to website/docs/cli/commands/show.mdx index 45bc6fa3f..f956db19b 100644 --- a/website/docs/cli/commands/show.html.md +++ b/website/docs/cli/commands/show.mdx @@ -1,9 +1,10 @@ --- -layout: "docs" -page_title: "Command: show" -sidebar_current: "docs-commands-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: '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. --- # Command: show @@ -18,7 +19,7 @@ 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 -[Sensitive Data in State](/docs/language/state/sensitive-data.html). +[Sensitive Data in State](/language/state/sensitive-data). ## JSON Output @@ -34,7 +35,7 @@ was written, the state needs to be upgraded before it can be displayed with `-refresh=false`. If you are viewing a state file, run `terraform refresh` first. -The output format is covered in detail in [JSON Output Format](/docs/internals/json-format.html). +The output format is covered in detail in [JSON Output Format](/internals/json-format). ## Usage diff --git a/website/docs/cli/commands/state/index.html.md b/website/docs/cli/commands/state/index.mdx similarity index 82% rename from website/docs/cli/commands/state/index.html.md rename to website/docs/cli/commands/state/index.mdx index 38e2028d9..7b2f10ac8 100644 --- a/website/docs/cli/commands/state/index.html.md +++ b/website/docs/cli/commands/state/index.mdx @@ -1,16 +1,13 @@ --- -layout: "docs" -page_title: "Command: state" -sidebar_current: "docs-commands-state-index" -description: |- - The `terraform state` command is used for advanced state management. +page_title: 'Command: state' +description: The `terraform state` command is used for advanced state management. --- # State Command 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](/docs/language/state/index.html). +you may need to modify the [Terraform state](/language/state). Rather than modify the state directly, the `terraform state` commands can be used in many cases instead. @@ -35,7 +32,7 @@ written to disk and the CLI usage is the same as if it were local state. All `terraform state` subcommands that modify the state write backup files. The path of these backup file can be controlled with `-backup`. -Subcommands that are read-only (such as [list](/docs/cli/commands/state/list.html)) +Subcommands that are read-only (such as [list](/cli/commands/state/list)) do not write any backup files since they aren't modifying the state. Note that backups for state modification _can not be disabled_. Due to diff --git a/website/docs/cli/commands/state/list.html.md b/website/docs/cli/commands/state/list.mdx similarity index 84% rename from website/docs/cli/commands/state/list.html.md rename to website/docs/cli/commands/state/list.mdx index a7b78c94b..b4ed0e66c 100644 --- a/website/docs/cli/commands/state/list.html.md +++ b/website/docs/cli/commands/state/list.mdx @@ -1,15 +1,14 @@ --- -layout: "docs" -page_title: "Command: state list" -sidebar_current: "docs-commands-state-sub-list" -description: |- - The terraform state list command is used to list resources within a Terraform state. +page_title: 'Command: state list' +description: >- + The terraform state list command is used to list resources within a Terraform + state. --- # Command: state list The `terraform state list` command is used to list resources within a -[Terraform state](/docs/language/state/index.html). +[Terraform state](/language/state). ## Usage @@ -25,12 +24,12 @@ within modules are listed last. For complex infrastructures, the state can contain thousands of resources. To filter these, provide one or more patterns to the command. Patterns are -in [resource addressing format](/docs/cli/state/resource-addressing.html). +in [resource addressing format](/cli/state/resource-addressing). The command-line flags are all optional. The list of available flags are: * `-state=path` - Path to the state file. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. + Ignored when [remote state](/language/state/remote) is used. * `-id=id` - ID of resources to show. Ignored when unset. ## Example: All Resources diff --git a/website/docs/cli/commands/state/mv.html.md b/website/docs/cli/commands/state/mv.mdx similarity index 81% rename from website/docs/cli/commands/state/mv.html.md rename to website/docs/cli/commands/state/mv.mdx index 2cf2f8cd6..72999019e 100644 --- a/website/docs/cli/commands/state/mv.html.md +++ b/website/docs/cli/commands/state/mv.mdx @@ -1,14 +1,13 @@ --- -layout: "docs" -page_title: "Command: state mv" -sidebar_current: "docs-commands-state-sub-mv" -description: |- - The `terraform state mv` command changes bindings in Terraform state, associating existing remote objects with new resource instances. +page_title: 'Command: state mv' +description: >- + The `terraform state mv` command changes bindings in Terraform state, + associating existing remote objects with new resource instances. --- # Command: state mv -The main function of [Terraform state](/docs/language/state/index.html) is +The main function of [Terraform state](/language/state) is to track the bindings between resource instance addresses in your configuration and the remote objects they represent. Normally Terraform automatically updates the state in response to actions taken when applying a plan, such as @@ -29,7 +28,7 @@ remote objects currently associated with the source to be tracked instead by the destination. Both the source and destination addresses must use -[resource address syntax](/docs/cli/state/resource-addressing.html), and +[resource address syntax](/cli/state/resource-addressing), and they must both refer to the same kind of object: you can only move a resource instance to another resource instance, a whole module instance to another whole module instance, etc. Furthermore, if you are moving a resource or @@ -45,7 +44,7 @@ object and create a new object at the new address, and so `terraform state mv` allows you to override that interpretation by pre-emptively attaching the existing object to the new address in Terraform. -~> *Warning:* If you are using Terraform in a collaborative environment, you +~> _Warning:_ If you are using Terraform in a collaborative environment, you must ensure that when you are using `terraform state mv` for a code refactoring purpose you communicate carefully with your coworkers to ensure that nobody makes any other changes between your configuration change and your @@ -59,8 +58,8 @@ This command also accepts the following options: address without actually "forgetting" any of them. * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before @@ -68,23 +67,22 @@ This command also accepts the following options: unit letter, such as "3s" for three seconds. For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) +[the `remote` backend](/language/settings/backends/remote) only, `terraform state mv` also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). -The legacy options [`-backup` and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments) +The legacy options [`-backup` and `-backup-out`](/language/settings/backends/local#command-line-arguments) operate on a local state file only. Configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) -must specify a local state file with the [`-state`](/docs/language/settings/backends/local.html#command-line-arguments) -option in order to use the [`-backup` and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments) +[the `remote` backend](/language/settings/backends/remote) +must specify a local state file with the [`-state`](/language/settings/backends/local#command-line-arguments) +option in order to use the [`-backup` and `-backup-out`](/language/settings/backends/local#command-line-arguments) options. - For configurations using -[the `local` state mv](/docs/language/settings/backends/local.html) only, +[the `local` state mv](/language/settings/backends/local) only, `terraform state mv` also accepts the legacy options -[`-state`, `-state-out`, `-backup`, and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`, `-state-out`, `-backup`, and `-backup-out`](/language/settings/backends/local#command-line-arguments). ## Example: Rename a Resource @@ -136,7 +134,7 @@ terraform state mv module.app module.parent.module.app ## Example: Move a Particular Instance of a Resource using `count` -A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html) +A resource defined with [the `count` meta-argument](/language/meta-arguments/count) has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address: @@ -161,7 +159,7 @@ The above examples show the typical quoting syntax for Unix-style shells. ## Example: Move a Resource configured with for_each -A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html) +A resource defined with [the `for_each` meta-argument](/language/meta-arguments/for_each) has multiple instances that are each identified by an string. You can select a particular instance by including an explicit key in your given address. diff --git a/website/docs/cli/commands/state/pull.html.md b/website/docs/cli/commands/state/pull.mdx similarity index 77% rename from website/docs/cli/commands/state/pull.html.md rename to website/docs/cli/commands/state/pull.mdx index ad52c96b6..5fc5a7ba3 100644 --- a/website/docs/cli/commands/state/pull.html.md +++ b/website/docs/cli/commands/state/pull.mdx @@ -1,15 +1,14 @@ --- -layout: "docs" -page_title: "Command: state pull" -sidebar_current: "docs-commands-state-sub-pull" -description: |- - The `terraform state pull` command is used to manually download and output the state from remote state. +page_title: 'Command: state pull' +description: >- + The `terraform state pull` command is used to manually download and output the + state from remote state. --- # Command: state pull The `terraform state pull` command is used to manually download and output -the state from [remote state](/docs/language/state/remote.html). This command also +the state from [remote state](/language/state/remote). This command also works with local state. ## Usage diff --git a/website/docs/cli/commands/state/push.html.md b/website/docs/cli/commands/state/push.html.md deleted file mode 100644 index 2ba8f21da..000000000 --- a/website/docs/cli/commands/state/push.html.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: "docs" -page_title: "Command: state push" -sidebar_current: "docs-commands-state-sub-push" -description: |- - The `terraform state push` command pushes items to the Terraform state. ---- - -# Command: state push - -The `terraform state push` command is used to manually upload a local -state file to [remote state](/docs/language/state/remote.html). This command also -works with local state. - -This command should rarely be used. It is meant only as a utility in case -manual intervention is necessary with the remote state. - -## Usage - -Usage: `terraform state push [options] PATH` - -This command will push the state specified by PATH to the currently -configured [backend](/docs/language/settings/backends/index.html). - -If PATH is "-" then the state data to push is read from stdin. This data -is loaded completely into memory and verified prior to being written to -the destination state. - -Terraform will perform a number of safety checks to prevent you from -making changes that appear to be unsafe: - - * **Differing lineage**: If the "lineage" value in the state differs, - Terraform will not allow you to push the state. A differing lineage - suggests that the states are completely different and you may lose - data. - - * **Higher remote serial**: If the "serial" value in the destination state - is higher than the state being pushed, Terraform will prevent the push. - A higher serial suggests that data is in the destination state that isn't - accounted for in the local state being pushed. - -Both of these safety checks can be disabled with the `-force` flag. -**This is not recommended.** If you disable the safety checks and are -pushing state, the destination state will be overwritten. - -For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) -only, `terraform state push` -also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx new file mode 100644 index 000000000..853b53618 --- /dev/null +++ b/website/docs/cli/commands/state/push.mdx @@ -0,0 +1,47 @@ +--- +page_title: 'Command: state push' +description: The `terraform state push` command pushes items to the Terraform state. +--- + +# Command: state push + +The `terraform state push` command is used to manually upload a local +state file to [remote state](/language/state/remote). This command also +works with local state. + +This command should rarely be used. It is meant only as a utility in case +manual intervention is necessary with the remote state. + +## Usage + +Usage: `terraform state push [options] PATH` + +This command will push the state specified by PATH to the currently +configured [backend](/language/settings/backends). + +If PATH is "-" then the state data to push is read from stdin. This data +is loaded completely into memory and verified prior to being written to +the destination state. + +Terraform will perform a number of safety checks to prevent you from +making changes that appear to be unsafe: + +- **Differing lineage**: If the "lineage" value in the state differs, + Terraform will not allow you to push the state. A differing lineage + suggests that the states are completely different and you may lose + data. + +- **Higher remote serial**: If the "serial" value in the destination state + is higher than the state being pushed, Terraform will prevent the push. + A higher serial suggests that data is in the destination state that isn't + accounted for in the local state being pushed. + +Both of these safety checks can be disabled with the `-force` flag. +**This is not recommended.** If you disable the safety checks and are +pushing state, the destination state will be overwritten. + +For configurations using +[the `remote` backend](/language/settings/backends/remote) +only, `terraform state push` +also accepts the option +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). diff --git a/website/docs/cli/commands/state/replace-provider.html.md b/website/docs/cli/commands/state/replace-provider.mdx similarity index 65% rename from website/docs/cli/commands/state/replace-provider.html.md rename to website/docs/cli/commands/state/replace-provider.mdx index 21befd99e..3c74bd6e7 100644 --- a/website/docs/cli/commands/state/replace-provider.html.md +++ b/website/docs/cli/commands/state/replace-provider.mdx @@ -1,15 +1,14 @@ --- -layout: "docs" -page_title: "Command: state replace-provider" -sidebar_current: "docs-commands-state-sub-replace-provider" -description: |- - The `terraform state replace-provider` command replaces the provider for resources in the Terraform state. +page_title: 'Command: state replace-provider' +description: >- + The `terraform state replace-provider` command replaces the provider for + resources in the Terraform state. --- # Command: state replace-provider The `terraform state replace-provider` command is used to replace the provider -for resources in a [Terraform state](/docs/language/state/index.html). +for resources in a [Terraform state](/language/state). ## Usage @@ -28,22 +27,21 @@ This command also accepts the following options: * `-auto-approve` - Skip interactive approval. * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=0s` - Duration to retry a state lock. For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) +[the `remote` backend](/language/settings/backends/remote) only, `terraform state replace-provider` also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). For configurations using -[the `local` state rm](/docs/language/settings/backends/local.html) only, +[the `local` state rm](/language/settings/backends/local) only, `terraform state replace-provider` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). - +[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). ## Example diff --git a/website/docs/cli/commands/state/rm.html.md b/website/docs/cli/commands/state/rm.mdx similarity index 80% rename from website/docs/cli/commands/state/rm.html.md rename to website/docs/cli/commands/state/rm.mdx index 131c31a81..034265767 100644 --- a/website/docs/cli/commands/state/rm.html.md +++ b/website/docs/cli/commands/state/rm.mdx @@ -1,14 +1,13 @@ --- -layout: "docs" -page_title: "Command: state rm" -sidebar_current: "docs-commands-state-sub-rm" -description: |- - The `terraform state rm` command removes bindings from the Terraform state, causing Terraform to "forget about" existing objects. +page_title: 'Command: state rm' +description: >- + The `terraform state rm` command removes bindings from the Terraform state, + causing Terraform to "forget about" existing objects. --- # Command: state rm -The main function of [Terraform state](/docs/language/state/index.html) is +The main function of [Terraform state](/language/state) is to track the bindings between resource instance addresses in your configuration and the remote objects they represent. Normally Terraform automatically updates the state in response to actions taken when applying a plan, such as @@ -24,13 +23,13 @@ to exist in the remote system. Usage: `terraform state rm [options] ADDRESS...` Terraform will search the state for any instances matching the given -[resource address](/docs/cli/state/resource-addressing.html), and remove +[resource address](/cli/state/resource-addressing), and remove the record of each one so that Terraform will no longer be tracking the corresponding remote objects. This means that although the objects will still continue to exist in the remote system, a subsequent -[`terraform plan`](../plan.html) +[`terraform plan`](/cli/commands/plan) will include an action to create a new object for each of the "forgotten" instances. Depending on the constraints imposed by the remote system, creating those objects might fail if their names or other identifiers conflict with @@ -42,8 +41,8 @@ This command also accepts the following options: address without actually "forgetting" any of them. * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before @@ -51,15 +50,15 @@ This command also accepts the following options: unit letter, such as "3s" for three seconds. For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) +[the `remote` backend](/language/settings/backends/remote) only, `terraform state rm` also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). For configurations using -[the `local` state rm](/docs/language/settings/backends/local.html) only, +[the `local` state rm](/language/settings/backends/local) only, `terraform state rm` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). ## Example: Remove all Instances of a Resource @@ -94,7 +93,7 @@ $ terraform state rm 'module.foo' ## Example: Remove a Particular Instance of a Resource using `count` -A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html) +A resource defined with [the `count` meta-argument](/language/meta-arguments/count) has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address: @@ -109,7 +108,7 @@ The above shows the typical quoting syntax for Unix-style shells. ## Example: Remove a Particular Instance of a Resource using `for_each` -A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html) +A resource defined with [the `for_each` meta-argument](/language/meta-arguments/for_each) has multiple instances that are each identified by an string. You can select a particular instance by including an explicit key in your given address. diff --git a/website/docs/cli/commands/state/show.html.md b/website/docs/cli/commands/state/show.mdx similarity index 78% rename from website/docs/cli/commands/state/show.html.md rename to website/docs/cli/commands/state/show.mdx index 2c665ba64..46032ac31 100644 --- a/website/docs/cli/commands/state/show.html.md +++ b/website/docs/cli/commands/state/show.mdx @@ -1,16 +1,15 @@ --- -layout: "docs" -page_title: "Command: state show" -sidebar_current: "docs-commands-state-sub-show" -description: |- - The `terraform state show` command is used to show the attributes of a single resource in the Terraform state. +page_title: 'Command: state show' +description: >- + The `terraform state show` command is used to show the attributes of a single + resource in the Terraform state. --- # Command: state show The `terraform state show` command is used to show the attributes of a single resource in the -[Terraform state](/docs/language/state/index.html). +[Terraform state](/language/state). ## Usage @@ -21,16 +20,16 @@ state file that matches the given address. This command requires an address that points to a single resource in the state. Addresses are -in [resource addressing format](/docs/cli/state/resource-addressing.html). +in [resource addressing format](/cli/state/resource-addressing). The command-line flags are all optional. The list of available flags are: * `-state=path` - Path to the state file. Defaults to "terraform.tfstate". - Ignored when [remote state](/docs/language/state/remote.html) is used. + Ignored when [remote state](/language/state/remote) is used. The output of `terraform state show` is intended for human consumption, not programmatic consumption. To extract state data for use in other software, use -[`terraform show -json`](/docs/cli/commands/show.html#json-output) and decode the result +[`terraform show -json`](/cli/commands/show#json-output) and decode the result using the documented structure. ## Example: Show a Resource @@ -61,7 +60,7 @@ $ terraform state show 'module.foo.packet_device.worker' ## Example: Show a Resource configured with count The example below shows the first instance of a `packet_device` resource named `worker` configured with -[`count`](/docs/language/meta-arguments/count.html): +[`count`](/language/meta-arguments/count): ```shell $ terraform state show 'packet_device.worker[0]' @@ -70,7 +69,7 @@ $ terraform state show 'packet_device.worker[0]' ## Example: Show a Resource configured with for_each The example below shows the `"example"` instance of a `packet_device` resource named `worker` configured with -[`for_each`](/docs/language/meta-arguments/for_each.html): +[`for_each`](/language/meta-arguments/for_each): Linux, Mac OS, and UNIX: diff --git a/website/docs/cli/commands/taint.html.md b/website/docs/cli/commands/taint.mdx similarity index 73% rename from website/docs/cli/commands/taint.html.md rename to website/docs/cli/commands/taint.mdx index aeffa1d7b..f0fcf1b1a 100644 --- a/website/docs/cli/commands/taint.html.md +++ b/website/docs/cli/commands/taint.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Command: taint" -sidebar_current: "docs-commands-taint" +page_title: 'Command: taint' description: |- The `terraform taint` command informs Terraform that a particular object is damaged or degraded. @@ -14,12 +12,12 @@ become degraded or damaged. Terraform represents this by marking the object as "tainted" in the Terraform state, in which case Terraform will propose to replace it in the next plan you create. -~> *Warning:* This command is deprecated, because there are better alternatives +~> _Warning:_ This command is deprecated, because there are better alternatives available in Terraform v0.15.2 and later. See below for more details. If your intent is to force replacement of a particular object even though there are no configuration changes that would require it, we recommend instead -to use the `-replace` option with [`terraform apply`](./apply.html). +to use the `-replace` option with [`terraform apply`](/cli/commands/apply). For example: ``` @@ -44,13 +42,13 @@ Usage: `terraform taint [options] address` The `address` argument is the address of the resource to mark as tainted. The address is in -[the resource address syntax](/docs/cli/state/resource-addressing.html) syntax, +[the resource address syntax](/cli/state/resource-addressing) syntax, as shown in the output from other commands, such as: - * `aws_instance.foo` - * `aws_instance.bar[1]` - * `aws_instance.baz[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they will not be interpreted by your shell) - * `module.foo.module.bar.aws_instance.qux` +* `aws_instance.foo` +* `aws_instance.bar[1]` +* `aws_instance.baz[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they will not be interpreted by your shell) +* `module.foo.module.bar.aws_instance.qux` This command accepts the following options: @@ -68,12 +66,12 @@ This command accepts the following options: unit letter, such as "3s" for three seconds. For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) +[the `remote` backend](/language/settings/backends/remote) only, `terraform taint` also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, +[the `local` backend](/language/settings/backends/local) only, `terraform taint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). diff --git a/website/docs/cli/commands/test.html.md b/website/docs/cli/commands/test.mdx similarity index 52% rename from website/docs/cli/commands/test.html.md rename to website/docs/cli/commands/test.mdx index 7edd1fb1b..282c21710 100644 --- a/website/docs/cli/commands/test.html.md +++ b/website/docs/cli/commands/test.mdx @@ -1,15 +1,12 @@ --- -layout: "docs" -page_title: "Command: test" -sidebar_current: "docs-commands-test" -description: |- - Part of the ongoing design research for module integration testing. +page_title: 'Command: test' +description: Part of the ongoing design research for module integration testing. --- # Command: test The `terraform test` command is currently serving as part of -[the module integration testing experiment](/docs/language/modules/testing-experiment.html). +[the module integration testing experiment](/language/modules/testing-experiment). It's not ready for routine use, but if you'd be interested in trying the prototype functionality then we'd love to hear your feedback. See the diff --git a/website/docs/cli/commands/untaint.html.md b/website/docs/cli/commands/untaint.mdx similarity index 78% rename from website/docs/cli/commands/untaint.html.md rename to website/docs/cli/commands/untaint.mdx index 12793958b..85e210a6a 100644 --- a/website/docs/cli/commands/untaint.html.md +++ b/website/docs/cli/commands/untaint.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Command: untaint" -sidebar_current: "docs-commands-untaint" +page_title: 'Command: untaint' description: |- The `terraform untaint` command tells Terraform that an object is functioning correctly, even though its creation failed or it was previously manually @@ -18,7 +16,7 @@ a multi-step "create" action, because Terraform can't be sure that the object was left in a fully-functional state. You can also manually mark an object as "tainted" using the deprecated command -[`terraform taint`](./taint.html), although we no longer recommend that +[`terraform taint`](/cli/commands/taint), although we no longer recommend that workflow. If Terraform currently considers a particular object as tainted but you've @@ -40,7 +38,7 @@ terraform apply -replace="aws_instance.example[0]" Usage: `terraform untaint [options] address` -The `address` argument is a [resource address](/docs/cli/state/resource-addressing.html) +The `address` argument is a [resource address](/cli/state/resource-addressing) identifying a particular resource instance which is currently tainted. This command also accepts the following options: @@ -51,8 +49,8 @@ This command also accepts the following options: the state. * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before @@ -64,12 +62,12 @@ This command also accepts the following options: rendered by a system that cannot interpret terminal formatting. For configurations using -[the `remote` backend](/docs/language/settings/backends/remote.html) +[the `remote` backend](/language/settings/backends/remote) only, `terraform untaint` also accepts the option -[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). +[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). For configurations using -[the `local` backend](/docs/language/settings/backends/local.html) only, +[the `local` backend](/language/settings/backends/local) only, `terraform untaint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). diff --git a/website/docs/cli/commands/validate.html.md b/website/docs/cli/commands/validate.mdx similarity index 56% rename from website/docs/cli/commands/validate.html.md rename to website/docs/cli/commands/validate.mdx index e81da01b2..fbbb03971 100644 --- a/website/docs/cli/commands/validate.html.md +++ b/website/docs/cli/commands/validate.mdx @@ -1,9 +1,8 @@ --- -layout: "docs" -page_title: "Command: validate" -sidebar_current: "docs-commands-validate" -description: |- - The `terraform validate` command is used to validate the syntax of the terraform files. +page_title: 'Command: validate' +description: >- + The `terraform validate` command is used to validate the syntax of the + terraform files. --- # Command: validate @@ -39,11 +38,11 @@ Usage: `terraform validate [options]` This command accepts the following options: -- `-json` - Produce output in a machine-readable JSON format, suitable for +* `-json` - Produce output in a machine-readable JSON format, suitable for use in text editor integrations and other automated systems. Always disables color. -- `-no-color` - If specified, output won't contain any color. +* `-no-color` - If specified, output won't contain any color. ## JSON Output Format @@ -60,15 +59,15 @@ JSON, which it should then treat as a generic error case. The output includes a `format_version` key, which as of Terraform 1.1.0 has value `"1.0"`. The semantics of this version are: -- We will increment the minor version, e.g. `"1.1"`, for backward-compatible +* We will increment the minor version, e.g. `"1.1"`, for backward-compatible changes or additions. Ignore any object properties with unrecognized names to remain forward-compatible with future minor versions. -- We will increment the major version, e.g. `"2.0"`, for changes that are not +* We will increment the major version, e.g. `"2.0"`, for changes that are not backward-compatible. Reject any input which reports an unsupported major version. We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). +[the Terraform 1.0 Compatibility Promises](/language/v1-compatibility-promises). In the normal case, Terraform will print a JSON object to the standard output stream. The top-level JSON object will have the following properties: @@ -95,93 +94,93 @@ The nested objects in `diagnostics` have the following properties: * `severity` (string): A string keyword, currently either `"error"` or `"warning"`, indicating the diagnostic severity. - The presence of errors causes Terraform to consider a configuration to be - invalid, while warnings are just advice or caveats to the user which do not - block working with the configuration. Later versions of Terraform may - introduce new severity keywords, so consumers should be prepared to accept - and ignore severity values they don't understand. + The presence of errors causes Terraform to consider a configuration to be + invalid, while warnings are just advice or caveats to the user which do not + block working with the configuration. Later versions of Terraform may + introduce new severity keywords, so consumers should be prepared to accept + and ignore severity values they don't understand. * `summary` (string): A short description of the nature of the problem that the diagnostic is reporting. - In Terraform's usual human-oriented diagnostic messages, the summary serves - as a sort of "heading" for the diagnostic, printed after the "Error:" or - "Warning:" indicator. + In Terraform's usual human-oriented diagnostic messages, the summary serves + as a sort of "heading" for the diagnostic, printed after the "Error:" or + "Warning:" indicator. - Summaries are typically short, single sentences, but can sometimes be longer - as a result of returning errors from subsystems that are not designed to - return full diagnostics, where the entire error message therefore becomes the - summary. In those cases, the summary might include newline characters which - a renderer should honor when presenting the message visually to a user. + Summaries are typically short, single sentences, but can sometimes be longer + as a result of returning errors from subsystems that are not designed to + return full diagnostics, where the entire error message therefore becomes the + summary. In those cases, the summary might include newline characters which + a renderer should honor when presenting the message visually to a user. * `detail` (string): An optional additional message giving more detail about the problem. - In Terraform's usual human-oriented diagnostic messages, the detail provides - the paragraphs of text that appear after the heading and the source location - reference. + In Terraform's usual human-oriented diagnostic messages, the detail provides + the paragraphs of text that appear after the heading and the source location + reference. - Detail messages are often multiple paragraphs and possibly interspersed with - non-paragraph lines, so tools which aim to present detail messages to the - user should distinguish between lines without leading spaces, treating them - as paragraphs, and lines with leading spaces, treating them as preformatted - text. Renderers should then soft-wrap the paragraphs to fit the width of the - rendering container, but leave the preformatted lines unwrapped. + Detail messages are often multiple paragraphs and possibly interspersed with + non-paragraph lines, so tools which aim to present detail messages to the + user should distinguish between lines without leading spaces, treating them + as paragraphs, and lines with leading spaces, treating them as preformatted + text. Renderers should then soft-wrap the paragraphs to fit the width of the + rendering container, but leave the preformatted lines unwrapped. - Some Terraform detail messages currently contain an approximation of bullet - lists using ASCII characters to mark the bullets. This is not currently a - contractural formatting convention and so renderers should avoid depending on - it and should instead treat those lines as either paragraphs or preformatted - text per the rules above. A future version of this format may define some - additional rules for processing other text conventions, but will do so within - the bounds of the rules above to achieve backward-compatibility. + Some Terraform detail messages currently contain an approximation of bullet + lists using ASCII characters to mark the bullets. This is not currently a + contractural formatting convention and so renderers should avoid depending on + it and should instead treat those lines as either paragraphs or preformatted + text per the rules above. A future version of this format may define some + additional rules for processing other text conventions, but will do so within + the bounds of the rules above to achieve backward-compatibility. * `range` (object): An optional object referencing a portion of the configuration source code that the diagnostic message relates to. For errors, this will typically indicate the bounds of the specific block header, attribute, or expression which was detected as invalid. - A source range is an object with a property `filename` which gives the - filename as a relative path from the current working directory, and then - two properties `start` and `end` which are both themselves objects - describing source positions, as described below. + A source range is an object with a property `filename` which gives the + filename as a relative path from the current working directory, and then + two properties `start` and `end` which are both themselves objects + describing source positions, as described below. - Not all diagnostic messages are connected with specific portions of the - configuration, so `range` will be omitted or `null` for diagnostic messages - where it isn't relevant. + Not all diagnostic messages are connected with specific portions of the + configuration, so `range` will be omitted or `null` for diagnostic messages + where it isn't relevant. * `snippet` (object): An optional object including an excerpt of the configuration source code that the diagnostic message relates to. - The snippet information includes: + The snippet information includes: - * `context` (string): An optional summary of the root context of the - diagnostic. For example, this might be the resource block containing the - expression which triggered the diagnostic. For some diagnostics this - information is not available, and then this property will be `null`. + * `context` (string): An optional summary of the root context of the + diagnostic. For example, this might be the resource block containing the + expression which triggered the diagnostic. For some diagnostics this + information is not available, and then this property will be `null`. - * `code` (string): A snippet of Terraform configuration including the - source of the diagnostic. This can be multiple lines and may include - additional configuration source code around the expression which - triggered the diagnostic. + * `code` (string): A snippet of Terraform configuration including the + source of the diagnostic. This can be multiple lines and may include + additional configuration source code around the expression which + triggered the diagnostic. - * `start_line` (number): A one-based line count representing the position - in the source file at which the `code` excerpt begins. This is not - necessarily the same value as `range.start.line`, as it is possible for - `code` to include one or more lines of context before the source of the - diagnostic. + * `start_line` (number): A one-based line count representing the position + in the source file at which the `code` excerpt begins. This is not + necessarily the same value as `range.start.line`, as it is possible for + `code` to include one or more lines of context before the source of the + diagnostic. - * `highlight_start_offset` (number): A zero-based character offset into the - `code` string, pointing at the start of the expression which triggered - the diagnostic. + * `highlight_start_offset` (number): A zero-based character offset into the + `code` string, pointing at the start of the expression which triggered + the diagnostic. - * `highlight_end_offset` (number): A zero-based character offset into the - `code` string, pointing at the end of the expression which triggered the - diagnostic. + * `highlight_end_offset` (number): A zero-based character offset into the + `code` string, pointing at the end of the expression which triggered the + diagnostic. - * `values` (array of objects): Contains zero or more expression values - which may be useful in understanding the source of a diagnostic in a - complex expression. These expression value objects are described below. + * `values` (array of objects): Contains zero or more expression values + which may be useful in understanding the source of a diagnostic in a + complex expression. These expression value objects are described below. ### Source Position diff --git a/website/docs/cli/commands/version.html.md b/website/docs/cli/commands/version.mdx similarity index 75% rename from website/docs/cli/commands/version.html.md rename to website/docs/cli/commands/version.mdx index 917983801..bcfa5f0b7 100644 --- a/website/docs/cli/commands/version.html.md +++ b/website/docs/cli/commands/version.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Command: version" -sidebar_current: "docs-commands-version" -description: "The terraform version command displays the Terraform version and the version of all installed plugins." +page_title: 'Command: version' +description: >- + The terraform version command displays the Terraform version and the version + of all installed plugins. --- # Command: version @@ -16,12 +16,12 @@ 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](/docs/cli/commands/index.html#upgrade-and-security-bulletin-checks). +and security checks [unless disabled](/cli/commands#upgrade-and-security-bulletin-checks). This command has one optional flag: * `-json` - If specified, the version information is formatted as a JSON object, - and no upgrade or security information is included. + and no upgrade or security information is included. -> **Note:** Platform information was added to the `version` command in Terraform 0.15. @@ -51,4 +51,4 @@ $ terraform version -json }, "terraform_outdated": true } -``` \ No newline at end of file +``` diff --git a/website/docs/cli/commands/workspace/delete.html.md b/website/docs/cli/commands/workspace/delete.mdx similarity index 81% rename from website/docs/cli/commands/workspace/delete.html.md rename to website/docs/cli/commands/workspace/delete.mdx index 3fd077631..cadfa6459 100644 --- a/website/docs/cli/commands/workspace/delete.html.md +++ b/website/docs/cli/commands/workspace/delete.mdx @@ -1,9 +1,6 @@ --- -layout: "docs" -page_title: "Command: workspace delete" -sidebar_current: "docs-commands-workspace-sub-delete" -description: |- - The terraform workspace delete command is used to delete a workspace. +page_title: 'Command: workspace delete' +description: The terraform workspace delete command is used to delete a workspace. --- # Command: workspace delete @@ -31,8 +28,8 @@ The command-line flags are all optional. The only supported flag is: * `-force` - Delete the workspace even if its state is not empty. Defaults to false. * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s. ## Example diff --git a/website/docs/cli/commands/workspace/index.html.md b/website/docs/cli/commands/workspace/index.mdx similarity index 60% rename from website/docs/cli/commands/workspace/index.html.md rename to website/docs/cli/commands/workspace/index.mdx index 6237a4133..2d67b1d7c 100644 --- a/website/docs/cli/commands/workspace/index.html.md +++ b/website/docs/cli/commands/workspace/index.mdx @@ -1,15 +1,12 @@ --- -layout: "docs" -page_title: "Command: workspace" -sidebar_current: "docs-commands-workspace-index" -description: "The workspace command helps you manage workspaces." - +page_title: 'Command: workspace' +description: The workspace command helps you manage workspaces. --- # Command: workspace The `terraform workspace` command is used to manage -[workspaces](/docs/language/state/workspaces.html). +[workspaces](/language/state/workspaces). This command is a container for further subcommands. These subcommands are listed in the navigation bar. diff --git a/website/docs/cli/commands/workspace/list.html.md b/website/docs/cli/commands/workspace/list.mdx similarity index 64% rename from website/docs/cli/commands/workspace/list.html.md rename to website/docs/cli/commands/workspace/list.mdx index 2114a60c6..d7d2e6eee 100644 --- a/website/docs/cli/commands/workspace/list.html.md +++ b/website/docs/cli/commands/workspace/list.mdx @@ -1,9 +1,6 @@ --- -layout: "docs" -page_title: "Command: workspace list" -sidebar_current: "docs-commands-workspace-sub-list" -description: |- - The terraform workspace list command is used to list all existing workspaces. +page_title: 'Command: workspace list' +description: The terraform workspace list command is used to list all existing workspaces. --- # Command: workspace list diff --git a/website/docs/cli/commands/workspace/new.html.md b/website/docs/cli/commands/workspace/new.mdx similarity index 83% rename from website/docs/cli/commands/workspace/new.html.md rename to website/docs/cli/commands/workspace/new.mdx index ef2e73ecf..28b4d1c30 100644 --- a/website/docs/cli/commands/workspace/new.html.md +++ b/website/docs/cli/commands/workspace/new.mdx @@ -1,9 +1,6 @@ --- -layout: "docs" -page_title: "Command: workspace new" -sidebar_current: "docs-commands-workspace-sub-new" -description: |- - The terraform workspace new command is used to create a new workspace. +page_title: 'Command: workspace new' +description: The terraform workspace new command is used to create a new workspace. --- # Command: workspace new @@ -23,8 +20,8 @@ will be copied to initialize the state for this new workspace. The command-line flags are all optional. The supported flags are: * `-lock=false` - Don't hold a state lock during the operation. This is - dangerous if others might concurrently run commands against the same - workspace. + dangerous if others might concurrently run commands against the same + workspace. * `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s. * `-state=path` - Path to an existing state file to initialize the state of this environment. diff --git a/website/docs/cli/commands/workspace/select.html.md b/website/docs/cli/commands/workspace/select.mdx similarity index 69% rename from website/docs/cli/commands/workspace/select.html.md rename to website/docs/cli/commands/workspace/select.mdx index 08170a61e..f22f7aabe 100644 --- a/website/docs/cli/commands/workspace/select.html.md +++ b/website/docs/cli/commands/workspace/select.mdx @@ -1,9 +1,6 @@ --- -layout: "docs" -page_title: "Command: workspace select" -sidebar_current: "docs-commands-workspace-sub-select" -description: |- - The terraform workspace select command is used to choose a workspace. +page_title: 'Command: workspace select' +description: The terraform workspace select command is used to choose a workspace. --- # Command: workspace select diff --git a/website/docs/cli/commands/workspace/show.html.md b/website/docs/cli/commands/workspace/show.mdx similarity index 57% rename from website/docs/cli/commands/workspace/show.html.md rename to website/docs/cli/commands/workspace/show.mdx index 7cd7d5b5d..c6063f22f 100644 --- a/website/docs/cli/commands/workspace/show.html.md +++ b/website/docs/cli/commands/workspace/show.mdx @@ -1,9 +1,6 @@ --- -layout: "docs" -page_title: "Command: workspace show" -sidebar_current: "docs-commands-workspace-sub-show" -description: |- - The terraform workspace show command is used to output the current workspace. +page_title: 'Command: workspace show' +description: The terraform workspace show command is used to output the current workspace. --- # Command: workspace show diff --git a/website/docs/cli/config/config-file.html.md b/website/docs/cli/config/config-file.mdx similarity index 86% rename from website/docs/cli/config/config-file.html.md rename to website/docs/cli/config/config-file.mdx index 1aa83c40e..6e97aee35 100644 --- a/website/docs/cli/config/config-file.html.md +++ b/website/docs/cli/config/config-file.mdx @@ -1,15 +1,15 @@ --- -layout: "docs" -page_title: "CLI Configuration" -sidebar_current: "docs-commands-cli-config" -description: "Learn to use the CLI configuration file to customize your CLI settings, including credentials, plugin caching, provider installation methods, etc." +page_title: CLI Configuration +description: >- + Learn to use the CLI configuration file to customize your CLI settings, + including credentials, plugin caching, provider installation methods, etc. --- # CLI Configuration File (`.terraformrc` or `terraform.rc`) 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](/docs/language/index.html). +[your infrastructure configuration](/language). ## Locations @@ -31,7 +31,7 @@ as just `terraform.rc`. Use `dir` from PowerShell or Command Prompt to confirm the filename. The location of the Terraform CLI configuration file can also be specified -using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/cli/config/environment-variables.html). +using the `TF_CLI_CONFIG_FILE` [environment variable](/cli/config/environment-variables). Any such file should follow the naming pattern `*.tfrc`. ## Configuration File Syntax @@ -50,38 +50,38 @@ disable_checkpoint = true The following settings can be set in the CLI configuration file: -- `credentials` - configures credentials for use with Terraform Cloud or +* `credentials` - configures credentials for use with Terraform Cloud or Terraform Enterprise. See [Credentials](#credentials) below for more information. -- `credentials_helper` - configures an external helper program for the storage +* `credentials_helper` - configures an external helper program for the storage and retrieval of credentials for Terraform Cloud or Terraform Enterprise. See [Credentials Helpers](#credentials-helpers) below for more information. -- `disable_checkpoint` — when set to `true`, disables - [upgrade and security bulletin checks](/docs/cli/commands/index.html#upgrade-and-security-bulletin-checks) +* `disable_checkpoint` — when set to `true`, disables + [upgrade and security bulletin checks](/cli/commands#upgrade-and-security-bulletin-checks) that require reaching out to HashiCorp-provided network services. -- `disable_checkpoint_signature` — when set to `true`, allows the upgrade and +* `disable_checkpoint_signature` — when set to `true`, allows the upgrade and security bulletin checks described above but disables the use of an anonymous id used to de-duplicate warning messages. -- `plugin_cache_dir` — enables +* `plugin_cache_dir` — enables [plugin caching](#provider-plugin-cache) and specifies, as a string, the location of the plugin cache directory. -- `provider_installation` - customizes the installation methods used by +* `provider_installation` - customizes the installation methods used by `terraform init` when installing provider plugins. See [Provider Installation](#provider-installation) below for more information. ## Credentials -[Terraform Cloud](/docs/cloud/index.html) provides a number of remote network +[Terraform Cloud](/cloud) provides a number of remote network services for use with Terraform, and -[Terraform Enterprise](/docs/enterprise/index.html) allows hosting those +[Terraform Enterprise](/enterprise) allows hosting those services inside your own infrastructure. For example, these systems offer both -[remote operations](/docs/cloud/run/cli.html) and a -[private module registry](/docs/cloud/registry/index.html). +[remote operations](/cloud-docs/run/cli) and a +[private module registry](/cloud-docs/registry). When interacting with Terraform-specific network services, Terraform expects to find API tokens in CLI configuration files in `credentials` blocks: @@ -92,7 +92,7 @@ credentials "app.terraform.io" { } ``` -If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/docs/cli/commands/login.html) +If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/cli/commands/login) to get credentials and automatically save them in the CLI configuration. If not, you can manually write `credentials` blocks. @@ -104,9 +104,9 @@ giving the API token to use for that host. ~> **Important:** If you are using Terraform Cloud or Terraform Enterprise, the token provided must be either a -[user token](/docs/cloud/users-teams-organizations/users.html#api-tokens) +[user token](/cloud-docs/users-teams-organizations/users#api-tokens) or a -[team token](/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens); +[team token](/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens); organization tokens cannot be used for command-line Terraform actions. -> **Note:** The credentials hostname must match the hostname in your module @@ -144,7 +144,7 @@ for a specific hostname by writing a `credentials` block alongside the Terraform does not include any credentials helpers in the main distribution. To learn how to write and install your own credentials helpers to integrate with existing in-house credentials management systems, see -[the guide to Credentials Helper internals](/docs/internals/credentials-helpers.html). +[the guide to Credentials Helper internals](/internals/credentials-helpers). ## Provider Installation @@ -216,36 +216,36 @@ The following are the two supported installation method types: providers. This method requires the additional argument `path` to indicate which directory to look in. - Terraform expects the given directory to contain a nested directory structure - where the path segments together provide metadata about the available - providers. The following two directory structures are supported: + Terraform expects the given directory to contain a nested directory structure + where the path segments together provide metadata about the available + providers. The following two directory structures are supported: - * Packed layout: `HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip` - is the distribution zip file obtained from the provider's origin registry. - * Unpacked layout: `HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET` is a directory - containing the result of extracting the provider's distribution zip file. + * Packed layout: `HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip` + is the distribution zip file obtained from the provider's origin registry. + * Unpacked layout: `HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET` is a directory + containing the result of extracting the provider's distribution zip file. - In both layouts, the `VERSION` is a string like `2.0.0` and the `TARGET` - specifies a particular target platform using a format like `darwin_amd64`, - `linux_arm`, `windows_amd64`, etc. + In both layouts, the `VERSION` is a string like `2.0.0` and the `TARGET` + specifies a particular target platform using a format like `darwin_amd64`, + `linux_arm`, `windows_amd64`, etc. - If you use the unpacked layout, Terraform will attempt to create a symbolic - link to the mirror directory when installing the provider, rather than - creating a deep copy of the directory. The packed layout prevents this - because Terraform must extract the zip file during installation. + If you use the unpacked layout, Terraform will attempt to create a symbolic + link to the mirror directory when installing the provider, rather than + creating a deep copy of the directory. The packed layout prevents this + because Terraform must extract the zip file during installation. - You can include multiple `filesystem_mirror` blocks in order to specify - several different directories to search. + You can include multiple `filesystem_mirror` blocks in order to specify + several different directories to search. * `network_mirror`: consult a particular HTTPS server for copies of providers, regardless of which registry host they belong to. This method requires the additional argument `url` to indicate the mirror base URL, which should use the `https:` scheme and end with a trailing slash. - Terraform expects the given URL to be a base URL for an implementation of - [the provider network mirror protocol](/docs/internals/provider-network-mirror-protocol.html), - which is designed to be relatively easy to implement using typical static - website hosting mechanisms. + Terraform expects the given URL to be a base URL for an implementation of + [the provider network mirror protocol](/internals/provider-network-mirror-protocol), + which is designed to be relatively easy to implement using typical static + website hosting mechanisms. ~> **Warning:** Don't configure `network_mirror` URLs that you do not trust. Provider mirror servers are subject to TLS certificate checks to verify @@ -402,7 +402,7 @@ provider_installation { With development overrides in effect, the `terraform init` command will still attempt to select a suitable published version of your provider to install and record in -[the dependency lock file](/docs/language/dependency-lock.html) +[the dependency lock file](/language/files/dependency-lock) for future use, but other commands like `terraform apply` will disregard the lock file's entry for `hashicorp/null` and will use the given directory instead. Once your new changes are included in a diff --git a/website/docs/cli/config/environment-variables.html.md b/website/docs/cli/config/environment-variables.mdx similarity index 88% rename from website/docs/cli/config/environment-variables.html.md rename to website/docs/cli/config/environment-variables.mdx index 55997e97e..ffe749ec6 100644 --- a/website/docs/cli/config/environment-variables.html.md +++ b/website/docs/cli/config/environment-variables.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Environment Variables" -sidebar_current: "docs-commands-environment-variables" -description: "Learn to use environment variables to change Terraform's default behavior. Configure log content and output, set variables, and more." +page_title: Environment Variables +description: >- + Learn to use environment variables to change Terraform's default behavior. + Configure log content and output, set variables, and more. --- # Environment Variables @@ -27,7 +27,7 @@ To disable, either unset it, or set it to `off`. For example: export TF_LOG=off ``` -For more on debugging Terraform, check out the section on [Debugging](/docs/internals/debugging.html). +For more on debugging Terraform, check out the section on [Debugging](/internals/debugging). ## TF_LOG_PATH @@ -37,7 +37,7 @@ This specifies where the log should persist its output to. Note that even when ` export TF_LOG_PATH=./terraform.log ``` -For more on debugging Terraform, check out the section on [Debugging](/docs/internals/debugging.html). +For more on debugging Terraform, check out the section on [Debugging](/internals/debugging). ## TF_INPUT @@ -58,9 +58,10 @@ export TF_VAR_alist='[1,2,3]' export TF_VAR_amap='{ foo = "bar", baz = "qux" }' ``` -For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/docs/language/values/variables.html). +For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/language/values/variables). ## TF_CLI_ARGS and TF_CLI_ARGS_name + The value of `TF_CLI_ARGS` will specify additional arguments to the @@ -113,8 +114,7 @@ export TF_WORKSPACE=your_workspace Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state. -For more information regarding workspaces, check out the section on [Using Workspaces] -(https://www.terraform.io/docs/language/state/workspaces.html). +For more information regarding workspaces, check out the section on [Using Workspaces](/language/state/workspaces). ## TF_IN_AUTOMATION @@ -145,7 +145,7 @@ export TF_REGISTRY_CLIENT_TIMEOUT=15 ## TF_CLI_CONFIG_FILE -The location of the [Terraform CLI configuration file](/docs/cli/config/config-file.html). +The location of the [Terraform CLI configuration file](/cli/config/config-file). ```shell export TF_CLI_CONFIG_FILE="$HOME/.terraformrc-custom" @@ -159,4 +159,4 @@ If `TF_IGNORE` is set to "trace", Terraform will output debug messages to displa export TF_IGNORE=trace ``` -For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/docs/language/settings/backends/remote.html#excluding-files-from-upload-with-terraformignore). +For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore). diff --git a/website/docs/cli/config/index.html.md b/website/docs/cli/config/index.mdx similarity index 68% rename from website/docs/cli/config/index.html.md rename to website/docs/cli/config/index.mdx index afe00e8f2..188e7ad61 100644 --- a/website/docs/cli/config/index.html.md +++ b/website/docs/cli/config/index.mdx @@ -1,7 +1,8 @@ --- -layout: "docs" -page_title: "CLI Configuration - Terraform CLI" -description: "Find documentation about the CLI config file and customizing Terraform environment variables." +page_title: CLI Configuration - Terraform CLI +description: >- + Find documentation about the CLI config file and customizing Terraform + environment variables. --- # CLI Configuration @@ -15,9 +16,9 @@ most of the global settings relate to advanced or automated workflows, or unusual environmental conditions like running Terraform on an airgapped instance. -- The [CLI config file](/docs/cli/config/config-file.html) configures provider +- The [CLI config file](/cli/config/config-file) configures provider installation and security features. -- Several [environment variables](/docs/cli/config/environment-variables.html) can +- Several [environment variables](/cli/config/environment-variables) can configure Terraform's inputs and outputs; this includes some alternate ways to provide information that is usually passed on the command line or read from the state of the shell. diff --git a/website/docs/cli/import/importability.html.md b/website/docs/cli/import/importability.mdx similarity index 82% rename from website/docs/cli/import/importability.html.md rename to website/docs/cli/import/importability.mdx index 79d78d90a..88a200a4e 100644 --- a/website/docs/cli/import/importability.html.md +++ b/website/docs/cli/import/importability.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Import: Resource Importability" -sidebar_current: "docs-import-importability" +page_title: 'Import: Resource Importability' description: |- Each resource in Terraform must implement some basic logic to become importable. As a result, not all Terraform resources are currently importable. @@ -21,4 +19,4 @@ you're interested in contributing that functionality, the Terraform team would be grateful. To make a resource importable, please see -[Extending Terraform: Resources — Import](/docs/extend/resources/import.html). +[Extending Terraform: Resources — Import](/plugin/sdkv2/resources/import). diff --git a/website/docs/cli/import/index.html.md b/website/docs/cli/import/index.mdx similarity index 81% rename from website/docs/cli/import/index.html.md rename to website/docs/cli/import/index.mdx index b06c668fc..3ff341749 100644 --- a/website/docs/cli/import/index.html.md +++ b/website/docs/cli/import/index.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Import" -sidebar_current: "docs-import" -description: "Terraform can import and manage existing infrastructure. This can help you transition your infrastructure to Terraform." +page_title: Import +description: >- + Terraform can import and manage existing infrastructure. This can help you + transition your infrastructure to Terraform. --- # Import @@ -23,12 +23,12 @@ itself having created all objects. If you import existing objects into Terraform be careful to import each remote object to only one Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. For more information on this assumption, see -[the State section](/docs/language/state/index.html). +[the State section](/language/state). ## Currently State Only The current implementation of Terraform import can only import resources -into the [state](/docs/language/state/index.html). It does not generate configuration. A future +into the [state](/language/state). It does not generate configuration. A future version of Terraform will also generate configuration. Because of this, prior to running `terraform import` it is necessary to write @@ -41,7 +41,7 @@ importing existing resources. ## Remote Backends When using Terraform import on the command line with a [remote -backend](/docs/language/settings/backends/remote.html), such as Terraform Cloud, the import +backend](/language/settings/backends/remote), such as Terraform Cloud, the import command runs locally, unlike commands such as apply, which run inside your Terraform Cloud environment. Because of this, the import command will not have access to information from the remote backend, such as workspace variables. diff --git a/website/docs/cli/import/usage.html.md b/website/docs/cli/import/usage.mdx similarity index 90% rename from website/docs/cli/import/usage.html.md rename to website/docs/cli/import/usage.mdx index 4fdc5452d..e5d448990 100644 --- a/website/docs/cli/import/usage.html.md +++ b/website/docs/cli/import/usage.mdx @@ -1,9 +1,6 @@ --- -layout: "docs" -page_title: "Import: Usage" -sidebar_current: "docs-import-usage" -description: |- - The `terraform import` command is used to import existing infrastructure. +page_title: 'Import: Usage' +description: The `terraform import` command is used to import existing infrastructure. --- # Import Usage @@ -23,7 +20,7 @@ itself having created all objects. If you import existing objects into Terraform be careful to import each remote object to only one Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. For more information on this assumption, see -[the State section](/docs/language/state/index.html). +[the State section](/language/state). To import a resource, first write a resource block for it in your configuration, establishing the name by which it will be known to Terraform: @@ -57,7 +54,7 @@ Terraform state. It is also possible to import to resources in child modules, using their paths, and to single instances of a resource with `count` or `for_each` set. See -[_Resource Addressing_](/docs/cli/state/resource-addressing.html) for more +[_Resource Addressing_](/cli/state/resource-addressing) for more details on how to specify a target resource. The syntax of the given ID is dependent on the resource type being imported. @@ -83,4 +80,4 @@ a `resource` block in configuration for each secondary resource. If this is not done, Terraform will plan to destroy the imported objects on the next run. If you want to rename or otherwise move the imported resources, the -[state management commands](/docs/cli/commands/state/index.html) can be used. +[state management commands](/cli/commands/state) can be used. diff --git a/website/docs/cli/index.html.md b/website/docs/cli/index.mdx similarity index 67% rename from website/docs/cli/index.html.md rename to website/docs/cli/index.mdx index f52fb1bc5..e59efd750 100644 --- a/website/docs/cli/index.html.md +++ b/website/docs/cli/index.mdx @@ -1,8 +1,8 @@ --- -layout: "docs" -page_title: "Terraform CLI Documentation" -sidebar_current: "docs-home" -description: "Learn how to use Terraform's CLI-based workflows. You can use the CLI alone or in conjunction with Terraform Cloud or Terraform Enterprise." +page_title: Terraform CLI Documentation +description: >- + Learn how to use Terraform's CLI-based workflows. You can use the CLI alone or + in conjunction with Terraform Cloud or Terraform Enterprise. --- # Terraform CLI Documentation @@ -16,4 +16,4 @@ Cloud or Terraform Enterprise. Notably, this documentation does not cover the syntax and usage of the Terraform language. For that, see the -[Terraform Language Documentation](/docs/language/index.html). +[Terraform Language Documentation](/language). diff --git a/website/docs/cli/init/index.html.md b/website/docs/cli/init/index.mdx similarity index 85% rename from website/docs/cli/init/index.html.md rename to website/docs/cli/init/index.mdx index 1fc581e3f..133527e97 100644 --- a/website/docs/cli/init/index.html.md +++ b/website/docs/cli/init/index.mdx @@ -1,14 +1,16 @@ --- -layout: "docs" -page_title: "Initializing Working Directories - Terraform CLI" -description: "Working directories contain configurations, settings, cached plugins and modules, and state data. Learn how to initialize and manage working directories." +page_title: Initializing Working Directories - Terraform CLI +description: >- + Working directories contain configurations, settings, cached plugins and + modules, and state data. Learn how to initialize and manage working + directories. --- # Initializing Working Directories Terraform expects to be invoked from a working directory that contains configuration files written in -[the Terraform language](/docs/language/index.html). Terraform uses +[the Terraform language](/language). Terraform uses configuration content from this directory, and also uses the directory to store settings, cached plugins and modules, and sometimes state data. @@ -23,7 +25,7 @@ A Terraform working directory typically contains: configuration is expected to change over time. - A hidden `.terraform` directory, which Terraform uses to manage cached provider plugins and modules, record which - [workspace](/docs/cli/workspaces/index.html) is currently active, and + [workspace](/cli/workspaces) is currently active, and record the last known backend configuration in case it needs to migrate state on the next run. This directory is automatically managed by Terraform, and is created during initialization. @@ -48,7 +50,7 @@ plugins, and downloading modules. Under some conditions (usually when changing from one backend to another), it might ask the user for guidance or confirmation. -For details, see [the `terraform init` command](/docs/cli/commands/init.html). +For details, see [the `terraform init` command](/cli/commands/init). ## Reinitialization diff --git a/website/docs/cli/inspect/index.html.md b/website/docs/cli/inspect/index.mdx similarity index 63% rename from website/docs/cli/inspect/index.html.md rename to website/docs/cli/inspect/index.mdx index 3fac82ed5..2337764de 100644 --- a/website/docs/cli/inspect/index.html.md +++ b/website/docs/cli/inspect/index.mdx @@ -1,7 +1,8 @@ --- -layout: "docs" -page_title: "Inspecting Infrastructure - Terraform CLI" -description: "Learn commands to inspect dependency information, outputs, etc. Use them for integration or to understand your infrastructure." +page_title: Inspecting Infrastructure - Terraform CLI +description: >- + Learn commands to inspect dependency information, outputs, etc. Use them for + integration or to understand your infrastructure. --- # Inspecting Infrastructure @@ -16,19 +17,19 @@ Terraform CLI includes some commands for inspecting or transforming this data. You can use these to integrate other tools with Terraform's infrastructure data, or just to gain a deeper or more holistic understanding of your infrastructure. -- [The `terraform graph` command](/docs/cli/commands/graph.html) creates a visual +- [The `terraform graph` command](/cli/commands/graph) creates a visual representation of a configuration or a set of planned changes. -- [The `terraform output` command](/docs/cli/commands/output.html) can get the - values for the top-level [output values](/docs/language/values/outputs.html) of +- [The `terraform output` command](/cli/commands/output) can get the + values for the top-level [output values](/language/values/outputs) of a configuration, which are often helpful when making use of the infrastructure Terraform has provisioned. -- [The `terraform show` command](/docs/cli/commands/show.html) can generate +- [The `terraform show` command](/cli/commands/show) can generate human-readable versions of a state file or plan file, or generate machine-readable versions that can be integrated with other tools. -- [The `terraform state list` command](/docs/cli/commands/state/list.html) can list +- [The `terraform state list` command](/cli/commands/state/list) can list the resources being managed by the current working directory and workspace, providing a complete or filtered list. -- [The `terraform state show` command](/docs/cli/commands/state/show.html) can print +- [The `terraform state show` command](/cli/commands/state/show) can print all of the attributes of a given resource being managed by the current working directory and workspace, including generated read-only attributes like the unique ID assigned by the cloud provider. diff --git a/website/docs/cli/install/apt.html.md b/website/docs/cli/install/apt.mdx similarity index 93% rename from website/docs/cli/install/apt.html.md rename to website/docs/cli/install/apt.mdx index 88cf58fb2..fff3cdf2f 100644 --- a/website/docs/cli/install/apt.html.md +++ b/website/docs/cli/install/apt.mdx @@ -1,9 +1,8 @@ --- -layout: "downloads" -page_title: "APT Packages for Debian and Ubuntu" -sidebar_current: "docs-cli-install-apt" -description: |- - The HashiCorp APT repositories contain distribution-specific Terraform packages for both Debian and Ubuntu systems. +page_title: APT Packages for Debian and Ubuntu +description: >- + The HashiCorp APT repositories contain distribution-specific Terraform + packages for both Debian and Ubuntu systems. --- # APT Packages for Debian and Ubuntu @@ -16,7 +15,7 @@ Debian and Ubuntu systems, which allow you to install Terraform using the `apt install` command or any other APT frontend. If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you -might prefer to [install Terraform from our Yum repositories](yum.html). +might prefer to [install Terraform from our Yum repositories](/cli/install/yum). -> **Note:** The APT repositories discussed on this page are generic HashiCorp repositories that contain packages for a variety of different HashiCorp @@ -64,7 +63,7 @@ architecture, which is also sometimes known as `x86_64`. There are no official packages available for other architectures, such as `arm64`. If you wish to use Terraform on a non-`amd64` system, -[download a normal release `.zip` file](/downloads.html) instead. +[download a normal release `.zip` file](/downloads) instead. ## Supported Debian and Ubuntu Releases diff --git a/website/docs/cli/install/yum.html.md b/website/docs/cli/install/yum.mdx similarity index 91% rename from website/docs/cli/install/yum.html.md rename to website/docs/cli/install/yum.mdx index 45e88e0eb..accc2d3f3 100644 --- a/website/docs/cli/install/yum.html.md +++ b/website/docs/cli/install/yum.mdx @@ -1,9 +1,8 @@ --- -layout: "downloads" -page_title: "Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux" -sidebar_current: "docs-cli-install-yum" -description: |- - The HashiCorp Yum repositories contain distribution-specific Terraform packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems. +page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux' +description: >- + The HashiCorp Yum repositories contain distribution-specific Terraform + packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems. --- # Yum/DNF Packages for RHEL, CentOS, and Fedora @@ -16,7 +15,7 @@ RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to install Terraform using the `yum install` or `dnf install` commands. If you are instead using Debian or Ubuntu, you -might prefer to [install Terraform from our APT repositories](apt.html). +might prefer to [install Terraform from our APT repositories](/cli/install/apt). -> **Note:** The Yum repositories discussed on this page are generic HashiCorp repositories that contain packages for a variety of different HashiCorp @@ -64,7 +63,7 @@ architecture, which is also sometimes known as `amd64`. There are no official packages available for other architectures, such as `aarch64`. If you wish to use Terraform on a non-`x86_64` system, -[download a normal release `.zip` file](/downloads.html) instead. +[download a normal release `.zip` file](/downloads) instead. ## Supported Distribution Releases diff --git a/website/docs/cli/plugins/index.html.md b/website/docs/cli/plugins/index.mdx similarity index 65% rename from website/docs/cli/plugins/index.html.md rename to website/docs/cli/plugins/index.mdx index 95edb225e..22965ea07 100644 --- a/website/docs/cli/plugins/index.html.md +++ b/website/docs/cli/plugins/index.mdx @@ -1,14 +1,15 @@ --- -layout: "docs" -page_title: "Managing Plugins - Terraform CLI" -description: "Commands to install, configure, and show information about providers. Also commands to reduce install effort in air-gapped environments." +page_title: Managing Plugins - Terraform CLI +description: >- + Commands to install, configure, and show information about providers. Also + commands to reduce install effort in air-gapped environments. --- # Managing Plugins Terraform relies on plugins called "providers" in order to manage various types of resources. (For more information about providers, see -[Providers](/docs/language/providers/index.html) in the Terraform +[Providers](/language/providers) in the Terraform language docs.) -> **Note:** Providers are currently the only plugin type most Terraform users @@ -16,8 +17,8 @@ will interact with. Terraform also supports third-party provisioner plugins, but we discourage their use. Terraform downloads and/or installs any providers -[required](/docs/language/providers/requirements.html) by a configuration -when [initializing](/docs/cli/init/index.html) a working directory. By default, +[required](/language/providers/requirements) by a configuration +when [initializing](/cli/init) a working directory. By default, this works without any additional interaction but requires network access to download providers from their source registry. @@ -31,29 +32,29 @@ environments. Terraform's configuration file includes options for caching downloaded plugins, or explicitly specifying a local or HTTPS mirror to install plugins from. For -more information, see [CLI Config File](/docs/cli/config/config-file.html). +more information, see [CLI Config File](/cli/config/config-file). ## Getting Plugin Information -Use the [`terraform providers`](/docs/cli/commands/providers.html) command to get information +Use the [`terraform providers`](/cli/commands/providers) command to get information about the providers required by the current working directory's configuration. -Use the [`terraform version`](/docs/cli/commands/version.html) command (or +Use the [`terraform version`](/cli/commands/version) command (or `terraform -version`) to show the specific provider versions installed for the current working directory. -Use the [`terraform providers schema`](/docs/cli/commands/providers/schema.html) command to +Use the [`terraform providers schema`](/cli/commands/providers/schema) command to get machine-readable information about the resources and configuration options offered by each provider. ## Managing Plugin Installation -Use the [`terraform providers mirror`](/docs/cli/commands/providers/mirror.html) command to +Use the [`terraform providers mirror`](/cli/commands/providers/mirror) command to download local copies of every provider required by the current working directory's configuration. This directory will use the nested directory layout that Terraform expects when installing plugins from a local source, so you can transfer it directly to an airgapped system that runs Terraform. -Use the [`terraform providers lock`](/docs/cli/commands/providers/lock.html) command +Use the [`terraform providers lock`](/cli/commands/providers/lock) command to update the lock file that Terraform uses to ensure predictable runs when using ambiguous provider version constraints. diff --git a/website/docs/cli/plugins/signing.html.md b/website/docs/cli/plugins/signing.mdx similarity index 70% rename from website/docs/cli/plugins/signing.html.md rename to website/docs/cli/plugins/signing.mdx index 9c82157d3..cdcd546d6 100644 --- a/website/docs/cli/plugins/signing.html.md +++ b/website/docs/cli/plugins/signing.mdx @@ -1,7 +1,8 @@ --- -layout: "docs" -page_title: "Plugin Signing" -description: "Learn about the types of signatures providers can have on the Terraform Registry." +page_title: Plugin Signing +description: >- + Learn about the types of signatures providers can have on the Terraform + Registry. --- @@ -14,11 +15,11 @@ Terraform providers installed from the Registry are cryptographically signed, an * **Signed by HashiCorp** - are built, signed, and supported by HashiCorp. * **Signed by 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. + 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 -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. + 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. diff --git a/website/docs/cli/run/index.html.md b/website/docs/cli/run/index.mdx similarity index 82% rename from website/docs/cli/run/index.html.md rename to website/docs/cli/run/index.mdx index 0d0770a34..0ce523820 100644 --- a/website/docs/cli/run/index.html.md +++ b/website/docs/cli/run/index.mdx @@ -1,14 +1,13 @@ --- -layout: "docs" -page_title: "Provisioning Infrastructure - Terraform CLI" -description: "Learn about commands for core provisioning tasks: plan, apply, and destroy." +page_title: Provisioning Infrastructure - Terraform CLI +description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.' --- # Provisioning Infrastructure with Terraform Terraform's primary function is to create, modify, and destroy infrastructure resources to match the desired state described in a -[Terraform configuration](/docs/language/index.html). +[Terraform configuration](/language). When people refer to "running Terraform," they generally mean performing these provisioning actions in order to affect real infrastructure objects. The @@ -17,8 +16,8 @@ actions, but these basic provisioning tasks are the core of Terraform. Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and `destroy`. All of these commands require an -[initialized](/docs/cli/init/index.html) working directory, and all of them act -only upon the currently selected [workspace](/docs/cli/workspaces/index.html). +[initialized](/cli/init) working directory, and all of them act +only upon the currently selected [workspace](/cli/workspaces). ## Planning @@ -39,7 +38,7 @@ resulting actions are as expected. However, `terraform plan` can also save its plan as a runnable artifact, which `terraform apply` can use to carry out those exact changes. -For details, see [the `terraform plan` command](/docs/cli/commands/plan.html). +For details, see [the `terraform plan` command](/cli/commands/plan). ## Applying @@ -55,7 +54,7 @@ running a new plan. You can use this to reliably perform an exact set of pre-approved changes, even if the configuration or the state of the real infrastructure has changed in the minutes since the original plan was created. -For details, see [the `terraform apply` command](/docs/cli/commands/apply.html). +For details, see [the `terraform apply` command](/cli/commands/apply). ## Destroying @@ -69,4 +68,4 @@ and then running an apply, except that it doesn't require editing the configuration. This is more convenient if you intend to provision similar resources at a later date. -For details, see [the `terraform destroy` command](/docs/cli/commands/destroy.html). +For details, see [the `terraform destroy` command](/cli/commands/destroy). diff --git a/website/docs/cli/state/index.html.md b/website/docs/cli/state/index.mdx similarity index 66% rename from website/docs/cli/state/index.html.md rename to website/docs/cli/state/index.mdx index 7f12fea4f..9db8d9252 100644 --- a/website/docs/cli/state/index.html.md +++ b/website/docs/cli/state/index.mdx @@ -1,14 +1,15 @@ --- -layout: "docs" -page_title: "Manipulating State - Terraform CLI" -description: "State data tracks which real-world object corresponds to each resource. Inspect state, move or import resources, and more." +page_title: Manipulating State - Terraform CLI +description: >- + State data tracks which real-world object corresponds to each resource. + Inspect state, move or import resources, and more. --- # Manipulating Terraform State > **Hands-on:** Try the [Manage Resources in Terraform State](https://learn.hashicorp.com/tutorials/terraform/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. -Terraform uses [state data](/docs/language/state/index.html) to remember which +Terraform uses [state data](/language/state) to remember which real-world object corresponds to each resource in the configuration; this allows it to modify an existing object when its resource declaration changes. @@ -20,12 +21,12 @@ infrastructure. Terraform CLI supports several workflows for interacting with state: -- [Inspecting State](/docs/cli/state/inspect.html) -- [Forcing Re-creation (Tainting)](/docs/cli/state/taint.html) -- [Moving Resources](/docs/cli/state/move.html) +- [Inspecting State](/cli/state/inspect) +- [Forcing Re-creation (Tainting)](/cli/state/taint) +- [Moving Resources](/cli/state/move) - Importing Pre-existing Resources (documented in the - [Importing Infrastructure](/docs/cli/import/index.html) section) -- [Disaster Recovery](/docs/cli/state/recover.html) + [Importing Infrastructure](/cli/import) section) +- [Disaster Recovery](/cli/state/recover) ~> **Important:** Modifying state data outside a normal plan or apply can cause Terraform to lose track of managed resources, which might waste money, annoy diff --git a/website/docs/cli/state/inspect.html.md b/website/docs/cli/state/inspect.mdx similarity index 58% rename from website/docs/cli/state/inspect.html.md rename to website/docs/cli/state/inspect.mdx index 382cd37a2..54767bb83 100644 --- a/website/docs/cli/state/inspect.html.md +++ b/website/docs/cli/state/inspect.mdx @@ -1,7 +1,6 @@ --- -layout: "docs" -page_title: "Inspecting State - Terraform CLI" -description: "Commands that allow you to read and update state." +page_title: Inspecting State - Terraform CLI +description: Commands that allow you to read and update state. --- # Inspecting State @@ -9,14 +8,14 @@ description: "Commands that allow you to read and update state." Terraform includes some commands for reading and updating state without taking any other actions. -- [The `terraform state list` command](/docs/cli/commands/state/list.html) +- [The `terraform state list` command](/cli/commands/state/list) shows the resource addresses for every resource Terraform knows about in a configuration, optionally filtered by partial resource address. -- [The `terraform state show` command](/docs/cli/commands/state/show.html) +- [The `terraform state show` command](/cli/commands/state/show) displays detailed state data about one resource. -- [The `terraform refresh` command](/docs/cli/commands/refresh.html) updates +- [The `terraform refresh` command](/cli/commands/refresh) updates state data to match the real-world condition of the managed resources. This is done automatically during plans and applies, but not when interacting with state directly. diff --git a/website/docs/cli/state/move.html.md b/website/docs/cli/state/move.mdx similarity index 64% rename from website/docs/cli/state/move.html.md rename to website/docs/cli/state/move.mdx index c507aa0ef..8b0f9cdae 100644 --- a/website/docs/cli/state/move.html.md +++ b/website/docs/cli/state/move.mdx @@ -1,13 +1,14 @@ --- -layout: "docs" -page_title: "Moving Resources - Terraform CLI" -description: "Commands that allow you to manage the way that resources are tracked in state. They are helpful when you move or change resources." +page_title: Moving Resources - Terraform CLI +description: >- + Commands that allow you to manage the way that resources are tracked in state. + They are helpful when you move or change resources. --- # Moving Resources Terraform's state associates each real-world object with a configured resource -at a specific [resource address](/docs/cli/state/resource-addressing.html). This +at a specific [resource address](/cli/state/resource-addressing). This is seamless when changing a resource's attributes, but Terraform will lose track of a resource if you change its name, move it to a different module, or change its provider. @@ -20,19 +21,19 @@ In cases where it's important to preserve an existing infrastructure object, you can explicitly tell Terraform to associate it with a different configured resource. -- [The `terraform state mv` command](/docs/cli/commands/state/mv.html) changes +- [The `terraform state mv` command](/cli/commands/state/mv) changes which resource address in your configuration is associated with a particular real-world object. Use this to preserve an object when renaming a resource, or when moving a resource into or out of a child module. - > **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn. + > **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn. -- [The `terraform state rm` command](/docs/cli/commands/state/rm.html) tells +- [The `terraform state rm` command](/cli/commands/state/rm) tells Terraform to stop managing a resource as part of the current working directory and workspace, _without_ destroying the corresponding real-world object. (You can later use `terraform import` to start managing that resource in a different workspace or a different Terraform configuration.) -- [The `terraform state replace-provider` command](/docs/cli/commands/state/replace-provider.html) +- [The `terraform state replace-provider` command](/cli/commands/state/replace-provider) transfers existing resources to a new provider without requiring them to be re-created. diff --git a/website/docs/cli/state/recover.html.md b/website/docs/cli/state/recover.mdx similarity index 65% rename from website/docs/cli/state/recover.html.md rename to website/docs/cli/state/recover.mdx index 29e289c42..f3b124cb2 100644 --- a/website/docs/cli/state/recover.html.md +++ b/website/docs/cli/state/recover.mdx @@ -1,7 +1,8 @@ --- -layout: "docs" -page_title: "Recovering from State Disasters - Terraform CLI" -descriptin: "Commands that allow you to restore state backups and override Terraform state protections." +page_title: Recovering from State Disasters - Terraform CLI +descriptin: >- + Commands that allow you to restore state backups and override Terraform state + protections. --- # Recovering from State Disasters @@ -10,7 +11,7 @@ If something has gone horribly wrong (possibly due to accidents when performing other state manipulation actions), you might need to take drastic actions with your state data. -- [The `terraform force-unlock` command](/docs/cli/commands/force-unlock.html) can +- [The `terraform force-unlock` command](/cli/commands/force-unlock) can override the protections Terraform uses to prevent two processes from 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 @@ -18,8 +19,7 @@ your state data. state backend. Do not run this until you are completely certain what happened to the process that caused the lock to get stuck. -- [The `terraform state pull` command](/docs/cli/commands/state/pull.html) and - [the `terraform state push` command](/docs/cli/commands/state/push.html) can +- [The `terraform state pull` command](/cli/commands/state/pull) and + [the `terraform state push` command](/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. - diff --git a/website/docs/cli/state/resource-addressing.html.md b/website/docs/cli/state/resource-addressing.mdx similarity index 69% rename from website/docs/cli/state/resource-addressing.html.md rename to website/docs/cli/state/resource-addressing.mdx index 72b987a83..07f3039c0 100644 --- a/website/docs/cli/state/resource-addressing.html.md +++ b/website/docs/cli/state/resource-addressing.mdx @@ -1,7 +1,5 @@ --- -layout: "docs" -page_title: "Internals: Resource Address" -sidebar_current: "docs-internals-resource-addressing" +page_title: 'Internals: Resource Address' description: |- A resource address is a string that identifies zero or more resource instances in your overall configuration. @@ -32,12 +30,12 @@ A module path addresses a module within the tree of modules. It takes the form: module.module_name[module index] ``` - * `module` - Module keyword indicating a child module (non-root). Multiple `module` - keywords in a path indicate nesting. - * `module_name` - User-defined name of the module. - * `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources) - to select an instance from a module call that has multiple instances, - surrounded by square bracket characters (`[` and `]`). +- `module` - Module keyword indicating a child module (non-root). Multiple `module` + keywords in a path indicate nesting. +- `module_name` - User-defined name of the module. +- `[module index]` - (Optional) [Index](#index-values-for-modules-and-resources) + to select an instance from a module call that has multiple instances, + surrounded by square bracket characters (`[` and `]`). An address without a resource spec, i.e. `module.foo` applies to every resource within the module if a single module, or all instances of a module if a module has multiple instances. @@ -64,11 +62,11 @@ It has the following syntax: resource_type.resource_name[instance index] ``` - * `resource_type` - Type of the resource being addressed. - * `resource_name` - User-defined name of the resource. - * `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources) - to select an instance from a resource that has multiple instances, - surrounded by square bracket characters (`[` and `]`). +- `resource_type` - Type of the resource being addressed. +- `resource_name` - User-defined name of the resource. +- `[instance index]` - (Optional) [Index](#index-values-for-modules-and-resources) + to select an instance from a resource that has multiple instances, + surrounded by square bracket characters (`[` and `]`). -> In Terraform v0.12 and later, a resource spec without a module path prefix matches only resources in the root module. In earlier versions, a resource spec @@ -79,12 +77,12 @@ in any descendent module. The following specifications apply to index values on modules and resources with multiple instances: - * `[N]` where `N` is a `0`-based numerical index into a resource with multiple - instances specified by the `count` meta-argument. Omitting an index when - addressing a resource where `count > 1` means that the address references - all instances. - * `["INDEX"]` where `INDEX` is a alphanumerical key index into a resource with - multiple instances specified by the `for_each` meta-argument. +- `[N]` where `N` is a `0`-based numerical index into a resource with multiple + instances specified by the `count` meta-argument. Omitting an index when + addressing a resource where `count > 1` means that the address references + all instances. +- `["INDEX"]` where `INDEX` is a alphanumerical key index into a resource with + multiple instances specified by the `for_each` meta-argument. ## Examples diff --git a/website/docs/cli/state/taint.html.md b/website/docs/cli/state/taint.mdx similarity index 68% rename from website/docs/cli/state/taint.html.md rename to website/docs/cli/state/taint.mdx index cea128144..dbe67f906 100644 --- a/website/docs/cli/state/taint.html.md +++ b/website/docs/cli/state/taint.mdx @@ -1,7 +1,6 @@ --- -layout: "docs" -page_title: "Forcing Re-creation of Resources (Tainting) - Terraform CLI" -description: "Commands that allow you to destroy and re-create resources manually." +page_title: Forcing Re-creation of Resources (Tainting) - Terraform CLI +description: Commands that allow you to destroy and re-create resources manually. --- # Forcing Re-creation of Resources (Tainting) @@ -17,10 +16,10 @@ happen during creation; for example, a virtual machine that configures itself with `cloud-init` on startup might no longer meet your needs if the cloud-init configuration changes. -- [The `terraform taint` command](/docs/cli/commands/taint.html) tells Terraform to +- [The `terraform taint` command](/cli/commands/taint) tells Terraform to destroy and re-create a particular resource during the next apply, regardless of whether its resource arguments would normally require that. -- [The `terraform untaint` command](/docs/cli/commands/untaint.html) undoes a +- [The `terraform untaint` command](/cli/commands/untaint) undoes a previous taint, or can preserve a resource that was automatically tainted due - to failed [provisioners](/docs/language/resources/provisioners/syntax.html). + to failed [provisioners](/language/resources/provisioners/syntax). diff --git a/website/docs/cli/workspaces/index.html.md b/website/docs/cli/workspaces/index.mdx similarity index 65% rename from website/docs/cli/workspaces/index.html.md rename to website/docs/cli/workspaces/index.mdx index 39dd00f5e..7a6b11f9e 100644 --- a/website/docs/cli/workspaces/index.html.md +++ b/website/docs/cli/workspaces/index.mdx @@ -1,28 +1,29 @@ --- -layout: "docs" -page_title: "Managing Workspaces - Terraform CLI" -description: "Commands to list, select, create, and output workspaces. Workspaces help manage different groups of resources with one configuration." +page_title: Managing Workspaces - Terraform CLI +description: >- + Commands to list, select, create, and output workspaces. Workspaces help + manage different groups of resources with one configuration. --- # Managing Workspaces In Terraform CLI, _workspaces_ are separate instances of -[state data](/docs/language/state/index.html) that can be used from the same working +[state data](/language/state) that can be used from the same working directory. You can use workspaces to manage multiple non-overlapping groups of resources with the same configuration. -- Every [initialized working directory](/docs/cli/init/index.html) has at least +- Every [initialized working directory](/cli/init) has at least one workspace. (If you haven't created other workspaces, it is a workspace named `default`.) - For a given working directory, only one workspace can be _selected_ at a time. -- Most Terraform commands (including [provisioning](/docs/cli/run/index.html) - and [state manipulation](/docs/cli/state/index.html) commands) only interact +- Most Terraform commands (including [provisioning](/cli/run) + and [state manipulation](/cli/state) commands) only interact with the currently selected workspace. -- Use [the `terraform workspace select` command](/docs/cli/commands/workspace/select.html) +- Use [the `terraform workspace select` command](/cli/commands/workspace/select) to change the currently selected workspace. -- Use the [`terraform workspace list`](/docs/cli/commands/workspace/list.html), - [`terraform workspace new`](/docs/cli/commands/workspace/new.html), and - [`terraform workspace delete`](/docs/cli/commands/workspace/delete.html) commands +- Use the [`terraform workspace list`](/cli/commands/workspace/list), + [`terraform workspace new`](/cli/commands/workspace/new), and + [`terraform workspace delete`](/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory. -> **Note:** Terraform Cloud and Terraform CLI both have features called @@ -35,19 +36,19 @@ Since most of the resources you can manage with Terraform don't include a unique name as part of their configuration, it's common to use the same Terraform configuration to provision multiple groups of similar resources. -Terraform relies on [state](/docs/language/state/index.html) to associate resources with +Terraform relies on [state](/language/state) to associate resources with real-world objects, so if you run the same configuration multiple times with completely separate state data, Terraform can manage many non-overlapping groups of resources. In some cases you'll want to change -[variable values](/docs/language/values/variables.html) for these different +[variable values](/language/values/variables) for these different resource collections (like when specifying differences between staging and production deployments), and in other cases you might just want many instances of a particular infrastructure pattern. The simplest way to maintain multiple instances of a configuration with completely separate state data is to use multiple -[working directories](/docs/cli/init/index.html) (with different -[backend](/docs/language/settings/backends/configuration.html) configurations per directory, if you +[working directories](/cli/init) (with different +[backend](/language/settings/backends/configuration) configurations per directory, if you aren't using the default `local` backend). However, this isn't always the most _convenient_ way to handle separate states. @@ -69,9 +70,9 @@ workspace has its own Terraform configuration, set of variable values, state data, run history, and settings. These two kinds of workspaces are different, but related. When [using Terraform -CLI as a frontend for Terraform Cloud](/docs/cli/cloud/index.html), you can associate the current working +CLI as a frontend for Terraform Cloud](/cli/cloud), you can associate the current working directory with one or more remote workspaces. If you associate the directory with multiple workspaces (using workspace tags), you can use the `terraform workspace` commands to select which remote workspace to use. -Refer to [CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud. +Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud. diff --git a/website/docs/configuration-0-11/interpolation.html.md b/website/docs/configuration-0-11/interpolation.html.md deleted file mode 100644 index 9ec65d8aa..000000000 --- a/website/docs/configuration-0-11/interpolation.html.md +++ /dev/null @@ -1,570 +0,0 @@ ---- -layout: "language" -page_title: "Interpolation Syntax - 0.11 Configuration Language" -sidebar_current: "docs-conf-old-interpolation" -description: |- - Embedded within strings in Terraform, whether you're using the Terraform syntax or JSON syntax, you can interpolate other values into strings. These interpolations are wrapped in `${}`, such as `${var.foo}`. ---- - -# Interpolation Syntax - --> **Note:** This page is about Terraform 0.11 and earlier. For Terraform 0.12 -and later, see -[Configuration Language: Expressions](/docs/language/expressions/index.html) and -[Configuration Language: Functions](/docs/language/functions/index.html). - -Embedded within strings in Terraform, whether you're using the -Terraform syntax or JSON syntax, you can interpolate other values. These -interpolations are wrapped in `${}`, such as `${var.foo}`. - -The interpolation syntax is powerful and allows you to reference -variables, attributes of resources, call functions, etc. - -You can perform [simple math](#math) in interpolations, allowing -you to write expressions such as `${count.index + 1}`. And you can -also use [conditionals](#conditionals) to determine a value based -on some logic. - -You can escape interpolation with double dollar signs: `$${foo}` -will be rendered as a literal `${foo}`. - -## Available Variables - -There are a variety of available variable references you can use. - -#### User string variables - -Use the `var.` prefix followed by the variable name. For example, -`${var.foo}` will interpolate the `foo` variable value. - -#### User map variables - -The syntax is `var.[""]`. For example, `${var.amis["us-east-1"]}` -would get the value of the `us-east-1` key within the `amis` map -variable. - -#### User list variables - -The syntax is `"${var.}"`. For example, `"${var.subnets}"` -would get the value of the `subnets` list, as a list. You can also -return list elements by index: `${var.subnets[idx]}`. - -#### Attributes of your own resource - -The syntax is `self.`. For example `${self.private_ip}` -will interpolate that resource's private IP address. - --> **Note**: The `self.` syntax is only allowed and valid within -provisioners. - -#### Attributes of other resources - -The syntax is `..`. For example, -`${aws_instance.web.id}` will interpolate the ID attribute from the -`aws_instance` resource named `web`. If the resource has a `count` -attribute set, you can access individual attributes with a zero-based -index, such as `${aws_instance.web.0.id}`. You can also use the splat -syntax to get a list of all the attributes: `${aws_instance.web.*.id}`. - -#### Attributes of a data source - -The syntax is `data...`. For example. `${data.aws_ami.ubuntu.id}` will interpolate the `id` attribute from the `aws_ami` [data source](./data-sources.html) named `ubuntu`. If the data source has a `count` -attribute set, you can access individual attributes with a zero-based -index, such as `${data.aws_subnet.example.0.cidr_block}`. You can also use the splat -syntax to get a list of all the attributes: `${data.aws_subnet.example.*.cidr_block}`. - -#### Outputs from a module - -The syntax is `module..`. For example `${module.foo.bar}` will -interpolate the `bar` output from the `foo` -[module](/docs/language/modules/develop/index.html). - -#### Count information - -The syntax is `count.index`. For example, `${count.index}` will -interpolate the current index in a multi-count resource. For more -information on `count`, see the [resource configuration -page](./resources.html). - -#### Path information - -The syntax is `path.`. TYPE can be `cwd`, `module`, or `root`. -`cwd` will interpolate the current working directory. `module` will -interpolate the path to the current module. `root` will interpolate the -path of the root module. In general, you probably want the -`path.module` variable. - -#### Terraform meta information - -The syntax is `terraform.`. This variable type contains metadata about -the currently executing Terraform run. FIELD can currently only be `env` to -reference the currently active workspace. - -## Conditionals - -Interpolations may contain conditionals to branch on the final value. - -```hcl -resource "aws_instance" "web" { - subnet = "${var.env == "production" ? var.prod_subnet : var.dev_subnet}" -} -``` - -The conditional syntax is the well-known ternary operation: - -```text -CONDITION ? TRUEVAL : FALSEVAL -``` - -The condition can be any valid interpolation syntax, such as variable -access, a function call, or even another conditional. The true and false -value can also be any valid interpolation syntax. The returned types by -the true and false side must be the same. - -The supported operators are: - - * Equality: `==` and `!=` - * Numerical comparison: `>`, `<`, `>=`, `<=` - * Boolean logic: `&&`, `||`, unary `!` - -A common use case for conditionals is to enable/disable a resource by -conditionally setting the count: - -```hcl -resource "aws_instance" "vpn" { - count = "${var.something ? 1 : 0}" -} -``` - -In the example above, the "vpn" resource will only be included if -"var.something" evaluates to true. Otherwise, the VPN resource will -not be created at all. - -## Built-in Functions - -Terraform ships with built-in functions. Functions are called with the -syntax `name(arg, arg2, ...)`. For example, to read a file: -`${file("path.txt")}`. - -~> **Note**: Proper escaping is required for JSON field values containing quotes -(`"`) such as `environment` values. If directly setting the JSON, they should be -escaped as `\"` in the JSON, e.g. `"value": "I \"love\" escaped quotes"`. If -using a Terraform variable value, they should be escaped as `\\\"` in the -variable, e.g. `value = "I \\\"love\\\" escaped quotes"` in the variable and -`"value": "${var.myvariable}"` in the JSON. - -### Supported built-in functions - -The supported built-in functions are: - - * `abs(float)` - Returns the absolute value of a given float. - Example: `abs(1)` returns `1`, and `abs(-1)` would also return `1`, - whereas `abs(-3.14)` would return `3.14`. See also the `signum` function. - - * `basename(path)` - Returns the last element of a path. - - * `base64decode(string)` - Given a base64-encoded string, decodes it and - returns the original string. - - * `base64encode(string)` - Returns a base64-encoded representation of the - given string. - - * `base64gzip(string)` - Compresses the given string with gzip and then - encodes the result to base64. This can be used with certain resource - arguments that allow binary data to be passed with base64 encoding, since - Terraform strings are required to be valid UTF-8. - - * `base64sha256(string)` - Returns a base64-encoded representation of raw - SHA-256 sum of the given string. - **This is not equivalent** of `base64encode(sha256(string))` - since `sha256()` returns hexadecimal representation. - - * `base64sha512(string)` - Returns a base64-encoded representation of raw - SHA-512 sum of the given string. - **This is not equivalent** of `base64encode(sha512(string))` - since `sha512()` returns hexadecimal representation. - - * `bcrypt(password, cost)` - Returns the Blowfish encrypted hash of the string - at the given cost. A default `cost` of 10 will be used if not provided. - - * `ceil(float)` - Returns the least integer value greater than or equal - to the argument. - - * `chomp(string)` - Removes trailing newlines from the given string. - - * `chunklist(list, size)` - Returns the `list` items chunked by `size`. - Examples: - * `chunklist(aws_subnet.foo.*.id, 1)`: will outputs `[["id1"], ["id2"], ["id3"]]` - * `chunklist(var.list_of_strings, 2)`: will outputs `[["id1", "id2"], ["id3", "id4"], ["id5"]]` - - * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation - and creates an IP address with the given host number. If given host - number is negative, the count starts from the end of the range. - For example, `cidrhost("10.0.0.0/8", 2)` returns `10.0.0.2` and - `cidrhost("10.0.0.0/8", -2)` returns `10.255.255.254`. - - * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation - and returns the address-formatted subnet mask format that some - systems expect for IPv4 interfaces. For example, - `cidrnetmask("10.0.0.0/8")` returns `255.0.0.0`. Not applicable - to IPv6 networks since CIDR notation is the only valid notation for - IPv6. - - * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in - CIDR notation (like `10.0.0.0/8`) and extends its prefix to include an - additional subnet number. For example, - `cidrsubnet("10.0.0.0/8", 8, 2)` returns `10.2.0.0/16`; - `cidrsubnet("2607:f298:6051:516c::/64", 8, 2)` returns - `2607:f298:6051:516c:200::/72`. - - * `coalesce(string1, string2, ...)` - Returns the first non-empty value from - the given arguments. At least two arguments must be provided. - - * `coalescelist(list1, list2, ...)` - Returns the first non-empty list from - the given arguments. At least two arguments must be provided. - - * `compact(list)` - Removes empty string elements from a list. This can be - useful in some cases, for example when passing joined lists as module - variables or when parsing module outputs. - Example: `compact(module.my_asg.load_balancer_names)` - - * `concat(list1, list2, ...)` - Combines two or more lists into a single list. - Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)` - - * `contains(list, element)` - Returns *true* if a list contains the given element - and returns *false* otherwise. Examples: `contains(var.list_of_strings, "an_element")` - - * `dirname(path)` - Returns all but the last element of path, typically the path's directory. - - * `distinct(list)` - Removes duplicate items from a list. Keeps the first - occurrence of each element, and removes subsequent occurrences. This - function is only valid for flat lists. Example: `distinct(var.usernames)` - - * `element(list, index)` - Returns a single element from a list - at the given index. If the index is greater than the number of - elements, this function will wrap using a standard mod algorithm. - This function only works on flat lists. Examples: - * `element(aws_subnet.foo.*.id, count.index)` - * `element(var.list_of_strings, 2)` - - * `file(path)` - Reads the contents of a file into the string. Variables - in this file are _not_ interpolated. The contents of the file are - read as-is. The `path` is interpreted relative to the working directory. - [Path variables](#path-information) can be used to reference paths relative - to other base locations. For example, when using `file()` from inside a - module, you generally want to make the path relative to the module base, - like this: `file("${path.module}/file")`. - - * `floor(float)` - Returns the greatest integer value less than or equal to - the argument. - - * `flatten(list of lists)` - Flattens lists of lists down to a flat list of - primitive values, eliminating any nested lists recursively. Examples: - * `flatten(data.github_user.user.*.gpg_keys)` - - * `format(format, args, ...)` - Formats a string according to the given - format. The syntax for the format is standard `sprintf` syntax. - Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/). - Example to zero-prefix a count, used commonly for naming servers: - `format("web-%03d", count.index + 1)`. - - * `formatlist(format, args, ...)` - Formats each element of a list - according to the given format, similarly to `format`, and returns a list. - Non-list arguments are repeated for each list element. - For example, to convert a list of DNS addresses to a list of URLs, you might use: - `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. - If multiple args are lists, and they have the same number of elements, then the formatting is applied to the elements of the lists in parallel. - Example: - `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. - Passing lists with different lengths to formatlist results in an error. - - * `indent(numspaces, string)` - Prepends the specified number of spaces to all but the first - line of the given multi-line string. May be useful when inserting a multi-line string - into an already-indented context. The first line is not indented, to allow for the - indented string to be placed after some sort of already-indented preamble. - Example: `" \"items\": ${ indent(4, "[\n \"item1\"\n]") },"` - - * `index(list, elem)` - Finds the index of a given element in a list. - This function only works on flat lists. - Example: `index(aws_instance.foo.*.tags.Name, "foo-test")` - - * `join(delim, list)` - Joins the list with the delimiter for a resultant string. - This function works only on flat lists. - Examples: - * `join(",", aws_instance.foo.*.id)` - * `join(",", var.ami_list)` - - * `jsonencode(value)` - Returns a JSON-encoded representation of the given - value, which can contain arbitrarily-nested lists and maps. Note that if - the value is a string then its value will be placed in quotes. - - * `keys(map)` - Returns a lexically sorted list of the map keys. - - * `length(list)` - Returns the number of members in a given list or map, or the number of characters in a given string. - * `${length(split(",", "a,b,c"))}` = 3 - * `${length("a,b,c")}` = 5 - * `${length(map("key", "val"))}` = 1 - - * `list(items, ...)` - Returns a list consisting of the arguments to the function. - This function provides a way of representing list literals in interpolation. - * `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`. - * `${list()}` returns an empty list. - - * `log(x, base)` - Returns the logarithm of `x`. - - * `lookup(map, key, [default])` - Performs a dynamic lookup into a map - variable. The `map` parameter should be another variable, such - as `var.amis`. If `key` does not exist in `map`, the interpolation will - fail unless you specify a third argument, `default`, which should be a - string value to return if no `key` is found in `map`. This function - only works on flat maps and will return an error for maps that - include nested lists or maps. - - * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case. - - * `map(key, value, ...)` - Returns a map consisting of the key/value pairs - specified as arguments. Every odd argument must be a string key, and every - even argument must have the same type as the other values specified. - Duplicate keys are not allowed. Examples: - * `map("hello", "world")` - * `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))` - - * `matchkeys(values, keys, searchset)` - For two lists `values` and `keys` of - equal length, returns all elements from `values` where the corresponding - element from `keys` exists in the `searchset` list. E.g. - `matchkeys(aws_instance.example.*.id, - aws_instance.example.*.availability_zone, list("us-west-2a"))` will return a - list of the instance IDs of the `aws_instance.example` instances in - `"us-west-2a"`. No match will result in empty list. Items of `keys` are - processed sequentially, so the order of returned `values` is preserved. - - * `max(float1, float2, ...)` - Returns the largest of the floats. - - * `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps - are consumed in the order provided, and duplicate keys overwrite previous - entries. - * `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}` - - * `min(float1, float2, ...)` - Returns the smallest of the floats. - - * `md5(string)` - Returns a (conventional) hexadecimal representation of the - MD5 hash of the given string. - - * `pathexpand(string)` - Returns a filepath string with `~` expanded to the home directory. Note: - This will create a plan diff between two different hosts, unless the filepaths are the same. - - * `pow(x, y)` - Returns the base `x` of exponential `y` as a float. - - Example: - * `${pow(3,2)}` = 9 - * `${pow(4,0)}` = 1 - - * `replace(string, search, replace)` - Does a search and replace on the - given string. All instances of `search` are replaced with the value - of `replace`. If `search` is wrapped in forward slashes, it is treated - as a regular expression. If using a regular expression, `replace` - can reference subcaptures in the regular expression by using `$n` where - `n` is the index or name of the subcapture. If using a regular expression, - the syntax conforms to the [re2 regular expression syntax](https://github.com/google/re2/wiki/Syntax). - - * `rsadecrypt(string, key)` - Decrypts `string` using RSA. The padding scheme - PKCS #1 v1.5 is used. The `string` must be base64-encoded. `key` must be an - RSA private key in PEM format. You may use `file()` to load it from a file. - - * `sha1(string)` - Returns a (conventional) hexadecimal representation of the - SHA-1 hash of the given string. - Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"` - - * `sha256(string)` - Returns a (conventional) hexadecimal representation of the - SHA-256 hash of the given string. - Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"` - - * `sha512(string)` - Returns a (conventional) hexadecimal representation of the - SHA-512 hash of the given string. - Example: `"${sha512("${aws_vpc.default.tags.customer}-s3-bucket")}"` - - * `signum(integer)` - Returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. - This function is useful when you need to set a value for the first resource and - a different value for the rest of the resources. - Example: `element(split(",", var.r53_failover_policy), signum(count.index))` - where the 0th index points to `PRIMARY` and 1st to `FAILOVER` - - * `slice(list, from, to)` - Returns the portion of `list` between `from` (inclusive) and `to` (exclusive). - Example: `slice(var.list_of_strings, 0, length(var.list_of_strings) - 1)` - - * `sort(list)` - Returns a lexicographically sorted list of the strings contained in - the list passed as an argument. Sort may only be used with lists which contain only - strings. - Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)` - - * `split(delim, string)` - Returns a list by splitting the string based on - the delimiter. This is useful for pushing lists through module - outputs since they currently only support string values. Depending on the - use, the string this is being performed within may need to be wrapped - in brackets to indicate that the output is actually a list, e.g. - `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. - Example: `split(",", module.amod.server_ids)` - - * `substr(string, offset, length)` - Extracts a substring from the input string. A negative offset is interpreted as being equivalent to a positive offset measured backwards from the end of the string. A length of `-1` is interpreted as meaning "until the end of the string". - - * `timestamp()` - Returns a UTC timestamp string in RFC 3339 format. This string will change with every - invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the - [`ignore_changes`](./resources.html#ignore_changes) lifecycle attribute. - - * `timeadd(time, duration)` - Returns a UTC timestamp string corresponding to adding a given `duration` to `time` in RFC 3339 format. - For example, `timeadd("2017-11-22T00:00:00Z", "10m")` produces a value `"2017-11-22T00:10:00Z"`. - - * `title(string)` - Returns a copy of the string with the first characters of all the words capitalized. - - * `transpose(map)` - Swaps the keys and list values in a map of lists of strings. For example, transpose(map("a", list("1", "2"), "b", list("2", "3")) produces a value equivalent to map("1", list("a"), "2", list("a", "b"), "3", list("b")). - - * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed. - - * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case. - - * `urlencode(string)` - Returns an URL-safe copy of the string. - - * `uuid()` - Returns a random UUID string. This string will change with every invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the [`ignore_changes`](./resources.html#ignore_changes) lifecycle attribute. - - * `values(map)` - Returns a list of the map values, in the order of the keys - returned by the `keys` function. This function only works on flat maps and - will return an error for maps that include nested lists or maps. - - * `zipmap(list, list)` - Creates a map from a list of keys and a list of - values. The keys must all be of type string, and the length of the lists - must be the same. - For example, to output a mapping of AWS IAM user names to the fingerprint - of the key used to encrypt their initial password, you might use: - `zipmap(aws_iam_user.users.*.name, aws_iam_user_login_profile.users.*.key_fingerprint)`. - -The hashing functions `base64sha256`, `base64sha512`, `md5`, `sha1`, `sha256`, -and `sha512` all have variants with a `file` prefix, like `filesha1`, which -interpret their first argument as a path to a file on disk rather than as a -literal string. This allows safely creating hashes of binary files that might -otherwise be corrupted in memory if loaded into Terraform strings (which are -assumed to be UTF-8). `filesha1(filename)` is equivalent to `sha1(file(filename))` -in Terraform 0.11 and earlier, but the latter will fail for binary files in -Terraform 0.12 and later. - -## Templates - -Long strings can be managed using templates. -[Templates](https://registry.terraform.io/providers/hashicorp/template/latest/docs) are -[data-sources](./data-sources.html) defined by a -string with interpolation tokens (usually loaded from a file) and some variables -to use during interpolation. They have a computed `rendered` attribute -containing the result. - -A template data source looks like: - -```hcl -# templates/greeting.tpl -${hello} ${world}! -``` - -```hcl -data "template_file" "example" { - template = "${file("templates/greeting.tpl")}" - vars { - hello = "goodnight" - world = "moon" - } -} - -output "rendered" { - value = "${data.template_file.example.rendered}" -} -``` - -Then the rendered value would be `goodnight moon!`. - --> **Note:** If you specify the template as a literal string instead of loading -a file, the inline template must use double dollar signs (like `$${hello}`) to -prevent Terraform from interpolating values from the configuration into the -string. This is because `template_file` creates its own instance of the -interpolation system, with values provided by its nested `vars` block instead of -by the surrounding scope of the configuration. - -You may use any of the built-in functions in your template. For more -details on template usage, please see the -[template_file documentation](https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file). - -### Using Templates with Count - -Here is an example that combines the capabilities of templates with the interpolation -from `count` to give us a parameterized template, unique to each resource instance: - -```hcl -variable "hostnames" { - default = { - "0" = "example1.org" - "1" = "example2.net" - } -} - -data "template_file" "web_init" { - # Render the template once for each instance - count = "${length(var.hostnames)}" - template = "${file("templates/web_init.tpl")}" - vars { - # count.index tells us the index of the instance we are rendering - hostname = "${var.hostnames[count.index]}" - } -} - -resource "aws_instance" "web" { - # Create one instance for each hostname - count = "${length(var.hostnames)}" - - # Pass each instance its corresponding template_file - user_data = "${data.template_file.web_init.*.rendered[count.index]}" -} -``` - -With this, we will build a list of `template_file.web_init` data resources -which we can use in combination with our list of `aws_instance.web` resources. - -## Math - -Simple math can be performed in interpolations: - -```hcl -variable "count" { - default = 2 -} - -resource "aws_instance" "web" { - # ... - - count = "${var.count}" - - # Tag the instance with a counter starting at 1, ie. web-001 - tags { - Name = "${format("web-%03d", count.index + 1)}" - } -} -``` - -The supported operations are: - -- *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types -- *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types - -Operator precedences is the standard mathematical order of operations: -*Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) have precedence over -*Add* (`+`) and *Subtract* (`-`). Parenthesis can be used to force ordering. - -```text -"${2 * 4 + 3 * 3}" # computes to 17 -"${3 * 3 + 2 * 4}" # computes to 17 -"${2 * (4 + 3) * 3}" # computes to 42 -``` - -You can use the [terraform console](/docs/cli/commands/console.html) command to -try the math operations. - --> **Note:** Since Terraform allows hyphens in resource and variable names, -it's best to use spaces between math operators to prevent confusion or unexpected -behavior. For example, `${var.instance-count - 1}` will subtract **1** from the -`instance-count` variable value, while `${var.instance-count-1}` will interpolate -the `instance-count-1` variable value. diff --git a/website/docs/configuration/expressions.html.md b/website/docs/configuration/expressions.html.md deleted file mode 100644 index 801253dcc..000000000 --- a/website/docs/configuration/expressions.html.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -layout: "language" -page_title: "Expressions Landing Page - Configuration Language" -sidebar_current: "docs-config-expressions" ---- - -# Expressions Landing Page - -To improve navigation, we've split the old Expressions page into several smaller -pages. - - - - - - - -## Types and Values, Literal Expressions, Indices and Attributes - -Terraform's types are `string`, `number`, `bool`, `list`, `tuple`, `map`, -`object`, and `null`. - -This information has moved to -[Types and Values](/docs/language/expressions/types.html). - -
- - - - - - - - - - -## References to Named Values (Resource Attributes, Variables, etc.) - -You can refer to certain values by name, like `var.some_variable` or -`aws_instance.example.ami`. - -This information has moved to -[References to Values](/docs/language/expressions/references.html). - -
- - - - - - - - -## Arithmetic and Logical Operators - -Operators are expressions that transform other expressions, like adding two -numbers (`+`) or comparing two values to get a bool (`==`, `>=`, etc.). - -This information has moved to -[Operators](/docs/language/expressions/operators.html). - -
- - - -## Conditional Expressions - -The `condition ? true_val : false_val` expression chooses between two -expressions based on a bool condition. - -This information has moved to -[Conditional Expressions](/docs/language/expressions/conditionals.html). - -
- - - - - - -## Function Calls - -Terraform's functions can be called like `function_name(arg1, arg2)`. - -This information has moved to -[Function Calls](/docs/language/expressions/function-calls.html). - -
- - - - - -## `for` Expressions - -Expressions like `[for s in var.list : upper(s)]` can transform a complex type -value into another complex type value. - -This information has moved to -[For Expressions](/docs/language/expressions/for.html). - -
- - - - - - -## Splat Expressions - -Expressions like `var.list[*].id` can extract simpler collections from complex -collections. - -This information has moved to -[Splat Expressions](/docs/language/expressions/splat.html). - -
- - - - - - -## `dynamic` Blocks - -The special `dynamic` block type serves the same purpose as a `for` expression, -except it creates multiple repeatable nested blocks instead of a complex value. - -This information has moved to -[Dynamic Blocks](/docs/language/expressions/dynamic-blocks.html). - -
- - - - - - - - -## String Literals and String Templates - -Strings can be `"double-quoted"` or - -```hcl -< diff --git a/website/docs/configuration/expressions.mdx b/website/docs/configuration/expressions.mdx new file mode 100644 index 000000000..f9ac61468 --- /dev/null +++ b/website/docs/configuration/expressions.mdx @@ -0,0 +1,121 @@ +--- +page_title: Expressions Landing Page - Configuration Language +--- + +# Expressions Landing Page + +To improve navigation, we've split the old Expressions page into several smaller +pages. + + + +## Types and Values, Literal Expressions, Indices and Attributes + +Terraform's types are `string`, `number`, `bool`, `list`, `tuple`, `map`, +`object`, and `null`. + +This information has moved to +[Types and Values](/language/expressions/types). + +
+ + + +## References to Named Values (Resource Attributes, Variables, etc.) + +You can refer to certain values by name, like `var.some_variable` or +`aws_instance.example.ami`. + +This information has moved to +[References to Values](/language/expressions/references). + +
+ + + +## Arithmetic and Logical Operators + +Operators are expressions that transform other expressions, like adding two +numbers (`+`) or comparing two values to get a bool (`==`, `>=`, etc.). + +This information has moved to +[Operators](/language/expressions/operators). + +
+ +## Conditional Expressions + +The `condition ? true_val : false_val` expression chooses between two +expressions based on a bool condition. + +This information has moved to +[Conditional Expressions](/language/expressions/conditionals). + +
+ + + +## Function Calls + +Terraform's functions can be called like `function_name(arg1, arg2)`. + +This information has moved to +[Function Calls](/language/expressions/function-calls). + +
+ + + +## `for` Expressions + +Expressions like `[for s in var.list : upper(s)]` can transform a complex type +value into another complex type value. + +This information has moved to +[For Expressions](/language/expressions/for). + +
+ + + +## Splat Expressions + +Expressions like `var.list[*].id` can extract simpler collections from complex +collections. + +This information has moved to +[Splat Expressions](/language/expressions/splat). + +
+ + + +## `dynamic` Blocks + +The special `dynamic` block type serves the same purpose as a `for` expression, +except it creates multiple repeatable nested blocks instead of a complex value. + +This information has moved to +[Dynamic Blocks](/language/expressions/dynamic-blocks). + +
+ + + +## String Literals and String Templates + +Strings can be `"double-quoted"` or + +```hcl +< diff --git a/website/docs/configuration/index.mdx b/website/docs/configuration/index.mdx new file mode 100644 index 000000000..046abeac2 --- /dev/null +++ b/website/docs/configuration/index.mdx @@ -0,0 +1,5 @@ +--- +page_title: Terraform Configuration +--- + +# Terraform Configuration diff --git a/website/docs/configuration/modules.html.md b/website/docs/configuration/modules.html.md deleted file mode 100644 index 1dbcf06a1..000000000 --- a/website/docs/configuration/modules.html.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: "language" -page_title: "Modules Landing Page - Configuration Language" ---- - -# Modules Landing Page - -To improve navigation, we've split the old Modules page into several smaller -pages. - - - - - - - - -## Syntax and Elements of Module Blocks - -This information has moved to -[Module Blocks](/docs/language/modules/syntax.html). - -
- - - - - -## Multiple Instances with `count` and `for_each` - -This information has moved to -[`count`](/docs/language/meta-arguments/count.html) and -[`for_each`](/docs/language/meta-arguments/for_each.html). - -
- - - - - - - - - - -## Handling Provider Configurations in Re-usable Modules - -This information has moved to -[The `providers` Meta-Argument](/docs/language/meta-arguments/module-providers.html) -(for users of re-usable modules) and -[Providers Within Modules](/docs/language/modules/develop/providers.html) -(for module developers). - -
diff --git a/website/docs/configuration/modules.mdx b/website/docs/configuration/modules.mdx new file mode 100644 index 000000000..b6a0adeed --- /dev/null +++ b/website/docs/configuration/modules.mdx @@ -0,0 +1,39 @@ +--- +page_title: Modules Landing Page - Configuration Language +--- + +# Modules Landing Page + +To improve navigation, we've split the old Modules page into several smaller +pages. + + + +## Syntax and Elements of Module Blocks + +This information has moved to +[Module Blocks](/language/modules/syntax). + +
+ + + +## Multiple Instances with `count` and `for_each` + +This information has moved to +[`count`](/language/meta-arguments/count) and +[`for_each`](/language/meta-arguments/for_each). + +
+ + + +## Handling Provider Configurations in Re-usable Modules + +This information has moved to +[The `providers` Meta-Argument](/language/meta-arguments/module-providers) +(for users of re-usable modules) and +[Providers Within Modules](/language/modules/develop/providers) +(for module developers). + +
diff --git a/website/docs/configuration/resources.html.md b/website/docs/configuration/resources.html.md deleted file mode 100644 index 87ae1bf5f..000000000 --- a/website/docs/configuration/resources.html.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -layout: "language" -page_title: "Resources Landing Page - Configuration Language" ---- - -# Resources Landing Page - -To improve navigation, we've split the old Resources page into several smaller -pages. - - - - - - - - - - -## Syntax and Elements of Resource Blocks - -This information has moved to -[Resource Blocks](/docs/language/resources/syntax.html). - -
- - - - - - - - -## Details of Resource Behavior - -This information has moved to -[Resource Behavior](/docs/language/resources/behavior.html). - -
- - - -## Resource Meta-Arguments - -Each resource meta-argument has moved to its own page: - -- [`depends_on`](/docs/language/meta-arguments/depends_on.html) -- [`count`](/docs/language/meta-arguments/count.html) -- [`for_each`](/docs/language/meta-arguments/for_each.html) -- [`provider`](/docs/language/meta-arguments/resource-provider.html) -- [`lifecycle`](/docs/language/meta-arguments/lifecycle.html) -- [Provisioners](/docs/language/resources/provisioners/index.html) - -
- - - - - -### `depends_on` - -This information has moved to -[`depends_on`](/docs/language/meta-arguments/depends_on.html). - -
- - - - - - - - - - - -### `count` - -This information has moved to -[`count`](/docs/language/meta-arguments/count.html). - -
- - - - - - - - - - - -### `for_each` - -This information has moved to -[`for_each`](/docs/language/meta-arguments/for_each.html). - -
- - - - - -### `provider` - -This information has moved to -[`provider`](/docs/language/meta-arguments/resource-provider.html). - -
- - - - - - - - -### `lifecycle` - -This information has moved to -[`lifecycle`](/docs/language/meta-arguments/lifecycle.html). - -
- - - - - -### Provisioners - -This information has moved to -[Provisioners](/docs/language/resources/provisioners/index.html). - -
diff --git a/website/docs/configuration/resources.mdx b/website/docs/configuration/resources.mdx new file mode 100644 index 000000000..7f9489afd --- /dev/null +++ b/website/docs/configuration/resources.mdx @@ -0,0 +1,93 @@ +--- +page_title: Resources Landing Page - Configuration Language +--- + +# Resources Landing Page + +To improve navigation, we've split the old Resources page into several smaller +pages. + + + +## Syntax and Elements of Resource Blocks + +This information has moved to +[Resource Blocks](/language/resources/syntax). + +
+ + + +## Details of Resource Behavior + +This information has moved to +[Resource Behavior](/language/resources/behavior). + +
+ +## Resource Meta-Arguments + +Each resource meta-argument has moved to its own page: + +- [`depends_on`](/language/meta-arguments/depends_on) +- [`count`](/language/meta-arguments/count) +- [`for_each`](/language/meta-arguments/for_each) +- [`provider`](/language/meta-arguments/resource-provider) +- [`lifecycle`](/language/meta-arguments/lifecycle) +- [Provisioners](/language/resources/provisioners) + +
+ + + +### `depends_on` + +This information has moved to +[`depends_on`](/language/meta-arguments/depends_on). + +
+ + + +### `count` + +This information has moved to +[`count`](/language/meta-arguments/count). + +
+ + + +### `for_each` + +This information has moved to +[`for_each`](/language/meta-arguments/for_each). + +
+ + + +### `provider` + +This information has moved to +[`provider`](/language/meta-arguments/resource-provider). + +
+ + + +### `lifecycle` + +This information has moved to +[`lifecycle`](/language/meta-arguments/lifecycle). + +
+ + + +### Provisioners + +This information has moved to +[Provisioners](/language/resources/provisioners). + +
diff --git a/website/docs/internals/archiving.html.md b/website/docs/internals/archiving.mdx similarity index 75% rename from website/docs/internals/archiving.html.md rename to website/docs/internals/archiving.mdx index 6c9cad0f1..5c71326b7 100644 --- a/website/docs/internals/archiving.html.md +++ b/website/docs/internals/archiving.mdx @@ -1,9 +1,9 @@ --- -layout: "docs" -page_title: "Archiving Providers" -sidebar_current: "docs-internals" -description: |- - Terraform is built on a plugin-based architecture, much of which is maintained by our user community. Occasionally, unmaintained providers may archived to reduce confusion for users and developers. +page_title: Archiving Providers +description: >- + Terraform is built on a plugin-based architecture, much of which is maintained + by our user community. Occasionally, unmaintained providers may archived to + reduce confusion for users and developers. --- This function maps -[Terraform language values](/docs/language/expressions/types.html) +[Terraform language values](/language/expressions/types) to YAML tags in the following way: | Terraform type | YAML type | @@ -77,12 +74,12 @@ mean that this is rarely a problem in practice. `yamlencode` always uses YAML's "block style" for mappings and sequences, unless the mapping or sequence is empty. To generate flow-style YAML, use -[`jsonencode`](./jsonencode.html) instead: YAML flow-style is a superset +[`jsonencode`](/language/functions/jsonencode) instead: YAML flow-style is a superset of JSON syntax. ## Related Functions -- [`jsonencode`](./jsonencode.html) is a similar operation using JSON instead +- [`jsonencode`](/language/functions/jsonencode) is a similar operation using JSON instead of YAML. -- [`yamldecode`](./yamldecode.html) performs the opposite operation, _decoding_ +- [`yamldecode`](/language/functions/yamldecode) performs the opposite operation, _decoding_ a YAML string to obtain its represented value. diff --git a/website/docs/language/functions/zipmap.html.md b/website/docs/language/functions/zipmap.mdx similarity index 85% rename from website/docs/language/functions/zipmap.html.md rename to website/docs/language/functions/zipmap.mdx index d37926f74..c813e3e49 100644 --- a/website/docs/language/functions/zipmap.html.md +++ b/website/docs/language/functions/zipmap.mdx @@ -1,7 +1,5 @@ --- -layout: "language" -page_title: "zipmap - Functions - Configuration Language" -sidebar_current: "docs-funcs-collection-zipmap" +page_title: zipmap - Functions - Configuration Language description: |- The zipmap function constructs a map from a list of keys and a corresponding list of values. diff --git a/website/docs/language/index.html.md b/website/docs/language/index.mdx similarity index 89% rename from website/docs/language/index.html.md rename to website/docs/language/index.mdx index 649429890..8efe473ee 100644 --- a/website/docs/language/index.html.md +++ b/website/docs/language/index.mdx @@ -1,16 +1,16 @@ --- -layout: "language" -page_title: "Overview - Configuration Language" -description: "You can use the Terraform language to write configuration files that tell Terraform how to manage a collection of infrastructure." - +page_title: Overview - Configuration Language +description: >- + You can use the Terraform language to write configuration files that tell + Terraform how to manage a collection of infrastructure. --- # Terraform Language Documentation This is the documentation for Terraform's configuration language. It is relevant -to users of [Terraform CLI](/docs/cli/index.html), -[Terraform Cloud](/docs/cloud/index.html), and -[Terraform Enterprise](/docs/enterprise/index.html). Terraform's language is +to users of [Terraform CLI](/cli), +[Terraform Cloud](/cloud), and +[Terraform Enterprise](/enterprise). Terraform's language is its primary user interface. Configuration files you write in Terraform language tell Terraform what plugins to install, what infrastructure to create, and what data to fetch. Terraform language also lets you define dependencies @@ -22,7 +22,7 @@ configuration block. ## About the Terraform Language The main purpose of the Terraform language is declaring -[resources](/docs/language/resources/index.html), which represent infrastructure objects. All other +[resources](/language/resources), which represent infrastructure objects. All other language features exist only to make the definition of resources more flexible and convenient. diff --git a/website/docs/language/meta-arguments/count.html.md b/website/docs/language/meta-arguments/count.mdx similarity index 89% rename from website/docs/language/meta-arguments/count.html.md rename to website/docs/language/meta-arguments/count.mdx index ed188d924..7b051c8f1 100644 --- a/website/docs/language/meta-arguments/count.html.md +++ b/website/docs/language/meta-arguments/count.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "The count Meta-Argument - Configuration Language" -description: "Count helps you efficiently manage nearly identical infrastructure resources without writing a separate block for each one." +page_title: The count Meta-Argument - Configuration Language +description: >- + Count helps you efficiently manage nearly identical infrastructure resources + without writing a separate block for each one. --- # The `count` Meta-Argument @@ -13,14 +14,14 @@ previous versions can only use it with resources. > **Hands-on:** Try the [Manage Similar Resources With Count](https://learn.hashicorp.com/tutorials/terraform/count?in=terraform/0-13&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. -By default, a [resource block](/docs/language/resources/syntax.html) configures one real +By default, a [resource block](/language/resources/syntax) configures one real infrastructure object. (Similarly, a -[module block](/docs/language/modules/syntax.html) includes a +[module block](/language/modules/syntax) includes a child module's contents into the configuration one time.) However, sometimes you want to manage several similar objects (like a fixed pool of compute instances) without writing a separate block for each one. Terraform has two ways to do this: -`count` and [`for_each`](/docs/language/meta-arguments/for_each.html). +`count` and [`for_each`](/language/meta-arguments/for_each). If a resource or module block includes a `count` argument whose value is a whole number, Terraform will create that many instances. @@ -59,7 +60,7 @@ This object has one attribute: ## Using Expressions in `count` -The `count` meta-argument accepts numeric [expressions](/docs/language/expressions/index.html). +The `count` meta-argument accepts numeric [expressions](/language/expressions). However, unlike most arguments, the `count` value must be known _before_ Terraform performs any remote resource actions. This means `count` can't refer to any resource attributes that aren't known until after a diff --git a/website/docs/language/meta-arguments/depends_on.html.md b/website/docs/language/meta-arguments/depends_on.mdx similarity index 92% rename from website/docs/language/meta-arguments/depends_on.html.md rename to website/docs/language/meta-arguments/depends_on.mdx index 7224007c7..0792e721a 100644 --- a/website/docs/language/meta-arguments/depends_on.html.md +++ b/website/docs/language/meta-arguments/depends_on.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "The depends_on Meta-Argument - Configuration Language" -description: "The depends_on meta-argument allows you to handle hidden resource or module dependencies." +page_title: The depends_on Meta-Argument - Configuration Language +description: >- + The depends_on meta-argument allows you to handle hidden resource or module + dependencies. --- # The `depends_on` Meta-Argument @@ -74,4 +75,3 @@ and thus before it can safely evaluate expressions. The `depends_on` argument should be used only as a last resort. When using it, always include a comment explaining why it is being used, to help future maintainers understand the purpose of the additional dependency. - diff --git a/website/docs/language/meta-arguments/for_each.html.md b/website/docs/language/meta-arguments/for_each.mdx similarity index 83% rename from website/docs/language/meta-arguments/for_each.html.md rename to website/docs/language/meta-arguments/for_each.mdx index 088f424fa..48dbc67b2 100644 --- a/website/docs/language/meta-arguments/for_each.html.md +++ b/website/docs/language/meta-arguments/for_each.mdx @@ -1,19 +1,20 @@ --- -layout: "language" -page_title: "The for_each Meta-Argument - Configuration Language" -description: "The for_each meta-argument allows you to manage similar infrastructure resources without writing a separate block for each one." +page_title: The for_each Meta-Argument - Configuration Language +description: >- + The for_each meta-argument allows you to manage similar infrastructure + resources without writing a separate block for each one. --- # The `for_each` Meta-Argument -By default, a [resource block](/docs/language/resources/syntax.html) configures one real +By default, a [resource block](/language/resources/syntax) configures one real infrastructure object (and similarly, a -[module block](/docs/language/modules/syntax.html) includes a +[module block](/language/modules/syntax) includes a child module's contents into the configuration one time). However, sometimes you want to manage several similar objects (like a fixed pool of compute instances) without writing a separate block for each one. Terraform has two ways to do this: -[`count`](/docs/language/meta-arguments/count.html) and `for_each`. +[`count`](/language/meta-arguments/count) and `for_each`. > **Hands-on:** Try the [Manage Similar Resources With For Each](https://learn.hashicorp.com/tutorials/terraform/for-each?in=terraform/configuration-language) tutorial on HashiCorp Learn. @@ -108,16 +109,16 @@ that cannot be determined before apply, and a `-target` may be needed. including `uuid`, `bcrypt`, or `timestamp`, as their evaluation is deferred during the main evaluation step. -Sensitive values, such as [sensitive input variables](https://www.terraform.io/docs/language/values/variables.html#suppressing-values-in-cli-output), -[sensitive outputs](https://www.terraform.io/docs/language/values/outputs.html#sensitive-suppressing-values-in-cli-output), -or [sensitive resource attributes](https://www.terraform.io/docs/language/expressions/references.html#sensitive-resource-attributes), +Sensitive values, such as [sensitive input variables](/language/values/variables#suppressing-values-in-cli-output), +[sensitive outputs](/language/values/outputs#sensitive-suppressing-values-in-cli-output), +or [sensitive resource attributes](/language/expressions/references#sensitive-resource-attributes), cannot be used as arguments to `for_each`. The value used in `for_each` is used to identify the resource instance and will always be disclosed in UI output, which is why sensitive values are not allowed. Attempts to use sensitive values as `for_each` arguments will result in an error. If you transform a value containing sensitive data into an argument to be used in `for_each`, be aware that -[most functions in Terraform will return a sensitive result if given an argument with any sensitive content](https://www.terraform.io/docs/language/expressions/function-calls.html#using-sensitive-data-as-function-arguments). +[most functions in Terraform will return a sensitive result if given an argument with any sensitive content](/language/expressions/function-calls#using-sensitive-data-as-function-arguments). In many cases, you can achieve similar results to a function used for this purpose by using a `for` expression. For example, if you would like to call `keys(local.map)`, where `local.map` is an object with sensitive values (but non-sensitive keys), you can create a @@ -125,7 +126,7 @@ value to pass to `for_each` with `toset([for k,v in local.map : k])`. ## Using Expressions in `for_each` -The `for_each` meta-argument accepts map or set [expressions](/docs/language/expressions/index.html). +The `for_each` meta-argument accepts map or set [expressions](/language/expressions). However, unlike most arguments, the `for_each` value must be known _before_ Terraform performs any remote resource actions. This means `for_each` can't refer to any resource attributes that aren't known until after a @@ -134,7 +135,7 @@ an object is created). The `for_each` value must be a map or set with one element per desired resource instance. When providing a set, you must use an expression that -explicitly returns a set value, like the [`toset`](/docs/language/functions/toset.html) +explicitly returns a set value, like the [`toset`](/language/functions/toset) function; to prevent unwanted surprises during conversion, the `for_each` argument does not implicitly convert lists or tuples to sets. If you need to declare resource instances based on a nested @@ -142,11 +143,11 @@ data structure or combinations of elements from multiple data structures you can use Terraform expressions and functions to derive a suitable value. For example: -* Transform a multi-level nested structure into a flat list by - [using nested `for` expressions with the `flatten` function](/docs/language/functions/flatten.html#flattening-nested-structures-for-for_each). -* Produce an exhaustive list of combinations of elements from two or more +- Transform a multi-level nested structure into a flat list by + [using nested `for` expressions with the `flatten` function](/language/functions/flatten#flattening-nested-structures-for-for_each). +- Produce an exhaustive list of combinations of elements from two or more collections by - [using the `setproduct` function inside a `for` expression](/docs/language/functions/setproduct.html#finding-combinations-for-for_each). + [using the `setproduct` function inside a `for` expression](/language/functions/setproduct#finding-combinations-for-for_each). ### Chaining `for_each` Between Resources @@ -226,7 +227,7 @@ as a whole. ## Using Sets The Terraform language doesn't have a literal syntax for -[set values](/docs/language/expressions/type-constraints.html#collection-types), but you can use the `toset` +[set values](/language/expressions/type-constraints#collection-types), but you can use the `toset` function to explicitly convert a list of strings to a set: ```hcl @@ -255,7 +256,7 @@ removes any duplicate elements. `toset(["b", "a", "b"])` will produce a set containing only `"a"` and `"b"` in no particular order; the second `"b"` is discarded. -If you are writing a module with an [input variable](/docs/language/values/variables.html) that +If you are writing a module with an [input variable](/language/values/variables) that will be used as a set of strings for `for_each`, you can set its type to `set(string)` to avoid the need for an explicit type conversion: diff --git a/website/docs/language/meta-arguments/lifecycle.html.md b/website/docs/language/meta-arguments/lifecycle.html.md deleted file mode 100644 index 840ab71a5..000000000 --- a/website/docs/language/meta-arguments/lifecycle.html.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -layout: "language" -page_title: "The lifecycle Meta-Argument - Configuration Language" -description: "The meta-arguments in a lifecycle block allow you to customize resource behavior." ---- - -# The `lifecycle` Meta-Argument - -> **Hands-on:** Try the [Lifecycle Management](https://learn.hashicorp.com/tutorials/terraform/resource-lifecycle?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. - -The general lifecycle for resources is described in the -[Resource Behavior](/docs/language/resources/behavior.html) page. Some details of -that behavior can be customized using the special nested `lifecycle` block -within a resource block body: - -```hcl -resource "azurerm_resource_group" "example" { - # ... - - lifecycle { - create_before_destroy = true - } -} -``` - -## Syntax and Arguments - -`lifecycle` is a nested block that can appear within a resource block. -The `lifecycle` block and its contents are meta-arguments, available -for all `resource` blocks regardless of type. - -The following arguments can be used within a `lifecycle` block: - -* `create_before_destroy` (bool) - By default, when Terraform must change - a resource argument that cannot be updated in-place due to - remote API limitations, Terraform will instead destroy the existing object - and then create a new replacement object with the new configured arguments. - - The `create_before_destroy` meta-argument changes this behavior so that - the new replacement object is created _first,_ and the prior object - is destroyed after the replacement is created. - - This is an opt-in behavior because many remote object types have unique - name requirements or other constraints that must be accommodated for - both a new and an old object to exist concurrently. Some resource types - offer special options to append a random suffix onto each object name to - avoid collisions, for example. Terraform CLI cannot automatically activate - such features, so you must understand the constraints for each resource - type before using `create_before_destroy` with it. - - Destroy provisioners of this resource will not run if `create_before_destroy` - is set to `true`. We may address this in the future, and this [GitHub issue](https://github.com/hashicorp/terraform/issues/13549) contains more details. - -* `prevent_destroy` (bool) - This meta-argument, when set to `true`, will - cause Terraform to reject with an error any plan that would destroy the - infrastructure object associated with the resource, as long as the argument - remains present in the configuration. - - This can be used as a measure of safety against the accidental replacement - of objects that may be costly to reproduce, such as database instances. - However, it will make certain configuration changes impossible to apply, - and will prevent the use of the `terraform destroy` command once such - objects are created, and so this option should be used sparingly. - - Since this argument must be present in configuration for the protection to - apply, note that this setting does not prevent the remote object from - being destroyed if the `resource` block were removed from configuration - entirely: in that case, the `prevent_destroy` setting is removed along - with it, and so Terraform will allow the destroy operation to succeed. - -* `ignore_changes` (list of attribute names) - By default, Terraform detects - any difference in the current settings of a real infrastructure object - and plans to update the remote object to match configuration. - - The `ignore_changes` feature is intended to be used when a resource is - created with references to data that may change in the future, but should - not affect said resource after its creation. In some rare cases, settings - of a remote object are modified by processes outside of Terraform, which - Terraform would then attempt to "fix" on the next run. In order to make - Terraform share management responsibilities of a single object with a - separate process, the `ignore_changes` meta-argument specifies resource - attributes that Terraform should ignore when planning updates to the - associated remote object. - - The arguments corresponding to the given attribute names are considered - when planning a _create_ operation, but are ignored when planning an - _update_. The arguments are the relative address of the attributes in the - resource. Map and list elements can be referenced using index notation, - like `tags["Name"]` and `list[0]` respectively. - - ```hcl - resource "aws_instance" "example" { - # ... - - lifecycle { - ignore_changes = [ - # Ignore changes to tags, e.g. because a management agent - # updates these based on some ruleset managed elsewhere. - tags, - ] - } - } - ``` - - Instead of a list, the special keyword `all` may be used to instruct - Terraform to ignore _all_ attributes, which means that Terraform can - create and destroy the remote object but will never propose updates to it. - - Only attributes defined by the resource type can be ignored. - `ignore_changes` cannot be applied to itself or to any other meta-arguments. - -## Literal Values Only - -The `lifecycle` settings all affect how Terraform constructs and traverses -the dependency graph. As a result, only literal values can be used because -the processing happens too early for arbitrary expression evaluation. diff --git a/website/docs/language/meta-arguments/lifecycle.mdx b/website/docs/language/meta-arguments/lifecycle.mdx new file mode 100644 index 000000000..1554bcb39 --- /dev/null +++ b/website/docs/language/meta-arguments/lifecycle.mdx @@ -0,0 +1,117 @@ +--- +page_title: The lifecycle Meta-Argument - Configuration Language +description: >- + The meta-arguments in a lifecycle block allow you to customize resource + behavior. +--- + +# The `lifecycle` Meta-Argument + +> **Hands-on:** Try the [Lifecycle Management](https://learn.hashicorp.com/tutorials/terraform/resource-lifecycle?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. + +The general lifecycle for resources is described in the +[Resource Behavior](/language/resources/behavior) page. Some details of +that behavior can be customized using the special nested `lifecycle` block +within a resource block body: + +```hcl +resource "azurerm_resource_group" "example" { + # ... + + lifecycle { + create_before_destroy = true + } +} +``` + +## Syntax and Arguments + +`lifecycle` is a nested block that can appear within a resource block. +The `lifecycle` block and its contents are meta-arguments, available +for all `resource` blocks regardless of type. + +The following arguments can be used within a `lifecycle` block: + +* `create_before_destroy` (bool) - By default, when Terraform must change + a resource argument that cannot be updated in-place due to + remote API limitations, Terraform will instead destroy the existing object + and then create a new replacement object with the new configured arguments. + + The `create_before_destroy` meta-argument changes this behavior so that + the new replacement object is created _first,_ and the prior object + is destroyed after the replacement is created. + + This is an opt-in behavior because many remote object types have unique + name requirements or other constraints that must be accommodated for + both a new and an old object to exist concurrently. Some resource types + offer special options to append a random suffix onto each object name to + avoid collisions, for example. Terraform CLI cannot automatically activate + such features, so you must understand the constraints for each resource + type before using `create_before_destroy` with it. + + Destroy provisioners of this resource will not run if `create_before_destroy` + is set to `true`. We may address this in the future, and this [GitHub issue](https://github.com/hashicorp/terraform/issues/13549) contains more details. + +* `prevent_destroy` (bool) - This meta-argument, when set to `true`, will + cause Terraform to reject with an error any plan that would destroy the + infrastructure object associated with the resource, as long as the argument + remains present in the configuration. + + This can be used as a measure of safety against the accidental replacement + of objects that may be costly to reproduce, such as database instances. + However, it will make certain configuration changes impossible to apply, + and will prevent the use of the `terraform destroy` command once such + objects are created, and so this option should be used sparingly. + + Since this argument must be present in configuration for the protection to + apply, note that this setting does not prevent the remote object from + being destroyed if the `resource` block were removed from configuration + entirely: in that case, the `prevent_destroy` setting is removed along + with it, and so Terraform will allow the destroy operation to succeed. + +* `ignore_changes` (list of attribute names) - By default, Terraform detects + any difference in the current settings of a real infrastructure object + and plans to update the remote object to match configuration. + + The `ignore_changes` feature is intended to be used when a resource is + created with references to data that may change in the future, but should + not affect said resource after its creation. In some rare cases, settings + of a remote object are modified by processes outside of Terraform, which + Terraform would then attempt to "fix" on the next run. In order to make + Terraform share management responsibilities of a single object with a + separate process, the `ignore_changes` meta-argument specifies resource + attributes that Terraform should ignore when planning updates to the + associated remote object. + + The arguments corresponding to the given attribute names are considered + when planning a _create_ operation, but are ignored when planning an + _update_. The arguments are the relative address of the attributes in the + resource. Map and list elements can be referenced using index notation, + like `tags["Name"]` and `list[0]` respectively. + + ```hcl + resource "aws_instance" "example" { + # ... + + lifecycle { + ignore_changes = [ + # Ignore changes to tags, e.g. because a management agent + # updates these based on some ruleset managed elsewhere. + tags, + ] + } + } + ``` + + Instead of a list, the special keyword `all` may be used to instruct + Terraform to ignore _all_ attributes, which means that Terraform can + create and destroy the remote object but will never propose updates to it. + + Only attributes defined by the resource type can be ignored. + `ignore_changes` cannot be applied to itself or to any other meta-arguments. + +## Literal Values Only + +The `lifecycle` settings all affect how Terraform constructs and traverses +the dependency graph. As a result, only literal values can be used because +the processing happens too early for arbitrary expression evaluation. diff --git a/website/docs/language/meta-arguments/module-providers.html.md b/website/docs/language/meta-arguments/module-providers.mdx similarity index 88% rename from website/docs/language/meta-arguments/module-providers.html.md rename to website/docs/language/meta-arguments/module-providers.mdx index 0103fd030..2b7f7d9a9 100644 --- a/website/docs/language/meta-arguments/module-providers.html.md +++ b/website/docs/language/meta-arguments/module-providers.mdx @@ -1,14 +1,15 @@ --- -layout: "language" -page_title: "The Module providers Meta-Argument - Configuration Language" -description: "The providers meta-argument specifies which provider configurations from a parent module are available in a child module." +page_title: The Module providers Meta-Argument - Configuration Language +description: >- + The providers meta-argument specifies which provider configurations from a + parent module are available in a child module. --- # The Module `providers` Meta-Argument -In a [module call](/docs/language/modules/syntax.html) block, the +In a [module call](/language/modules/syntax) block, the optional `providers` meta-argument specifies which -[provider configurations](/docs/language/providers/configuration.html) from the parent +[provider configurations](/language/providers/configuration) from the parent module will be available inside the child module. ```hcl @@ -37,7 +38,7 @@ module "example" { ## Default Behavior: Inherit Default Providers -If the child module does not declare any [configuration aliases](/docs/language/modules/develop/providers.html#provider-aliases-within-modules), +If the child module does not declare any [configuration aliases](/language/modules/develop/providers#provider-aliases-within-modules), the `providers` argument is optional. If you omit it, a child module inherits all of the _default_ provider configurations from its parent module. (Default provider configurations are ones that don't use the `alias` argument.) @@ -122,4 +123,4 @@ names it needs. For more details and guidance about working with providers inside a re-usable child module, see -[Module Development: Providers Within Modules](/docs/language/modules/develop/providers.html). +[Module Development: Providers Within Modules](/language/modules/develop/providers). diff --git a/website/docs/language/meta-arguments/resource-provider.html.md b/website/docs/language/meta-arguments/resource-provider.mdx similarity index 79% rename from website/docs/language/meta-arguments/resource-provider.html.md rename to website/docs/language/meta-arguments/resource-provider.mdx index 21eaad48d..683eaa3e0 100644 --- a/website/docs/language/meta-arguments/resource-provider.html.md +++ b/website/docs/language/meta-arguments/resource-provider.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "The Resource provider Meta-Argument - Configuration Language" -description: "The provider meta-argument specifies the provider configuration Terraform should use for a resource, overriding Terraform's default behavior." +page_title: The Resource provider Meta-Argument - Configuration Language +description: >- + The provider meta-argument specifies the provider configuration Terraform + should use for a resource, overriding Terraform's default behavior. --- # The Resource `provider` Meta-Argument @@ -10,7 +11,7 @@ The `provider` meta-argument specifies which provider configuration to use for a overriding Terraform's default behavior of selecting one based on the resource type name. Its value should be an unquoted `.` reference. -As described in [Provider Configuration](/docs/language/providers/configuration.html), you can optionally +As described in [Provider Configuration](/language/providers/configuration), you can optionally create multiple configurations for a single provider (usually to manage resources in different regions of multi-region services). Each provider can have one default configuration, and any number of alternate configurations that @@ -52,7 +53,7 @@ ensure that the provider is fully configured before any resource actions are taken. The `provider` meta-argument expects -[a `.` reference](/docs/language/providers/configuration.html#referring-to-alternate-provider-configurations), +[a `.` reference](/language/providers/configuration#referring-to-alternate-provider-configurations), which does not need to be quoted. Arbitrary expressions are not permitted for `provider` because it must be resolved while Terraform is constructing the dependency graph, before it is safe to evaluate expressions. diff --git a/website/docs/language/modules/develop/composition.html.md b/website/docs/language/modules/develop/composition.mdx similarity index 98% rename from website/docs/language/modules/develop/composition.html.md rename to website/docs/language/modules/develop/composition.mdx index 96c2da685..a083597e5 100644 --- a/website/docs/language/modules/develop/composition.html.md +++ b/website/docs/language/modules/develop/composition.mdx @@ -1,7 +1,5 @@ --- -layout: "language" -page_title: "Module Composition" -sidebar_current: "docs-modules-composition" +page_title: Module Composition description: |- Module composition allows infrastructure to be described from modular building blocks. @@ -310,7 +308,7 @@ Most modules contain `resource` blocks and thus describe infrastructure to be created and managed. It may sometimes be useful to write modules that do not describe any new infrastructure at all, but merely retrieve information about existing infrastructure that was created elsewhere using -[data sources](/docs/language/data-sources/index.html). +[data sources](/language/data-sources). As with conventional modules, we suggest using this technique only when the module raises the level of abstraction in some way, in this case by @@ -346,7 +344,7 @@ data sources, or it could read saved information from a Consul cluster using [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys), or it might read the outputs directly from the state of the configuration that manages the network using -[`terraform_remote_state`](https://www.terraform.io/docs/language/state/remote-state-data.html). +[`terraform_remote_state`](/language/state/remote-state-data). The key benefit of this approach is that the source of this information can change over time without updating every configuration that depends on it. diff --git a/website/docs/language/modules/develop/index.html.md b/website/docs/language/modules/develop/index.mdx similarity index 77% rename from website/docs/language/modules/develop/index.html.md rename to website/docs/language/modules/develop/index.mdx index 98b28ea7c..760b5ea7a 100644 --- a/website/docs/language/modules/develop/index.html.md +++ b/website/docs/language/modules/develop/index.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Creating Modules" -sidebar_current: "docs-modules" -description: "Modules are containers for multiple resources that are used together in a configuration. Learn when to create modules and about module structure." +page_title: Creating Modules +description: >- + Modules are containers for multiple resources that are used together in a + configuration. Learn when to create modules and about module structure. --- # Creating Modules @@ -14,27 +14,27 @@ Modules can be used to create lightweight abstractions, so that you can describe your infrastructure in terms of its architecture, rather than directly in terms of physical objects. -The `.tf` files in your working directory when you run [`terraform plan`](/docs/cli/commands/plan.html) -or [`terraform apply`](/docs/cli/commands/apply.html) together form the _root_ -module. That module may [call other modules](/docs/language/modules/syntax.html#calling-a-child-module) +The `.tf` files in your working directory when you run [`terraform plan`](/cli/commands/plan) +or [`terraform apply`](/cli/commands/apply) together form the _root_ +module. That module may [call other modules](/language/modules/syntax#calling-a-child-module) and connect them together by passing output values from one to input values of another. -To learn how to _use_ modules, see [the Modules configuration section](/docs/language/modules/index.html). +To learn how to _use_ modules, see [the Modules configuration section](/language/modules). This section is about _creating_ re-usable modules that other configurations can include using `module` blocks. ## Module structure Re-usable modules are defined using all of the same -[configuration language](/docs/language/index.html) concepts we use in root modules. +[configuration language](/language) concepts we use in root modules. Most commonly, modules use: -* [Input variables](/docs/language/values/variables.html) to accept values from +* [Input variables](/language/values/variables) to accept values from the calling module. -* [Output values](/docs/language/values/outputs.html) to return results to the +* [Output values](/language/values/outputs) to return results to the calling module, which it can then use to populate arguments elsewhere. -* [Resources](/docs/language/resources/index.html) to define one or more +* [Resources](/language/resources) to define one or more infrastructure objects that the module will manage. To define a module, create a new directory for it and place one or more `.tf` @@ -44,7 +44,7 @@ be re-used by lots of configurations you may wish to place it in its own version control repository. Modules can also call other modules using a `module` block, but we recommend -keeping the module tree relatively flat and using [module composition](./composition.html) +keeping the module tree relatively flat and using [module composition](/language/modules/develop/composition) as an alternative to a deeply-nested tree of modules, because this makes the individual modules easier to re-use in different combinations. @@ -72,7 +72,7 @@ calling module instead. ## Refactoring module resources -You can include [refactoring blocks](refactoring.html) to record how resource +You can include [refactoring blocks](/language/modules/develop/refactoring) to record how resource names and module structure have changed from previous module versions. Terraform uses that information during planning to reinterpret existing objects as if they had been created at the corresponding new addresses, eliminating a diff --git a/website/docs/language/modules/develop/providers.html.md b/website/docs/language/modules/develop/providers.mdx similarity index 94% rename from website/docs/language/modules/develop/providers.html.md rename to website/docs/language/modules/develop/providers.mdx index fd5db189a..32864a6b6 100644 --- a/website/docs/language/modules/develop/providers.html.md +++ b/website/docs/language/modules/develop/providers.mdx @@ -1,6 +1,5 @@ --- -layout: "language" -page_title: "Providers Within Modules - Configuration Language" +page_title: Providers Within Modules - Configuration Language --- # Providers Within Modules @@ -45,10 +44,10 @@ to reintroduce the provider configuration. ## Provider Version Constraints in Modules Although provider _configurations_ are shared between modules, each module must -declare its own [provider requirements](/docs/language/providers/requirements.html), so that +declare its own [provider requirements](/language/providers/requirements), so that Terraform can ensure that there is a single version of the provider that is compatible with all modules in the configuration and to specify the -[source address](/docs/language/providers/requirements.html#source-addresses) that serves as +[source address](/language/providers/requirements#source-addresses) that serves as the global (module-agnostic) identifier for a provider. To declare that a module requires particular versions of a specific provider, @@ -71,7 +70,7 @@ however, specify any of the configuration settings that determine what remote endpoints the provider will access, such as an AWS region; configuration settings come from provider _configurations_, and a particular overall Terraform configuration can potentially have -[several different configurations for the same provider](/docs/language/providers/configuration.html#alias-multiple-provider-configurations). +[several different configurations for the same provider](/language/providers/configuration#alias-multiple-provider-configurations). ## Provider Aliases Within Modules @@ -133,10 +132,10 @@ resource "aws_s3_bucket" "example" { We recommend using this approach when a single configuration for each provider is sufficient for an entire configuration. -~> **Note:** Only provider configurations are inherited by child modules, not provider source or version requirements. Each module must [declare its own provider requirements](/docs/language/providers/requirements.html). This is especially important for non-HashiCorp providers. +~> **Note:** Only provider configurations are inherited by child modules, not provider source or version requirements. Each module must [declare its own provider requirements](/language/providers/requirements). This is especially important for non-HashiCorp providers. In more complex situations there may be -[multiple provider configurations](/docs/language/providers/configuration.html#alias-multiple-provider-configurations), +[multiple provider configurations](/language/providers/configuration#alias-multiple-provider-configurations), or a child module may need to use different provider settings than its parent. For such situations, you must pass providers explicitly. @@ -173,7 +172,7 @@ module "example" { ``` The `providers` argument within a `module` block is similar to -[the `provider` argument](/docs/language/meta-arguments/resource-provider.html) +[the `provider` argument](/language/meta-arguments/resource-provider) within a resource, but is a map rather than a single string because a module may contain resources from many different providers. diff --git a/website/docs/language/modules/develop/publish.html.md b/website/docs/language/modules/develop/publish.mdx similarity index 76% rename from website/docs/language/modules/develop/publish.html.md rename to website/docs/language/modules/develop/publish.mdx index 2f1419dbb..6a5e0992d 100644 --- a/website/docs/language/modules/develop/publish.html.md +++ b/website/docs/language/modules/develop/publish.mdx @@ -1,20 +1,17 @@ --- -layout: "language" -page_title: "Publishing Modules" -sidebar_current: "docs-modules-publish" -description: |- - A module is a container for multiple resources that are used together. +page_title: Publishing Modules +description: A module is a container for multiple resources that are used together. --- # Publishing Modules If you've built a module that you intend to be reused, we recommend -[publishing the module](/docs/registry/modules/publish.html) on the +[publishing the module](/registry/modules/publish) on the [Terraform Registry](https://registry.terraform.io). This will version your module, generate documentation, and more. Published modules can be easily consumed by Terraform, and users can -[constrain module versions](/docs/language/modules/syntax.html#version) +[constrain module versions](/language/modules/syntax#version) for safe and predictable updates. The following example shows how a caller might use a module from the Terraform Registry: @@ -25,21 +22,20 @@ module "consul" { ``` If you do not wish to publish your modules in the public registry, you can -instead use a [private registry](/docs/registry/private.html) to get +instead use a [private registry](/registry/private) to get the same benefits. We welcome contributions of Terraform modules from our community members, partners, and customers. Our ecosystem is made richer by each new module created or an existing one updated, as they reflect the wide range of experience and technical requirements of the community that uses them. Our cloud provider partners often seek to develop specific modules for popular or challenging use cases on their platform and utilize them as valuable learning experiences to empathize with their users. Similarly, our community module developers incorporate a variety of opinions and use cases from the broader Terraform community. Both types of modules have their place in the Terraform registry, accessible to practitioners who can decide which modules best fit their requirements. - ## Distribution via other sources Although the registry is the native mechanism for distributing re-usable modules, Terraform can also install modules from -[various other sources](/docs/language/modules/sources.html). The alternative sources +[various other sources](/language/modules/sources). The alternative sources do not support the first-class versioning mechanism, but some sources have their own mechanisms for selecting particular VCS commits, etc. We recommend that modules distributed via other protocols still use the -[standard module structure](/docs/language/modules/develop/structure.html) so that they can +[standard module structure](/language/modules/develop/structure) so that they can be used in a similar way as a registry module or be published on the registry at a later time. diff --git a/website/docs/language/modules/develop/refactoring.html.md b/website/docs/language/modules/develop/refactoring.mdx similarity index 95% rename from website/docs/language/modules/develop/refactoring.html.md rename to website/docs/language/modules/develop/refactoring.mdx index b094608ad..210d025ce 100644 --- a/website/docs/language/modules/develop/refactoring.html.md +++ b/website/docs/language/modules/develop/refactoring.mdx @@ -1,15 +1,12 @@ --- -layout: "language" -page_title: "Refactoring" -sidebar_current: "docs-modules-recactoring" -description: |- - How to make backward-compatible changes to modules already in use. +page_title: Refactoring +description: How to make backward-compatible changes to modules already in use. --- # Refactoring -> **Note:** Explicit refactoring declarations with `moved` blocks is available in Terraform v1.1 and later. For earlier Terraform versions or for refactoring actions too complex to express as `moved` blocks, you can -use the [`terraform state mv` CLI command](/docs/cli/commands/state/mv.html) +use the [`terraform state mv` CLI command](/cli/commands/state/mv) as a separate step. In shared modules and long-lived configurations, you may eventually outgrow @@ -125,7 +122,7 @@ resource "aws_instance" "a" { Applying this configuration would lead to Terraform creating an object bound to the address `aws_instance.a`. -Later, you use [`for_each`](../../meta-arguments/for_each.html) with this +Later, you use [`for_each`](/language/meta-arguments/for_each) with this resource to systematically declare multiple instances. To preserve an object that was previously associated with `aws_instance.a` alone, you must add a `moved` block to specify which instance key the object will take in the new @@ -264,7 +261,7 @@ Applying this configuration would cause Terraform to create objects whose addresses begin with `module.a`. In later module versions, you may need to use -[`count`](../../meta-arguments/count.html) with this resource to systematically +[`count`](/language/meta-arguments/count) with this resource to systematically declare multiple instances. To preserve an object that was previously associated with `aws_instance.a` alone, you can add a `moved` block to specify which instance key that object will take in the new configuration: @@ -328,8 +325,8 @@ To achieve this refactoring without replacing existing objects bound to the old resource addresses, you must: 1. Write module "x", copying over the two resources it should contain. -2. Write module "y", copying over the one resource it should contain. -3. Edit the original module to no longer include any of these resources, and +1. Write module "y", copying over the one resource it should contain. +1. Edit the original module to no longer include any of these resources, and instead to contain only shim configuration to migrate existing users. The new modules "x" and "y" should contain only `resource` blocks: @@ -401,13 +398,13 @@ typical rule that a parent module sees its child module as a "closed box", unaware of exactly which resources are declared inside it. This compromise assumes that all three of these modules are maintained by the same people and distributed together in a single -[module package](../sources.html#modules-in-package-sub-directories). +[module package](/language/modules/sources#modules-in-package-sub-directories). -To reduce [coupling](https://en.wikipedia.org/wiki/Coupling_(computer_programming)) +To reduce [coupling](https://en.wikipedia.org/wiki/Coupling_\(computer_programming\)) between separately-packaged modules, Terraform only allows declarations of moves between modules in the same package. In other words, Terraform would not have allowed moving into `module.x` above if the `source` address of -that call had not been a [local path](../sources.html#local-paths). +that call had not been a [local path](/language/modules/sources#local-paths). Terraform resolves module references in `moved` blocks relative to the module instance they are defined in. For example, if the original module above were @@ -439,7 +436,6 @@ If you do decide to remove `moved` blocks, proceed with caution. It can be safe If you need to rename or move the same object twice, we recommend documenting the full history using _chained_ `moved` blocks, where the new block refers to the existing block: - ```hcl moved { from = aws_instance.a diff --git a/website/docs/language/modules/develop/structure.html.md b/website/docs/language/modules/develop/structure.mdx similarity index 95% rename from website/docs/language/modules/develop/structure.html.md rename to website/docs/language/modules/develop/structure.mdx index 6aed2b265..dbe2db33c 100644 --- a/website/docs/language/modules/develop/structure.html.md +++ b/website/docs/language/modules/develop/structure.mdx @@ -1,6 +1,5 @@ --- -layout: "language" -page_title: "Standard Module Structure" +page_title: Standard Module Structure --- # Standard Module Structure @@ -54,8 +53,8 @@ don't need to do any extra work to follow the standard structure. * **Variables and outputs should have descriptions.** All variables and outputs should have one or two sentence descriptions that explain their purpose. This is used for documentation. See the documentation for - [variable configuration](/docs/language/values/variables.html) and - [output configuration](/docs/language/values/outputs.html) for more details. + [variable configuration](/language/values/variables) and + [output configuration](/language/values/outputs) for more details. * **Nested modules**. Nested modules should exist under the `modules/` subdirectory. Any nested module with a `README.md` is considered usable @@ -75,7 +74,7 @@ don't need to do any extra work to follow the standard structure. again separately. If a repository or package contains multiple nested modules, they should - ideally be [composable](./composition.html) by the caller, rather than + ideally be [composable](/language/modules/develop/composition) by the caller, rather than calling directly to each other and creating a deeply-nested tree of modules. * **Examples**. Examples of using the module should exist under the diff --git a/website/docs/language/modules/index.html.md b/website/docs/language/modules/index.mdx similarity index 71% rename from website/docs/language/modules/index.html.md rename to website/docs/language/modules/index.mdx index a1c122768..bbfad4e8e 100644 --- a/website/docs/language/modules/index.html.md +++ b/website/docs/language/modules/index.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "Modules Overview - Configuration Language" -description: "Modules are containers for multiple resources that are used together in a configuration. Find resources for using, developing, and publishing modules." +page_title: Modules Overview - Configuration Language +description: >- + Modules are containers for multiple resources that are used together in a + configuration. Find resources for using, developing, and publishing modules. --- # Modules @@ -43,27 +44,27 @@ download them automatically if you specify the appropriate source and version in a module call block. Also, members of your organization might produce modules specifically crafted -for your own infrastructure needs. [Terraform Cloud](/docs/cloud/index.html) and -[Terraform Enterprise](/docs/enterprise/index.html) both include a private +for your own infrastructure needs. [Terraform Cloud](/cloud) and +[Terraform Enterprise](/enterprise) both include a private module registry for sharing modules internally within your organization. ## Using Modules -- [Module Blocks](/docs/language/modules/syntax.html) documents the syntax for +- [Module Blocks](/language/modules/syntax) documents the syntax for calling a child module from a parent module, including meta-arguments like `for_each`. -- [Module Sources](/docs/language/modules/sources.html) documents what kinds of paths, +- [Module Sources](/language/modules/sources) documents what kinds of paths, addresses, and URIs can be used in the `source` argument of a module block. - The Meta-Arguments section documents special arguments that can be used with every module, including - [`providers`](/docs/language/meta-arguments/module-providers.html), - [`depends_on`](/docs/language/meta-arguments/depends_on.html), - [`count`](/docs/language/meta-arguments/count.html), - and [`for_each`](/docs/language/meta-arguments/for_each.html). + [`providers`](/language/meta-arguments/module-providers), + [`depends_on`](/language/meta-arguments/depends_on), + [`count`](/language/meta-arguments/count), + and [`for_each`](/language/meta-arguments/for_each). ## Developing Modules For information about developing reusable modules, see -[Module Development](/docs/language/modules/develop/index.html). +[Module Development](/language/modules/develop). diff --git a/website/docs/language/modules/sources.html.md b/website/docs/language/modules/sources.mdx similarity index 92% rename from website/docs/language/modules/sources.html.md rename to website/docs/language/modules/sources.mdx index b9db802fa..1af189b94 100644 --- a/website/docs/language/modules/sources.html.md +++ b/website/docs/language/modules/sources.mdx @@ -1,13 +1,14 @@ --- -layout: "language" -page_title: "Module Sources" -sidebar_current: "docs-modules-sources" -description: "The source argument tells Terraform where to find child modules's configurations in locations like GitHub, the Terraform Registry, Bitbucket, Git, Mercurial, S3, and GCS." +page_title: Module Sources +description: >- + The source argument tells Terraform where to find child modules's + configurations in locations like GitHub, the Terraform Registry, Bitbucket, + Git, Mercurial, S3, and GCS. --- # Module Sources -The `source` argument in [a `module` block](/docs/language/modules/syntax.html) +The `source` argument in [a `module` block](/language/modules/syntax) tells Terraform where to find the source code for the desired child module. Terraform uses this during the module installation step of `terraform init` @@ -16,28 +17,28 @@ used by other Terraform commands. > **Hands-on:** Try our HashiCorp Learn tutorials to use modules from [the > registry](https://learn.hashicorp.com/tutorials/terraform/module-use) ->or [locally](https://learn.hashicorp.com/tutorials/terraform/module-create). +> or [locally](https://learn.hashicorp.com/tutorials/terraform/module-create). The module installer supports installation from a number of different source types, as listed below. - * [Local paths](#local-paths) +* [Local paths](#local-paths) - * [Terraform Registry](#terraform-registry) +* [Terraform Registry](#terraform-registry) - * [GitHub](#github) +* [GitHub](#github) - * [Bitbucket](#bitbucket) +* [Bitbucket](#bitbucket) - * Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories +* Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories - * [HTTP URLs](#http-urls) +* [HTTP URLs](#http-urls) - * [S3 buckets](#s3-bucket) +* [S3 buckets](#s3-bucket) - * [GCS buckets](#gcs-bucket) +* [GCS buckets](#gcs-bucket) - * [Modules in Package Sub-directories](#modules-in-package-sub-directories) +* [Modules in Package Sub-directories](#modules-in-package-sub-directories) Each of these is described in the following sections. Module source addresses use a _URL-like_ syntax, but with extensions to support unambiguous selection @@ -99,10 +100,10 @@ to get started with Terraform and find modules created by others in the community. You can also use a -[private registry](/docs/registry/private.html), either +[private registry](/registry/private), either via the built-in feature from Terraform Cloud, or by running a custom service that implements -[the module registry protocol](/docs/registry/api.html). +[the module registry protocol](/registry/api-docs). Modules on the public Terraform Registry can be referenced using a registry source address of the form `//`, with each @@ -138,13 +139,13 @@ the `remote` backend. Registry modules support versioning. You can provide a specific version as shown in the above examples, or use flexible -[version constraints](/docs/language/modules/syntax.html#version). +[version constraints](/language/modules/syntax#version). You can learn more about the registry at the -[Terraform Registry documentation](/docs/registry/modules/use.html#using-modules). +[Terraform Registry documentation](/registry/modules/use#using-modules). To access modules from a private registry, you may need to configure an access -token [in the CLI config](/docs/cli/config/config-file.html#credentials). Use the +token [in the CLI config](/cli/config/config-file#credentials). Use the same hostname as used in the module source string. For a private registry within Terraform Cloud, use the same authentication token as you would use with the Enterprise API or command-line clients. @@ -231,7 +232,7 @@ to select a suitable source of credentials for your environment. If your Terraform configuration will be used within [Terraform Cloud](https://www.hashicorp.com/products/terraform), only SSH key authentication is supported, and -[keys can be configured on a per-workspace basis](/docs/cloud/workspaces/ssh-keys.html). +[keys can be configured on a per-workspace basis](/cloud-docs/workspaces/settings/ssh-keys). ### Selecting a Revision @@ -266,7 +267,6 @@ module "storage" { } ``` - If you use the `ssh://` URL scheme then Terraform will assume that the colon marks the beginning of a port number, rather than the beginning of the path. This matches how Git itself interprets these different forms, aside from @@ -297,7 +297,7 @@ repositories without interactive prompts. If your Terraform configuration will be used within [Terraform Cloud](https://www.hashicorp.com/products/terraform), only SSH key authentication is supported, and -[keys can be configured on a per-workspace basis](/docs/cloud/workspaces/ssh-keys.html). +[keys can be configured on a per-workspace basis](/cloud-docs/workspaces/settings/ssh-keys). ### Selecting a Revision @@ -427,7 +427,6 @@ The module installer uses Google Cloud SDK to authenticate with GCS. To set cred * If you're running Terraform from a GCE instance, default credentials are automatically available. See [Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) for Instances for more details * On your computer, you can make your Google identity available by running `gcloud auth application-default login`. - ## Modules in Package Sub-directories When the source of a module is a version control repository or archive file diff --git a/website/docs/language/modules/syntax.html.md b/website/docs/language/modules/syntax.mdx similarity index 83% rename from website/docs/language/modules/syntax.html.md rename to website/docs/language/modules/syntax.mdx index 83c98fcba..87064e9d3 100644 --- a/website/docs/language/modules/syntax.html.md +++ b/website/docs/language/modules/syntax.mdx @@ -1,8 +1,9 @@ --- -layout: "language" -page_title: "Modules - Configuration Language" -sidebar_current: "docs-config-modules" -description: "Modules are containers for multiple resources that are used together in configurations. Learn how to call one module from another and access module output." +page_title: Modules - Configuration Language +description: >- + Modules are containers for multiple resources that are used together in + configurations. Learn how to call one module from another and access module + output. --- # Module Blocks @@ -22,13 +23,13 @@ in separate configurations, allowing resource configurations to be packaged and re-used. This page describes how to call one module from another. For more information -about creating re-usable child modules, see [Module Development](/docs/language/modules/develop/index.html). +about creating re-usable child modules, see [Module Development](/language/modules/develop). ## Calling a Child Module To _call_ a module means to include the contents of that module into the configuration with specific values for its -[input variables](/docs/language/values/variables.html). Modules are called +[input variables](/language/values/variables). Modules are called from within other modules using `module` blocks: ```hcl @@ -52,7 +53,7 @@ Module calls use the following kinds of arguments: - The `version` argument is recommended for modules from a registry. -- Most other arguments correspond to [input variables](/docs/language/values/variables.html) +- Most other arguments correspond to [input variables](/language/values/variables) defined by the module. (The `servers` argument in the example above is one of these.) @@ -66,7 +67,7 @@ Terraform. Its value is either the path to a local directory containing the module's configuration files, or a remote module source that Terraform should download and use. This value must be a literal string with no template sequences; arbitrary expressions are not allowed. For more information on -possible values for this argument, see [Module Sources](/docs/language/modules/sources.html). +possible values for this argument, see [Module Sources](/language/modules/sources). The same source address can be specified in multiple `module` blocks to create multiple copies of the resources defined within, possibly with different @@ -94,14 +95,14 @@ module "consul" { } ``` -The `version` argument accepts a [version constraint string](/docs/language/expressions/version-constraints.html). +The `version` argument accepts a [version constraint string](/language/expressions/version-constraints). Terraform will use the newest installed version of the module that meets the constraint; if no acceptable versions are installed, it will download the newest version that meets the constraint. Version constraints are supported only for modules installed from a module registry, such as the public [Terraform Registry](https://registry.terraform.io/) -or [Terraform Cloud's private module registry](/docs/cloud/registry/index.html). +or [Terraform Cloud's private module registry](/cloud-docs/registry). Other module sources can provide their own versioning mechanisms within the source string itself, or might not support versions at all. In particular, modules sourced from local file paths do not support `version`; since @@ -115,22 +116,22 @@ optional meta-arguments that have special meaning across all modules, described in more detail in the following pages: - `count` - Creates multiple instances of a module from a single `module` block. - See [the `count` page](/docs/language/meta-arguments/count.html) + See [the `count` page](/language/meta-arguments/count) for details. - `for_each` - Creates multiple instances of a module from a single `module` block. See - [the `for_each` page](/docs/language/meta-arguments/for_each.html) + [the `for_each` page](/language/meta-arguments/for_each) for details. - `providers` - Passes provider configurations to a child module. See - [the `providers` page](/docs/language/meta-arguments/module-providers.html) + [the `providers` page](/language/meta-arguments/module-providers) for details. If not specified, the child module inherits all of the default (un-aliased) provider configurations from the calling module. - `depends_on` - Creates explicit dependencies between the entire module and the listed targets. See - [the `depends_on` page](/docs/language/meta-arguments/depends_on.html) + [the `depends_on` page](/language/meta-arguments/depends_on) for details. In addition to the above, the `lifecycle` argument is not currently used by @@ -140,7 +141,7 @@ Terraform but is reserved for planned future features. The resources defined in a module are encapsulated, so the calling module cannot access their attributes directly. However, the child module can -declare [output values](/docs/language/values/outputs.html) to selectively +declare [output values](/language/values/outputs) to selectively export certain values to be accessed by the calling module. For example, if the `./app-cluster` module referenced in the example above @@ -156,7 +157,7 @@ resource "aws_elb" "example" { ``` For more information about referring to named values, see -[Expressions](/docs/language/expressions/index.html). +[Expressions](/language/expressions). ## Transferring Resource State Into Modules @@ -166,7 +167,7 @@ result, Terraform plans to destroy all resource instances at the old address and create new instances at the new address. To preserve existing objects, you can use -[refactoring blocks](develop/refactoring.html) to record the old and new +[refactoring blocks](/language/modules/develop/refactoring) to record the old and new addresses for each resource instance. This directs Terraform to treat existing objects at the old addresses as if they had originally been created at the corresponding new addresses. @@ -176,7 +177,7 @@ corresponding new addresses. You may have an object that needs to be replaced with a new object for a reason that isn't automatically visible to Terraform, such as if a particular virtual machine is running on degraded underlying hardware. In this case, you can use -[the `-replace=...` planning option](/docs/cli/commands/plan.html#replace-address) +[the `-replace=...` planning option](/cli/commands/plan#replace-address) to force Terraform to propose replacing that object. If the object belongs to a resource within a nested module, specify the full diff --git a/website/docs/language/modules/testing-experiment.html.md b/website/docs/language/modules/testing-experiment.mdx similarity index 99% rename from website/docs/language/modules/testing-experiment.html.md rename to website/docs/language/modules/testing-experiment.mdx index 6b2bb7fce..f230b85b9 100644 --- a/website/docs/language/modules/testing-experiment.html.md +++ b/website/docs/language/modules/testing-experiment.mdx @@ -1,6 +1,5 @@ --- -layout: "language" -page_title: "Module Testing Experiment - Configuration Language" +page_title: Module Testing Experiment - Configuration Language --- # Module Testing Experiment diff --git a/website/docs/language/providers/configuration.html.md b/website/docs/language/providers/configuration.mdx similarity index 86% rename from website/docs/language/providers/configuration.html.md rename to website/docs/language/providers/configuration.mdx index 8251bce19..4513338fb 100644 --- a/website/docs/language/providers/configuration.html.md +++ b/website/docs/language/providers/configuration.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Provider Configuration - Configuration Language" -sidebar_current: "docs-config-providers" -description: "Learn how to set up providers, including how to use the alias meta-argument to specify multiple configurations for a single provider." +page_title: Provider Configuration - Configuration Language +description: >- + Learn how to set up providers, including how to use the alias meta-argument to + specify multiple configurations for a single provider. --- # Provider Configuration @@ -16,7 +16,7 @@ configure settings for providers. Additionally, all Terraform configurations must declare which providers they require so that Terraform can install and use them. The -[Provider Requirements](/docs/language/providers/requirements.html) +[Provider Requirements](/language/providers/requirements) page documents how to declare providers so Terraform can install them. ## Provider Configuration @@ -24,8 +24,8 @@ page documents how to declare providers so Terraform can install them. Provider configurations belong in the root module of a Terraform configuration. (Child modules receive their provider configurations from the root module; for more information, see -[The Module `providers` Meta-Argument](/docs/language/meta-arguments/module-providers.html) -and [Module Development: Providers Within Modules](/docs/language/modules/develop/providers.html).) +[The Module `providers` Meta-Argument](/language/meta-arguments/module-providers) +and [Module Development: Providers Within Modules](/language/modules/develop/providers).) A provider configuration is created using a `provider` block: @@ -37,7 +37,7 @@ provider "google" { ``` The name given in the block header (`"google"` in this example) is the -[local name](/docs/language/providers/requirements.html#local-names) of the provider to +[local name](/language/providers/requirements#local-names) of the provider to configure. This provider should already be included in a `required_providers` block. @@ -46,7 +46,7 @@ the provider. Most arguments in this section are defined by the provider itself; in this example both `project` and `region` are specific to the `google` provider. -You can use [expressions](/docs/language/expressions/index.html) in the values of these +You can use [expressions](/language/expressions) in the values of these configuration arguments, but can only reference values that are known before the configuration is applied. This means you can safely reference input variables, but not attributes exported by resources (with an exception for resource @@ -68,7 +68,7 @@ and available for all `provider` blocks: - [`alias`, for using the same provider with different configurations for different resources][inpage-alias] - [`version`, which we no longer recommend][inpage-versions] (use - [provider requirements](/docs/language/providers/requirements.html) instead) + [provider requirements](/language/providers/requirements) instead) Unlike many other objects in the Terraform language, a `provider` block may be omitted if its contents would otherwise be empty. Terraform assumes an @@ -175,7 +175,7 @@ module "aws_vpc" { ``` Modules have some special requirements when passing in providers; see -[The Module `providers` Meta-Argument](/docs/language/meta-arguments/module-providers.html) +[The Module `providers` Meta-Argument](/language/meta-arguments/module-providers) for more details. In most cases, only _root modules_ should define provider configurations, with all child modules obtaining their provider configurations from their parents. @@ -188,11 +188,11 @@ from their parents. The `version` meta-argument specifies a version constraint for a provider, and works the same way as the `version` argument in a -[`required_providers` block](/docs/language/providers/requirements.html). The version +[`required_providers` block](/language/providers/requirements). The version constraint in a provider configuration is only used if `required_providers` does not include one for that provider. **The `version` argument in provider configurations is deprecated.** In Terraform 0.13 and later, always declare provider version constraints in -[the `required_providers` block](/docs/language/providers/requirements.html). The `version` +[the `required_providers` block](/language/providers/requirements). The `version` argument will be removed in a future version of Terraform. diff --git a/website/docs/language/providers/index.html.md b/website/docs/language/providers/index.mdx similarity index 54% rename from website/docs/language/providers/index.html.md rename to website/docs/language/providers/index.mdx index fd95e66e5..6dab35086 100644 --- a/website/docs/language/providers/index.html.md +++ b/website/docs/language/providers/index.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "Providers - Configuration Language" -description: "An overview of how to install and use providers, Terraform plugins that interact with services, cloud providers, and other APIs." +page_title: Providers - Configuration Language +description: >- + An overview of how to install and use providers, Terraform plugins that + interact with services, cloud providers, and other APIs. --- # Providers @@ -17,8 +18,8 @@ configuration (like endpoint URLs or cloud regions) before they can be used. ## What Providers Do -Each provider adds a set of [resource types](/docs/language/resources/index.html) -and/or [data sources](/docs/language/data-sources/index.html) that Terraform can +Each provider adds a set of [resource types](/language/resources) +and/or [data sources](/language/data-sources) that Terraform can manage. Every resource type is implemented by a provider; without providers, Terraform @@ -50,20 +51,20 @@ Provider documentation in the Registry is versioned; you can use the version menu in the header to change which version you're viewing. For details about writing, generating, and previewing provider documentation, -see the [provider publishing documentation](/docs/registry/providers/docs.html). +see the [provider publishing documentation](/registry/providers/docs). ## How to Use Providers To use resources from a given provider, you need to include some information about it in your configuration. See the following pages for details: -- [Provider Requirements](/docs/language/providers/requirements.html) +- [Provider Requirements](/language/providers/requirements) documents how to declare providers so Terraform can install them. -- [Provider Configuration](/docs/language/providers/configuration.html) +- [Provider Configuration](/language/providers/configuration) documents how to configure settings for providers. -- [Dependency Lock File](/docs/language/dependency-lock.html) +- [Dependency Lock File](/language/files/dependency-lock) documents an additional HCL file that can be included with a configuration, which tells Terraform to always use a specific set of provider versions. @@ -72,18 +73,18 @@ about it in your configuration. See the following pages for details: - Terraform Cloud and Terraform Enterprise install providers as part of every run. - Terraform CLI finds and installs providers when - [initializing a working directory](/docs/cli/init/index.html). It can + [initializing a working directory](/cli/init). It can automatically download providers from a Terraform registry, or load them from a local mirror or cache. If you are using a persistent working directory, you must reinitialize whenever you change a configuration's providers. - To save time and bandwidth, Terraform CLI supports an optional plugin - cache. You can enable the cache using the `plugin_cache_dir` setting in - [the CLI configuration file](/docs/cli/config/config-file.html). + To save time and bandwidth, Terraform CLI supports an optional plugin + cache. You can enable the cache using the `plugin_cache_dir` setting in + [the CLI configuration file](/cli/config/config-file). To ensure Terraform always installs the same provider versions for a given configuration, you can use Terraform CLI to create a -[dependency lock file](/docs/language/dependency-lock.html) +[dependency lock file](/language/files/dependency-lock) and commit it to version control along with your configuration. If a lock file is present, Terraform Cloud, CLI, and Enterprise will all obey it when installing providers. @@ -100,42 +101,14 @@ are published by platform maintainers, and some are published by users and volunteers. The provider listings use the following badges to indicate who develops and maintains a given provider. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TierDescriptionNamespace
Official providers are owned and maintained by HashiCorp hashicorp
Verified providers are owned and maintained by third-party technology partners. Providers in this tier indicate HashiCorp has verified the authenticity of the Provider’s publisher, and that the partner is a member of the HashiCorp Technology Partner Program.Third-party organization, e.g. mongodb/mongodbatlas
Community providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.
Maintainer’s individual or organization account, e.g. DeviaVir/gsuite
Archived Providers are Official or Verified Providers that are no longer maintained by HashiCorp or the community. This may occur if an API is deprecated or interest was low.hashicorp or third-party
- + +

## How to Develop Providers Providers are written in Go, using the Terraform Plugin SDK. For more information on developing providers, see: -- The [Plugin Development](/docs/extend/index.html) documentation +- The [Plugin Development](/plugin) documentation - The [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn diff --git a/website/docs/language/providers/requirements.html.md b/website/docs/language/providers/requirements.mdx similarity index 91% rename from website/docs/language/providers/requirements.html.md rename to website/docs/language/providers/requirements.mdx index 6e8b995c4..8331bd74e 100644 --- a/website/docs/language/providers/requirements.html.md +++ b/website/docs/language/providers/requirements.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "Provider Requirements - Configuration Language" -description: "Providers are plugins that allow Terraform to interact with services, cloud providers, and other APIs. Learn how to declare providers in a configuration." +page_title: Provider Requirements - Configuration Language +description: >- + Providers are plugins that allow Terraform to interact with services, cloud + providers, and other APIs. Learn how to declare providers in a configuration. --- # Provider Requirements @@ -15,7 +16,7 @@ so Terraform can install them. Additionally, some providers require configuration (like endpoint URLs or cloud regions) before they can be used. The [Provider -Configuration](/docs/language/providers/configuration.html) page documents how +Configuration](/language/providers/configuration) page documents how to configure settings for providers. -> **Note:** This page is about a feature of Terraform 0.13 and later; it also @@ -43,7 +44,7 @@ terraform { ``` The `required_providers` block must be nested inside the top-level -[`terraform` block](/docs/language/settings/index.html) (which can also contain other settings). +[`terraform` block](/language/settings) (which can also contain other settings). Each argument in the `required_providers` block enables one provider. The key determines the provider's [local name](#local-names) (its unique identifier @@ -66,8 +67,8 @@ Requirements](#v0-12-compatible-provider-requirements) below. Each provider has two identifiers: -- A unique _source address,_ which is only used when requiring a provider. -- A _local name,_ which is used everywhere else in a Terraform module. +* A unique _source address,_ which is only used when requiring a provider. +* A _local name,_ which is used everywhere else in a Terraform module. -> **Note:** Prior to Terraform 0.13, providers only had local names, since Terraform could only automatically download providers distributed by HashiCorp. @@ -80,7 +81,7 @@ Local names must be unique per-module. Outside of the `required_providers` block, Terraform configurations always refer to providers by their local names. For example, the following configuration declares `mycloud` as the local name for `mycorp/mycloud`, then uses that local -name when [configuring the provider](/docs/language/providers/configuration.html): +name when [configuring the provider](/language/providers/configuration): ```hcl terraform { @@ -131,11 +132,11 @@ follows: * **Type:** A short name for the platform or system the provider manages. Must be unique within a particular namespace on a particular registry host. - The type is usually the provider's preferred local name. (There are - exceptions; for example, - [`hashicorp/google-beta`](https://registry.terraform.io/providers/hashicorp/google-beta/latest) - is an alternate release channel for `hashicorp/google`, so its preferred - local name is `google`. If in doubt, check the provider's documentation.) + The type is usually the provider's preferred local name. (There are + exceptions; for example, + [`hashicorp/google-beta`](https://registry.terraform.io/providers/hashicorp/google-beta/latest) + is an alternate release channel for `hashicorp/google`, so its preferred + local name is `google`. If in doubt, check the provider's documentation.) For example, [the official HTTP provider](https://registry.terraform.io/providers/hashicorp/http) @@ -150,7 +151,6 @@ version is used. This display version omits the source host when it is the public registry, so you may see the shortened version `"hashicorp/random"` instead of `"registry.terraform.io/hashicorp/random"`. - -> **Note:** If you omit the `source` argument when requiring a provider, Terraform uses an implied source address of `registry.terraform.io/hashicorp/`. This is a backward compatibility @@ -210,7 +210,7 @@ avoiding typing. Each provider plugin has its own set of available versions, allowing the functionality of the provider to evolve over time. Each provider dependency you -declare should have a [version constraint](/docs/language/expressions/version-constraints.html) given in +declare should have a [version constraint](/language/expressions/version-constraints) given in the `version` argument so Terraform can select a single version per provider that all modules are compatible with. @@ -220,7 +220,7 @@ a version constraint for every provider your module depends on. To ensure Terraform always installs the same provider versions for a given configuration, you can use Terraform CLI to create a -[dependency lock file](/docs/language/dependency-lock.html) +[dependency lock file](/language/files/dependency-lock) and commit it to version control along with your configuration. If a lock file is present, Terraform Cloud, CLI, and Enterprise will all obey it when installing providers. @@ -272,7 +272,7 @@ incompatibilities, and let the root module manage the maximum version. While most Terraform providers are distributed separately as plugins, there is currently one provider that is built in to Terraform itself, which provides -[the `terraform_remote_state` data source](/docs/language/state/remote-state-data.html). +[the `terraform_remote_state` data source](/language/state/remote-state-data). Because this provider is built in to Terraform, you don't need to declare it in the `required_providers` block in order to use its features. However, for @@ -301,11 +301,11 @@ publishing them on the public Terraform Registry. One option for distributing such a provider is to run an in-house _private_ registry, by implementing -[the provider registry protocol](/docs/internals/provider-registry-protocol.html). +[the provider registry protocol](/internals/provider-registry-protocol). Running an additional service just to distribute a single provider internally may be undesirable, so Terraform also supports -[other provider installation methods](/docs/cli/config/config-file.html#provider-installation), +[other provider installation methods](/cli/config/config-file#provider-installation), including placing provider plugins directly in specific directories in the local filesystem, via _filesystem mirrors_. @@ -334,7 +334,7 @@ terraform { To make version 1.0.0 of this provider available for installation from the local filesystem, choose one of the -[implied local mirror directories](/docs/cli/config/config-file.html#implied-local-mirror-directories) +[implied local mirror directories](/cli/config/config-file#implied-local-mirror-directories) and create a directory structure under it like this: ``` diff --git a/website/docs/language/resources/behavior.html.md b/website/docs/language/resources/behavior.mdx similarity index 86% rename from website/docs/language/resources/behavior.html.md rename to website/docs/language/resources/behavior.mdx index 1f8b4c249..4d53a1f61 100644 --- a/website/docs/language/resources/behavior.html.md +++ b/website/docs/language/resources/behavior.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "Resource Behavior - Configuration Language" -description: "Learn how Terraform uses resource blocks to create infrastructure objects. Also learn about resource dependencies and how to access resource attributes." +page_title: Resource Behavior - Configuration Language +description: >- + Learn how Terraform uses resource blocks to create infrastructure objects. + Also learn about resource dependencies and how to access resource attributes. --- # Resource Behavior @@ -19,7 +20,7 @@ match the configuration. When Terraform creates a new infrastructure object represented by a `resource` block, the identifier for that real object is saved in Terraform's -[state](/docs/language/state/index.html), allowing it to be updated and destroyed +[state](/language/state), allowing it to be updated and destroyed in response to future changes. For resource blocks that already have an associated infrastructure object in the state, Terraform compares the actual configuration of the object with the arguments given in the @@ -43,7 +44,7 @@ customized on a per-resource basis. ## Accessing Resource Attributes -[Expressions](/docs/language/expressions/index.html) within a Terraform module can access +[Expressions](/language/expressions) within a Terraform module can access information about resources in the same module, and you can use that information to help configure other resources. Use the `..` syntax to reference a resource attribute in an expression. @@ -53,7 +54,7 @@ read-only attributes with information obtained from the remote API; this often includes things that can't be known until the resource is created, like the resource's unique random ID. -Many providers also include [data sources](/docs/language/data-sources/index.html), +Many providers also include [data sources](/language/data-sources), which are a special type of resource used only for looking up information. For a list of the attributes a resource or data source type provides, consult @@ -61,7 +62,7 @@ its documentation; these are generally included in a second list below its list of configurable arguments. For more information about referencing resource attributes in expressions, see -[Expressions: References to Resource Attributes](/docs/language/expressions/references.html#references-to-resource-attributes). +[Expressions: References to Resource Attributes](/language/expressions/references#references-to-resource-attributes). ## Resource Dependencies @@ -74,7 +75,7 @@ resource's configuration just requires information generated by another resource. Most resource dependencies are handled automatically. Terraform analyses any -[expressions](/docs/language/expressions/index.html) within a `resource` block to find references +[expressions](/language/expressions) within a `resource` block to find references to other objects, and treats those references as implicit ordering requirements when creating, updating, or destroying resources. Since most resources with behavioral dependencies on other resources also refer to those resources' data, @@ -85,7 +86,7 @@ example, if Terraform must manage access control policies _and_ take actions that require those policies to be present, there is a hidden dependency between the access policy and a resource whose creation depends on it. In these rare cases, -[the `depends_on` meta-argument](/docs/language/meta-arguments/depends_on.html) +[the `depends_on` meta-argument](/language/meta-arguments/depends_on) can explicitly specify a dependency. ## Local-only Resources @@ -106,4 +107,3 @@ connect together other resources. The behavior of local-only resources is the same as all other resources, but their result data exists only within the Terraform state. "Destroying" such a resource means only to remove it from the state, discarding its data. - diff --git a/website/docs/language/resources/index.html.md b/website/docs/language/resources/index.mdx similarity index 55% rename from website/docs/language/resources/index.html.md rename to website/docs/language/resources/index.mdx index 4de70b7d4..08921cf75 100644 --- a/website/docs/language/resources/index.html.md +++ b/website/docs/language/resources/index.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "Resources Overview - Configuration Language" -description: "Resources describe infrastructure objects in Terraform configurations. Find documentation for resource syntax, behavior, and meta-arguments." +page_title: Resources Overview - Configuration Language +description: >- + Resources describe infrastructure objects in Terraform configurations. Find + documentation for resource syntax, behavior, and meta-arguments. --- # Resources @@ -13,22 +14,22 @@ Each resource block describes one or more infrastructure objects, such as virtual networks, compute instances, or higher-level components such as DNS records. -- [Resource Blocks](/docs/language/resources/syntax.html) documents +- [Resource Blocks](/language/resources/syntax) documents the syntax for declaring resources. -- [Resource Behavior](/docs/language/resources/behavior.html) explains in +- [Resource Behavior](/language/resources/behavior) explains in more detail how Terraform handles resource declarations when applying a configuration. - The Meta-Arguments section documents special arguments that can be used with every resource type, including - [`depends_on`](/docs/language/meta-arguments/depends_on.html), - [`count`](/docs/language/meta-arguments/count.html), - [`for_each`](/docs/language/meta-arguments/for_each.html), - [`provider`](/docs/language/meta-arguments/resource-provider.html), - and [`lifecycle`](/docs/language/meta-arguments/lifecycle.html). + [`depends_on`](/language/meta-arguments/depends_on), + [`count`](/language/meta-arguments/count), + [`for_each`](/language/meta-arguments/for_each), + [`provider`](/language/meta-arguments/resource-provider), + and [`lifecycle`](/language/meta-arguments/lifecycle). -- [Provisioners](/docs/language/resources/provisioners/index.html) +- [Provisioners](/language/resources/provisioners) documents configuring post-creation actions for a resource using the `provisioner` and `connection` blocks. Since provisioners are non-declarative and potentially unpredictable, we strongly recommend that you treat them as a diff --git a/website/docs/language/resources/provisioners/chef.html.md b/website/docs/language/resources/provisioners/chef.mdx similarity index 93% rename from website/docs/language/resources/provisioners/chef.html.md rename to website/docs/language/resources/provisioners/chef.mdx index e420b9a38..9ec4887e2 100644 --- a/website/docs/language/resources/provisioners/chef.html.md +++ b/website/docs/language/resources/provisioners/chef.mdx @@ -1,18 +1,17 @@ --- -layout: "language" -page_title: "Provisioner: chef" -sidebar_current: "docs-provisioners-chef" -description: |- - The `chef` provisioner installs, configures and runs the Chef client on a resource. +page_title: 'Provisioner: chef' +description: >- + The `chef` provisioner installs, configures and runs the Chef client on a + resource. --- # Chef Provisioner The `chef` provisioner installs, configures and runs the Chef Client on a remote resource. The `chef` provisioner supports both `ssh` and `winrm` type -[connections](/docs/language/resources/provisioners/connection.html). +[connections](/language/resources/provisioners/connection). -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](./). +!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). ## Requirements @@ -68,7 +67,7 @@ The following arguments are supported: * `attributes_json (string)` - (Optional) A raw JSON string with initial node attributes for the new node. These can also be loaded from a file on disk using - [the `file` function](/docs/language/functions/file.html). + [the `file` function](/language/functions/file). * `channel (string)` - (Optional) The Chef Client release channel to install from. If not set, the `stable` channel will be used. @@ -127,7 +126,7 @@ The following arguments are supported: * `prevent_sudo (boolean)` - (Optional) Prevent the use of the `sudo` command while installing, configuring and running the initial Chef Client run. This option is only used with `ssh` type - [connections](/docs/language/resources/provisioners/connection.html). + [connections](/language/resources/provisioners/connection). * `recreate_client (boolean)` - (Optional) If `true`, first delete any existing Chef Node and Client before registering the new Chef Client. @@ -145,7 +144,7 @@ The following arguments are supported: * `secret_key (string)` - (Optional) The contents of the secret key that is used by the Chef Client to decrypt data bags on the Chef Server. The key will be uploaded to the remote machine. This can also be loaded from a file on disk using - [the `file` function](/docs/language/functions/file.html). + [the `file` function](/language/functions/file). * `server_url (string)` - (Required) The URL to the Chef server. This includes the path to the organization. See the example. @@ -167,11 +166,11 @@ The following arguments are supported: * `user_key (string)` - (Required) The contents of the user key that will be used to authenticate with the Chef Server. This can also be loaded from a file on disk using - [the `file` function](/docs/language/functions/file.html). + [the `file` function](/language/functions/file). * `vault_json (string)` - (Optional) A raw JSON string with Chef Vaults and Items to which the new node should have access. These can also be loaded from a file on disk using - [the `file` function](/docs/language/functions/file.html). + [the `file` function](/language/functions/file). * `version (string)` - (Optional) The Chef Client version to install on the remote machine. If not set, the latest available version will be installed. diff --git a/website/docs/language/resources/provisioners/connection.html.md b/website/docs/language/resources/provisioners/connection.mdx similarity index 80% rename from website/docs/language/resources/provisioners/connection.html.md rename to website/docs/language/resources/provisioners/connection.mdx index 762c37a91..704012199 100644 --- a/website/docs/language/resources/provisioners/connection.html.md +++ b/website/docs/language/resources/provisioners/connection.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Provisioner Connection Settings" -sidebar_current: "docs-provisioners-connection" -description: "The connection block allows you to manage provisioner connection defaults for SSH and WinRM." +page_title: Provisioner Connection Settings +description: >- + The connection block allows you to manage provisioner connection defaults for + SSH and WinRM. --- # Provisioner Connection Settings @@ -12,7 +12,7 @@ expect a nested `connection` block with details about how to connect. -> **Note:** Provisioners should only be used as a last resort. For most common situations there are better alternatives. For more information, see -[the main Provisioners page](./). +[the main Provisioners page](/language/resources/provisioners). -> **Note:** In Terraform 0.11 and earlier, providers could set default values for some connection settings, so that `connection` blocks could sometimes be @@ -28,9 +28,9 @@ below explicitly set to verify against a specific key or signing CA. Connection blocks don't take a block label, and can be nested within either a `resource` or a `provisioner`. -- A `connection` block nested directly within a `resource` affects all of +* A `connection` block nested directly within a `resource` affects all of that resource's provisioners. -- A `connection` block nested in a `provisioner` block only affects that +* A `connection` block nested in a `provisioner` block only affects that provisioner, and overrides any resource-level connection settings. One use case for providing multiple connections is to have an initial @@ -85,10 +85,10 @@ block would create a dependency cycle. **The following arguments are supported by all connection types:** * `type` - The connection type that should be used. Valid types are `ssh` and `winrm`. - Defaults to `ssh`. + Defaults to `ssh`. * `user` - The user that we should use for the connection. - Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`. + Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`. * `password` - The password we should use for the connection. In some cases this is specified by the provider. @@ -96,10 +96,10 @@ block would create a dependency cycle. * `host` - (Required) The address of the resource to connect to. * `port` - The port to connect to. - Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`. + Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`. * `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`. - Defaults to 5 minutes. + Defaults to 5 minutes. * `script_path` - The path used to copy scripts meant for remote execution. @@ -107,24 +107,25 @@ block would create a dependency cycle. * `private_key` - The contents of an SSH key to use for the connection. These can be loaded from a file on disk using - [the `file` function](/docs/language/functions/file.html). This takes + [the `file` function](/language/functions/file). This takes preference over the password if provided. * `certificate` - The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can - be loaded from a file on disk using the [the `file` function](/docs/language/functions/file.html). + be loaded from a file on disk using the [the `file` function](/language/functions/file). * `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the only supported SSH authentication agent is - [Pageant](http://the.earth.li/~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). + [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). * `agent_identity` - The preferred identity from the ssh agent for authentication. * `host_key` - The public key from the remote host or the signing CA, used to verify the connection. + * `target_platform` - The target platform to connect to. Valid values are `windows` and `unix`. Defaults to `unix` if not set. - If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` + If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` **Additional arguments only supported by the `winrm` connection type:** @@ -160,9 +161,9 @@ The `ssh` connection also supports the following fields to facilitate connnectio * `bastion_private_key` - The contents of an SSH key file to use for the bastion host. These can be loaded from a file on disk using - [the `file` function](/docs/language/functions/file.html). + [the `file` function](/language/functions/file). Defaults to the value of the `private_key` field. * `bastion_certificate` - The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `bastion_private_key`. These can be loaded from - a file on disk using the [the `file` function](/docs/language/functions/file.html). + a file on disk using the [the `file` function](/language/functions/file). diff --git a/website/docs/language/resources/provisioners/file.html.md b/website/docs/language/resources/provisioners/file.mdx similarity index 89% rename from website/docs/language/resources/provisioners/file.html.md rename to website/docs/language/resources/provisioners/file.mdx index 05b494e5b..06b22758b 100644 --- a/website/docs/language/resources/provisioners/file.html.md +++ b/website/docs/language/resources/provisioners/file.mdx @@ -1,20 +1,20 @@ --- -layout: "language" -page_title: "Provisioner: file" -sidebar_current: "docs-provisioners-file" -description: |- - The `file` provisioner is used to copy files or directories from the machine executing Terraform to the newly created resource. The `file` provisioner supports both `ssh` and `winrm` type connections. +page_title: 'Provisioner: file' +description: >- + The `file` provisioner is used to copy files or directories from the machine + executing Terraform to the newly created resource. The `file` provisioner + supports both `ssh` and `winrm` type connections. --- # File Provisioner The `file` provisioner is used to copy files or directories from the machine executing Terraform to the newly created resource. The `file` provisioner -supports both `ssh` and `winrm` type [connections](/docs/language/resources/provisioners/connection.html). +supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection). -> **Note:** Provisioners should only be used as a last resort. For most common situations there are better alternatives. For more information, see -[the main Provisioners page](./). +[the main Provisioners page](/language/resources/provisioners). ## Example usage diff --git a/website/docs/language/resources/provisioners/habitat.html.md b/website/docs/language/resources/provisioners/habitat.mdx similarity index 94% rename from website/docs/language/resources/provisioners/habitat.html.md rename to website/docs/language/resources/provisioners/habitat.mdx index 66af5a655..c8ab535d1 100644 --- a/website/docs/language/resources/provisioners/habitat.html.md +++ b/website/docs/language/resources/provisioners/habitat.mdx @@ -1,22 +1,21 @@ --- -layout: "language" -page_title: "Provisioner: habitat" -sidebar_current: "docs-provisioners-habitat" -description: |- - The `habitat` provisioner installs the Habitat supervisor, and loads configured services. +page_title: 'Provisioner: habitat' +description: >- + The `habitat` provisioner installs the Habitat supervisor, and loads + configured services. --- # Habitat Provisioner The `habitat` provisioner installs the [Habitat](https://habitat.sh) supervisor and loads configured services. This provisioner only supports Linux targets using the `ssh` connection type at this time. -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](./). +!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). ## Requirements The `habitat` provisioner has some prerequisites for specific connection types: -- For `ssh` type connections, we assume a few tools to be available on the remote host: +* For `ssh` type connections, we assume a few tools to be available on the remote host: * `curl` * `tee` * `setsid` - Only if using the `unmanaged` service type. @@ -50,6 +49,7 @@ resource "aws_instance" "redis" { There are 2 configuration levels, `supervisor` and `service`. Configuration placed directly within the `provisioner` block are supervisor configurations, and a provisioner can define zero or more services to run, and each service will have a `service` block within the `provisioner`. A `service` block can also contain zero or more `bind` blocks to create service group bindings. ### Supervisor Arguments + * `accept_license (bool)` - (Required) Set to true to accept [Habitat end user license agreement](https://www.chef.io/end-user-license-agreement/) * `version (string)` - (Optional) The Habitat version to install on the remote machine. If not specified, the latest available version is used. * `auto_update (bool)` - (Optional) If set to `true`, the supervisor will auto-update itself as soon as new releases are available on the specified `channel`. @@ -66,7 +66,7 @@ There are 2 configuration levels, `supervisor` and `service`. Configuration pla * `ring_key (string)` - (Optional) The name of the ring key for encrypting gossip ring communication (Defaults to no encryption) * `ring_key_content (string)` - (Optional) The key content. Only needed if using ring encryption and want the provisioner to take care of uploading and importing it. Easiest to source from a file (eg `ring_key_content = "${file("conf/foo-123456789.sym.key")}"`) (Defaults to none) * `ctl_secret (string)` - (Optional) Specify a secret to use (from `hab sup secret generate`) for control gateway communication between hab client(s) and the supervisor. (Defaults to none) -* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to https://bldr.habitat.sh) +* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to ) * `channel (string)` - (Optional) The release channel in the Builder service to use. (Defaults to `stable`) * `events (string)` - (Optional) Name of the service group running a Habitat EventSrv to forward Supervisor and service event data to. (Defaults to none) * `organization (string)` - (Optional) The organization that the Supervisor and it's subsequent services are part of. (Defaults to `default`) @@ -74,6 +74,7 @@ There are 2 configuration levels, `supervisor` and `service`. Configuration pla * `builder_auth_token (string)` - (Optional) The builder authorization token when using a private origin. (Defaults to none) ### Service Arguments + * `name (string)` - (Required) The Habitat package identifier of the service to run. (ie `core/haproxy` or `core/redis/3.2.4/20171002182640`) * `binds (array)` - (Optional) An array of bind specifications. (ie `binds = ["backend:nginx.default"]`) * `bind` - (Optional) An alternative way of declaring binds. This method can be easier to deal with when populating values from other values or variable inputs without having to do string interpolation. The following example is equivalent to `binds = ["backend:nginx.default"]`: @@ -85,12 +86,13 @@ bind { group = "default" } ``` + * `topology (string)` - (Optional) Topology to start service in. Possible values `standalone` or `leader`. (Defaults to `standalone`) * `strategy (string)` - (Optional) Update strategy to use. Possible values `at-once`, `rolling` or `none`. (Defaults to `none`) * `user_toml (string)` - (Optional) TOML formatted user configuration for the service. Easiest to source from a file (eg `user_toml = "${file("conf/redis.toml")}"`). (Defaults to none) * `channel (string)` - (Optional) The release channel in the Builder service to use. (Defaults to `stable`) * `group (string)` - (Optional) The service group to join. (Defaults to `default`) -* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to https://bldr.habitat.sh) +* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to ) * `application (string)` - (Optional) The application name. (Defaults to none) * `environment (string)` - (Optional) The environment name. (Defaults to none) * `service_key (string)` - (Optional) The key content of a service private key, if using service group encryption. Easiest to source from a file (eg `service_key = "${file("conf/redis.default@org-123456789.box.key")}"`) (Defaults to none) diff --git a/website/docs/language/resources/provisioners/index.html.md b/website/docs/language/resources/provisioners/index.html.md deleted file mode 100644 index 2a22e2dd2..000000000 --- a/website/docs/language/resources/provisioners/index.html.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: "language" -page_title: "Provisioners Overview - Configuration Language" -description: "Provisioners model specific actions on a local or remote machine to prepare servers or other infrastructure for service." ---- - -# Provisioners - -Provisioners can be used to model specific actions on the local machine or on a -remote machine in order to prepare servers or other infrastructure objects for -service. - diff --git a/website/docs/language/resources/provisioners/index.mdx b/website/docs/language/resources/provisioners/index.mdx new file mode 100644 index 000000000..badd56b09 --- /dev/null +++ b/website/docs/language/resources/provisioners/index.mdx @@ -0,0 +1,12 @@ +--- +page_title: Provisioners Overview - Configuration Language +description: >- + Provisioners model specific actions on a local or remote machine to prepare + servers or other infrastructure for service. +--- + +# Provisioners + +Provisioners can be used to model specific actions on the local machine or on a +remote machine in order to prepare servers or other infrastructure objects for +service. diff --git a/website/docs/language/resources/provisioners/local-exec.html.md b/website/docs/language/resources/provisioners/local-exec.mdx similarity index 83% rename from website/docs/language/resources/provisioners/local-exec.html.md rename to website/docs/language/resources/provisioners/local-exec.mdx index 1feded8c7..02eec0ef7 100644 --- a/website/docs/language/resources/provisioners/local-exec.html.md +++ b/website/docs/language/resources/provisioners/local-exec.mdx @@ -1,9 +1,9 @@ --- -layout: "language" -page_title: "Provisioner: local-exec" -sidebar_current: "docs-provisioners-local" -description: |- - The `local-exec` provisioner invokes a local executable after a resource is created. This invokes a process on the machine running Terraform, not on the resource. See the `remote-exec` provisioner to run commands on the resource. +page_title: 'Provisioner: local-exec' +description: >- + The `local-exec` provisioner invokes a local executable after a resource is + created. This invokes a process on the machine running Terraform, not on the + resource. See the `remote-exec` provisioner to run commands on the resource. --- # local-exec Provisioner @@ -11,7 +11,7 @@ description: |- The `local-exec` provisioner invokes a local executable after a resource is created. This invokes a process on the machine running Terraform, not on the resource. See the `remote-exec` -[provisioner](/docs/language/resources/provisioners/remote-exec.html) to run commands on the +[provisioner](/language/resources/provisioners/remote-exec) to run commands on the resource. Note that even though the resource will be fully created when the provisioner is @@ -20,7 +20,7 @@ system services such as `sshd` may not be started yet on compute resources. -> **Note:** Provisioners should only be used as a last resort. For most common situations there are better alternatives. For more information, see -[the main Provisioners page](./). +[the main Provisioners page](/language/resources/provisioners). ## Example usage @@ -45,7 +45,7 @@ The following arguments are supported: * `working_dir` - (Optional) If provided, specifies the working directory where `command` will be executed. It can be provided as a relative path to the - current working directory or as an absolute path. The directory must exist. + current working directory or as an absolute path. The directory must exist. * `interpreter` - (Optional) If provided, this is a list of interpreter arguments used to execute the command. The first argument is the diff --git a/website/docs/language/resources/provisioners/null_resource.html.md b/website/docs/language/resources/provisioners/null_resource.mdx similarity index 68% rename from website/docs/language/resources/provisioners/null_resource.html.md rename to website/docs/language/resources/provisioners/null_resource.mdx index 4d9f53712..3e7b3fd65 100644 --- a/website/docs/language/resources/provisioners/null_resource.html.md +++ b/website/docs/language/resources/provisioners/null_resource.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Provisioners Without a Resource" -sidebar_current: "docs-provisioners-null-resource" -description: "A null_resource allows you to configure provisioners that are not directly associated with a single existing resource." +page_title: Provisioners Without a Resource +description: >- + A null_resource allows you to configure provisioners that are not directly + associated with a single existing resource. --- # Provisioners Without a Resource @@ -14,8 +14,8 @@ resource, you can associate them with a `null_resource`. Instances of [`null_resource`][null] are treated like normal resources, but they don't do anything. Like with any other resource, you can configure -[provisioners](/docs/language/resources/provisioners/syntax.html) and [connection -details](/docs/language/resources/provisioners/connection.html) on a `null_resource`. You can also +[provisioners](/language/resources/provisioners/syntax) and [connection +details](/language/resources/provisioners/connection) on a `null_resource`. You can also use its `triggers` argument and any meta-arguments to control exactly where in the dependency graph its provisioners will run. @@ -54,6 +54,6 @@ resource "null_resource" "cluster" { In addition to meta-arguments supported by all resources, `null_resource` supports the following specific arguments: - * `triggers` - A map of values which should cause this set of provisioners to - re-run. Values are meant to be interpolated references to variables or - attributes of other resources. +- `triggers` - A map of values which should cause this set of provisioners to + re-run. Values are meant to be interpolated references to variables or + attributes of other resources. diff --git a/website/docs/language/resources/provisioners/puppet.html.md b/website/docs/language/resources/provisioners/puppet.mdx similarity index 93% rename from website/docs/language/resources/provisioners/puppet.html.md rename to website/docs/language/resources/provisioners/puppet.mdx index 0e5005256..e0894c271 100644 --- a/website/docs/language/resources/provisioners/puppet.html.md +++ b/website/docs/language/resources/provisioners/puppet.mdx @@ -1,18 +1,17 @@ --- -layout: "language" -page_title: "Provisioner: puppet" -sidebar_current: "docs-provisioners-puppet" -description: |- - The `puppet` provisioner installs, configures and runs the Puppet agent on a resource. +page_title: 'Provisioner: puppet' +description: >- + The `puppet` provisioner installs, configures and runs the Puppet agent on a + resource. --- # Puppet Provisioner The `puppet` provisioner installs, configures and runs the Puppet agent on a remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type -[connections](/docs/language/resources/provisioners/connection.html). +[connections](/language/resources/provisioners/connection). -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](./). +!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). ## Requirements @@ -76,7 +75,7 @@ The following arguments are supported: a certificate from the Puppet master CA (defaults to the FQDN of the resource). -* `extension_requests (map)` - (Optional) A map of [extension +* `extension_requests (map)` - (Optional) A map of [extension requests](https://puppet.com/docs/puppet/latest/ssl_attributes_extensions.html#concept-932) to be embedded in the certificate signing request before it is sent to the Puppet master CA and then transferred to the final certificate when the CSR diff --git a/website/docs/language/resources/provisioners/remote-exec.html.md b/website/docs/language/resources/provisioners/remote-exec.mdx similarity index 67% rename from website/docs/language/resources/provisioners/remote-exec.html.md rename to website/docs/language/resources/provisioners/remote-exec.mdx index 19e771989..4b4d94274 100644 --- a/website/docs/language/resources/provisioners/remote-exec.html.md +++ b/website/docs/language/resources/provisioners/remote-exec.mdx @@ -1,9 +1,11 @@ --- -layout: "language" -page_title: "Provisioner: remote-exec" -sidebar_current: "docs-provisioners-remote" -description: |- - The `remote-exec` provisioner invokes a script on a remote resource after it is created. This can be used to run a configuration management tool, bootstrap into a cluster, etc. To invoke a local process, see the `local-exec` provisioner instead. The `remote-exec` provisioner supports both `ssh` and `winrm` type connections. +page_title: 'Provisioner: remote-exec' +description: >- + The `remote-exec` provisioner invokes a script on a remote resource after it + is created. This can be used to run a configuration management tool, bootstrap + into a cluster, etc. To invoke a local process, see the `local-exec` + provisioner instead. The `remote-exec` provisioner supports both `ssh` and + `winrm` type connections. --- # remote-exec Provisioner @@ -11,13 +13,13 @@ description: |- The `remote-exec` provisioner invokes a script on a remote resource after it is created. This can be used to run a configuration management tool, bootstrap into a cluster, etc. To invoke a local process, see the `local-exec` -[provisioner](/docs/language/resources/provisioners/local-exec.html) instead. The `remote-exec` -provisioner requires a [connection](/docs/language/resources/provisioners/connection.html) +[provisioner](/language/resources/provisioners/local-exec) instead. The `remote-exec` +provisioner requires a [connection](/language/resources/provisioners/connection) and supports both `ssh` and `winrm`. -> **Note:** Provisioners should only be used as a last resort. For most common situations there are better alternatives. For more information, see -[the main Provisioners page](./). +[the main Provisioners page](/language/resources/provisioners). ## Example usage @@ -58,14 +60,14 @@ The following arguments are supported: that will be copied to the remote resource and then executed. They are executed in the order they are provided. This cannot be provided with `inline` or `script`. --> **Note:** Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/docs/language/resources/provisioners/syntax.html#failure-behavior) applies only to the final command in the list. In particular, with `on_failure = fail` (the default behaviour) earlier commands will be allowed to fail, and later commands will also execute. If this behaviour is not desired, consider using `"set -o errexit"` as the first command. +-> **Note:** Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/language/resources/provisioners/syntax#failure-behavior) applies only to the final command in the list. In particular, with `on_failure = fail` (the default behaviour) earlier commands will be allowed to fail, and later commands will also execute. If this behaviour is not desired, consider using `"set -o errexit"` as the first command. ## Script Arguments You cannot pass any arguments to scripts using the `script` or `scripts` arguments to this provisioner. If you want to specify arguments, upload the script with the -[file provisioner](/docs/language/resources/provisioners/file.html) +[file provisioner](/language/resources/provisioners/file) and then use `inline` to call it. Example: ```hcl diff --git a/website/docs/language/resources/provisioners/salt-masterless.html.md b/website/docs/language/resources/provisioners/salt-masterless.html.md deleted file mode 100644 index 6cdb4f326..000000000 --- a/website/docs/language/resources/provisioners/salt-masterless.html.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -layout: "language" -page_title: "Provisioner: salt-masterless" -sidebar_current: "docs-provisioners-salt-masterless" -description: |- - The salt-masterless Terraform provisioner provisions machines built by Terraform ---- - -# Salt Masterless Provisioner - -Type: `salt-masterless` - -The `salt-masterless` Terraform provisioner provisions machines built by Terraform -using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/docs/language/resources/provisioners/connection.html). - -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](./). - -## Requirements - -The `salt-masterless` provisioner has some prerequisites. `cURL` must be available on the remote host. - -## Example usage - -The example below is fully functional. - -```hcl - -provisioner "salt-masterless" { - "local_state_tree" = "/srv/salt" -} -``` - -## Argument Reference - -The reference of available configuration options is listed below. The only -required argument is the path to your local salt state tree. - -Optional: - -- `bootstrap_args` (string) - Arguments to send to the bootstrap script. Usage - is somewhat documented on - [github](https://github.com/saltstack/salt-bootstrap), but the [script - itself](https://github.com/saltstack/salt-bootstrap/blob/develop/bootstrap-salt.sh) - has more detailed usage instructions. By default, no arguments are sent to - the script. - -- `disable_sudo` (boolean) - By default, the bootstrap install command is prefixed with `sudo`. When using a - Docker builder, you will likely want to pass `true` since `sudo` is often not pre-installed. - -- `remote_pillar_roots` (string) - The path to your remote [pillar - roots](http://docs.saltstack.com/ref/configuration/master.html#pillar-configuration). - default: `/srv/pillar`. This option cannot be used with `minion_config`. - -- `remote_state_tree` (string) - The path to your remote [state - tree](http://docs.saltstack.com/ref/states/highstate.html#the-salt-state-tree). - default: `/srv/salt`. This option cannot be used with `minion_config`. - -- `local_pillar_roots` (string) - The path to your local [pillar - roots](http://docs.saltstack.com/ref/configuration/master.html#pillar-configuration). - This will be uploaded to the `remote_pillar_roots` on the remote. - -- `local_state_tree` (string) - The path to your local [state - tree](http://docs.saltstack.com/ref/states/highstate.html#the-salt-state-tree). - This will be uploaded to the `remote_state_tree` on the remote. - -- `custom_state` (string) - A state to be run instead of `state.highstate`. - Defaults to `state.highstate` if unspecified. - -- `minion_config_file` (string) - The path to your local [minion config - file](http://docs.saltstack.com/ref/configuration/minion.html). This will be - uploaded to the `/etc/salt` on the remote. This option overrides the - `remote_state_tree` or `remote_pillar_roots` options. - -- `skip_bootstrap` (boolean) - By default the salt provisioner runs [salt - bootstrap](https://github.com/saltstack/salt-bootstrap) to install salt. Set - this to true to skip this step. - -- `temp_config_dir` (string) - Where your local state tree will be copied - before moving to the `/srv/salt` directory. Default is `/tmp/salt`. - -- `no_exit_on_failure` (boolean) - Terraform will exit if the `salt-call` command - fails. Set this option to true to ignore Salt failures. - -- `log_level` (string) - Set the logging level for the `salt-call` run. - -- `salt_call_args` (string) - Additional arguments to pass directly to `salt-call`. See - [salt-call](https://docs.saltstack.com/ref/cli/salt-call.html) documentation for more - information. By default no additional arguments (besides the ones Terraform generates) - are passed to `salt-call`. - -- `salt_bin_dir` (string) - Path to the `salt-call` executable. Useful if it is not - on the PATH. diff --git a/website/docs/language/resources/provisioners/salt-masterless.mdx b/website/docs/language/resources/provisioners/salt-masterless.mdx new file mode 100644 index 000000000..d24532177 --- /dev/null +++ b/website/docs/language/resources/provisioners/salt-masterless.mdx @@ -0,0 +1,91 @@ +--- +page_title: 'Provisioner: salt-masterless' +description: >- + The salt-masterless Terraform provisioner provisions machines built by + Terraform +--- + +# Salt Masterless Provisioner + +Type: `salt-masterless` + +The `salt-masterless` Terraform provisioner provisions machines built by Terraform +using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection). + +!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). + +## Requirements + +The `salt-masterless` provisioner has some prerequisites. `cURL` must be available on the remote host. + +## Example usage + +The example below is fully functional. + +```hcl + +provisioner "salt-masterless" { + "local_state_tree" = "/srv/salt" +} +``` + +## Argument Reference + +The reference of available configuration options is listed below. The only +required argument is the path to your local salt state tree. + +Optional: + +- `bootstrap_args` (string) - Arguments to send to the bootstrap script. Usage + is somewhat documented on + [github](https://github.com/saltstack/salt-bootstrap), but the [script + itself](https://github.com/saltstack/salt-bootstrap/blob/develop/bootstrap-salt.sh) + has more detailed usage instructions. By default, no arguments are sent to + the script. + +- `disable_sudo` (boolean) - By default, the bootstrap install command is prefixed with `sudo`. When using a + Docker builder, you will likely want to pass `true` since `sudo` is often not pre-installed. + +- `remote_pillar_roots` (string) - The path to your remote [pillar + roots](http://docs.saltstack.com/ref/configuration/master.html#pillar-configuration). + default: `/srv/pillar`. This option cannot be used with `minion_config`. + +- `remote_state_tree` (string) - The path to your remote [state + tree](http://docs.saltstack.com/ref/states/highstate.html#the-salt-state-tree). + default: `/srv/salt`. This option cannot be used with `minion_config`. + +- `local_pillar_roots` (string) - The path to your local [pillar + roots](http://docs.saltstack.com/ref/configuration/master.html#pillar-configuration). + This will be uploaded to the `remote_pillar_roots` on the remote. + +- `local_state_tree` (string) - The path to your local [state + tree](http://docs.saltstack.com/ref/states/highstate.html#the-salt-state-tree). + This will be uploaded to the `remote_state_tree` on the remote. + +- `custom_state` (string) - A state to be run instead of `state.highstate`. + Defaults to `state.highstate` if unspecified. + +- `minion_config_file` (string) - The path to your local [minion config + file](http://docs.saltstack.com/ref/configuration/minion.html). This will be + uploaded to the `/etc/salt` on the remote. This option overrides the + `remote_state_tree` or `remote_pillar_roots` options. + +- `skip_bootstrap` (boolean) - By default the salt provisioner runs [salt + bootstrap](https://github.com/saltstack/salt-bootstrap) to install salt. Set + this to true to skip this step. + +- `temp_config_dir` (string) - Where your local state tree will be copied + before moving to the `/srv/salt` directory. Default is `/tmp/salt`. + +- `no_exit_on_failure` (boolean) - Terraform will exit if the `salt-call` command + fails. Set this option to true to ignore Salt failures. + +- `log_level` (string) - Set the logging level for the `salt-call` run. + +- `salt_call_args` (string) - Additional arguments to pass directly to `salt-call`. See + [salt-call](https://docs.saltstack.com/ref/cli/salt-call.html) documentation for more + information. By default no additional arguments (besides the ones Terraform generates) + are passed to `salt-call`. + +- `salt_bin_dir` (string) - Path to the `salt-call` executable. Useful if it is not + on the PATH. diff --git a/website/docs/language/resources/provisioners/syntax.html.md b/website/docs/language/resources/provisioners/syntax.mdx similarity index 93% rename from website/docs/language/resources/provisioners/syntax.html.md rename to website/docs/language/resources/provisioners/syntax.mdx index 0ba9d9d00..421e5d2ee 100644 --- a/website/docs/language/resources/provisioners/syntax.html.md +++ b/website/docs/language/resources/provisioners/syntax.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Provisioners" -sidebar_current: "docs-provisioners" -description: "Provisioners run scripts on a local or remote machine during resource creation or destruction. Learn how to declare provisioners in a configuration." +page_title: Provisioners +description: >- + Provisioners run scripts on a local or remote machine during resource creation + or destruction. Learn how to declare provisioners in a configuration. --- # Provisioners @@ -161,7 +161,7 @@ resource "aws_instance" "web" { The `local-exec` provisioner requires no other configuration, but most other provisioners must connect to the remote system using SSH or WinRM. -You must include [a `connection` block](./connection.html) so that Terraform +You must include [a `connection` block](/language/resources/provisioners/connection) so that Terraform will know how to communicate with the server. Terraform includes several built-in provisioners; use the navigation sidebar to @@ -193,8 +193,8 @@ block would create a dependency cycle. ## Suppressing Provisioner Logs in CLI Output The configuration for a `provisioner` block may use sensitive values, such as -[`sensitive` variables](/docs/language/values/variables.html#suppressing-values-in-cli-output) or -[`sensitive` output values](/docs/language/values/outputs.html#sensitive-suppressing-values-in-cli-output). +[`sensitive` variables](/language/values/variables#suppressing-values-in-cli-output) or +[`sensitive` output values](/language/values/outputs#sensitive-suppressing-values-in-cli-output). In this case, all log output from the provisioner is automatically suppressed to prevent the sensitive values from being displayed. @@ -236,8 +236,10 @@ fail, Terraform will error and rerun the provisioners again on the next `terraform apply`. Due to this behavior, care should be taken for destroy provisioners to be safe to run multiple times. - Destroy provisioners of this resource will not run if `create_before_destroy` - is set to `true`. We may address this in the future, and this [GitHub issue](https://github.com/hashicorp/terraform/issues/13549) contains more details. +``` +Destroy provisioners of this resource will not run if `create_before_destroy` +is set to `true`. We may address this in the future, and this [GitHub issue](https://github.com/hashicorp/terraform/issues/13549) contains more details. +``` Destroy-time provisioners can only run if they remain in the configuration at the time a resource is destroyed. If a resource block with a destroy-time @@ -288,10 +290,10 @@ By default, provisioners that fail will also cause the Terraform apply itself to fail. The `on_failure` setting can be used to change this. The allowed values are: -- `continue` - Ignore the error and continue with creation or destruction. +* `continue` - Ignore the error and continue with creation or destruction. -- `fail` - Raise an error and stop applying (the default behavior). If this is a creation provisioner, - taint the resource. +* `fail` - Raise an error and stop applying (the default behavior). If this is a creation provisioner, + taint the resource. Example: diff --git a/website/docs/language/resources/syntax.html.md b/website/docs/language/resources/syntax.mdx similarity index 83% rename from website/docs/language/resources/syntax.html.md rename to website/docs/language/resources/syntax.mdx index 456e93779..259981bfb 100644 --- a/website/docs/language/resources/syntax.html.md +++ b/website/docs/language/resources/syntax.mdx @@ -1,8 +1,9 @@ --- -layout: "language" -page_title: "Resources - Configuration Language" -sidebar_current: "docs-config-resources" -description: "Resources correspond to infrastructure objects like virtual networks or compute instances. Learn about resource types, syntax, behavior, and arguments." +page_title: Resources - Configuration Language +description: >- + Resources correspond to infrastructure objects like virtual networks or + compute instances. Learn about resource types, syntax, behavior, and + arguments. --- # Resource Blocks @@ -52,7 +53,7 @@ attributes the resource supports. ### Providers -Each resource type is implemented by a [provider](/docs/language/providers/requirements.html), +Each resource type is implemented by a [provider](/language/providers/requirements), which is a plugin for Terraform that offers a collection of resource types. A provider usually provides resources to manage a single cloud or on-premises infrastructure platform. Providers are distributed separately from Terraform @@ -65,16 +66,16 @@ access their remote APIs, and the root module must provide that configuration. For more information, see: -- [Provider Requirements](/docs/language/providers/requirements.html), for declaring which +- [Provider Requirements](/language/providers/requirements), for declaring which providers a module uses. -- [Provider Configuration](/docs/language/providers/configuration.html), for configuring provider settings. +- [Provider Configuration](/language/providers/configuration), for configuring provider settings. Terraform usually automatically determines which provider to use based on a resource type's name. (By convention, resource type names start with their provider's preferred local name.) When using multiple configurations of a provider (or non-preferred local provider names), you must use the `provider` meta-argument to manually choose an alternate provider configuration. See -[the `provider` meta-argument](/docs/language/meta-arguments/resource-provider.html) for more details. +[the `provider` meta-argument](/language/meta-arguments/resource-provider) for more details. ### Resource Arguments @@ -83,7 +84,7 @@ selected resource type. The resource type's documentation lists which arguments are available and how their values should be formatted. The values for resource arguments can make full use of -[expressions](/docs/language/expressions/index.html) and other dynamic Terraform +[expressions](/language/expressions) and other dynamic Terraform language features. There are also some _meta-arguments_ that are defined by Terraform itself @@ -114,7 +115,7 @@ public provider docs. For more information about how Terraform manages resources when applying a configuration, see -[Resource Behavior](/docs/language/resources/behavior.html). +[Resource Behavior](/language/resources/behavior). ## Meta-Arguments @@ -123,12 +124,12 @@ any resource type to change the behavior of resources. The following meta-arguments are documented on separate pages: -- [`depends_on`, for specifying hidden dependencies](/docs/language/meta-arguments/depends_on.html) -- [`count`, for creating multiple resource instances according to a count](/docs/language/meta-arguments/count.html) -- [`for_each`, to create multiple instances according to a map, or set of strings](/docs/language/meta-arguments/for_each.html) -- [`provider`, for selecting a non-default provider configuration](/docs/language/meta-arguments/resource-provider.html) -- [`lifecycle`, for lifecycle customizations](/docs/language/meta-arguments/lifecycle.html) -- [`provisioner` and `connection`, for taking extra actions after resource creation](/docs/language/resources/provisioners/index.html) +- [`depends_on`, for specifying hidden dependencies](/language/meta-arguments/depends_on) +- [`count`, for creating multiple resource instances according to a count](/language/meta-arguments/count) +- [`for_each`, to create multiple instances according to a map, or set of strings](/language/meta-arguments/for_each) +- [`provider`, for selecting a non-default provider configuration](/language/meta-arguments/resource-provider) +- [`lifecycle`, for lifecycle customizations](/language/meta-arguments/lifecycle) +- [`provisioner` and `connection`, for taking extra actions after resource creation](/language/resources/provisioners) ## Operation Timeouts diff --git a/website/docs/language/settings/backends/artifactory.html.md b/website/docs/language/settings/backends/artifactory.mdx similarity index 63% rename from website/docs/language/settings/backends/artifactory.html.md rename to website/docs/language/settings/backends/artifactory.mdx index d3cdf789f..cca3e82b2 100644 --- a/website/docs/language/settings/backends/artifactory.html.md +++ b/website/docs/language/settings/backends/artifactory.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Backend Type: artifactory" -sidebar_current: "docs-backends-types-standard-artifactory" -description: |- - Terraform can store state in artifactory. +page_title: 'Backend Type: artifactory' +description: Terraform can store state in artifactory. --- # artifactory @@ -17,7 +14,7 @@ configurations may be kept at different subpaths within the repository. -> **Note:** The URL must include the path to the Artifactory installation. It will likely end in `/artifactory`. -This backend does **not** support [state locking](/docs/language/state/locking.html). +This backend does **not** support [state locking](/language/state/locking). ## Example Configuration @@ -52,8 +49,8 @@ data "terraform_remote_state" "foo" { The following configuration options / environment variables are supported: - * `username` / `ARTIFACTORY_USERNAME` (Required) - The username - * `password` / `ARTIFACTORY_PASSWORD` (Required) - The password - * `url` / `ARTIFACTORY_URL` (Required) - The URL. Note that this is the base url to artifactory not the full repo and subpath. - * `repo` (Required) - The repository name - * `subpath` (Required) - Path within the repository +- `username` / `ARTIFACTORY_USERNAME` (Required) - The username +- `password` / `ARTIFACTORY_PASSWORD` (Required) - The password +- `url` / `ARTIFACTORY_URL` (Required) - The URL. Note that this is the base url to artifactory not the full repo and subpath. +- `repo` (Required) - The repository name +- `subpath` (Required) - Path within the repository diff --git a/website/docs/language/settings/backends/azurerm.html.md b/website/docs/language/settings/backends/azurerm.mdx similarity index 96% rename from website/docs/language/settings/backends/azurerm.html.md rename to website/docs/language/settings/backends/azurerm.mdx index 8e0f951a8..0539f9ddf 100644 --- a/website/docs/language/settings/backends/azurerm.html.md +++ b/website/docs/language/settings/backends/azurerm.mdx @@ -1,10 +1,6 @@ --- -layout: "language" -page_title: "Backend Type: azurerm" -sidebar_current: "docs-backends-types-standard-azurerm" -description: |- - Terraform can store state remotely in Azure Blob Storage. - +page_title: 'Backend Type: azurerm' +description: Terraform can store state remotely in Azure Blob Storage. --- # azurerm @@ -13,7 +9,7 @@ Stores the state as a Blob with the given Key within the Blob Container within [ This backend supports state locking and consistency checking with Azure Blob Storage native capabilities. --> **Note:** By default the Azure Backend uses ADAL for authentication which is deprecated in favour of MSAL - MSAL can be used by setting `use_microsoft_graph` to `true`. **The default for this will change in Terraform 1.2**, so that MSAL authentication is used by default. +-> **Note:** By default the Azure Backend uses ADAL for authentication which is deprecated in favour of MSAL - MSAL can be used by setting `use_microsoft_graph` to `true`. **The default for this will change in Terraform 1.2**, so that MSAL authentication is used by default. ## Example Configuration @@ -30,7 +26,7 @@ terraform { } ``` ---- +*** When authenticating using Managed Service Identity (MSI): @@ -48,7 +44,7 @@ terraform { } ``` ---- +*** When authenticating using Azure AD Authentication: @@ -67,7 +63,7 @@ terraform { -> **Note:** When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned. ---- +*** When authenticating using the Access Key associated with the Storage Account: @@ -85,7 +81,7 @@ terraform { } ``` ---- +*** When authenticating using a SAS Token associated with the Storage Account: @@ -103,7 +99,7 @@ terraform { } ``` --> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/docs/language/settings/backends/configuration.html#partial-configuration) for the credentials. +-> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/language/settings/backends/configuration#partial-configuration) for the credentials. ## Data Source Configuration @@ -120,7 +116,7 @@ data "terraform_remote_state" "foo" { } ``` ---- +*** When authenticating using Managed Service Identity (MSI): @@ -139,7 +135,7 @@ data "terraform_remote_state" "foo" { } ``` ---- +*** When authenticating using AzureAD Authentication: @@ -159,7 +155,7 @@ data "terraform_remote_state" "foo" { -> **Note:** When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned. ---- +*** When authenticating using the Access Key associated with the Storage Account: @@ -178,7 +174,7 @@ data "terraform_remote_state" "foo" { } ``` ---- +*** When authenticating using a SAS Token associated with the Storage Account: @@ -215,14 +211,16 @@ The following configuration options are supported: * `snapshot` - (Optional) Should the Blob used to store the Terraform Statefile be snapshotted before use? Defaults to `false`. This value can also be sourced from the `ARM_SNAPSHOT` environment variable. ---- +*** When authenticating using the Managed Service Identity (MSI) - the following fields are also supported: * `resource_group_name` - (Required) The Name of the Resource Group in which the Storage Account exists. * `msi_endpoint` - (Optional) The path to a custom Managed Service Identity endpoint which is automatically determined if not specified. This can also be sourced from the `ARM_MSI_ENDPOINT` environment variable. -* + +* + * `subscription_id` - (Optional) The Subscription ID in which the Storage Account exists. This can also be sourced from the `ARM_SUBSCRIPTION_ID` environment variable. * `tenant_id` - (Optional) The Tenant ID in which the Subscription exists. This can also be sourced from the `ARM_TENANT_ID` environment variable. @@ -233,19 +231,19 @@ When authenticating using the Managed Service Identity (MSI) - the following fie * `use_msi` - (Optional) Should Managed Service Identity authentication be used? This can also be sourced from the `ARM_USE_MSI` environment variable. ---- +*** When authenticating using a SAS Token associated with the Storage Account - the following fields are also supported: * `sas_token` - (Optional) The SAS Token used to access the Blob Storage Account. This can also be sourced from the `ARM_SAS_TOKEN` environment variable. ---- +*** When authenticating using the Storage Account's Access Key - the following fields are also supported: * `access_key` - (Optional) The Access Key used to access the Blob Storage Account. This can also be sourced from the `ARM_ACCESS_KEY` environment variable. ---- +*** When authenticating using AzureAD Authentication - the following fields are also supported: @@ -257,7 +255,7 @@ When authenticating using AzureAD Authentication - the following fields are also -> **Note:** By default the Azure Backend uses ADAL for authentication which is deprecated in favour of MSAL - MSAL can be used by setting `use_microsoft_graph` to `true`. **The default for this will change in Terraform 1.2**, so that MSAL authentication is used by default. ---- +*** When authenticating using a Service Principal with a Client Certificate - the following fields are also supported: @@ -277,7 +275,7 @@ When authenticating using a Service Principal with a Client Certificate - the fo -> **Note:** By default the Azure Backend uses ADAL for authentication which is deprecated in favour of MSAL - MSAL can be used by setting `use_microsoft_graph` to `true`. **The default for this will change in Terraform 1.2**, so that MSAL authentication is used by default. ---- +*** When authenticating using a Service Principal with a Client Secret - the following fields are also supported: diff --git a/website/docs/language/settings/backends/configuration.html.md b/website/docs/language/settings/backends/configuration.mdx similarity index 81% rename from website/docs/language/settings/backends/configuration.html.md rename to website/docs/language/settings/backends/configuration.mdx index e7286f5bf..79f118672 100644 --- a/website/docs/language/settings/backends/configuration.html.md +++ b/website/docs/language/settings/backends/configuration.mdx @@ -1,15 +1,14 @@ --- -layout: "language" -page_title: "Backend Configuration - Configuration Language" +page_title: Backend Configuration - Configuration Language --- # Backend Configuration Each Terraform configuration can specify a backend, which defines where -[state](/docs/language/state/index.html) snapshots are stored. +[state](/language/state) snapshots are stored. You do not need to configure a backend when using Terraform Cloud because -Terraform Cloud automatically manages state in the workspaces associated with your configuration. If your configuration includes [a `cloud` block](/docs/language/settings/terraform-cloud.html), it cannot include a `backend` block. +Terraform Cloud automatically manages state in the workspaces associated with your configuration. If your configuration includes [a `cloud` block](/language/settings/terraform-cloud), it cannot include a `backend` block. Most non-trivial Terraform configurations store state remotely so that multiple people can work with the same infrastructure. @@ -73,25 +72,25 @@ automatically by an automation script running Terraform. When some or all of the arguments are omitted, we call this a _partial configuration_. With a partial configuration, the remaining configuration arguments must be -provided as part of [the initialization process](/docs/cli/init/index.html). +provided as part of [the initialization process](/cli/init). There are several ways to supply the remaining arguments: - * **File**: A configuration file may be specified via the `init` command line. - To specify a file, use the `-backend-config=PATH` option when running - `terraform init`. If the file contains secrets it may be kept in - a secure data store, such as [Vault](https://www.vaultproject.io/), - in which case it must be downloaded to the local disk before running Terraform. +- **File**: A configuration file may be specified via the `init` command line. + To specify a file, use the `-backend-config=PATH` option when running + `terraform init`. If the file contains secrets it may be kept in + a secure data store, such as [Vault](https://www.vaultproject.io/), + in which case it must be downloaded to the local disk before running Terraform. - * **Command-line key/value pairs**: Key/value pairs can be specified via the - `init` command line. Note that many shells retain command-line flags in a - history file, so this isn't recommended for secrets. To specify a single - key/value pair, use the `-backend-config="KEY=VALUE"` option when running - `terraform init`. +- **Command-line key/value pairs**: Key/value pairs can be specified via the + `init` command line. Note that many shells retain command-line flags in a + history file, so this isn't recommended for secrets. To specify a single + key/value pair, use the `-backend-config="KEY=VALUE"` option when running + `terraform init`. - * **Interactively**: Terraform will interactively ask you for the required - values, unless interactive input is disabled. Terraform will not prompt for - optional values. +- **Interactively**: Terraform will interactively ask you for the required + values, unless interactive input is disabled. Terraform will not prompt for + optional values. If backend settings are provided in multiple locations, the top-level settings are merged such that any command-line options override the settings @@ -156,12 +155,12 @@ both the configuration itself as well as the type of backend (for example from "consul" to "s3"). Terraform will automatically detect any changes in your configuration -and request a [reinitialization](/docs/cli/init/index.html). As part of +and request a [reinitialization](/cli/init). As part of the reinitialization process, Terraform will ask if you'd like to migrate your existing state to the new configuration. This allows you to easily switch from one backend to another. -If you're using multiple [workspaces](/docs/language/state/workspaces.html), +If you're using multiple [workspaces](/language/state/workspaces), Terraform can copy all workspaces to the destination. If Terraform detects you have multiple workspaces, it will ask if this is what you want to do. @@ -172,7 +171,7 @@ want to migrate your state. You can respond "no" in this scenario. If you no longer want to use any backend, you can simply remove the configuration from the file. Terraform will detect this like any other -change and prompt you to [reinitialize](/docs/cli/init/index.html). +change and prompt you to [reinitialize](/cli/init). As part of the reinitialization, Terraform will ask if you'd like to migrate your state back down to normal local state. Once this is complete then diff --git a/website/docs/language/settings/backends/consul.html.md b/website/docs/language/settings/backends/consul.html.md deleted file mode 100644 index dcb21df88..000000000 --- a/website/docs/language/settings/backends/consul.html.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -layout: "language" -page_title: "Backend Type: consul" -sidebar_current: "docs-backends-types-standard-consul" -description: |- - Terraform can store state in Consul. ---- - -# consul - -Stores the state in the [Consul](https://www.consul.io/) KV store at a given path. - -This backend supports [state locking](/docs/language/state/locking.html). - -## Example Configuration - -```hcl -terraform { - backend "consul" { - address = "consul.example.com" - scheme = "https" - path = "full/path" - } -} -``` - -Note that for the access credentials we recommend using a -[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). - -## Data Source Configuration - -```hcl -data "terraform_remote_state" "foo" { - backend = "consul" - config = { - path = "full/path" - } -} -``` - -## Configuration variables - -The following configuration options / environment variables are supported: - - * `path` - (Required) Path in the Consul KV store - * `access_token` / `CONSUL_HTTP_TOKEN` - (Required) Access token - * `address` / `CONSUL_HTTP_ADDR` - (Optional) DNS name and port of your Consul endpoint specified in the - format `dnsname:port`. Defaults to the local agent HTTP listener. - * `scheme` - (Optional) Specifies what protocol to use when talking to the given - `address`, either `http` or `https`. SSL support can also be triggered - by setting then environment variable `CONSUL_HTTP_SSL` to `true`. - * `datacenter` - (Optional) The datacenter to use. Defaults to that of the agent. - * `http_auth` / `CONSUL_HTTP_AUTH` - (Optional) HTTP Basic Authentication credentials to be used when - communicating with Consul, in the format of either `user` or `user:pass`. - * `gzip` - (Optional) `true` to compress the state data using gzip, or `false` (the default) to leave it uncompressed. - * `lock` - (Optional) `false` to disable locking. This defaults to true, but will require session permissions with Consul and at least kv write permissions on `$path/.lock` to perform locking. - * `ca_file` / `CONSUL_CACERT` - (Optional) A path to a PEM-encoded certificate authority used to verify the remote agent's certificate. - * `cert_file` / `CONSUL_CLIENT_CERT` - (Optional) A path to a PEM-encoded certificate provided to the remote agent; requires use of `key_file`. - * `key_file` / `CONSUL_CLIENT_KEY` - (Optional) A path to a PEM-encoded private key, required if `cert_file` is specified. diff --git a/website/docs/language/settings/backends/consul.mdx b/website/docs/language/settings/backends/consul.mdx new file mode 100644 index 000000000..f003b7851 --- /dev/null +++ b/website/docs/language/settings/backends/consul.mdx @@ -0,0 +1,56 @@ +--- +page_title: 'Backend Type: consul' +description: Terraform can store state in Consul. +--- + +# consul + +Stores the state in the [Consul](https://www.consul.io/) KV store at a given path. + +This backend supports [state locking](/language/state/locking). + +## Example Configuration + +```hcl +terraform { + backend "consul" { + address = "consul.example.com" + scheme = "https" + path = "full/path" + } +} +``` + +Note that for the access credentials we recommend using a +[partial configuration](/language/settings/backends/configuration#partial-configuration). + +## Data Source Configuration + +```hcl +data "terraform_remote_state" "foo" { + backend = "consul" + config = { + path = "full/path" + } +} +``` + +## Configuration variables + +The following configuration options / environment variables are supported: + +- `path` - (Required) Path in the Consul KV store +- `access_token` / `CONSUL_HTTP_TOKEN` - (Required) Access token +- `address` / `CONSUL_HTTP_ADDR` - (Optional) DNS name and port of your Consul endpoint specified in the + format `dnsname:port`. Defaults to the local agent HTTP listener. +- `scheme` - (Optional) Specifies what protocol to use when talking to the given + `address`, either `http` or `https`. SSL support can also be triggered + by setting then environment variable `CONSUL_HTTP_SSL` to `true`. +- `datacenter` - (Optional) The datacenter to use. Defaults to that of the agent. +- `http_auth` / `CONSUL_HTTP_AUTH` - (Optional) HTTP Basic Authentication credentials to be used when + communicating with Consul, in the format of either `user` or `user:pass`. +- `gzip` - (Optional) `true` to compress the state data using gzip, or `false` (the default) to leave it uncompressed. +- `lock` - (Optional) `false` to disable locking. This defaults to true, but will require session permissions with Consul and at least kv write permissions on `$path/.lock` to perform locking. +- `ca_file` / `CONSUL_CACERT` - (Optional) A path to a PEM-encoded certificate authority used to verify the remote agent's certificate. +- `cert_file` / `CONSUL_CLIENT_CERT` - (Optional) A path to a PEM-encoded certificate provided to the remote agent; requires use of `key_file`. +- `key_file` / `CONSUL_CLIENT_KEY` - (Optional) A path to a PEM-encoded private key, required if `cert_file` is specified. diff --git a/website/docs/language/settings/backends/cos.html.md b/website/docs/language/settings/backends/cos.mdx similarity index 51% rename from website/docs/language/settings/backends/cos.html.md rename to website/docs/language/settings/backends/cos.mdx index 4e8772f91..548c569cd 100644 --- a/website/docs/language/settings/backends/cos.html.md +++ b/website/docs/language/settings/backends/cos.mdx @@ -1,16 +1,15 @@ --- -layout: "language" -page_title: "Backend Type: cos" -sidebar_current: "docs-backends-types-standard-cos" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. +page_title: 'Backend Type: cos' +description: >- + Terraform can store the state remotely, making it easier to version and work + with in a team. --- # COS Stores the state as an object in a configurable prefix in a given bucket on [Tencent Cloud Object Storage](https://intl.cloud.tencent.com/product/cos) (COS). -This backend supports [state locking](/docs/language/state/locking.html). +This backend supports [state locking](/language/state/locking). ~> **Warning!** It is highly recommended that you enable [Object Versioning](https://intl.cloud.tencent.com/document/product/436/19883) on the COS bucket to allow for state recovery in the case of accidental deletions and human error. @@ -32,7 +31,7 @@ Terraform state will be written into the file `terraform/state/terraform.tfstate ## Data Source Configuration -To make use of the COS remote state in another configuration, use the [`terraform_remote_state` data source](/docs/language/state/remote-state-data.html). +To make use of the COS remote state in another configuration, use the [`terraform_remote_state` data source](/language/state/remote-state-data). ```hcl data "terraform_remote_state" "foo" { @@ -50,11 +49,11 @@ data "terraform_remote_state" "foo" { The following configuration options or environment variables are supported: - * `secret_id` - (Optional) Secret id of Tencent Cloud. It supports environment variables `TENCENTCLOUD_SECRET_ID`. - * `secret_key` - (Optional) Secret key of Tencent Cloud. It supports environment variables `TENCENTCLOUD_SECRET_KEY`. - * `region` - (Optional) The region of the COS bucket. It supports environment variables `TENCENTCLOUD_REGION`. - * `bucket` - (Required) The name of the COS bucket. You shall manually create it first. - * `prefix` - (Optional) The directory for saving the state file in bucket. Default to "env:". - * `key` - (Optional) The path for saving the state file in bucket. Defaults to `terraform.tfstate`. - * `encrypt` - (Optional) Whether to enable server side encryption of the state file. If it is true, COS will use 'AES256' encryption algorithm to encrypt state file. - * `acl` - (Optional) Object ACL to be applied to the state file, allows `private` and `public-read`. Defaults to `private`. +- `secret_id` - (Optional) Secret id of Tencent Cloud. It supports environment variables `TENCENTCLOUD_SECRET_ID`. +- `secret_key` - (Optional) Secret key of Tencent Cloud. It supports environment variables `TENCENTCLOUD_SECRET_KEY`. +- `region` - (Optional) The region of the COS bucket. It supports environment variables `TENCENTCLOUD_REGION`. +- `bucket` - (Required) The name of the COS bucket. You shall manually create it first. +- `prefix` - (Optional) The directory for saving the state file in bucket. Default to "env:". +- `key` - (Optional) The path for saving the state file in bucket. Defaults to `terraform.tfstate`. +- `encrypt` - (Optional) Whether to enable server side encryption of the state file. If it is true, COS will use 'AES256' encryption algorithm to encrypt state file. +- `acl` - (Optional) Object ACL to be applied to the state file, allows `private` and `public-read`. Defaults to `private`. diff --git a/website/docs/language/settings/backends/etcd.html.md b/website/docs/language/settings/backends/etcd.mdx similarity index 55% rename from website/docs/language/settings/backends/etcd.html.md rename to website/docs/language/settings/backends/etcd.mdx index 771b74d72..8495e72f5 100644 --- a/website/docs/language/settings/backends/etcd.html.md +++ b/website/docs/language/settings/backends/etcd.mdx @@ -1,16 +1,13 @@ --- -layout: "language" -page_title: "Backend Type: etcd" -sidebar_current: "docs-backends-types-standard-etcdv2" -description: |- - Terraform can store state remotely in etcd 2.x. +page_title: 'Backend Type: etcd' +description: Terraform can store state remotely in etcd 2.x. --- # etcd Stores the state in [etcd 2.x](https://coreos.com/etcd/docs/latest/v2/README.html) at a given path. -This backend does **not** support [state locking](/docs/language/state/locking.html). +This backend does **not** support [state locking](/language/state/locking). ## Example Configuration @@ -39,7 +36,7 @@ data "terraform_remote_state" "foo" { The following configuration options are supported: - * `path` - (Required) The path where to store the state - * `endpoints` - (Required) A space-separated list of the etcd endpoints - * `username` - (Optional) The username - * `password` - (Optional) The password +- `path` - (Required) The path where to store the state +- `endpoints` - (Required) A space-separated list of the etcd endpoints +- `username` - (Optional) The username +- `password` - (Optional) The password diff --git a/website/docs/language/settings/backends/etcdv3.html.md b/website/docs/language/settings/backends/etcdv3.html.md deleted file mode 100644 index 478f79d2c..000000000 --- a/website/docs/language/settings/backends/etcdv3.html.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -layout: "language" -page_title: "Backend Type: etcdv3" -sidebar_current: "docs-backends-types-standard-etcdv3" -description: |- - Terraform can store state remotely in etcd 3.x. ---- - -# etcdv3 - -Stores the state in the [etcd](https://etcd.io/) KV store with a given prefix. - -This backend supports [state locking](/docs/language/state/locking.html). - -## Example Configuration - -```hcl -terraform { - backend "etcdv3" { - endpoints = ["etcd-1:2379", "etcd-2:2379", "etcd-3:2379"] - lock = true - prefix = "terraform-state/" - } -} -``` - -Note that for the access credentials we recommend using a -[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). - -## Data Source Configuration - -```hcl -data "terraform_remote_state" "foo" { - backend = "etcdv3" - config = { - endpoints = ["etcd-1:2379", "etcd-2:2379", "etcd-3:2379"] - lock = true - prefix = "terraform-state/" - } -} -``` - -## Configuration variables - -The following configuration options / environment variables are supported: - - * `endpoints` - (Required) The list of 'etcd' endpoints which to connect to. - * `username` / `ETCDV3_USERNAME` - (Optional) Username used to connect to the etcd cluster. - * `password` / `ETCDV3_PASSWORD` - (Optional) Password used to connect to the etcd cluster. - * `prefix` - (Optional) An optional prefix to be added to keys when to storing state in etcd. Defaults to `""`. - * `lock` - (Optional) Whether to lock state access. Defaults to `true`. - * `cacert_path` - (Optional) The path to a PEM-encoded CA bundle with which to verify certificates of TLS-enabled etcd servers. - * `cert_path` - (Optional) The path to a PEM-encoded certificate to provide to etcd for secure client identification. - * `key_path` - (Optional) The path to a PEM-encoded key to provide to etcd for secure client identification. - * `max_request_bytes` - (Optional) The max request size to send to etcd. This can be increased to enable storage of larger state. You must set the corresponding server-side flag [--max-request-bytes](https://etcd.io/docs/current/dev-guide/limit/#request-size-limit) as well and the value should be less than the client setting. Defaults to `2097152` (2.0 MiB). **Please Note:** Increasing etcd's request size limit may negatively impact overall latency. diff --git a/website/docs/language/settings/backends/etcdv3.mdx b/website/docs/language/settings/backends/etcdv3.mdx new file mode 100644 index 000000000..2196c164c --- /dev/null +++ b/website/docs/language/settings/backends/etcdv3.mdx @@ -0,0 +1,52 @@ +--- +page_title: 'Backend Type: etcdv3' +description: Terraform can store state remotely in etcd 3.x. +--- + +# etcdv3 + +Stores the state in the [etcd](https://etcd.io/) KV store with a given prefix. + +This backend supports [state locking](/language/state/locking). + +## Example Configuration + +```hcl +terraform { + backend "etcdv3" { + endpoints = ["etcd-1:2379", "etcd-2:2379", "etcd-3:2379"] + lock = true + prefix = "terraform-state/" + } +} +``` + +Note that for the access credentials we recommend using a +[partial configuration](/language/settings/backends/configuration#partial-configuration). + +## Data Source Configuration + +```hcl +data "terraform_remote_state" "foo" { + backend = "etcdv3" + config = { + endpoints = ["etcd-1:2379", "etcd-2:2379", "etcd-3:2379"] + lock = true + prefix = "terraform-state/" + } +} +``` + +## Configuration variables + +The following configuration options / environment variables are supported: + +- `endpoints` - (Required) The list of 'etcd' endpoints which to connect to. +- `username` / `ETCDV3_USERNAME` - (Optional) Username used to connect to the etcd cluster. +- `password` / `ETCDV3_PASSWORD` - (Optional) Password used to connect to the etcd cluster. +- `prefix` - (Optional) An optional prefix to be added to keys when to storing state in etcd. Defaults to `""`. +- `lock` - (Optional) Whether to lock state access. Defaults to `true`. +- `cacert_path` - (Optional) The path to a PEM-encoded CA bundle with which to verify certificates of TLS-enabled etcd servers. +- `cert_path` - (Optional) The path to a PEM-encoded certificate to provide to etcd for secure client identification. +- `key_path` - (Optional) The path to a PEM-encoded key to provide to etcd for secure client identification. +- `max_request_bytes` - (Optional) The max request size to send to etcd. This can be increased to enable storage of larger state. You must set the corresponding server-side flag [--max-request-bytes](https://etcd.io/docs/current/dev-guide/limit/#request-size-limit) as well and the value should be less than the client setting. Defaults to `2097152` (2.0 MiB). **Please Note:** Increasing etcd's request size limit may negatively impact overall latency. diff --git a/website/docs/language/settings/backends/gcs.html.md b/website/docs/language/settings/backends/gcs.mdx similarity index 53% rename from website/docs/language/settings/backends/gcs.html.md rename to website/docs/language/settings/backends/gcs.mdx index 172c1154a..f5f23353a 100644 --- a/website/docs/language/settings/backends/gcs.html.md +++ b/website/docs/language/settings/backends/gcs.mdx @@ -1,9 +1,8 @@ --- -layout: "language" -page_title: "Backend Type: gcs" -sidebar_current: "docs-backends-types-standard-gcs" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. +page_title: 'Backend Type: gcs' +description: >- + Terraform can store the state remotely, making it easier to version and work + with in a team. --- # gcs @@ -11,7 +10,7 @@ description: |- Stores the state as an object in a configurable prefix in a pre-existing bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS). The bucket must exist prior to configuring the backend. -This backend supports [state locking](/docs/language/state/locking.html). +This backend supports [state locking](/language/state/locking). ~> **Warning!** It is highly recommended that you enable [Object Versioning](https://cloud.google.com/storage/docs/object-versioning) @@ -78,30 +77,30 @@ Terraform can impersonate a Google Service Account as described [here](https://c The following configuration options are supported: - * `bucket` - (Required) The name of the GCS bucket. This name must be - globally unique. For more information, see [Bucket Naming - Guidelines](https://cloud.google.com/storage/docs/bucketnaming.html#requirements). - * `credentials` / `GOOGLE_BACKEND_CREDENTIALS` / `GOOGLE_CREDENTIALS` - - (Optional) Local path to Google Cloud Platform account credentials in JSON - format. If unset, [Google Application Default - Credentials](https://developers.google.com/identity/protocols/application-default-credentials) - are used. The provided credentials must have Storage Object Admin role on the bucket. - **Warning**: if using the Google Cloud Platform provider as well, it will - also pick up the `GOOGLE_CREDENTIALS` environment variable. - * `impersonate_service_account` - (Optional) The service account to impersonate for accessing the State Bucket. - You must have `roles/iam.serviceAccountTokenCreator` role on that account for the impersonation to succeed. - If you are using a delegation chain, you can specify that using the `impersonate_service_account_delegates` field. - Alternatively, this can be specified using the `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` environment - variable. - * `impersonate_service_account_delegates` - (Optional) The delegation chain for an impersonating a service account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials#sa-credentials-delegated). - * `access_token` - (Optional) A temporary [OAuth 2.0 access token] obtained - from the Google Authorization server, i.e. the `Authorization: Bearer` token - used to authenticate HTTP requests to GCP APIs. This is an alternative to - `credentials`. If both are specified, `access_token` will be used over the - `credentials` field. - * `prefix` - (Optional) GCS prefix inside the bucket. Named states for - workspaces are stored in an object called `/.tfstate`. - * `encryption_key` / `GOOGLE_ENCRYPTION_KEY` - (Optional) A 32 byte base64 - encoded 'customer supplied encryption key' used to encrypt all state. For - more information see [Customer Supplied Encryption - Keys](https://cloud.google.com/storage/docs/encryption#customer-supplied). +- `bucket` - (Required) The name of the GCS bucket. This name must be + globally unique. For more information, see [Bucket Naming + Guidelines](https://cloud.google.com/storage/docs/bucketnaming.html#requirements). +- `credentials` / `GOOGLE_BACKEND_CREDENTIALS` / `GOOGLE_CREDENTIALS` - + (Optional) Local path to Google Cloud Platform account credentials in JSON + format. If unset, [Google Application Default + Credentials](https://developers.google.com/identity/protocols/application-default-credentials) + are used. The provided credentials must have Storage Object Admin role on the bucket. + **Warning**: if using the Google Cloud Platform provider as well, it will + also pick up the `GOOGLE_CREDENTIALS` environment variable. +- `impersonate_service_account` - (Optional) The service account to impersonate for accessing the State Bucket. + You must have `roles/iam.serviceAccountTokenCreator` role on that account for the impersonation to succeed. + If you are using a delegation chain, you can specify that using the `impersonate_service_account_delegates` field. + Alternatively, this can be specified using the `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` environment + variable. +- `impersonate_service_account_delegates` - (Optional) The delegation chain for an impersonating a service account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials#sa-credentials-delegated). +- `access_token` - (Optional) A temporary \[OAuth 2.0 access token] obtained + from the Google Authorization server, i.e. the `Authorization: Bearer` token + used to authenticate HTTP requests to GCP APIs. This is an alternative to + `credentials`. If both are specified, `access_token` will be used over the + `credentials` field. +- `prefix` - (Optional) GCS prefix inside the bucket. Named states for + workspaces are stored in an object called `/.tfstate`. +- `encryption_key` / `GOOGLE_ENCRYPTION_KEY` - (Optional) A 32 byte base64 + encoded 'customer supplied encryption key' used to encrypt all state. For + more information see [Customer Supplied Encryption + Keys](https://cloud.google.com/storage/docs/encryption#customer-supplied). diff --git a/website/docs/language/settings/backends/http.html.md b/website/docs/language/settings/backends/http.html.md deleted file mode 100644 index 78eedcba9..000000000 --- a/website/docs/language/settings/backends/http.html.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -layout: "language" -page_title: "Backend Type: http" -sidebar_current: "docs-backends-types-standard-http" -description: |- - Terraform can store state remotely at any valid HTTP endpoint. ---- - -# http - -Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) client. - -State will be fetched via GET, updated via POST, and purged with DELETE. The method used for updating is configurable. - -This backend optionally supports [state locking](/docs/language/state/locking.html). When locking -support is enabled it will use LOCK and UNLOCK requests providing the lock info in the body. The -endpoint should return a 423: Locked or 409: Conflict with the holding lock info when it's already -taken, 200: OK for success. Any other status will be considered an error. The ID of the holding lock -info will be added as a query parameter to state updates requests. - -## Example Usage - -```hcl -terraform { - backend "http" { - address = "http://myrest.api.com/foo" - lock_address = "http://myrest.api.com/foo" - unlock_address = "http://myrest.api.com/foo" - } -} -``` - -## Data Source Configuration - -```hcl -data "terraform_remote_state" "foo" { - backend = "http" - config = { - address = "http://my.rest.api.com" - } -} -``` - -## Configuration variables - -The following configuration options / environment variables are supported: - - * `address` / `TF_HTTP_ADDRESS` - (Required) The address of the REST endpoint - * `update_method` / `TF_HTTP_UPDATE_METHOD` - (Optional) HTTP method to use - when updating state. Defaults to `POST`. - * `lock_address` / `TF_HTTP_LOCK_ADDRESS` - (Optional) The address of the lock - REST endpoint. Defaults to disabled. - * `lock_method` / `TF_HTTP_LOCK_METHOD` - (Optional) The HTTP method to use - when locking. Defaults to `LOCK`. - * `unlock_address` / `TF_HTTP_UNLOCK_ADDRESS` - (Optional) The address of the - unlock REST endpoint. Defaults to disabled. - * `unlock_method` / `TF_HTTP_UNLOCK_METHOD` - (Optional) The HTTP method to use - when unlocking. Defaults to `UNLOCK`. - * `username` / `TF_HTTP_USERNAME` - (Optional) The username for HTTP basic - authentication - * `password` / `TF_HTTP_PASSWORD` - (Optional) The password for HTTP basic - authentication - * `skip_cert_verification` - (Optional) Whether to skip TLS verification. - Defaults to `false`. - * `retry_max` / `TF_HTTP_RETRY_MAX` – (Optional) The number of HTTP request - retries. Defaults to `2`. - * `retry_wait_min` / `TF_HTTP_RETRY_WAIT_MIN` – (Optional) The minimum time in - seconds to wait between HTTP request attempts. Defaults to `1`. - * `retry_wait_max` / `TF_HTTP_RETRY_WAIT_MAX` – (Optional) The maximum time in - seconds to wait between HTTP request attempts. Defaults to `30`. diff --git a/website/docs/language/settings/backends/http.mdx b/website/docs/language/settings/backends/http.mdx new file mode 100644 index 000000000..a87b2152c --- /dev/null +++ b/website/docs/language/settings/backends/http.mdx @@ -0,0 +1,67 @@ +--- +page_title: 'Backend Type: http' +description: Terraform can store state remotely at any valid HTTP endpoint. +--- + +# http + +Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) client. + +State will be fetched via GET, updated via POST, and purged with DELETE. The method used for updating is configurable. + +This backend optionally supports [state locking](/language/state/locking). When locking +support is enabled it will use LOCK and UNLOCK requests providing the lock info in the body. The +endpoint should return a 423: Locked or 409: Conflict with the holding lock info when it's already +taken, 200: OK for success. Any other status will be considered an error. The ID of the holding lock +info will be added as a query parameter to state updates requests. + +## Example Usage + +```hcl +terraform { + backend "http" { + address = "http://myrest.api.com/foo" + lock_address = "http://myrest.api.com/foo" + unlock_address = "http://myrest.api.com/foo" + } +} +``` + +## Data Source Configuration + +```hcl +data "terraform_remote_state" "foo" { + backend = "http" + config = { + address = "http://my.rest.api.com" + } +} +``` + +## Configuration variables + +The following configuration options / environment variables are supported: + +- `address` / `TF_HTTP_ADDRESS` - (Required) The address of the REST endpoint +- `update_method` / `TF_HTTP_UPDATE_METHOD` - (Optional) HTTP method to use + when updating state. Defaults to `POST`. +- `lock_address` / `TF_HTTP_LOCK_ADDRESS` - (Optional) The address of the lock + REST endpoint. Defaults to disabled. +- `lock_method` / `TF_HTTP_LOCK_METHOD` - (Optional) The HTTP method to use + when locking. Defaults to `LOCK`. +- `unlock_address` / `TF_HTTP_UNLOCK_ADDRESS` - (Optional) The address of the + unlock REST endpoint. Defaults to disabled. +- `unlock_method` / `TF_HTTP_UNLOCK_METHOD` - (Optional) The HTTP method to use + when unlocking. Defaults to `UNLOCK`. +- `username` / `TF_HTTP_USERNAME` - (Optional) The username for HTTP basic + authentication +- `password` / `TF_HTTP_PASSWORD` - (Optional) The password for HTTP basic + authentication +- `skip_cert_verification` - (Optional) Whether to skip TLS verification. + Defaults to `false`. +- `retry_max` / `TF_HTTP_RETRY_MAX` – (Optional) The number of HTTP request + retries. Defaults to `2`. +- `retry_wait_min` / `TF_HTTP_RETRY_WAIT_MIN` – (Optional) The minimum time in + seconds to wait between HTTP request attempts. Defaults to `1`. +- `retry_wait_max` / `TF_HTTP_RETRY_WAIT_MAX` – (Optional) The maximum time in + seconds to wait between HTTP request attempts. Defaults to `30`. diff --git a/website/docs/language/settings/backends/index.html.md b/website/docs/language/settings/backends/index.mdx similarity index 70% rename from website/docs/language/settings/backends/index.html.md rename to website/docs/language/settings/backends/index.mdx index 3259b5422..6af64ab11 100644 --- a/website/docs/language/settings/backends/index.html.md +++ b/website/docs/language/settings/backends/index.mdx @@ -1,21 +1,22 @@ --- -layout: "language" -page_title: "Backend Overview - Configuration Language" -description: "A backend defines where Terraform stores its state. Learn about how backends work." +page_title: Backend Overview - Configuration Language +description: >- + A backend defines where Terraform stores its state. Learn about how backends + work. --- # Backends -Backends define where Terraform's [state](/docs/language/state/index.html) snapshots are stored. +Backends define where Terraform's [state](/language/state) snapshots are stored. A given Terraform configuration can either specify a backend, -[integrate with Terraform Cloud](/docs/language/settings/terraform-cloud.html), +[integrate with Terraform Cloud](/language/settings/terraform-cloud), or do neither and default to storing state locally. The rest of this page introduces the concept of backends; the other pages in this section document how to configure and use backends. -- [Backend Configuration](/docs/language/settings/backends/configuration.html) documents the form +- [Backend Configuration](/language/settings/backends/configuration) documents the form of a `backend` block, which selects and configures a backend for a Terraform configuration. - This section also includes a page for each of Terraform's built-in backends, @@ -24,14 +25,14 @@ this section document how to configure and use backends. ## What Backends Do -Backends primarily determine where Terraform stores its [state](/docs/language/state/index.html). -Terraform uses this persisted [state](/docs/language/state/index.html) data to keep track of the +Backends primarily determine where Terraform stores its [state](/language/state). +Terraform uses this persisted [state](/language/state) data to keep track of the resources it manages. Since it needs the state in order to know which real-world infrastructure objects correspond to the resources in a configuration, everyone working with a given collection of infrastructure resources must be able to access the same state data. By default, Terraform implicitly uses a backend called -[`local`](/docs/language/settings/backends/local.html) to store state as a local file on disk. +[`local`](/language/settings/backends/local) to store state as a local file on disk. Every other backend stores state in a remote service of some kind, which allows multiple people to access it. Accessing state in a remote service generally requires some kind of access credentials, since state data contains extremely sensitive information. @@ -42,9 +43,9 @@ conflicts and inconsistencies. -> **Note:** In Terraform versions prior to 1.1.0, backends were also classified as being 'standard' or 'enhanced', where the latter term referred to the ability of the -[remote backend](/docs/language/settings/backends/remote.html) to store state and perform +[remote backend](/language/settings/backends/remote) to store state and perform Terraform operations. This classification has been removed, clarifying the primary purpose of -backends. Refer to [Using Terraform Cloud](/docs/cli/cloud/index.html) for details about how to +backends. Refer to [Using Terraform Cloud](/cli/cloud) for details about how to store state, execute remote operations, and use Terraform Cloud directly from Terraform. ## Available Backends @@ -55,4 +56,3 @@ very often. The built-in backends are the only backends. You cannot load additional backends as plugins. - diff --git a/website/docs/language/settings/backends/kubernetes.html.md b/website/docs/language/settings/backends/kubernetes.mdx similarity index 86% rename from website/docs/language/settings/backends/kubernetes.html.md rename to website/docs/language/settings/backends/kubernetes.mdx index 20e3ecc1b..1f7ee648e 100644 --- a/website/docs/language/settings/backends/kubernetes.html.md +++ b/website/docs/language/settings/backends/kubernetes.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Backend Type: Kubernetes" -sidebar_current: "docs-backends-types-standard-kubernetes" -description: |- - Terraform can store state remotely in Kubernetes and lock that state. +page_title: 'Backend Type: Kubernetes' +description: Terraform can store state remotely in Kubernetes and lock that state. --- # kubernetes @@ -12,7 +9,7 @@ description: |- Stores the state in a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/). -This backend supports [state locking](/docs/language/state/locking.html), with locking done using a Lease resource. +This backend supports [state locking](/language/state/locking), with locking done using a Lease resource. ## Example Configuration @@ -27,14 +24,13 @@ terraform { This assumes the user/service account running terraform has [permissions](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) to read/write secrets in the [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) used to store the secret. -If the `config_path` or `config_paths` attribute is set the backend will attempt to use a [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) to gain access to the cluster. +If the `config_path` or `config_paths` attribute is set the backend will attempt to use a [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) to gain access to the cluster. -If the `in_cluster_config` flag is set the backend will attempt to use a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to access the cluster. This can be used if Terraform is being run from within a pod running in the Kubernetes cluster. +If the `in_cluster_config` flag is set the backend will attempt to use a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to access the cluster. This can be used if Terraform is being run from within a pod running in the Kubernetes cluster. For most use cases either `in_cluster_config`, `config_path`, or `config_paths` will need to be set. If all flags are set the configuration at `config_path` will be used. -Note that for the access credentials we recommend using a [partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). - +Note that for the access credentials we recommend using a [partial configuration](/language/settings/backends/configuration#partial-configuration). ## Example Referencing @@ -69,7 +65,7 @@ The following configuration options are supported: * `config_context_auth_info` - (Optional) Authentication info context of the kube config (name of the kubeconfig user, `--user` flag in `kubectl`). Can be sourced from `KUBE_CTX_AUTH_INFO`. * `config_context_cluster` - (Optional) Cluster context of the kube config (name of the kubeconfig cluster, `--cluster` flag in `kubectl`). Can be sourced from `KUBE_CTX_CLUSTER`. * `token` - (Optional) Token of your service account. Can be sourced from `KUBE_TOKEN`. -* `exec` - (Optional) Configuration block to use an [exec-based credential plugin] (https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials. +* `exec` - (Optional) Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials. * `api_version` - (Required) API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`. * `command` - (Required) Command to execute. * `args` - (Optional) List of arguments to pass when executing the plugin. diff --git a/website/docs/language/settings/backends/local.html.md b/website/docs/language/settings/backends/local.mdx similarity index 71% rename from website/docs/language/settings/backends/local.html.md rename to website/docs/language/settings/backends/local.mdx index f2829d3a4..d2f5d18a0 100644 --- a/website/docs/language/settings/backends/local.html.md +++ b/website/docs/language/settings/backends/local.mdx @@ -1,9 +1,8 @@ --- -layout: "language" -page_title: "Backend Type: local" -sidebar_current: "docs-backends-types-enhanced-local" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. +page_title: 'Backend Type: local' +description: >- + Terraform can store the state remotely, making it easier to version and work + with in a team. --- # local @@ -39,9 +38,9 @@ data "terraform_remote_state" "foo" { The following configuration options are supported: - * `path` - (Optional) The path to the `tfstate` file. This defaults to - "terraform.tfstate" relative to the root module by default. - * `workspace_dir` - (Optional) The path to non-default workspaces. +* `path` - (Optional) The path to the `tfstate` file. This defaults to + "terraform.tfstate" relative to the root module by default. +* `workspace_dir` - (Optional) The path to non-default workspaces. ## Command Line Arguments @@ -58,17 +57,17 @@ additional arguments: * `-state-out=FILENAME` - overrides the state filename when _writing_ new state snapshots. - If you use `-state` without also using `-state-out` then Terraform will - use the `-state` filename for both `-state` and `-state-out`, which means - Terraform will overwrite the input file if it creates a new state snapshot. + If you use `-state` without also using `-state-out` then Terraform will + use the `-state` filename for both `-state` and `-state-out`, which means + Terraform will overwrite the input file if it creates a new state snapshot. * `-backup=FILENAME` - overrides the default filename that the local backend would normally choose dynamically to create backup files when it writes new state. - If you use `-state` without also using `-backup` then Terraform will use - the `-state` filename as a filename prefix for generating a backup filename. - You can use `-backup=-` (that is, set the filename to just the ASCII - dash character) to disable the creation of backup files altogether. + If you use `-state` without also using `-backup` then Terraform will use + the `-state` filename as a filename prefix for generating a backup filename. + You can use `-backup=-` (that is, set the filename to just the ASCII + dash character) to disable the creation of backup files altogether. These three options are preserved for backward-compatibility with earlier workflows that predated the introduction of built-in remote state, where @@ -78,7 +77,7 @@ the three arguments would typically all be paths within a temporary directory used just for one operation. Because these old workflows predate the introduction of the possibility of -[multiple workspaces](/docs/language/state/workspaces.html), setting them +[multiple workspaces](/language/state/workspaces), setting them overrides Terraform's usual behavior of selecting a different state filename based on the selected workspace. If you use all three of these options then the selected workspace has no effect on which filenames Terraform will select @@ -90,7 +89,7 @@ backend type selected. We do not recommend using these options in new systems, even if you are running Terraform in automation. Instead, -[select a different backend which supports remote state](./) and configure it +[select a different backend which supports remote state](/language/settings/backends) and configure it within your root module, which ensures that everyone working on your configuration will automatically retrieve and store state in the correct shared location without any special command line options. diff --git a/website/docs/language/settings/backends/manta.html.md b/website/docs/language/settings/backends/manta.html.md deleted file mode 100644 index 150b3633b..000000000 --- a/website/docs/language/settings/backends/manta.html.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: "language" -page_title: "Backend Type: manta" -sidebar_current: "docs-backends-types-standard-manta" -description: |- - Terraform can store state in manta. ---- - -# manta - -Stores the state as an artifact in [Manta](https://www.joyent.com/manta). - -This backend supports [state locking](/docs/language/state/locking.html), with locking within Manta. - -## Example Configuration - -```hcl -terraform { - backend "manta" { - path = "random/path" - object_name = "terraform.tfstate" - } -} -``` - -Note that for the access credentials we recommend using a -[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). - -## Data Source Configuration - -```hcl -data "terraform_remote_state" "foo" { - backend = "manta" - config = { - path = "random/path" - object_name = "terraform.tfstate" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `account` - (Required) This is the name of the Manta account. It can also be provided via the `SDC_ACCOUNT` or `TRITON_ACCOUNT` environment variables. - * `user` - (Optional) The username of the Triton account used to authenticate with the Triton API. It can also be provided via the `SDC_USER` or `TRITON_USER` environment variables. - * `url` - (Optional) The Manta API Endpoint. It can also be provided via the `MANTA_URL` environment variable. Defaults to `https://us-east.manta.joyent.com`. - * `key_material` - (Optional) This is the private key of an SSH key associated with the Triton account to be used. If this is not set, the private key corresponding to the fingerprint in key_id must be available via an SSH Agent. Can be set via the `SDC_KEY_MATERIAL` or `TRITON_KEY_MATERIAL` environment variables. - * `key_id` - (Required) This is the fingerprint of the public key matching the key specified in key_path. It can be obtained via the command ssh-keygen -l -E md5 -f /path/to/key. Can be set via the `SDC_KEY_ID` or `TRITON_KEY_ID` environment variables. - * `insecure_skip_tls_verify` - (Optional) This allows skipping TLS verification of the Triton endpoint. It is useful when connecting to a temporary Triton installation such as Cloud-On-A-Laptop which does not generally use a certificate signed by a trusted root CA. Defaults to `false`. - * `path` - (Required) The path relative to your private storage directory (`/$MANTA_USER/stor`) where the state file will be stored. **Please Note:** If this path does not exist, then the backend will create this folder location as part of backend creation. - * `object_name` - (Optional) The name of the state file (defaults to `terraform.tfstate`) diff --git a/website/docs/language/settings/backends/manta.mdx b/website/docs/language/settings/backends/manta.mdx new file mode 100644 index 000000000..b3d49c792 --- /dev/null +++ b/website/docs/language/settings/backends/manta.mdx @@ -0,0 +1,49 @@ +--- +page_title: 'Backend Type: manta' +description: Terraform can store state in manta. +--- + +# manta + +Stores the state as an artifact in [Manta](https://www.joyent.com/manta). + +This backend supports [state locking](/language/state/locking), with locking within Manta. + +## Example Configuration + +```hcl +terraform { + backend "manta" { + path = "random/path" + object_name = "terraform.tfstate" + } +} +``` + +Note that for the access credentials we recommend using a +[partial configuration](/language/settings/backends/configuration#partial-configuration). + +## Data Source Configuration + +```hcl +data "terraform_remote_state" "foo" { + backend = "manta" + config = { + path = "random/path" + object_name = "terraform.tfstate" + } +} +``` + +## Configuration variables + +The following configuration options are supported: + +- `account` - (Required) This is the name of the Manta account. It can also be provided via the `SDC_ACCOUNT` or `TRITON_ACCOUNT` environment variables. +- `user` - (Optional) The username of the Triton account used to authenticate with the Triton API. It can also be provided via the `SDC_USER` or `TRITON_USER` environment variables. +- `url` - (Optional) The Manta API Endpoint. It can also be provided via the `MANTA_URL` environment variable. Defaults to `https://us-east.manta.joyent.com`. +- `key_material` - (Optional) This is the private key of an SSH key associated with the Triton account to be used. If this is not set, the private key corresponding to the fingerprint in key_id must be available via an SSH Agent. Can be set via the `SDC_KEY_MATERIAL` or `TRITON_KEY_MATERIAL` environment variables. +- `key_id` - (Required) This is the fingerprint of the public key matching the key specified in key_path. It can be obtained via the command ssh-keygen -l -E md5 -f /path/to/key. Can be set via the `SDC_KEY_ID` or `TRITON_KEY_ID` environment variables. +- `insecure_skip_tls_verify` - (Optional) This allows skipping TLS verification of the Triton endpoint. It is useful when connecting to a temporary Triton installation such as Cloud-On-A-Laptop which does not generally use a certificate signed by a trusted root CA. Defaults to `false`. +- `path` - (Required) The path relative to your private storage directory (`/$MANTA_USER/stor`) where the state file will be stored. **Please Note:** If this path does not exist, then the backend will create this folder location as part of backend creation. +- `object_name` - (Optional) The name of the state file (defaults to `terraform.tfstate`) diff --git a/website/docs/language/settings/backends/oss.html.md b/website/docs/language/settings/backends/oss.mdx similarity index 90% rename from website/docs/language/settings/backends/oss.html.md rename to website/docs/language/settings/backends/oss.mdx index a67ac94ff..85dd38009 100644 --- a/website/docs/language/settings/backends/oss.html.md +++ b/website/docs/language/settings/backends/oss.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Backend Type: oss" -sidebar_current: "docs-backends-types-standard-oss" -description: |- - Terraform can store state remotely in OSS and lock that state with OSS. +page_title: 'Backend Type: oss' +description: Terraform can store state remotely in OSS and lock that state with OSS. --- # OSS @@ -14,7 +11,7 @@ This backend also supports state locking and consistency checking via [Alibaba Cloud Table Store](https://www.alibabacloud.com/help/doc-detail/27280.htm), which can be enabled by setting the `tablestore_table` field to an existing TableStore table name. -This backend supports [state locking](/docs/language/state/locking.html) via TableStore. +This backend supports [state locking](/language/state/locking) via TableStore. -> **Note:** The OSS backend is available from terraform version 0.12.2. @@ -38,12 +35,11 @@ a [OTS Instance](https://registry.terraform.io/providers/aliyun/alicloud/latest/ a [OTS TableStore](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/ots_table) called `statelock`. The Terraform state will be written into the file `path/mystate/version-1.tfstate`. The `TableStore` must have a primary key named `LockID` of type `String`. - ## Data Source Configuration To make use of the OSS remote state in another configuration, use the [`terraform_remote_state` data -source](/docs/language/state/remote-state-data.html). +source](/language/state/remote-state-data). ```hcl terraform { @@ -78,29 +74,48 @@ data "terraform_remote_state" "network" { The following configuration options or environment variables are supported: * `access_key` - (Optional) Alibaba Cloud access key. It supports environment variables `ALICLOUD_ACCESS_KEY` and `ALICLOUD_ACCESS_KEY_ID`. + * `secret_key` - (Optional) Alibaba Cloud secret access key. It supports environment variables `ALICLOUD_SECRET_KEY` and `ALICLOUD_ACCESS_KEY_SECRET`. + * `security_token` - (Optional) STS access token. It supports environment variable `ALICLOUD_SECURITY_TOKEN`. + * `ecs_role_name` - (Optional, Available in 0.12.14+) The RAM Role Name attached on a ECS instance for API operations. You can retrieve this from the 'Access Control' section of the Alibaba Cloud console. + * `region` - (Optional) The region of the OSS bucket. It supports environment variables `ALICLOUD_REGION` and `ALICLOUD_DEFAULT_REGION`. + * `endpoint` - (Optional) A custom endpoint for the OSS API. It supports environment variables `ALICLOUD_OSS_ENDPOINT` and `OSS_ENDPOINT`. + * `bucket` - (Required) The name of the OSS bucket. + * `prefix` - (Opeional) The path directory of the state file will be stored. Default to "env:". + * `key` - (Optional) The name of the state file. Defaults to `terraform.tfstate`. + * `tablestore_endpoint` / `ALICLOUD_TABLESTORE_ENDPOINT` - (Optional) A custom endpoint for the TableStore API. + * `tablestore_table` - (Optional) A TableStore table for state locking and consistency. The table must have a primary key named `LockID` of type `String`. + * `sts_endpoint` - (Optional, Available in 1.0.11+) Custom endpoint for the AliCloud Security Token Service (STS) API. It supports environment variable `ALICLOUD_STS_ENDPOINT`. + * `encrypt` - (Optional) Whether to enable server side encryption of the state file. If it is true, OSS will use 'AES256' encryption algorithm to encrypt state file. + * `acl` - (Optional) [Object ACL](https://www.alibabacloud.com/help/doc-detail/52284.htm) to be applied to the state file. + * `shared_credentials_file` - (Optional, Available in 0.12.8+) This is the path to the shared credentials file. It can also be sourced from the `ALICLOUD_SHARED_CREDENTIALS_FILE` environment variable. If this is not set and a profile is specified, `~/.aliyun/config.json` will be used. + * `profile` - (Optional, Available in 0.12.8+) This is the Alibaba Cloud profile name as set in the shared credentials file. It can also be sourced from the `ALICLOUD_PROFILE` environment variable. + * `assume_role_role_arn` - (Optional, Available in 1.1.0+) The ARN of the role to assume. If ARN is set to an empty string, it does not perform role switching. It supports the environment variable `ALICLOUD_ASSUME_ROLE_ARN`. Terraform executes configuration on account with provided credentials. + * `assume_role_policy` - (Optional, Available in 1.1.0+) A more restrictive policy to apply to the temporary credentials. This gives you a way to further restrict the permissions for the resulting temporary security credentials. You cannot use this policy to grant permissions that exceed those of the role that is being assumed. + * `assume_role_session_name` - (Optional, Available in 1.1.0+) The session name to use when assuming the role. If omitted, 'terraform' is passed to the AssumeRole call as session name. It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_NAME`. -* `assume_role_session_expiration` - (Optional, Available in 1.1.0+) The time after which the established session for assuming role expires. Valid value range: [900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`. + +* `assume_role_session_expiration` - (Optional, Available in 1.1.0+) The time after which the established session for assuming role expires. Valid value range: \[900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`. * `assume_role` - (**Deprecated as of 1.1.0+**, Available in 0.12.6+) If provided with a role ARN, will attempt to assume this role using the supplied credentials. It will be ignored when `assume_role_role_arn` is specified. @@ -113,6 +128,6 @@ The following configuration options or environment variables are supported: * `session_name` - (Optional) The session name to use when assuming the role. If omitted, 'terraform' is passed to the AssumeRole call as session name. It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_NAME`. - * `session_expiration` - (Optional) The time after which the established session for assuming role expires. Valid value range: [900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`. + * `session_expiration` - (Optional) The time after which the established session for assuming role expires. Valid value range: \[900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`. -> **Note:** If you want to store state in the custom OSS endpoint, you can specify an environment variable `OSS_ENDPOINT`, like "oss-cn-beijing-internal.aliyuncs.com" diff --git a/website/docs/language/settings/backends/pg.html.md b/website/docs/language/settings/backends/pg.html.md deleted file mode 100644 index 509f33c8e..000000000 --- a/website/docs/language/settings/backends/pg.html.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -layout: "language" -page_title: "Backend Type: pg" -sidebar_current: "docs-backends-types-standard-pg" -description: |- - Terraform can store state remotely in a Postgres database with locking. ---- - -# pg - -Stores the state in a [Postgres database](https://www.postgresql.org) version 10 or newer. - -This backend supports [state locking](/docs/language/state/locking.html). - -## Example Configuration - -```hcl -terraform { - backend "pg" { - conn_str = "postgres://user:pass@db.example.com/terraform_backend" - } -} -``` - -Before initializing the backend with `terraform init`, the database must already exist: - -``` -createdb terraform_backend -``` - -This `createdb` command is found in [Postgres client applications](https://www.postgresql.org/docs/10/reference-client.html) which are installed along with the database server. - -We recommend using a -[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration) -for the `conn_str` variable, because it typically contains access credentials that should not be committed to source control: - -```hcl -terraform { - backend "pg" {} -} -``` - -Then, set the credentials when initializing the configuration: - -``` -terraform init -backend-config="conn_str=postgres://user:pass@db.example.com/terraform_backend" -``` - -To use a Postgres server running on the same machine as Terraform, configure localhost with SSL disabled: - -``` -terraform init -backend-config="conn_str=postgres://localhost/terraform_backend?sslmode=disable" -``` - -## Data Source Configuration - -To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/docs/language/state/remote-state-data.html). - -```hcl -data "terraform_remote_state" "network" { - backend = "pg" - config = { - conn_str = "postgres://localhost/terraform_backend" - } -} -``` - -## Configuration Variables - -The following configuration options or environment variables are supported: - - * `conn_str` - (Required) Postgres connection string; a `postgres://` URL - * `schema_name` - Name of the automatically-managed Postgres schema, default `terraform_remote_state`. - * `skip_schema_creation` - If set to `true`, the Postgres schema must already exist. Terraform won't try to create the schema, this is useful when it has already been created by a database administrator. - * `skip_table_creation` - If set to `true`, the Postgres table must already exist. Terraform won't try to create the table, this is useful when it has already been created by a database administrator. - * `skip_index_creation` - If set to `true`, the Postgres index must already exist. Terraform won't try to create the index, this is useful when it has already been created by a database administrator. - -## Technical Design - -This backend creates one table **states** in the automatically-managed Postgres schema configured by the `schema_name` variable. - -The table is keyed by the [workspace](/docs/language/state/workspaces.html) name. If workspaces are not in use, the name `default` is used. - -Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](https://www.terraform.io/docs/cli/commands/force-unlock.html) is not supported, because these database-native locks will automatically unlock when the session is aborted or the connection fails. To see outstanding locks in a Postgres server, use the [`pg_locks` system view](https://www.postgresql.org/docs/9.5/view-pg-locks.html). - -The **states** table contains: - - * a serial integer `id`, used as the key for advisory locks - * the workspace `name` key as *text* with a unique index - * the Terraform state `data` as *text* diff --git a/website/docs/language/settings/backends/pg.mdx b/website/docs/language/settings/backends/pg.mdx new file mode 100644 index 000000000..fae9c8561 --- /dev/null +++ b/website/docs/language/settings/backends/pg.mdx @@ -0,0 +1,87 @@ +--- +page_title: 'Backend Type: pg' +description: Terraform can store state remotely in a Postgres database with locking. +--- + +# pg + +Stores the state in a [Postgres database](https://www.postgresql.org) version 10 or newer. + +This backend supports [state locking](/language/state/locking). + +## Example Configuration + +```hcl +terraform { + backend "pg" { + conn_str = "postgres://user:pass@db.example.com/terraform_backend" + } +} +``` + +Before initializing the backend with `terraform init`, the database must already exist: + +``` +createdb terraform_backend +``` + +This `createdb` command is found in [Postgres client applications](https://www.postgresql.org/docs/10/reference-client.html) which are installed along with the database server. + +We recommend using a +[partial configuration](/language/settings/backends/configuration#partial-configuration) +for the `conn_str` variable, because it typically contains access credentials that should not be committed to source control: + +```hcl +terraform { + backend "pg" {} +} +``` + +Then, set the credentials when initializing the configuration: + +``` +terraform init -backend-config="conn_str=postgres://user:pass@db.example.com/terraform_backend" +``` + +To use a Postgres server running on the same machine as Terraform, configure localhost with SSL disabled: + +``` +terraform init -backend-config="conn_str=postgres://localhost/terraform_backend?sslmode=disable" +``` + +## Data Source Configuration + +To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/language/state/remote-state-data). + +```hcl +data "terraform_remote_state" "network" { + backend = "pg" + config = { + conn_str = "postgres://localhost/terraform_backend" + } +} +``` + +## Configuration Variables + +The following configuration options or environment variables are supported: + +- `conn_str` - (Required) Postgres connection string; a `postgres://` URL +- `schema_name` - Name of the automatically-managed Postgres schema, default `terraform_remote_state`. +- `skip_schema_creation` - If set to `true`, the Postgres schema must already exist. Terraform won't try to create the schema, this is useful when it has already been created by a database administrator. +- `skip_table_creation` - If set to `true`, the Postgres table must already exist. Terraform won't try to create the table, this is useful when it has already been created by a database administrator. +- `skip_index_creation` - If set to `true`, the Postgres index must already exist. Terraform won't try to create the index, this is useful when it has already been created by a database administrator. + +## Technical Design + +This backend creates one table **states** in the automatically-managed Postgres schema configured by the `schema_name` variable. + +The table is keyed by the [workspace](/language/state/workspaces) name. If workspaces are not in use, the name `default` is used. + +Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](/cli/commands/force-unlock) is not supported, because these database-native locks will automatically unlock when the session is aborted or the connection fails. To see outstanding locks in a Postgres server, use the [`pg_locks` system view](https://www.postgresql.org/docs/9.5/view-pg-locks.html). + +The **states** table contains: + +- a serial integer `id`, used as the key for advisory locks +- the workspace `name` key as _text_ with a unique index +- the Terraform state `data` as _text_ diff --git a/website/docs/language/settings/backends/remote.html.md b/website/docs/language/settings/backends/remote.mdx similarity index 75% rename from website/docs/language/settings/backends/remote.html.md rename to website/docs/language/settings/backends/remote.mdx index dfe8df5a3..e67c90e27 100644 --- a/website/docs/language/settings/backends/remote.html.md +++ b/website/docs/language/settings/backends/remote.mdx @@ -1,19 +1,15 @@ --- -layout: "language" -page_title: "Backend Type: remote" -sidebar_current: "docs-backends-types-enhanced-remote" -description: |- - Terraform can store the state and run operations remotely, making it easier to version and work with in a team. +page_title: 'Backend Type: remote' +description: >- + Terraform can store the state and run operations remotely, making it easier to + version and work with in a team. --- # remote --> **Note:** The remote backend was introduced in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, **we recommend using the Terraform Cloud's built-in [`cloud` integration](/docs/language/settings/terraform-cloud.html)** instead of this backend. The `cloud` option includes an improved user experience and more features. - - -The remote backend is unique among all other Terraform backends because it can both store state snapshots and execute operations for Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html). It used to be called an "enhanced" backend. - +-> **Note:** The remote backend was introduced in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, **we recommend using the Terraform Cloud's built-in [`cloud` integration](/language/settings/terraform-cloud)** instead of this backend. The `cloud` option includes an improved user experience and more features. +The remote backend is unique among all other Terraform backends because it can both store state snapshots and execute operations for Terraform Cloud's [CLI-driven run workflow](/cloud-docs/run/cli). It used to be called an "enhanced" backend. When using full remote operations, operations like `terraform plan` or `terraform apply` can be executed in Terraform Cloud's run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated Terraform Cloud workspace. @@ -57,7 +53,7 @@ determines which mode it uses: all of the desired remote workspace names. For example, set `prefix = "networking-"` to use Terraform cloud workspaces with names like `networking-dev` and `networking-prod`. This is helpful when - mapping multiple Terraform CLI [workspaces](/docs/language/state/workspaces.html) + mapping multiple Terraform CLI [workspaces](/language/state/workspaces) used in a single Terraform configuration to multiple Terraform Cloud workspaces. @@ -68,7 +64,7 @@ the Terraform CLI workspace `prod` within the current configuration. Remote Terraform operations such as `plan` and `apply` executed against that Terraform CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`. -Additionally, the [`terraform.workspace`](/docs/language/state/workspaces.html#current-workspace-interpolation) +Additionally, the [`terraform.workspace`](/language/state/workspaces#current-workspace-interpolation) expression shouldn't be used in Terraform configurations that use Terraform 1.0.x or earlier and run remote operations against Terraform Cloud workspaces. The reason for this is that prior to Terraform 1.1.0, Terraform Cloud workspaces only used the single `default` Terraform @@ -92,8 +88,8 @@ running any remote operations against them. ## Example Configurations -> **Note:** We recommend omitting the token from the configuration, and instead using - [`terraform login`](/docs/cli/commands/login.html) or manually configuring - `credentials` in the [CLI config file](/docs/cli/config/config-file.html#credentials). +[`terraform login`](/cli/commands/login) or manually configuring +`credentials` in the [CLI config file](/cli/config/config-file#credentials). ### Basic Configuration @@ -169,21 +165,21 @@ data "terraform_remote_state" "foo" { The following configuration options are supported: -* `hostname` - (Optional) The remote backend hostname to connect to. Defaults +- `hostname` - (Optional) The remote backend hostname to connect to. Defaults to app.terraform.io. -* `organization` - (Required) The name of the organization containing the +- `organization` - (Required) The name of the organization containing the targeted workspace(s). -* `token` - (Optional) The token used to authenticate with the remote backend. +- `token` - (Optional) The token used to authenticate with the remote backend. We recommend omitting the token from the configuration, and instead using - [`terraform login`](/docs/cli/commands/login.html) or manually configuring + [`terraform login`](/cli/commands/login) or manually configuring `credentials` in the - [CLI config file](/docs/cli/config/config-file.html#credentials). -* `workspaces` - (Required) A block specifying which remote workspace(s) to use. + [CLI config file](/cli/config/config-file#credentials). +- `workspaces` - (Required) A block specifying which remote workspace(s) to use. The `workspaces` block supports the following keys: - * `name` - (Optional) The full name of one remote workspace. When configured, + - `name` - (Optional) The full name of one remote workspace. When configured, only the default workspace can be used. This option conflicts with `prefix`. - * `prefix` - (Optional) A prefix used in the names of one or more remote + - `prefix` - (Optional) A prefix used in the names of one or more remote workspaces, all of which can be used with this configuration. The full workspace names are used in Terraform Cloud, and the short names (minus the prefix) are used on the command line for Terraform CLI workspaces. @@ -199,38 +195,37 @@ For configurations that include a `backend "remote"` block, commands that make local modifications to Terraform state and then push them back up to the remote workspace accept the following option to modify that behavior: -* `-ignore-remote-version` - Override checking that the local and remote +- `-ignore-remote-version` - Override checking that the local and remote Terraform versions agree, making an operation proceed even when there is a mismatch. - Normally state-modification operations require using a local version of - Terraform CLI which is compatible with the Terraform version selected - for the remote workspace as part of its settings. This is to avoid the - local operation creating a new state snapshot which the workspace's - remote execution environment would then be unable to decode. + Normally state-modification operations require using a local version of + Terraform CLI which is compatible with the Terraform version selected + for the remote workspace as part of its settings. This is to avoid the + local operation creating a new state snapshot which the workspace's + remote execution environment would then be unable to decode. - Overriding this check can result in a Terraform Cloud workspace that is - no longer able to complete remote operations, so we recommend against - using this option. + Overriding this check can result in a Terraform Cloud workspace that is + no longer able to complete remote operations, so we recommend against + using this option. ## Excluding Files from Upload with .terraformignore -> **Version note:** `.terraformignore` support was added in Terraform 0.12.11. -When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), +When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli), an archive of your configuration directory is uploaded to Terraform Cloud. You can define paths to ignore from upload via a `.terraformignore` file at the root of your configuration directory. If this file is not present, the archive will exclude the following by default: -* `.git/` directories -* `.terraform/` directories (exclusive of `.terraform/modules`) +- `.git/` directories +- `.terraform/` directories (exclusive of `.terraform/modules`) The `.terraformignore` file can include rules as one would include in a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) - -* Comments (starting with `#`) or blank lines are ignored -* End a pattern with a forward slash `/` to specify a directory -* Negate a pattern by starting it with an exclamation point `!` +- Comments (starting with `#`) or blank lines are ignored +- End a pattern with a forward slash `/` to specify a directory +- Negate a pattern by starting it with an exclamation point `!` Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered. diff --git a/website/docs/language/settings/backends/s3.html.md b/website/docs/language/settings/backends/s3.mdx similarity index 96% rename from website/docs/language/settings/backends/s3.html.md rename to website/docs/language/settings/backends/s3.mdx index f8d6b449a..a338a42e1 100644 --- a/website/docs/language/settings/backends/s3.html.md +++ b/website/docs/language/settings/backends/s3.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Backend Type: s3" -sidebar_current: "docs-backends-types-standard-s3" -description: |- - Terraform can store state remotely in S3 and lock that state with DynamoDB. +page_title: 'Backend Type: s3' +description: Terraform can store state remotely in S3 and lock that state with DynamoDB. --- # S3 @@ -35,7 +32,7 @@ This assumes we have a bucket created called `mybucket`. The Terraform state is written to the key `path/to/my/key`. Note that for the access credentials we recommend using a -[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). +[partial configuration](/language/settings/backends/configuration#partial-configuration). ### S3 Bucket Permissions @@ -106,7 +103,7 @@ This is seen in the following AWS IAM Statement: To make use of the S3 remote state in another configuration, use the [`terraform_remote_state` data -source](/docs/language/state/remote-state-data.html). +source](/language/state/remote-state-data). ```hcl data "terraform_remote_state" "network" { @@ -181,7 +178,7 @@ The following configuration is optional: The following configuration is required: * `bucket` - (Required) Name of the S3 Bucket. -* `key` - (Required) Path to the state file inside the S3 Bucket. When using a non-default [workspace](/docs/language/state/workspaces.html), the state path will be `/workspace_key_prefix/workspace_name/key` (see also the `workspace_key_prefix` configuration). +* `key` - (Required) Path to the state file inside the S3 Bucket. When using a non-default [workspace](/language/state/workspaces), the state path will be `/workspace_key_prefix/workspace_name/key` (see also the `workspace_key_prefix` configuration). The following configuration is optional: @@ -213,7 +210,7 @@ The S3 backend can be used in a number of different ways that make different tradeoffs between convenience, security, and isolation in such an organization. This section describes one such approach that aims to find a good compromise between these tradeoffs, allowing use of -[Terraform's workspaces feature](/docs/language/state/workspaces.html) to switch +[Terraform's workspaces feature](/language/state/workspaces) to switch conveniently between multiple isolated deployments of the same configuration. Use this section as a starting-point for your approach, but note that @@ -321,7 +318,7 @@ provider "aws" { If workspace IAM roles are centrally managed and shared across many separate Terraform configurations, the role ARNs could also be obtained via a data -source such as [`terraform_remote_state`](/docs/language/state/remote-state-data.html) +source such as [`terraform_remote_state`](/language/state/remote-state-data) to avoid repeating these values. ### Creating and Selecting Workspaces diff --git a/website/docs/language/settings/backends/swift.html.md b/website/docs/language/settings/backends/swift.mdx similarity index 91% rename from website/docs/language/settings/backends/swift.html.md rename to website/docs/language/settings/backends/swift.mdx index b53d83087..0f3483280 100644 --- a/website/docs/language/settings/backends/swift.html.md +++ b/website/docs/language/settings/backends/swift.mdx @@ -1,18 +1,15 @@ --- -layout: "language" -page_title: "Backend Type: swift" -sidebar_current: "docs-backends-types-standard-swift" -description: |- - Terraform can store state remotely in Swift. +page_title: 'Backend Type: swift' +description: Terraform can store state remotely in Swift. --- # swift Stores the state as an artifact in [Swift](http://docs.openstack.org/developer/swift/latest/). -This backend supports [state locking](/docs/language/state/locking.html). +This backend supports [state locking](/language/state/locking). -~> Warning! It is highly recommended that you enable [Object Versioning](https://docs.openstack.org/developer/swift/latest/overview_object_versioning.html) by setting the [`archive_container`](https://www.terraform.io/docs/language/settings/backends/swift.html#archive_container) configuration. This allows for state recovery in the case of accidental deletions and human error. +~> Warning! It is highly recommended that you enable [Object Versioning](https://docs.openstack.org/developer/swift/latest/overview_object_versioning.html) by setting the [`archive_container`](/language/settings/backends/swift#archive_container) configuration. This allows for state recovery in the case of accidental deletions and human error. ## Example Configuration @@ -24,10 +21,11 @@ terraform { } } ``` + This will create a container called `terraform-state` and an object within that container called `tfstate.tf`. It will enable versioning using the `terraform-state-archive` container to contain the older version. For the access credentials we recommend using a -[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). +[partial configuration](/language/settings/backends/configuration#partial-configuration). ## Data Source Configuration @@ -46,7 +44,7 @@ data "terraform_remote_state" "foo" { The following configuration options are supported: * `auth_url` - (Optional) The Identity authentication URL. If omitted, the - `OS_AUTH_URL` environment variable is used. + `OS_AUTH_URL` environment variable is used. * `cloud` - (Optional; required if `auth_url` is not specified) An entry in a `clouds.yaml` file. See the OpenStack `os-client-config` @@ -55,7 +53,7 @@ The following configuration options are supported: environment variable is used. * `region_name` - (Optional) - The region in which to store `terraform.tfstate`. If - omitted, the `OS_REGION_NAME` environment variable is used. + omitted, the `OS_REGION_NAME` environment variable is used. * `container` - (Required) The name of the container to create for storing the Terraform state file. @@ -137,10 +135,10 @@ The following configuration options are supported: certificate. If omitted, the `OS_CACERT` environment variable is used. * `cert` - (Optional) Specify client certificate file for SSL client authentication. - If omitted the `OS_CERT` environment variable is used. + If omitted the `OS_CERT` environment variable is used. * `key` - (Optional) Specify client private key file for SSL client authentication. - If omitted the `OS_KEY` environment variable is used. + If omitted the `OS_KEY` environment variable is used. * `endpoint_type` - (Optional) Specify which type of endpoint to use from the service catalog. It can be set using the OS_ENDPOINT_TYPE environment diff --git a/website/docs/language/settings/index.html.md b/website/docs/language/settings/index.mdx similarity index 78% rename from website/docs/language/settings/index.html.md rename to website/docs/language/settings/index.mdx index cec07d293..213e01f1a 100644 --- a/website/docs/language/settings/index.html.md +++ b/website/docs/language/settings/index.mdx @@ -1,8 +1,9 @@ --- -layout: "language" -page_title: "Terraform Settings - Configuration Language" -sidebar_current: "docs-config-terraform" -description: "The terraform block allows you to configure Terraform behavior, including the Terraform version, backend, integration with Terraform Cloud, and required providers." +page_title: Terraform Settings - Configuration Language +description: >- + The terraform block allows you to configure Terraform behavior, including the + Terraform version, backend, integration with Terraform Cloud, and required + providers. --- # Terraform Settings @@ -32,32 +33,32 @@ following sections. ## Configuring Terraform Cloud The nested `cloud` block configures Terraform Cloud for enabling its -[CLI-driven run workflow](/docs/cloud/run/cli.html). +[CLI-driven run workflow](/cloud-docs/run/cli). -- Refer to [Terraform Cloud Configuration](/docs/language/settings/terraform-cloud.html) for a summary of the `cloud` block's syntax. +- Refer to [Terraform Cloud Configuration](/language/settings/terraform-cloud) for a summary of the `cloud` block's syntax. -- Refer to [Using Terraform Cloud](/docs/cli/cloud/index.html) in the -Terraform CLI documentation for complete details about how to initialize and configure the Terraform Cloud CLI integration. +- Refer to [Using Terraform Cloud](/cli/cloud) in the + Terraform CLI documentation for complete details about how to initialize and configure the Terraform Cloud CLI integration. ## Configuring a Terraform Backend The nested `backend` block configures which state backend Terraform should use. The syntax and behavior of the `backend` block is described in [Backend -Configuration](/docs/language/settings/backends/configuration.html). +Configuration](/language/settings/backends/configuration). ## Specifying a Required Terraform Version > **Hands-on:** Try the [Manage Terraform Versions](https://learn.hashicorp.com/tutorials/terraform/versions?in=terraform/configuration-language) or [Manage Terraform Versions in Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-versions?in=terraform/cloud) tutorials on HashiCorp Learn. The `required_version` setting accepts a [version constraint -string,](/docs/language/expressions/version-constraints.html) which specifies which versions of Terraform +string,](/language/expressions/version-constraints) which specifies which versions of Terraform can be used with your configuration. If the running version of Terraform doesn't match the constraints specified, Terraform will produce an error and exit without taking any further actions. -When you use [child modules](/docs/language/modules/index.html), each module can specify its own +When you use [child modules](/language/modules), each module can specify its own version requirements. The requirements of all modules in the tree must be satisfied. @@ -68,7 +69,7 @@ a minimum Terraform version that has behavior expected by the configuration. The `required_version` setting applies only to the version of Terraform CLI. Terraform's resource types are implemented by provider plugins, whose release cycles are independent of Terraform CLI and of each other. -Use [the `required_providers` block](/docs/language/providers/requirements.html) to manage +Use [the `required_providers` block](/language/providers/requirements) to manage the expected versions for each provider you use. ## Specifying Provider Requirements @@ -90,7 +91,7 @@ terraform { } ``` -For more information, see [Provider Requirements](/docs/language/providers/requirements.html). +For more information, see [Provider Requirements](/language/providers/requirements). ## Experimental Language Features @@ -135,4 +136,4 @@ provider a module is using, if the provider defines a schema for it. This allows the provider to receive module-specific information, and is primarily intended for modules distributed by the same vendor as the associated provider. -For more information, see [Provider Metadata](/docs/internals/provider-meta.html). +For more information, see [Provider Metadata](/internals/provider-meta). diff --git a/website/docs/language/settings/terraform-cloud.html.md b/website/docs/language/settings/terraform-cloud.html.md deleted file mode 100644 index fd1b94b71..000000000 --- a/website/docs/language/settings/terraform-cloud.html.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: "language" -page_title: "Terraform Cloud Configuration - Terraform Settings - Configuration Language" -sidebar_current: "docs-config-terraform" -description: "The nested `cloud` block configures Terraform's integration with Terraform Cloud." ---- - -# Terraform Cloud Configuration - -The main module of a Terraform configuration can integrate with Terraform Cloud to enable its -[CLI-driven run workflow](/docs/cloud/run/cli.html). You only need to configure these settings when you want to use Terraform CLI to interact with Terraform Cloud. Terraform Cloud ignores them when interacting with -Terraform through version control or the API. - -> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. - -You can configure the Terraform Cloud CLI integration by adding a nested `cloud` block within the top-level -`terraform` block: - -```hcl -terraform { - cloud { - organization = "example_corp" - - workspaces { - tags = ["app"] - } - } -} -``` - -You cannot use the CLI integration and a [state backend](/docs/language/settings/backends/index.html) in the same configuration; they are mutually exclusive. A configuration can only provide one `cloud` block and the `cloud` block cannot refer to named values like input variables, locals, or data source attributes. - -Refer to [Using Terraform Cloud](/docs/cli/cloud/index.html) in the Terraform CLI docs for more information. diff --git a/website/docs/language/settings/terraform-cloud.mdx b/website/docs/language/settings/terraform-cloud.mdx new file mode 100644 index 000000000..e76454772 --- /dev/null +++ b/website/docs/language/settings/terraform-cloud.mdx @@ -0,0 +1,33 @@ +--- +page_title: Terraform Cloud Configuration - Terraform Settings - Configuration Language +description: >- + The nested `cloud` block configures Terraform's integration with Terraform + Cloud. +--- + +# Terraform Cloud Configuration + +The main module of a Terraform configuration can integrate with Terraform Cloud to enable its +[CLI-driven run workflow](/cloud-docs/run/cli). You only need to configure these settings when you want to use Terraform CLI to interact with Terraform Cloud. Terraform Cloud ignores them when interacting with +Terraform through version control or the API. + +> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn. + +You can configure the Terraform Cloud CLI integration by adding a nested `cloud` block within the top-level +`terraform` block: + +```hcl +terraform { + cloud { + organization = "example_corp" + + workspaces { + tags = ["app"] + } + } +} +``` + +You cannot use the CLI integration and a [state backend](/language/settings/backends) in the same configuration; they are mutually exclusive. A configuration can only provide one `cloud` block and the `cloud` block cannot refer to named values like input variables, locals, or data source attributes. + +Refer to [Using Terraform Cloud](/cli/cloud) in the Terraform CLI docs for more information. diff --git a/website/docs/language/state/backends.html.md b/website/docs/language/state/backends.mdx similarity index 69% rename from website/docs/language/state/backends.html.md rename to website/docs/language/state/backends.mdx index da957173d..03a119584 100644 --- a/website/docs/language/state/backends.html.md +++ b/website/docs/language/state/backends.mdx @@ -1,15 +1,14 @@ --- -layout: "language" -page_title: "Backends: State Storage and Locking" -sidebar_current: "docs-backends-state" -description: |- - Backends are configured directly in Terraform files in the `terraform` section. +page_title: 'Backends: State Storage and Locking' +description: >- + Backends are configured directly in Terraform files in the `terraform` + section. --- # State Storage and Locking Backends are responsible for storing state and providing an API for -[state locking](/docs/language/state/locking.html). State locking is optional. +[state locking](/language/state/locking). State locking is optional. Despite the state being stored remotely, all Terraform commands such as `terraform console`, the `terraform state` operations, `terraform taint`, @@ -47,15 +46,15 @@ overwrite the remote state. This can be used to do manual fixups if necessary. When manually pushing state, Terraform will attempt to protect you from some potentially dangerous situations: - * **Differing lineage**: The "lineage" is a unique ID assigned to a state - when it is created. If a lineage is different, then it means the states - were created at different times and its very likely you're modifying a - different state. Terraform will not allow this. +- **Differing lineage**: The "lineage" is a unique ID assigned to a state + when it is created. If a lineage is different, then it means the states + were created at different times and its very likely you're modifying a + different state. Terraform will not allow this. - * **Higher serial**: Every state has a monotonically increasing "serial" - number. If the destination state has a higher serial, Terraform will - not allow you to write it since it means that changes have occurred since - the state you're attempting to write. +- **Higher serial**: Every state has a monotonically increasing "serial" + number. If the destination state has a higher serial, Terraform will + not allow you to write it since it means that changes have occurred since + the state you're attempting to write. Both of these protections can be bypassed with the `-force` flag if you're confident you're making the right decision. Even if using the `-force` flag, @@ -64,12 +63,12 @@ prior to forcing the overwrite. ## State Locking -Backends are responsible for supporting [state locking](/docs/language/state/locking.html) +Backends are responsible for supporting [state locking](/language/state/locking) if possible. Not all backends support locking. The -[documentation for each backend](/docs/language/settings/backends/index.html) +[documentation for each backend](/language/settings/backends) includes details on whether it supports locking or not. For more information on state locking, view the -[page dedicated to state locking](/docs/language/state/locking.html). +[page dedicated to state locking](/language/state/locking). diff --git a/website/docs/language/state/import.html.md b/website/docs/language/state/import.mdx similarity index 59% rename from website/docs/language/state/import.html.md rename to website/docs/language/state/import.mdx index 1334269e9..bbbf92d03 100644 --- a/website/docs/language/state/import.html.md +++ b/website/docs/language/state/import.mdx @@ -1,9 +1,8 @@ --- -layout: "language" -page_title: "State: Import Existing Resources" -sidebar_current: "docs-state-import" -description: |- - Terraform stores state which caches the known state of the world the last time Terraform ran. +page_title: 'State: Import Existing Resources' +description: >- + Terraform stores state which caches the known state of the world the last time + Terraform ran. --- # Import Existing Resources @@ -12,4 +11,4 @@ Terraform is able to import existing infrastructure. This allows you take resources you've created by some other means and bring it under Terraform management. To learn more about this, please visit the -[pages dedicated to import](/docs/cli/import/index.html). +[pages dedicated to import](/cli/import). diff --git a/website/docs/language/state/index.html.md b/website/docs/language/state/index.mdx similarity index 77% rename from website/docs/language/state/index.html.md rename to website/docs/language/state/index.mdx index 67072eab2..fea81b2cb 100644 --- a/website/docs/language/state/index.html.md +++ b/website/docs/language/state/index.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "State" -sidebar_current: "docs-state" -description: "An introduction to state, information that Terraform uses to map resources to a configuration, track metadata, and improve performance." +page_title: State +description: >- + An introduction to state, information that Terraform uses to map resources to + a configuration, track metadata, and improve performance. --- # State @@ -17,7 +17,7 @@ but it can also be stored remotely, which works better in a team environment. Terraform uses this local state to create plans and make changes to your infrastructure. Prior to any operation, Terraform does a -[refresh](/docs/cli/commands/refresh.html) to update the state with the +[refresh](/cli/commands/refresh) to update the state with the real infrastructure. The primary purpose of Terraform state is to store bindings between objects in @@ -28,13 +28,13 @@ resource instance, and then potentially update or delete that object in response to future configuration changes. For more information on why Terraform requires state and why Terraform cannot -function without state, please see the page [state purpose](/docs/language/state/purpose.html). +function without state, please see the page [state purpose](/language/state/purpose). ## Inspection and Modification While the format of the state files are just JSON, direct file editing of the state is discouraged. Terraform provides the -[terraform state](/docs/cli/commands/state/index.html) command to perform +[terraform state](/cli/commands/state) command to perform basic modifications of the state using the CLI. The CLI usage and output of the state commands is structured to be @@ -67,13 +67,13 @@ in new versions. Alternatively, there are several integration points which produce JSON output that is specifically intended for consumption by external software: -* [The `terraform output` command](/docs/cli/commands/output.html) -has a `-json` option, for obtaining either the full set of root module output -values or a specific named output value from the latest state snapshot. -* [The `terraform show` command](/docs/cli/commands/show.html) has a `-json` -option for inspecting the latest state snapshot in full, and also for -inspecting saved plan files which include a copy of the prior state at the -time the plan was made. +* [The `terraform output` command](/cli/commands/output) + has a `-json` option, for obtaining either the full set of root module output + values or a specific named output value from the latest state snapshot. +* [The `terraform show` command](/cli/commands/show) has a `-json` + option for inspecting the latest state snapshot in full, and also for + inspecting saved plan files which include a copy of the prior state at the + time the plan was made. A typical way to use these in situations where Terraform is running in automation is to run them immediately after a successful `terraform apply` diff --git a/website/docs/language/state/locking.html.md b/website/docs/language/state/locking.mdx similarity index 77% rename from website/docs/language/state/locking.html.md rename to website/docs/language/state/locking.mdx index 739a4b8c4..970c14f2f 100644 --- a/website/docs/language/state/locking.html.md +++ b/website/docs/language/state/locking.mdx @@ -1,14 +1,13 @@ --- -layout: "language" -page_title: "State: Locking" -sidebar_current: "docs-state-locking" -description: |- - Terraform stores state which caches the known state of the world the last time Terraform ran. +page_title: 'State: Locking' +description: >- + Terraform stores state which caches the known state of the world the last time + Terraform ran. --- # State Locking -If supported by your [backend](/docs/language/settings/backends/index.html), Terraform will lock your +If supported by your [backend](/language/settings/backends), Terraform will lock your state for all operations that could write state. This prevents others from acquiring the lock and potentially corrupting your state. @@ -22,12 +21,12 @@ a status message. If Terraform doesn't output a message, state locking is still occurring if your backend supports it. Not all backends support locking. The -[documentation for each backend](/docs/language/settings/backends/index.html) +[documentation for each backend](/language/settings/backends) includes details on whether it supports locking or not. ## Force Unlock -Terraform has a [force-unlock command](/docs/cli/commands/force-unlock.html) +Terraform has a [force-unlock command](/cli/commands/force-unlock) to manually unlock the state if unlocking failed. **Be very careful with this command.** If you unlock the state when someone diff --git a/website/docs/language/state/purpose.html.md b/website/docs/language/state/purpose.mdx similarity index 93% rename from website/docs/language/state/purpose.html.md rename to website/docs/language/state/purpose.mdx index 44bfef6d1..95e8f09d4 100644 --- a/website/docs/language/state/purpose.html.md +++ b/website/docs/language/state/purpose.mdx @@ -1,9 +1,10 @@ --- -layout: "language" -page_title: "State" -sidebar_current: "docs-state-purpose" -description: |- - Terraform must store state about your managed infrastructure and configuration. This state is used by Terraform to map real world resources to your configuration, keep track of metadata, and to improve performance for large infrastructures. +page_title: State +description: >- + Terraform must store state about your managed infrastructure and + configuration. This state is used by Terraform to map real world resources to + your configuration, keep track of metadata, and to improve performance for + large infrastructures. --- # Purpose of Terraform State @@ -105,7 +106,7 @@ started, but when using Terraform in a team it is important for everyone to be working with the same state so that operations will be applied to the same remote objects. -[Remote state](/docs/language/state/remote.html) is the recommended solution +[Remote state](/language/state/remote) is the recommended solution to this problem. With a fully-featured state backend, Terraform can use remote locking as a measure to avoid two or more different users accidentally running Terraform at the same time, and thus ensure that each Terraform run diff --git a/website/docs/language/state/remote-state-data.html.md b/website/docs/language/state/remote-state-data.html.md deleted file mode 100644 index 10e514600..000000000 --- a/website/docs/language/state/remote-state-data.html.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -layout: "language" -page_title: "The terraform_remote_state Data Source" -sidebar_current: "docs-terraform-datasource-remote-state" -description: |- - Retrieves the root module output values from a Terraform state snapshot stored in a remote backend. ---- - -# The `terraform_remote_state` Data Source - -[backends]: /docs/backends/index.html - -The `terraform_remote_state` data source retrieves the root module output values -from some other Terraform configuration, using the latest state snapshot from -the remote backend. - -This data source is built into Terraform, and is always available; you do not -need to require or configure a provider in order to use it. - --> **Note:** This data source is implemented by a built-in provider, whose -[source address](/docs/language/providers/requirements.html#source-addresses) -is `terraform.io/builtin/terraform`. That provider does not include any other -resources or data sources. - -## Alternative Ways to Share Data Between Configurations - -Sharing data with root module outputs is convenient, but it has drawbacks. -Although `terraform_remote_state` only exposes output values, its user must have -access to the entire state snapshot, which often includes some sensitive -information. - -When possible, we recommend explicitly publishing data for external consumption -to a separate location instead of accessing it via remote state. This lets you -apply different access controls for shared information and state snapshots. - -To share data explicitly between configurations, you can use pairs of managed -resource types and data sources in various providers, including (but not -limited to) the following: - -| System | Publish with... | Read with... | -|--|--|--| -| Alibaba Cloud DNS
(for IP addresses and hostnames) | [`alicloud_alidns_record` resource type](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/alidns_record) | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | -| Amazon Route53
(for IP addresses and hostnames) | [`aws_route53_record` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_record) | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | -| Amazon S3 | [`aws_s3_bucket_object` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_object) | [`aws_s3_bucket_object` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/s3_bucket_object) | -| Amazon SSM Parameter Store | [`aws_ssm_parameter` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_parameter) | [`aws_ssm_parameter` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | -| Azure Automation | [`azurerm_automation_variable_string` resource type](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/automation_variable_string) | [`azurerm_automation_variable_string` data source](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/automation_variable_string) | -| Azure DNS
(for IP addresses and hostnames) | [`azurerm_dns_a_record` resource type](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/dns_a_record), etc | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | -| Google Cloud DNS
(for IP addresses and hostnames) | [`google_dns_record_set` resource type](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/dns_record_set) | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | -| Google Cloud Storage | [`google_storage_bucket_object` resource type](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket_object) | [`google_storage_bucket_object` data source](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/storage_bucket_object) and [`http` data source](https://registry.terraform.io/providers/hashicorp/http/latest/docs/data-sources/http) | -| HashiCorp Consul | [`consul_key_prefix` resource type](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) | [`consul_key_prefix` data source](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/key_prefix) | -| HashiCorp Terraform Cloud | Normal `outputs` terraform block | [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) | -| Kubernetes | [`kubernetes_config_map` resource type](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/config_map) | [`kubernetes_config_map` data source](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/data-sources/config_map) | -| OCI Object Storage | [`oci_objectstorage_bucket` resource type](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/objectstorage_object) | [`oci_objectstorage_bucket` data source](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/objectstorage_object) | - --> These are some common options from the Official Terraform providers, but -there are too many configuration storage options for us to list them all -here, including some in partner and community providers. -Any pair of managed resource type and corresponding data source can potentially -be used to share data between Terraform configurations. See individual provider -documentation to find other possibilities. - -A key advantage of using a separate explicit configuration store instead of -`terraform_remote_state` is that the data can potentially also be read by -systems other than Terraform, such as configuration management or scheduler -systems within your compute instances. For that reason, we recommend selecting -a configuration store that your other infrastructure could potentially make -use of. For example: - -* If you wish to share IP addresses and hostnames, you could publish them as -normal DNS `A`, `AAAA`, `CNAME`, and `SRV` records in a private DNS zone and -then configure your other infrastructure to refer to that zone so you can -find infrastructure objects via your system's built-in DNS resolver. -* If you use HashiCorp Consul then publishing data to the Consul key/value -store or Consul service catalog can make that data also accessible via -[Consul Template](https://github.com/hashicorp/consul-template) -or the -[HashiCorp Nomad](https://www.nomadproject.io/docs/job-specification/template) -`template` stanza. -* If you use Kubernetes then you can -[make Config Maps available to your Pods](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/). - -Some of the data stores listed above are specifically designed for storing -small configuration values, while others are generic blob storage systems. For -those generic systems, you can use -[the `jsonencode` function](https://www.terraform.io/docs/language/functions/jsonencode.html) -and -[the `jsondecode` function](https://www.terraform.io/docs/language/functions/jsondecode.html) respectively -to store and retrieve structured data. - -You can encapsulate the implementation details of retrieving your published -configuration data by writing a -[data-only module](/docs/language/modules/develop/composition.html#data-only-modules) -containing the necessary data source configuration and any necessary -post-processing such as JSON decoding. You can then change that module later -if you switch to a different strategy for sharing data between multiple -Terraform configurations. - -## Usage with Terraform Cloud/Enterprise - -When trying to access remote state outputs in Terraform Cloud/Enterprise, it is recommended to use the `tfe_outputs` data source in the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) instead of relying the `terraform_remote_state` data source. - -See the [full documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) for the `tfe_outputs` data source for more details. - -## Example Usage (`remote` Backend) - -```hcl -data "terraform_remote_state" "vpc" { - backend = "remote" - - config = { - organization = "hashicorp" - workspaces = { - name = "vpc-prod" - } - } -} - -# Terraform >= 0.12 -resource "aws_instance" "foo" { - # ... - subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id -} - -# Terraform <= 0.11 -resource "aws_instance" "foo" { - # ... - subnet_id = "${data.terraform_remote_state.vpc.subnet_id}" -} -``` - -## Example Usage (`local` Backend) - -```hcl -data "terraform_remote_state" "vpc" { - backend = "local" - - config = { - path = "..." - } -} - -# Terraform >= 0.12 -resource "aws_instance" "foo" { - # ... - subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id -} - -# Terraform <= 0.11 -resource "aws_instance" "foo" { - # ... - subnet_id = "${data.terraform_remote_state.vpc.subnet_id}" -} -``` - -## Argument Reference - -The following arguments are supported: - -* `backend` - (Required) The remote backend to use. -* `workspace` - (Optional) The Terraform workspace to use, if the backend - supports workspaces. -* `config` - (Optional; object) The configuration of the remote backend. - Although this argument is listed as optional, most backends require - some configuration. - - The `config` object can use any arguments that would be valid in the - equivalent `terraform { backend "" { ... } }` block. See - [the documentation of your chosen backend](/docs/language/settings/backends/index.html) - for details. - - -> **Note:** If the backend configuration requires a nested block, specify - it here as a normal attribute with an object value. (For example, - `workspaces = { ... }` instead of `workspaces { ... }`.) -* `defaults` - (Optional; object) Default values for outputs, in case the state - file is empty or lacks a required output. - -## Attributes Reference - -In addition to the above, the following attributes are exported: - -* (v0.12+) `outputs` - An object containing every root-level - [output](/docs/language/values/outputs.html) in the remote state. -* (<= v0.11) `` - Each root-level [output](/docs/language/values/outputs.html) - in the remote state appears as a top level attribute on the data source. - -## Root Outputs Only - -Only the root-level output values from the remote state snapshot are exposed -for use elsewhere in your module. Resource data and output values from nested -modules are not accessible. - -If you wish to make a nested module output value accessible as a root module -output value, you must explicitly configure a passthrough in the root module. -For example: - -For example: - -```hcl -module "app" { - source = "..." -} - -output "app_value" { - # This syntax is for Terraform 0.12 or later. - value = module.app.example -} -``` - -In this example, the output value named `example` from the "app" module is -available as the `app_value` root module output value. If this configuration -didn't include the `output "app_value"` block then the data would not be -accessible via `terraform_remote_state`. - -~> **Warning:** Although `terraform_remote_state` doesn't expose any other -state snapshot information for use in configuration, the state snapshot data -is a single object and so any user or server which has enough access to read -the root module output values will also always have access to the full state -snapshot data by direct network requests. Don't use `terraform_remote_state` -if any of the resources in your configuration work with data that you consider -sensitive. diff --git a/website/docs/language/state/remote-state-data.mdx b/website/docs/language/state/remote-state-data.mdx new file mode 100644 index 000000000..8dbda8ccb --- /dev/null +++ b/website/docs/language/state/remote-state-data.mdx @@ -0,0 +1,219 @@ +--- +page_title: The terraform_remote_state Data Source +description: >- + Retrieves the root module output values from a Terraform state snapshot stored + in a remote backend. +--- + +# The `terraform_remote_state` Data Source + +[backends]: /language/settings/backends + +The `terraform_remote_state` data source retrieves the root module output values +from some other Terraform configuration, using the latest state snapshot from +the remote backend. + +This data source is built into Terraform, and is always available; you do not +need to require or configure a provider in order to use it. + +-> **Note:** This data source is implemented by a built-in provider, whose +[source address](/language/providers/requirements#source-addresses) +is `terraform.io/builtin/terraform`. That provider does not include any other +resources or data sources. + +## Alternative Ways to Share Data Between Configurations + +Sharing data with root module outputs is convenient, but it has drawbacks. +Although `terraform_remote_state` only exposes output values, its user must have +access to the entire state snapshot, which often includes some sensitive +information. + +When possible, we recommend explicitly publishing data for external consumption +to a separate location instead of accessing it via remote state. This lets you +apply different access controls for shared information and state snapshots. + +To share data explicitly between configurations, you can use pairs of managed +resource types and data sources in various providers, including (but not +limited to) the following: + +| System | Publish with... | Read with... | +| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba Cloud DNS
(for IP addresses and hostnames) | [`alicloud_alidns_record` resource type](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/alidns_record) | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | +| Amazon Route53
(for IP addresses and hostnames) | [`aws_route53_record` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_record) | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | +| Amazon S3 | [`aws_s3_bucket_object` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_object) | [`aws_s3_bucket_object` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/s3_bucket_object) | +| Amazon SSM Parameter Store | [`aws_ssm_parameter` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_parameter) | [`aws_ssm_parameter` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | +| Azure Automation | [`azurerm_automation_variable_string` resource type](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/automation_variable_string) | [`azurerm_automation_variable_string` data source](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/automation_variable_string) | +| Azure DNS
(for IP addresses and hostnames) | [`azurerm_dns_a_record` resource type](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/dns_a_record), etc | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | +| Google Cloud DNS
(for IP addresses and hostnames) | [`google_dns_record_set` resource type](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/dns_record_set) | Normal DNS lookups, or [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) | +| Google Cloud Storage | [`google_storage_bucket_object` resource type](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket_object) | [`google_storage_bucket_object` data source](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/storage_bucket_object) and [`http` data source](https://registry.terraform.io/providers/hashicorp/http/latest/docs/data-sources/http) | +| HashiCorp Consul | [`consul_key_prefix` resource type](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) | [`consul_key_prefix` data source](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/key_prefix) | +| HashiCorp Terraform Cloud | Normal `outputs` terraform block | [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) | +| Kubernetes | [`kubernetes_config_map` resource type](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/config_map) | [`kubernetes_config_map` data source](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/data-sources/config_map) | +| OCI Object Storage | [`oci_objectstorage_bucket` resource type](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/objectstorage_object) | [`oci_objectstorage_bucket` data source](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/objectstorage_object) | + +-> These are some common options from the Official Terraform providers, but +there are too many configuration storage options for us to list them all +here, including some in partner and community providers. +Any pair of managed resource type and corresponding data source can potentially +be used to share data between Terraform configurations. See individual provider +documentation to find other possibilities. + +A key advantage of using a separate explicit configuration store instead of +`terraform_remote_state` is that the data can potentially also be read by +systems other than Terraform, such as configuration management or scheduler +systems within your compute instances. For that reason, we recommend selecting +a configuration store that your other infrastructure could potentially make +use of. For example: + +* If you wish to share IP addresses and hostnames, you could publish them as + normal DNS `A`, `AAAA`, `CNAME`, and `SRV` records in a private DNS zone and + then configure your other infrastructure to refer to that zone so you can + find infrastructure objects via your system's built-in DNS resolver. +* If you use HashiCorp Consul then publishing data to the Consul key/value + store or Consul service catalog can make that data also accessible via + [Consul Template](https://github.com/hashicorp/consul-template) + or the + [HashiCorp Nomad](https://www.nomadproject.io/docs/job-specification/template) + `template` stanza. +* If you use Kubernetes then you can + [make Config Maps available to your Pods](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/). + +Some of the data stores listed above are specifically designed for storing +small configuration values, while others are generic blob storage systems. For +those generic systems, you can use +[the `jsonencode` function](/language/functions/jsonencode) +and +[the `jsondecode` function](/language/functions/jsondecode) respectively +to store and retrieve structured data. + +You can encapsulate the implementation details of retrieving your published +configuration data by writing a +[data-only module](/language/modules/develop/composition#data-only-modules) +containing the necessary data source configuration and any necessary +post-processing such as JSON decoding. You can then change that module later +if you switch to a different strategy for sharing data between multiple +Terraform configurations. + +## Usage with Terraform Cloud/Enterprise + +When trying to access remote state outputs in Terraform Cloud/Enterprise, it is recommended to use the `tfe_outputs` data source in the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) instead of relying the `terraform_remote_state` data source. + +See the [full documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) for the `tfe_outputs` data source for more details. + +## Example Usage (`remote` Backend) + +```hcl +data "terraform_remote_state" "vpc" { + backend = "remote" + + config = { + organization = "hashicorp" + workspaces = { + name = "vpc-prod" + } + } +} + +# Terraform >= 0.12 +resource "aws_instance" "foo" { + # ... + subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id +} + +# Terraform <= 0.11 +resource "aws_instance" "foo" { + # ... + subnet_id = "${data.terraform_remote_state.vpc.subnet_id}" +} +``` + +## Example Usage (`local` Backend) + +```hcl +data "terraform_remote_state" "vpc" { + backend = "local" + + config = { + path = "..." + } +} + +# Terraform >= 0.12 +resource "aws_instance" "foo" { + # ... + subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id +} + +# Terraform <= 0.11 +resource "aws_instance" "foo" { + # ... + subnet_id = "${data.terraform_remote_state.vpc.subnet_id}" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `backend` - (Required) The remote backend to use. +* `workspace` - (Optional) The Terraform workspace to use, if the backend + supports workspaces. +* `config` - (Optional; object) The configuration of the remote backend. + Although this argument is listed as optional, most backends require + some configuration. + + The `config` object can use any arguments that would be valid in the + equivalent `terraform { backend "" { ... } }` block. See + [the documentation of your chosen backend](/language/settings/backends) + for details. + + -> **Note:** If the backend configuration requires a nested block, specify + it here as a normal attribute with an object value. (For example, + `workspaces = { ... }` instead of `workspaces { ... }`.) +* `defaults` - (Optional; object) Default values for outputs, in case the state + file is empty or lacks a required output. + +## Attributes Reference + +In addition to the above, the following attributes are exported: + +* (v0.12+) `outputs` - An object containing every root-level + [output](/language/values/outputs) in the remote state. +* (<= v0.11) `` - Each root-level [output](/language/values/outputs) + in the remote state appears as a top level attribute on the data source. + +## Root Outputs Only + +Only the root-level output values from the remote state snapshot are exposed +for use elsewhere in your module. Resource data and output values from nested +modules are not accessible. + +If you wish to make a nested module output value accessible as a root module +output value, you must explicitly configure a passthrough in the root module. +For example: + +For example: + +```hcl +module "app" { + source = "..." +} + +output "app_value" { + # This syntax is for Terraform 0.12 or later. + value = module.app.example +} +``` + +In this example, the output value named `example` from the "app" module is +available as the `app_value` root module output value. If this configuration +didn't include the `output "app_value"` block then the data would not be +accessible via `terraform_remote_state`. + +~> **Warning:** Although `terraform_remote_state` doesn't expose any other +state snapshot information for use in configuration, the state snapshot data +is a single object and so any user or server which has enough access to read +the root module output values will also always have access to the full state +snapshot data by direct network requests. Don't use `terraform_remote_state` +if any of the resources in your configuration work with data that you consider +sensitive. diff --git a/website/docs/language/state/remote.html.md b/website/docs/language/state/remote.mdx similarity index 84% rename from website/docs/language/state/remote.html.md rename to website/docs/language/state/remote.mdx index b9cf39d64..77cce472c 100644 --- a/website/docs/language/state/remote.html.md +++ b/website/docs/language/state/remote.mdx @@ -1,9 +1,8 @@ --- -layout: "language" -page_title: "State: Remote Storage" -sidebar_current: "docs-state-remote" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. +page_title: 'State: Remote Storage' +description: >- + Terraform can store the state remotely, making it easier to version and work + with in a team. --- # Remote State @@ -19,13 +18,13 @@ which can then be shared between all members of a team. Terraform supports storing state in [Terraform Cloud](https://www.hashicorp.com/products/terraform/), [HashiCorp Consul](https://www.consul.io/), Amazon S3, Azure Blob Storage, Google Cloud Storage, Alibaba Cloud OSS, and more. -Remote state is implemented by a [backend](/docs/language/settings/backends/index.html) or by +Remote state is implemented by a [backend](/language/settings/backends) or by Terraform Cloud, both of which you can configure in your configuration's root module. ## Delegation and Teamwork Remote state allows you to share -[output values](/docs/language/values/outputs.html) with other configurations. +[output values](/language/values/outputs) with other configurations. This allows your infrastructure to be decomposed into smaller components. Put another way, remote state also allows teams to share infrastructure @@ -39,7 +38,7 @@ you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through remote state and have other Terraform states consume that. For example usage, see -[the `terraform_remote_state` data source](/docs/language/state/remote-state-data.html). +[the `terraform_remote_state` data source](/language/state/remote-state-data). While remote state can be a convenient, built-in mechanism for sharing data between configurations, you may prefer to use more general stores to @@ -53,7 +52,7 @@ another that consumes those values using ## Locking and Teamwork For fully-featured remote backends, Terraform can also use -[state locking](/docs/language/state/locking.html) to prevent concurrent runs of +[state locking](/language/state/locking) to prevent concurrent runs of Terraform against the same state. [Terraform Cloud by HashiCorp](https://www.hashicorp.com/products/terraform/) diff --git a/website/docs/language/state/sensitive-data.html.md b/website/docs/language/state/sensitive-data.mdx similarity index 79% rename from website/docs/language/state/sensitive-data.html.md rename to website/docs/language/state/sensitive-data.mdx index 49f5c1270..63f624751 100644 --- a/website/docs/language/state/sensitive-data.html.md +++ b/website/docs/language/state/sensitive-data.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "State: Sensitive Data" -sidebar_current: "docs-state-sensitive-data" -description: |- - Sensitive data in Terraform state. +page_title: 'State: Sensitive Data' +description: Sensitive data in Terraform state. --- # Sensitive Data in State @@ -15,7 +12,7 @@ passwords. When using local state, state is stored in plain-text JSON files. -When using [remote state](/docs/language/state/remote.html), state is only ever held in +When using [remote state](/language/state/remote), state is only ever held in memory when used by Terraform. It may be encrypted at rest, but this depends on the specific remote state backend. @@ -30,10 +27,10 @@ and some backends can be configured to encrypt the state data at rest. For example: -- [Terraform Cloud](/docs/cloud/index.html) always encrypts state at rest and +- [Terraform Cloud](/cloud) always encrypts state at rest and protects it with TLS in transit. Terraform Cloud also knows the identity of the user requesting state and maintains a history of state changes. This can - be used to control access and track activity. [Terraform Enterprise](/docs/enterprise/index.html) + be used to control access and track activity. [Terraform Enterprise](/enterprise) also supports detailed audit logging. - The S3 backend supports encryption at rest when the `encrypt` option is enabled. IAM policies and logging can be used to identify any invalid access. diff --git a/website/docs/language/state/workspaces.html.md b/website/docs/language/state/workspaces.mdx similarity index 85% rename from website/docs/language/state/workspaces.html.md rename to website/docs/language/state/workspaces.mdx index 8dcb7b5f4..a3f38d447 100644 --- a/website/docs/language/state/workspaces.html.md +++ b/website/docs/language/state/workspaces.mdx @@ -1,16 +1,15 @@ --- -layout: "language" -page_title: "State: Workspaces" -sidebar_current: "docs-state-workspaces" -description: |- - Workspaces allow the use of multiple states with a single configuration directory. +page_title: 'State: Workspaces' +description: >- + Workspaces allow the use of multiple states with a single configuration + directory. --- # Workspaces -Each Terraform configuration has an associated [backend](/docs/language/settings/backends/index.html) +Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how operations are executed and where persistent data such as -[the Terraform state](https://www.terraform.io/docs/language/state/purpose.html) are +[the Terraform state](/language/state/purpose) are stored. The persistent data stored in the backend belongs to a _workspace_. Initially @@ -25,17 +24,17 @@ credentials. Multiple workspaces are currently supported by the following backends: - * [AzureRM](/docs/language/settings/backends/azurerm.html) - * [Consul](/docs/language/settings/backends/consul.html) - * [COS](/docs/language/settings/backends/cos.html) - * [etcdv3](/docs/language/settings/backends/etcdv3.html) - * [GCS](/docs/language/settings/backends/gcs.html) - * [Kubernetes](/docs/language/settings/backends/kubernetes.html) - * [Local](/docs/language/settings/backends/local.html) - * [Manta](/docs/language/settings/backends/manta.html) - * [Postgres](/docs/language/settings/backends/pg.html) - * [Remote](/docs/language/settings/backends/remote.html) - * [S3](/docs/language/settings/backends/s3.html) +* [AzureRM](/language/settings/backends/azurerm) +* [Consul](/language/settings/backends/consul) +* [COS](/language/settings/backends/cos) +* [etcdv3](/language/settings/backends/etcdv3) +* [GCS](/language/settings/backends/gcs) +* [Kubernetes](/language/settings/backends/kubernetes) +* [Local](/language/settings/backends/local) +* [Manta](/language/settings/backends/manta) +* [Postgres](/language/settings/backends/pg) +* [Remote](/language/settings/backends/remote) +* [S3](/language/settings/backends/s3) In the 0.9 line of Terraform releases, this concept was known as "environment". It was renamed in 0.10 based on feedback about confusion caused by the @@ -44,9 +43,9 @@ organizations that use Terraform. -> **Note**: The Terraform CLI workspace concept described in this document is different from but related to the Terraform Cloud -[workspace](/docs/cloud/workspaces/index.html) concept. +[workspace](/cloud-docs/workspaces) concept. If you use multiple Terraform CLI workspaces in a single Terraform configuration -and are migrating that configuration to Terraform Cloud, refer to [Initializing and Migrating](/docs/cli/cloud/migrating.html). +and are migrating that configuration to Terraform Cloud, refer to [Initializing and Migrating](/cli/cloud/migrating). ## Using Workspaces @@ -143,7 +142,7 @@ In this case, the backend used for each deployment often belongs to that deployment, with different credentials and access controls. Named workspaces are _not_ a suitable isolation mechanism for this scenario. -Instead, use one or more [re-usable modules](/docs/language/modules/develop/index.html) to +Instead, use one or more [re-usable modules](/language/modules/develop) to represent the common elements, and then represent each instance as a separate configuration that instantiates those common elements in the context of a different backend. In that case, the root module of each configuration will @@ -173,7 +172,7 @@ another using paired resources types and data sources. For example: * If a Terraform state for one configuration is stored in a remote backend that is accessible to other configurations then - [`terraform_remote_state`](/docs/language/state/remote-state-data.html) + [`terraform_remote_state`](/language/state/remote-state-data) can be used to directly consume its root module outputs from those other configurations. This creates a tighter coupling between configurations, but avoids the need for the "producer" configuration to explicitly @@ -191,9 +190,9 @@ local-only `terraform.tfstate`; some teams commit these files to version control, although using a remote backend instead is recommended when there are multiple collaborators. -For [remote state](/docs/language/state/remote.html), the workspaces are stored -directly in the configured [backend](/docs/language/settings/backends/index.html). For example, if you -use [Consul](/docs/language/settings/backends/consul.html), the workspaces are stored +For [remote state](/language/state/remote), the workspaces are stored +directly in the configured [backend](/language/settings/backends). For example, if you +use [Consul](/language/settings/backends/consul), the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping. diff --git a/website/docs/language/syntax/configuration.html.md b/website/docs/language/syntax/configuration.mdx similarity index 92% rename from website/docs/language/syntax/configuration.html.md rename to website/docs/language/syntax/configuration.mdx index 5dd06b28e..01467288b 100644 --- a/website/docs/language/syntax/configuration.html.md +++ b/website/docs/language/syntax/configuration.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Syntax - Configuration Language" -sidebar_current: "docs-config-syntax" -description: "Key constructs of the native Terraform language syntax, including identifiers, arguments, blocks, and comments." +page_title: Syntax - Configuration Language +description: >- + Key constructs of the native Terraform language syntax, including identifiers, + arguments, blocks, and comments. --- # Configuration Syntax @@ -15,7 +15,7 @@ those constructs are built from. This page describes the _native syntax_ of the Terraform language, which is a rich language designed to be relatively easy for humans to read and write. The constructs in the Terraform language can also be expressed in -[JSON syntax](/docs/language/syntax/json.html), which is harder for humans +[JSON syntax](/language/syntax/json), which is harder for humans to read and edit but easier to generate and parse programmatically. This low-level syntax of the Terraform language is defined in terms of a @@ -46,7 +46,7 @@ after the equals sign is the argument's value. The context where the argument appears determines what value types are valid (for example, each resource type has a schema that defines the types of its arguments), but many arguments accept arbitrary -[expressions](/docs/language/expressions/index.html), which allow the value to +[expressions](/language/expressions), which allow the value to either be specified literally or generated from other values programmatically. -> **Note:** Terraform's configuration language is based on a more general diff --git a/website/docs/language/syntax/index.html.md b/website/docs/language/syntax/index.mdx similarity index 53% rename from website/docs/language/syntax/index.html.md rename to website/docs/language/syntax/index.mdx index ccd8a67d9..742a40fef 100644 --- a/website/docs/language/syntax/index.html.md +++ b/website/docs/language/syntax/index.mdx @@ -1,7 +1,8 @@ --- -layout: "language" -page_title: "Syntax Overview - Configuration Language" -description: "Terraform language syntax for both the native and JSON variants. Also learn formatting conventions that you can enforce with terraform fmt." +page_title: Syntax Overview - Configuration Language +description: >- + Terraform language syntax for both the native and JSON variants. Also learn + formatting conventions that you can enforce with terraform fmt. --- # Syntax @@ -10,13 +11,13 @@ The majority of the Terraform language documentation focuses on the practical uses of the language and the specific constructs it uses. The pages in this section offer a more abstract view of the Terraform language. -- [Configuration Syntax](/docs/language/syntax/configuration.html) describes the native +- [Configuration Syntax](/language/syntax/configuration) describes the native grammar of the Terraform language. -- [JSON Configuration Syntax](/docs/language/syntax/json.html) documents +- [JSON Configuration Syntax](/language/syntax/json) documents how to represent Terraform language constructs in the pure JSON variant of the Terraform language. Terraform's JSON syntax is unfriendly to humans, but can be very useful when generating infrastructure as code with other systems that don't have a readily available HCL library. -- [Style Conventions](/docs/language/syntax/style.html) documents some commonly +- [Style Conventions](/language/syntax/style) documents some commonly accepted formatting guidelines for Terraform code. These conventions can be - enforced automatically with [`terraform fmt`](/docs/cli/commands/fmt.html). + enforced automatically with [`terraform fmt`](/cli/commands/fmt). diff --git a/website/docs/language/syntax/json.html.md b/website/docs/language/syntax/json.mdx similarity index 95% rename from website/docs/language/syntax/json.html.md rename to website/docs/language/syntax/json.mdx index 32a69578e..477ce9fd7 100644 --- a/website/docs/language/syntax/json.html.md +++ b/website/docs/language/syntax/json.mdx @@ -1,14 +1,14 @@ --- -layout: "language" -page_title: "JSON Configuration Syntax - Configuration Language" -sidebar_current: "docs-config-syntax-json" -description: "Learn about the JSON-compatible language syntax, including file structure, expression mapping, block mapping, and block-type-specific exceptions." +page_title: JSON Configuration Syntax - Configuration Language +description: >- + Learn about the JSON-compatible language syntax, including file structure, + expression mapping, block mapping, and block-type-specific exceptions. --- # JSON Configuration Syntax Most Terraform configurations are written in -[the native Terraform language syntax](/docs/language/syntax/configuration.html), which is designed to be +[the native Terraform language syntax](/language/syntax/configuration), which is designed to be relatively easy for humans to read and update. Terraform also supports an alternative syntax that is JSON-compatible. This @@ -92,7 +92,7 @@ different (see the [block-type-specific exceptions](#block-type-specific-excepti correspond either to argument names or to nested block type names. * Where a property corresponds to an argument that accepts - [arbitrary expressions](/docs/language/expressions/index.html) in the native syntax, the + [arbitrary expressions](/language/expressions) in the native syntax, the property value is mapped to an expression as described under [_Expression Mapping_](#expression-mapping) below. For arguments that do _not_ accept arbitrary expressions, the interpretation of the property @@ -109,7 +109,7 @@ different (see the [block-type-specific exceptions](#block-type-specific-excepti ## Expression Mapping Since JSON grammar is not able to represent all of the Terraform language -[expression syntax](/docs/language/expressions/index.html), JSON values interpreted as expressions +[expression syntax](/language/expressions), JSON values interpreted as expressions are mapped as follows: | JSON | Terraform Language Interpretation | @@ -121,7 +121,7 @@ are mapped as follows: | Array | Each element is mapped per this table, producing a `tuple(...)` value with suitable element types. | | Null | A literal `null`. | -[string template]: /docs/language/expressions/strings.html#string-templates +[string template]: /language/expressions/strings#string-templates When a JSON string is encountered in a location where arbitrary expressions are expected, its value is first parsed as a [string template][] @@ -259,7 +259,7 @@ preserved exactly. ### Comment Properties Although we do not recommend hand-editing of JSON syntax configuration files --- this format is primarily intended for programmatic generation and consumption -- +\-- this format is primarily intended for programmatic generation and consumption -- a limited form of _comments_ are allowed inside JSON objects that represent block bodies using a special property name: diff --git a/website/docs/language/syntax/style.html.md b/website/docs/language/syntax/style.mdx similarity index 76% rename from website/docs/language/syntax/style.html.md rename to website/docs/language/syntax/style.mdx index bbbf090f7..b29195dca 100644 --- a/website/docs/language/syntax/style.html.md +++ b/website/docs/language/syntax/style.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Style Conventions - Configuration Language" -sidebar_current: "docs-config-style" -description: "Learn recommended formatting conventions for the Terraform language and a command to automatically enforce them." +page_title: Style Conventions - Configuration Language +description: >- + Learn recommended formatting conventions for the Terraform language and a + command to automatically enforce them. --- # Style Conventions @@ -14,17 +14,17 @@ for consistency between files and modules written by different teams. Automatic source code formatting tools may apply these conventions automatically. --> **Note**: You can enforce these conventions automatically by running [`terraform fmt`](/docs/cli/commands/fmt.html). +-> **Note**: You can enforce these conventions automatically by running [`terraform fmt`](/cli/commands/fmt). * Indent two spaces for each nesting level. * When multiple arguments with single-line values appear on consecutive lines at the same nesting level, align their equals signs: - ```hcl - ami = "abc123" - instance_type = "t2.micro" - ``` + ```hcl + ami = "abc123" + instance_type = "t2.micro" + ``` * When both arguments and blocks appear together inside a block body, place all of the arguments together at the top and then place nested @@ -39,22 +39,22 @@ automatically. meta-argument blocks _last_ and separate them from other blocks with one blank line. - ```hcl - resource "aws_instance" "example" { - count = 2 # meta-argument first + ```hcl + resource "aws_instance" "example" { + count = 2 # meta-argument first - ami = "abc123" - instance_type = "t2.micro" + ami = "abc123" + instance_type = "t2.micro" - network_interface { - # ... - } - - lifecycle { # meta-argument block last - create_before_destroy = true - } + network_interface { + # ... } - ``` + + lifecycle { # meta-argument block last + create_before_destroy = true + } + } + ``` * Top-level blocks should always be separated from one another by one blank line. Nested blocks should also be separated by blank lines, except @@ -68,4 +68,3 @@ automatically. `ephemeral_block_device` on `aws_instance` form a family of block types describing AWS block devices, and can therefore be grouped together and mixed.) - diff --git a/website/upgrade-guides/0-10.html.markdown b/website/docs/language/upgrade-guides/0-10.mdx similarity index 90% rename from website/upgrade-guides/0-10.html.markdown rename to website/docs/language/upgrade-guides/0-10.mdx index c33b6186b..f12f9979f 100644 --- a/website/upgrade-guides/0-10.html.markdown +++ b/website/docs/language/upgrade-guides/0-10.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform 0.10" -sidebar_current: "upgrade-guides-0-10" -description: |- - Upgrading to Terraform v0.10 +page_title: Upgrading to Terraform 0.10 +description: Upgrading to Terraform v0.10 --- # Upgrading to Terraform v0.10 @@ -28,7 +25,7 @@ in the navigation) if you are upgrading directly from an earlier version. As of v0.10, provider plugins are no longer included in the main Terraform distribution. Instead, they are distributed separately and installed automatically by -[the `terraform init` command](/docs/cli/commands/init.html). +[the `terraform init` command](/cli/commands/init). In the long run, this new approach should be beneficial to anyone who wishes to upgrade a specific provider to get new functionality without also @@ -37,7 +34,7 @@ In the short term, it just means a smaller distribution package and thus avoiding the need to download tens of providers that may never be used. Provider plugins are now also versioned separately from Terraform itself. -[Version constraints](/docs/language/providers/configuration.html#provider-versions) +[Version constraints](/language/providers/configuration#provider-versions) can be specified in configuration to ensure that new major releases (which may have breaking changes) are not automatically installed. @@ -48,7 +45,7 @@ step after a Terraform configuration is cloned from version control, and will also install any necessary modules and configure any remote backend. **Action:** For "production" configurations, consider adding -[provider version constraints](/docs/language/providers/configuration.html#provider-versions), +[provider version constraints](/language/providers/configuration#provider-versions), as suggested by the `terraform init` output, to prevent new major versions of plugins from being automatically installed in future. @@ -66,10 +63,10 @@ third-party providers released on the Terraform Registry. In the mean time, third-party providers can be installed by placing them in the user plugins directory: -Operating system | User plugins directory -------------------|----------------------- -Windows | `%APPDATA%\terraform.d\plugins` -All other systems | `~/.terraform.d/plugins` +| Operating system | User plugins directory | +| ----------------- | ------------------------------- | +| Windows | `%APPDATA%\terraform.d\plugins` | +| All other systems | `~/.terraform.d/plugins` | Maintainers of third-party providers may optionally make use of the new versioning mechanism by naming provider binaries @@ -104,9 +101,9 @@ For example, if `module.example` contains a module itself, called `module.example` _and_ `module.example.module.examplechild`. This also applies to other Terraform features that use -[resource addressing](/docs/cli/state/resource-addressing.html) syntax. +[resource addressing](/cli/state/resource-addressing) syntax. This includes some of the subcommands of -[`terraform state`](/docs/cli/commands/state/index.html). +[`terraform state`](/cli/commands/state). **Action:** If running Terraform with `-target` in automation, review usage to ensure that selecting additional resources in child modules will not have diff --git a/website/upgrade-guides/0-11.html.markdown b/website/docs/language/upgrade-guides/0-11.mdx similarity index 95% rename from website/upgrade-guides/0-11.html.markdown rename to website/docs/language/upgrade-guides/0-11.mdx index 60f7708ad..76daf9aa8 100644 --- a/website/upgrade-guides/0-11.html.markdown +++ b/website/docs/language/upgrade-guides/0-11.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform 0.11" -sidebar_current: "upgrade-guides-0-11" -description: |- - Upgrading to Terraform v0.11 +page_title: Upgrading to Terraform 0.11 +description: Upgrading to Terraform v0.11 --- # Upgrading to Terraform v0.11 @@ -96,7 +93,7 @@ situations: * If a `provider` block is present in a child module, it must either contain a complete configuration for its associated provider or a configuration must be passed from the parent module using - [the new `providers` attribute](/docs/configuration-0-11/modules.html#providers-within-modules). + [the new `providers` attribute](/language/configuration-0-11/modules#providers-within-modules). In the latter case, an empty provider block is a placeholder that declares that the child module requires a configuration to be passed from its parent. @@ -157,7 +154,7 @@ now inherit only as a whole, rather than on a per-argument basis. **Action**: In existing configurations where a descendent module inherits _aliased_ providers from an ancestor module, use -[the new `providers` attribute](/docs/configuration-0-11/modules.html#providers-within-modules) +[the new `providers` attribute](/language/configuration-0-11/modules#providers-within-modules) to explicitly pass those aliased providers. **Action**: Consider refactoring existing configurations so that all provider @@ -260,13 +257,13 @@ resource "aws_vpc" "example" { ``` After the above refactoring, run `terraform apply` to re-synchoronize -Terraform's record (in [the Terraform state](/docs/language/state/index.html)) of the +Terraform's record (in [the Terraform state](/language/state)) of the location of each resource's provider configuration. This should make no changes to actual infrastructure, since no resource configurations were changed. For more details on the explicit `providers` map, and discussion of more complex possibilities such as child modules with additional (aliased) provider -configurations, see [_Providers Within Modules_](/docs/configuration-0-11/modules.html#providers-within-modules). +configurations, see [_Providers Within Modules_](/language/configuration-0-11/modules#providers-within-modules). ## Error Checking for Output Values diff --git a/website/upgrade-guides/0-12.html.markdown b/website/docs/language/upgrade-guides/0-12.mdx similarity index 97% rename from website/upgrade-guides/0-12.html.markdown rename to website/docs/language/upgrade-guides/0-12.mdx index 8c72aa1ee..42b490f5d 100644 --- a/website/upgrade-guides/0-12.html.markdown +++ b/website/docs/language/upgrade-guides/0-12.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform 0.12" -sidebar_current: "upgrade-guides-0-12" -description: |- - Upgrading to Terraform v0.12 +page_title: Upgrading to Terraform 0.12 +description: Upgrading to Terraform v0.12 --- # Upgrading to Terraform v0.12 @@ -16,14 +13,13 @@ to cover the most common upgrade concerns and issues. For most users, upgrading configuration should be completely automatic. Some simple configurations will require no changes at all, and most other configurations can be prepared by running -[the automatic upgrade tool](/docs/cli/commands/0.12upgrade.html). Please read on +[the automatic upgrade tool](/cli/commands/0.12upgrade). Please read on for more information and recommendations on the upgrade process. -> If you are a developer maintaining a provider plugin, please see -[the documentation on 0.12 compatibility for providers](/docs/extend/terraform-0.12-compatibility.html) +[the documentation on 0.12 compatibility for providers](/plugin/sdkv2/guides/terraform-0.12-compatibility) to learn more about the changes that are required. - ## Upgrade to Terraform 0.11 first We strongly recommend completing an upgrade to the latest Terraform v0.11 @@ -32,7 +28,7 @@ required for the previous major version upgrades separately, rather than making multiple changes at once. In particular, if you are upgrading from a Terraform version prior to v0.9, -you _must_ first [upgrade to Terraform v0.9](/upgrade-guides/0-9.html) and +you _must_ first [upgrade to Terraform v0.9](/language/upgrade-guides/0-9) and switch to initializing with `terraform init`, because v0.12 no longer includes the functionality for automatically migrating from the legacy remote state mechanism. @@ -448,7 +444,7 @@ in retrospect it was an obvious consequence of how the compatibility mechanism was implemented. If you have expressions in your modules that produce a list of strings by using list brackets with a mixture of string and list-of-string sub-expressions, you will need to rewrite this to explicitly use -[the `flatten` function](/docs/language/functions/flatten.html) +[the `flatten` function](/language/functions/flatten) to make the special treatment more obvious to the reader: ```hcl @@ -519,7 +515,7 @@ even though it was then generally inconvenient to work with those values elsewhere in the module due to limitations of the index syntax, `element` function, and `lookup` function. -Terraform now allows various [type constraints](/docs/language/expressions/type-constraints.html) +Terraform now allows various [type constraints](/language/expressions/type-constraints) to be specified, as part of the language's new type system and generalized functions and operators. However, because lists and maps of non-string values were not officially supported in 0.11, existing configurations do not have @@ -557,7 +553,7 @@ child/child.tf:1,1-19: element 0: string required. ``` To fix this, change the `type` argument from `list(string)` or `map(string)` -to a more appropriate [type constraint](/docs/language/expressions/type-constraints.html). +to a more appropriate [type constraint](/language/expressions/type-constraints). If you're not sure what type constraint to use yet, another option is to use the type constraint `any`, which will effectively disable validation and @@ -821,13 +817,13 @@ possible and most policies will continue to work without modification. However, there are some important changes and certain policies will need to modified. More information on the changes can be found in our page on [using Sentinel with -Terraform 0.12](/docs/cloud/sentinel/sentinel-tf-012.html). +Terraform 0.12](/cloud-docs/sentinel/sentinel-tf-012). It's strongly advised that you test your Sentinel policies after upgrading to Terraform 0.12 to ensure they continue to work as expected. [Mock -generation](/docs/cloud/sentinel/mock.html) has also been updated to +generation](/cloud-docs/sentinel/mock) has also been updated to produce mock data for the Sentinel imports as they appear in Terraform 0.12. For more information on testing a policy with 0.11 and 0.12 at the same time, see the section on [testing a policy with 0.11 and 0.12 -simultaneously](/docs/cloud/sentinel/sentinel-tf-012.html#testing-a-policy-with-0-11-and-0-12-simultaneously). +simultaneously](/cloud-docs/sentinel/sentinel-tf-012#testing-a-policy-with-0-11-and-0-12-simultaneously). diff --git a/website/upgrade-guides/0-13.html.markdown b/website/docs/language/upgrade-guides/0-13.mdx similarity index 95% rename from website/upgrade-guides/0-13.html.markdown rename to website/docs/language/upgrade-guides/0-13.mdx index 96fda4b96..14e6be4fb 100644 --- a/website/upgrade-guides/0-13.html.markdown +++ b/website/docs/language/upgrade-guides/0-13.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform v0.13" -sidebar_current: "upgrade-guides-0-13" -description: |- - Upgrading to Terraform v0.13 +page_title: Upgrading to Terraform v0.13 +description: Upgrading to Terraform v0.13 --- # Upgrading to Terraform v0.13 @@ -117,7 +114,7 @@ following command: As mentioned in the error message, Terraform v0.13 includes an automatic upgrade command -[`terraform 0.13upgrade`](/docs/cli/commands/0.13upgrade.html) +[`terraform 0.13upgrade`](/cli/commands/0.13upgrade) that is able to automatically generate source addresses for unlabelled providers by consulting the same lookup table that was previously used for Terraform v0.12 provider installation. This command will automatically modify @@ -129,18 +126,18 @@ because it will generate the recommended explicit source addresses for providers in the "hashicorp" namespace. For more information on declaring provider dependencies, see -[Provider Requirements](/docs/language/providers/requirements.html). +[Provider Requirements](/language/providers/requirements). That page also includes some guidance on how to write provider dependencies for a module that must remain compatible with both Terraform v0.12 and Terraform v0.13; the `terraform 0.13upgrade` result includes a conservative version constraint for Terraform v0.13 or later, which you can weaken to `>= 0.12.26` if you follow the guidelines in -[v0.12-Compatible Provider Requirements](/docs/language/providers/requirements.html#v0-12-compatible-provider-requirements). +[v0.12-Compatible Provider Requirements](/language/providers/requirements#v0-12-compatible-provider-requirements). Each module must declare its own set of provider requirements, so if you have a configuration which calls other modules then you'll need to run this upgrade command for each module separately. -[The `terraform 0.13upgrade documentation`](/docs/cli/commands/0.13upgrade.html) +[The `terraform 0.13upgrade documentation`](/cli/commands/0.13upgrade) includes an example of running the upgrade process across all directories under a particular prefix that contain `.tf` files using some common Unix command line tools, which may be useful if you want to upgrade all modules in a single @@ -149,7 +146,7 @@ repository at once. After you've added explicit provider source addresses to your configuration, run `terraform init` again to re-run the provider installer. --> **Action:** Either run [`terraform 0.13upgrade`](/docs/cli/commands/0.13upgrade.html) for each of your modules, or manually update the provider declarations to use explicit source addresses. +-> **Action:** Either run [`terraform 0.13upgrade`](/cli/commands/0.13upgrade) for each of your modules, or manually update the provider declarations to use explicit source addresses. The upgrade tool described above only updates references in your configuration. The Terraform state also includes references to provider configurations which @@ -164,7 +161,7 @@ from your configuration after upgrading. If you are using Terraform Cloud or Terraform Enterprise with the VCS-driven workflow (as opposed to CLI-driven runs), refer to -[The UI- and VCS-driven Run Workflow](/docs/cloud/run/ui.html) to learn how +[The UI- and VCS-driven Run Workflow](/cloud-docs/run/ui) to learn how to manually start a run after you select a Terraform v0.13 release for your workspace. @@ -232,12 +229,12 @@ Terraform under: Terraform v0.13 introduces some additional options for customizing where Terraform looks for providers in the local filesystem. For more information on -those new options, see [Provider Installation](/docs/cli/config/config-file.html#provider-installation). +those new options, see [Provider Installation](/cli/config/config-file#provider-installation). If you use only providers that are automatically installable from Terraform provider registries but still want to avoid Terraform re-downloading them from registries each time, Terraform v0.13 includes -[the `terraform providers mirror` command](/docs/cli/commands/providers/mirror.html) +[the `terraform providers mirror` command](/cli/commands/providers/mirror) which you can use to automatically populate a local directory based on the requirements of the current configuration file: @@ -408,7 +405,7 @@ The provisioner's `connection` configuration can refer to that value via `self`, whereas referring directly to `aws_instance.example.private_ip` in that context is forbidden. -[Provisioners are a last resort](/docs/language/resources/provisioners/syntax.html#provisioners-are-a-last-resort), +[Provisioners are a last resort](/language/resources/provisioners/syntax#provisioners-are-a-last-resort), so we recommend avoiding both create-time and destroy-time provisioners wherever possible. Other options for destroy-time actions include using `systemd` to run commands within your virtual machines during shutdown or using virtual @@ -441,6 +438,7 @@ accurate plan, and so there is no replacement mechanism in Terraform v0.13 to restore the previous behavior. ## Frequently Asked Questions + ### Why do I see `-/provider` during init? Provider source addresses starting with `registry.terraform.io/-/` are a special @@ -464,7 +462,7 @@ see output like this during your first `init`: ``` Terraform found providers `null` and `random` in the statefile without a -namespace. Terraform *also* found `hashicorp/null` and `hashicorp/random` in the +namespace. Terraform _also_ found `hashicorp/null` and `hashicorp/random` in the configuration files. Providers in configuration are automatically assumed to be default (HashiCorp) providers, while providers found in state are first looked up in the registry. diff --git a/website/upgrade-guides/0-14.html.markdown b/website/docs/language/upgrade-guides/0-14.mdx similarity index 95% rename from website/upgrade-guides/0-14.html.markdown rename to website/docs/language/upgrade-guides/0-14.mdx index ce73b8b12..684b63f42 100644 --- a/website/upgrade-guides/0-14.html.markdown +++ b/website/docs/language/upgrade-guides/0-14.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform v0.14" -sidebar_current: "upgrade-guides-0-14" -description: |- - Upgrading to Terraform v0.14 +page_title: Upgrading to Terraform v0.14 +description: Upgrading to Terraform v0.14 --- # Upgrading to Terraform v0.14 @@ -31,7 +28,7 @@ the previous upgrade guides for any considerations that may be relevant to you. In particular, Terraform v0.14 no longer includes the `terraform 0.13upgrade` command for automatically inserting -[provider requirements](/docs/language/providers/requirements.html) +[provider requirements](/language/providers/requirements) into existing modules, and the automatic mechanisms to upgrade legacy provider references in the Terraform state. You will need to successfully complete a `terraform apply` at least once under Terraform v0.13 before upgrading an @@ -83,7 +80,7 @@ represented in files that can be included in a version control system and code review process. To better meet that goal, Terraform v0.14 introduces a new -[dependency lock file](/docs/language/dependency-lock.html), +[dependency lock file](/language/files/dependency-lock), which Terraform will generate automatically after running `terraform init` in the same directory as your configuration's root module. This file includes the specific version numbers selected for each provider, and also includes @@ -132,7 +129,7 @@ v0.14 which can support a mixture of official, partner, community and in-house providers in a single configuration. If you followed the advice from the Terraform v0.13 upgrade guide about -[assigning your in-house providers their own unique source addresses](0-13.html#in-house-providers), +[assigning your in-house providers their own unique source addresses](/language/upgrade-guides/0-13#in-house-providers), and you're distributing your in-house providers to Terraform through one of the documented mechanisms, Terraform should handle selecting a version and recording its checksums in the same way for all of the providers you use. @@ -159,7 +156,7 @@ network mirrors: across a mixture of platforms then, in addition to making sure that your mirrors include packages for all of the necessary platforms, you may choose to use - [the new `terraform providers lock` command](/docs/cli/commands/providers/lock.html) + [the new `terraform providers lock` command](/cli/commands/providers/lock) to pre-enter the required lock file entries for all of the platforms you intend to use. @@ -265,9 +262,9 @@ Cloud in particular that this approach was previously mis-documented. If you aren't intending to upload the provider plugin to Terraform Cloud as part of your configuration, we recommend instead installing to one of -[the other implied mirror directories](/docs/cli/config/config-file.html#implied-local-mirror-directories), +[the other implied mirror directories](/cli/config/config-file#implied-local-mirror-directories), or you can explicitly configure some -[custom provider installation methods](/docs/cli/config/config-file.html#provider-installation) +[custom provider installation methods](/cli/config/config-file#provider-installation) if your needs are more complicated. ## Concise Terraform Plan Output @@ -322,8 +319,8 @@ instead of the actual value. Terraform v0.14 introduces a more extensive version of that behavior where Terraform will track when you write an expression whose result is derived from a -[sensitive input variable](/docs/language/values/outputs.html#sensitive-suppressing-values-in-cli-output) or -[sensitive output value](/docs/language/values/variables.html#suppressing-values-in-cli-output), +[sensitive input variable](/language/values/outputs#sensitive-suppressing-values-in-cli-output) or +[sensitive output value](/language/values/variables#suppressing-values-in-cli-output), and so after upgrading to Terraform v0.14 you may find that more values are obscured in the Terraform plan output than would have been in Terraform v0.13. @@ -406,13 +403,12 @@ Sensitive values are also still saved in state snapshots stored in your configured backend. Use the access control and audit mechanisms offered by the remote system to control who can access that data. - ## Other Important Workflow Changes ### Terraform Output Formatting -We've modified the formatting of `terraform output` to match the formatting of `terraform show`. +We've modified the formatting of `terraform output` to match the formatting of `terraform show`. We consider the console output of Terraform human readable; specifically designed and optimized for operators and practitioners to review themselves. As a result we occasionally (maybe even regularly) intend to tweak that output to help improve consistency, clarity, actionability and more. -If you rely on `terraform output` in automation, please use `terraform output -json`. +If you rely on `terraform output` in automation, please use `terraform output -json`. diff --git a/website/upgrade-guides/0-15.html.markdown b/website/docs/language/upgrade-guides/0-15.mdx similarity index 84% rename from website/upgrade-guides/0-15.html.markdown rename to website/docs/language/upgrade-guides/0-15.mdx index 8e51bd4f3..762693a03 100644 --- a/website/upgrade-guides/0-15.html.markdown +++ b/website/docs/language/upgrade-guides/0-15.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform v0.15" -sidebar_current: "upgrade-guides-0-15" -description: |- - Upgrading to Terraform v0.15 +page_title: Upgrading to Terraform v0.15 +description: Upgrading to Terraform v0.15 --- # Upgrading to Terraform v0.15 @@ -151,7 +148,7 @@ OMU3v8F3h8jp+AB/1zGr5UBYfnYp5ncJm/OTCXLFAHxGibEbRnf1m2A3o0hEaWsw If you consider Terraform's treatment of a sensitive value to be too conservative and you'd like to force Terraform to treat a sensitive value as non-sensitive, you can use -[the `nonsensitive` function](/docs/language/functions/nonsensitive.html) to +[the `nonsensitive` function](/language/functions/nonsensitive) to override Terraform's automatic detection: ```hcl @@ -164,13 +161,13 @@ output "private_key" { For more information on the various situations where sensitive values can originate in Terraform, refer to the following sections: -* [Sensitive Input Variables](/docs/language/values/variables.html#suppressing-values-in-cli-output) -* [Sensitive Resource Attributes](/docs/language/expressions/references.html#sensitive-resource-attributes) -* [Sensitive Output Values](/docs/language/values/outputs.html#sensitive) +* [Sensitive Input Variables](/language/values/variables#suppressing-values-in-cli-output) +* [Sensitive Resource Attributes](/language/expressions/references#sensitive-resource-attributes) +* [Sensitive Output Values](/language/values/outputs#sensitive) -> **Note:** The new behavior described in this section was previously available in Terraform v0.14 as the -[language experiment](/docs/language/settings/#experimental-language-features) +[language experiment](/language/settings/#experimental-language-features) `provider_sensitive_attrs`. That experiment has now concluded, so if you were participating in that experiment then you'll now need to remove the experiment opt-in from your module as part of upgrading to Terraform v0.15. @@ -193,72 +190,72 @@ upgrading to Terraform v0.15: deprecated functions in order to resolve the ambiguity with the syntax used to declare list and map type constraints inside `variable` blocks. - If you need to update a module which was using the `list` function, you - can get the same result by replacing `list(...)` with `tolist([...])`. - For example: + If you need to update a module which was using the `list` function, you + can get the same result by replacing `list(...)` with `tolist([...])`. + For example: - ```diff - - list("a", "b", "c") - + tolist(["a", "b", "c"]) - ``` + ```diff + - list("a", "b", "c") + + tolist(["a", "b", "c"]) + ``` - If you need to update a module which was using the `map` function, you - can get the same result by replacing `map(...)` with `tomap({...})`. - For example: + If you need to update a module which was using the `map` function, you + can get the same result by replacing `map(...)` with `tomap({...})`. + For example: - ```diff - - map("a", 1, "b", 2) - + tomap({ a = 1, b = 2 }) - ``` + ```diff + - map("a", 1, "b", 2) + + tomap({ a = 1, b = 2 }) + ``` - The above examples include the type conversion functions `tolist` and - `tomap` to ensure that the result will always be of the same type as - before. However, in most situations those explicit type conversions won't - be necessary because Terraform can infer the necessary type conversions - automatically from context. In those cases, you can just use the - `[ ... ]` or `{ ... }` syntax directly, without a conversion function. + The above examples include the type conversion functions `tolist` and + `tomap` to ensure that the result will always be of the same type as + before. However, in most situations those explicit type conversions won't + be necessary because Terraform can infer the necessary type conversions + automatically from context. In those cases, you can just use the + `[ ... ]` or `{ ... }` syntax directly, without a conversion function. * In `variable` declaration blocks, the `type` argument previously accepted v0.11-style type constraints given as quoted strings. This legacy syntax is removed in Terraform v0.15. - To update an old-style type constraint to the modern syntax, start by - removing the quotes so that the argument is a bare keyword rather than - a string: + To update an old-style type constraint to the modern syntax, start by + removing the quotes so that the argument is a bare keyword rather than + a string: - ```hcl - variable "example" { - type = string - } - ``` + ```hcl + variable "example" { + type = string + } + ``` - Additionally, if the previous type constraint was either `"list"` or - `"map`", add a type argument to specify the element type of the collection. - Terraform v0.11 typically supported only collections of strings, so in - most cases you can set the element type to `string`: + Additionally, if the previous type constraint was either `"list"` or + `"map`", add a type argument to specify the element type of the collection. + Terraform v0.11 typically supported only collections of strings, so in + most cases you can set the element type to `string`: - ```hcl - variable "example" { - type = list(string) - } + ```hcl + variable "example" { + type = list(string) + } - variable "example" { - type = map(string) - } - ``` + variable "example" { + type = map(string) + } + ``` * In `lifecycle` blocks nested inside `resource` blocks, Terraform previously supported a legacy value `["*"]` for the `ignore_changes` argument, which is removed in Terraform v0.15. - Instead, use the `all` keyword to indicate that you wish to ignore changes - to all of the resource arguments: + Instead, use the `all` keyword to indicate that you wish to ignore changes + to all of the resource arguments: - ```hcl - lifecycle { - ignore_changes = all - } - ``` + ```hcl + lifecycle { + ignore_changes = all + } + ``` * Finally, Terraform v0.11 and earlier required all non-constant expressions to be written using string interpolation syntax, even if the result was @@ -296,7 +293,7 @@ Terraform's provider configuration scheme includes the idea of a "default" The `required_providers` block now has a new field for providers to indicate aliased configuration names, replacing the need for an empty "proxy configuration block" as a placeholder. In order to declare -[configuration aliases](/docs/language/modules/develop/providers.html#provider-aliases-within-modules), +[configuration aliases](/language/modules/develop/providers#provider-aliases-within-modules), add the desired names to the `configuration_aliases` argument for the provider requirements. @@ -388,18 +385,18 @@ event that your automation was relying on the limitations of the old mechanism: you can use the `TF_DATA_DIR` environment variable to specify the absolute path where Terraform should store its working directory internal state: - ```bash - TF_DATA_DIR="$PWD/.terraform" - ``` + ```bash + TF_DATA_DIR="$PWD/.terraform" + ``` * If your system uses `.tfvars` or `.tfvars.json` files either implicitly found or explicitly selected in the current working directory, you must either move those variables files into the root module directory or specify your files from elsewhere explicitly using the `-var-file` command line option: - ```bash - terraform plan -var-file="$PWD/example.tfvars" - ``` + ```bash + terraform plan -var-file="$PWD/example.tfvars" + ``` As a special case for backward compatibility, Terraform ensures that the language expression `path.cwd` will return the _original_ working directory, @@ -433,10 +430,10 @@ two possible workarounds available in the v0.15.0 release: * Run Terraform commands using the `-no-color` command line option to disable the terminal formatting sequences. - - This will cause the output to be unformatted plain text, but as a result - will avoid the output being interspersed with uninterpreted terminal - control sequences. + + This will cause the output to be unformatted plain text, but as a result + will avoid the output being interspersed with uninterpreted terminal + control sequences. * Alternatively, you can use Terraform v0.15.0 in various third-party virtual terminal implementations for older Windows versions, including @@ -459,11 +456,11 @@ cleanup of obsolete features and improved consistency: signal (`SIGINT` on Unix systems) will now cause Terraform to exit with a non-successful exit code. Previously it would, in some cases, exit with a success code. - - This signal is typically sent to Terraform when you press - Ctrl+C or similar interrupt keyboard shortcuts in an interactive terminal, - but might also be used by automation in order to gracefully cancel a - long-running Terraform operation. + + This signal is typically sent to Terraform when you press + Ctrl+C or similar interrupt keyboard shortcuts in an interactive terminal, + but might also be used by automation in order to gracefully cancel a + long-running Terraform operation. * The `-lock` and `-lock-timeout` options are no longer available for the `terraform init` command. Locking applies to operations that can potentially @@ -471,9 +468,9 @@ cleanup of obsolete features and improved consistency: don't try to run conflicting operations, but `terraform init` does not interact with any providers in order to possibly effect such changes. - These options didn't do anything in the `terraform init` command before, - and so you can remove them from any automated calls with no change - in behavior. + These options didn't do anything in the `terraform init` command before, + and so you can remove them from any automated calls with no change + in behavior. * The `-verify-plugins` and `-get-plugins` options to `terraform init` are no longer available. These have been non-functional since Terraform v0.13, @@ -482,18 +479,18 @@ cleanup of obsolete features and improved consistency: both require a `terraform init` but can also run without valid provider plugins installed. - If you were using these options in automated calls to `terraform init`, - remove them from the command line for compatibility with Terraform v0.15. - There is no longer an option to initialize without installing the - required provider plugins. + If you were using these options in automated calls to `terraform init`, + remove them from the command line for compatibility with Terraform v0.15. + There is no longer an option to initialize without installing the + required provider plugins. * The `terraform destroy` command no longer accepts the option `-force`. This was a previous name for the option in earlier Terraform versions, but we've since adopted `-auto-approve` for consistency with the `terraform apply` command. - If you are using `-force` in an automated call to `terraform destroy`, - change to using `-auto-approve` instead. + If you are using `-force` in an automated call to `terraform destroy`, + change to using `-auto-approve` instead. ## Azure Backend Removed Arguments @@ -501,7 +498,7 @@ In an earlier release the `azure` backend changed to remove the `arm_` prefix from a number of the configuration arguments: | Old Name | New Name | -|-----------------------|-------------------| +| --------------------- | ----------------- | | `arm_client_id` | `client_id` | | `arm_client_secret` | `client_secret` | | `arm_subscription_id` | `subscription_id` | diff --git a/website/upgrade-guides/0-7.html.markdown b/website/docs/language/upgrade-guides/0-7.mdx similarity index 93% rename from website/upgrade-guides/0-7.html.markdown rename to website/docs/language/upgrade-guides/0-7.mdx index e77dd2f18..249cf7621 100644 --- a/website/upgrade-guides/0-7.html.markdown +++ b/website/docs/language/upgrade-guides/0-7.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform 0.7" -sidebar_current: "upgrade-guides-0-7" -description: |- - Upgrading to Terraform v0.7 +page_title: Upgrading to Terraform 0.7 +description: Upgrading to Terraform v0.7 --- # Upgrading to Terraform v0.7 @@ -101,12 +98,12 @@ For most users, this change will not affect your day-to-day usage of Terraform. ## Migrating to Data Sources -With the addition of [Data Sources](/docs/language/data-sources/index.html), there are several resources that were acting as Data Sources that are now deprecated. Existing configurations will continue to work, but will print a deprecation warning when a data source is used as a resource. +With the addition of [Data Sources](/language/data-sources), there are several resources that were acting as Data Sources that are now deprecated. Existing configurations will continue to work, but will print a deprecation warning when a data source is used as a resource. - * `atlas_artifact` - * `template_file` - * `template_cloudinit_config` - * `tls_cert_request` +- `atlas_artifact` +- `template_file` +- `template_cloudinit_config` +- `tls_cert_request` Migrating to the equivalent Data Source is as simple as changing the `resource` keyword to `data` in your declaration and prepending `data.` to attribute references elsewhere in your config. diff --git a/website/upgrade-guides/0-8.html.markdown b/website/docs/language/upgrade-guides/0-8.mdx similarity index 96% rename from website/upgrade-guides/0-8.html.markdown rename to website/docs/language/upgrade-guides/0-8.mdx index 23c407ee8..ddecaf145 100644 --- a/website/upgrade-guides/0-8.html.markdown +++ b/website/docs/language/upgrade-guides/0-8.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform 0.8" -sidebar_current: "upgrade-guides-0-8" -description: |- - Upgrading to Terraform v0.8 +page_title: Upgrading to Terraform 0.8 +description: Upgrading to Terraform v0.8 --- # Upgrading to Terraform v0.8 diff --git a/website/upgrade-guides/0-9.html.markdown b/website/docs/language/upgrade-guides/0-9.mdx similarity index 76% rename from website/upgrade-guides/0-9.html.markdown rename to website/docs/language/upgrade-guides/0-9.mdx index 158de2099..3bb58ff15 100644 --- a/website/upgrade-guides/0-9.html.markdown +++ b/website/docs/language/upgrade-guides/0-9.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform 0.9" -sidebar_current: "upgrade-guides-0-9" -description: |- - Upgrading to Terraform v0.9 +page_title: Upgrading to Terraform 0.9 +description: Upgrading to Terraform v0.9 --- # Upgrading to Terraform v0.9 @@ -49,7 +46,7 @@ terraform { **Action:** Nothing immediately, everything will continue working except scripts using `terraform remote config`. -As soon as possible, [upgrade to backends](/docs/language/settings/backends/index.html). +As soon as possible, [upgrade to backends](/language/settings/backends). ## State Locking @@ -63,13 +60,13 @@ use these backends, you can ignore this section. Specific notes for each affected backend: - * **Amazon S3**: DynamoDB is used for locking. The AWS access keys - must have access to Dynamo. You may disable locking by omitting the - `lock_table` key in your backend configuration. +- **Amazon S3**: DynamoDB is used for locking. The AWS access keys + must have access to Dynamo. You may disable locking by omitting the + `lock_table` key in your backend configuration. - * **HashiCorp Consul**: Sessions are used for locking. If an auth token - is used it must have permissions to create and destroy sessions. You - may disable locking by specifying `lock = false` in your backend - configuration. +- **HashiCorp Consul**: Sessions are used for locking. If an auth token + is used it must have permissions to create and destroy sessions. You + may disable locking by specifying `lock = false` in your backend + configuration. **Action:** Update your credentials or configuration if necessary. diff --git a/website/upgrade-guides/1-0.html.markdown b/website/docs/language/upgrade-guides/1-0.mdx similarity index 52% rename from website/upgrade-guides/1-0.html.markdown rename to website/docs/language/upgrade-guides/1-0.mdx index 05425a659..47892dae4 100644 --- a/website/upgrade-guides/1-0.html.markdown +++ b/website/docs/language/upgrade-guides/1-0.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform v1.0" -sidebar_current: "upgrade-guides-1-0" -description: |- - Upgrading to Terraform v1.0 +page_title: Upgrading to Terraform v1.0 +description: Upgrading to Terraform v1.0 --- # Upgrading to Terraform v1.0 @@ -22,7 +19,7 @@ There are no special steps to take if you are upgrading from the previous major release, Terraform v0.15. You can also upgrade directly from Terraform v0.14 if you wish, although please -still consider the notes from [the Terraform v0.15 upgrade guide](0-15.html). +still consider the notes from [the Terraform v0.15 upgrade guide](/language/upgrade-guides/0-15). If you are affected by the notes in that upgrade guide, you will still need to take the steps described there but you can do so as part of upgrading to v1.0, without any need for an intermediate step of running Terraform v0.15. @@ -39,14 +36,14 @@ The following table summarizes the above recommendations. In each case, we recommend using the latest patch release from each major version in order to complete your upgrade. -| Current Version | Recommendation | -| -- | -- | -| v0.10 or earlier | Refer to the upgrade guides for these historical versions until you have upgraded to the latest v0.11 release, then refer to the following item. | -| v0.11 | Use [the `terraform 0.12checklist` command](0-12.html#pre-upgrade-checklist) to detect any situations that must be addressed before upgrading to v0.12, resolve them, and then upgrade to the latest v0.12 release and follow [the v0.12 Upgrade Guide](/upgrade-guides/0-12.html). | -| v0.12 | Upgrade to the latest Terraform v0.13 release and then follow [the v0.13 upgrade guide](0-13.html) to upgrade your configuration and state for explicit provider requirements. | -| v0.13 | Upgrade to the latest Terraform v0.14 release and attempt a normal Terraform run. If you encounter any new errors, refer to [the v0.14 upgrade guide](0-14.html) for resolution steps. | -| v0.14 | Upgrade directly to the latest Terraform v1.0 release and attempt a normal Terraform run. If you encounter any new errors, refer to [the v0.15 upgrade guide](0-15.html) for resolution steps. | -| v0.15 | Upgrade directly to the latest Terraform v1.0 release and attempt a normal Terraform run. Terraform v1.0 is a continuation of the v0.15 series, and so v1.0.0 and later are directly backward-compatible with Terraform v0.15.5. | +| Current Version | Recommendation | +| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| v0.10 or earlier | Refer to the upgrade guides for these historical versions until you have upgraded to the latest v0.11 release, then refer to the following item. | +| v0.11 | Use [the `terraform 0.12checklist` command](/language/upgrade-guides/0-12#pre-upgrade-checklist) to detect any situations that must be addressed before upgrading to v0.12, resolve them, and then upgrade to the latest v0.12 release and follow [the v0.12 Upgrade Guide](/language/upgrade-guides/0-12). | +| v0.12 | Upgrade to the latest Terraform v0.13 release and then follow [the v0.13 upgrade guide](/language/upgrade-guides/0-13) to upgrade your configuration and state for explicit provider requirements. | +| v0.13 | Upgrade to the latest Terraform v0.14 release and attempt a normal Terraform run. If you encounter any new errors, refer to [the v0.14 upgrade guide](/language/upgrade-guides/0-14) for resolution steps. | +| v0.14 | Upgrade directly to the latest Terraform v1.0 release and attempt a normal Terraform run. If you encounter any new errors, refer to [the v0.15 upgrade guide](/language/upgrade-guides/0-15) for resolution steps. | +| v0.15 | Upgrade directly to the latest Terraform v1.0 release and attempt a normal Terraform run. Terraform v1.0 is a continuation of the v0.15 series, and so v1.0.0 and later are directly backward-compatible with Terraform v0.15.5. | -> If you run into any problems during upgrading, please feel free to start a topic in [the Terraform community forum](https://discuss.hashicorp.com/c/terraform-core), @@ -57,7 +54,7 @@ may be able to reproduce it and offer advice. In a more complex system you might have multiple separate Terraform configurations that collaborate together using -[the `terraform_remote_state` data source](/docs/language/state/remote-state-data.html). +[the `terraform_remote_state` data source](/language/state/remote-state-data). In that case, it's typical for some configurations to be applied with a new version before others do, causing differences in the state snapshot format diff --git a/website/upgrade-guides/1-1.html.markdown b/website/docs/language/upgrade-guides/1-1.mdx similarity index 91% rename from website/upgrade-guides/1-1.html.markdown rename to website/docs/language/upgrade-guides/1-1.mdx index 2232e6053..faafcf147 100644 --- a/website/upgrade-guides/1-1.html.markdown +++ b/website/docs/language/upgrade-guides/1-1.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrading to Terraform v1.1" -sidebar_current: "upgrade-guides-1-1" -description: |- - Upgrading to Terraform v1.1 +page_title: Upgrading to Terraform v1.1 +description: Upgrading to Terraform v1.1 --- # Upgrading to Terraform v1.1 @@ -13,14 +10,14 @@ baseline in Terraform v1.0, and so this release should not require any unusual upgrade steps for most users. However, if you are upgrading from a version earlier than v1.0 then please -refer to [the Terraform v1.0 upgrade guide](1-0.html) for how to upgrade through +refer to [the Terraform v1.0 upgrade guide](/language/upgrade-guides/1-0) for how to upgrade through the v0 releases to reach the v1 release series. Because v1.1 is backward-compatible with the v1.0 series, you can upgrade directly to the latest v1.1 release, skipping the v1.0 series entirely, at any point where the v1.0 upgrade guide calls for upgrading to Terraform v1.0. Terraform v1.1 continues to honor -[the Terraform v1.0 Compatibility Promises](/docs/language/v1-compatibility-promises.html), +[the Terraform v1.0 Compatibility Promises](/language/v1-compatibility-promises), but there are some behavior changes outside of those promises that may affect a small number of users, described in the following sections. @@ -44,7 +41,7 @@ supported, and Terraform CLI behavior on those earlier versions is undefined. [Microsoft has announced the deprecation of Azure AD Graph](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-faq), and so Terraform v1.1 marks the first phase of a deprecation process for -that legacy system in [the AzureRM state storage backend](/docs/language/settings/backends/azurerm.html). +that legacy system in [the AzureRM state storage backend](/language/settings/backends/azurerm). During the Terraform v1.1 release the default behavior is unchanged, but you can explicitly opt in to Microsoft Graph by setting @@ -78,7 +75,7 @@ therefore requires no special `-type=...` option. ## Changes to `terraform state mv` Terraform's local state storage backend supports a number of -[legacy command line options](/docs/language/settings/backends/local.html#command-line-arguments) +[legacy command line options](/language/settings/backends/local#command-line-arguments) for backward-compatibility with workflows from much older versions of Terraform, prior to the introduction of Backends. @@ -126,7 +123,7 @@ executable file representing a provider plugin, and didn't consider other files that might appear alongside in the plugin package. Terraform v1.1 now uses the same strategy for provider checking during apply as it does when verifying provider consistency against -[the dependency lock file](/docs/language/dependency-lock.html) +[the dependency lock file](/language/files/dependency-lock) during `terraform init`, which means `terraform apply` will return an error if it detects that _any_ of the files in a provider's plugin package have changed compared to when the plan was created. diff --git a/website/upgrade-guides/index.html.markdown b/website/docs/language/upgrade-guides/index.mdx similarity index 66% rename from website/upgrade-guides/index.html.markdown rename to website/docs/language/upgrade-guides/index.mdx index 49b28253f..5d3c95166 100644 --- a/website/upgrade-guides/index.html.markdown +++ b/website/docs/language/upgrade-guides/index.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Upgrade Guides" -sidebar_current: "upgrade-guides" -description: |- - Upgrade Guides +page_title: Upgrade Guides +description: Upgrade Guides --- # Upgrade Guides diff --git a/website/docs/language/v1-compatibility-promises.html.md b/website/docs/language/v1-compatibility-promises.mdx similarity index 88% rename from website/docs/language/v1-compatibility-promises.html.md rename to website/docs/language/v1-compatibility-promises.mdx index a44a8b3f6..e475b8ec6 100644 --- a/website/docs/language/v1-compatibility-promises.html.md +++ b/website/docs/language/v1-compatibility-promises.mdx @@ -1,7 +1,5 @@ --- -layout: "language" -page_title: "Terraform v1.0 Compatibility Promises" -sidebar_current: "docs-v1-compatibility" +page_title: Terraform v1.0 Compatibility Promises description: |- From Terraform v1.0 onwards the Terraform team promises to preserve backward compatibility for most of the Terraform language and the primary CLI @@ -68,35 +66,35 @@ The following top-level blocks and their defined "meta-arguments" (that is, arguments defined by Terraform Core rather than by external plugins such as providers) will retain their current functionality: -* [`resource`](/docs/language/resources/) and - [`data`](/docs/language/data-sources/) blocks to +* [`resource`](/language/resources) and + [`data`](/language/data-sources) blocks to declare resources, including their nested block types `lifecycle`, `connection`, and `provisioner`, and their meta-argument `provider`. -* [`module`](/docs/language/modules/syntax.html) blocks to call other modules, +* [`module`](/language/modules/syntax) blocks to call other modules, and its meta-argument `providers`. -* The [`count`](/docs/language/meta-arguments/count.html), - [`for_each`](/docs/language/meta-arguments/for_each.html), and - [`depends_on`](/docs/language/meta-arguments/depends_on.html) meta-arguments +* The [`count`](/language/meta-arguments/count), + [`for_each`](/language/meta-arguments/for_each), and + [`depends_on`](/language/meta-arguments/depends_on) meta-arguments in `resource`, `data`, and `module` blocks. -* [`provider`](/docs/language/providers/configuration.html) blocks to configure +* [`provider`](/language/providers/configuration) blocks to configure providers, and the `alias` meta-argument. -* [`variable`](/docs/language/values/variables.html#declaring-an-input-variable), - [`output`](/docs/language/values/outputs.html#declaring-an-output-value), and - [`locals`](/docs/language/values/locals.html#declaring-a-local-value) blocks +* [`variable`](/language/values/variables#declaring-an-input-variable), + [`output`](/language/values/outputs#declaring-an-output-value), and + [`locals`](/language/values/locals#declaring-a-local-value) blocks for declaring the various kinds of named values in a module. -* [`terraform`](/docs/language/settings/) blocks, including the nested - [`required_version`](/docs/language/settings/index.html#specifying-a-required-terraform-version) +* [`terraform`](/language/settings) blocks, including the nested + [`required_version`](/language/settings#specifying-a-required-terraform-version) and - [`required_providers`](/docs/language/providers/requirements.html#requiring-providers) + [`required_providers`](/language/providers/requirements#requiring-providers) arguments, and nested - [`backend`](/docs/language/settings/backends/configuration.html#using-a-backend-block) + [`backend`](/language/settings/backends/configuration#using-a-backend-block) blocks for backend configuration. We also intend to keep compatibility with all -[expression operators](/docs/language/expressions/) and -[built-in functions](/docs/language/functions/), with the exception of +[expression operators](/language/expressions) and +[built-in functions](/language/functions), with the exception of references to -[`terraform.workspace`](/docs/language/expressions/references.html#terraform-workspace), +[`terraform.workspace`](/language/expressions/references#terraform-workspace), whose behavior may change as part of future changes to the workspace model. We intend to retain broad compatibility with Terraform language features, with @@ -104,17 +102,17 @@ a few specific caveats: * We consider a configuration to be valid if Terraform can create and apply a plan for it without reporting any errors. - - A configuration that currently produces errors might generate different - errors or exhibit other non-error behaviors in a future version of - Terraform. A configuration that generates errors during the apply phase - might generate similar errors at an earlier phase in future, because - we generally consider it better to detect errors in as early a phase as - possible. - Generally-speaking, the compatibility promises described in this document - apply only to valid configurations. Handling of invalid configurations is - always subject to change in future Terraform releases. + A configuration that currently produces errors might generate different + errors or exhibit other non-error behaviors in a future version of + Terraform. A configuration that generates errors during the apply phase + might generate similar errors at an earlier phase in future, because + we generally consider it better to detect errors in as early a phase as + possible. + + Generally-speaking, the compatibility promises described in this document + apply only to valid configurations. Handling of invalid configurations is + always subject to change in future Terraform releases. * If the actual behavior of a feature differs from what we explicitly documented as the feature's behavior, we will usually treat that as a bug and change the feature to match the documentation, although we will avoid @@ -192,18 +190,18 @@ if you are still using a Terraform v1.x release. ### Provider Installation Methods Terraform normally installs providers from a provider registry implementing -[the Provider Registry Protocol](/docs/internals/provider-registry-protocol.html), +[the Provider Registry Protocol](/internals/provider-registry-protocol), version 1. All Terraform v1.x releases will remain compatible with that protocol, and so correctly-implemented provider registries will stay compatible. Terraform also supports installation of providers from -[local filesystem directories](/docs/cli/config/config-file.html#filesystem_mirror) +[local filesystem directories](/cli/config/config-file#filesystem_mirror) (filesystem mirrors) and from -[network mirrors](/docs/cli/config/config-file.html#network_mirror) -(implementing [the Provider Mirror Protocol](/docs/internals/provider-network-mirror-protocol.html). +[network mirrors](/cli/config/config-file#network_mirror) +(implementing [the Provider Mirror Protocol](/internals/provider-network-mirror-protocol). All Terraform v1.x releases will remain compatible with those installation methods, including -[the Implied Local Mirror Directories](/docs/cli/config/config-file.html#implied-local-mirror-directories). +[the Implied Local Mirror Directories](/cli/config/config-file#implied-local-mirror-directories). Specific provider registries or network mirrors are run independently from Terraform itself and so their own behaviors are not subject to these @@ -239,11 +237,11 @@ and of Terraform itself. ### Module Installation Methods Terraform supports installing child modules from a number of different -[module source types](/docs/language/modules/sources.html). We will continue +[module source types](/language/modules/sources). We will continue to support all of the existing source types throughout the v1.x releases. One of the supported source types is a module registry implementing -[the Module Registry Protocol](/docs/internals/module-registry-protocol.html) +[the Module Registry Protocol](/internals/module-registry-protocol) version 1. All Terraform v1.x releases will remain compatible with correct implementations of that protocol. @@ -286,6 +284,7 @@ For historical reasons, all supported state storage backends are included as part of Terraform CLI but not all are supported directly by the Terraform Team. Only the following backends maintained by the Terraform team are subject to compatibility promises: + * `local` (the default, when you are not using remote state) * `http` @@ -388,7 +387,7 @@ As noted above, compatibility with external software is limited to explicitly-machine-readable output (`-json` and `-raw` modes) and exit codes. Any natural-language output from these commands might change in later releases. -* [`init`](/docs/cli/commands/init.html) +* [`init`](/cli/commands/init) * `-backend=false` * `-backend-config=FILE` * `-backend-config="KEY=VALUE"` @@ -400,10 +399,10 @@ Any natural-language output from these commands might change in later releases. * `-plugin-dir=DIR` * `-reconfigure` * `-upgrade` -* [`validate`](/docs/cli/commands/validate.html) +* [`validate`](/cli/commands/validate) * `-json` * `-no-color` -* [`plan`](/docs/cli/commands/plan.html) +* [`plan`](/cli/commands/plan) * `-compact-warnings` * `-destroy` * `-detailed-exitcode` @@ -420,7 +419,7 @@ Any natural-language output from these commands might change in later releases. * `-target=ADDRESS` * `-var 'NAME=VALUE'` * `-var-file=FILE` -* [`apply`](/docs/cli/commands/apply.html) +* [`apply`](/cli/commands/apply) * `-auto-approve` * `-compact-warnings` * `-lock=false` @@ -435,53 +434,53 @@ Any natural-language output from these commands might change in later releases. * `-target=ADDRESS` * `-var 'NAME=VALUE'` * `-var-file=FILE` -* [`show`](/docs/cli/commands/show.html) +* [`show`](/cli/commands/show) * `-no-color` * `-json` * (both with and without a plan file) -* [`providers`](/docs/cli/commands/providers.html) (with no subcommand) -* [`providers lock`](/docs/cli/commands/providers/lock.html) +* [`providers`](/cli/commands/providers) (with no subcommand) +* [`providers lock`](/cli/commands/providers/lock) * `-fs-mirror=PATH` * `-net-mirror=URL` * `-platform=OS_ARCH` -* [`providers mirror`](/docs/cli/commands/providers/mirror.html) +* [`providers mirror`](/cli/commands/providers/mirror) * `-platform=OS_ARCH` -* [`providers schema`](/docs/cli/commands/providers/schema.html) +* [`providers schema`](/cli/commands/providers/schema) * `-json` -* [`fmt`](/docs/cli/commands/fmt.html) +* [`fmt`](/cli/commands/fmt) * `-list=false` * `-write=false` * `-diff` * `-recursive` * `-check` -* [`version`](/docs/cli/commands/version.html) +* [`version`](/cli/commands/version) * `-json` -* [`output`](/docs/cli/commands/output.html) +* [`output`](/cli/commands/output) * `-no-color` * `-json` * `-raw` -* [`taint`](/docs/cli/commands/taint.html) +* [`taint`](/cli/commands/taint) * `-allow-missing` * `-lock=false` * `-lock-timeout=DURATION` * `-ignore-remote-version` -* [`untaint`](/docs/cli/commands/untaint.html) +* [`untaint`](/cli/commands/untaint) * `-allow-missing` * `-lock=false` * `-lock-timeout=DURATION` * `-ignore-remote-version` -* [`force-unlock`](/docs/cli/commands/force-unlock.html) +* [`force-unlock`](/cli/commands/force-unlock) * `-force` -* [`state list`](/docs/cli/commands/state/list.html) +* [`state list`](/cli/commands/state/list) * `-id=ID` -* [`state pull`](/docs/cli/commands/state/pull.html) -* [`state push`](/docs/cli/commands/state/push.html) +* [`state pull`](/cli/commands/state/pull) +* [`state push`](/cli/commands/state/push) * `-force` * `-lock=false` * `-lock-timeout=DURATION` -* [`state show`](/docs/cli/commands/state/show.html) +* [`state show`](/cli/commands/state/show) * `-ignore-remote-version` -* [`login`](/docs/cli/commands/login.html) +* [`login`](/cli/commands/login) For commands or options not in the above list, we will still avoid breaking changes where possible, but can't promise full compatibility throughout the diff --git a/website/docs/language/values/index.html.md b/website/docs/language/values/index.html.md deleted file mode 100644 index 3074f965c..000000000 --- a/website/docs/language/values/index.html.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: "language" -page_title: "Variables and Outputs" -description: "An overview of input variables, output values, and local values in Terraform language." ---- - -# Variables and Outputs - -The Terraform language includes a few kinds of blocks for requesting or -publishing named values. - -- [Input Variables](/docs/language/values/variables.html) serve as parameters for - a Terraform module, so users can customize behavior without editing the source. - -- [Output Values](/docs/language/values/outputs.html) are like return values for a - Terraform module. - -- [Local Values](/docs/language/values/locals.html) are a convenience feature for - assigning a short name to an expression. diff --git a/website/docs/language/values/index.mdx b/website/docs/language/values/index.mdx new file mode 100644 index 000000000..d271492c3 --- /dev/null +++ b/website/docs/language/values/index.mdx @@ -0,0 +1,20 @@ +--- +page_title: Variables and Outputs +description: >- + An overview of input variables, output values, and local values in Terraform + language. +--- + +# Variables and Outputs + +The Terraform language includes a few kinds of blocks for requesting or +publishing named values. + +- [Input Variables](/language/values/variables) serve as parameters for + a Terraform module, so users can customize behavior without editing the source. + +- [Output Values](/language/values/outputs) are like return values for a + Terraform module. + +- [Local Values](/language/values/locals) are a convenience feature for + assigning a short name to an expression. diff --git a/website/docs/language/values/locals.html.md b/website/docs/language/values/locals.mdx similarity index 74% rename from website/docs/language/values/locals.html.md rename to website/docs/language/values/locals.mdx index a487698bf..aa529f9fe 100644 --- a/website/docs/language/values/locals.html.md +++ b/website/docs/language/values/locals.mdx @@ -1,25 +1,25 @@ --- -layout: "language" -page_title: "Local Values - Configuration Language" -sidebar_current: "docs-config-locals" -description: "Local values assign a name to an expression that can be used multiple times within a Terraform module." +page_title: Local Values - Configuration Language +description: >- + Local values assign a name to an expression that can be used multiple times + within a Terraform module. --- # Local Values > **Hands-on:** Try the [Simplify Terraform Configuration with -Locals](https://learn.hashicorp.com/tutorials/terraform/locals?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) -tutorial on HashiCorp Learn. +> Locals](https://learn.hashicorp.com/tutorials/terraform/locals?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) +> tutorial on HashiCorp Learn. -A local value assigns a name to an [expression](/docs/language/expressions/index.html), +A local value assigns a name to an [expression](/language/expressions), so you can use it multiple times within a module without repeating it. If you're familiar with traditional programming languages, it can be useful to compare Terraform modules to function definitions: -- [Input variables](./variables.html) are like function arguments. -- [Output values](./outputs.html) are like function return values. +- [Input variables](/language/values/variables) are like function arguments. +- [Output values](/language/values/outputs) are like function return values. - Local values are like a function's temporary local variables. -> **Note:** For brevity, local values are often referred to as just "locals" @@ -59,7 +59,7 @@ locals { ## Using Local Values Once a local value is declared, you can reference it in -[expressions](/docs/language/expressions/index.html) as `local.`. +[expressions](/language/expressions) as `local.`. -> **Note:** Local values are _created_ by a `locals` block (plural), but you _reference_ them as attributes on an object named `local` (singular). Make sure diff --git a/website/docs/language/values/outputs.html.md b/website/docs/language/values/outputs.mdx similarity index 87% rename from website/docs/language/values/outputs.html.md rename to website/docs/language/values/outputs.mdx index 824929fd5..a06c8ffcb 100644 --- a/website/docs/language/values/outputs.html.md +++ b/website/docs/language/values/outputs.mdx @@ -1,9 +1,6 @@ --- -layout: "language" -page_title: "Output Values - Configuration Language" -sidebar_current: "docs-config-outputs" -description: |- - Output values are the return values of a Terraform module. +page_title: Output Values - Configuration Language +description: Output values are the return values of a Terraform module. --- # Output Values @@ -13,8 +10,8 @@ command line, and can expose information for other Terraform configurations to use. Output values are similar to return values in programming languages. > **Hands-on:** Try the [Output Data From -Terraform](https://learn.hashicorp.com/tutorials/terraform/outputs) -tutorial on HashiCorp Learn. +> Terraform](https://learn.hashicorp.com/tutorials/terraform/outputs) +> tutorial on HashiCorp Learn. Output values have several uses: @@ -22,9 +19,9 @@ Output values have several uses: to a parent module. - A root module can use outputs to print certain values in the CLI output after running `terraform apply`. -- When using [remote state](/docs/language/state/remote.html), root module outputs can be +- When using [remote state](/language/state/remote), root module outputs can be accessed by other configurations via a - [`terraform_remote_state` data source](/docs/language/state/remote-state-data.html). + [`terraform_remote_state` data source](/language/state/remote-state-data). Resource instances managed by Terraform each export attributes whose values can be used elsewhere in configuration. Output values are a way to expose some @@ -45,11 +42,11 @@ output "instance_ip_addr" { ``` The label immediately after the `output` keyword is the name, which must be a -valid [identifier](/docs/language/syntax/configuration.html#identifiers). In a root module, this name is +valid [identifier](/language/syntax/configuration#identifiers). In a root module, this name is displayed to the user; in a child module, it can be used to access the output's value. -The `value` argument takes an [expression](/docs/language/expressions/index.html) +The `value` argument takes an [expression](/language/expressions) whose result is to be returned to the user. In this example, the expression refers to the `private_ip` attribute exposed by an `aws_instance` resource defined elsewhere in this module (not shown). Any valid expression is allowed @@ -156,10 +153,10 @@ value in the list of outputs at the end of `terraform apply`. However, the value could still display in the CLI output for other reasons, like if the value is referenced in an expression for a resource argument. -Terraform will still record sensitive values in the [state](/docs/language/state/index.html), +Terraform will still record sensitive values in the [state](/language/state), and so anyone who can access the state data will have access to the sensitive values in cleartext. For more information, see -[_Sensitive Data in State_](/docs/language/state/sensitive-data.html). +[_Sensitive Data in State_](/language/state/sensitive-data). @@ -175,7 +172,7 @@ correctly determine the dependencies between resources defined in different modules. Just as with -[resource dependencies](/docs/language/resources/behavior.html#resource-dependencies), +[resource dependencies](/language/resources/behavior#resource-dependencies), Terraform analyzes the `value` expression for an output value and automatically determines a set of dependencies, but in less-common cases there are dependencies that cannot be recognized implicitly. In these rare cases, the diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.mdx similarity index 87% rename from website/docs/language/values/variables.html.md rename to website/docs/language/values/variables.mdx index e1578a7d7..fc8de6e4e 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.mdx @@ -1,8 +1,8 @@ --- -layout: "language" -page_title: "Input Variables - Configuration Language" -sidebar_current: "docs-config-variables" -description: "Input variables allow you to customize modules without altering their source code. Learn how to declare, define, and reference variables in configurations." +page_title: Input Variables - Configuration Language +description: >- + Input variables allow you to customize modules without altering their source + code. Learn how to declare, define, and reference variables in configurations. --- # Input Variables @@ -15,22 +15,22 @@ Terraform configurations, making your module composable and reusable. When you declare variables in the root module of your configuration, you can set their values using CLI options and environment variables. -When you declare them in [child modules](/docs/language/modules/index.html), +When you declare them in [child modules](/language/modules), the calling module should pass values in the `module` block. If you're familiar with traditional programming languages, it can be useful to compare Terraform modules to function definitions: -- Input variables are like function arguments. -- [Output values](./outputs.html) are like function return values. -- [Local values](./locals.html) are like a function's temporary local variables. +* Input variables are like function arguments. +* [Output values](/language/values/outputs) are like function return values. +* [Local values](/language/values/locals) are like a function's temporary local variables. -> **Note:** For brevity, input variables are often referred to as just "variables" or "Terraform variables" when it is clear from context what sort of variable is being discussed. Other kinds of variables in Terraform include _environment variables_ (set by the shell where Terraform runs) and _expression variables_ (used to indirectly represent a value in an -[expression](/docs/language/expressions/index.html)). +[expression](/language/expressions)). ## Declaring an Input Variable @@ -68,23 +68,23 @@ be unique among all variables in the same module. This name is used to assign a value to the variable from outside and to reference the variable's value from within the module. -The name of a variable can be any valid [identifier](/docs/language/syntax/configuration.html#identifiers) +The name of a variable can be any valid [identifier](/language/syntax/configuration#identifiers) _except_ the following: `source`, `version`, `providers`, `count`, `for_each`, `lifecycle`, `depends_on`, `locals`. These names are reserved for meta-arguments in -[module configuration blocks](/docs/language/modules/syntax.html), and cannot be +[module configuration blocks](/language/modules/syntax), and cannot be declared as variable names. ## Arguments Terraform CLI defines the following optional arguments for variable declarations: -- [`default`][inpage-default] - A default value which then makes the variable optional. -- [`type`][inpage-type] - This argument specifies what value types are accepted for the variable. -- [`description`][inpage-description] - This specifies the input variable's documentation. -- [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints. -- [`sensitive`][inpage-sensitive] - Limits Terraform UI output when the variable is used in configuration. -- [`nullable`][inpage-nullable] - Specify if the variable can be `null` within the module. +* [`default`][inpage-default] - A default value which then makes the variable optional. +* [`type`][inpage-type] - This argument specifies what value types are accepted for the variable. +* [`description`][inpage-description] - This specifies the input variable's documentation. +* [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints. +* [`sensitive`][inpage-sensitive] - Limits Terraform UI output when the variable is used in configuration. +* [`nullable`][inpage-nullable] - Specify if the variable can be `null` within the module. ### Default values @@ -101,7 +101,7 @@ configuration. [inpage-type]: #type-constraints The `type` argument in a `variable` block allows you to restrict the -[type of value](/docs/language/expressions/types.html) that will be accepted as +[type of value](/language/expressions/types) that will be accepted as the value for a variable. If no type constraint is set then a value of any type is accepted. @@ -128,7 +128,7 @@ collections: The keyword `any` may be used to indicate that any type is acceptable. For more information on the meaning and behavior of these different types, as well as detailed information about automatic conversion of complex types, see -[Type Constraints](/docs/language/expressions/types.html). +[Type Constraints](/language/expressions/types). If both the `type` and `default` arguments are specified, the given default value must be convertible to the specified type. @@ -182,7 +182,7 @@ The expression can refer only to the variable that the condition applies to, and _must not_ produce errors. If the failure of an expression is the basis of the validation decision, use -[the `can` function](/docs/language/functions/can.html) to detect such errors. For example: +[the `can` function](/language/functions/can) to detect such errors. For example: ```hcl variable "image_id" { @@ -217,10 +217,10 @@ Setting a variable as `sensitive` prevents Terraform from showing its value in the `plan` or `apply` output, when you use that variable elsewhere in your configuration. -Terraform will still record sensitive values in the [state](/docs/language/state/index.html), +Terraform will still record sensitive values in the [state](/language/state), and so anyone who can access the state data will have access to the sensitive values in cleartext. For more information, see -[_Sensitive Data in State_](/docs/language/state/sensitive-data.html). +[_Sensitive Data in State_](/language/state/sensitive-data). Declare a variable as sensitive by setting the `sensitive` argument to `true`: @@ -271,13 +271,13 @@ disclosing the content of one block might imply the content of a sibling block. ``` A provider can also -[declare an attribute as sensitive](/docs/extend/best-practices/sensitive-state.html#using-the-sensitive-flag), +[declare an attribute as sensitive](/plugin/sdkv2/best-practices/sensitive-state#using-the-sensitive-flag), which will cause Terraform to hide it from regular output regardless of how you assign it a value. For more information, see -[Sensitive Resource Attributes](/docs/language/expressions/references.html#sensitive-resource-attributes). +[Sensitive Resource Attributes](/language/expressions/references#sensitive-resource-attributes). If you use a sensitive value from as part of an -[output value](/docs/language/values/outputs.html) then Terraform will require +[output value](/language/values/outputs) then Terraform will require you to also mark the output value itself as sensitive, to confirm that you intended to export it. @@ -334,11 +334,10 @@ For variables of collection or structural types, such as lists or objects, the caller may still use `null` in nested elements or attributes, as long as the collection or structure itself is not null. - ## Using Input Variable Values Within the module that declared a variable, its value can be accessed from -within [expressions](/docs/language/expressions/index.html) as `var.`, +within [expressions](/language/expressions) as `var.`, where `` matches the label given in the declaration block: -> **Note:** Input variables are _created_ by a `variable` block, but you @@ -359,7 +358,7 @@ the module where it was declared. When variables are declared in the root module of your configuration, they can be set in a number of ways: -* [In a Terraform Cloud workspace](/docs/cloud/workspaces/variables.html). +* [In a Terraform Cloud workspace](/cloud-docs/workspaces/variables). * Individually, with the `-var` command line option. * In variable definitions (`.tfvars`) files, either specified on the command line or automatically loaded. @@ -368,7 +367,7 @@ can be set in a number of ways: The following sections describe these options in more detail. This section does not apply to _child_ modules, where values for input variables are instead assigned in the configuration of their parent module, as described in -[_Modules_](/docs/language/modules/index.html). +[_Modules_](/language/modules). ### Variables on the Command Line @@ -384,7 +383,7 @@ terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-de The above examples show appropriate syntax for Unix-style shells, such as on Linux or macOS. For more information on shell quoting, including additional examples for Windows Command Prompt, see -[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line). +[Input Variables on the Command Line](/cli/commands/plan#input-variables-on-the-command-line). You can use the `-var` option multiple times in a single command to set several different variables. @@ -403,7 +402,7 @@ terraform apply -var-file="testing.tfvars" ``` -> **Note:** This is how Terraform Cloud passes -[workspace variables](/docs/cloud/workspaces/variables.html) to Terraform. +[workspace variables](/cloud-docs/workspaces/variables) to Terraform. A variable definitions file uses the same basic syntax as Terraform language files, but consists only of variable name assignments: @@ -457,7 +456,7 @@ and lower case letters as in the above example. When variable values are provided in a variable definitions file, you can use Terraform's usual syntax for -[literal expressions](/docs/language/expressions/types.html#literal-expressions) +[literal expressions](/language/expressions/types#literal-expressions) to assign complex-typed values, like lists and maps. Some special rules apply to the `-var` command line option and to environment @@ -483,7 +482,7 @@ For readability, and to avoid the need to worry about shell escaping, we recommend always setting complex variable values via variable definitions files. For more information on quoting and escaping for `-var` arguments, see -[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line). +[Input Variables on the Command Line](/cli/commands/plan#input-variables-on-the-command-line). ### Values for Undeclared Variables @@ -516,7 +515,7 @@ Will cause Terraform to warn you that there is no variable declared `"mosse"`, w you spot this mistake. If you use `.tfvars` files across multiple configurations and expect to continue to see this warning, -you can use the [`-compact-warnings`](https://www.terraform.io/docs/cli/commands/plan.html#compact-warnings) +you can use the [`-compact-warnings`](/cli/commands/plan#compact-warnings) option to simplify your output. If you provide values for undeclared variables on the [command line](#variables-on-the-command-line), diff --git a/website/guides/index.html.md b/website/guides/index.mdx similarity index 86% rename from website/guides/index.html.md rename to website/guides/index.mdx index 987d38531..1e4ccedea 100644 --- a/website/guides/index.html.md +++ b/website/guides/index.mdx @@ -1,7 +1,5 @@ --- -layout: "intro" -page_title: "Guides" -sidebar_current: "guides-home" +page_title: Guides description: |- Welcome to the Terraform guides! The guides provide examples for common Terraform workflows and actions for both beginner and advanced Terraform @@ -11,7 +9,7 @@ description: |- # Terraform Guides Welcome to the Terraform guides section! If you are just getting started with -Terraform, please start with the [Terraform introduction](/intro/index.html) +Terraform, please start with the [Terraform introduction](/intro) instead and then continue on to the guides. The guides provide examples for common Terraform workflows and actions for both beginner and advanced Terraform users. diff --git a/website/guides/terraform-integration-program.html.md b/website/guides/terraform-integration-program.html.md deleted file mode 100644 index 56dea778e..000000000 --- a/website/guides/terraform-integration-program.html.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -layout: "extend" -page_title: "Terraform Integration Program" -sidebar_current: "guides-terraform-integration-program" -description: The Terraform Integration Program allows prospect partners to create and publish Terraform integrations that have been verified by HashiCorp. ---- - -# Terraform Integration Program - -The Terraform Integration Program facilitates prospect partners in creating and publishing Terraform integrations that have been verified by HashiCorp. - -## Terraform Editions - -Terraform is an infrastructure as code (IaC) tool that allows you to build, change, and version infrastructure safely and efficiently. This includes low-level components such as compute instances, storage, and networking, as well as high-level components such as DNS entries, SaaS features, etc. Terraform can manage both existing service providers and custom in-house solutions. - -HashiCorp offers three editions of Terraform: Open Source, Terraform Cloud, and Terraform Enterprise. - -- [Terraform Open Source](https://www.terraform.io/) provides a consistent CLI workflow to manage hundreds of cloud services. Terraform codifies cloud APIs into declarative configuration files. -- [Terraform Cloud (TFC)](https://www.terraform.io/cloud) is a free to use, self-service SaaS platform that extends the capabilities of the open source Terraform CLI. It adds automation and collaboration features, and performs Terraform functionality remotely, making it ideal for collaborative and production environments. Terraform Cloud is available as a hosted service at https://app.terraform.io. Small teams can sign up for free to connect Terraform to version control, share variables, run Terraform in a stable remote environment, and securely store remote state. Paid tiers allow you to add more than five users, create teams with different levels of permissions, enforce policies before creating infrastructure, and collaborate more effectively. -- [Terraform Enterprise (TFE)](https://www.terraform.io/docs/enterprise/index.html) is our self-hosted distribution of Terraform Cloud with advanced security and compliance features. It offers enterprises a private instance that includes the advanced features available in Terraform Cloud. - -## Types of Terraform Integrations - -The Terraform ecosystem is designed to enable users to apply Terraform across different use cases and environments. The Terraform Integration Program current supports both workflow and integration partners (details below). Some partners can be both, depending on their use cases. - -- **Workflow Partners** build integrations for Terraform Cloud and/or Terraform Enterprise. Ideally, these partners are seeking to enable customers to use their existing platform within a Terraform Run. - -- **Infrastructure Partners** empower customers to leverage Terraform to manage resources exposed by their platform APIs. These are accessible to users of all Terraform editions. - -Our Workflow Partners typically have the following use cases: - -- **Code Scanning:** These partners provide tooling to review infrastructure as code configurations to prevent errors or security issues. -- **Cost Estimation:** These partners drive cost estimation of new deployment based on historical deployments. -- **Monitoring:** These partners provide performance visibility. -- **Zero Trust Security:** These partners help users create configurations to verify connections prior to providing access to an organization’s systems. -- **Audit:** These partners focus on maintaining code formatting, preventing security threats, and performing additional code analysis. -- **ITSM (Information Technology Service Management):** These partners focus on implementation, deployment, and delivery of IT workflows. -- **SSO (Single Sign On):** These partners focus on authentication for end users to securely sign on. -- **CI/CD:** These partners focus on continuous integration and continuous delivery/deployment. -- **VCS:** These partners focus on tracking and managing software code changes. - -Most workflow partners integrate with the Terraform workflow itself. Run tasks allow Terraform Cloud to execute tasks in external systems at specific points in the Terraform Cloud run lifecycle. This offers much more extensibility to Terraform Cloud customers, enabling them to integrate your services into the Terraform Cloud workflow. The beta release of this feature allows users to add and execute these tasks during the new pre-apply stage which exists in between the plan and apply stages. Eventually, we will open the entire workflow to Terraform Cloud users, including the pre-plan and post apply stages. Reference the [Terraform Cloud Integrations documentation](https://www.terraform.io/guides/terraform-integration-program.html#terraform-cloud-integrations) for more details. - -![Integration program diagram](/assets/images/docs/terraform-integration-program-diagram.png) - -Our Infrastructure Partners typically have the following use cases: - -- **Public Cloud:** These are large-scale, global cloud providers that offer a range of services including IaaS, SaaS, and PaaS. -- **Container Orchestration:** These partners help with container provisioning and deployment. -- **IaaS (Infrastructure-as-a-Service):** These are infrastructure and IaaS providers that offer solutions such as storage, networking, and virtualization. -- **Security & Authentication:** These are partners with authentication and security monitoring platforms. -- **Asset Management:** These partners offer asset management of key organization and IT resources, including software licenses, hardware assets, and cloud resources. -- **CI/CD:** These partners focus on continuous integration and continuous delivery/deployment. -- **Logging & Monitoring:** These partners offer the capability to configure and manage services such as loggers, metric tools, and monitoring services. -- **Utility:** These partners offer helper functionality, such as random value generation, file creation, http interactions, and time-based resources. -- **Cloud Automation:** These partners offer specialized cloud infrastructure automation management capabilities such as configuration management. -- **Data Management:** These partners focus on data center storage, backup, and recovery solutions. -- **Networking:** These partners integrate with network-specific hardware and virtualized products such as routing, switching, firewalls, and SD-WAN solutions. -- **VCS (Version Control Systems):** These partners focus on VCS (Version Control System) projects, teams, and repositories from within Terraform. -- **Comms & Messaging:** These partners integrate with communication, email, and messaging platforms. -- **Database:** These partners offer capabilities to provision and configure your database resources. -- **PaaS (Platform-as-a-Service):** These are platform and PaaS providers that offer a range of hardware, software, and application development tools. This category includes smaller-scale providers and those with more specialized offerings. -- **Web Services:** These partners focus on web hosting, web performance, CDN and DNS services. - -Infrastructure partners integrate by building and publishing a plugin called a Terraform [provider](https://www.terraform.io/docs/language/providers/index.html). Providers are executable binaries written in Go that communicate with Terraform Core over an RPC interface. The provider acts as a translation layer for transactions with external APIs, such as a public cloud service (AWS, GCP, Azure), a PaaS service (Heroku), a SaaS service (DNSimple, CloudFlare), or on-prem resources (vSphere). Providers work across Terraform OSS, Terraform Cloud and Terraform Enterprise. Refer to the [Terraform Provider Integrations documentation](https://www.terraform.io/guides/terraform-integration-program.html#terraform-provider-integrations) for more detail. - - - -## Terraform Provider Integrations - -You can follow the five steps. below to develop your provider alongside HashiCorp. This ensures that you can publish new versions with Terraform quickly and efficiently. - -![Provider Development Process](/assets/images/docs/provider-program-steps.png) - -1. **Prepare**: Develop integration using included resources -2. **Publish**: Publish provider to the Registry or plugin documentation -3. **Apply**: Apply to Technology Partnership Program -4. **Verify**: Verify integration with HashiCorp Alliances team -5. **Support**: Vendor provides ongoing maintenance and support - -We encourage you to follow the tasks associated with each step fully to streamline the development process and minimize rework. - -All providers integrate into and operate with Terraform exactly the same way. The table below is intended to help users understand who develops, and maintains a particular provider. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TierDescriptionNamespace
Official providers are owned and maintained by HashiCorp hashicorp
Verified providers are owned and maintained by third-party technology partners. Providers in this tier indicate HashiCorp has verified the authenticity of the Provider’s publisher, and that the partner is a member of the HashiCorp Technology Partner Program.Third-party organization, e.g. cisco/aci
Community providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.
Maintainer’s individual or organization account, e.g. cyrilgdn/postgresql
Archived Providers are Official or Verified Providers that are no longer maintained by HashiCorp or the community. This may occur if an API is deprecated or interest was low.hashicorp or third-party
- - -### 1. Prepare -To get started with the Terraform provider development, we recommend reviewing and following the articles listed below. -#### Provider Development Kit - -a) Writing custom providers [guide](https://www.terraform.io/guides/writing-custom-terraform-providers.html) - -b) Creating a Terraform Provider for Just About Anything: [video](https://www.youtube.com/watch?v=noxwUVet5RE) - -c) Sample provider developed by [partner](http://container-solutions.com/write-terraform-provider-part-1/) - -d) Example provider for reference: [AWS](https://github.com/terraform-providers/terraform-provider-aws), [OPC](https://github.com/terraform-providers/terraform-provider-opc) - -e) Contributing to Terraform [guidelines](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md) - -f) HashiCorp developer [forum](https://discuss.hashicorp.com/c/terraform-providers/tf-plugin-sdk/43) - -Please submit questions or suggestions about the Terraform SDK and provider development to the HashiCorp Terraform plugin SDK forum. If you are new to provider development and would like assistance, you can leverage one of the following development agencies that have developed Terraform providers in the past: - -| Partner | Email | Website | -|--------------------|:-----------------------------|:---------------------| -| Crest Data Systems | malhar@crestdatasys.com | www.crestdatasys.com | -| DigitalOnUs | hashicorp@digitalonus.com | www.digitalonus.com | -| Akava | bd@akava.io | www.akava.io | -| OpenCredo | hashicorp@opencredo.com | www.opencredo.com | - -#### Provider License - -All Terraform providers listed as Verified must contain one of the following open source licenses: - -- CDDL 1.0, 2.0 -- CPL 1.0 -- Eclipse Public License (EPL) 1.0 -- MPL 1.0, 1.1, 2.0 -- PSL 2.0 -- Ruby's Licensing -- AFL 2.1, 3.0 -- Apache License 2.0 -- Artistic License 1.0, 2.0 -- Apache Software License (ASL) 1.1 -- Boost Software License -- BSD, BSD 3-clause, "BSD-new" -- CC-BY -- Microsoft Public License (MS-PL) -- MIT -### 2. Publish - -After your provider is complete and ready to release, you can publish it the integration to the [Terraform Registry](https://registry.terraform.io/). This makes it publicly available for all Terraform users. - -Follow the [Terraform Registry publishing documentation](https://www.terraform.io/docs/registry/providers/publishing.html) and review the [provider publishing learn guide](https://learn.hashicorp.com/tutorials/terraform/provider-release-publish?in=terraform/providers). If your company has multiple products with separate providers, we recommend publishing them under the same Github organization to help with discoverability. - -Once completed, your provider will be visible in the Terraform Registry and available to use in Terraform. Please confirm that everything looks correct and that documentation is rendering properly. - -### 3. Apply - -After your provider is published, connect with HashiCorp Alliances to onboard your integration to the HashiCorp technology ecosystem or [apply to become a technology partner](https://www.hashicorp.com/ecosystem/become-a-partner/#technology). - -### 4. Verify - -Work with your HashiCorp Alliances representative to verify the plugin within the Registry and become listed as an HashiCorp technology partner integration on HashiCorp website. - -### 5. Support - -Getting a new provider built and published to the Terraform Registry is just the first step towards enabling your users with a quality Terraform integration. Once a verified provider has been published, on-going effort is required to maintain the provider. - -HashiCorp Terraform has an extremely wide community of users and contributors and we encourage everyone to report issues however small, as well as help resolve them when possible. We expect that all verified provider publishers will continue to maintain the provider and address any issues users report in a timely manner. This includes resolving all critical issues within 48 hours and all other issues within 5 business days. HashiCorp reserves the right to remove verified status from any integration that is no longer being maintained. - -Vendors who choose not to support their provider and prefer to make it a community-supported provider will no longer be listed as Verified. - -## Terraform Cloud Integrations - -Run tasks allow Terraform Cloud to execute tasks in external systems at specific points in the Terraform Cloud run lifecycle. The beta release of this feature allows users to add and execute these tasks during the new pre-apply stage that exists in between the plan and apply stages. Tasks are executed by sending an API payload to the external system. This payload contains a collection of run-related information and a callback URL which the external system can use to send updates back to Terraform Cloud. - -The external system can then use this run information and respond back to Terraform Cloud with a passed or failed status. Terraform Cloud uses this status response to determine if a run should proceed, based on the task's enforcement settings within a workspace. - -Partners who successfully complete the Terraform Cloud Integration Checklist obtain a Terraform Cloud badge. This signifies HashiCorp has verified the integration and the partner is a member of the HashiCorp Technology Partner Program. - -- Note: Currently, pre-apply is the only integration phase available at this time. As of September 2021, run tasks are available only as a beta feature, are subject to change, and not all customers will see this functionality in their Terraform Cloud organization since this is currently enabled by default for our business tier customers of Terraform Cloud. If you have a customer that is interested in run tasks and are not a current Terraform Cloud for Business customer, customers can [sign up here](https://docs.google.com/forms/d/e/1FAIpQLSf3JJIkU05bKWov2wXa9c-QV524WNaHuGIk7xjHnwl5ceGw2A/viewform). - -![TFC Badge](/assets/images/docs/tfc-badge.png) - -The above badge will help drive visibility for the partner as well as provide better differentiation for joint customers. This badge will be available for partners to use at their digital properties (as per guidelines in the technology partner guide that partners receive when they join HashiCorp’s technology partner program). - -The Terraform Cloud Integration program has the following five steps. - -![RunTask Program Process](/assets/images/docs/runtask-program-steps.png) - -1. **Engage**: Sign up for the Technology Partner -Program -2. **Develop & Test**: Understand and build using the API integration for Run Tasks -3. **Review**: Review integration with HashiCorp Alliances team -4. **Release**: Provide documentation for your Integration -5. **Support**: Vendor provides ongoing maintanance and support - -### 1. Engage - -For partners who are new to working with Hashicorp, we recommend [signing up for our Technology Partner Program](https://www.hashicorp.com/go/tech-partner). To understand more about the program, check out our “[Become a Partner](https://www.hashicorp.com/partners/become-a-partner)” page. - -### 2. Develop & Test -Partners should build an integration using [Run Task APIs in Terraform Cloud](https://www.terraform.io/docs/cloud/api/run-tasks.html). To better understand how run Task enhances the workflow, see diagram listed below and check out our [announcement about Terraform run Task](https://www.hashicorp.com/blog/terraform-cloud-run-tasks-beta-now-available). [Snyk](https://docs.snyk.io/features/integrations/ci-cd-integrations/integrating-snyk-with-terraform-cloud), for example, created an integration to detect configuration anomalies in code while reducing risk to the infrastructure. For additional API resources, [click here](https://www.terraform.io/docs/cloud/api/index.html). -**Currently, pre-apply is the only integration phase available.** - -![RunTask Diagram](/assets/images/docs/runtask-diagram.png) - -### 3. Review - -Schedule time with your Partner Alliance manager to review your integration. The review should include enabling the integration on the partner’s platform and Terraform Cloud, explaining the use case for the integration, and a live demonstration of the functionality. If you are unable to engage with your Partner Alliances manager, you can also reach out to [technologypartners@hashicorp.com](technologypartners@hashicorp.com). - -### 4. Release - -We add new partners to the [Terraform Run Task page](https://www.terraform.io/docs/cloud/integrations/run-tasks/index.html#run-tasks-technology-partners) after the integration review and documentation is complete. On this page, you will provide a two-line summary about your integration(s). If you have multiple integrations, we highly recommend creating a summary that highlights all potential integration options. - -You must provide documentation that helps users get started with your integration. You also need to provide documentation for our support team, including points of contact, email address, FAQ and/or best practices. We want to ensure end users are able to reach the right contacts for internal HashiCorp support when working with customers. - -### 5. Support - -At HashiCorp, we view the release step to be the beginning of the journey. Getting the integration built is just the first step in enabling users to leverage it against their infrastructure. On-going effort is required to support and maintain it after you complete the initial development. - -We expect that partners will create a mechanism to track and resolve all critical issues as soon as possible (ideally within 48 hours) and all other issues within 5 business days. This is a requirement given the critical nature of Terraform Cloud to a customer’s operation. If you choose not to support your integration, we cannot consider it Verified and will not list it on the Terraform documentation website. - --> Contact us at technologypartners@hashicorp.com with any questions or feedback. diff --git a/website/guides/terraform-provider-development-program.html.md b/website/guides/terraform-provider-development-program.mdx similarity index 56% rename from website/guides/terraform-provider-development-program.html.md rename to website/guides/terraform-provider-development-program.mdx index 59d5ffc64..102446672 100644 --- a/website/guides/terraform-provider-development-program.html.md +++ b/website/guides/terraform-provider-development-program.mdx @@ -1,8 +1,9 @@ --- -layout: "extend" -page_title: "Terraform Provider Development Program" -sidebar_current: "guides-terraform-provider-development-program" -description: This guide is intended for vendors who're interested in having their platform supported by Terraform. The guide walks vendors through the steps involved in creating a provider and applying for it to be included with Terraform. +page_title: Terraform Provider Development Program +description: >- + This guide is intended for vendors who're interested in having their platform + supported by Terraform. The guide walks vendors through the steps involved in + creating a provider and applying for it to be included with Terraform. --- # Terraform Provider Development Program @@ -11,10 +12,9 @@ The Terraform Provider Development Program facilitates vendors in creating and p The Verified badge helps users easily identify and discover integrations developed and maintained directly by an integration’s vendor, establishing a level of trust for our users. This program is intended to be largely self-serve, with links to information sources, clearly defined steps, and checkpoints detailed below. -![Verified Provider Card](/assets/images/docs/verified-card.png) - --> **Building your own provider?** If you're building your own provider and aren't interested in having HashiCorp officially verify and regularly monitor your provider, please refer to the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITEhttps://www.terraform.io/docs/extend/writing-custom-providers.htmlutm_medium=WEB_IOhttps://www.terraform.io/docs/extend/writing-custom-providers.htmlutm_offer=ARTICLE_PAGEhttps://www.terraform.io/docs/extend/writing-custom-providers.htmlutm_content=DOCS) collection on HashiCorp Learn and the [Extending Terraform](https://www.terraform.io/docs/extend/index.html) section of the documentation. +![Verified Provider Card](/img/docs/verified-card.png) +-> **Building your own provider?** If you're building your own provider and aren't interested in having HashiCorp officially verify and regularly monitor your provider, please refer to the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITEhttps://www.terraform.io/docs/extend/writing-custom-providers.htmlutm_medium=WEB_IOhttps://www.terraform.io/docs/extend/writing-custom-providers.htmlutm_offer=ARTICLE_PAGEhttps://www.terraform.io/docs/extend/writing-custom-providers.htmlutm_content=DOCS) collection on HashiCorp Learn and the [Extending Terraform](/plugin) section of the documentation. ## What is a Terraform Provider? @@ -24,72 +24,41 @@ A Terraform Provider represents an integration that is responsible for understan All providers integrate into and operate with Terraform exactly the same way. The table below is intended to help users understand who develops, and maintains a particular provider. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TierDescriptionNamespace
Official providers are owned and maintained by HashiCorp hashicorp
Verified providers are owned and maintained by third-party technology partners. Providers in this tier indicate HashiCorp has verified the authenticity of the Provider’s publisher, and that the partner is a member of the HashiCorp Technology Partner Program.Third-party organization, e.g. mongodb/mongodbatlas
Community providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.
Maintainer’s individual or organization account, e.g. DeviaVir/gsuite
Archived Providers are Official or Verified Providers that are no longer maintained by HashiCorp or the community. This may occur if an API is deprecated or interest was low.hashicorp or third-party
+

- --> **Note:** This document focuses on the "Verified" Tier in the table above. Community contributors interested in contributing to existing providers or building new providers should refer to the [Publishing a Provider](https://www.terraform.io/docs/registry/providers/publishing.html) section of our documentation. - +-> **Note:** This document focuses on the "Verified" Tier in the table above. Community contributors interested in contributing to existing providers or building new providers should refer to the [Publishing a Provider](/registry/providers/publishing) section of our documentation. ## Provider Development Process The provider development process is divided into five steps below. By following these steps, providers can be developed alongside HashiCorp to ensure new providers are able to be published in Terraform as quickly as possible. -![Provider Development Process](/assets/images/docs/program-steps.png) +![Provider Development Process](/img/docs/program-steps.png) 1. **Apply**: Initial contact between vendor and HashiCorp -2. **Prepare**: Follow documentation while developing the provider -3. **Verify**: Share public GPG key with HashiCorp -4. **Publish**: Release the provider on the Registry -5. **Support**: Ongoing maintenance and support of the provider by the vendor. +1. **Prepare**: Follow documentation while developing the provider +1. **Verify**: Share public GPG key with HashiCorp +1. **Publish**: Release the provider on the Registry +1. **Support**: Ongoing maintenance and support of the provider by the vendor. ### 1. Apply -Please begin by completing our HashiCorp Technology Partner application: https://www.hashicorp.com/ecosystem/become-a-partner/#technology +Please begin by completing our HashiCorp Technology Partner application: Terraform has a large and active ecosystem of partners that may have already started working on the same provider. We'll do our best to connect similar parties to avoid duplicate efforts, and prepare for a successful and impactful launch of the integration. Once you have applied, a member of the HashiCorp Alliances team will be in touch, and will ask for your organization to sign our Technology Partner Agreement. - ### 2. Prepare -Detailed instructions for preparing a provider for publishing are available in our Registry documentation. Please see [Preparing your Provider](https://www.terraform.io/docs/registry/providers/publishing.html#preparing-your-provider). In order to provide a consistent and quality experience for users, please make sure detailed documentation for your provider is included. You can find more information on how to build and structure [provider documentation here](https://www.terraform.io/docs/registry/providers/docs.html). +Detailed instructions for preparing a provider for publishing are available in our Registry documentation. Please see [Preparing your Provider](/registry/providers/publishing#preparing-your-provider). In order to provide a consistent and quality experience for users, please make sure detailed documentation for your provider is included. You can find more information on how to build and structure [provider documentation here](/registry/providers/docs). We’ve found the provider development process to be fairly straightforward and simple when you pay close attention and follow the resources below. If you have not developed a provider before and are looking for some help in developing one, you may choose to leverage one of the following development agencies which have developed Terraform providers in the past and are familiar with the requirements and process: -| Partner | Email | Website | -|--------------------|:-----------------------------|:---------------------| -| Crest Data Systems | malhar@crestdatasys.com | www.crestdatasys.com | -| DigitalOnUs | hashicorp@digitalonus.com | www.digitalonus.com | -| Akava | bd@akava.io | www.akava.io | -| OpenCredo | hashicorp@opencredo.com | www.opencredo.com | +| Partner | Email | Website | +| ------------------ | :-------------------------- | :-------------------------------------------------- | +| Crest Data Systems | | [www.crestdatasys.com](http://www.crestdatasys.com) | +| DigitalOnUs | | [www.digitalonus.com](http://www.digitalonus.com) | +| Akava | | [www.akava.io](http://www.akava.io) | +| OpenCredo | | [www.opencredo.com](http://www.opencredo.com) | -> **Important:** All Terraform providers listed as Verified must contain one of the following open source licenses: @@ -109,14 +78,13 @@ We’ve found the provider development process to be fairly straightforward and - Microsoft Public License (MS-PL) - MIT - ### 3. Verify At this stage, it is expected that the provider is fully developed, all tests and documentation are in place, and your provider is ready for publishing. In this step, HashiCorp will verify the source and authenticity of the namespace being used to publish the provider by signing your GPG key with a trust signature. -> **Important:** This step requires that you have signed and accepted our Technology Partner Agreement. If you have not received this, please see step #1 above. -Please send your public key to terraform-registry@hashicorp.com, indicating you are a partner seeking verification, and a HashiCorp employee will be in touch to help verify, and add your key. +Please send your public key to , indicating you are a partner seeking verification, and a HashiCorp employee will be in touch to help verify, and add your key. To export your public key in ASCII-armor format, use the following command: @@ -126,7 +94,7 @@ $ gpg --armor --export "{Key ID or email address}" ### 4. Publish -Once the verification step is complete please follow the steps on [Publishing a Provider](https://www.terraform.io/docs/registry/providers/publishing.html). This step does not require additional involvement from HashiCorp as publishing is a fully self-service process in the [Terraform Registry](https://registry.terraform.io). +Once the verification step is complete please follow the steps on [Publishing a Provider](/registry/providers/publishing). This step does not require additional involvement from HashiCorp as publishing is a fully self-service process in the [Terraform Registry](https://registry.terraform.io). Once completed, your provider should be visible in the Terraform Registry and usable in Terraform. Please confirm that everything looks good, and that documentation is rendering properly. diff --git a/website/guides/core-workflow.html.md b/website/intro/core-workflow.mdx similarity index 93% rename from website/guides/core-workflow.html.md rename to website/intro/core-workflow.mdx index 2cd010ee5..62afc53dc 100644 --- a/website/guides/core-workflow.html.md +++ b/website/intro/core-workflow.mdx @@ -1,9 +1,6 @@ --- -layout: "intro" -page_title: "The Core Terraform Workflow - Guides" -sidebar_current: "guides-core-workflow" -description: |- - An overview of how individuals, teams, and organizations can use Terraform. +page_title: The Core Terraform Workflow - Guides +description: 'An overview of how individuals, teams, and organizations can use Terraform. ' --- # The Core Terraform Workflow @@ -11,8 +8,8 @@ description: |- The core Terraform workflow has three steps: 1. **Write** - Author infrastructure as code. -2. **Plan** - Preview changes before applying. -3. **Apply** - Provision reproducible infrastructure. +1. **Plan** - Preview changes before applying. +1. **Apply** - Provision reproducible infrastructure. This guide walks through how each of these three steps plays out in the context of working as an individual practitioner, how they evolve when a team is @@ -184,7 +181,7 @@ requests should include an attached copy of speculative plan output generated by the change author. Others arrange for their CI system to post speculative plan output to pull requests automatically. -![Screenshot of Pull Request with manually posted Terraform plan output](guides/core-workflow/manually-pasted-plan-output.png) +![Screenshot of Pull Request with manually posted Terraform plan output](/img/docs/manually-pasted-plan-output.png) In addition to reviewing the plan for the proper expression of its author's intent, the team can also make an evaluation whether they want this change to @@ -233,7 +230,7 @@ for a better experience at each step. Terraform Cloud provides a centralized and secure location for storing input variables and state while also bringing back a tight feedback loop for speculative plans for config authors. Terraform configuration interacts with -Terraform Cloud via the ["remote" backend](/docs/language/settings/backends/remote.html). +Terraform Cloud via the ["remote" backend](/language/settings/backends/remote). ``` terraform { @@ -283,14 +280,14 @@ request indicate while the plan is in progress. Once the plan is complete, the status update indicates whether there were any changes in the speculative plan, right from the pull request view. -![Screenshot of Pull Request with resource changes in the status update](guides/core-workflow/pull-request.png) +![Screenshot of Pull Request with resource changes in the status update](/img/docs/pull-request.png) For certain types of changes, this information is all that's needed for a team member to be able to approve the pull request. When a teammate needs to do a full review of the plan, clicking the link to Terraform Cloud brings up a view that allows them to quickly analyze the full plan details. -![Screenshot of Pull Request run in Terraform Cloud](guides/core-workflow/pr-plan.png) +![Screenshot of Pull Request run in Terraform Cloud](/img/docs/pr-plan.png) This page allows the reviewer to quickly determine if the plan is matching the config author's intent and evaluate the risk of the change. @@ -300,17 +297,17 @@ config author's intent and evaluate the risk of the change. After merge, Terraform Cloud presents the concrete plan to the team for review and approval. -![Screenshot of concrete plan](guides/core-workflow/concrete-plan.png) +![Screenshot of concrete plan](/img/docs/concrete-plan.png) The team can discuss any outstanding questions about the plan before the change is made. -![Screenshot of back-and-forth in Terraform Cloud comments](guides/core-workflow/plan-comments.png) +![Screenshot of back-and-forth in Terraform Cloud comments](/img/docs/plan-comments.png) Once the Apply is confirmed, Terraform Cloud displays the progress live to anyone who'd like to watch. -![Screenshot of in-progress Apply](guides/core-workflow/in-progress-apply.png) +![Screenshot of in-progress Apply](/img/docs/in-progress-apply.png)