diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.html.md similarity index 64% rename from website/docs/cli/auth/index.mdx rename to website/docs/cli/auth/index.html.md index 3d09a4f93..cb61fbcdf 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.html.md @@ -1,23 +1,21 @@ --- -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. -sidebar_title: Authentication +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." --- # 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](/cloud-docs/) and -[Terraform Enterprise](/enterprise/) are platforms that perform +[Terraform Cloud](/docs/cloud/index.html) and +[Terraform Enterprise](/docs/enterprise/index.html) 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](/cloud-docs/run/cli) in Terraform Cloud, +front-end for [CLI-driven runs](/docs/cloud/run/cli.html) 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. @@ -28,5 +26,5 @@ Terraform Cloud user account. For details, see: -- [The `terraform login` command](/cli/commands/login) -- [The `terraform logout` command](/cli/commands/logout) +- [The `terraform login` command](/docs/cli/commands/login.html) +- [The `terraform logout` command](/docs/cli/commands/logout.html) diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.html.md similarity index 65% rename from website/docs/cli/code/index.mdx rename to website/docs/cli/code/index.html.md index ba1a408c0..bf858dd6b 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.html.md @@ -1,14 +1,12 @@ --- -page_title: Writing and Modifying Code - Terraform CLI -description: >- - Learn commands that help validate, format, and upgrade code written in the - Terraform Configuration Language. -sidebar_title: Writing and Modifying Code +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." --- # Writing and Modifying Terraform Code -The [Terraform language](/language/) is Terraform's primary +The [Terraform language](/docs/language/index.html) is Terraform's primary user interface, and all of Terraform's workflows rely on configurations written in the Terraform language. @@ -16,17 +14,18 @@ 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](/cli/commands/console) starts an +- [The `terraform console` command](/docs/cli/commands/console.html) starts an interactive shell for evaluating Terraform - [expressions](/language/expressions/), which can be a faster way + [expressions](/docs/language/expressions/index.html), which can be a faster way to verify that a particular resource argument results in the value you expect. -- [The `terraform fmt` command](/cli/commands/fmt) rewrites Terraform + +- [The `terraform fmt` command](/docs/cli/commands/fmt.html) rewrites Terraform configuration files to a canonical format and style, so you don't have to 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](/cli/commands/validate) validates the +- [The `terraform validate` command](/docs/cli/commands/validate.html) 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 @@ -34,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](/cli/commands/0.13upgrade) and - [the `0.12upgrade` command](/cli/commands/0.12upgrade) can automatically +- [The `0.13upgrade` command](/docs/cli/commands/0.13upgrade.html) and + [the `0.12upgrade` command](/docs/cli/commands/0.12upgrade.html) 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/) in the Terraform language docs. + guides](/upgrade-guides/index.html) in the Terraform language docs. diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.html.md similarity index 90% rename from website/docs/cli/commands/0.12upgrade.mdx rename to website/docs/cli/commands/0.12upgrade.html.md index 192a1103e..59ff0de44 100644 --- a/website/docs/cli/commands/0.12upgrade.mdx +++ b/website/docs/cli/commands/0.12upgrade.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Command: 0.12upgrade' -description: >- - The 0.12upgrade subcommand automatically rewrites existing configurations for - Terraform 0.12 compatibility. +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. --- # Command: 0.12upgrade @@ -11,7 +12,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](/upgrade-guides/0-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). ## Usage @@ -70,13 +71,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](/language/modules/syntax#version) +[fix existing configurations to a previous version](/docs/language/modules/syntax.html#version) to allow for a gradual upgrade. If the module is published via -[a Terraform registry](/registry/), assign a new _major_ version number +[a Terraform registry](/docs/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](/language/modules/sources#selecting-a-revision) +[use specific revisions](https://www.terraform.io/docs/language/modules/sources.html#selecting-a-revision) to control which version is used by which caller. The command-line options are all optional. The available options are: @@ -106,9 +107,9 @@ 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`. + 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.mdx b/website/docs/cli/commands/0.13upgrade.html.md similarity index 92% rename from website/docs/cli/commands/0.13upgrade.mdx rename to website/docs/cli/commands/0.13upgrade.html.md index d8697a653..52ff42067 100644 --- a/website/docs/cli/commands/0.13upgrade.mdx +++ b/website/docs/cli/commands/0.13upgrade.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Command: 0.13upgrade' -description: >- - The 0.13upgrade subcommand updates existing configurations to use the new - provider source features from Terraform 0.13. +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. --- # Command: 0.13upgrade @@ -11,7 +12,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](/upgrade-guides/0-13). +-> **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). ## Usage @@ -22,7 +23,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]: /language/providers/requirements +[required-providers]: /docs/language/providers/requirements.html ~> Note: the command ignores `.tf.json` files and override files in the module. diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.html.md similarity index 82% rename from website/docs/cli/commands/apply.mdx rename to website/docs/cli/commands/apply.html.md index ece491cdc..09172c542 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.html.md @@ -1,8 +1,8 @@ --- -page_title: 'Command: apply' -description: >- - The terraform apply command executes the actions proposed in a Terraform plan - to create, update, or destroy infrastructure. +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." --- # 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`](/cli/commands/plan) would. +plan of action, in the same way that [`terraform plan`](./plan.html) 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](/cli/commands/plan#planning-modes) and -[planning options](/cli/commands/plan#planning-options) that `terraform plan` would +[planning modes](./plan.html#planning-modes) and +[planning options](./plan.html#planning-options) that `terraform plan` would accept, so you can customize how Terraform will create the plan. ### 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`](/cli/commands/show). +[`terraform show`](./show.html). 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](/cli/commands/plan#planning-modes) -* [Planning Options](/cli/commands/plan#planning-options) +- [Planning Modes](./plan.html#planning-modes) +- [Planning Options](./plan.html#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`](/cli/commands/plan). +[`terraform plan`](./plan.html). * `-auto-approve` - Skips interactive approval of plan before applying. This option is ignored when you pass a previously-saved plan file, because @@ -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]: /internals/machine-readable-ui + [machine-readable-ui]: /docs/internals/machine-readable-ui.html * `-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](/internals/graph#walking-the-graph). Defaults to - 10\. + [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to + 10. For configurations using -[the `local` backend](/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local.html) only, `terraform apply` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#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](/cli/commands/#switching-working-directory-with-chdir) +[the `-chdir` global option](./#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the 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](/cli/config/environment-variables#tf_data_dir) +[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#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.mdx b/website/docs/cli/commands/console.html.md similarity index 77% rename from website/docs/cli/commands/console.mdx rename to website/docs/cli/commands/console.html.md index 9168a45e3..23682b562 100644 --- a/website/docs/cli/commands/console.mdx +++ b/website/docs/cli/commands/console.html.md @@ -1,36 +1,37 @@ --- -page_title: 'Command: console' -description: >- - The terraform console command provides an interactive console for evaluating - expressions. +layout: "docs" +page_title: "Command: console" +sidebar_current: "docs-commands-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](/language/expressions/). +evaluating [expressions](/docs/language/expressions/index.html). ## Usage Usage: `terraform console [options]` This command provides an interactive command-line console for evaluating and -experimenting with [expressions](/language/expressions/). +experimenting with [expressions](/docs/language/expressions/index.html). This is useful for testing interpolations before using them in configurations, and for interacting with any values currently saved in -[state](/language/state/). +[state](/docs/language/state/index.html). 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](/language/functions/). +[built-in functions](/docs/language/functions/index.html). You can close the console with the `exit` command or by pressing Control-C or Control-D. For configurations using -[the `local` backend](/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local.html) only, `terraform console` accepts the legacy command line option -[`-state`](/language/settings/backends/local#command-line-arguments). +[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). ## Scripting @@ -51,7 +52,7 @@ tolist([ ## Remote State -If [remote state](/language/state/remote) is used by the current backend, +If [remote state](/docs/language/state/remote.html) 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.mdx b/website/docs/cli/commands/destroy.html.md similarity index 78% rename from website/docs/cli/commands/destroy.mdx rename to website/docs/cli/commands/destroy.html.md index beb9782eb..4e45bbe3d 100644 --- a/website/docs/cli/commands/destroy.mdx +++ b/website/docs/cli/commands/destroy.html.md @@ -1,8 +1,8 @@ --- -page_title: 'Command: destroy' -description: >- - The terraform destroy command destroys all objects managed by a Terraform - configuration. +layout: "docs" +page_title: "Command: destroy" +sidebar_current: "docs-commands-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`](/cli/commands/apply) accepts, although it does +[`terraform apply`](./apply.html) 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`](/cli/commands/plan) in _destroy_ mode, showing +This will run [`terraform plan`](./plan.html) 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 new file mode 100644 index 000000000..bbaacc530 --- /dev/null +++ b/website/docs/cli/commands/env.html.md @@ -0,0 +1,12 @@ +--- +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 deleted file mode 100644 index 08b3139df..000000000 --- a/website/docs/cli/commands/env.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -page_title: 'Command: env' -description: >- - The terraform env command is a deprecated form of the terraform workspace - command. ---- - -# Command: env - -The `terraform env` command is deprecated. -[The `terraform workspace` command](/cli/commands/workspace/) -should be used instead. diff --git a/website/docs/cli/commands/fmt.mdx b/website/docs/cli/commands/fmt.html.md similarity index 89% rename from website/docs/cli/commands/fmt.mdx rename to website/docs/cli/commands/fmt.html.md index c6868d733..b25a476b4 100644 --- a/website/docs/cli/commands/fmt.mdx +++ b/website/docs/cli/commands/fmt.html.md @@ -1,15 +1,15 @@ --- -page_title: 'Command: fmt' -description: >- - The terraform fmt command rewrites configuration files to a canonical format - and style. +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." --- # 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](/language/syntax/style), +the [Terraform language style conventions](/docs/language/syntax/style.html), 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.mdx b/website/docs/cli/commands/force-unlock.html.md similarity index 71% rename from website/docs/cli/commands/force-unlock.mdx rename to website/docs/cli/commands/force-unlock.html.md index 735eec489..0ad7a6285 100644 --- a/website/docs/cli/commands/force-unlock.mdx +++ b/website/docs/cli/commands/force-unlock.html.md @@ -1,8 +1,8 @@ --- -page_title: 'Command: force-unlock' -description: >- - The terraform force-unlock command unlocks the state for a configuration. It - does not modify your infrastructure. +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." --- # 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.mdx b/website/docs/cli/commands/get.html.md similarity index 60% rename from website/docs/cli/commands/get.mdx rename to website/docs/cli/commands/get.html.md index 7dd5f199c..47f4e6cfa 100644 --- a/website/docs/cli/commands/get.mdx +++ b/website/docs/cli/commands/get.html.md @@ -1,12 +1,14 @@ --- -page_title: 'Command: get' -description: The terraform get command downloads and updates modules. +layout: "docs" +page_title: "Command: get" +sidebar_current: "docs-commands-get" +description: "The terraform get command downloads and updates modules." --- # Command: get The `terraform get` command is used to download and update -[modules](/language/modules/develop/) mentioned in the root module. +[modules](/docs/language/modules/develop/index.html) mentioned in the root module. ## Usage @@ -19,6 +21,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.mdx b/website/docs/cli/commands/graph.html.md similarity index 74% rename from website/docs/cli/commands/graph.mdx rename to website/docs/cli/commands/graph.html.md index 969c6e5db..cfc915667 100644 --- a/website/docs/cli/commands/graph.mdx +++ b/website/docs/cli/commands/graph.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # Command: graph @@ -12,6 +12,7 @@ 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]` @@ -32,16 +33,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 @@ -54,4 +55,4 @@ $ terraform graph | dot -Tsvg > graph.svg ``` Here is an example graph output: -![Graph Example](/img/docs/graph-example.png) +![Graph Example](docs/graph-example.png) diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.html.md similarity index 79% rename from website/docs/cli/commands/import.mdx rename to website/docs/cli/commands/import.html.md index 0bf0bae26..7c26b1758 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.html.md @@ -1,6 +1,8 @@ --- -page_title: 'Command: import' -description: The terraform import command brings existing resources into Terraform state. +layout: "docs" +page_title: "Command: import" +sidebar_current: "docs-commands-import" +description: "The terraform import command brings existing resources into Terraform state." --- # Command: import @@ -8,7 +10,7 @@ description: The terraform import command brings existing resources into Terrafo > **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](/cli/import/) +[import existing resources](/docs/cli/import/index.html) into Terraform. ## Usage @@ -18,7 +20,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](/cli/state/resource-addressing). +ADDRESS must be a valid [resource address](/docs/cli/state/resource-addressing.html). Because any resource address is valid, the import command can import resources into modules as well as directly into the root of your state. @@ -34,7 +36,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](/language/state/). +[the State section](/docs/language/state/index.html). The command-line flags are all optional. The list of available flags are: @@ -46,29 +48,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](/internals/graph#walking-the-graph). Defaults + [walks the graph](/docs/internals/graph.html#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](/language/expressions/types) in the + [literal expressions](/docs/language/expressions/types.html) 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](/language/values/variables#variable-definitions-tfvars-files). If + a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If a `terraform.tfvars` or any `.auto.tfvars` files are present in the current directory, they will be automatically loaded. `terraform.tfvars` is loaded first and the `.auto.tfvars` files after in alphabetical order. Any files @@ -77,15 +79,15 @@ The command-line flags are all optional. The list of available flags are: useful with the `-config` flag. For configurations using -[the `remote` backend](/language/settings/backends/remote) +[the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform import` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). For configurations using -[the `local` backend](/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local.html) only, `terraform import` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). ## Provider Configuration @@ -133,7 +135,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`](/language/meta-arguments/count): +[`count`](/docs/language/meta-arguments/count.html): ```shell $ terraform import 'aws_instance.baz[0]' i-abcd1234 @@ -142,7 +144,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`](/language/meta-arguments/for_each): +[`for_each`](/docs/language/meta-arguments/for_each.html): Linux, Mac OS, and UNIX: diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.html.md similarity index 93% rename from website/docs/cli/commands/index.mdx rename to website/docs/cli/commands/index.html.md index 99ba47df6..6fb5919a7 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.html.md @@ -1,6 +1,8 @@ --- -page_title: Basic CLI Features -description: An introduction to the terraform command and its available subcommands. +layout: "docs" +page_title: "Basic CLI Features" +sidebar_current: "docs-commands" +description: "An introduction to the terraform command and its available subcommands." --- # Basic CLI Features @@ -15,8 +17,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](/cloud-docs/) or -the various [Terraform providers](/language/providers/), which +[Terraform Cloud](/docs/cloud/) or +the various [Terraform providers](/docs/language/providers/index.html), which are developed and released separately from Terraform CLI. To view a list of the commands available in your current Terraform version, @@ -98,7 +100,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](/cli/config/config-file) are not for a specific +* Settings in the [CLI Configuration](/docs/cli/config/config-file.html) are not for a specific subcommand and Terraform processes them before acting on the `-chdir` option. @@ -151,7 +153,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](/cli/config/config-file) can be used to +[the CLI configuration file](/docs/cli/config/config-file.html) 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.mdx b/website/docs/cli/commands/init.html.md similarity index 83% rename from website/docs/cli/commands/init.mdx rename to website/docs/cli/commands/init.html.md index 47b38e528..6a62906a5 100644 --- a/website/docs/cli/commands/init.mdx +++ b/website/docs/cli/commands/init.html.md @@ -1,8 +1,8 @@ --- -page_title: 'Command: init' -description: >- - The terraform init command initializes a working directory containing - configuration files and installs plugins for required providers. +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." --- # 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](/language/settings/backends/configuration) and the chosen backend +[backend configuration](/docs/language/settings/backends/configuration.html) 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](/language/settings/backends/configuration#partial-configuration), +[partial backend configuration](/docs/language/settings/backends/configuration.html#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](/language/modules/develop/) is retrieved from the locations +code for referenced [modules](/docs/language/modules/develop/index.html) 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](/cli/config/config-file#provider-installation). +[the provider installation settings in the CLI configuration](/docs/cli/config/config-file.html#provider-installation). For more information about specifying which providers are required for each -of your modules, see [Provider Requirements](/language/providers/requirements). +of your modules, see [Provider Requirements](/docs/language/providers/requirements.html). After successful installation, Terraform writes information about the selected -providers to [the dependency lock file](/language/dependency-lock). +providers to [the dependency lock file](/docs/language/dependency-lock.html). 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`](/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 + -> 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 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](/cli/config/config-file#provider-installation). + [configuring Terraform's installation methods globally](/docs/cli/config/config-file.html#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](/cli/commands/#switching-working-directory-with-chdir) +[the `-chdir` global option](./#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the 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](/cli/config/environment-variables#tf_data_dir) +[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#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.mdx b/website/docs/cli/commands/login.html.md similarity index 72% rename from website/docs/cli/commands/login.mdx rename to website/docs/cli/commands/login.html.md index 86e1fcfee..8af1ef7a4 100644 --- a/website/docs/cli/commands/login.mdx +++ b/website/docs/cli/commands/login.html.md @@ -1,9 +1,9 @@ --- -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. +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. --- # 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](/cli/config/config-file#credentials). +[configure credentials manually in the CLI configuration](https://www.terraform.io/docs/cli/config/config-file.html#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](/cli/config/config-file#credentials-helpers) which knows +[credentials helper program](/docs/cli/config/config-file.html#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](/internals/login-protocol), including Terraform Cloud +[login protocol](/docs/internals/login-protocol.html), including Terraform Cloud and Terraform Enterprise. diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.html.md similarity index 79% rename from website/docs/cli/commands/logout.mdx rename to website/docs/cli/commands/logout.html.md index dbec4bc75..15656fba9 100644 --- a/website/docs/cli/commands/logout.mdx +++ b/website/docs/cli/commands/logout.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Command: logout' -description: >- - The terraform logout command is used to remove credentials stored by terraform - login. +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. --- # Command: logout @@ -25,5 +26,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](/cli/config/config-file#credentials-helpers), Terraform +[credentials helper program](/docs/cli/config/config-file.html#credentials-helpers), Terraform will use the helper's `forget` command to remove it. diff --git a/website/docs/cli/commands/output.mdx b/website/docs/cli/commands/output.html.md similarity index 81% rename from website/docs/cli/commands/output.mdx rename to website/docs/cli/commands/output.html.md index 2fe970ba7..a09725e21 100644 --- a/website/docs/cli/commands/output.mdx +++ b/website/docs/cli/commands/output.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Command: output' -description: >- - The `terraform output` command is used to extract the value of an output - variable from the state file. +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. --- # Command: output @@ -21,20 +22,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](/language/state/remote) is used. + Ignored when [remote state](/docs/language/state/remote.html) 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](/language/state/sensitive-data). +see [Sensitive Data in State](/docs/language/state/sensitive-data.html). ## Examples diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.html.md similarity index 78% rename from website/docs/cli/commands/plan.mdx rename to website/docs/cli/commands/plan.html.md index 61f5833c5..cdb3bbe27 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # 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`](/cli/commands/apply) directly. By default, the "apply" command +[`terraform apply`](./apply.html) 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`](/cli/commands/apply) as an extra argument. This two-step workflow +[`terraform apply`](./apply.html) 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`](/cli/commands/destroy). +earlier versions you must run [`terraform destroy`](./destroy.html). -> **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`](/cli/commands/taint). + 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). * `-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](/language/values/variables) declared in the + [input variable](/docs/language/values/variables.html) 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](/language/values/variables) declared in the + [input variables](/docs/language/values/variables.html) declared in the root module of the configuration, using definitions from a - ["tfvars" file](/language/values/variables#variable-definitions-tfvars-files). + ["tfvars" file](/docs/language/values/variables.html#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](/language/values/variables#assigning-values-to-root-module-variables). +[Assigning Values to Root Module Variables](/docs/language/values/variables.html#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](/language/values/variables) declared in your +[input variables](/docs/language/values/variables.html) 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](/language/expressions/type-constraints). +on the variable's [type constraint](/docs/language/expressions/type-constraints.html). 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,7 +262,8 @@ 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](/language/values/variables#assigning-values-to-root-module-variables). +[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables). + ### Resource Targeting @@ -270,7 +271,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](/cli/state/resource-addressing) +You can use [resource address syntax](/docs/cli/state/resource-addressing.html) to specify the constraint. Terraform interprets the resource address as follows: * If the given address identifies one specific resource instance, Terraform @@ -295,14 +296,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](/language/data-sources/) can be used to access +[Data sources](/docs/language/data-sources/index.html) 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. @@ -338,11 +339,11 @@ The available options are: This implies `-input=false`, so the configuration must have no unassigned variable values to continue. - [machine-readable-ui]: /internals/machine-readable-ui + [machine-readable-ui]: /docs/internals/machine-readable-ui.html * `-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 @@ -358,28 +359,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](/internals/graph#walking-the-graph). Defaults + [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults to 10. For configurations using -[the `local` backend](/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local.html) only, `terraform plan` accepts the legacy command line option -[`-state`](/language/settings/backends/local#command-line-arguments). +[`-state`](/docs/language/settings/backends/local.html#command-line-arguments). ### Passing a Different Configuration Directory @@ -389,7 +390,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](/cli/commands/#switching-working-directory-with-chdir) +[the `-chdir` global option](./#switching-working-directory-with-chdir) instead, which works across all commands and makes Terraform consistently look in the given directory for all files it would normally read or write in the current working directory. @@ -397,6 +398,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](/cli/config/environment-variables#tf_data_dir) +[the `TF_DATA_DIR` environment variable](/docs/cli/config/environment-variables.html#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.mdx b/website/docs/cli/commands/providers.html.md similarity index 55% rename from website/docs/cli/commands/providers.mdx rename to website/docs/cli/commands/providers.html.md index 9d2b6c722..a39d0ee0f 100644 --- a/website/docs/cli/commands/providers.mdx +++ b/website/docs/cli/commands/providers.html.md @@ -1,14 +1,14 @@ --- -page_title: 'Command: providers' -description: >- - The terraform providers command prints information about the providers - required in the current configuration. +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." --- # Command: providers The `terraform providers` command shows information about the -[provider requirements](/language/providers/requirements) of the +[provider requirements](/docs/language/providers/requirements.html) 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.mdx b/website/docs/cli/commands/providers/lock.html.md similarity index 76% rename from website/docs/cli/commands/providers/lock.mdx rename to website/docs/cli/commands/providers/lock.html.md index 7e7ccced2..b9a48fae7 100644 --- a/website/docs/cli/commands/providers/lock.mdx +++ b/website/docs/cli/commands/providers/lock.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Command: providers lock' +layout: "docs" +page_title: "Command: providers lock" +sidebar_current: "docs-commands-providers-lock" description: |- The `terraform providers lock` command adds new provider selection information to the dependency lock file without initializing the referenced providers. @@ -9,31 +11,31 @@ description: |- The `terraform providers lock` consults upstream registries (by default) in order to write provider dependency information into -[the dependency lock file](/language/dependency-lock). +[the dependency lock file](/docs/language/dependency-lock.html). The common way to update the dependency lock file is as a side-effect of normal provider installation during -[`terraform init`](/cli/commands/init), but there are several situations where that +[`terraform init`](/docs/cli/commands/init.html), 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](/cli/config/config-file#provider-installation), + [alternative provider installation methods](/docs/cli/config/config-file.html#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](/language/dependency-lock#new-provider-package-checksums). + [add additional checksums to the lock file](/docs/language/dependency-lock.html#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. @@ -47,17 +49,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](/language/dependency-lock) to +[the dependency lock file](/docs/language/dependency-lock.html) 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, @@ -72,21 +74,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](/internals/provider-network-mirror-protocol). + [the Terraform provider network mirror protocol](/docs/internals/provider-network-mirror-protocol.html). * `-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. - 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. - 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. + There is more detail on this option in the following section. ## Specifying Target Platforms @@ -148,7 +150,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](/cli/config/config-file#provider-installation), +[the provider installation methods configuration](/docs/cli/config/config-file.html#provider-installation), but specify only a single method in order to be explicit about where you intend to derive the package checksum information from. @@ -165,4 +167,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](/internals/provider-registry-protocol). +[the provider registry protocol](/docs/internals/provider-registry-protocol.html). diff --git a/website/docs/cli/commands/providers/mirror.mdx b/website/docs/cli/commands/providers/mirror.html.md similarity index 89% rename from website/docs/cli/commands/providers/mirror.mdx rename to website/docs/cli/commands/providers/mirror.html.md index d6f9c8c8c..b0827837e 100644 --- a/website/docs/cli/commands/providers/mirror.mdx +++ b/website/docs/cli/commands/providers/mirror.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Command: providers mirror' +layout: "docs" +page_title: "Command: providers mirror" +sidebar_current: "docs-commands-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 @@ -17,7 +19,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](/cli/config/config-file#explicit-installation-method-configuration) +[explicit installation method configuration](/docs/cli/config/config-file.html#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. @@ -39,7 +41,7 @@ themselves. Terraform will also generate various `.json` index files which contain suitable responses to implement -[the network mirror protocol](/internals/provider-network-mirror-protocol), +[the network mirror protocol](/docs/internals/provider-network-mirror-protocol.html), 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.mdx b/website/docs/cli/commands/providers/schema.html.md similarity index 93% rename from website/docs/cli/commands/providers/schema.mdx rename to website/docs/cli/commands/providers/schema.html.md index fbdeafc70..2a3dddc13 100644 --- a/website/docs/cli/commands/providers/schema.mdx +++ b/website/docs/cli/commands/providers/schema.html.md @@ -1,9 +1,9 @@ --- -page_title: 'Command: providers schema' -description: >- - The `terraform providers schema` command prints detailed schemas for the - providers used - +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 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](/language/v1-compatibility-promises). +[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). ## Format Summary diff --git a/website/docs/cli/commands/push.mdx b/website/docs/cli/commands/push.html.md similarity index 61% rename from website/docs/cli/commands/push.mdx rename to website/docs/cli/commands/push.html.md index 7eb66776e..bc093a85c 100644 --- a/website/docs/cli/commands/push.mdx +++ b/website/docs/cli/commands/push.html.md @@ -1,14 +1,16 @@ --- -page_title: 'Command: push' -description: >- - DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced - the old `terraform push` command. +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. --- # Command: push -!> **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. +!> **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. The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise. The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional. + diff --git a/website/docs/cli/commands/refresh.mdx b/website/docs/cli/commands/refresh.html.md similarity index 88% rename from website/docs/cli/commands/refresh.mdx rename to website/docs/cli/commands/refresh.html.md index f882e567d..55a007f38 100644 --- a/website/docs/cli/commands/refresh.mdx +++ b/website/docs/cli/commands/refresh.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Command: refresh' +layout: "docs" +page_title: "Command: refresh" +sidebar_current: "docs-commands-refresh" description: |- The `terraform refresh` command reads the current settings from all managed remote objects and updates the Terraform state to match. @@ -12,19 +14,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](/language/state/). +[Terraform state](/docs/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`](/cli/commands/plan) +[`terraform plan`](./plan.html) and -[`terraform apply`](/cli/commands/apply) +[`terraform apply`](./apply.html) 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. @@ -40,7 +42,7 @@ terraform apply -refresh-only -auto-approve ``` Consequently, it supports all of the same options as -[`terraform apply`](/cli/commands/apply) except that it does not accept a saved +[`terraform apply`](./apply.html) 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.mdx b/website/docs/cli/commands/show.html.md similarity index 81% rename from website/docs/cli/commands/show.mdx rename to website/docs/cli/commands/show.html.md index f956db19b..45bc6fa3f 100644 --- a/website/docs/cli/commands/show.mdx +++ b/website/docs/cli/commands/show.html.md @@ -1,10 +1,9 @@ --- -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. +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. --- # Command: show @@ -19,7 +18,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](/language/state/sensitive-data). +[Sensitive Data in State](/docs/language/state/sensitive-data.html). ## JSON Output @@ -35,7 +34,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](/internals/json-format). +The output format is covered in detail in [JSON Output Format](/docs/internals/json-format.html). ## Usage diff --git a/website/docs/cli/commands/state/index.mdx b/website/docs/cli/commands/state/index.html.md similarity index 82% rename from website/docs/cli/commands/state/index.mdx rename to website/docs/cli/commands/state/index.html.md index a39344b59..38e2028d9 100644 --- a/website/docs/cli/commands/state/index.mdx +++ b/website/docs/cli/commands/state/index.html.md @@ -1,13 +1,16 @@ --- -page_title: 'Command: state' -description: The `terraform state` command is used for advanced state management. +layout: "docs" +page_title: "Command: state" +sidebar_current: "docs-commands-state-index" +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](/language/state/). +you may need to modify the [Terraform state](/docs/language/state/index.html). Rather than modify the state directly, the `terraform state` commands can be used in many cases instead. @@ -32,7 +35,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](/cli/commands/state/list)) +Subcommands that are read-only (such as [list](/docs/cli/commands/state/list.html)) 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.mdx b/website/docs/cli/commands/state/list.html.md similarity index 84% rename from website/docs/cli/commands/state/list.mdx rename to website/docs/cli/commands/state/list.html.md index 38f48bbe6..a7b78c94b 100644 --- a/website/docs/cli/commands/state/list.mdx +++ b/website/docs/cli/commands/state/list.html.md @@ -1,14 +1,15 @@ --- -page_title: 'Command: state list' -description: >- - The terraform state list command is used to list resources within a Terraform - state. +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. --- # Command: state list The `terraform state list` command is used to list resources within a -[Terraform state](/language/state/). +[Terraform state](/docs/language/state/index.html). ## Usage @@ -24,12 +25,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](/cli/state/resource-addressing). +in [resource addressing format](/docs/cli/state/resource-addressing.html). 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](/language/state/remote) is used. + Ignored when [remote state](/docs/language/state/remote.html) is used. * `-id=id` - ID of resources to show. Ignored when unset. ## Example: All Resources diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.html.md similarity index 81% rename from website/docs/cli/commands/state/mv.mdx rename to website/docs/cli/commands/state/mv.html.md index 17ee50370..2cf2f8cd6 100644 --- a/website/docs/cli/commands/state/mv.mdx +++ b/website/docs/cli/commands/state/mv.html.md @@ -1,13 +1,14 @@ --- -page_title: 'Command: state mv' -description: >- - The `terraform state mv` command changes bindings in Terraform state, - associating existing remote objects with new resource instances. +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. --- # Command: state mv -The main function of [Terraform state](/language/state/) is +The main function of [Terraform state](/docs/language/state/index.html) 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 @@ -28,7 +29,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](/cli/state/resource-addressing), and +[resource address syntax](/docs/cli/state/resource-addressing.html), 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 @@ -44,7 +45,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 @@ -58,8 +59,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 @@ -67,22 +68,23 @@ This command also accepts the following options: unit letter, such as "3s" for three seconds. For configurations using -[the `remote` backend](/language/settings/backends/remote) +[the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform state mv` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). -The legacy options [`-backup` and `-backup-out`](/language/settings/backends/local#command-line-arguments) +The legacy options [`-backup` and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments) operate on a local state file only. Configurations using -[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) +[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) options. + For configurations using -[the `local` state mv](/language/settings/backends/local) only, +[the `local` state mv](/docs/language/settings/backends/local.html) only, `terraform state mv` also accepts the legacy options -[`-state`, `-state-out`, `-backup`, and `-backup-out`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, `-backup`, and `-backup-out`](/docs/language/settings/backends/local.html#command-line-arguments). ## Example: Rename a Resource @@ -134,7 +136,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](/language/meta-arguments/count) +A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html) 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: @@ -159,7 +161,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](/language/meta-arguments/for_each) +A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html) 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.mdx b/website/docs/cli/commands/state/pull.html.md similarity index 77% rename from website/docs/cli/commands/state/pull.mdx rename to website/docs/cli/commands/state/pull.html.md index 5fc5a7ba3..ad52c96b6 100644 --- a/website/docs/cli/commands/state/pull.mdx +++ b/website/docs/cli/commands/state/pull.html.md @@ -1,14 +1,15 @@ --- -page_title: 'Command: state pull' -description: >- - The `terraform state pull` command is used to manually download and output the - state from remote state. +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. --- # Command: state pull The `terraform state pull` command is used to manually download and output -the state from [remote state](/language/state/remote). This command also +the state from [remote state](/docs/language/state/remote.html). 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 new file mode 100644 index 000000000..2ba8f21da --- /dev/null +++ b/website/docs/cli/commands/state/push.html.md @@ -0,0 +1,50 @@ +--- +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 deleted file mode 100644 index ea3d9898a..000000000 --- a/website/docs/cli/commands/state/push.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -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.mdx b/website/docs/cli/commands/state/replace-provider.html.md similarity index 65% rename from website/docs/cli/commands/state/replace-provider.mdx rename to website/docs/cli/commands/state/replace-provider.html.md index 6bbd7195e..21befd99e 100644 --- a/website/docs/cli/commands/state/replace-provider.mdx +++ b/website/docs/cli/commands/state/replace-provider.html.md @@ -1,14 +1,15 @@ --- -page_title: 'Command: state replace-provider' -description: >- - The `terraform state replace-provider` command replaces the provider for - resources in the Terraform state. +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. --- # Command: state replace-provider The `terraform state replace-provider` command is used to replace the provider -for resources in a [Terraform state](/language/state/). +for resources in a [Terraform state](/docs/language/state/index.html). ## Usage @@ -27,21 +28,22 @@ 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](/language/settings/backends/remote) +[the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform state replace-provider` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). For configurations using -[the `local` state rm](/language/settings/backends/local) only, +[the `local` state rm](/docs/language/settings/backends/local.html) only, `terraform state replace-provider` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). + ## Example diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.html.md similarity index 80% rename from website/docs/cli/commands/state/rm.mdx rename to website/docs/cli/commands/state/rm.html.md index 635a363a9..131c31a81 100644 --- a/website/docs/cli/commands/state/rm.mdx +++ b/website/docs/cli/commands/state/rm.html.md @@ -1,13 +1,14 @@ --- -page_title: 'Command: state rm' -description: >- - The `terraform state rm` command removes bindings from the Terraform state, - causing Terraform to "forget about" existing objects. +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. --- # Command: state rm -The main function of [Terraform state](/language/state/) is +The main function of [Terraform state](/docs/language/state/index.html) 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 @@ -23,13 +24,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](/cli/state/resource-addressing), and remove +[resource address](/docs/cli/state/resource-addressing.html), 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`](/cli/commands/plan) +[`terraform plan`](../plan.html) 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 @@ -41,8 +42,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 @@ -50,15 +51,15 @@ This command also accepts the following options: unit letter, such as "3s" for three seconds. For configurations using -[the `remote` backend](/language/settings/backends/remote) +[the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform state rm` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). For configurations using -[the `local` state rm](/language/settings/backends/local) only, +[the `local` state rm](/docs/language/settings/backends/local.html) only, `terraform state rm` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). ## Example: Remove all Instances of a Resource @@ -93,7 +94,7 @@ $ terraform state rm 'module.foo' ## Example: Remove a Particular Instance of a Resource using `count` -A resource defined with [the `count` meta-argument](/language/meta-arguments/count) +A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html) 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: @@ -108,7 +109,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](/language/meta-arguments/for_each) +A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html) 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.mdx b/website/docs/cli/commands/state/show.html.md similarity index 78% rename from website/docs/cli/commands/state/show.mdx rename to website/docs/cli/commands/state/show.html.md index a973b88c5..2c665ba64 100644 --- a/website/docs/cli/commands/state/show.mdx +++ b/website/docs/cli/commands/state/show.html.md @@ -1,15 +1,16 @@ --- -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. +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. --- # Command: state show The `terraform state show` command is used to show the attributes of a single resource in the -[Terraform state](/language/state/). +[Terraform state](/docs/language/state/index.html). ## Usage @@ -20,16 +21,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](/cli/state/resource-addressing). +in [resource addressing format](/docs/cli/state/resource-addressing.html). 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](/language/state/remote) is used. + Ignored when [remote state](/docs/language/state/remote.html) 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`](/cli/commands/show#json-output) and decode the result +[`terraform show -json`](/docs/cli/commands/show.html#json-output) and decode the result using the documented structure. ## Example: Show a Resource @@ -60,7 +61,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`](/language/meta-arguments/count): +[`count`](/docs/language/meta-arguments/count.html): ```shell $ terraform state show 'packet_device.worker[0]' @@ -69,7 +70,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`](/language/meta-arguments/for_each): +[`for_each`](/docs/language/meta-arguments/for_each.html): Linux, Mac OS, and UNIX: diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.html.md similarity index 73% rename from website/docs/cli/commands/taint.mdx rename to website/docs/cli/commands/taint.html.md index f0fcf1b1a..aeffa1d7b 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Command: taint' +layout: "docs" +page_title: "Command: taint" +sidebar_current: "docs-commands-taint" description: |- The `terraform taint` command informs Terraform that a particular object is damaged or degraded. @@ -12,12 +14,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`](/cli/commands/apply). +to use the `-replace` option with [`terraform apply`](./apply.html). For example: ``` @@ -42,13 +44,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](/cli/state/resource-addressing) syntax, +[the resource address syntax](/docs/cli/state/resource-addressing.html) 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: @@ -66,12 +68,12 @@ This command accepts the following options: unit letter, such as "3s" for three seconds. For configurations using -[the `remote` backend](/language/settings/backends/remote) +[the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform taint` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). For configurations using -[the `local` backend](/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local.html) only, `terraform taint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). diff --git a/website/docs/cli/commands/test.mdx b/website/docs/cli/commands/test.html.md similarity index 52% rename from website/docs/cli/commands/test.mdx rename to website/docs/cli/commands/test.html.md index 282c21710..7edd1fb1b 100644 --- a/website/docs/cli/commands/test.mdx +++ b/website/docs/cli/commands/test.html.md @@ -1,12 +1,15 @@ --- -page_title: 'Command: test' -description: Part of the ongoing design research for module integration testing. +layout: "docs" +page_title: "Command: test" +sidebar_current: "docs-commands-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](/language/modules/testing-experiment). +[the module integration testing experiment](/docs/language/modules/testing-experiment.html). 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.mdx b/website/docs/cli/commands/untaint.html.md similarity index 78% rename from website/docs/cli/commands/untaint.mdx rename to website/docs/cli/commands/untaint.html.md index 85e210a6a..12793958b 100644 --- a/website/docs/cli/commands/untaint.mdx +++ b/website/docs/cli/commands/untaint.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Command: untaint' +layout: "docs" +page_title: "Command: untaint" +sidebar_current: "docs-commands-untaint" description: |- The `terraform untaint` command tells Terraform that an object is functioning correctly, even though its creation failed or it was previously manually @@ -16,7 +18,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`](/cli/commands/taint), although we no longer recommend that +[`terraform taint`](./taint.html), although we no longer recommend that workflow. If Terraform currently considers a particular object as tainted but you've @@ -38,7 +40,7 @@ terraform apply -replace="aws_instance.example[0]" Usage: `terraform untaint [options] address` -The `address` argument is a [resource address](/cli/state/resource-addressing) +The `address` argument is a [resource address](/docs/cli/state/resource-addressing.html) identifying a particular resource instance which is currently tainted. This command also accepts the following options: @@ -49,8 +51,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 @@ -62,12 +64,12 @@ This command also accepts the following options: rendered by a system that cannot interpret terminal formatting. For configurations using -[the `remote` backend](/language/settings/backends/remote) +[the `remote` backend](/docs/language/settings/backends/remote.html) only, `terraform untaint` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments). For configurations using -[the `local` backend](/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local.html) only, `terraform untaint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments). diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.html.md similarity index 56% rename from website/docs/cli/commands/validate.mdx rename to website/docs/cli/commands/validate.html.md index fbbb03971..e81da01b2 100644 --- a/website/docs/cli/commands/validate.mdx +++ b/website/docs/cli/commands/validate.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Command: validate' -description: >- - The `terraform validate` command is used to validate the syntax of the - terraform files. +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. --- # Command: validate @@ -38,11 +39,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 @@ -59,15 +60,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](/language/v1-compatibility-promises). +[the Terraform 1.0 Compatibility Promises](https://www.terraform.io/docs/language/v1-compatibility-promises.html). 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: @@ -94,93 +95,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.mdx b/website/docs/cli/commands/version.html.md similarity index 75% rename from website/docs/cli/commands/version.mdx rename to website/docs/cli/commands/version.html.md index 44b1db006..917983801 100644 --- a/website/docs/cli/commands/version.mdx +++ b/website/docs/cli/commands/version.html.md @@ -1,8 +1,8 @@ --- -page_title: 'Command: version' -description: >- - The terraform version command displays the Terraform version and the version - of all installed plugins. +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." --- # 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](/cli/commands/#upgrade-and-security-bulletin-checks). +and security checks [unless disabled](/docs/cli/commands/index.html#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.mdx b/website/docs/cli/commands/workspace/delete.html.md similarity index 81% rename from website/docs/cli/commands/workspace/delete.mdx rename to website/docs/cli/commands/workspace/delete.html.md index cadfa6459..3fd077631 100644 --- a/website/docs/cli/commands/workspace/delete.mdx +++ b/website/docs/cli/commands/workspace/delete.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Command: workspace delete' -description: The terraform workspace delete command is used to delete a workspace. +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. --- # Command: workspace delete @@ -28,8 +31,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.mdx b/website/docs/cli/commands/workspace/index.html.md similarity index 60% rename from website/docs/cli/commands/workspace/index.mdx rename to website/docs/cli/commands/workspace/index.html.md index 2d67b1d7c..6237a4133 100644 --- a/website/docs/cli/commands/workspace/index.mdx +++ b/website/docs/cli/commands/workspace/index.html.md @@ -1,12 +1,15 @@ --- -page_title: 'Command: workspace' -description: The workspace command helps you manage workspaces. +layout: "docs" +page_title: "Command: workspace" +sidebar_current: "docs-commands-workspace-index" +description: "The workspace command helps you manage workspaces." + --- # Command: workspace The `terraform workspace` command is used to manage -[workspaces](/language/state/workspaces). +[workspaces](/docs/language/state/workspaces.html). 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.mdx b/website/docs/cli/commands/workspace/list.html.md similarity index 64% rename from website/docs/cli/commands/workspace/list.mdx rename to website/docs/cli/commands/workspace/list.html.md index d7d2e6eee..2114a60c6 100644 --- a/website/docs/cli/commands/workspace/list.mdx +++ b/website/docs/cli/commands/workspace/list.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Command: workspace list' -description: The terraform workspace list command is used to list all existing workspaces. +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. --- # Command: workspace list diff --git a/website/docs/cli/commands/workspace/new.mdx b/website/docs/cli/commands/workspace/new.html.md similarity index 83% rename from website/docs/cli/commands/workspace/new.mdx rename to website/docs/cli/commands/workspace/new.html.md index 28b4d1c30..ef2e73ecf 100644 --- a/website/docs/cli/commands/workspace/new.mdx +++ b/website/docs/cli/commands/workspace/new.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Command: workspace new' -description: The terraform workspace new command is used to create a new workspace. +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. --- # Command: workspace new @@ -20,8 +23,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.mdx b/website/docs/cli/commands/workspace/select.html.md similarity index 69% rename from website/docs/cli/commands/workspace/select.mdx rename to website/docs/cli/commands/workspace/select.html.md index f22f7aabe..08170a61e 100644 --- a/website/docs/cli/commands/workspace/select.mdx +++ b/website/docs/cli/commands/workspace/select.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Command: workspace select' -description: The terraform workspace select command is used to choose a workspace. +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. --- # Command: workspace select diff --git a/website/docs/cli/commands/workspace/show.mdx b/website/docs/cli/commands/workspace/show.html.md similarity index 57% rename from website/docs/cli/commands/workspace/show.mdx rename to website/docs/cli/commands/workspace/show.html.md index c6063f22f..7cd7d5b5d 100644 --- a/website/docs/cli/commands/workspace/show.mdx +++ b/website/docs/cli/commands/workspace/show.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Command: workspace show' -description: The terraform workspace show command is used to output the current workspace. +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. --- # Command: workspace show diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.html.md similarity index 86% rename from website/docs/cli/config/config-file.mdx rename to website/docs/cli/config/config-file.html.md index 105f503e7..1aa83c40e 100644 --- a/website/docs/cli/config/config-file.mdx +++ b/website/docs/cli/config/config-file.html.md @@ -1,15 +1,15 @@ --- -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. +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." --- # 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](/language/). +[your infrastructure configuration](/docs/language/index.html). ## 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](/cli/config/environment-variables). +using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/cli/config/environment-variables.html). 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](/cli/commands/#upgrade-and-security-bulletin-checks) +- `disable_checkpoint` — when set to `true`, disables + [upgrade and security bulletin checks](/docs/cli/commands/index.html#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](/cloud-docs/) provides a number of remote network +[Terraform Cloud](/docs/cloud/index.html) provides a number of remote network services for use with Terraform, and -[Terraform Enterprise](/enterprise/) allows hosting those +[Terraform Enterprise](/docs/enterprise/index.html) allows hosting those services inside your own infrastructure. For example, these systems offer both -[remote operations](/cloud-docs/run/cli) and a -[private module registry](/cloud-docs/registry/). +[remote operations](/docs/cloud/run/cli.html) and a +[private module registry](/docs/cloud/registry/index.html). 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](/cli/commands/login) +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) 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](/cloud-docs/users-teams-organizations/users#api-tokens) +[user token](/docs/cloud/users-teams-organizations/users.html#api-tokens) or a -[team token](/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens); +[team token](/docs/cloud/users-teams-organizations/api-tokens.html#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](/internals/credentials-helpers). +[the guide to Credentials Helper internals](/docs/internals/credentials-helpers.html). ## 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](/internals/provider-network-mirror-protocol), - 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](/docs/internals/provider-network-mirror-protocol.html), + 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](/language/dependency-lock) +[the dependency lock file](/docs/language/dependency-lock.html) 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.mdx b/website/docs/cli/config/environment-variables.html.md similarity index 88% rename from website/docs/cli/config/environment-variables.mdx rename to website/docs/cli/config/environment-variables.html.md index ffe749ec6..55997e97e 100644 --- a/website/docs/cli/config/environment-variables.mdx +++ b/website/docs/cli/config/environment-variables.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # 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](/internals/debugging). +For more on debugging Terraform, check out the section on [Debugging](/docs/internals/debugging.html). ## 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](/internals/debugging). +For more on debugging Terraform, check out the section on [Debugging](/docs/internals/debugging.html). ## TF_INPUT @@ -58,10 +58,9 @@ 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](/language/values/variables). +For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/docs/language/values/variables.html). ## TF_CLI_ARGS and TF_CLI_ARGS_name - The value of `TF_CLI_ARGS` will specify additional arguments to the @@ -114,7 +113,8 @@ 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](/language/state/workspaces). +For more information regarding workspaces, check out the section on [Using Workspaces] +(https://www.terraform.io/docs/language/state/workspaces.html). ## 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](/cli/config/config-file). +The location of the [Terraform CLI configuration file](/docs/cli/config/config-file.html). ```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](/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore). +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). diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.html.md similarity index 68% rename from website/docs/cli/config/index.mdx rename to website/docs/cli/config/index.html.md index 8261c614f..afe00e8f2 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.html.md @@ -1,9 +1,7 @@ --- -page_title: CLI Configuration - Terraform CLI -description: >- - Find documentation about the CLI config file and customizing Terraform - environment variables. -sidebar_title: CLI Configuration +layout: "docs" +page_title: "CLI Configuration - Terraform CLI" +description: "Find documentation about the CLI config file and customizing Terraform environment variables." --- # CLI Configuration @@ -17,9 +15,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](/cli/config/config-file) configures provider +- The [CLI config file](/docs/cli/config/config-file.html) configures provider installation and security features. -- Several [environment variables](/cli/config/environment-variables) can +- Several [environment variables](/docs/cli/config/environment-variables.html) 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.mdx b/website/docs/cli/import/importability.html.md similarity index 82% rename from website/docs/cli/import/importability.mdx rename to website/docs/cli/import/importability.html.md index 88a200a4e..79d78d90a 100644 --- a/website/docs/cli/import/importability.mdx +++ b/website/docs/cli/import/importability.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Import: Resource Importability' +layout: "docs" +page_title: "Import: Resource Importability" +sidebar_current: "docs-import-importability" description: |- Each resource in Terraform must implement some basic logic to become importable. As a result, not all Terraform resources are currently importable. @@ -19,4 +21,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](/plugin/sdkv2/resources/import). +[Extending Terraform: Resources — Import](/docs/extend/resources/import.html). diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.html.md similarity index 81% rename from website/docs/cli/import/index.mdx rename to website/docs/cli/import/index.html.md index c1e3b33ad..b06c668fc 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.html.md @@ -1,8 +1,8 @@ --- -page_title: Import -description: >- - Terraform can import and manage existing infrastructure. This can help you - transition your infrastructure to Terraform. +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." --- # 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](/language/state/). +[the State section](/docs/language/state/index.html). ## Currently State Only The current implementation of Terraform import can only import resources -into the [state](/language/state/). It does not generate configuration. A future +into the [state](/docs/language/state/index.html). 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](/language/settings/backends/remote), such as Terraform Cloud, the import +backend](/docs/language/settings/backends/remote.html), 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.mdx b/website/docs/cli/import/usage.html.md similarity index 90% rename from website/docs/cli/import/usage.mdx rename to website/docs/cli/import/usage.html.md index b631dfd8e..4fdc5452d 100644 --- a/website/docs/cli/import/usage.mdx +++ b/website/docs/cli/import/usage.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Import: Usage' -description: The `terraform import` command is used to import existing infrastructure. +layout: "docs" +page_title: "Import: Usage" +sidebar_current: "docs-import-usage" +description: |- + The `terraform import` command is used to import existing infrastructure. --- # Import Usage @@ -20,7 +23,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](/language/state/). +[the State section](/docs/language/state/index.html). 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: @@ -54,7 +57,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_](/cli/state/resource-addressing) for more +[_Resource Addressing_](/docs/cli/state/resource-addressing.html) for more details on how to specify a target resource. The syntax of the given ID is dependent on the resource type being imported. @@ -80,4 +83,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](/cli/commands/state/) can be used. +[state management commands](/docs/cli/commands/state/index.html) can be used. diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.html.md similarity index 67% rename from website/docs/cli/index.mdx rename to website/docs/cli/index.html.md index e4638311a..f52fb1bc5 100644 --- a/website/docs/cli/index.mdx +++ b/website/docs/cli/index.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # 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](/language/). +[Terraform Language Documentation](/docs/language/index.html). diff --git a/website/docs/cli/init/index.mdx b/website/docs/cli/init/index.html.md similarity index 85% rename from website/docs/cli/init/index.mdx rename to website/docs/cli/init/index.html.md index 58c8837d6..1fc581e3f 100644 --- a/website/docs/cli/init/index.mdx +++ b/website/docs/cli/init/index.html.md @@ -1,17 +1,14 @@ --- -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. -sidebar_title: Initializing Working Directories +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." --- # Initializing Working Directories Terraform expects to be invoked from a working directory that contains configuration files written in -[the Terraform language](/language/). Terraform uses +[the Terraform language](/docs/language/index.html). Terraform uses configuration content from this directory, and also uses the directory to store settings, cached plugins and modules, and sometimes state data. @@ -26,7 +23,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](/cli/workspaces/) is currently active, and + [workspace](/docs/cli/workspaces/index.html) 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. @@ -51,7 +48,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](/cli/commands/init). +For details, see [the `terraform init` command](/docs/cli/commands/init.html). ## Reinitialization diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.html.md similarity index 63% rename from website/docs/cli/inspect/index.mdx rename to website/docs/cli/inspect/index.html.md index 2dd1c5fd7..3fac82ed5 100644 --- a/website/docs/cli/inspect/index.mdx +++ b/website/docs/cli/inspect/index.html.md @@ -1,9 +1,7 @@ --- -page_title: Inspecting Infrastructure - Terraform CLI -description: >- - Learn commands to inspect dependency information, outputs, etc. Use them for - integration or to understand your infrastructure. -sidebar_title: Inspecting Infrastructure +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." --- # Inspecting Infrastructure @@ -18,19 +16,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](/cli/commands/graph) creates a visual +- [The `terraform graph` command](/docs/cli/commands/graph.html) creates a visual representation of a configuration or a set of planned changes. -- [The `terraform output` command](/cli/commands/output) can get the - values for the top-level [output values](/language/values/outputs) of +- [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 a configuration, which are often helpful when making use of the infrastructure Terraform has provisioned. -- [The `terraform show` command](/cli/commands/show) can generate +- [The `terraform show` command](/docs/cli/commands/show.html) 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](/cli/commands/state/list) can list +- [The `terraform state list` command](/docs/cli/commands/state/list.html) can list the resources being managed by the current working directory and workspace, providing a complete or filtered list. -- [The `terraform state show` command](/cli/commands/state/show) can print +- [The `terraform state show` command](/docs/cli/commands/state/show.html) 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.mdx b/website/docs/cli/install/apt.html.md similarity index 94% rename from website/docs/cli/install/apt.mdx rename to website/docs/cli/install/apt.html.md index c662fa9dc..5b88b9613 100644 --- a/website/docs/cli/install/apt.mdx +++ b/website/docs/cli/install/apt.html.md @@ -1,8 +1,9 @@ --- -page_title: APT Packages for Debian and Ubuntu -description: >- - The HashiCorp APT repositories contain distribution-specific Terraform - packages for both Debian and Ubuntu systems. +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. --- # APT Packages for Debian and Ubuntu @@ -15,7 +16,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](/cli/install/yum). +might prefer to [install Terraform from our Yum repositories](yum.html). -> **Note:** The APT repositories discussed on this page are generic HashiCorp repositories that contain packages for a variety of different HashiCorp @@ -66,7 +67,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) instead. +[download a normal release `.zip` file](/downloads.html) instead. ## Supported Debian and Ubuntu Releases diff --git a/website/docs/cli/install/yum.mdx b/website/docs/cli/install/yum.html.md similarity index 91% rename from website/docs/cli/install/yum.mdx rename to website/docs/cli/install/yum.html.md index accc2d3f3..45e88e0eb 100644 --- a/website/docs/cli/install/yum.mdx +++ b/website/docs/cli/install/yum.html.md @@ -1,8 +1,9 @@ --- -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. +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. --- # Yum/DNF Packages for RHEL, CentOS, and Fedora @@ -15,7 +16,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](/cli/install/apt). +might prefer to [install Terraform from our APT repositories](apt.html). -> **Note:** The Yum repositories discussed on this page are generic HashiCorp repositories that contain packages for a variety of different HashiCorp @@ -63,7 +64,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) instead. +[download a normal release `.zip` file](/downloads.html) instead. ## Supported Distribution Releases diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.html.md similarity index 65% rename from website/docs/cli/plugins/index.mdx rename to website/docs/cli/plugins/index.html.md index 7b12e945a..95edb225e 100644 --- a/website/docs/cli/plugins/index.mdx +++ b/website/docs/cli/plugins/index.html.md @@ -1,16 +1,14 @@ --- -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. -sidebar_title: Managing Plugins +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." --- # Managing Plugins Terraform relies on plugins called "providers" in order to manage various types of resources. (For more information about providers, see -[Providers](/language/providers/) in the Terraform +[Providers](/docs/language/providers/index.html) in the Terraform language docs.) -> **Note:** Providers are currently the only plugin type most Terraform users @@ -18,8 +16,8 @@ will interact with. Terraform also supports third-party provisioner plugins, but we discourage their use. Terraform downloads and/or installs any providers -[required](/language/providers/requirements) by a configuration -when [initializing](/cli/init/) a working directory. By default, +[required](/docs/language/providers/requirements.html) by a configuration +when [initializing](/docs/cli/init/index.html) a working directory. By default, this works without any additional interaction but requires network access to download providers from their source registry. @@ -33,29 +31,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](/cli/config/config-file). +more information, see [CLI Config File](/docs/cli/config/config-file.html). ## Getting Plugin Information -Use the [`terraform providers`](/cli/commands/providers) command to get information +Use the [`terraform providers`](/docs/cli/commands/providers.html) command to get information about the providers required by the current working directory's configuration. -Use the [`terraform version`](/cli/commands/version) command (or +Use the [`terraform version`](/docs/cli/commands/version.html) command (or `terraform -version`) to show the specific provider versions installed for the current working directory. -Use the [`terraform providers schema`](/cli/commands/providers/schema) command to +Use the [`terraform providers schema`](/docs/cli/commands/providers/schema.html) command to get machine-readable information about the resources and configuration options offered by each provider. ## Managing Plugin Installation -Use the [`terraform providers mirror`](/cli/commands/providers/mirror) command to +Use the [`terraform providers mirror`](/docs/cli/commands/providers/mirror.html) 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`](/cli/commands/providers/lock) command +Use the [`terraform providers lock`](/docs/cli/commands/providers/lock.html) 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.mdx b/website/docs/cli/plugins/signing.html.md similarity index 70% rename from website/docs/cli/plugins/signing.mdx rename to website/docs/cli/plugins/signing.html.md index cdcd546d6..9c82157d3 100644 --- a/website/docs/cli/plugins/signing.mdx +++ b/website/docs/cli/plugins/signing.html.md @@ -1,8 +1,7 @@ --- -page_title: Plugin Signing -description: >- - Learn about the types of signatures providers can have on the Terraform - Registry. +layout: "docs" +page_title: "Plugin Signing" +description: "Learn about the types of signatures providers can have on the Terraform Registry." --- @@ -15,11 +14,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.mdx b/website/docs/cli/run/index.html.md similarity index 82% rename from website/docs/cli/run/index.mdx rename to website/docs/cli/run/index.html.md index a3f887279..0d0770a34 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.html.md @@ -1,14 +1,14 @@ --- -page_title: Provisioning Infrastructure - Terraform CLI -description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.' -sidebar_title: Provisioning Infrastructure +layout: "docs" +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](/language/). +[Terraform configuration](/docs/language/index.html). When people refer to "running Terraform," they generally mean performing these provisioning actions in order to affect real infrastructure objects. The @@ -17,8 +17,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](/cli/init/) working directory, and all of them act -only upon the currently selected [workspace](/cli/workspaces/). +[initialized](/docs/cli/init/index.html) working directory, and all of them act +only upon the currently selected [workspace](/docs/cli/workspaces/index.html). ## Planning @@ -39,7 +39,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](/cli/commands/plan). +For details, see [the `terraform plan` command](/docs/cli/commands/plan.html). ## Applying @@ -55,7 +55,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](/cli/commands/apply). +For details, see [the `terraform apply` command](/docs/cli/commands/apply.html). ## Destroying @@ -69,4 +69,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](/cli/commands/destroy). +For details, see [the `terraform destroy` command](/docs/cli/commands/destroy.html). diff --git a/website/docs/cli/state/index.mdx b/website/docs/cli/state/index.html.md similarity index 66% rename from website/docs/cli/state/index.mdx rename to website/docs/cli/state/index.html.md index 803e15a03..7f12fea4f 100644 --- a/website/docs/cli/state/index.mdx +++ b/website/docs/cli/state/index.html.md @@ -1,16 +1,14 @@ --- -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. -sidebar_title: Manipulating State +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." --- # 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](/language/state/) to remember which +Terraform uses [state data](/docs/language/state/index.html) 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. @@ -22,12 +20,12 @@ infrastructure. Terraform CLI supports several workflows for interacting with state: -- [Inspecting State](/cli/state/inspect) -- [Forcing Re-creation (Tainting)](/cli/state/taint) -- [Moving Resources](/cli/state/move) +- [Inspecting State](/docs/cli/state/inspect.html) +- [Forcing Re-creation (Tainting)](/docs/cli/state/taint.html) +- [Moving Resources](/docs/cli/state/move.html) - Importing Pre-existing Resources (documented in the - [Importing Infrastructure](/cli/import/) section) -- [Disaster Recovery](/cli/state/recover) + [Importing Infrastructure](/docs/cli/import/index.html) section) +- [Disaster Recovery](/docs/cli/state/recover.html) ~> **Important:** Modifying state data outside a normal plan or apply can cause Terraform to lose track of managed resources, which might waste money, annoy diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.html.md similarity index 58% rename from website/docs/cli/state/inspect.mdx rename to website/docs/cli/state/inspect.html.md index 12439d822..382cd37a2 100644 --- a/website/docs/cli/state/inspect.mdx +++ b/website/docs/cli/state/inspect.html.md @@ -1,7 +1,7 @@ --- -page_title: Inspecting State - Terraform CLI -description: Commands that allow you to read and update state. -sidebar_title: Inspecting State +layout: "docs" +page_title: "Inspecting State - Terraform CLI" +description: "Commands that allow you to read and update state." --- # Inspecting State @@ -9,14 +9,14 @@ sidebar_title: Inspecting State Terraform includes some commands for reading and updating state without taking any other actions. -- [The `terraform state list` command](/cli/commands/state/list) +- [The `terraform state list` command](/docs/cli/commands/state/list.html) shows the resource addresses for every resource Terraform knows about in a configuration, optionally filtered by partial resource address. -- [The `terraform state show` command](/cli/commands/state/show) +- [The `terraform state show` command](/docs/cli/commands/state/show.html) displays detailed state data about one resource. -- [The `terraform refresh` command](/cli/commands/refresh) updates +- [The `terraform refresh` command](/docs/cli/commands/refresh.html) 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.mdx b/website/docs/cli/state/move.html.md similarity index 69% rename from website/docs/cli/state/move.mdx rename to website/docs/cli/state/move.html.md index f39a192c3..4eb654fd3 100644 --- a/website/docs/cli/state/move.mdx +++ b/website/docs/cli/state/move.html.md @@ -1,15 +1,13 @@ --- -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. -sidebar_title: Moving Resources +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." --- # Moving Resources Terraform's state associates each real-world object with a configured resource -at a specific [resource address](/cli/state/resource-addressing). This +at a specific [resource address](/docs/cli/state/resource-addressing.html). 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. @@ -22,17 +20,17 @@ 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](/cli/commands/state/mv) changes +- [The `terraform state mv` command](/docs/cli/commands/state/mv.html) 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. -- [The `terraform state rm` command](/cli/commands/state/rm) tells +- [The `terraform state rm` command](/docs/cli/commands/state/rm.html) 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](/cli/commands/state/replace-provider) +- [The `terraform state replace-provider` command](/docs/cli/commands/state/replace-provider.html) transfers existing resources to a new provider without requiring them to be re-created. diff --git a/website/docs/cli/state/recover.mdx b/website/docs/cli/state/recover.html.md similarity index 65% rename from website/docs/cli/state/recover.mdx rename to website/docs/cli/state/recover.html.md index dc2b0cb29..29e289c42 100644 --- a/website/docs/cli/state/recover.mdx +++ b/website/docs/cli/state/recover.html.md @@ -1,9 +1,7 @@ --- -page_title: Recovering from State Disasters - Terraform CLI -descriptin: >- - Commands that allow you to restore state backups and override Terraform state - protections. -sidebar_title: Recovering from State Disasters +layout: "docs" +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 @@ -12,7 +10,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](/cli/commands/force-unlock) can +- [The `terraform force-unlock` command](/docs/cli/commands/force-unlock.html) 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 @@ -20,7 +18,8 @@ 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](/cli/commands/state/pull) and - [the `terraform state push` command](/cli/commands/state/push) can +- [The `terraform state pull` command](/docs/cli/commands/state/pull.html) and + [the `terraform state push` command](/docs/cli/commands/state/push.html) 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.mdx b/website/docs/cli/state/resource-addressing.html.md similarity index 69% rename from website/docs/cli/state/resource-addressing.mdx rename to website/docs/cli/state/resource-addressing.html.md index 07f3039c0..72b987a83 100644 --- a/website/docs/cli/state/resource-addressing.mdx +++ b/website/docs/cli/state/resource-addressing.html.md @@ -1,5 +1,7 @@ --- -page_title: 'Internals: Resource Address' +layout: "docs" +page_title: "Internals: Resource Address" +sidebar_current: "docs-internals-resource-addressing" description: |- A resource address is a string that identifies zero or more resource instances in your overall configuration. @@ -30,12 +32,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. @@ -62,11 +64,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 @@ -77,12 +79,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.mdx b/website/docs/cli/state/taint.html.md similarity index 68% rename from website/docs/cli/state/taint.mdx rename to website/docs/cli/state/taint.html.md index 9d145205e..cea128144 100644 --- a/website/docs/cli/state/taint.mdx +++ b/website/docs/cli/state/taint.html.md @@ -1,7 +1,7 @@ --- -page_title: Forcing Re-creation of Resources (Tainting) - Terraform CLI -description: Commands that allow you to destroy and re-create resources manually. -sidebar_title: Forcing Re-creation of Resources (Tainting) +layout: "docs" +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 +17,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](/cli/commands/taint) tells Terraform to +- [The `terraform taint` command](/docs/cli/commands/taint.html) 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](/cli/commands/untaint) undoes a +- [The `terraform untaint` command](/docs/cli/commands/untaint.html) undoes a previous taint, or can preserve a resource that was automatically tainted due - to failed [provisioners](/language/resources/provisioners/syntax). + to failed [provisioners](/docs/language/resources/provisioners/syntax.html). diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.html.md similarity index 68% rename from website/docs/cli/workspaces/index.mdx rename to website/docs/cli/workspaces/index.html.md index c20eb40d0..e8a5dcb5e 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.html.md @@ -1,30 +1,28 @@ --- -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. -sidebar_title: Managing Workspaces +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." --- # Managing Workspaces In Terraform CLI, _workspaces_ are separate instances of -[state data](/language/state/) that can be used from the same working +[state data](/docs/language/state/index.html) 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](/cli/init/) has at least +- Every [initialized working directory](/docs/cli/init/index.html) 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](/cli/run/) - and [state manipulation](/cli/state/) commands) only interact +- Most Terraform commands (including [provisioning](/docs/cli/run/index.html) + and [state manipulation](/docs/cli/state/index.html) commands) only interact with the currently selected workspace. -- Use [the `terraform workspace select` command](/cli/commands/workspace/select) +- Use [the `terraform workspace select` command](/docs/cli/commands/workspace/select.html) to change the currently selected workspace. -- 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 +- 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 to manage the available workspaces in the current working directory. -> **Note:** Terraform Cloud and Terraform CLI both have features called @@ -37,19 +35,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](/language/state/) to associate resources with +Terraform relies on [state](/docs/language/state/index.html) 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](/language/values/variables) for these different +[variable values](/docs/language/values/variables.html) 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](/cli/init/) (with different -[backend](/language/settings/backends/configuration) configurations per directory, if you +[working directories](/docs/cli/init/index.html) (with different +[backend](/docs/language/settings/backends/configuration.html) 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. @@ -73,9 +71,9 @@ data, run history, and settings. These two kinds of workspaces are different, but related. When using Terraform CLI as a frontend for Terraform Cloud, you associate the current working directory with one or more remote workspaces by configuring -[the `remote` backend](/language/settings/backends/remote). If you associate the +[the `remote` backend](/docs/language/settings/backends/remote.html). If you associate the directory with multiple workspaces (using a name prefix), you can use the `terraform workspace` commands to select which remote workspace to use. For more information about using Terraform CLI with Terraform Cloud, see -[CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud docs. +[CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud docs. diff --git a/website/docs/configuration/expressions.html.md b/website/docs/configuration/expressions.html.md new file mode 100644 index 000000000..801253dcc --- /dev/null +++ b/website/docs/configuration/expressions.html.md @@ -0,0 +1,157 @@ +--- +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 deleted file mode 100644 index 67bebe859..000000000 --- a/website/docs/configuration/expressions.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -page_title: Expressions Landing Page - Configuration Language -sidebar_title: Expressions Landing Page ---- - -# 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 deleted file mode 100644 index 046abeac2..000000000 --- a/website/docs/configuration/index.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -page_title: Terraform Configuration ---- - -# Terraform Configuration diff --git a/website/docs/configuration/modules.html.md b/website/docs/configuration/modules.html.md new file mode 100644 index 000000000..1dbcf06a1 --- /dev/null +++ b/website/docs/configuration/modules.html.md @@ -0,0 +1,54 @@ +--- +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 deleted file mode 100644 index 1718f821e..000000000 --- a/website/docs/configuration/modules.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -page_title: Modules Landing Page - Configuration Language -sidebar_title: Modules Landing Page ---- - -# 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 new file mode 100644 index 000000000..87ae1bf5f --- /dev/null +++ b/website/docs/configuration/resources.html.md @@ -0,0 +1,135 @@ +--- +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 deleted file mode 100644 index 67e9ad67c..000000000 --- a/website/docs/configuration/resources.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -page_title: Resources Landing Page - Configuration Language -sidebar_title: Resources Landing Page ---- - -# 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.mdx b/website/docs/internals/archiving.html.md similarity index 75% rename from website/docs/internals/archiving.mdx rename to website/docs/internals/archiving.html.md index d1a153b81..6c9cad0f1 100644 --- a/website/docs/internals/archiving.mdx +++ b/website/docs/internals/archiving.html.md @@ -1,9 +1,9 @@ --- -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. +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. --- This function maps -[Terraform language values](/language/expressions/types) +[Terraform language values](/docs/language/expressions/types.html) to YAML tags in the following way: | Terraform type | YAML type | @@ -75,12 +77,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`](/language/functions/jsonencode) instead: YAML flow-style is a superset +[`jsonencode`](./jsonencode.html) instead: YAML flow-style is a superset of JSON syntax. ## Related Functions -- [`jsonencode`](/language/functions/jsonencode) is a similar operation using JSON instead +- [`jsonencode`](./jsonencode.html) is a similar operation using JSON instead of YAML. -- [`yamldecode`](/language/functions/yamldecode) performs the opposite operation, _decoding_ +- [`yamldecode`](./yamldecode.html) performs the opposite operation, _decoding_ a YAML string to obtain its represented value. diff --git a/website/docs/language/functions/zipmap.mdx b/website/docs/language/functions/zipmap.html.md similarity index 85% rename from website/docs/language/functions/zipmap.mdx rename to website/docs/language/functions/zipmap.html.md index 77df4ab30..d37926f74 100644 --- a/website/docs/language/functions/zipmap.mdx +++ b/website/docs/language/functions/zipmap.html.md @@ -1,9 +1,10 @@ --- -page_title: zipmap - Functions - Configuration Language +layout: "language" +page_title: "zipmap - Functions - Configuration Language" +sidebar_current: "docs-funcs-collection-zipmap" description: |- The zipmap function constructs a map from a list of keys and a corresponding list of values. -sidebar_title: zipmap --- # `zipmap` Function diff --git a/website/docs/language/index.mdx b/website/docs/language/index.html.md similarity index 89% rename from website/docs/language/index.mdx rename to website/docs/language/index.html.md index 329bdf9cf..649429890 100644 --- a/website/docs/language/index.mdx +++ b/website/docs/language/index.html.md @@ -1,17 +1,16 @@ --- -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. -sidebar_title: Overview +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." + --- # Terraform Language Documentation This is the documentation for Terraform's configuration language. It is relevant -to users of [Terraform CLI](/cli/), -[Terraform Cloud](/cloud-docs/), and -[Terraform Enterprise](/enterprise/). Terraform's language is +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 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 @@ -23,7 +22,7 @@ configuration block. ## About the Terraform Language The main purpose of the Terraform language is declaring -[resources](/language/resources/), which represent infrastructure objects. All other +[resources](/docs/language/resources/index.html), 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.mdx b/website/docs/language/meta-arguments/count.html.md similarity index 89% rename from website/docs/language/meta-arguments/count.mdx rename to website/docs/language/meta-arguments/count.html.md index 0d594831c..ed188d924 100644 --- a/website/docs/language/meta-arguments/count.mdx +++ b/website/docs/language/meta-arguments/count.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: The count Meta-Argument +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." --- # The `count` Meta-Argument @@ -15,14 +13,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](/language/resources/syntax) configures one real +By default, a [resource block](/docs/language/resources/syntax.html) configures one real infrastructure object. (Similarly, a -[module block](/language/modules/syntax) includes a +[module block](/docs/language/modules/syntax.html) 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`](/language/meta-arguments/for_each). +`count` and [`for_each`](/docs/language/meta-arguments/for_each.html). If a resource or module block includes a `count` argument whose value is a whole number, Terraform will create that many instances. @@ -61,7 +59,7 @@ This object has one attribute: ## Using Expressions in `count` -The `count` meta-argument accepts numeric [expressions](/language/expressions/). +The `count` meta-argument accepts numeric [expressions](/docs/language/expressions/index.html). 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.mdx b/website/docs/language/meta-arguments/depends_on.html.md similarity index 91% rename from website/docs/language/meta-arguments/depends_on.mdx rename to website/docs/language/meta-arguments/depends_on.html.md index 38a49c1b0..7224007c7 100644 --- a/website/docs/language/meta-arguments/depends_on.mdx +++ b/website/docs/language/meta-arguments/depends_on.html.md @@ -1,9 +1,7 @@ --- -page_title: The depends_on Meta-Argument - Configuration Language -description: >- - The depends_on meta-argument allows you to handle hidden resource or module - dependencies. -sidebar_title: The depends_on Meta-Argument +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." --- # The `depends_on` Meta-Argument @@ -76,3 +74,4 @@ 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.mdx b/website/docs/language/meta-arguments/for_each.html.md similarity index 83% rename from website/docs/language/meta-arguments/for_each.mdx rename to website/docs/language/meta-arguments/for_each.html.md index 63f8f4548..088f424fa 100644 --- a/website/docs/language/meta-arguments/for_each.mdx +++ b/website/docs/language/meta-arguments/for_each.html.md @@ -1,21 +1,19 @@ --- -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. -sidebar_title: The for_each Meta-Argument +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." --- # The `for_each` Meta-Argument -By default, a [resource block](/language/resources/syntax) configures one real +By default, a [resource block](/docs/language/resources/syntax.html) configures one real infrastructure object (and similarly, a -[module block](/language/modules/syntax) includes a +[module block](/docs/language/modules/syntax.html) 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`](/language/meta-arguments/count) and `for_each`. +[`count`](/docs/language/meta-arguments/count.html) 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. @@ -110,16 +108,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](/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), +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), 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](/language/expressions/function-calls#using-sensitive-data-as-function-arguments). +[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). 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 @@ -127,7 +125,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](/language/expressions/). +The `for_each` meta-argument accepts map or set [expressions](/docs/language/expressions/index.html). 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 @@ -136,7 +134,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`](/language/functions/toset) +explicitly returns a set value, like the [`toset`](/docs/language/functions/toset.html) 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 @@ -144,11 +142,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](/language/functions/flatten#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](/docs/language/functions/flatten.html#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](/language/functions/setproduct#finding-combinations-for-for_each). + [using the `setproduct` function inside a `for` expression](/docs/language/functions/setproduct.html#finding-combinations-for-for_each). ### Chaining `for_each` Between Resources @@ -228,7 +226,7 @@ as a whole. ## Using Sets The Terraform language doesn't have a literal syntax for -[set values](/language/expressions/type-constraints#collection-types), but you can use the `toset` +[set values](/docs/language/expressions/type-constraints.html#collection-types), but you can use the `toset` function to explicitly convert a list of strings to a set: ```hcl @@ -257,7 +255,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](/language/values/variables) that +If you are writing a module with an [input variable](/docs/language/values/variables.html) 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 new file mode 100644 index 000000000..840ab71a5 --- /dev/null +++ b/website/docs/language/meta-arguments/lifecycle.html.md @@ -0,0 +1,116 @@ +--- +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 deleted file mode 100644 index c7d6d8729..000000000 --- a/website/docs/language/meta-arguments/lifecycle.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -page_title: The lifecycle Meta-Argument - Configuration Language -description: >- - The meta-arguments in a lifecycle block allow you to customize resource - behavior. -sidebar_title: The lifecycle Meta-Argument ---- - -# 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.mdx b/website/docs/language/meta-arguments/module-providers.html.md similarity index 88% rename from website/docs/language/meta-arguments/module-providers.mdx rename to website/docs/language/meta-arguments/module-providers.html.md index c57f387c0..0103fd030 100644 --- a/website/docs/language/meta-arguments/module-providers.mdx +++ b/website/docs/language/meta-arguments/module-providers.html.md @@ -1,16 +1,14 @@ --- -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. -sidebar_title: The Module providers Meta-Argument +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." --- # The Module `providers` Meta-Argument -In a [module call](/language/modules/syntax) block, the +In a [module call](/docs/language/modules/syntax.html) block, the optional `providers` meta-argument specifies which -[provider configurations](/language/providers/configuration) from the parent +[provider configurations](/docs/language/providers/configuration.html) from the parent module will be available inside the child module. ```hcl @@ -39,7 +37,7 @@ module "example" { ## Default Behavior: Inherit Default Providers -If the child module does not declare any [configuration aliases](/language/modules/develop/providers#provider-aliases-within-modules), +If the child module does not declare any [configuration aliases](/docs/language/modules/develop/providers.html#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.) @@ -124,4 +122,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](/language/modules/develop/providers). +[Module Development: Providers Within Modules](/docs/language/modules/develop/providers.html). diff --git a/website/docs/language/meta-arguments/resource-provider.mdx b/website/docs/language/meta-arguments/resource-provider.html.md similarity index 78% rename from website/docs/language/meta-arguments/resource-provider.mdx rename to website/docs/language/meta-arguments/resource-provider.html.md index 8a7576150..21eaad48d 100644 --- a/website/docs/language/meta-arguments/resource-provider.mdx +++ b/website/docs/language/meta-arguments/resource-provider.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: The Resource provider Meta-Argument +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." --- # The Resource `provider` Meta-Argument @@ -12,7 +10,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](/language/providers/configuration), you can optionally +As described in [Provider Configuration](/docs/language/providers/configuration.html), 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 @@ -54,7 +52,7 @@ ensure that the provider is fully configured before any resource actions are taken. The `provider` meta-argument expects -[a `.` reference](/language/providers/configuration#referring-to-alternate-provider-configurations), +[a `.` reference](/docs/language/providers/configuration.html#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.mdx b/website/docs/language/modules/develop/composition.html.md similarity index 98% rename from website/docs/language/modules/develop/composition.mdx rename to website/docs/language/modules/develop/composition.html.md index fdfa02c1d..96c2da685 100644 --- a/website/docs/language/modules/develop/composition.mdx +++ b/website/docs/language/modules/develop/composition.html.md @@ -1,5 +1,7 @@ --- -page_title: Module Composition +layout: "language" +page_title: "Module Composition" +sidebar_current: "docs-modules-composition" description: |- Module composition allows infrastructure to be described from modular building blocks. @@ -308,7 +310,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](/language/data-sources/). +[data sources](/docs/language/data-sources/index.html). 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 @@ -344,7 +346,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`](/language/state/remote-state-data). +[`terraform_remote_state`](https://www.terraform.io/docs/language/state/remote-state-data.html). 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.mdx b/website/docs/language/modules/develop/index.html.md similarity index 77% rename from website/docs/language/modules/develop/index.mdx rename to website/docs/language/modules/develop/index.html.md index 6494cae4e..98b28ea7c 100644 --- a/website/docs/language/modules/develop/index.mdx +++ b/website/docs/language/modules/develop/index.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # 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`](/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) +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) 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](/language/modules/). +To learn how to _use_ modules, see [the Modules configuration section](/docs/language/modules/index.html). 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](/language/) concepts we use in root modules. +[configuration language](/docs/language/index.html) concepts we use in root modules. Most commonly, modules use: -* [Input variables](/language/values/variables) to accept values from +* [Input variables](/docs/language/values/variables.html) to accept values from the calling module. -* [Output values](/language/values/outputs) to return results to the +* [Output values](/docs/language/values/outputs.html) to return results to the calling module, which it can then use to populate arguments elsewhere. -* [Resources](/language/resources/) to define one or more +* [Resources](/docs/language/resources/index.html) 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](/language/modules/develop/composition) +keeping the module tree relatively flat and using [module composition](./composition.html) 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](/language/modules/develop/refactoring) to record how resource +You can include [refactoring blocks](refactoring.html) 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.mdx b/website/docs/language/modules/develop/providers.html.md similarity index 94% rename from website/docs/language/modules/develop/providers.mdx rename to website/docs/language/modules/develop/providers.html.md index 7ae63cf32..fd5db189a 100644 --- a/website/docs/language/modules/develop/providers.mdx +++ b/website/docs/language/modules/develop/providers.html.md @@ -1,6 +1,6 @@ --- -page_title: Providers Within Modules - Configuration Language -sidebar_title: Providers Within Modules +layout: "language" +page_title: "Providers Within Modules - Configuration Language" --- # Providers Within Modules @@ -45,10 +45,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](/language/providers/requirements), so that +declare its own [provider requirements](/docs/language/providers/requirements.html), 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](/language/providers/requirements#source-addresses) that serves as +[source address](/docs/language/providers/requirements.html#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 +71,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](/language/providers/configuration#alias-multiple-provider-configurations). +[several different configurations for the same provider](/docs/language/providers/configuration.html#alias-multiple-provider-configurations). ## Provider Aliases Within Modules @@ -133,10 +133,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](/language/providers/requirements). 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](/docs/language/providers/requirements.html). This is especially important for non-HashiCorp providers. In more complex situations there may be -[multiple provider configurations](/language/providers/configuration#alias-multiple-provider-configurations), +[multiple provider configurations](/docs/language/providers/configuration.html#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 +173,7 @@ module "example" { ``` The `providers` argument within a `module` block is similar to -[the `provider` argument](/language/meta-arguments/resource-provider) +[the `provider` argument](/docs/language/meta-arguments/resource-provider.html) 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.mdx b/website/docs/language/modules/develop/publish.html.md similarity index 76% rename from website/docs/language/modules/develop/publish.mdx rename to website/docs/language/modules/develop/publish.html.md index 6a5e0992d..2f1419dbb 100644 --- a/website/docs/language/modules/develop/publish.mdx +++ b/website/docs/language/modules/develop/publish.html.md @@ -1,17 +1,20 @@ --- -page_title: Publishing Modules -description: A module is a container for multiple resources that are used together. +layout: "language" +page_title: "Publishing Modules" +sidebar_current: "docs-modules-publish" +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](/registry/modules/publish) on the +[publishing the module](/docs/registry/modules/publish.html) 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](/language/modules/syntax#version) +[constrain module versions](/docs/language/modules/syntax.html#version) for safe and predictable updates. The following example shows how a caller might use a module from the Terraform Registry: @@ -22,20 +25,21 @@ module "consul" { ``` If you do not wish to publish your modules in the public registry, you can -instead use a [private registry](/registry/private) to get +instead use a [private registry](/docs/registry/private.html) 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](/language/modules/sources). The alternative sources +[various other sources](/docs/language/modules/sources.html). 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](/language/modules/develop/structure) so that they can +[standard module structure](/docs/language/modules/develop/structure.html) 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.mdx b/website/docs/language/modules/develop/refactoring.html.md similarity index 94% rename from website/docs/language/modules/develop/refactoring.mdx rename to website/docs/language/modules/develop/refactoring.html.md index 56d53db19..a7381a4c4 100644 --- a/website/docs/language/modules/develop/refactoring.mdx +++ b/website/docs/language/modules/develop/refactoring.html.md @@ -1,6 +1,9 @@ --- -page_title: Refactoring -description: How to make backward-compatible changes to modules already in use. +layout: "language" +page_title: "Refactoring" +sidebar_current: "docs-modules-recactoring" +description: |- + How to make backward-compatible changes to modules already in use. --- # Refactoring @@ -9,7 +12,7 @@ description: How to make backward-compatible changes to modules already in use. only in Terraform v1.1 and later. When working with earlier Terraform versions, or for refactoring actions too complex to express as `moved` blocks, you could use -[the `terraform state mv` CLI command](/cli/commands/state/mv) +[the `terraform state mv` CLI command](/docs/cli/commands/state/mv.html) as a separate step instead. In shared modules and long-lived configurations, you may eventually outgrow @@ -123,7 +126,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`](/language/meta-arguments/for_each) with this +Later, you use [`for_each`](../../meta-arguments/for_each.html) 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 @@ -257,7 +260,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`](/language/meta-arguments/count) with this resource to systematically +[`count`](../../meta-arguments/count.html) 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: @@ -321,8 +324,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. -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 +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 instead to contain only shim configuration to migrate existing users. The new modules "x" and "y" should contain only `resource` blocks: @@ -394,13 +397,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](/language/modules/sources#modules-in-package-sub-directories). +[module package](../sources.html#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](/language/modules/sources#local-paths). +that call had not been a [local path](../sources.html#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 @@ -423,15 +426,16 @@ moved { ## Removing `moved` Blocks -Over time, a long-lasting module may accumulate many `moved` blocks. +Over time, a long-lasting module may accumulate many `moved` blocks. -Removing a `moved` block is a generally breaking change because any configurations that refer to the old address will plan to delete that existing object instead of move it. We strongly recommend that you retain all historical `moved` blocks from earlier versions of your modules to preserve the upgrade path for users of any previous version. +Removing a `moved` block is a generally breaking change because any configurations that refer to the old address will plan to delete that existing object instead of move it. We strongly recommend that you retain all historical `moved` blocks from earlier versions of your modules to preserve the upgrade path for users of any previous version. If you do decide to remove `moved` blocks, proceed with caution. It can be safe to remove `moved` blocks when you are maintaining private modules within an organization and you are certain that all users have successfully run `terraform apply` with your new module version. 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.mdx b/website/docs/language/modules/develop/structure.html.md similarity index 95% rename from website/docs/language/modules/develop/structure.mdx rename to website/docs/language/modules/develop/structure.html.md index dbe2db33c..6aed2b265 100644 --- a/website/docs/language/modules/develop/structure.mdx +++ b/website/docs/language/modules/develop/structure.html.md @@ -1,5 +1,6 @@ --- -page_title: Standard Module Structure +layout: "language" +page_title: "Standard Module Structure" --- # Standard Module Structure @@ -53,8 +54,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](/language/values/variables) and - [output configuration](/language/values/outputs) for more details. + [variable configuration](/docs/language/values/variables.html) and + [output configuration](/docs/language/values/outputs.html) for more details. * **Nested modules**. Nested modules should exist under the `modules/` subdirectory. Any nested module with a `README.md` is considered usable @@ -74,7 +75,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](/language/modules/develop/composition) by the caller, rather than + ideally be [composable](./composition.html) 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.mdx b/website/docs/language/modules/index.html.md similarity index 71% rename from website/docs/language/modules/index.mdx rename to website/docs/language/modules/index.html.md index 768b3c760..a1c122768 100644 --- a/website/docs/language/modules/index.mdx +++ b/website/docs/language/modules/index.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: Modules Overview +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." --- # Modules @@ -45,27 +43,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](/cloud-docs/) and -[Terraform Enterprise](/enterprise/) both include a private +for your own infrastructure needs. [Terraform Cloud](/docs/cloud/index.html) and +[Terraform Enterprise](/docs/enterprise/index.html) both include a private module registry for sharing modules internally within your organization. ## Using Modules -- [Module Blocks](/language/modules/syntax) documents the syntax for +- [Module Blocks](/docs/language/modules/syntax.html) documents the syntax for calling a child module from a parent module, including meta-arguments like `for_each`. -- [Module Sources](/language/modules/sources) documents what kinds of paths, +- [Module Sources](/docs/language/modules/sources.html) 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`](/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). + [`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). ## Developing Modules For information about developing reusable modules, see -[Module Development](/language/modules/develop/). +[Module Development](/docs/language/modules/develop/index.html). diff --git a/website/docs/language/modules/sources.mdx b/website/docs/language/modules/sources.html.md similarity index 92% rename from website/docs/language/modules/sources.mdx rename to website/docs/language/modules/sources.html.md index 1af189b94..b9db802fa 100644 --- a/website/docs/language/modules/sources.mdx +++ b/website/docs/language/modules/sources.html.md @@ -1,14 +1,13 @@ --- -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. +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." --- # Module Sources -The `source` argument in [a `module` block](/language/modules/syntax) +The `source` argument in [a `module` block](/docs/language/modules/syntax.html) tells Terraform where to find the source code for the desired child module. Terraform uses this during the module installation step of `terraform init` @@ -17,28 +16,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 @@ -100,10 +99,10 @@ to get started with Terraform and find modules created by others in the community. You can also use a -[private registry](/registry/private), either +[private registry](/docs/registry/private.html), either via the built-in feature from Terraform Cloud, or by running a custom service that implements -[the module registry protocol](/registry/api-docs). +[the module registry protocol](/docs/registry/api.html). Modules on the public Terraform Registry can be referenced using a registry source address of the form `//`, with each @@ -139,13 +138,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](/language/modules/syntax#version). +[version constraints](/docs/language/modules/syntax.html#version). You can learn more about the registry at the -[Terraform Registry documentation](/registry/modules/use#using-modules). +[Terraform Registry documentation](/docs/registry/modules/use.html#using-modules). To access modules from a private registry, you may need to configure an access -token [in the CLI config](/cli/config/config-file#credentials). Use the +token [in the CLI config](/docs/cli/config/config-file.html#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. @@ -232,7 +231,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](/cloud-docs/workspaces/settings/ssh-keys). +[keys can be configured on a per-workspace basis](/docs/cloud/workspaces/ssh-keys.html). ### Selecting a Revision @@ -267,6 +266,7 @@ 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](/cloud-docs/workspaces/settings/ssh-keys). +[keys can be configured on a per-workspace basis](/docs/cloud/workspaces/ssh-keys.html). ### Selecting a Revision @@ -427,6 +427,7 @@ 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.mdx b/website/docs/language/modules/syntax.html.md similarity index 83% rename from website/docs/language/modules/syntax.mdx rename to website/docs/language/modules/syntax.html.md index 3b5e37831..83c98fcba 100644 --- a/website/docs/language/modules/syntax.mdx +++ b/website/docs/language/modules/syntax.html.md @@ -1,10 +1,8 @@ --- -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. -sidebar_title: Modules +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." --- # Module Blocks @@ -24,13 +22,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](/language/modules/develop/). +about creating re-usable child modules, see [Module Development](/docs/language/modules/develop/index.html). ## 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](/language/values/variables). Modules are called +[input variables](/docs/language/values/variables.html). Modules are called from within other modules using `module` blocks: ```hcl @@ -54,7 +52,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](/language/values/variables) +- Most other arguments correspond to [input variables](/docs/language/values/variables.html) defined by the module. (The `servers` argument in the example above is one of these.) @@ -68,7 +66,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](/language/modules/sources). +possible values for this argument, see [Module Sources](/docs/language/modules/sources.html). The same source address can be specified in multiple `module` blocks to create multiple copies of the resources defined within, possibly with different @@ -96,14 +94,14 @@ module "consul" { } ``` -The `version` argument accepts a [version constraint string](/language/expressions/version-constraints). +The `version` argument accepts a [version constraint string](/docs/language/expressions/version-constraints.html). 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](/cloud-docs/registry/). +or [Terraform Cloud's private module registry](/docs/cloud/registry/index.html). 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 @@ -117,22 +115,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](/language/meta-arguments/count) + See [the `count` page](/docs/language/meta-arguments/count.html) for details. - `for_each` - Creates multiple instances of a module from a single `module` block. See - [the `for_each` page](/language/meta-arguments/for_each) + [the `for_each` page](/docs/language/meta-arguments/for_each.html) for details. - `providers` - Passes provider configurations to a child module. See - [the `providers` page](/language/meta-arguments/module-providers) + [the `providers` page](/docs/language/meta-arguments/module-providers.html) 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](/language/meta-arguments/depends_on) + [the `depends_on` page](/docs/language/meta-arguments/depends_on.html) for details. In addition to the above, the `lifecycle` argument is not currently used by @@ -142,7 +140,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](/language/values/outputs) to selectively +declare [output values](/docs/language/values/outputs.html) to selectively export certain values to be accessed by the calling module. For example, if the `./app-cluster` module referenced in the example above @@ -158,7 +156,7 @@ resource "aws_elb" "example" { ``` For more information about referring to named values, see -[Expressions](/language/expressions/). +[Expressions](/docs/language/expressions/index.html). ## Transferring Resource State Into Modules @@ -168,7 +166,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](/language/modules/develop/refactoring) to record the old and new +[refactoring blocks](develop/refactoring.html) 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. @@ -178,7 +176,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](/cli/commands/plan#replace-address) +[the `-replace=...` planning option](/docs/cli/commands/plan.html#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.mdx b/website/docs/language/modules/testing-experiment.html.md similarity index 99% rename from website/docs/language/modules/testing-experiment.mdx rename to website/docs/language/modules/testing-experiment.html.md index a3b5328cf..6b2bb7fce 100644 --- a/website/docs/language/modules/testing-experiment.mdx +++ b/website/docs/language/modules/testing-experiment.html.md @@ -1,6 +1,6 @@ --- -page_title: Module Testing Experiment - Configuration Language -sidebar_title: Module Testing Experiment +layout: "language" +page_title: "Module Testing Experiment - Configuration Language" --- # Module Testing Experiment diff --git a/website/docs/language/providers/configuration.mdx b/website/docs/language/providers/configuration.html.md similarity index 86% rename from website/docs/language/providers/configuration.mdx rename to website/docs/language/providers/configuration.html.md index 495a0c668..8251bce19 100644 --- a/website/docs/language/providers/configuration.mdx +++ b/website/docs/language/providers/configuration.html.md @@ -1,9 +1,8 @@ --- -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. -sidebar_title: Provider Configuration +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." --- # Provider Configuration @@ -17,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](/language/providers/requirements) +[Provider Requirements](/docs/language/providers/requirements.html) page documents how to declare providers so Terraform can install them. ## Provider Configuration @@ -25,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](/language/meta-arguments/module-providers) -and [Module Development: Providers Within Modules](/language/modules/develop/providers).) +[The Module `providers` Meta-Argument](/docs/language/meta-arguments/module-providers.html) +and [Module Development: Providers Within Modules](/docs/language/modules/develop/providers.html).) A provider configuration is created using a `provider` block: @@ -38,7 +37,7 @@ provider "google" { ``` The name given in the block header (`"google"` in this example) is the -[local name](/language/providers/requirements#local-names) of the provider to +[local name](/docs/language/providers/requirements.html#local-names) of the provider to configure. This provider should already be included in a `required_providers` block. @@ -47,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](/language/expressions/) in the values of these +You can use [expressions](/docs/language/expressions/index.html) 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 @@ -69,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](/language/providers/requirements) instead) + [provider requirements](/docs/language/providers/requirements.html) 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 @@ -176,7 +175,7 @@ module "aws_vpc" { ``` Modules have some special requirements when passing in providers; see -[The Module `providers` Meta-Argument](/language/meta-arguments/module-providers) +[The Module `providers` Meta-Argument](/docs/language/meta-arguments/module-providers.html) for more details. In most cases, only _root modules_ should define provider configurations, with all child modules obtaining their provider configurations from their parents. @@ -189,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](/language/providers/requirements). The version +[`required_providers` block](/docs/language/providers/requirements.html). 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](/language/providers/requirements). The `version` +[the `required_providers` block](/docs/language/providers/requirements.html). The `version` argument will be removed in a future version of Terraform. diff --git a/website/docs/language/providers/index.mdx b/website/docs/language/providers/index.html.md similarity index 54% rename from website/docs/language/providers/index.mdx rename to website/docs/language/providers/index.html.md index 5568fdd70..fd95e66e5 100644 --- a/website/docs/language/providers/index.mdx +++ b/website/docs/language/providers/index.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: Providers +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." --- # Providers @@ -19,8 +17,8 @@ configuration (like endpoint URLs or cloud regions) before they can be used. ## What Providers Do -Each provider adds a set of [resource types](/language/resources/) -and/or [data sources](/language/data-sources/) that Terraform can +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 manage. Every resource type is implemented by a provider; without providers, Terraform @@ -52,20 +50,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](/registry/providers/docs). +see the [provider publishing documentation](/docs/registry/providers/docs.html). ## 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](/language/providers/requirements) +- [Provider Requirements](/docs/language/providers/requirements.html) documents how to declare providers so Terraform can install them. -- [Provider Configuration](/language/providers/configuration) +- [Provider Configuration](/docs/language/providers/configuration.html) documents how to configure settings for providers. -- [Dependency Lock File](/language/dependency-lock) +- [Dependency Lock File](/docs/language/dependency-lock.html) documents an additional HCL file that can be included with a configuration, which tells Terraform to always use a specific set of provider versions. @@ -74,18 +72,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](/cli/init/). It can + [initializing a working directory](/docs/cli/init/index.html). 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](/cli/config/config-file). + 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 ensure Terraform always installs the same provider versions for a given configuration, you can use Terraform CLI to create a -[dependency lock file](/language/dependency-lock) +[dependency lock file](/docs/language/dependency-lock.html) 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. @@ -102,14 +100,42 @@ 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](/plugin/) documentation +- The [Plugin Development](/docs/extend/index.html) 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.mdx b/website/docs/language/providers/requirements.html.md similarity index 91% rename from website/docs/language/providers/requirements.mdx rename to website/docs/language/providers/requirements.html.md index df5118ac1..6e8b995c4 100644 --- a/website/docs/language/providers/requirements.mdx +++ b/website/docs/language/providers/requirements.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: Provider Requirements +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." --- # Provider Requirements @@ -17,7 +15,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](/language/providers/configuration) page documents how +Configuration](/docs/language/providers/configuration.html) page documents how to configure settings for providers. -> **Note:** This page is about a feature of Terraform 0.13 and later; it also @@ -45,7 +43,7 @@ terraform { ``` The `required_providers` block must be nested inside the top-level -[`terraform` block](/language/settings/) (which can also contain other settings). +[`terraform` block](/docs/language/settings/index.html) (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 @@ -68,8 +66,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. @@ -82,7 +80,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](/language/providers/configuration): +name when [configuring the provider](/docs/language/providers/configuration.html): ```hcl terraform { @@ -133,11 +131,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) @@ -152,6 +150,7 @@ 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 @@ -211,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](/language/expressions/version-constraints) given in +declare should have a [version constraint](/docs/language/expressions/version-constraints.html) given in the `version` argument so Terraform can select a single version per provider that all modules are compatible with. @@ -221,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](/language/dependency-lock) +[dependency lock file](/docs/language/dependency-lock.html) 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. @@ -273,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](/language/state/remote-state-data). +[the `terraform_remote_state` data source](/docs/language/state/remote-state-data.html). 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 @@ -302,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](/internals/provider-registry-protocol). +[the provider registry protocol](/docs/internals/provider-registry-protocol.html). Running an additional service just to distribute a single provider internally may be undesirable, so Terraform also supports -[other provider installation methods](/cli/config/config-file#provider-installation), +[other provider installation methods](/docs/cli/config/config-file.html#provider-installation), including placing provider plugins directly in specific directories in the local filesystem, via _filesystem mirrors_. @@ -335,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](/cli/config/config-file#implied-local-mirror-directories) +[implied local mirror directories](/docs/cli/config/config-file.html#implied-local-mirror-directories) and create a directory structure under it like this: ``` diff --git a/website/docs/language/resources/behavior.mdx b/website/docs/language/resources/behavior.html.md similarity index 86% rename from website/docs/language/resources/behavior.mdx rename to website/docs/language/resources/behavior.html.md index 44b9eadfb..1f8b4c249 100644 --- a/website/docs/language/resources/behavior.mdx +++ b/website/docs/language/resources/behavior.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: Resource Behavior +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." --- # Resource Behavior @@ -21,7 +19,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](/language/state/), allowing it to be updated and destroyed +[state](/docs/language/state/index.html), 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 @@ -45,7 +43,7 @@ customized on a per-resource basis. ## Accessing Resource Attributes -[Expressions](/language/expressions/) within a Terraform module can access +[Expressions](/docs/language/expressions/index.html) 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. @@ -55,7 +53,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](/language/data-sources/), +Many providers also include [data sources](/docs/language/data-sources/index.html), 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 @@ -63,7 +61,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](/language/expressions/references#references-to-resource-attributes). +[Expressions: References to Resource Attributes](/docs/language/expressions/references.html#references-to-resource-attributes). ## Resource Dependencies @@ -76,7 +74,7 @@ resource's configuration just requires information generated by another resource. Most resource dependencies are handled automatically. Terraform analyses any -[expressions](/language/expressions/) within a `resource` block to find references +[expressions](/docs/language/expressions/index.html) 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, @@ -87,7 +85,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](/language/meta-arguments/depends_on) +[the `depends_on` meta-argument](/docs/language/meta-arguments/depends_on.html) can explicitly specify a dependency. ## Local-only Resources @@ -108,3 +106,4 @@ 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.mdx b/website/docs/language/resources/index.html.md similarity index 55% rename from website/docs/language/resources/index.mdx rename to website/docs/language/resources/index.html.md index c99606fe4..4de70b7d4 100644 --- a/website/docs/language/resources/index.mdx +++ b/website/docs/language/resources/index.html.md @@ -1,9 +1,7 @@ --- -page_title: Resources Overview - Configuration Language -description: >- - Resources describe infrastructure objects in Terraform configurations. Find - documentation for resource syntax, behavior, and meta-arguments. -sidebar_title: Resources Overview +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." --- # Resources @@ -15,22 +13,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](/language/resources/syntax) documents +- [Resource Blocks](/docs/language/resources/syntax.html) documents the syntax for declaring resources. -- [Resource Behavior](/language/resources/behavior) explains in +- [Resource Behavior](/docs/language/resources/behavior.html) 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`](/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). + [`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). -- [Provisioners](/language/resources/provisioners/) +- [Provisioners](/docs/language/resources/provisioners/index.html) 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.mdx b/website/docs/language/resources/provisioners/chef.html.md similarity index 93% rename from website/docs/language/resources/provisioners/chef.mdx rename to website/docs/language/resources/provisioners/chef.html.md index 9ec4887e2..e420b9a38 100644 --- a/website/docs/language/resources/provisioners/chef.mdx +++ b/website/docs/language/resources/provisioners/chef.html.md @@ -1,17 +1,18 @@ --- -page_title: 'Provisioner: chef' -description: >- - The `chef` provisioner installs, configures and runs the Chef client on a - resource. +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. --- # 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](/language/resources/provisioners/connection). +[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](/language/resources/provisioners). +!> **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 @@ -67,7 +68,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](/language/functions/file). + [the `file` function](/docs/language/functions/file.html). * `channel (string)` - (Optional) The Chef Client release channel to install from. If not set, the `stable` channel will be used. @@ -126,7 +127,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](/language/resources/provisioners/connection). + [connections](/docs/language/resources/provisioners/connection.html). * `recreate_client (boolean)` - (Optional) If `true`, first delete any existing Chef Node and Client before registering the new Chef Client. @@ -144,7 +145,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](/language/functions/file). + [the `file` function](/docs/language/functions/file.html). * `server_url (string)` - (Required) The URL to the Chef server. This includes the path to the organization. See the example. @@ -166,11 +167,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](/language/functions/file). + [the `file` function](/docs/language/functions/file.html). * `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](/language/functions/file). + [the `file` function](/docs/language/functions/file.html). * `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.mdx b/website/docs/language/resources/provisioners/connection.html.md similarity index 80% rename from website/docs/language/resources/provisioners/connection.mdx rename to website/docs/language/resources/provisioners/connection.html.md index 704012199..762c37a91 100644 --- a/website/docs/language/resources/provisioners/connection.mdx +++ b/website/docs/language/resources/provisioners/connection.html.md @@ -1,8 +1,8 @@ --- -page_title: Provisioner Connection Settings -description: >- - The connection block allows you to manage provisioner connection defaults for - SSH and WinRM. +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." --- # 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](/language/resources/provisioners). +[the main Provisioners page](./). -> **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,25 +107,24 @@ 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](/language/functions/file). This takes + [the `file` function](/docs/language/functions/file.html). 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](/language/functions/file). + be loaded from a file on disk using the [the `file` function](/docs/language/functions/file.html). * `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:** @@ -161,9 +160,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](/language/functions/file). + [the `file` function](/docs/language/functions/file.html). 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](/language/functions/file). + a file on disk using the [the `file` function](/docs/language/functions/file.html). diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.html.md similarity index 89% rename from website/docs/language/resources/provisioners/file.mdx rename to website/docs/language/resources/provisioners/file.html.md index 06b22758b..05b494e5b 100644 --- a/website/docs/language/resources/provisioners/file.mdx +++ b/website/docs/language/resources/provisioners/file.html.md @@ -1,20 +1,20 @@ --- -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. +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. --- # 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](/language/resources/provisioners/connection). +supports both `ssh` and `winrm` type [connections](/docs/language/resources/provisioners/connection.html). -> **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](/language/resources/provisioners). +[the main Provisioners page](./). ## Example usage diff --git a/website/docs/language/resources/provisioners/habitat.mdx b/website/docs/language/resources/provisioners/habitat.html.md similarity index 94% rename from website/docs/language/resources/provisioners/habitat.mdx rename to website/docs/language/resources/provisioners/habitat.html.md index c8ab535d1..66af5a655 100644 --- a/website/docs/language/resources/provisioners/habitat.mdx +++ b/website/docs/language/resources/provisioners/habitat.html.md @@ -1,21 +1,22 @@ --- -page_title: 'Provisioner: habitat' -description: >- - The `habitat` provisioner installs the Habitat supervisor, and loads - configured services. +layout: "language" +page_title: "Provisioner: habitat" +sidebar_current: "docs-provisioners-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](/language/resources/provisioners). +!> **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 `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. @@ -49,7 +50,6 @@ 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 ) +* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to https://bldr.habitat.sh) * `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,7 +74,6 @@ 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"]`: @@ -86,13 +85,12 @@ 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 ) +* `url (string)` - (Optional) The URL of a Builder service to download packages and receive updates from. (Defaults to https://bldr.habitat.sh) * `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 new file mode 100644 index 000000000..2a22e2dd2 --- /dev/null +++ b/website/docs/language/resources/provisioners/index.html.md @@ -0,0 +1,12 @@ +--- +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 deleted file mode 100644 index 29d295c25..000000000 --- a/website/docs/language/resources/provisioners/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. -sidebar_title: Provisioners Overview ---- - -# 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.mdx b/website/docs/language/resources/provisioners/local-exec.html.md similarity index 83% rename from website/docs/language/resources/provisioners/local-exec.mdx rename to website/docs/language/resources/provisioners/local-exec.html.md index 02eec0ef7..1feded8c7 100644 --- a/website/docs/language/resources/provisioners/local-exec.mdx +++ b/website/docs/language/resources/provisioners/local-exec.html.md @@ -1,9 +1,9 @@ --- -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. +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. --- # 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](/language/resources/provisioners/remote-exec) to run commands on the +[provisioner](/docs/language/resources/provisioners/remote-exec.html) 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](/language/resources/provisioners). +[the main Provisioners page](./). ## 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.mdx b/website/docs/language/resources/provisioners/null_resource.html.md similarity index 68% rename from website/docs/language/resources/provisioners/null_resource.mdx rename to website/docs/language/resources/provisioners/null_resource.html.md index 3e7b3fd65..4d9f53712 100644 --- a/website/docs/language/resources/provisioners/null_resource.mdx +++ b/website/docs/language/resources/provisioners/null_resource.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # 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](/language/resources/provisioners/syntax) and [connection -details](/language/resources/provisioners/connection) on a `null_resource`. You can also +[provisioners](/docs/language/resources/provisioners/syntax.html) and [connection +details](/docs/language/resources/provisioners/connection.html) 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.mdx b/website/docs/language/resources/provisioners/puppet.html.md similarity index 93% rename from website/docs/language/resources/provisioners/puppet.mdx rename to website/docs/language/resources/provisioners/puppet.html.md index e0894c271..0e5005256 100644 --- a/website/docs/language/resources/provisioners/puppet.mdx +++ b/website/docs/language/resources/provisioners/puppet.html.md @@ -1,17 +1,18 @@ --- -page_title: 'Provisioner: puppet' -description: >- - The `puppet` provisioner installs, configures and runs the Puppet agent on a - resource. +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. --- # 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](/language/resources/provisioners/connection). +[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](/language/resources/provisioners). +!> **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 @@ -75,7 +76,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.mdx b/website/docs/language/resources/provisioners/remote-exec.html.md similarity index 67% rename from website/docs/language/resources/provisioners/remote-exec.mdx rename to website/docs/language/resources/provisioners/remote-exec.html.md index 4b4d94274..19e771989 100644 --- a/website/docs/language/resources/provisioners/remote-exec.mdx +++ b/website/docs/language/resources/provisioners/remote-exec.html.md @@ -1,11 +1,9 @@ --- -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. +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. --- # remote-exec Provisioner @@ -13,13 +11,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](/language/resources/provisioners/local-exec) instead. The `remote-exec` -provisioner requires a [connection](/language/resources/provisioners/connection) +[provisioner](/docs/language/resources/provisioners/local-exec.html) instead. The `remote-exec` +provisioner requires a [connection](/docs/language/resources/provisioners/connection.html) 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](/language/resources/provisioners). +[the main Provisioners page](./). ## Example usage @@ -60,14 +58,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`](/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. +-> **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. ## 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](/language/resources/provisioners/file) +[file provisioner](/docs/language/resources/provisioners/file.html) 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 new file mode 100644 index 000000000..6cdb4f326 --- /dev/null +++ b/website/docs/language/resources/provisioners/salt-masterless.html.md @@ -0,0 +1,92 @@ +--- +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 deleted file mode 100644 index d24532177..000000000 --- a/website/docs/language/resources/provisioners/salt-masterless.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -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.mdx b/website/docs/language/resources/provisioners/syntax.html.md similarity index 93% rename from website/docs/language/resources/provisioners/syntax.mdx rename to website/docs/language/resources/provisioners/syntax.html.md index 421e5d2ee..0ba9d9d00 100644 --- a/website/docs/language/resources/provisioners/syntax.mdx +++ b/website/docs/language/resources/provisioners/syntax.html.md @@ -1,8 +1,8 @@ --- -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. +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." --- # 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](/language/resources/provisioners/connection) so that Terraform +You must include [a `connection` block](./connection.html) 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](/language/values/variables#suppressing-values-in-cli-output) or -[`sensitive` output values](/language/values/outputs#sensitive-suppressing-values-in-cli-output). +[`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). In this case, all log output from the provisioner is automatically suppressed to prevent the sensitive values from being displayed. @@ -236,10 +236,8 @@ 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 @@ -290,10 +288,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.mdx b/website/docs/language/resources/syntax.html.md similarity index 83% rename from website/docs/language/resources/syntax.mdx rename to website/docs/language/resources/syntax.html.md index 9aefe8bac..456e93779 100644 --- a/website/docs/language/resources/syntax.mdx +++ b/website/docs/language/resources/syntax.html.md @@ -1,10 +1,8 @@ --- -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. -sidebar_title: Resources +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." --- # Resource Blocks @@ -54,7 +52,7 @@ attributes the resource supports. ### Providers -Each resource type is implemented by a [provider](/language/providers/requirements), +Each resource type is implemented by a [provider](/docs/language/providers/requirements.html), 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 @@ -67,16 +65,16 @@ access their remote APIs, and the root module must provide that configuration. For more information, see: -- [Provider Requirements](/language/providers/requirements), for declaring which +- [Provider Requirements](/docs/language/providers/requirements.html), for declaring which providers a module uses. -- [Provider Configuration](/language/providers/configuration), for configuring provider settings. +- [Provider Configuration](/docs/language/providers/configuration.html), 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](/language/meta-arguments/resource-provider) for more details. +[the `provider` meta-argument](/docs/language/meta-arguments/resource-provider.html) for more details. ### Resource Arguments @@ -85,7 +83,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](/language/expressions/) and other dynamic Terraform +[expressions](/docs/language/expressions/index.html) and other dynamic Terraform language features. There are also some _meta-arguments_ that are defined by Terraform itself @@ -116,7 +114,7 @@ public provider docs. For more information about how Terraform manages resources when applying a configuration, see -[Resource Behavior](/language/resources/behavior). +[Resource Behavior](/docs/language/resources/behavior.html). ## Meta-Arguments @@ -125,12 +123,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](/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/) +- [`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) ## Operation Timeouts diff --git a/website/docs/language/settings/backends/artifactory.mdx b/website/docs/language/settings/backends/artifactory.html.md similarity index 67% rename from website/docs/language/settings/backends/artifactory.mdx rename to website/docs/language/settings/backends/artifactory.html.md index b800dd040..2e19dea89 100644 --- a/website/docs/language/settings/backends/artifactory.mdx +++ b/website/docs/language/settings/backends/artifactory.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Backend Type: artifactory' -description: Terraform can store state in artifactory. +layout: "language" +page_title: "Backend Type: artifactory" +sidebar_current: "docs-backends-types-standard-artifactory" +description: |- + Terraform can store state in artifactory. --- # artifactory @@ -49,8 +52,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.mdx b/website/docs/language/settings/backends/azurerm.html.md similarity index 96% rename from website/docs/language/settings/backends/azurerm.mdx rename to website/docs/language/settings/backends/azurerm.html.md index 01d5a15fd..9179a5551 100644 --- a/website/docs/language/settings/backends/azurerm.mdx +++ b/website/docs/language/settings/backends/azurerm.html.md @@ -1,6 +1,10 @@ --- -page_title: 'Backend Type: azurerm' -description: Terraform can store state remotely in Azure Blob Storage. +layout: "language" +page_title: "Backend Type: azurerm" +sidebar_current: "docs-backends-types-standard-azurerm" +description: |- + Terraform can store state remotely in Azure Blob Storage. + --- # azurerm @@ -9,7 +13,7 @@ description: Terraform can store state remotely in Azure Blob Storage. Stores the state as a Blob with the given Key within the Blob Container within [the Blob Storage Account](https://docs.microsoft.com/en-us/azure/storage/common/storage-introduction). This backend also supports state locking and consistency checking via native capabilities of Azure Blob Storage. --> **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 @@ -26,7 +30,7 @@ terraform { } ``` -*** +--- When authenticating using Managed Service Identity (MSI): @@ -44,7 +48,7 @@ terraform { } ``` -*** +--- When authenticating using Azure AD Authentication: @@ -63,7 +67,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: @@ -81,7 +85,7 @@ terraform { } ``` -*** +--- When authenticating using a SAS Token associated with the Storage Account: @@ -99,7 +103,7 @@ terraform { } ``` --> **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. +-> **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. ## Data Source Configuration @@ -116,7 +120,7 @@ data "terraform_remote_state" "foo" { } ``` -*** +--- When authenticating using Managed Service Identity (MSI): @@ -135,7 +139,7 @@ data "terraform_remote_state" "foo" { } ``` -*** +--- When authenticating using AzureAD Authentication: @@ -155,7 +159,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: @@ -174,7 +178,7 @@ data "terraform_remote_state" "foo" { } ``` -*** +--- When authenticating using a SAS Token associated with the Storage Account: @@ -211,16 +215,14 @@ 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. @@ -231,19 +233,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: @@ -255,7 +257,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: @@ -275,7 +277,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.mdx b/website/docs/language/settings/backends/configuration.html.md similarity index 82% rename from website/docs/language/settings/backends/configuration.mdx rename to website/docs/language/settings/backends/configuration.html.md index daff89d75..886413e7e 100644 --- a/website/docs/language/settings/backends/configuration.mdx +++ b/website/docs/language/settings/backends/configuration.html.md @@ -1,12 +1,13 @@ --- -page_title: Backend Configuration - Configuration Language -sidebar_title: Backend Configuration +layout: "language" +page_title: "Backend Configuration - Configuration Language" --- # Backend Configuration + Each Terraform configuration can specify a backend, which defines exactly where -and how operations are performed, where [state](/language/state/) +and how operations are performed, where [state](/docs/language/state/index.html) snapshots are stored, etc. Most non-trivial Terraform configurations configure a remote backend so that multiple people can work with the same infrastructure. @@ -69,25 +70,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](/cli/init/). +provided as part of [the initialization process](/docs/cli/init/index.html). 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 @@ -152,12 +153,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](/cli/init/). As part of +and request a [reinitialization](/docs/cli/init/index.html). 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](/language/state/workspaces), +If you're using multiple [workspaces](/docs/language/state/workspaces.html), 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. @@ -168,7 +169,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](/cli/init/). +change and prompt you to [reinitialize](/docs/cli/init/index.html). 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 new file mode 100644 index 000000000..d2f921454 --- /dev/null +++ b/website/docs/language/settings/backends/consul.html.md @@ -0,0 +1,61 @@ +--- +layout: "language" +page_title: "Backend Type: consul" +sidebar_current: "docs-backends-types-standard-consul" +description: |- + Terraform can store state in Consul. +--- + +# consul + +**Kind: Standard (with locking)** + +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 deleted file mode 100644 index 3f2a0d004..000000000 --- a/website/docs/language/settings/backends/consul.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -page_title: 'Backend Type: consul' -description: Terraform can store state in Consul. ---- - -# consul - -**Kind: Standard (with locking)** - -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.mdx b/website/docs/language/settings/backends/cos.html.md similarity index 52% rename from website/docs/language/settings/backends/cos.mdx rename to website/docs/language/settings/backends/cos.html.md index 43131c111..cef18670c 100644 --- a/website/docs/language/settings/backends/cos.mdx +++ b/website/docs/language/settings/backends/cos.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Backend Type: cos' -description: >- - Terraform can store the state remotely, making it easier to version and work - with in a team. +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. --- # COS @@ -10,7 +11,7 @@ description: >- **Kind: Standard (with locking)** 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 also supports [state locking](/language/state/locking). +This backend also supports [state locking](/docs/language/state/locking.html). ~> **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 +33,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](/language/state/remote-state-data). +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). ```hcl data "terraform_remote_state" "foo" { @@ -50,11 +51,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.mdx b/website/docs/language/settings/backends/etcd.html.md similarity index 61% rename from website/docs/language/settings/backends/etcd.mdx rename to website/docs/language/settings/backends/etcd.html.md index 024a4e00e..792b7354c 100644 --- a/website/docs/language/settings/backends/etcd.mdx +++ b/website/docs/language/settings/backends/etcd.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Backend Type: etcd' -description: Terraform can store state remotely in etcd 2.x. +layout: "language" +page_title: "Backend Type: etcd" +sidebar_current: "docs-backends-types-standard-etcdv2" +description: |- + Terraform can store state remotely in etcd 2.x. --- # etcd @@ -36,7 +39,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 new file mode 100644 index 000000000..318a7b405 --- /dev/null +++ b/website/docs/language/settings/backends/etcdv3.html.md @@ -0,0 +1,57 @@ +--- +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 + +**Kind: Standard (with locking)** + +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 deleted file mode 100644 index 9b3a8842f..000000000 --- a/website/docs/language/settings/backends/etcdv3.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -page_title: 'Backend Type: etcdv3' -description: Terraform can store state remotely in etcd 3.x. ---- - -# etcdv3 - -**Kind: Standard (with locking)** - -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.mdx b/website/docs/language/settings/backends/gcs.html.md similarity index 53% rename from website/docs/language/settings/backends/gcs.mdx rename to website/docs/language/settings/backends/gcs.html.md index c6a27e87b..1d869579e 100644 --- a/website/docs/language/settings/backends/gcs.mdx +++ b/website/docs/language/settings/backends/gcs.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Backend Type: gcs' -description: >- - Terraform can store the state remotely, making it easier to version and work - with in a team. +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. --- # gcs @@ -10,7 +11,7 @@ description: >- **Kind: Standard (with locking)** 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). -This backend also supports [state locking](/language/state/locking). The bucket must exist prior to configuring the backend. +This backend also supports [state locking](/docs/language/state/locking.html). The bucket must exist prior to configuring the backend. ~> **Warning!** It is highly recommended that you enable [Object Versioning](https://cloud.google.com/storage/docs/object-versioning) @@ -77,30 +78,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 new file mode 100644 index 000000000..e87903c44 --- /dev/null +++ b/website/docs/language/settings/backends/http.html.md @@ -0,0 +1,70 @@ +--- +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 + +**Kind: Standard (with optional locking)** + +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. + +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 deleted file mode 100644 index 0a4952786..000000000 --- a/website/docs/language/settings/backends/http.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -page_title: 'Backend Type: http' -description: Terraform can store state remotely at any valid HTTP endpoint. ---- - -# http - -**Kind: Standard (with optional locking)** - -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. - -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.mdx b/website/docs/language/settings/backends/index.html.md similarity index 83% rename from website/docs/language/settings/backends/index.mdx rename to website/docs/language/settings/backends/index.html.md index b2e416ed7..5a8a75359 100644 --- a/website/docs/language/settings/backends/index.mdx +++ b/website/docs/language/settings/backends/index.html.md @@ -1,21 +1,19 @@ --- -page_title: Backend Overview - Configuration Language -description: >- - A backend defines where and how Terraform performs operations, such as where - it stores state files. Learn about recommended backends and how backends work. -sidebar_title: Backend Overview +layout: "language" +page_title: "Backend Overview - Configuration Language" +description: "A backend defines where and how Terraform performs operations, such as where it stores state files. Learn about recommended backends and how backends work." --- # Backends Each Terraform configuration can specify a backend, which defines where -and how operations are performed, where [state](/language/state/) +and how operations are performed, where [state](/docs/language/state/index.html) snapshots are stored, etc. 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](/language/settings/backends/configuration) documents the form +- [Backend Configuration](/docs/language/settings/backends/configuration.html) 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, @@ -27,19 +25,19 @@ this section document how to configure and use backends. - If you are still learning how to use Terraform, we recommend using the default `local` backend, which requires no configuration. - If you and your team are using Terraform to manage meaningful infrastructure, - we recommend using the `remote` backend with [Terraform Cloud](/cloud-docs/) - or [Terraform Enterprise](/enterprise/). + we recommend using the `remote` backend with [Terraform Cloud](/docs/cloud/index.html) + or [Terraform Enterprise](/docs/enterprise/index.html). ## Where Backends are Used -Backend configuration is only used by [Terraform CLI](/cli/). +Backend configuration is only used by [Terraform CLI](/docs/cli/index.html). Terraform Cloud and Terraform Enterprise always use their own state storage when performing Terraform runs, so they ignore any backend block in the configuration. But since it's common to -[use Terraform CLI alongside Terraform Cloud](/cloud-docs/run/cli) -(and since certain state operations, like [tainting](/cli/commands/taint), +[use Terraform CLI alongside Terraform Cloud](/docs/cloud/run/cli.html) +(and since certain state operations, like [tainting](/docs/cli/commands/taint.html), can only be performed on the CLI), we recommend that Terraform Cloud users include a backend block in their configurations and configure the `remote` backend to use the relevant Terraform Cloud workspace(s). @@ -61,7 +59,7 @@ There are two areas of Terraform's behavior that are determined by the backend: ### State -Terraform uses persistent [state](/language/state/) data to keep track of +Terraform uses persistent [state](/docs/language/state/index.html) 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 diff --git a/website/docs/language/settings/backends/kubernetes.mdx b/website/docs/language/settings/backends/kubernetes.html.md similarity index 88% rename from website/docs/language/settings/backends/kubernetes.mdx rename to website/docs/language/settings/backends/kubernetes.html.md index cb475018b..71d80e24f 100644 --- a/website/docs/language/settings/backends/kubernetes.mdx +++ b/website/docs/language/settings/backends/kubernetes.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Backend Type: Kubernetes' -description: Terraform can store state remotely in Kubernetes and lock that state. +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. --- # kubernetes @@ -24,13 +27,14 @@ 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](/language/settings/backends/configuration#partial-configuration). +Note that for the access credentials we recommend using a [partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). + ## Example Referencing @@ -65,7 +69,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.mdx b/website/docs/language/settings/backends/local.html.md similarity index 71% rename from website/docs/language/settings/backends/local.mdx rename to website/docs/language/settings/backends/local.html.md index d2f5d18a0..f2829d3a4 100644 --- a/website/docs/language/settings/backends/local.mdx +++ b/website/docs/language/settings/backends/local.html.md @@ -1,8 +1,9 @@ --- -page_title: 'Backend Type: local' -description: >- - Terraform can store the state remotely, making it easier to version and work - with in a team. +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. --- # local @@ -38,9 +39,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 @@ -57,17 +58,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 @@ -77,7 +78,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](/language/state/workspaces), setting them +[multiple workspaces](/docs/language/state/workspaces.html), 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 @@ -89,7 +90,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](/language/settings/backends) and configure it +[select a different backend which supports remote state](./) 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 new file mode 100644 index 000000000..ef82e5602 --- /dev/null +++ b/website/docs/language/settings/backends/manta.html.md @@ -0,0 +1,52 @@ +--- +layout: "language" +page_title: "Backend Type: manta" +sidebar_current: "docs-backends-types-standard-manta" +description: |- + Terraform can store state in manta. +--- + +# manta + +**Kind: Standard (with locking within Manta)** + +Stores the state as an artifact in [Manta](https://www.joyent.com/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 deleted file mode 100644 index 1c1ecf469..000000000 --- a/website/docs/language/settings/backends/manta.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -page_title: 'Backend Type: manta' -description: Terraform can store state in manta. ---- - -# manta - -**Kind: Standard (with locking within Manta)** - -Stores the state as an artifact in [Manta](https://www.joyent.com/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.mdx b/website/docs/language/settings/backends/oss.html.md similarity index 91% rename from website/docs/language/settings/backends/oss.mdx rename to website/docs/language/settings/backends/oss.html.md index 03513d1c2..e2a0adc12 100644 --- a/website/docs/language/settings/backends/oss.mdx +++ b/website/docs/language/settings/backends/oss.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Backend Type: oss' -description: Terraform can store state remotely in OSS and lock that state with OSS. +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. --- # OSS @@ -35,11 +38,12 @@ 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](/language/state/remote-state-data). +source](/docs/language/state/remote-state-data.html). ```hcl terraform { @@ -74,48 +78,29 @@ 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. @@ -128,6 +113,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 new file mode 100644 index 000000000..934345f34 --- /dev/null +++ b/website/docs/language/settings/backends/pg.html.md @@ -0,0 +1,92 @@ +--- +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 + +**Kind: Standard (with locking)** + +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 deleted file mode 100644 index 870350ce6..000000000 --- a/website/docs/language/settings/backends/pg.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -page_title: 'Backend Type: pg' -description: Terraform can store state remotely in a Postgres database with locking. ---- - -# pg - -**Kind: Standard (with locking)** - -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.mdx b/website/docs/language/settings/backends/remote.html.md similarity index 77% rename from website/docs/language/settings/backends/remote.mdx rename to website/docs/language/settings/backends/remote.html.md index d9d150807..1c26169b8 100644 --- a/website/docs/language/settings/backends/remote.mdx +++ b/website/docs/language/settings/backends/remote.html.md @@ -1,8 +1,9 @@ --- -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. +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. --- # remote @@ -17,7 +18,7 @@ backend. This backend requires either a Terraform Cloud account on The remote backend stores Terraform state and may be used to run operations in Terraform Cloud. 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. +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. Terraform Cloud can also be used with local operations, in which case only state is stored in the Terraform Cloud backend. @@ -58,7 +59,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](/language/state/workspaces) + mapping multiple Terraform CLI [workspaces](/docs/language/state/workspaces.html) used in a single Terraform configuration to multiple Terraform Cloud workspaces. @@ -69,7 +70,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}`](/language/state/workspaces#current-workspace-interpolation) +Additionally, the [`${terraform.workspace}`](/docs/language/state/workspaces.html#current-workspace-interpolation) interpolation sequence should be removed from Terraform configurations that run remote operations against Terraform Cloud workspaces. The reason for this is that each Terraform Cloud workspace currently only uses the single `default` Terraform @@ -93,8 +94,8 @@ running any remote operations against them. ## Example Configurations -> **Note:** We recommend omitting the token from the configuration, and instead using -[`terraform login`](/cli/commands/login) or manually configuring -`credentials` in the [CLI config file](/cli/config/config-file#credentials). + [`terraform login`](/docs/cli/commands/login.html) or manually configuring + `credentials` in the [CLI config file](/docs/cli/config/config-file.html#credentials). ### Basic Configuration @@ -170,26 +171,26 @@ 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`](/cli/commands/login) or manually configuring + [`terraform login`](/docs/cli/commands/login.html) or manually configuring `credentials` in the - [CLI config file](/cli/config/config-file#credentials). -- `workspaces` - (Required) A block specifying which remote workspace(s) to use. + [CLI config file](/docs/cli/config/config-file.html#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. If omitted, only the default workspace can be used. This option conflicts with `name`. - + -> **Note:** You must use the `name` key when configuring a `terraform_remote_state` data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only intended for use when configuring an instance of the remote backend. @@ -200,37 +201,38 @@ 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](/cloud-docs/run/cli), +When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), 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.mdx b/website/docs/language/settings/backends/s3.html.md similarity index 96% rename from website/docs/language/settings/backends/s3.mdx rename to website/docs/language/settings/backends/s3.html.md index ea9d23326..e043701f4 100644 --- a/website/docs/language/settings/backends/s3.mdx +++ b/website/docs/language/settings/backends/s3.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Backend Type: s3' -description: Terraform can store state remotely in S3 and lock that state with DynamoDB. +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. --- # S3 @@ -34,7 +37,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](/language/settings/backends/configuration#partial-configuration). +[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). ### S3 Bucket Permissions @@ -105,7 +108,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](/language/state/remote-state-data). +source](/docs/language/state/remote-state-data.html). ```hcl data "terraform_remote_state" "network" { @@ -180,7 +183,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](/language/state/workspaces), 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](/docs/language/state/workspaces.html), the state path will be `/workspace_key_prefix/workspace_name/key` (see also the `workspace_key_prefix` configuration). The following configuration is optional: @@ -212,7 +215,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](/language/state/workspaces) to switch +[Terraform's workspaces feature](/docs/language/state/workspaces.html) to switch conveniently between multiple isolated deployments of the same configuration. Use this section as a starting-point for your approach, but note that @@ -318,7 +321,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`](/language/state/remote-state-data) +source such as [`terraform_remote_state`](/docs/language/state/remote-state-data.html) to avoid repeating these values. ### Creating and Selecting Workspaces diff --git a/website/docs/language/settings/backends/swift.mdx b/website/docs/language/settings/backends/swift.html.md similarity index 91% rename from website/docs/language/settings/backends/swift.mdx rename to website/docs/language/settings/backends/swift.html.md index 97bd33c26..8bc3d783a 100644 --- a/website/docs/language/settings/backends/swift.mdx +++ b/website/docs/language/settings/backends/swift.html.md @@ -1,6 +1,9 @@ --- -page_title: 'Backend Type: swift' -description: Terraform can store state remotely in Swift. +layout: "language" +page_title: "Backend Type: swift" +sidebar_current: "docs-backends-types-standard-swift" +description: |- + Terraform can store state remotely in Swift. --- # swift @@ -9,7 +12,7 @@ description: Terraform can store state remotely in Swift. Stores the state as an artifact in [Swift](http://docs.openstack.org/developer/swift/latest/). -~> 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. +~> 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. ## Example Configuration @@ -21,11 +24,10 @@ 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](/language/settings/backends/configuration#partial-configuration). +[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration). ## Data Source Configuration @@ -44,7 +46,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` @@ -53,7 +55,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. @@ -135,10 +137,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.mdx b/website/docs/language/settings/index.html.md similarity index 84% rename from website/docs/language/settings/index.mdx rename to website/docs/language/settings/index.html.md index 1f06019e6..5fa8949ac 100644 --- a/website/docs/language/settings/index.mdx +++ b/website/docs/language/settings/index.html.md @@ -1,9 +1,8 @@ --- -page_title: Terraform Settings - Configuration Language -description: >- - The terraform block allows you to configure Terraform behavior, including the - Terraform version, backend, and required providers. -sidebar_title: Terraform Settings +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, and required providers." --- # Terraform Settings @@ -35,20 +34,20 @@ following sections. The nested `backend` block configures which backend Terraform should use. The syntax and behavior of the `backend` block is described in [Backend -Configuration](/language/settings/backends/configuration). +Configuration](/docs/language/settings/backends/configuration.html). ## 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,](/language/expressions/version-constraints) which specifies which versions of Terraform +string,](/docs/language/expressions/version-constraints.html) 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](/language/modules/), each module can specify its own +When you use [child modules](/docs/language/modules/index.html), each module can specify its own version requirements. The requirements of all modules in the tree must be satisfied. @@ -59,7 +58,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](/language/providers/requirements) to manage +Use [the `required_providers` block](/docs/language/providers/requirements.html) to manage the expected versions for each provider you use. ## Specifying Provider Requirements @@ -81,7 +80,7 @@ terraform { } ``` -For more information, see [Provider Requirements](/language/providers/requirements). +For more information, see [Provider Requirements](/docs/language/providers/requirements.html). ## Experimental Language Features @@ -126,4 +125,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](/internals/provider-meta). +For more information, see [Provider Metadata](/docs/internals/provider-meta.html). diff --git a/website/docs/language/state/backends.mdx b/website/docs/language/state/backends.html.md similarity index 69% rename from website/docs/language/state/backends.mdx rename to website/docs/language/state/backends.html.md index a630dbd3e..da957173d 100644 --- a/website/docs/language/state/backends.mdx +++ b/website/docs/language/state/backends.html.md @@ -1,14 +1,15 @@ --- -page_title: 'Backends: State Storage and Locking' -description: >- - Backends are configured directly in Terraform files in the `terraform` - section. +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. --- # State Storage and Locking Backends are responsible for storing state and providing an API for -[state locking](/language/state/locking). State locking is optional. +[state locking](/docs/language/state/locking.html). State locking is optional. Despite the state being stored remotely, all Terraform commands such as `terraform console`, the `terraform state` operations, `terraform taint`, @@ -46,15 +47,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, @@ -63,12 +64,12 @@ prior to forcing the overwrite. ## State Locking -Backends are responsible for supporting [state locking](/language/state/locking) +Backends are responsible for supporting [state locking](/docs/language/state/locking.html) if possible. Not all backends support locking. The -[documentation for each backend](/language/settings/backends/) +[documentation for each backend](/docs/language/settings/backends/index.html) includes details on whether it supports locking or not. For more information on state locking, view the -[page dedicated to state locking](/language/state/locking). +[page dedicated to state locking](/docs/language/state/locking.html). diff --git a/website/docs/language/state/import.mdx b/website/docs/language/state/import.html.md similarity index 59% rename from website/docs/language/state/import.mdx rename to website/docs/language/state/import.html.md index 9646c32df..1334269e9 100644 --- a/website/docs/language/state/import.mdx +++ b/website/docs/language/state/import.html.md @@ -1,8 +1,9 @@ --- -page_title: 'State: Import Existing Resources' -description: >- - Terraform stores state which caches the known state of the world the last time - Terraform ran. +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. --- # Import Existing Resources @@ -11,4 +12,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](/cli/import/). +[pages dedicated to import](/docs/cli/import/index.html). diff --git a/website/docs/language/state/index.mdx b/website/docs/language/state/index.html.md similarity index 77% rename from website/docs/language/state/index.mdx rename to website/docs/language/state/index.html.md index 0b8dd3a80..67072eab2 100644 --- a/website/docs/language/state/index.mdx +++ b/website/docs/language/state/index.html.md @@ -1,8 +1,8 @@ --- -page_title: State -description: >- - An introduction to state, information that Terraform uses to map resources to - a configuration, track metadata, and improve performance. +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." --- # 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](/cli/commands/refresh) to update the state with the +[refresh](/docs/cli/commands/refresh.html) 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](/language/state/purpose). +function without state, please see the page [state purpose](/docs/language/state/purpose.html). ## 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](/cli/commands/state/) command to perform +[terraform state](/docs/cli/commands/state/index.html) 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](/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. +* [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. 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.mdx b/website/docs/language/state/locking.html.md similarity index 77% rename from website/docs/language/state/locking.mdx rename to website/docs/language/state/locking.html.md index c21b0aee1..739a4b8c4 100644 --- a/website/docs/language/state/locking.mdx +++ b/website/docs/language/state/locking.html.md @@ -1,13 +1,14 @@ --- -page_title: 'State: Locking' -description: >- - Terraform stores state which caches the known state of the world the last time - Terraform ran. +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. --- # State Locking -If supported by your [backend](/language/settings/backends/), Terraform will lock your +If supported by your [backend](/docs/language/settings/backends/index.html), Terraform will lock your state for all operations that could write state. This prevents others from acquiring the lock and potentially corrupting your state. @@ -21,12 +22,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](/language/settings/backends/) +[documentation for each backend](/docs/language/settings/backends/index.html) includes details on whether it supports locking or not. ## Force Unlock -Terraform has a [force-unlock command](/cli/commands/force-unlock) +Terraform has a [force-unlock command](/docs/cli/commands/force-unlock.html) 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.mdx b/website/docs/language/state/purpose.html.md similarity index 93% rename from website/docs/language/state/purpose.mdx rename to website/docs/language/state/purpose.html.md index 95e8f09d4..44bfef6d1 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.html.md @@ -1,10 +1,9 @@ --- -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. +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. --- # Purpose of Terraform State @@ -106,7 +105,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](/language/state/remote) is the recommended solution +[Remote state](/docs/language/state/remote.html) 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 new file mode 100644 index 000000000..10e514600 --- /dev/null +++ b/website/docs/language/state/remote-state-data.html.md @@ -0,0 +1,220 @@ +--- +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 deleted file mode 100644 index 1da4b1fb3..000000000 --- a/website/docs/language/state/remote-state-data.mdx +++ /dev/null @@ -1,219 +0,0 @@ ---- -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]: /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.mdx b/website/docs/language/state/remote.html.md similarity index 84% rename from website/docs/language/state/remote.mdx rename to website/docs/language/state/remote.html.md index f06dd22f0..998b47945 100644 --- a/website/docs/language/state/remote.mdx +++ b/website/docs/language/state/remote.html.md @@ -1,8 +1,9 @@ --- -page_title: 'State: Remote Storage' -description: >- - Terraform can store the state remotely, making it easier to version and work - with in a team. +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. --- # Remote State @@ -18,13 +19,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](/language/settings/backends/), +Remote state is implemented by a [backend](/docs/language/settings/backends/index.html), which you can configure in your configuration's root module. ## Delegation and Teamwork Remote state allows you to share -[output values](/language/values/outputs) with other configurations. +[output values](/docs/language/values/outputs.html) with other configurations. This allows your infrastructure to be decomposed into smaller components. Put another way, remote state also allows teams to share infrastructure @@ -38,7 +39,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](/language/state/remote-state-data). +[the `terraform_remote_state` data source](/docs/language/state/remote-state-data.html). While remote state can be a convenient, built-in mechanism for sharing data between configurations, you may prefer to use more general stores to @@ -52,7 +53,7 @@ another that consumes those values using ## Locking and Teamwork For fully-featured remote backends, Terraform can also use -[state locking](/language/state/locking) to prevent concurrent runs of +[state locking](/docs/language/state/locking.html) 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.mdx b/website/docs/language/state/sensitive-data.html.md similarity index 79% rename from website/docs/language/state/sensitive-data.mdx rename to website/docs/language/state/sensitive-data.html.md index 73cb17b98..49f5c1270 100644 --- a/website/docs/language/state/sensitive-data.mdx +++ b/website/docs/language/state/sensitive-data.html.md @@ -1,6 +1,9 @@ --- -page_title: 'State: Sensitive Data' -description: Sensitive data in Terraform state. +layout: "language" +page_title: "State: Sensitive Data" +sidebar_current: "docs-state-sensitive-data" +description: |- + Sensitive data in Terraform state. --- # Sensitive Data in State @@ -12,7 +15,7 @@ passwords. When using local state, state is stored in plain-text JSON files. -When using [remote state](/language/state/remote), state is only ever held in +When using [remote state](/docs/language/state/remote.html), 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. @@ -27,10 +30,10 @@ and some backends can be configured to encrypt the state data at rest. For example: -- [Terraform Cloud](/cloud-docs/) always encrypts state at rest and +- [Terraform Cloud](/docs/cloud/index.html) 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](/enterprise/) + be used to control access and track activity. [Terraform Enterprise](/docs/enterprise/index.html) 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.mdx b/website/docs/language/state/workspaces.html.md similarity index 84% rename from website/docs/language/state/workspaces.mdx rename to website/docs/language/state/workspaces.html.md index 2ab0c7976..a675d8edd 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.html.md @@ -1,15 +1,16 @@ --- -page_title: 'State: Workspaces' -description: >- - Workspaces allow the use of multiple states with a single configuration - directory. +layout: "language" +page_title: "State: Workspaces" +sidebar_current: "docs-state-workspaces" +description: |- + Workspaces allow the use of multiple states with a single configuration directory. --- # Workspaces -Each Terraform configuration has an associated [backend](/language/settings/backends/) +Each Terraform configuration has an associated [backend](/docs/language/settings/backends/index.html) that defines how operations are executed and where persistent data such as -[the Terraform state](/language/state/purpose) are +[the Terraform state](https://www.terraform.io/docs/language/state/purpose.html) are stored. The persistent data stored in the backend belongs to a _workspace_. Initially @@ -24,17 +25,17 @@ credentials. Multiple workspaces are currently supported by the following backends: -* [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) + * [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) 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 @@ -43,10 +44,10 @@ organizations that use Terraform. -> **Note**: The Terraform CLI workspace concept described in this document is different from but related to the Terraform Cloud -[workspace](/cloud-docs/workspaces/) concept. +[workspace](/docs/cloud/workspaces/index.html) concept. If you use multiple Terraform CLI workspaces in a single Terraform configuration and are migrating that configuration to Terraform Cloud, see this [migration -document](/cloud-docs/migrate/workspaces). +document](/docs/cloud/migrate/workspaces.html). ## Using Workspaces @@ -81,7 +82,7 @@ Within your Terraform configuration, you may include the name of the current workspace using the `${terraform.workspace}` interpolation sequence. This can be used anywhere interpolations are allowed. However, it should **not** be used in remote operations against Terraform Cloud workspaces. For an -explanation, see the [remote backend](/language/settings/backends/remote#workspaces) +explanation, see the [remote backend](/docs/language/settings/backends/remote.html#workspaces) document. Referencing the current workspace is useful for changing behavior based @@ -146,7 +147,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](/language/modules/develop/) to +Instead, use one or more [re-usable modules](/docs/language/modules/develop/index.html) 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 @@ -176,7 +177,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`](/language/state/remote-state-data) + [`terraform_remote_state`](/docs/language/state/remote-state-data.html) 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 @@ -194,9 +195,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](/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 +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 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.mdx b/website/docs/language/syntax/configuration.html.md similarity index 92% rename from website/docs/language/syntax/configuration.mdx rename to website/docs/language/syntax/configuration.html.md index d00e3b341..5dd06b28e 100644 --- a/website/docs/language/syntax/configuration.mdx +++ b/website/docs/language/syntax/configuration.html.md @@ -1,9 +1,8 @@ --- -page_title: Syntax - Configuration Language -description: >- - Key constructs of the native Terraform language syntax, including identifiers, - arguments, blocks, and comments. -sidebar_title: Syntax +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." --- # Configuration Syntax @@ -16,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](/language/syntax/json), which is harder for humans +[JSON syntax](/docs/language/syntax/json.html), 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 @@ -47,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](/language/expressions/), which allow the value to +[expressions](/docs/language/expressions/index.html), 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.mdx b/website/docs/language/syntax/index.html.md similarity index 53% rename from website/docs/language/syntax/index.mdx rename to website/docs/language/syntax/index.html.md index b3d7c1644..ccd8a67d9 100644 --- a/website/docs/language/syntax/index.mdx +++ b/website/docs/language/syntax/index.html.md @@ -1,9 +1,7 @@ --- -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. -sidebar_title: Syntax Overview +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." --- # Syntax @@ -12,13 +10,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](/language/syntax/configuration) describes the native +- [Configuration Syntax](/docs/language/syntax/configuration.html) describes the native grammar of the Terraform language. -- [JSON Configuration Syntax](/language/syntax/json) documents +- [JSON Configuration Syntax](/docs/language/syntax/json.html) 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](/language/syntax/style) documents some commonly +- [Style Conventions](/docs/language/syntax/style.html) documents some commonly accepted formatting guidelines for Terraform code. These conventions can be - enforced automatically with [`terraform fmt`](/cli/commands/fmt). + enforced automatically with [`terraform fmt`](/docs/cli/commands/fmt.html). diff --git a/website/docs/language/syntax/json.mdx b/website/docs/language/syntax/json.html.md similarity index 95% rename from website/docs/language/syntax/json.mdx rename to website/docs/language/syntax/json.html.md index 2527511fa..32a69578e 100644 --- a/website/docs/language/syntax/json.mdx +++ b/website/docs/language/syntax/json.html.md @@ -1,15 +1,14 @@ --- -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. -sidebar_title: JSON Configuration Syntax +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." --- # JSON Configuration Syntax Most Terraform configurations are written in -[the native Terraform language syntax](/language/syntax/configuration), which is designed to be +[the native Terraform language syntax](/docs/language/syntax/configuration.html), which is designed to be relatively easy for humans to read and update. Terraform also supports an alternative syntax that is JSON-compatible. This @@ -93,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](/language/expressions/) in the native syntax, the + [arbitrary expressions](/docs/language/expressions/index.html) 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 @@ -110,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](/language/expressions/), JSON values interpreted as expressions +[expression syntax](/docs/language/expressions/index.html), JSON values interpreted as expressions are mapped as follows: | JSON | Terraform Language Interpretation | @@ -122,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]: /language/expressions/strings#string-templates +[string template]: /docs/language/expressions/strings.html#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][] @@ -260,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.mdx b/website/docs/language/syntax/style.html.md similarity index 76% rename from website/docs/language/syntax/style.mdx rename to website/docs/language/syntax/style.html.md index 0e9701d40..bbbf090f7 100644 --- a/website/docs/language/syntax/style.mdx +++ b/website/docs/language/syntax/style.html.md @@ -1,9 +1,8 @@ --- -page_title: Style Conventions - Configuration Language -description: >- - Learn recommended formatting conventions for the Terraform language and a - command to automatically enforce them. -sidebar_title: Style Conventions +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." --- # Style Conventions @@ -15,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`](/cli/commands/fmt). +-> **Note**: You can enforce these conventions automatically by running [`terraform fmt`](/docs/cli/commands/fmt.html). * 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 @@ -40,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 { - # ... + network_interface { + # ... + } + + lifecycle { # meta-argument block last + create_before_destroy = true + } } - - 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 @@ -69,3 +68,4 @@ 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/docs/language/v1-compatibility-promises.mdx b/website/docs/language/v1-compatibility-promises.html.md similarity index 88% rename from website/docs/language/v1-compatibility-promises.mdx rename to website/docs/language/v1-compatibility-promises.html.md index 1c01f991d..a44a8b3f6 100644 --- a/website/docs/language/v1-compatibility-promises.mdx +++ b/website/docs/language/v1-compatibility-promises.html.md @@ -1,5 +1,7 @@ --- -page_title: Terraform v1.0 Compatibility Promises +layout: "language" +page_title: "Terraform v1.0 Compatibility Promises" +sidebar_current: "docs-v1-compatibility" description: |- From Terraform v1.0 onwards the Terraform team promises to preserve backward compatibility for most of the Terraform language and the primary CLI @@ -66,35 +68,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`](/language/resources/) and - [`data`](/language/data-sources/) blocks to +* [`resource`](/docs/language/resources/) and + [`data`](/docs/language/data-sources/) blocks to declare resources, including their nested block types `lifecycle`, `connection`, and `provisioner`, and their meta-argument `provider`. -* [`module`](/language/modules/syntax) blocks to call other modules, +* [`module`](/docs/language/modules/syntax.html) blocks to call other modules, and its meta-argument `providers`. -* The [`count`](/language/meta-arguments/count), - [`for_each`](/language/meta-arguments/for_each), and - [`depends_on`](/language/meta-arguments/depends_on) meta-arguments +* 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 in `resource`, `data`, and `module` blocks. -* [`provider`](/language/providers/configuration) blocks to configure +* [`provider`](/docs/language/providers/configuration.html) blocks to configure providers, and the `alias` meta-argument. -* [`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 +* [`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 for declaring the various kinds of named values in a module. -* [`terraform`](/language/settings/) blocks, including the nested - [`required_version`](/language/settings/#specifying-a-required-terraform-version) +* [`terraform`](/docs/language/settings/) blocks, including the nested + [`required_version`](/docs/language/settings/index.html#specifying-a-required-terraform-version) and - [`required_providers`](/language/providers/requirements#requiring-providers) + [`required_providers`](/docs/language/providers/requirements.html#requiring-providers) arguments, and nested - [`backend`](/language/settings/backends/configuration#using-a-backend-block) + [`backend`](/docs/language/settings/backends/configuration.html#using-a-backend-block) blocks for backend configuration. We also intend to keep compatibility with all -[expression operators](/language/expressions/) and -[built-in functions](/language/functions/), with the exception of +[expression operators](/docs/language/expressions/) and +[built-in functions](/docs/language/functions/), with the exception of references to -[`terraform.workspace`](/language/expressions/references#terraform-workspace), +[`terraform.workspace`](/docs/language/expressions/references.html#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 @@ -102,17 +104,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. - 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. + 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 @@ -190,18 +192,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](/internals/provider-registry-protocol), +[the Provider Registry Protocol](/docs/internals/provider-registry-protocol.html), 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](/cli/config/config-file#filesystem_mirror) +[local filesystem directories](/docs/cli/config/config-file.html#filesystem_mirror) (filesystem mirrors) and from -[network mirrors](/cli/config/config-file#network_mirror) -(implementing [the Provider Mirror Protocol](/internals/provider-network-mirror-protocol). +[network mirrors](/docs/cli/config/config-file.html#network_mirror) +(implementing [the Provider Mirror Protocol](/docs/internals/provider-network-mirror-protocol.html). All Terraform v1.x releases will remain compatible with those installation methods, including -[the Implied Local Mirror Directories](/cli/config/config-file#implied-local-mirror-directories). +[the Implied Local Mirror Directories](/docs/cli/config/config-file.html#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 @@ -237,11 +239,11 @@ and of Terraform itself. ### Module Installation Methods Terraform supports installing child modules from a number of different -[module source types](/language/modules/sources). We will continue +[module source types](/docs/language/modules/sources.html). 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](/internals/module-registry-protocol) +[the Module Registry Protocol](/docs/internals/module-registry-protocol.html) version 1. All Terraform v1.x releases will remain compatible with correct implementations of that protocol. @@ -284,7 +286,6 @@ 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` @@ -387,7 +388,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`](/cli/commands/init) +* [`init`](/docs/cli/commands/init.html) * `-backend=false` * `-backend-config=FILE` * `-backend-config="KEY=VALUE"` @@ -399,10 +400,10 @@ Any natural-language output from these commands might change in later releases. * `-plugin-dir=DIR` * `-reconfigure` * `-upgrade` -* [`validate`](/cli/commands/validate) +* [`validate`](/docs/cli/commands/validate.html) * `-json` * `-no-color` -* [`plan`](/cli/commands/plan) +* [`plan`](/docs/cli/commands/plan.html) * `-compact-warnings` * `-destroy` * `-detailed-exitcode` @@ -419,7 +420,7 @@ Any natural-language output from these commands might change in later releases. * `-target=ADDRESS` * `-var 'NAME=VALUE'` * `-var-file=FILE` -* [`apply`](/cli/commands/apply) +* [`apply`](/docs/cli/commands/apply.html) * `-auto-approve` * `-compact-warnings` * `-lock=false` @@ -434,53 +435,53 @@ Any natural-language output from these commands might change in later releases. * `-target=ADDRESS` * `-var 'NAME=VALUE'` * `-var-file=FILE` -* [`show`](/cli/commands/show) +* [`show`](/docs/cli/commands/show.html) * `-no-color` * `-json` * (both with and without a plan file) -* [`providers`](/cli/commands/providers) (with no subcommand) -* [`providers lock`](/cli/commands/providers/lock) +* [`providers`](/docs/cli/commands/providers.html) (with no subcommand) +* [`providers lock`](/docs/cli/commands/providers/lock.html) * `-fs-mirror=PATH` * `-net-mirror=URL` * `-platform=OS_ARCH` -* [`providers mirror`](/cli/commands/providers/mirror) +* [`providers mirror`](/docs/cli/commands/providers/mirror.html) * `-platform=OS_ARCH` -* [`providers schema`](/cli/commands/providers/schema) +* [`providers schema`](/docs/cli/commands/providers/schema.html) * `-json` -* [`fmt`](/cli/commands/fmt) +* [`fmt`](/docs/cli/commands/fmt.html) * `-list=false` * `-write=false` * `-diff` * `-recursive` * `-check` -* [`version`](/cli/commands/version) +* [`version`](/docs/cli/commands/version.html) * `-json` -* [`output`](/cli/commands/output) +* [`output`](/docs/cli/commands/output.html) * `-no-color` * `-json` * `-raw` -* [`taint`](/cli/commands/taint) +* [`taint`](/docs/cli/commands/taint.html) * `-allow-missing` * `-lock=false` * `-lock-timeout=DURATION` * `-ignore-remote-version` -* [`untaint`](/cli/commands/untaint) +* [`untaint`](/docs/cli/commands/untaint.html) * `-allow-missing` * `-lock=false` * `-lock-timeout=DURATION` * `-ignore-remote-version` -* [`force-unlock`](/cli/commands/force-unlock) +* [`force-unlock`](/docs/cli/commands/force-unlock.html) * `-force` -* [`state list`](/cli/commands/state/list) +* [`state list`](/docs/cli/commands/state/list.html) * `-id=ID` -* [`state pull`](/cli/commands/state/pull) -* [`state push`](/cli/commands/state/push) +* [`state pull`](/docs/cli/commands/state/pull.html) +* [`state push`](/docs/cli/commands/state/push.html) * `-force` * `-lock=false` * `-lock-timeout=DURATION` -* [`state show`](/cli/commands/state/show) +* [`state show`](/docs/cli/commands/state/show.html) * `-ignore-remote-version` -* [`login`](/cli/commands/login) +* [`login`](/docs/cli/commands/login.html) 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 new file mode 100644 index 000000000..3074f965c --- /dev/null +++ b/website/docs/language/values/index.html.md @@ -0,0 +1,19 @@ +--- +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 deleted file mode 100644 index d271492c3..000000000 --- a/website/docs/language/values/index.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -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.mdx b/website/docs/language/values/locals.html.md similarity index 74% rename from website/docs/language/values/locals.mdx rename to website/docs/language/values/locals.html.md index 41813cc21..a487698bf 100644 --- a/website/docs/language/values/locals.mdx +++ b/website/docs/language/values/locals.html.md @@ -1,26 +1,25 @@ --- -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. -sidebar_title: Local Values +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." --- # 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](/language/expressions/), +A local value assigns a name to an [expression](/docs/language/expressions/index.html), 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](/language/values/variables) are like function arguments. -- [Output values](/language/values/outputs) are like function return values. +- [Input variables](./variables.html) are like function arguments. +- [Output values](./outputs.html) 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" @@ -60,7 +59,7 @@ locals { ## Using Local Values Once a local value is declared, you can reference it in -[expressions](/language/expressions/) as `local.`. +[expressions](/docs/language/expressions/index.html) 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.mdx b/website/docs/language/values/outputs.html.md similarity index 87% rename from website/docs/language/values/outputs.mdx rename to website/docs/language/values/outputs.html.md index 2cd32a977..824929fd5 100644 --- a/website/docs/language/values/outputs.mdx +++ b/website/docs/language/values/outputs.html.md @@ -1,7 +1,9 @@ --- -page_title: Output Values - Configuration Language -description: Output values are the return values of a Terraform module. -sidebar_title: Output Values +layout: "language" +page_title: "Output Values - Configuration Language" +sidebar_current: "docs-config-outputs" +description: |- + Output values are the return values of a Terraform module. --- # Output Values @@ -11,8 +13,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: @@ -20,9 +22,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](/language/state/remote), root module outputs can be +- When using [remote state](/docs/language/state/remote.html), root module outputs can be accessed by other configurations via a - [`terraform_remote_state` data source](/language/state/remote-state-data). + [`terraform_remote_state` data source](/docs/language/state/remote-state-data.html). Resource instances managed by Terraform each export attributes whose values can be used elsewhere in configuration. Output values are a way to expose some @@ -43,11 +45,11 @@ output "instance_ip_addr" { ``` The label immediately after the `output` keyword is the name, which must be a -valid [identifier](/language/syntax/configuration#identifiers). In a root module, this name is +valid [identifier](/docs/language/syntax/configuration.html#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](/language/expressions/) +The `value` argument takes an [expression](/docs/language/expressions/index.html) 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 @@ -154,10 +156,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](/language/state/), +Terraform will still record sensitive values in the [state](/docs/language/state/index.html), 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_](/language/state/sensitive-data). +[_Sensitive Data in State_](/docs/language/state/sensitive-data.html). @@ -173,7 +175,7 @@ correctly determine the dependencies between resources defined in different modules. Just as with -[resource dependencies](/language/resources/behavior#resource-dependencies), +[resource dependencies](/docs/language/resources/behavior.html#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.mdx b/website/docs/language/values/variables.html.md similarity index 87% rename from website/docs/language/values/variables.mdx rename to website/docs/language/values/variables.html.md index 848ec9661..a983192be 100644 --- a/website/docs/language/values/variables.mdx +++ b/website/docs/language/values/variables.html.md @@ -1,9 +1,8 @@ --- -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. -sidebar_title: Input Variables +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." --- # Input Variables @@ -16,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](/language/modules/), +When you declare them in [child modules](/docs/language/modules/index.html), 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](/language/values/outputs) are like function return values. -* [Local values](/language/values/locals) are like a function's temporary local variables. +- 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. -> **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](/language/expressions/)). +[expression](/docs/language/expressions/index.html)). ## Declaring an Input Variable @@ -69,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](/language/syntax/configuration#identifiers) +The name of a variable can be any valid [identifier](/docs/language/syntax/configuration.html#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](/language/modules/syntax), and cannot be +[module configuration blocks](/docs/language/modules/syntax.html), 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 @@ -102,7 +101,7 @@ configuration. [inpage-type]: #type-constraints The `type` argument in a `variable` block allows you to restrict the -[type of value](/language/expressions/types) that will be accepted as +[type of value](/docs/language/expressions/types.html) that will be accepted as the value for a variable. If no type constraint is set then a value of any type is accepted. @@ -129,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](/language/expressions/types). +[Type Constraints](/docs/language/expressions/types.html). If both the `type` and `default` arguments are specified, the given default value must be convertible to the specified type. @@ -183,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](/language/functions/can) to detect such errors. For example: +[the `can` function](/docs/language/functions/can.html) to detect such errors. For example: ```hcl variable "image_id" { @@ -218,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](/language/state/), +Terraform will still record sensitive values in the [state](/docs/language/state/index.html), 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_](/language/state/sensitive-data). +[_Sensitive Data in State_](/docs/language/state/sensitive-data.html). Declare a variable as sensitive by setting the `sensitive` argument to `true`: @@ -272,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](/plugin/sdkv2/best-practices/sensitive-state#using-the-sensitive-flag), +[declare an attribute as sensitive](/docs/extend/best-practices/sensitive-state.html#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](/language/expressions/references#sensitive-resource-attributes). +[Sensitive Resource Attributes](/docs/language/expressions/references.html#sensitive-resource-attributes). If you use a sensitive value from as part of an -[output value](/language/values/outputs) then Terraform will require +[output value](/docs/language/values/outputs.html) then Terraform will require you to also mark the output value itself as sensitive, to confirm that you intended to export it. @@ -335,10 +334,11 @@ 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](/language/expressions/) as `var.`, +within [expressions](/docs/language/expressions/index.html) as `var.`, where `` matches the label given in the declaration block: -> **Note:** Input variables are _created_ by a `variable` block, but you @@ -359,7 +359,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](/cloud-docs/workspaces/variables). +* [In a Terraform Cloud workspace](/docs/cloud/workspaces/variables.html). * Individually, with the `-var` command line option. * In variable definitions (`.tfvars`) files, either specified on the command line or automatically loaded. @@ -368,7 +368,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_](/language/modules/). +[_Modules_](/docs/language/modules/index.html). ### Variables on the Command Line @@ -384,7 +384,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](/cli/commands/plan#input-variables-on-the-command-line). +[Input Variables on the Command Line](/docs/cli/commands/plan.html#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 +403,7 @@ terraform apply -var-file="testing.tfvars" ``` -> **Note:** This is how Terraform Cloud passes -[workspace variables](/cloud-docs/workspaces/variables) to Terraform. +[workspace variables](/docs/cloud/workspaces/variables.html) to Terraform. A variable definitions file uses the same basic syntax as Terraform language files, but consists only of variable name assignments: @@ -457,7 +457,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](/language/expressions/types#literal-expressions) +[literal expressions](/docs/language/expressions/types.html#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 +483,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](/cli/commands/plan#input-variables-on-the-command-line). +[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line). ### Values for Undeclared Variables @@ -516,7 +516,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`](/cli/commands/plan#compact-warnings) +you can use the [`-compact-warnings`](https://www.terraform.io/docs/cli/commands/plan.html#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/core-workflow.mdx b/website/guides/core-workflow.html.md similarity index 93% rename from website/guides/core-workflow.mdx rename to website/guides/core-workflow.html.md index 982b026a8..2cd010ee5 100644 --- a/website/guides/core-workflow.mdx +++ b/website/guides/core-workflow.html.md @@ -1,7 +1,9 @@ --- -page_title: The Core Terraform Workflow - Guides -description: 'An overview of how individuals, teams, and organizations can use Terraform. ' -sidebar_title: The Core Terraform Workflow +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. --- # The Core Terraform Workflow @@ -9,8 +11,8 @@ sidebar_title: The Core Terraform Workflow The core Terraform workflow has three steps: 1. **Write** - Author infrastructure as code. -1. **Plan** - Preview changes before applying. -1. **Apply** - Provision reproducible infrastructure. +2. **Plan** - Preview changes before applying. +3. **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 @@ -182,7 +184,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](/img/docs/manually-pasted-plan-output.png) +![Screenshot of Pull Request with manually posted Terraform plan output](guides/core-workflow/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 @@ -231,7 +233,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](/language/settings/backends/remote). +Terraform Cloud via the ["remote" backend](/docs/language/settings/backends/remote.html). ``` terraform { @@ -281,14 +283,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](/img/docs/pull-request.png) +![Screenshot of Pull Request with resource changes in the status update](guides/core-workflow/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](/img/docs/pr-plan.png) +![Screenshot of Pull Request run in Terraform Cloud](guides/core-workflow/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. @@ -298,17 +300,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](/img/docs/concrete-plan.png) +![Screenshot of concrete plan](guides/core-workflow/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](/img/docs/plan-comments.png) +![Screenshot of back-and-forth in Terraform Cloud comments](guides/core-workflow/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](/img/docs/in-progress-apply.png) +![Screenshot of in-progress Apply](guides/core-workflow/in-progress-apply.png) Contact us at with any questions or feedback. +-> Contact us at technologypartners@hashicorp.com with any questions or feedback. diff --git a/website/guides/terraform-provider-development-program.mdx b/website/guides/terraform-provider-development-program.html.md similarity index 56% rename from website/guides/terraform-provider-development-program.mdx rename to website/guides/terraform-provider-development-program.html.md index 5b0ec0edd..59d5ffc64 100644 --- a/website/guides/terraform-provider-development-program.mdx +++ b/website/guides/terraform-provider-development-program.html.md @@ -1,9 +1,8 @@ --- -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. +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. --- # Terraform Provider Development Program @@ -12,9 +11,10 @@ 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](/img/docs/verified-card.png) +![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. --> **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,41 +24,72 @@ 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](/registry/providers/publishing) 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](https://www.terraform.io/docs/registry/providers/publishing.html) 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](/img/docs/program-steps.png) +![Provider Development Process](/assets/images/docs/program-steps.png) 1. **Apply**: Initial contact between vendor and HashiCorp -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. +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. Apply -Please begin by completing our HashiCorp Technology Partner application: +Please begin by completing our HashiCorp Technology Partner application: https://www.hashicorp.com/ecosystem/become-a-partner/#technology 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](/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). +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). 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 | | [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) | +| 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 | -> **Important:** All Terraform providers listed as Verified must contain one of the following open source licenses: @@ -78,13 +109,14 @@ 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 , 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 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. To export your public key in ASCII-armor format, use the following command: @@ -94,7 +126,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](/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 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 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/intro/index.mdx b/website/intro/index.html.markdown similarity index 76% rename from website/intro/index.mdx rename to website/intro/index.html.markdown index 898bb69d7..8327f5e10 100644 --- a/website/intro/index.mdx +++ b/website/intro/index.html.markdown @@ -1,8 +1,9 @@ --- -page_title: Introduction -description: >- - Learn what Terraform is, what problems it can solve, and how it compares to - existing software. +layout: "intro" +page_title: "Introduction" +sidebar_current: "what" +description: |- + Learn what Terraform is, what problems it can solve, and how it compares to existing software. --- # Introduction to Terraform @@ -11,13 +12,15 @@ Terraform is an infrastructure as code (IaC) tool that allows you to build, chan Below, HashiCorp co-founder and CTO Armon Dadgar describes how Terraform can help solve common infrastructure challenges. - + + ## Key Features ### Infrastructure as Code -You describe your infrastructure using Terraform's high-level [configuration language](/language/) in human-readable, declarative configuration files. This allows you to create a blueprint that you can version, share, and reuse. +You describe your infrastructure using Terraform's high-level [configuration language](/docs/language/index.html) in human-readable, declarative configuration files. This allows you to create a blueprint that you can version, share, and reuse. ### Execution Plans @@ -31,8 +34,10 @@ Terraform builds a resource graph and creates or modifies non-dependent resource Terraform can apply complex changesets to your infrastructure with minimal human interaction. When you update configuration files, Terraform determines what changed and creates incremental execution plans that respect dependencies. + + ## Next Steps -- Learn about common [Terraform use cases](/intro/use-cases). -- Learn [how Terraform compares to and complements other tools](/intro/vs/). +- Learn about common [Terraform use cases](/intro/use-cases.html). +- Learn [how Terraform compares to and complements other tools](/intro/vs/index.html). - Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started) tutorials on HashiCorp Learn. diff --git a/website/intro/use-cases.mdx b/website/intro/use-cases.html.markdown similarity index 96% rename from website/intro/use-cases.mdx rename to website/intro/use-cases.html.markdown index 411fec47c..9ef2aa82c 100644 --- a/website/intro/use-cases.mdx +++ b/website/intro/use-cases.html.markdown @@ -1,13 +1,14 @@ --- -page_title: Use Cases -description: >- - Learn common use cases for Terraform including managing Heroku apps, - self-service clusters, and multi-cloud deployments. +layout: "intro" +page_title: "Use Cases" +sidebar_current: "use-cases" +description: |- + Learn common use cases for Terraform including managing Heroku apps, self-service clusters, and multi-cloud deployments. --- # Use Cases -This page lists a subset of use cases for [Terraform](/intro/). +This page lists a subset of use cases for [Terraform](/intro/index.html). ## Multi-Cloud Deployment diff --git a/website/intro/vs/boto.mdx b/website/intro/vs/boto.html.markdown similarity index 81% rename from website/intro/vs/boto.mdx rename to website/intro/vs/boto.html.markdown index de008b8dc..524893fef 100644 --- a/website/intro/vs/boto.mdx +++ b/website/intro/vs/boto.html.markdown @@ -1,6 +1,9 @@ --- -page_title: 'Terraform vs. Boto, Fog, etc.' -description: 'How Terraform compares to cloud provider client libraries like Boto and Fog. ' +layout: "intro" +page_title: "Terraform vs. Boto, Fog, etc." +sidebar_current: "vs-other-boto" +description: |- + How Terraform compares to cloud provider client libraries like Boto and Fog. --- # Terraform vs. Boto, Fog, etc. diff --git a/website/intro/vs/chef-puppet.mdx b/website/intro/vs/chef-puppet.html.markdown similarity index 80% rename from website/intro/vs/chef-puppet.mdx rename to website/intro/vs/chef-puppet.html.markdown index c846ffac7..128ceac47 100644 --- a/website/intro/vs/chef-puppet.mdx +++ b/website/intro/vs/chef-puppet.html.markdown @@ -1,8 +1,9 @@ --- -page_title: 'Terraform vs. Chef, Puppet, etc.' -description: >- - How Terraform compares to configuration management tools like Chef and - Puppet. +layout: "intro" +page_title: "Terraform vs. Chef, Puppet, etc." +sidebar_current: "vs-other-chef" +description: |- + How Terraform compares to configuration management tools like Chef and Puppet. --- # Terraform vs. Chef, Puppet, etc. diff --git a/website/intro/vs/cloudformation.mdx b/website/intro/vs/cloudformation.html.markdown similarity index 87% rename from website/intro/vs/cloudformation.mdx rename to website/intro/vs/cloudformation.html.markdown index a677ec089..def42de5b 100644 --- a/website/intro/vs/cloudformation.mdx +++ b/website/intro/vs/cloudformation.html.markdown @@ -1,9 +1,9 @@ --- -page_title: 'Terraform vs. CloudFormation, Heat, etc.' -description: >- - How Terraform compares to other infrastructure as code tools like - CloudFormation and Heat. Terraform can simultaneously manage multiple cloud - providers (AWS, OpenStack, etc.) and services (Cloudflare, DNSimple, etc.). +layout: "intro" +page_title: "Terraform vs. CloudFormation, Heat, etc." +sidebar_current: "vs-other-cloudformation" +description: |- + How Terraform compares to other infrastructure as code tools like CloudFormation and Heat. Terraform can simultaneously manage multiple cloud providers (AWS, OpenStack, etc.) and services (Cloudflare, DNSimple, etc.). --- # Terraform vs. CloudFormation, Heat, etc. diff --git a/website/intro/vs/custom.mdx b/website/intro/vs/custom.html.markdown similarity index 88% rename from website/intro/vs/custom.mdx rename to website/intro/vs/custom.html.markdown index 8b381c6df..94b25a2fe 100644 --- a/website/intro/vs/custom.mdx +++ b/website/intro/vs/custom.html.markdown @@ -1,8 +1,9 @@ --- -page_title: Terraform vs. Custom Solutions -description: >- - Why Terraform is easier to use and maintain than custom, internal - infrastructure solutions. +layout: "intro" +page_title: "Terraform vs. Custom Solutions" +sidebar_current: "vs-other-custom" +description: |- + Why Terraform is easier to use and maintain than custom, internal infrastructure solutions. --- # Terraform vs. Custom Solutions diff --git a/website/intro/vs/index.mdx b/website/intro/vs/index.html.markdown similarity index 80% rename from website/intro/vs/index.mdx rename to website/intro/vs/index.html.markdown index bc0d6dc9c..462e326fb 100644 --- a/website/intro/vs/index.mdx +++ b/website/intro/vs/index.html.markdown @@ -1,6 +1,9 @@ --- -page_title: Terraform vs. Other Software -description: An overview of how Terraform compares to other software and tools. +layout: "intro" +page_title: "Terraform vs. Other Software" +sidebar_current: "vs-other" +description: |- + An overview of how Terraform compares to other software and tools. --- # Terraform vs. Other Software