diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index 373b2f0456..31b72e0c87 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -22,5 +22,5 @@ TACOS user account. For details, see: -- [The `opentf login` command](/opentf/cli/commands/login) -- [The `opentf logout` command](/opentf/cli/commands/logout) +- [The `opentf login` command](/docs/cli/commands/login) +- [The `opentf logout` command](/docs/cli/commands/logout) diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx index 2cae6e21f9..0e23b6aaf5 100644 --- a/website/docs/cli/cloud/index.mdx +++ b/website/docs/cli/cloud/index.mdx @@ -14,7 +14,7 @@ Workspaces can also be configured for local execution, in which case the cloud b ## Documentation Summary -- [Cloud Backend Settings](/opentf/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable cloud backend support. -- [Initializing and Migrating](/opentf/cli/cloud/migrating) describes +- [Cloud Backend Settings](/docs/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable cloud backend support. +- [Initializing and Migrating](/docs/cli/cloud/migrating) describes how to start using the cloud backend with a working directory that already has state data. -- [Command Line Arguments](/opentf/cli/cloud/command-line-arguments) lists the OpenTF command flags that are specific to using OpenTF with the cloud backend. +- [Command Line Arguments](/docs/cli/cloud/command-line-arguments) lists the OpenTF command flags that are specific to using OpenTF with the cloud backend. diff --git a/website/docs/cli/cloud/migrating.mdx b/website/docs/cli/cloud/migrating.mdx index f97d94ab3a..848cdaf527 100644 --- a/website/docs/cli/cloud/migrating.mdx +++ b/website/docs/cli/cloud/migrating.mdx @@ -6,7 +6,7 @@ description: >- # Initializing and Migrating -After [configuring cloud backend settings](/opentf/cli/cloud/settings) for a working directory, you must run `opentf init` to finish setting up. If the working directory has no existing OpenTF state, you can start using OpenTF with a cloud backend right away. +After [configuring cloud backend settings](/docs/cli/cloud/settings) for a working directory, you must run `opentf init` to finish setting up. If the working directory has no existing OpenTF state, you can start using OpenTF with a cloud backend right away. When you run `opentf init` in the following scenarios, OpenTF will ask you to choose whether or not to migrate state from any existing workspaces. @@ -17,7 +17,7 @@ When you run `opentf init` in the following scenarios, OpenTF will ask you to ch ## Migrating from Local State or State Backends If the working directory already has state data available (using either local state or a [state -backend](/opentf/language/settings/backends/configuration)), OpenTF asks your approval to migrate +backend](/docs/language/settings/backends/configuration)), OpenTF asks your approval to migrate that state to the cloud backend. You will need permission to manage workspaces in the destination cloud backend organization. This process is interactive and self-documenting, and resembles moving between state backends. @@ -36,7 +36,7 @@ according to a pattern relative to their existing names. This can indicate the f If the working directory was already connected to a cloud backend with the `remote` backend, OpenTF can continue using the same cloud backend workspaces. The local names shown for those workspaces will change to match their remote names. -The [`remote` backend](/opentf/language/settings/backends/remote) was the primary implementation for cloud backends for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for OpenTF and Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. +The [`remote` backend](/docs/language/settings/backends/remote) was the primary implementation for cloud backends for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for OpenTF and Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. ### Block Replacement diff --git a/website/docs/cli/cloud/settings.mdx b/website/docs/cli/cloud/settings.mdx index 69337636df..a08e162244 100644 --- a/website/docs/cli/cloud/settings.mdx +++ b/website/docs/cli/cloud/settings.mdx @@ -11,7 +11,7 @@ OpenTF CLI can integrate with a cloud backend, acting as a client for it. You must configure the following settings to use the cloud backend for a particular working directory: - Provide credentials to access the cloud backend, preferably by using the - [`opentf login`](/opentf/cli/commands/login) command. + [`opentf login`](/docs/cli/commands/login) command. - Add a `cloud` block to the directory's OpenTF configuration, to specify which organization and workspace(s) to use. - Optionally, use a `.terraformignore` file to specify files that shouldn't be @@ -42,7 +42,7 @@ terraform { The `cloud` block also has some special restrictions: - A configuration can only provide one `cloud` block. -- A `cloud` block cannot be used with [state backends](/opentf/language/settings/backends/configuration). +- A `cloud` block cannot be used with [state backends](/docs/language/settings/backends/configuration). A configuration can use one or the other, but not both. - A `cloud` block cannot refer to named values (like input variables, locals, or data source attributes). @@ -66,7 +66,7 @@ The `cloud` block supports the following configuration arguments: - `tags` - (Optional) A set of cloud backend workspace tags. You will be able to use this working directory with any workspaces that have all of the specified tags, - and can use [the `opentf workspace` commands](/opentf/cli/workspaces) + and can use [the `opentf workspace` commands](/docs/cli/workspaces) to switch between them or create new workspaces. New workspaces will automatically have the specified tags. This option conflicts with `name`. @@ -81,9 +81,9 @@ The `cloud` block supports the following configuration arguments: - `token` - (Optional) The token used to authenticate with the cloud backend. We recommend omitting the token from the configuration, and instead using - [`opentf login`](/opentf/cli/commands/login) or manually configuring + [`opentf login`](/docs/cli/commands/login) or manually configuring `credentials` in the - [CLI config file](/opentf/cli/config/config-file#credentials). + [CLI config file](/docs/cli/config/config-file#credentials). ### Environment Variables @@ -99,7 +99,7 @@ Use the following environment variables to configure the `cloud` block: - `TF_CLOUD_PROJECT` - The name of a cloud backend project. OpenTF reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence. -- `TF_WORKSPACE` - The name of a single cloud backend workspace. OpenTF reads this when `workspaces` is omitted from the `cloud` block. The cloud backend will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/opentf/cli/config/environment-variables#tf_workspace) for details. +- `TF_WORKSPACE` - The name of a single cloud backend workspace. OpenTF reads this when `workspaces` is omitted from the `cloud` block. The cloud backend will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/docs/cli/config/environment-variables#tf_workspace) for details. ## Excluding Files from Upload with .terraformignore diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 59860f4aef..a5800bbd94 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -7,7 +7,7 @@ description: >- # Writing and Modifying OpenTF Code -The [OpenTF language](/opentf/language) is OpenTF's primary +The [OpenTF language](/docs/language) is OpenTF's primary user interface, and all of OpenTF's workflows rely on configurations written in the OpenTF language. @@ -15,17 +15,17 @@ OpenTF CLI includes several commands to make OpenTF code more convenient to work with. Integrating these commands into your editing workflow can potentially save you time and effort. -- [The `opentf console` command](/opentf/cli/commands/console) starts an +- [The `opentf console` command](/docs/cli/commands/console) starts an interactive shell for evaluating OpenTF - [expressions](/opentf/language/expressions), which can be a faster way + [expressions](/docs/language/expressions), which can be a faster way to verify that a particular resource argument results in the value you expect. -- [The `opentf fmt` command](/opentf/cli/commands/fmt) rewrites OpenTF +- [The `opentf fmt` command](/docs/cli/commands/fmt) rewrites OpenTF 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 `opentf validate` command](/opentf/cli/commands/validate) validates the +- [The `opentf validate` command](/docs/cli/commands/validate) validates the syntax and arguments of the OpenTF 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 diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index 3f8c8151b6..5164e97097 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -18,8 +18,8 @@ Usage: `opentf apply [options] [plan file]` ### Automatic Plan Mode -When you run `opentf apply` without passing a saved plan file, OpenTF automatically creates a new execution plan as if you had run [`opentf plan`](/opentf/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/opentf/cli/commands/plan#planning-modes) and -[planning options](/opentf/cli/commands/plan#planning-options) to customize how OpenTF will create the plan. +When you run `opentf apply` without passing a saved plan file, OpenTF automatically creates a new execution plan as if you had run [`opentf plan`](/docs/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/docs/cli/commands/plan#planning-modes) and +[planning options](/docs/cli/commands/plan#planning-options) to customize how OpenTF will create the plan. You can pass the `-auto-approve` option to instruct OpenTF to apply the plan without asking for confirmation. @@ -27,9 +27,9 @@ You can pass the `-auto-approve` option to instruct OpenTF to apply the plan wit ### Saved Plan Mode -When you pass a [saved plan file](/opentf/cli/commands/plan#out-filename) to `opentf apply`, OpenTF takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when running OpenTF in automation. +When you pass a [saved plan file](/docs/cli/commands/plan#out-filename) to `opentf apply`, OpenTF takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when running OpenTF in automation. -Use [`opentf show`](/opentf/cli/commands/show) to inspect a saved plan file before applying it. +Use [`opentf show`](/docs/cli/commands/show) to inspect a saved plan file before applying it. When using a saved plan, you cannot specify any additional planning modes or options. These options only affect OpenTF's decisions about which actions to take, and the plan file contains the final results of those @@ -39,8 +39,8 @@ decisions. Without a saved plan file, `opentf apply` supports all planning modes and planning options available for `opentf plan`. -- **[Planning Modes](/opentf/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update OpenTF state and root module output values. -- **[Planning Options](/opentf/cli/commands/plan#planning-options):** These include specifying which resource instances OpenTF should replace, setting OpenTF input variables, etc. +- **[Planning Modes](/docs/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update OpenTF state and root module output values. +- **[Planning Options](/docs/cli/commands/plan#planning-options):** These include specifying which resource instances OpenTF should replace, setting OpenTF input variables, etc. ### Apply Options @@ -82,22 +82,22 @@ The following options change how the apply command executes and reports on the a rendered by a system that cannot interpret terminal formatting. - `-parallelism=n` - Limit the number of concurrent operation as OpenTF - [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults to + [walks the graph](/docs/internals/graph#walking-the-graph). Defaults to 10\. -- All [planning modes](/opentf/cli/commands/plan#planning-modes) and -[planning options](/opentf/cli/commands/plan#planning-options) for +- All [planning modes](/docs/cli/commands/plan#planning-modes) and +[planning options](/docs/cli/commands/plan#planning-options) for `opentf plan` - Customize how OpenTF will create the plan. Only available when you run `opentf apply` without a saved plan file. For configurations using -[the `local` backend](/opentf/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local) only, `opentf apply` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments). ## Passing a Different Configuration Directory If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir) +[the `-chdir` global option](/docs/cli/commands#switching-working-directory-with-chdir) instead, which works across all commands and makes OpenTF consistently look in the given directory for all files it would normally read or write in the current working directory. diff --git a/website/docs/cli/commands/console.mdx b/website/docs/cli/commands/console.mdx index 1d469757d7..ca7c7450c1 100644 --- a/website/docs/cli/commands/console.mdx +++ b/website/docs/cli/commands/console.mdx @@ -8,26 +8,26 @@ description: >- # Command: console The `opentf console` command provides an interactive console for -evaluating [expressions](/opentf/language/expressions). +evaluating [expressions](/docs/language/expressions). ## Usage Usage: `opentf console [options]` This command provides an interactive command-line console for evaluating and -experimenting with [expressions](/opentf/language/expressions). +experimenting with [expressions](/docs/language/expressions). You can use it to test interpolations before using them in configurations and to interact with any values currently saved in -[state](/opentf/language/state). If the current state is empty or has not yet been created, you can use the console to experiment with the expression syntax and -[built-in functions](/opentf/language/functions). The console holds a [lock on the state](/opentf/language/state/locking), and you will not be able to use the console while performing other actions that modify state. +[state](/docs/language/state). If the current state is empty or has not yet been created, you can use the console to experiment with the expression syntax and +[built-in functions](/docs/language/functions). The console holds a [lock on the state](/docs/language/state/locking), and you will not be able to use the console while performing other actions that modify state. To close the console, enter the `exit` command or press Control-C or Control-D. For configurations using -[the `local` backend](/opentf/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local) only, `opentf console` accepts the legacy command line option -[`-state`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`](/docs/language/settings/backends/local#command-line-arguments). ## Scripting @@ -48,7 +48,7 @@ tolist([ ## Remote State -If [remote state](/opentf/language/state/remote) is used by the current backend, +If [remote state](/docs/language/state/remote) is used by the current backend, OpenTF 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.mdx index 841db0b455..bf4c29b8af 100644 --- a/website/docs/cli/commands/destroy.mdx +++ b/website/docs/cli/commands/destroy.mdx @@ -27,7 +27,7 @@ opentf apply -destroy ``` For that reason, this command accepts most of the options that -[`opentf apply`](/opentf/cli/commands/apply) accepts, although it does +[`opentf apply`](/docs/cli/commands/apply) accepts, although it does not accept a plan file argument and forces the selection of the "destroy" planning mode. @@ -38,5 +38,5 @@ destroying would be, by running the following command: opentf plan -destroy ``` -This will run [`opentf plan`](/opentf/cli/commands/plan) in _destroy_ mode, showing +This will run [`opentf plan`](/docs/cli/commands/plan) in _destroy_ mode, showing you the proposed destroy changes without executing them. diff --git a/website/docs/cli/commands/env.mdx b/website/docs/cli/commands/env.mdx index da52258c3f..cd47348ffc 100644 --- a/website/docs/cli/commands/env.mdx +++ b/website/docs/cli/commands/env.mdx @@ -8,5 +8,5 @@ description: >- # Command: env The `opentf env` command is deprecated. -[The `opentf workspace` command](/opentf/cli/commands/workspace) +[The `opentf workspace` command](/docs/cli/commands/workspace) should be used instead. diff --git a/website/docs/cli/commands/fmt.mdx b/website/docs/cli/commands/fmt.mdx index 944ae5daef..36b4ef1b1b 100644 --- a/website/docs/cli/commands/fmt.mdx +++ b/website/docs/cli/commands/fmt.mdx @@ -9,7 +9,7 @@ description: >- The `opentf fmt` command is used to rewrite OpenTF configuration files to a canonical format and style. This command applies a subset of -the [OpenTF language style conventions](/opentf/language/syntax/style), +the [OpenTF language style conventions](/docs/language/syntax/style), along with other minor adjustments for readability. Other OpenTF commands that generate OpenTF configuration will produce diff --git a/website/docs/cli/commands/get.mdx b/website/docs/cli/commands/get.mdx index 0a50c72662..e4f7e721d6 100644 --- a/website/docs/cli/commands/get.mdx +++ b/website/docs/cli/commands/get.mdx @@ -6,7 +6,7 @@ description: The opentf get command downloads and updates modules. # Command: get The `opentf get` command is used to download and update -[modules](/opentf/language/modules/develop) mentioned in the root module. +[modules](/docs/language/modules/develop) mentioned in the root module. ## Usage diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx index 387ac02a9e..39f1b8d1dc 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.mdx @@ -5,7 +5,7 @@ description: The opentf import command brings existing resources into OpenTF sta # Command: import -The `opentf import` command [imports existing resources](/opentf/cli/import) +The `opentf import` command [imports existing resources](/docs/cli/import) into OpenTF. ## Usage @@ -15,7 +15,7 @@ Usage: `opentf import [options] ADDRESS ID` Import will find the existing resource from ID and import it into your OpenTF state at the given ADDRESS. -ADDRESS must be a valid [resource address](/opentf/cli/state/resource-addressing). +ADDRESS must be a valid [resource address](/docs/cli/state/resource-addressing). Because any resource address is valid, the import command can import resources into modules as well as directly into the root of your state. @@ -31,7 +31,7 @@ itself having created all objects. If you import existing objects into OpenTF, be careful to import each remote object to only one OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. For more information on this assumption, see -[the State section](/opentf/language/state). +[the State section](/docs/language/state). The command-line flags are all optional. The following flags are available: @@ -51,7 +51,7 @@ The command-line flags are all optional. The following flags are available: - `-no-color` - If specified, output won't contain any color. - `-parallelism=n` - Limit the number of concurrent operation as OpenTF - [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults + [walks the graph](/docs/internals/graph#walking-the-graph). Defaults to 10. - `-provider=provider` - **Deprecated** Override the provider configuration to @@ -60,11 +60,11 @@ The command-line flags are all optional. The following flags are available: - `-var 'foo=bar'` - Set a variable in the OpenTF configuration. This flag can be set multiple times. Variable values are interpreted as - [literal expressions](/opentf/language/expressions/types) in the + [literal expressions](/docs/language/expressions/types) in the OpenTF language, so list and map values can be specified via this flag. - `-var-file=foo` - Set variables in the OpenTF configuration from - a [variable file](/opentf/language/values/variables#variable-definitions-tfvars-files). If + a [variable file](/docs/language/values/variables#variable-definitions-tfvars-files). If a `terraform.tfvars` or any `.auto.tfvars` files are present in the current directory, they will be automatically loaded. `terraform.tfvars` is loaded first and the `.auto.tfvars` files after in alphabetical order. Any files @@ -72,15 +72,15 @@ The command-line flags are all optional. The following flags are available: the working directory. This flag can be used multiple times. This is only useful with the `-config` flag. -For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf import` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` backend](/opentf/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local) only, `opentf import` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments). ## Provider Configuration @@ -128,7 +128,7 @@ $ opentf 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`](/opentf/language/meta-arguments/count): +[`count`](/docs/language/meta-arguments/count): ```shell $ opentf import 'aws_instance.baz[0]' i-abcd1234 @@ -137,7 +137,7 @@ $ opentf 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`](/opentf/language/meta-arguments/for_each): +[`for_each`](/docs/language/meta-arguments/for_each): Linux, Mac OS, and UNIX: diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx index 3b43335bd1..dd46184f53 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.mdx @@ -87,7 +87,7 @@ will be read or written in the given directory instead. There are two exceptions where OpenTF will use the original working directory even when you specify `-chdir=...`: -* Settings in the [CLI Configuration](/opentf/cli/config/config-file) are not for a specific +* Settings in the [CLI Configuration](/docs/cli/config/config-file) are not for a specific subcommand and OpenTF processes them before acting on the `-chdir` option. diff --git a/website/docs/cli/commands/init.mdx b/website/docs/cli/commands/init.mdx index 0898003af9..9a3f89cbc3 100644 --- a/website/docs/cli/commands/init.mdx +++ b/website/docs/cli/commands/init.mdx @@ -72,7 +72,7 @@ activating credentials) before running `opentf init`. ## Backend Initialization During init, the root configuration directory is consulted for -[backend configuration](/opentf/language/settings/backends/configuration) and the chosen backend +[backend configuration](/docs/language/settings/backends/configuration) and the chosen backend is initialized using the given configuration settings. Re-running init with an already-initialized backend will update the working @@ -94,14 +94,14 @@ when the working directory was already previously initialized for a particular backend. The `-backend-config=...` option can be used for -[partial backend configuration](/opentf/language/settings/backends/configuration#partial-configuration), +[partial backend configuration](/docs/language/settings/backends/configuration#partial-configuration), in situations where the backend settings are dynamic or sensitive and so cannot be statically specified in the configuration file. ## Child Module Installation During init, the configuration is searched for `module` blocks, and the source -code for referenced [modules](/opentf/language/modules/develop) is retrieved from the locations +code for referenced [modules](/docs/language/modules/develop) is retrieved from the locations given in their `source` arguments. Re-running init with modules already installed will install the sources for @@ -126,13 +126,13 @@ third-party provider registry, `opentf 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 OpenTF installs providers using -[the provider installation settings in the CLI configuration](/opentf/cli/config/config-file#provider-installation). +[the provider installation settings in the CLI configuration](/docs/cli/config/config-file#provider-installation). For more information about specifying which providers are required for each -of your modules, see [Provider Requirements](/opentf/language/providers/requirements). +of your modules, see [Provider Requirements](/docs/language/providers/requirements). After successful installation, OpenTF writes information about the selected -providers to [the dependency lock file](/opentf/language/files/dependency-lock). +providers to [the dependency lock file](/docs/language/files/dependency-lock). You should commit this file to your version control system to ensure that when you run `opentf init` again in future OpenTF will select exactly the same provider versions. Use the `-upgrade` option if you want OpenTF @@ -149,7 +149,7 @@ You can modify `opentf init`'s plugin behavior with the following options: 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 OpenTF's installation methods globally](/opentf/cli/config/config-file#provider-installation). + [configuring OpenTF's installation methods globally](/docs/cli/config/config-file#provider-installation). You can use `-plugin-dir` as a one-time override for exceptional situations, such as if you are testing a local build of a provider plugin you are currently developing. @@ -177,7 +177,7 @@ re-installation. If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir) +[the `-chdir` global option](/docs/cli/commands#switching-working-directory-with-chdir) instead, which works across all commands and makes OpenTF consistently look in the given directory for all files it would normally read or write in the current working directory. diff --git a/website/docs/cli/commands/login.mdx b/website/docs/cli/commands/login.mdx index e463b3dad7..7af8479e1a 100644 --- a/website/docs/cli/commands/login.mdx +++ b/website/docs/cli/commands/login.mdx @@ -14,7 +14,7 @@ API token for any host that offers OpenTF-compatible services. where it is possible to launch a web browser on the same host where OpenTF is running. If you are running OpenTF in an unattended automation scenario, you can -[configure credentials manually in the CLI configuration](/opentf/cli/config/config-file#credentials). +[configure credentials manually in the CLI configuration](/docs/cli/config/config-file#credentials). ## Usage @@ -30,11 +30,11 @@ 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](/opentf/cli/config/config-file#credentials-helpers) which knows +[credentials helper program](/docs/cli/config/config-file#credentials-helpers) which knows how to store and later retrieve credentials in some other system, such as your organization's existing secrets management system. ## Login Server Support The `opentf login` command works with any server supporting the -[login protocol](/opentf/internals/login-protocol). +[login protocol](/docs/internals/login-protocol). diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.mdx index 0865a5e408..31b50580b8 100644 --- a/website/docs/cli/commands/logout.mdx +++ b/website/docs/cli/commands/logout.mdx @@ -21,5 +21,5 @@ the remote server, so it will remain valid until manually revoked. By default, OpenTF 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](/opentf/cli/config/config-file#credentials-helpers), OpenTF +[credentials helper program](/docs/cli/config/config-file#credentials-helpers), OpenTF 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.mdx index fe739ee28e..63c53eba2f 100644 --- a/website/docs/cli/commands/output.mdx +++ b/website/docs/cli/commands/output.mdx @@ -30,11 +30,11 @@ The command-line flags are all optional. The following flags are available: for processing complex data types. * `-no-color` - If specified, output won't contain any color. * `-state=path` - Path to the state file. Defaults to "opentf.tfstate". - Ignored when [remote state](/opentf/language/state/remote) is used. + Ignored when [remote state](/docs/language/state/remote) is used. -> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive values in OpenTF state will be displayed in plain text. For more information, -see [Sensitive Data in State](/opentf/language/state/sensitive-data). +see [Sensitive Data in State](/docs/language/state/sensitive-data). ## Examples diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 81a6165663..be33603782 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -28,12 +28,12 @@ to be taken. If you are using OpenTF directly in an interactive terminal and you expect to apply the changes OpenTF proposes, you can alternatively run -[`opentf apply`](/opentf/cli/commands/apply) directly. By default, the "apply" command +[`opentf apply`](/docs/cli/commands/apply) directly. By default, the "apply" command automatically generates a new plan and prompts for you to approve it. You can use the optional `-out=FILE` option to save the generated plan to a file on disk, which you can later execute by passing the file to -[`opentf apply`](/opentf/cli/commands/apply) as an extra argument. This two-step workflow +[`opentf apply`](/docs/cli/commands/apply) as an extra argument. This two-step workflow is primarily intended for when running OpenTF in automation. If you run `opentf plan` without the `-out=FILE` option then it will create @@ -80,10 +80,10 @@ The remaining sections on this page describe the various options: The previous section describes OpenTF's default planning behavior, which changes the remote system to match the changes you make to -your configuration. OpenTF has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `opentf plan` and [`opentf apply`](/opentf/cli/commands/apply). +your configuration. OpenTF has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `opentf plan` and [`opentf apply`](/docs/cli/commands/apply). * **Destroy mode:** creates a plan whose goal is to destroy all remote objects - that currently exist, leaving an empty OpenTF state. It is the same as running [`opentf destroy`](/opentf/cli/commands/destroy). Destroy mode can be useful for situations like transient development environments, where the managed objects cease to be useful once the development task is complete. + that currently exist, leaving an empty OpenTF state. It is the same as running [`opentf destroy`](/docs/cli/commands/destroy). Destroy mode can be useful 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. @@ -108,7 +108,7 @@ one alternative mode at the same time. ## Planning Options -In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for both `opentf plan` and [`opentf apply`](/opentf/cli/commands/apply). +In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for both `opentf plan` and [`opentf apply`](/docs/cli/commands/apply). - `-refresh=false` - Disables the default behavior of synchronizing the OpenTF state with remote objects before checking for configuration changes. This can make the planning operation faster by reducing the number of remote API requests. However, setting `refresh=false` causes OpenTF to ignore external changes, which could result in an incomplete or incorrect plan. You cannot use `refresh=false` in refresh-only planning mode because it would effectively disable the entirety of the planning operation. @@ -123,25 +123,25 @@ In addition to alternate [planning modes](#planning-modes), there are several op -> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around OpenTF limitations. Refer to [Resource Targeting](#resource-targeting) for more details. - `-var 'NAME=VALUE'` - Sets a value for a single - [input variable](/opentf/language/values/variables) declared in the + [input variable](/docs/language/values/variables) declared in the root module of the configuration. Use this option multiple times to set more than one variable. Refer to [Input Variables on the Command Line](#input-variables-on-the-command-line) for more information. - `-var-file=FILENAME` - Sets values for potentially many - [input variables](/opentf/language/values/variables) declared in the + [input variables](/docs/language/values/variables) declared in the root module of the configuration, using definitions from a - ["tfvars" file](/opentf/language/values/variables#variable-definitions-tfvars-files). + ["tfvars" file](/docs/language/values/variables#variable-definitions-tfvars-files). Use this option multiple times to include values from more than one file. There are several other ways to set values for input variables in the root module, aside from the `-var` and `-var-file` options. Refer to -[Assigning Values to Root Module Variables](/opentf/language/values/variables#assigning-values-to-root-module-variables) for more information. +[Assigning Values to Root Module Variables](/docs/language/values/variables#assigning-values-to-root-module-variables) for more information. ### Input Variables on the Command Line You can use the `-var` command line option to specify values for -[input variables](/opentf/language/values/variables) declared in your +[input variables](/docs/language/values/variables) declared in your root module. However, to do so will require writing a command line that is parsable both @@ -190,7 +190,7 @@ so we do not recommend using OpenTF 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](/opentf/language/expressions/type-constraints). +on the variable's [type constraint](/docs/language/expressions/type-constraints). The primitive types `string`, `number`, and `bool` all expect a direct string value with no special punctuation except that required by your shell, as shown in the above examples. For all other type constraints, including list, @@ -210,13 +210,13 @@ opentf 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](/opentf/language/values/variables#assigning-values-to-root-module-variables). +[Assigning Values to Root Module Variables](/docs/language/values/variables#assigning-values-to-root-module-variables). ### Resource Targeting You can use the `-target` option to focus OpenTF's attention on only a subset of resources. -You can use [resource address syntax](/opentf/cli/state/resource-addressing) +You can use [resource address syntax](/docs/cli/state/resource-addressing) to specify the constraint. OpenTF interprets the resource address as follows: * If the given address identifies one specific resource instance, OpenTF @@ -248,7 +248,7 @@ 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](/opentf/language/data-sources) can be used to access +[Data sources](/docs/language/data-sources) can be used to access information about resources created in other configurations, allowing a complex system architecture to be broken down into more manageable parts that can be updated independently. @@ -321,18 +321,18 @@ The available options are: saved plan files as potentially-sensitive artifacts. * `-parallelism=n` - Limit the number of concurrent operations as OpenTF - [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults + [walks the graph](/docs/internals/graph#walking-the-graph). Defaults to 10. For configurations using -[the `local` backend](/opentf/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local) only, `opentf plan` accepts the legacy command line option -[`-state`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`](/docs/language/settings/backends/local#command-line-arguments). ### Passing a Different Configuration Directory If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](/opentf/cli/commands#switching-working-directory-with-chdir) +[the `-chdir` global option](/docs/cli/commands#switching-working-directory-with-chdir) instead, which works across all commands and makes OpenTF consistently look in the given directory for all files it would normally read or write in the current working directory. diff --git a/website/docs/cli/commands/providers.mdx b/website/docs/cli/commands/providers.mdx index 0f92f4b918..27aa380caf 100644 --- a/website/docs/cli/commands/providers.mdx +++ b/website/docs/cli/commands/providers.mdx @@ -8,7 +8,7 @@ description: >- # Command: providers The `opentf providers` command shows information about the -[provider requirements](/opentf/language/providers/requirements) of the +[provider requirements](/docs/language/providers/requirements) of the configuration in the current working directory, as an aid to understanding where each requirement was detected from. diff --git a/website/docs/cli/commands/providers/lock.mdx b/website/docs/cli/commands/providers/lock.mdx index 79363047e0..650535ec05 100644 --- a/website/docs/cli/commands/providers/lock.mdx +++ b/website/docs/cli/commands/providers/lock.mdx @@ -9,15 +9,15 @@ description: |- The `opentf providers lock` consults upstream registries (by default) in order to write provider dependency information into -[the dependency lock file](/opentf/language/files/dependency-lock). +[the dependency lock file](/docs/language/files/dependency-lock). The common way to update the dependency lock file is as a side-effect of normal provider installation during -[`opentf init`](/opentf/cli/commands/init), but there are several situations where that +[`opentf init`](/docs/cli/commands/init), but there are several situations where that automatic approach may not be sufficient: * If you are running OpenTF in an environment that uses - [alternative provider installation methods](/opentf/cli/config/config-file#provider-installation), + [alternative provider installation methods](/docs/cli/config/config-file#provider-installation), such as filesystem or network mirrors, normal provider installation will not access the origin registry for a provider and therefore OpenTF will not be able to populate all of the possible package checksums for the selected @@ -33,7 +33,7 @@ automatic approach may not be sufficient: 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 OpenTF on other platforms may - [add additional checksums to the lock file](/opentf/language/files/dependency-lock#new-provider-package-checksums). + [add additional checksums to the lock file](/docs/language/files/dependency-lock#new-provider-package-checksums). You can avoid that by pre-populating hashes for all of the platforms you intend to use, using the `opentf providers lock` command. @@ -45,7 +45,7 @@ With no additional command line arguments, `opentf 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](/opentf/language/files/dependency-lock) to +[the dependency lock file](/docs/language/files/dependency-lock) to include a selected version for each provider and all of the package checksums that are covered by the provider developer's cryptographic signature. @@ -70,7 +70,7 @@ You can customize the default behavior using the following additional option: * `-net-mirror=URL` - Direct OpenTF to look for provider packages in the given network mirror service, instead of in upstream registries. The given URL must implement - [the OpenTF provider network mirror protocol](/opentf/internals/provider-network-mirror-protocol). + [the OpenTF provider network mirror protocol](/docs/internals/provider-network-mirror-protocol). * `-platform=OS_ARCH` - Specify a platform you intend to use to work with this OpenTF configuration. OpenTF will ensure that the providers are all @@ -146,7 +146,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](/opentf/cli/config/config-file#provider-installation), +[the provider installation methods configuration](/docs/cli/config/config-file#provider-installation), but specify only a single method in order to be explicit about where you intend to derive the package checksum information from. @@ -163,4 +163,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](/opentf/internals/provider-registry-protocol). +[the provider registry protocol](/docs/internals/provider-registry-protocol). diff --git a/website/docs/cli/commands/providers/mirror.mdx b/website/docs/cli/commands/providers/mirror.mdx index aa516f23c0..8b802c8833 100644 --- a/website/docs/cli/commands/providers/mirror.mdx +++ b/website/docs/cli/commands/providers/mirror.mdx @@ -17,7 +17,7 @@ from provider registries as part of initializing the current working directory. Sometimes OpenTF is running in an environment where that isn't possible, such as on an isolated network without access to an OpenTF Registry. In that case, -[explicit installation method configuration](/opentf/cli/config/config-file#explicit-installation-method-configuration) +[explicit installation method configuration](/docs/cli/config/config-file#explicit-installation-method-configuration) allows you to configure OpenTF, 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. @@ -37,7 +37,7 @@ themselves. OpenTF will also generate various `.json` index files which contain suitable responses to implement -[the network mirror protocol](/opentf/internals/provider-network-mirror-protocol), +[the network mirror protocol](/docs/internals/provider-network-mirror-protocol), if you upload the resulting directory to a static website host. OpenTF 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.mdx index 74f64710b1..ceb8ac5c73 100644 --- a/website/docs/cli/commands/providers/schema.mdx +++ b/website/docs/cli/commands/providers/schema.mdx @@ -32,7 +32,7 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises). ## Format Summary diff --git a/website/docs/cli/commands/refresh.mdx b/website/docs/cli/commands/refresh.mdx index b6b983b62d..89a315915a 100644 --- a/website/docs/cli/commands/refresh.mdx +++ b/website/docs/cli/commands/refresh.mdx @@ -15,14 +15,14 @@ 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 -[OpenTF state](/opentf/language/state). +[OpenTF state](/docs/language/state). You shouldn't typically need to use this command, because OpenTF automatically performs the same refreshing actions as a part of creating a plan in both the -[`opentf plan`](/opentf/cli/commands/plan) +[`opentf plan`](/docs/cli/commands/plan) and -[`opentf apply`](/opentf/cli/commands/apply) +[`opentf apply`](/docs/cli/commands/apply) commands. This command is here primarily for backward compatibility, but we don't recommend using it because it provides no opportunity to review the effects of the operation before updating the state. @@ -38,7 +38,7 @@ opentf apply -refresh-only -auto-approve ``` Consequently, it supports all of the same options as -[`opentf apply`](/opentf/cli/commands/apply) except that it does not accept a saved +[`opentf apply`](/docs/cli/commands/apply) except that it does not accept a saved plan file, it doesn't allow selecting a planning mode other than "refresh only", and `-auto-approve` is always enabled. diff --git a/website/docs/cli/commands/show.mdx b/website/docs/cli/commands/show.mdx index cac828abca..2dc7dd1f7f 100644 --- a/website/docs/cli/commands/show.mdx +++ b/website/docs/cli/commands/show.mdx @@ -19,7 +19,7 @@ flag. -> **Note:** When using the `-json` command-line flag, any sensitive values in OpenTF state will be displayed in plain text. For more information, see -[Sensitive Data in State](/opentf/language/state/sensitive-data). +[Sensitive Data in State](/docs/language/state/sensitive-data). ## JSON Output @@ -35,7 +35,7 @@ was written, the state needs to be upgraded before it can be displayed with `-refresh=false`. If you are viewing a state file, run `opentf refresh` first. -The output format is covered in detail in [JSON Output Format](/opentf/internals/json-format). +The output format is covered in detail in [JSON Output Format](/docs/internals/json-format). ## Usage diff --git a/website/docs/cli/commands/state/index.mdx b/website/docs/cli/commands/state/index.mdx index 7d083e0950..c7fb843361 100644 --- a/website/docs/cli/commands/state/index.mdx +++ b/website/docs/cli/commands/state/index.mdx @@ -7,7 +7,7 @@ description: The `opentf state` command is used for advanced state management. The `opentf state` command is used for advanced state management. As your OpenTF usage becomes more advanced, there are some cases where -you may need to modify the [OpenTF state](/opentf/language/state). +you may need to modify the [OpenTF state](/docs/language/state). Rather than modify the state directly, the `opentf state` commands can be used in many cases instead. @@ -32,7 +32,7 @@ written to disk and the CLI usage is the same as if it were local state. All `opentf 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](/opentf/cli/commands/state/list)) +Subcommands that are read-only (such as [list](/docs/cli/commands/state/list)) do not write any backup files since they aren't modifying the state. Note that backups for state modification _can not be disabled_. Due to diff --git a/website/docs/cli/commands/state/list.mdx b/website/docs/cli/commands/state/list.mdx index 02b9c2f333..ddc46d2b72 100644 --- a/website/docs/cli/commands/state/list.mdx +++ b/website/docs/cli/commands/state/list.mdx @@ -8,7 +8,7 @@ description: >- # Command: state list The `opentf state list` command is used to list resources within a -[OpenTF state](/opentf/language/state). +[OpenTF state](/docs/language/state). ## Usage @@ -24,12 +24,12 @@ within modules are listed last. For complex infrastructures, the state can contain thousands of resources. To filter these, provide one or more patterns to the command. Patterns are -in [resource addressing format](/opentf/cli/state/resource-addressing). +in [resource addressing format](/docs/cli/state/resource-addressing). The command-line flags are all optional. The following flags are available: * `-state=path` - Path to the state file. Defaults to "opentf.tfstate". - Ignored when [remote state](/opentf/language/state/remote) is used. + Ignored when [remote state](/docs/language/state/remote) is used. * `-id=id` - ID of resources to show. Ignored when unset. ## Example: All Resources diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.mdx index 4d653178e4..d1d3a2b2af 100644 --- a/website/docs/cli/commands/state/mv.mdx +++ b/website/docs/cli/commands/state/mv.mdx @@ -7,7 +7,7 @@ description: >- # Command: state mv -The main function of [OpenTF state](/opentf/language/state) is +The main function of [OpenTF state](/docs/language/state) is to track the bindings between resource instance addresses in your configuration and the remote objects they represent. Normally OpenTF automatically updates the state in response to actions taken when applying a plan, such as @@ -28,7 +28,7 @@ remote objects currently associated with the source to be tracked instead by the destination. Both the source and destination addresses must use -[resource address syntax](/opentf/cli/state/resource-addressing), and +[resource address syntax](/docs/cli/state/resource-addressing), and they must both refer to the same kind of object: you can only move a resource instance to another resource instance, a whole module instance to another whole module instance, etc. Furthermore, if you are moving a resource or @@ -66,22 +66,22 @@ This command also accepts the following options: returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf state mv` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). -The legacy options [`-backup` and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments) +The legacy options [`-backup` and `-backup-out`](/docs/language/settings/backends/local#command-line-arguments) operate on a local state file only. Configurations using -[the `remote` backend](/opentf/language/settings/backends/remote) -must specify a local state file with the [`-state`](/opentf/language/settings/backends/local#command-line-arguments) -option in order to use the [`-backup` and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments) +[the `remote` backend](/docs/language/settings/backends/remote) +must specify a local state file with the [`-state`](/docs/language/settings/backends/local#command-line-arguments) +option in order to use the [`-backup` and `-backup-out`](/docs/language/settings/backends/local#command-line-arguments) options. For configurations using -[the `local` state mv](/opentf/language/settings/backends/local) only, +[the `local` state mv](/docs/language/settings/backends/local) only, `opentf state mv` also accepts the legacy options -[`-state`, `-state-out`, `-backup`, and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, `-backup`, and `-backup-out`](/docs/language/settings/backends/local#command-line-arguments). ## Example: Rename a Resource @@ -133,7 +133,7 @@ opentf 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](/opentf/language/meta-arguments/count) +A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count) has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address: @@ -158,7 +158,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](/opentf/language/meta-arguments/for_each) +A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each) has multiple instances that are each identified by an string. You can select a particular instance by including an explicit key in your given address. diff --git a/website/docs/cli/commands/state/pull.mdx b/website/docs/cli/commands/state/pull.mdx index 5fd7cd39ce..7e9584de30 100644 --- a/website/docs/cli/commands/state/pull.mdx +++ b/website/docs/cli/commands/state/pull.mdx @@ -8,7 +8,7 @@ description: >- # Command: state pull The `opentf state pull` command is used to manually download and output -the state from [remote state](/opentf/language/state/remote). This command also +the state from [remote state](/docs/language/state/remote). This command also works with local state. ## Usage diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx index a02b186f47..10d7575254 100644 --- a/website/docs/cli/commands/state/push.mdx +++ b/website/docs/cli/commands/state/push.mdx @@ -6,7 +6,7 @@ description: The `opentf state push` command pushes items to the OpenTF state. # Command: state push The `opentf state push` command is used to manually upload a local -state file to [remote state](/opentf/language/state/remote). This command also +state file to [remote state](/docs/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 @@ -17,7 +17,7 @@ manual intervention is necessary with the remote state. Usage: `opentf state push [options] PATH` This command pushes the state specified by PATH to the currently -configured [backend](/opentf/language/settings/backends/configuration). +configured [backend](/docs/language/settings/backends/configuration). 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 @@ -42,7 +42,7 @@ 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 [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf state push` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). diff --git a/website/docs/cli/commands/state/replace-provider.mdx b/website/docs/cli/commands/state/replace-provider.mdx index 2f68092d23..ee7afde460 100644 --- a/website/docs/cli/commands/state/replace-provider.mdx +++ b/website/docs/cli/commands/state/replace-provider.mdx @@ -8,7 +8,7 @@ description: >- # Command: state replace-provider The `opentf state replace-provider` command is used to replace the provider -for resources in a [OpenTF state](/opentf/language/state). +for resources in a [OpenTF state](/docs/language/state). ## Usage @@ -32,15 +32,15 @@ This command also accepts the following options: - `-lock-timeout=0s` - Duration to retry a state lock. -For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf state replace-provider` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` state](/opentf/language/settings/backends/local) only, +[the `local` state](/docs/language/settings/backends/local) only, `opentf state replace-provider` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments). ## Example diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.mdx index bd8f330ab6..ef1c2db367 100644 --- a/website/docs/cli/commands/state/rm.mdx +++ b/website/docs/cli/commands/state/rm.mdx @@ -7,7 +7,7 @@ description: >- # Command: state rm -The main function of [OpenTF state](/opentf/language/state) is +The main function of [OpenTF state](/docs/language/state) is to track the bindings between resource instance addresses in your configuration and the remote objects they represent. Normally OpenTF automatically updates the state in response to actions taken when applying a plan, such as @@ -23,13 +23,13 @@ to exist in the remote system. Usage: `opentf state rm [options] ADDRESS...` OpenTF will search the state for any instances matching the given -[resource address](/opentf/cli/state/resource-addressing), and remove +[resource address](/docs/cli/state/resource-addressing), and remove the record of each one so that OpenTF 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 -[`opentf plan`](/opentf/cli/commands/plan) +[`opentf plan`](/docs/cli/commands/plan) will include an action to create a new object for each of the "forgotten" instances. Depending on the constraints imposed by the remote system, creating those objects might fail if their names or other identifiers conflict with @@ -49,15 +49,15 @@ This command also accepts the following options: returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf state rm` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` state rm](/opentf/language/settings/backends/local) only, +[the `local` state rm](/docs/language/settings/backends/local) only, `opentf state rm` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments). ## Example: Remove all Instances of a Resource @@ -92,7 +92,7 @@ $ opentf state rm 'module.foo' ## Example: Remove a Particular Instance of a Resource using `count` -A resource defined with [the `count` meta-argument](/opentf/language/meta-arguments/count) +A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count) has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address: @@ -107,7 +107,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](/opentf/language/meta-arguments/for_each) +A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each) has multiple instances that are each identified by an string. You can select a particular instance by including an explicit key in your given address. diff --git a/website/docs/cli/commands/state/show.mdx b/website/docs/cli/commands/state/show.mdx index bfe64b8d6c..0bcc341a64 100644 --- a/website/docs/cli/commands/state/show.mdx +++ b/website/docs/cli/commands/state/show.mdx @@ -9,7 +9,7 @@ description: >- The `opentf state show` command is used to show the attributes of a single resource in the -[OpenTF state](/opentf/language/state). +[OpenTF state](/docs/language/state). ## Usage @@ -20,16 +20,16 @@ state file that matches the given address. This command requires an address that points to a single resource in the state. Addresses are -in [resource addressing format](/opentf/cli/state/resource-addressing). +in [resource addressing format](/docs/cli/state/resource-addressing). The command-line flags are all optional. The following flags are available: * `-state=path` - Path to the state file. Defaults to "opentf.tfstate". - Ignored when [remote state](/opentf/language/state/remote) is used. + Ignored when [remote state](/docs/language/state/remote) is used. The output of `opentf state show` is intended for human consumption, not programmatic consumption. To extract state data for use in other software, use -[`opentf show -json`](/opentf/cli/commands/show#json-output) and decode the result +[`opentf show -json`](/docs/cli/commands/show#json-output) and decode the result using the documented structure. ## Example: Show a Resource @@ -60,7 +60,7 @@ $ opentf 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`](/opentf/language/meta-arguments/count): +[`count`](/docs/language/meta-arguments/count): ```shell $ opentf state show 'packet_device.worker[0]' @@ -68,7 +68,7 @@ $ opentf state show 'packet_device.worker[0]' ## Example: Show a Resource configured with for_each -The following example shows the `"example"` instance of a `packet_device` resource named `worker` configured with the [`for_each`](/opentf/language/meta-arguments/for_each) meta-argument. You must place the resource name in single quotes when it contains special characters like double quotes. +The following example shows the `"example"` instance of a `packet_device` resource named `worker` configured with the [`for_each`](/docs/language/meta-arguments/for_each) meta-argument. You must place the resource name in single quotes when it contains special characters like double quotes. Linux, Mac OS, and UNIX: diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index 34fc4b4363..709a85615c 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -16,7 +16,7 @@ propose to replace it in the next plan you create. ## Recommended Alternative -We recommend using the [`-replace` option](/opentf/cli/commands/plan#replace-address) with `opentf apply` to force OpenTF to replace an object even though there are no configuration changes that would require it. +We recommend using the [`-replace` option](/docs/cli/commands/plan#replace-address) with `opentf apply` to force OpenTF to replace an object even though there are no configuration changes that would require it. ``` $ opentf apply -replace="aws_instance.example[0]" @@ -32,7 +32,7 @@ $ opentf taint [options]
The `address` argument is the address of the resource to mark as tainted. The address is in -[the resource address syntax](/opentf/cli/state/resource-addressing), +[the resource address syntax](/docs/cli/state/resource-addressing), as shown in the output from other commands, such as: - `aws_instance.foo` @@ -55,11 +55,11 @@ This command accepts the following options: returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) only, `opentf taint` +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf taint` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` backend](/opentf/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local) only, `opentf taint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments). diff --git a/website/docs/cli/commands/test.mdx b/website/docs/cli/commands/test.mdx index e404025cef..5a85ee3e06 100644 --- a/website/docs/cli/commands/test.mdx +++ b/website/docs/cli/commands/test.mdx @@ -6,7 +6,7 @@ description: Part of the ongoing design research for module integration testing. # Command: test The `opentf test` command is currently serving as part of -[the module integration testing experiment](/opentf/language/modules/testing-experiment). +[the module integration testing experiment](/docs/language/modules/testing-experiment). It's not ready for routine use, but if you'd be interested in trying the prototype functionality then we'd love to hear your feedback. See the diff --git a/website/docs/cli/commands/untaint.mdx b/website/docs/cli/commands/untaint.mdx index 145168e7da..14d3c9921c 100644 --- a/website/docs/cli/commands/untaint.mdx +++ b/website/docs/cli/commands/untaint.mdx @@ -16,7 +16,7 @@ a multi-step "create" action, because OpenTF 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 -[`opentf taint`](/opentf/cli/commands/taint), although we no longer recommend that +[`opentf taint`](/docs/cli/commands/taint), although we no longer recommend that workflow. If OpenTF currently considers a particular object as tainted but you've @@ -38,7 +38,7 @@ opentf apply -replace="aws_instance.example[0]" Usage: `opentf untaint [options] address` -The `address` argument is a [resource address](/opentf/cli/state/resource-addressing) +The `address` argument is a [resource address](/docs/cli/state/resource-addressing) identifying a particular resource instance which is currently tainted. This command also accepts the following options: @@ -61,12 +61,12 @@ This command also accepts the following options: if you are running OpenTF in a context where its output will be rendered by a system that cannot interpret terminal formatting. -For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf untaint` also accepts the option -[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` backend](/opentf/language/settings/backends/local) only, +[the `local` backend](/docs/language/settings/backends/local) only, `opentf untaint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/opentf/language/settings/backends/local#command-line-arguments). +[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments). diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.mdx index a598202ffb..3268339060 100644 --- a/website/docs/cli/commands/validate.mdx +++ b/website/docs/cli/commands/validate.mdx @@ -65,7 +65,7 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises). In the normal case, OpenTF will print a JSON object to the standard output stream. The top-level JSON object will have the following properties: diff --git a/website/docs/cli/commands/workspace/delete.mdx b/website/docs/cli/commands/workspace/delete.mdx index 2dbcb1f1ef..fa43cb46b8 100644 --- a/website/docs/cli/commands/workspace/delete.mdx +++ b/website/docs/cli/commands/workspace/delete.mdx @@ -17,7 +17,7 @@ To delete a workspace, it must already exist, it must not be tracking resources, and it must not be your current workspace. If the workspace is tracking resources, OpenTF will not allow you to delete it unless the `-force` flag is specified. -Additionally, different [backends](/opentf/language/settings/backends/configuration#backend-types) may implement other +Additionally, different [backends](/docs/language/settings/backends/configuration#backend-types) may implement other restrictions on whether a workspace is considered safe to delete without the `-force` flag, such as whether the workspace is locked. If you delete a workspace which is tracking resources (via `-force`), then resources diff --git a/website/docs/cli/commands/workspace/index.mdx b/website/docs/cli/commands/workspace/index.mdx index 3060ed77d1..84270aa4d1 100644 --- a/website/docs/cli/commands/workspace/index.mdx +++ b/website/docs/cli/commands/workspace/index.mdx @@ -6,7 +6,7 @@ description: The workspace command helps you manage workspaces. # Command: workspace The `opentf workspace` command is used to manage -[workspaces](/opentf/language/state/workspaces). +[workspaces](/docs/language/state/workspaces). This command is a container for further subcommands that each have their own page in the documentation. diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.mdx index e16a3757c4..d92ce8b4e7 100644 --- a/website/docs/cli/config/config-file.mdx +++ b/website/docs/cli/config/config-file.mdx @@ -9,7 +9,7 @@ description: >- The CLI configuration file configures per-user settings for CLI behaviors, which apply across all OpenTF working directories. This is separate from -[your infrastructure configuration](/opentf/language). +[your infrastructure configuration](/docs/language). ## Locations @@ -35,7 +35,7 @@ as just `opentf.rc`. Use `dir` from PowerShell or Command Prompt to confirm the filename. The location of the OpenTF CLI configuration file can also be specified -using the `TF_CLI_CONFIG_FILE` [environment variable](/opentf/cli/config/environment-variables). +using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/cli/config/environment-variables). Any such file should follow the naming pattern `*.tfrc`. ## Configuration File Syntax @@ -79,7 +79,7 @@ credentials "app.placeholderplaceholderplaceholder.io" { } ``` -If you are running the OpenTF CLI interactively on a computer with a web browser, you can use [the `opentf login` command](/opentf/cli/commands/login) +If you are running the OpenTF CLI interactively on a computer with a web browser, you can use [the `opentf login` command](/docs/cli/commands/login) to get credentials and automatically save them in the CLI configuration. If not, you can manually write `credentials` blocks. @@ -134,7 +134,7 @@ for a specific hostname by writing a `credentials` block alongside the OpenTF 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](/opentf/internals/credentials-helpers). +[the guide to Credentials Helper internals](/docs/internals/credentials-helpers). ### Credentials Source Priority Order @@ -239,7 +239,7 @@ The following are the two supported installation method types: use the `https:` scheme and end with a trailing slash. OpenTF expects the given URL to be a base URL for an implementation of - [the provider network mirror protocol](/opentf/internals/provider-network-mirror-protocol), + [the provider network mirror protocol](/docs/internals/provider-network-mirror-protocol), which is designed to be relatively easy to implement using typical static website hosting mechanisms. @@ -364,7 +364,7 @@ understand the consequences of enabling it. By default OpenTF will use packages from the global cache directory only if they match at least one of the checksums recorded in the -[dependency lock file](/opentf/language/files/dependency-lock) +[dependency lock file](/docs/language/files/dependency-lock) for that provider. This ensures that OpenTF can always generate a complete and correct dependency lock file entry the first time you use a new provider in a particular configuration. @@ -445,7 +445,7 @@ provider_installation { With development overrides in effect, the `opentf init` command will still attempt to select a suitable published version of your provider to install and record in -[the dependency lock file](/opentf/language/files/dependency-lock) +[the dependency lock file](/docs/language/files/dependency-lock) for future use, but other commands like `opentf 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.mdx index 99051760a6..02050fd52d 100644 --- a/website/docs/cli/config/environment-variables.mdx +++ b/website/docs/cli/config/environment-variables.mdx @@ -27,7 +27,7 @@ To disable, either unset it, or set it to `off`. For example: export TF_LOG=off ``` -For more on debugging OpenTF, check out the section on [Debugging](/opentf/internals/debugging). +For more on debugging OpenTF, check out the section on [Debugging](/docs/internals/debugging). ## TF_LOG_PATH @@ -37,7 +37,7 @@ This specifies where the log should persist its output to. Note that even when ` export TF_LOG_PATH=./terraform.log ``` -For more on debugging OpenTF, check out the section on [Debugging](/opentf/internals/debugging). +For more on debugging OpenTF, check out the section on [Debugging](/docs/internals/debugging). ## TF_INPUT @@ -58,7 +58,7 @@ 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](/opentf/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). ## TF_CLI_ARGS and TF_CLI_ARGS_name @@ -114,7 +114,7 @@ export TF_WORKSPACE=your_workspace Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state. -For more information regarding workspaces, check out the section on [Using Workspaces](/opentf/language/state/workspaces). +For more information regarding workspaces, check out the section on [Using Workspaces](/docs/language/state/workspaces). ## TF_IN_AUTOMATION @@ -143,7 +143,7 @@ export TF_REGISTRY_CLIENT_TIMEOUT=15 ## TF_CLI_CONFIG_FILE -The location of the [OpenTF CLI configuration file](/opentf/cli/config/config-file). +The location of the [OpenTF CLI configuration file](/docs/cli/config/config-file). ```shell export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom" @@ -151,9 +151,9 @@ export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom" ## TF_PLUGIN_CACHE_DIR -The `TF_PLUGIN_CACHE_DIR` environment variable is an alternative way to set [the `plugin_cache_dir` setting in the CLI configuration](/opentf/cli/config/config-file#provider-plugin-cache). +The `TF_PLUGIN_CACHE_DIR` environment variable is an alternative way to set [the `plugin_cache_dir` setting in the CLI configuration](/docs/cli/config/config-file#provider-plugin-cache). -You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [the transitional compatibility setting `plugin_cache_may_break_dependency_lock_file`](/opentf/cli/config/config-file#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file). +You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [the transitional compatibility setting `plugin_cache_may_break_dependency_lock_file`](/docs/cli/config/config-file#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file). ## TF_IGNORE @@ -163,10 +163,10 @@ If `TF_IGNORE` is set to "trace", OpenTF will output debug messages to display i export TF_IGNORE=trace ``` -For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/opentf/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#excluding-files-from-upload-with-terraformignore). ## Cloud Backend CLI Integration The CLI integration with cloud backends lets you use them on the command line. The integration requires including a `cloud` block in your OpenTF configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI). -Refer to [Cloud Backend Settings](/opentf/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables. +Refer to [Cloud Backend Settings](/docs/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables. diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.mdx index d7ea70c762..686369d8a5 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.mdx @@ -16,9 +16,9 @@ most of the global settings relate to advanced or automated workflows, or unusual environmental conditions like running OpenTF on an airgapped instance. -- The [CLI config file](/opentf/cli/config/config-file) configures provider +- The [CLI config file](/docs/cli/config/config-file) configures provider installation and security features. -- Several [environment variables](/opentf/cli/config/environment-variables) can +- Several [environment variables](/docs/cli/config/environment-variables) can configure OpenTF'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.mdx index d5a9f164c6..873e02812e 100644 --- a/website/docs/cli/import/importability.mdx +++ b/website/docs/cli/import/importability.mdx @@ -13,4 +13,4 @@ importable. As a result, you cannot import all OpenTF resources. The resources that you can import are documented at the bottom of each resource documentation page in the [public Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository. -To make a resource importable, refer to [Extending OpenTF: Resources — Import](/opentf/plugin/sdkv2/resources/import). +To make a resource importable, refer to [Extending OpenTF: Resources — Import](/docs/plugin/sdkv2/resources/import). diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx index 41ea41dd97..d9d8ef4620 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.mdx @@ -9,13 +9,13 @@ description: >- OpenTF can import existing infrastructure resources. This functionality lets you bring existing resources under OpenTF management. --> **Note:** OpenTF supports `import` blocks. Unlike the `opentf import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/opentf/language/import). +-> **Note:** OpenTF supports `import` blocks. Unlike the `opentf import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/docs/language/import). ## State Only -~> **Warning:** OpenTF expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. See [State](/opentf/language/state) for more details. +~> **Warning:** OpenTF expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. See [State](/docs/language/state) for more details. -The `opentf import` CLI command can only import resources into the [state](/opentf/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/opentf/language/import). +The `opentf import` CLI command can only import resources into the [state](/docs/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/docs/language/import). Before you run `opentf import` you must manually write a `resource` configuration block for the resource. The resource block describes where OpenTF should map the imported object. diff --git a/website/docs/cli/import/usage.mdx b/website/docs/cli/import/usage.mdx index 0c534b275d..4b9763948f 100644 --- a/website/docs/cli/import/usage.mdx +++ b/website/docs/cli/import/usage.mdx @@ -15,7 +15,7 @@ itself having created all objects. If you import existing objects into OpenTF, be careful to import each remote object to only one OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. For more information on this assumption, see -[the State section](/opentf/language/state). +[the State section](/docs/language/state). To import a resource, first write a resource block for it in your configuration, establishing the name by which it will be known to OpenTF: @@ -49,7 +49,7 @@ OpenTF 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_](/opentf/cli/state/resource-addressing) for more +[_Resource Addressing_](/docs/cli/state/resource-addressing) for more details on how to specify a target resource. The syntax of the given ID is dependent on the resource type being imported. @@ -75,4 +75,4 @@ a `resource` block in configuration for each secondary resource. If this is not done, OpenTF 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](/opentf/cli/commands/state) can be used. +[state management commands](/docs/cli/commands/state) can be used. diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.mdx index b715d138dc..ae4188dddc 100644 --- a/website/docs/cli/index.mdx +++ b/website/docs/cli/index.mdx @@ -14,4 +14,4 @@ TACOS (TF Automation and Collaboration Software). Notably, this documentation does not cover the syntax and usage of the OpenTF language. For that, see the -[OpenTF Language Documentation](/opentf/language). +[OpenTF Language Documentation](/docs/language). diff --git a/website/docs/cli/init/index.mdx b/website/docs/cli/init/index.mdx index 2fc9f119d7..1ee10b9758 100644 --- a/website/docs/cli/init/index.mdx +++ b/website/docs/cli/init/index.mdx @@ -10,7 +10,7 @@ description: >- OpenTF expects to be invoked from a working directory that contains configuration files written in -[the OpenTF language](/opentf/language). OpenTF uses +[the OpenTF language](/docs/language). OpenTF uses configuration content from this directory, and also uses the directory to store settings, cached plugins and modules, and sometimes state data. @@ -25,7 +25,7 @@ A OpenTF working directory typically contains: configuration is expected to change over time. - A hidden `.terraform` directory, which OpenTF uses to manage cached provider plugins and modules, record which - [workspace](/opentf/cli/workspaces) is currently active, and + [workspace](/docs/cli/workspaces) is currently active, and record the last known backend configuration in case it needs to migrate state on the next run. This directory is automatically managed by OpenTF, and is created during initialization. @@ -50,7 +50,7 @@ plugins, and downloading modules. Under some conditions (usually when changing from one backend to another), it might ask the user for guidance or confirmation. -For details, see [the `opentf init` command](/opentf/cli/commands/init). +For details, see [the `opentf init` command](/docs/cli/commands/init). ## Reinitialization diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx index 02c7cffe13..5cf9076e2e 100644 --- a/website/docs/cli/inspect/index.mdx +++ b/website/docs/cli/inspect/index.mdx @@ -17,19 +17,19 @@ OpenTF CLI includes some commands for inspecting or transforming this data. You can use these to integrate other tools with OpenTF's infrastructure data, or just to gain a deeper or more holistic understanding of your infrastructure. -- [The `opentf graph` command](/opentf/cli/commands/graph) creates a visual +- [The `opentf graph` command](/docs/cli/commands/graph) creates a visual representation of a configuration or a set of planned changes. -- [The `opentf output` command](/opentf/cli/commands/output) can get the - values for the top-level [output values](/opentf/language/values/outputs) of +- [The `opentf output` command](/docs/cli/commands/output) can get the + values for the top-level [output values](/docs/language/values/outputs) of a configuration, which are often helpful when making use of the infrastructure OpenTF has provisioned. -- [The `opentf show` command](/opentf/cli/commands/show) can generate +- [The `opentf show` command](/docs/cli/commands/show) can generate human-readable versions of a state file or plan file, or generate machine-readable versions that can be integrated with other tools. -- [The `opentf state list` command](/opentf/cli/commands/state/list) can list +- [The `opentf state list` command](/docs/cli/commands/state/list) can list the resources being managed by the current working directory and workspace, providing a complete or filtered list. -- [The `opentf state show` command](/opentf/cli/commands/state/show) can print +- [The `opentf state show` command](/docs/cli/commands/state/show) can print all of the attributes of a given resource being managed by the current working directory and workspace, including generated read-only attributes like the unique ID assigned by the cloud provider. diff --git a/website/docs/cli/install/apt.mdx b/website/docs/cli/install/apt.mdx index 309d60d8e5..33d59ffcb7 100644 --- a/website/docs/cli/install/apt.mdx +++ b/website/docs/cli/install/apt.mdx @@ -15,7 +15,7 @@ Debian and Ubuntu systems, which allow you to install OpenTF 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 OpenTF from our Yum repositories](/opentf/cli/install/yum). +might prefer to [install OpenTF from our Yum repositories](/docs/cli/install/yum). ## Repository Configuration @@ -28,7 +28,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 OpenTF on a non-`amd64` system, -[download a normal release `.zip` file](/opentf/downloads) instead. +[download a normal release `.zip` file](/docs/downloads) instead. ## Installing a Specific Version of OpenTF diff --git a/website/docs/cli/install/yum.mdx b/website/docs/cli/install/yum.mdx index 4b85c2fd6e..bdf6186b1c 100644 --- a/website/docs/cli/install/yum.mdx +++ b/website/docs/cli/install/yum.mdx @@ -15,7 +15,7 @@ RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to install OpenTF using the `yum install` or `dnf install` commands. If you are instead using Debian or Ubuntu, you -might prefer to [install OpenTF from our APT repositories](/opentf/cli/install/apt). +might prefer to [install OpenTF from our APT repositories](/docs/cli/install/apt). ## Repository Configuration @@ -56,7 +56,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 OpenTF on a non-`x86_64` system, -[download a normal release `.zip` file](/opentf/downloads) instead. +[download a normal release `.zip` file](/docs/downloads) instead. ## Supported Distribution Releases diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.mdx index be67617d9a..aa4bfaf2a3 100644 --- a/website/docs/cli/plugins/index.mdx +++ b/website/docs/cli/plugins/index.mdx @@ -9,15 +9,15 @@ description: >- OpenTF relies on plugins called "providers" in order to manage various types of resources. (For more information about providers, see -[Providers](/opentf/language/providers) in the OpenTF +[Providers](/docs/language/providers) in the OpenTF language docs.) -> **Note:** Providers are the only plugin type most OpenTF users interact with. OpenTF also supports third-party provisioner plugins, but we discourage their use. OpenTF downloads and/or installs any providers -[required](/opentf/language/providers/requirements) by a configuration -when [initializing](/opentf/cli/init) a working directory. By default, +[required](/docs/language/providers/requirements) by a configuration +when [initializing](/docs/cli/init) a working directory. By default, this works without any additional interaction but requires network access to download providers from their source registry. @@ -31,29 +31,29 @@ environments. OpenTF'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](/opentf/cli/config/config-file). +more information, see [CLI Config File](/docs/cli/config/config-file). ## Getting Plugin Information -Use the [`opentf providers`](/opentf/cli/commands/providers) command to get information +Use the [`opentf providers`](/docs/cli/commands/providers) command to get information about the providers required by the current working directory's configuration. -Use the [`opentf version`](/opentf/cli/commands/version) command (or +Use the [`opentf version`](/docs/cli/commands/version) command (or `opentf -version`) to show the specific provider versions installed for the current working directory. -Use the [`opentf providers schema`](/opentf/cli/commands/providers/schema) command to +Use the [`opentf providers schema`](/docs/cli/commands/providers/schema) command to get machine-readable information about the resources and configuration options offered by each provider. ## Managing Plugin Installation -Use the [`opentf providers mirror`](/opentf/cli/commands/providers/mirror) command to +Use the [`opentf providers mirror`](/docs/cli/commands/providers/mirror) command to download local copies of every provider required by the current working directory's configuration. This directory will use the nested directory layout that OpenTF expects when installing plugins from a local source, so you can transfer it directly to an airgapped system that runs OpenTF. -Use the [`opentf providers lock`](/opentf/cli/commands/providers/lock) command +Use the [`opentf providers lock`](/docs/cli/commands/providers/lock) command to update the lock file that OpenTF uses to ensure predictable runs when using ambiguous provider version constraints. diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx index ba7f33d87b..d1a7307a7c 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.mdx @@ -7,7 +7,7 @@ description: 'Learn about commands for core provisioning tasks: plan, apply, and OpenTF's primary function is to create, modify, and destroy infrastructure resources to match the desired state described in a -[OpenTF configuration](/opentf/language). +[OpenTF configuration](/docs/language). When people refer to "running OpenTF," they generally mean performing these provisioning actions in order to affect real infrastructure objects. The @@ -16,8 +16,8 @@ actions, but these basic provisioning tasks are the core of OpenTF. OpenTF's provisioning workflow relies on three commands: `plan`, `apply`, and `destroy`. All of these commands require an -[initialized](/opentf/cli/init) working directory, and all of them act -only upon the currently selected [workspace](/opentf/cli/workspaces). +[initialized](/docs/cli/init) working directory, and all of them act +only upon the currently selected [workspace](/docs/cli/workspaces). ## Planning @@ -38,7 +38,7 @@ resulting actions are as expected. However, `opentf plan` can also save its plan as a runnable artifact, which `opentf apply` can use to carry out those exact changes. -For details, see [the `opentf plan` command](/opentf/cli/commands/plan). +For details, see [the `opentf plan` command](/docs/cli/commands/plan). ## Applying @@ -54,7 +54,7 @@ running a new plan. You can use this to reliably perform an exact set of pre-approved changes, even if the configuration or the state of the real infrastructure has changed in the minutes since the original plan was created. -For details, see [the `opentf apply` command](/opentf/cli/commands/apply). +For details, see [the `opentf apply` command](/docs/cli/commands/apply). ## Destroying @@ -68,4 +68,4 @@ and then running an apply, except that it doesn't require editing the configuration. This is more convenient if you intend to provision similar resources at a later date. -For details, see [the `opentf destroy` command](/opentf/cli/commands/destroy). +For details, see [the `opentf destroy` command](/docs/cli/commands/destroy). diff --git a/website/docs/cli/state/index.mdx b/website/docs/cli/state/index.mdx index e080ebe109..ea3030d1a2 100644 --- a/website/docs/cli/state/index.mdx +++ b/website/docs/cli/state/index.mdx @@ -7,7 +7,7 @@ description: >- # Manipulating OpenTF State -OpenTF uses [state data](/opentf/language/state) to remember which +OpenTF uses [state data](/docs/language/state) to remember which real-world object corresponds to each resource in the configuration; this allows it to modify an existing object when its resource declaration changes. @@ -19,12 +19,12 @@ infrastructure. OpenTF CLI supports several workflows for interacting with state: -- [Inspecting State](/opentf/cli/state/inspect) -- [Forcing Re-creation](/opentf/cli/state/taint) -- [Moving Resources](/opentf/cli/state/move) +- [Inspecting State](/docs/cli/state/inspect) +- [Forcing Re-creation](/docs/cli/state/taint) +- [Moving Resources](/docs/cli/state/move) - Importing Pre-existing Resources (documented in the - [Importing Infrastructure](/opentf/cli/import) section) -- [Disaster Recovery](/opentf/cli/state/recover) + [Importing Infrastructure](/docs/cli/import) section) +- [Disaster Recovery](/docs/cli/state/recover) ~> **Important:** Modifying state data outside a normal plan or apply can cause OpenTF to lose track of managed resources, which might waste money, annoy diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.mdx index bee9216a84..37ee9f186b 100644 --- a/website/docs/cli/state/inspect.mdx +++ b/website/docs/cli/state/inspect.mdx @@ -8,14 +8,14 @@ description: Commands that allow you to read and update state. OpenTF includes some commands for reading and updating state without taking any other actions. -- [The `opentf state list` command](/opentf/cli/commands/state/list) +- [The `opentf state list` command](/docs/cli/commands/state/list) shows the resource addresses for every resource OpenTF knows about in a configuration, optionally filtered by partial resource address. -- [The `opentf state show` command](/opentf/cli/commands/state/show) +- [The `opentf state show` command](/docs/cli/commands/state/show) displays detailed state data about one resource. -- [The `opentf refresh` command](/opentf/cli/commands/refresh) updates +- [The `opentf refresh` command](/docs/cli/commands/refresh) updates state data to match the real-world condition of the managed resources. This is done automatically during plans and applies, but not when interacting with state directly. diff --git a/website/docs/cli/state/move.mdx b/website/docs/cli/state/move.mdx index 5fdea47303..b8e524a91c 100644 --- a/website/docs/cli/state/move.mdx +++ b/website/docs/cli/state/move.mdx @@ -8,7 +8,7 @@ description: >- # Moving Resources OpenTF's state associates each real-world object with a configured resource -at a specific [resource address](/opentf/cli/state/resource-addressing). This +at a specific [resource address](/docs/cli/state/resource-addressing). This is seamless when changing a resource's attributes, but OpenTF will lose track of a resource if you change its name, move it to a different module, or change its provider. @@ -22,24 +22,24 @@ can explicitly tell OpenTF to associate it with a different configured resource. For most cases we recommend using -[the OpenTF language's refactoring features](/opentf/language/modules/develop/refactoring) +[the OpenTF language's refactoring features](/docs/language/modules/develop/refactoring) to document in your module exactly how the resource names have changed over time. OpenTF reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps. There are some other situations which require explicit state modifications, though. For those, consider the following OpenTF commands: -- [The `opentf state mv` command](/opentf/cli/commands/state/mv) changes +- [The `opentf state mv` command](/docs/cli/commands/state/mv) changes which resource address in your configuration is associated with a particular real-world object. Use this to preserve an object when renaming a resource, or when moving a resource into or out of a child module. -- [The `opentf state rm` command](/opentf/cli/commands/state/rm) tells +- [The `opentf state rm` command](/docs/cli/commands/state/rm) tells OpenTF 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 `opentf import` to start managing that resource in a different workspace or a different OpenTF configuration.) -- [The `opentf state replace-provider` command](/opentf/cli/commands/state/replace-provider) +- [The `opentf state replace-provider` command](/docs/cli/commands/state/replace-provider) transfers existing resources to a new provider without requiring them to be re-created. diff --git a/website/docs/cli/state/recover.mdx b/website/docs/cli/state/recover.mdx index b54790164f..9e99d551f1 100644 --- a/website/docs/cli/state/recover.mdx +++ b/website/docs/cli/state/recover.mdx @@ -11,7 +11,7 @@ If something has gone horribly wrong (possibly due to accidents when performing other state manipulation actions), you might need to take drastic actions with your state data. -- [The `opentf force-unlock` command](/opentf/cli/commands/force-unlock) can +- [The `opentf force-unlock` command](/docs/cli/commands/force-unlock) can override the protections OpenTF uses to prevent two processes from modifying state at the same time. You might need this if a OpenTF process (like a normal apply) is unexpectedly terminated (like by the complete @@ -19,7 +19,7 @@ your state data. state backend. Do not run this until you are completely certain what happened to the process that caused the lock to get stuck. -- [The `opentf state pull` command](/opentf/cli/commands/state/pull) and - [the `opentf state push` command](/opentf/cli/commands/state/push) can +- [The `opentf state pull` command](/docs/cli/commands/state/pull) and + [the `opentf state push` command](/docs/cli/commands/state/push) can directly read and write entire state files from and to the configured backend. You might need this for obtaining or restoring a state backup. diff --git a/website/docs/cli/state/taint.mdx b/website/docs/cli/state/taint.mdx index 18ff36e1c5..05fcfedec3 100644 --- a/website/docs/cli/state/taint.mdx +++ b/website/docs/cli/state/taint.mdx @@ -18,7 +18,7 @@ to the problem, because OpenTF only directly manages the machine as a whole. If you know that an object is damaged, or if you want to force OpenTF to replace it for any other reason, you can override OpenTF's default behavior -using [the `-replace=...` planning option](/opentf/cli/commands/plan#replace-address) +using [the `-replace=...` planning option](/docs/cli/commands/plan#replace-address) when you run either `opentf plan` or `opentf apply`: ```shellsession @@ -53,11 +53,11 @@ address using `-replace=...` as described above. If OpenTF has marked an object as tainted but you consider it to be working correctly and do not want to replace it, you can override OpenTF's -determination using [the `opentf untaint` command](/opentf/cli/commands/untaint), +determination using [the `opentf untaint` command](/docs/cli/commands/untaint), after which OpenTF will consider the object to be ready for use by any downstream resource declarations. You can also _force_ OpenTF to mark a particular object as tainted using -[the `opentf taint` command](/opentf/cli/commands/taint), but that approach is +[the `opentf taint` command](/docs/cli/commands/taint), but that approach is deprecated in favor of the `-replace=...` option, which avoids the need to create an interim state snapshot with a tainted object. diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx index 4c0e69bc63..bee0941973 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -7,7 +7,7 @@ description: >- # Managing Workspaces -Workspaces in the OpenTF CLI refer to separate instances of [state data](/opentf/language/state) inside the same OpenTF working directory. They are distinctly different from workspaces in a cloud backend, which each have their own OpenTF configuration and function as separate working directories. +Workspaces in the OpenTF CLI refer to separate instances of [state data](/docs/language/state) inside the same OpenTF working directory. They are distinctly different from workspaces in a cloud backend, which each have their own OpenTF configuration and function as separate working directories. OpenTF relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, OpenTF can manage multiple sets of non-overlapping resources. @@ -16,18 +16,18 @@ Workspaces can be helpful for specific [use cases](#use-cases), but they are not ## Managing CLI Workspaces -Every [initialized working directory](/opentf/cli/init) starts with one workspace named `default`. +Every [initialized working directory](/docs/cli/init) starts with one workspace named `default`. -Use the [`opentf workspace list`](/opentf/cli/commands/workspace/list), [`opentf workspace new`](/opentf/cli/commands/workspace/new), and [`opentf workspace delete`](/opentf/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory. +Use the [`opentf workspace list`](/docs/cli/commands/workspace/list), [`opentf workspace new`](/docs/cli/commands/workspace/new), and [`opentf workspace delete`](/docs/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory. -Use [the `opentf workspace select` command](/opentf/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most OpenTF commands only interact with the currently selected workspace. This includes [provisioning](/opentf/cli/run) and [state manipulation](/opentf/cli/state). +Use [the `opentf workspace select` command](/docs/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most OpenTF commands only interact with the currently selected workspace. This includes [provisioning](/docs/cli/run) and [state manipulation](/docs/cli/state). -When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/opentf/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region. +When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/docs/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region. ## Use Cases -You can create multiple [working directories](/opentf/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, OpenTF installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches. +You can create multiple [working directories](/docs/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, OpenTF installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches. A common use for multiple workspaces is to create a parallel, distinct copy of a set of infrastructure to test a set of changes before modifying production infrastructure. @@ -48,7 +48,7 @@ development stages or different internal teams. In this case, the backend for ea ## Alternatives to Workspaces -Instead of creating CLI workspaces, you can use one or more [re-usable modules](/opentf/language/modules/develop) to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different [backend](/opentf/language/settings/backends/configuration). The root module of each configuration consists only of a backend configuration and a small number of `module` blocks with arguments describing any small differences between the deployments. +Instead of creating CLI workspaces, you can use one or more [re-usable modules](/docs/language/modules/develop) to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different [backend](/docs/language/settings/backends/configuration). The root module of each configuration consists only of a backend configuration and a small number of `module` blocks with arguments describing any small differences between the deployments. When multiple configurations represent distinct system components rather than multiple deployments, you can pass data from one component to another using paired resources types and data sources. @@ -58,7 +58,7 @@ When multiple configurations represent distinct system components rather than mu - For server addresses, use a provider-specific resource to create a DNS record with a predictable name. Then you can either use that name directly or use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve the published addresses in other configurations. -- If you store a OpenTF state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/opentf/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system. +- If you store a OpenTF state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/docs/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system. ## Workspace Internals @@ -68,6 +68,6 @@ Workspaces are also meant to be a shared resource. They are not private, unless For local state, OpenTF stores the workspace states in a directory called `terraform.tfstate.d`. This directory should be treated similarly to local-only `terraform.tfstate`. Some teams commit these files to version control, but we recommend using a remote backend instead when there are multiple collaborators. -For [remote state](/opentf/language/state/remote), the workspaces are stored directly in the configured [backend](/opentf/language/settings/backends/configuration). For example, if you use [Consul](/opentf/language/settings/backends/consul), the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping. +For [remote state](/docs/language/state/remote), the workspaces are stored directly in the configured [backend](/docs/language/settings/backends/configuration). For example, if you use [Consul](/docs/language/settings/backends/consul), the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping. -OpenTF stores the current workspace name locally in the ignored `.terraform` directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in a cloud backend. For more details about workspace names in cloud backends, refer to the [CLI Integration (recommended)](/opentf/cli/cloud/settings#arguments) and [remote backend](/opentf/language/settings/backends/remote#workspaces) and documentation. +OpenTF stores the current workspace name locally in the ignored `.terraform` directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in a cloud backend. For more details about workspace names in cloud backends, refer to the [CLI Integration (recommended)](/docs/cli/cloud/settings#arguments) and [remote backend](/docs/language/settings/backends/remote#workspaces) and documentation. diff --git a/website/docs/internals/credentials-helpers.mdx b/website/docs/internals/credentials-helpers.mdx index 3ea3b1eaec..9310cbbe2b 100644 --- a/website/docs/internals/credentials-helpers.mdx +++ b/website/docs/internals/credentials-helpers.mdx @@ -8,9 +8,9 @@ description: >- # Credentials Helpers For OpenTF-specific features that interact with remote network services, -such as [module registries](/opentf/registry), OpenTF by default looks for +such as [module registries](/docs/registry), OpenTF by default looks for API credentials to use in these calls in -[the CLI configuration](/opentf/cli/config/config-file). +[the CLI configuration](/docs/cli/config/config-file). Credentials helpers offer an alternative approach that allows you to customize how OpenTF obtains credentials using an external program, which can then @@ -18,7 +18,7 @@ directly access an existing secrets management system in your organization. This page is about how to write and install a credentials helper. To learn how to configure a credentials helper that was already installed, see -[the CLI config Credentials Helpers section](/opentf/cli/config/config-file#credentials-helpers). +[the CLI config Credentials Helpers section](/docs/cli/config/config-file#credentials-helpers). ## How OpenTF finds Credentials Helpers @@ -28,7 +28,7 @@ particular location and whose name follows a specific naming convention. A credentials helper called "credstore", for example, would be implemented as an executable program named `terraform-credentials-credstore` (with an `.exe` extension on Windows only), and installed in one of the -[default plugin search locations](/opentf/plugin/how-opentf-works#plugin-locations). +[default plugin search locations](/docs/plugin/how-opentf-works#plugin-locations). ## How OpenTF runs Credentials Helpers @@ -55,7 +55,7 @@ The current set of verbs are: To represent credentials, the credentials helper protocol uses a JSON object whose contents correspond with the contents of -[`credentials` blocks in the CLI configuration](/opentf/cli/config/config-file#credentials). +[`credentials` blocks in the CLI configuration](/docs/cli/config/config-file#credentials). To represent an API token, the object contains a property called "token" whose value is the token string: @@ -158,7 +158,7 @@ other properties as described above. OpenTF does not have any automatic installation mechanism for credentials helpers. Instead, the user must extract the helper program executable into -one of the [default plugin search locations](/opentf/plugin/how-opentf-works#plugin-locations). +one of the [default plugin search locations](/docs/plugin/how-opentf-works#plugin-locations). If you are packaging a credentials helper for distribution, place it in an named with the expected naming scheme (`terraform-credentials-example`) and, diff --git a/website/docs/internals/functions-meta.mdx b/website/docs/internals/functions-meta.mdx index 4da07a97ff..648dafabc5 100644 --- a/website/docs/internals/functions-meta.mdx +++ b/website/docs/internals/functions-meta.mdx @@ -30,7 +30,7 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises). ## Format Summary diff --git a/website/docs/internals/graph.mdx b/website/docs/internals/graph.mdx index 551d589d79..254c25b12a 100644 --- a/website/docs/internals/graph.mdx +++ b/website/docs/internals/graph.mdx @@ -110,8 +110,8 @@ The amount of parallelism is limited using a semaphore to prevent too many concurrent operations from overwhelming the resources of the machine running OpenTF. By default, up to 10 nodes in the graph will be processed concurrently. This number can be set using the `-parallelism` flag on the -[plan](/opentf/cli/commands/plan), [apply](/opentf/cli/commands/apply), and -[destroy](/opentf/cli/commands/destroy) commands. +[plan](/docs/cli/commands/plan), [apply](/docs/cli/commands/apply), and +[destroy](/docs/cli/commands/destroy) commands. Setting `-parallelism` is considered an advanced operation and should not be necessary for normal usage of OpenTF. It may be helpful in certain special diff --git a/website/docs/internals/json-format.mdx b/website/docs/internals/json-format.mdx index 9780e7c0f8..80b75e4e7c 100644 --- a/website/docs/internals/json-format.mdx +++ b/website/docs/internals/json-format.mdx @@ -11,7 +11,7 @@ When OpenTF plans to make changes, it prints a human-readable summary to the ter Since the format of plan files isn't suited for use with external tools (and likely never will be), OpenTF can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. -Use `opentf show -json ` to generate a JSON representation of a plan or state file. See [the `opentf show` documentation](/opentf/cli/commands/show) for more details. +Use `opentf show -json ` to generate a JSON representation of a plan or state file. See [the `opentf show` documentation](/docs/cli/commands/show) for more details. The output includes a `format_version` key, which has value `"1.0"`. The semantics of this version are: @@ -24,7 +24,7 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises). ## Format Summary @@ -341,7 +341,7 @@ The following example illustrates the structure of a ``: } ``` -The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by OpenTF's [`jsonencode`](/opentf/language/functions/jsonencode) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null. +The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by OpenTF's [`jsonencode`](/docs/language/functions/jsonencode) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null. Output values include a `"type"` field, which is a [serialization of the value's type](https://pkg.go.dev/github.com/zclconf/go-cty/cty#Type.MarshalJSON). For primitive types this is a string value, such as `"number"` or `"bool"`. Complex types are represented as a nested JSON array, such as `["map","string"]` or `["object",{"a":"number"}]`. This can be used to reconstruct the output value with the correct type. diff --git a/website/docs/internals/login-protocol.mdx b/website/docs/internals/login-protocol.mdx index 2964c3b224..322e075908 100644 --- a/website/docs/internals/login-protocol.mdx +++ b/website/docs/internals/login-protocol.mdx @@ -8,18 +8,18 @@ description: >- # Server-side Login Protocol ~> **Note:** You don't need to read these docs to _use_ -[`opentf login`](/opentf/cli/commands/login). The information below is for +[`opentf login`](/docs/cli/commands/login). The information below is for anyone intending to implement the server side of `opentf login` in order to offer OpenTF-native services in a third-party system. The `opentf login` command supports performing an OAuth 2.0 authorization request using configuration provided by the target host. You may wish to implement this protocol if you are producing a third-party implementation of -any [OpenTF-native services](/opentf/internals/remote-service-discovery), +any [OpenTF-native services](/docs/internals/remote-service-discovery), such as an OpenTF module registry. First, OpenTF uses -[remote service discovery](/opentf/internals/remote-service-discovery) to +[remote service discovery](/docs/internals/remote-service-discovery) to find the OAuth configuration for the host. The host must support the service name `login.v1` and define for it an object containing OAuth client configuration values, like this: diff --git a/website/docs/internals/machine-readable-ui.mdx b/website/docs/internals/machine-readable-ui.mdx index b44f02fc77..4cca62d2d5 100644 --- a/website/docs/internals/machine-readable-ui.mdx +++ b/website/docs/internals/machine-readable-ui.mdx @@ -22,7 +22,7 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises). ## Sample JSON Output @@ -58,7 +58,7 @@ The following message types are supported: - `version`: information about the OpenTF version and the version of the schema used for the following messages - `log`: unstructured human-readable log lines -- `diagnostic`: diagnostic warning or error messages; [see the `opentf validate` docs for more details on the format](/opentf/cli/commands/validate#json) +- `diagnostic`: diagnostic warning or error messages; [see the `opentf validate` docs for more details on the format](/docs/cli/commands/validate#json) ### Operation Results @@ -101,7 +101,7 @@ If drift is detected during planning, OpenTF will emit a `resource_drift` messag - `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details - `action`: the action planned to be taken for the resource. Values: `update`, `delete`. -This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](/opentf/internals/json-format). +This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](/docs/internals/json-format). ### Example @@ -144,7 +144,7 @@ At the end of a plan or before an apply, OpenTF will emit a `planned_change` mes - `delete_because_each_key`: resource instance key is not included in the `for_each` argument - `delete_because_no_module`: enclosing module instance is not in configuration -This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](/opentf/internals/json-format). +This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](/docs/internals/json-format). ### Example diff --git a/website/docs/internals/module-registry-protocol.mdx b/website/docs/internals/module-registry-protocol.mdx index f41a7cc4c9..7555803335 100644 --- a/website/docs/internals/module-registry-protocol.mdx +++ b/website/docs/internals/module-registry-protocol.mdx @@ -21,7 +21,7 @@ publishing them on the public Terraform Registry. The public Terraform Registry implements a superset of the API described on this page, in order to capture additional information used in the registry UI. For information on those extensions, see -[OpenTF Registry HTTP API](/opentf/registry/api-docs). Third-party registry +[OpenTF Registry HTTP API](/docs/registry/api-docs). Third-party registry implementations may choose to implement those extensions if desired, but OpenTF CLI itself does not use them. @@ -79,7 +79,7 @@ blocks have the same source address. ## Service Discovery The module registry protocol begins with OpenTF CLI using -[OpenTF's remote service discovery protocol](/opentf/internals/remote-service-discovery), +[OpenTF's remote service discovery protocol](/docs/internals/remote-service-discovery), with the hostname in the module address acting as the "User-facing Hostname". The service identifier for the module registry protocol is `modules.v1`. @@ -207,10 +207,10 @@ A successful response has no body, and includes the location from which the module version's source can be downloaded in the `X-Terraform-Get` header. The value of this header accepts the same values as the `source` argument in a `module` block in OpenTF configuration, as described in -[Module Sources](/opentf/language/modules/sources), +[Module Sources](/docs/language/modules/sources), except that it may not recursively refer to another module registry address. The value of `X-Terraform-Get` may instead be a relative URL, indicated by beginning with `/`, `./` or `../`, in which case it is resolved relative to the full URL of the download endpoint to produce -[an HTTP URL module source](/opentf/language/modules/sources#http-urls). +[an HTTP URL module source](/docs/language/modules/sources#http-urls). diff --git a/website/docs/internals/provider-network-mirror-protocol.mdx b/website/docs/internals/provider-network-mirror-protocol.mdx index 4ea2b6fe56..30bf81dc4f 100644 --- a/website/docs/internals/provider-network-mirror-protocol.mdx +++ b/website/docs/internals/provider-network-mirror-protocol.mdx @@ -14,7 +14,7 @@ implement to provide an alternative installation source for Terraform providers, regardless of their origin registries. OpenTF uses network mirrors only if you activate them explicitly in -[the CLI configuration's `provider_installation` block](/opentf/cli/config/config-file#provider-installation). +[the CLI configuration's `provider_installation` block](/docs/cli/config/config-file#provider-installation). When enabled, a network mirror can serve providers belonging to any registry hostname, which can allow an organization to serve all of the OpenTF providers they intend to use from an internal server, rather than from each @@ -24,7 +24,7 @@ This is _not_ the protocol that should be implemented by a host intending to serve as an origin registry for OpenTF Providers. To provide an origin registry (whose hostname would then be included in the source addresses of the providers it hosts), implement -[the provider registry protocol](/opentf/internals/provider-registry-protocol) +[the provider registry protocol](/docs/internals/provider-registry-protocol) instead. ## Provider Addresses @@ -32,7 +32,7 @@ instead. Each OpenTF provider has an associated address which uniquely identifies it within OpenTF. A provider address has the syntax `hostname/namespace/type`, which is described in more detail in -[the Provider Requirements documentation](/opentf/language/providers/requirements). +[the Provider Requirements documentation](/docs/language/providers/requirements). By default, the `hostname` portion of a provider address serves both as part of its unique identifier _and_ as the location of the registry to retrieve it @@ -50,7 +50,7 @@ the hostname where the provider network mirror is deployed. ## Protocol Base URL Most OpenTF-native services use -[the remote service discovery protocol](/opentf/internals/remote-service-discovery) so +[the remote service discovery protocol](/docs/internals/remote-service-discovery) so that the physical location of the endpoints can potentially be separated from the hostname used in identifiers. The Provider Network Mirror protocol does _not_ use the service discovery indirection, because a network mirror location @@ -92,7 +92,7 @@ base URL from the above CLI configuration example. ### Authentication If the CLI configuration includes -[credentials](/opentf/cli/config/config-file#credentials) for the hostname +[credentials](/docs/cli/config/config-file#credentials) for the hostname given in the network mirror base URL, OpenTF will include those credentials in its requests for operations described below. @@ -256,7 +256,7 @@ in the appropriate nested subdirectories, and ensure that your system is configured to serve `.json` files with the `application/json` media type. As a convenience, OpenTF CLI includes -[the `opentf providers mirror` subcommand](/opentf/cli/commands/providers/mirror), +[the `opentf providers mirror` subcommand](/docs/cli/commands/providers/mirror), which will analyze the current configuration for the providers it requires, download the packages for those providers from their origin registries, and place them into a local directory suitable for use as a mirror. diff --git a/website/docs/internals/provider-registry-protocol.mdx b/website/docs/internals/provider-registry-protocol.mdx index deda469d64..90c8e8d190 100644 --- a/website/docs/internals/provider-registry-protocol.mdx +++ b/website/docs/internals/provider-registry-protocol.mdx @@ -33,7 +33,7 @@ where: * `hostname` is the registry host that the provider is considered to have originated from, and the default location OpenTF will consult for information about the provider - [unless overridden in the CLI configuration](/opentf/cli/config/config-file#provider-installation). + [unless overridden in the CLI configuration](/docs/cli/config/config-file#provider-installation). * `namespace` is the name of a namespace, unique on a particular hostname, that can contain one or more providers that are somehow related. On the public Terraform Registry the "namespace" represents the organization that is @@ -69,7 +69,7 @@ to see it as an entirely separate provider that will _not_ be usable by modules that declare a dependency on `hashicorp/azurerm`. If your goal is to create an alternative local distribution source for an existing provider -- that is, a _mirror_ of the provider -- refer to -[the provider installation method configuration](/opentf/cli/config/config-file#provider-installation) +[the provider installation method configuration](/docs/cli/config/config-file#provider-installation) instead. ## Provider Versions @@ -89,7 +89,7 @@ version selection. ## Service Discovery The providers protocol begins with OpenTF CLI using -[OpenTF's remote service discovery protocol](/opentf/internals/remote-service-discovery), +[OpenTF's remote service discovery protocol](/docs/internals/remote-service-discovery), with the hostname in the provider address acting as the "User-facing Hostname". The service identifier for the provider registry protocol is `providers.v1`. diff --git a/website/docs/internals/remote-service-discovery.mdx b/website/docs/internals/remote-service-discovery.mdx index 8d045463b3..73a3923dd0 100644 --- a/website/docs/internals/remote-service-discovery.mdx +++ b/website/docs/internals/remote-service-discovery.mdx @@ -83,14 +83,14 @@ version 1 of the module registry protocol: At present, the following service identifiers are in use: -* `login.v1`: [login protocol version 1](/opentf/cli/commands/login) -* `modules.v1`: [module registry API version 1](/opentf/internals/module-registry-protocol) -* `providers.v1`: [provider registry API version 1](/opentf/internals/provider-registry-protocol) +* `login.v1`: [login protocol version 1](/docs/cli/commands/login) +* `modules.v1`: [module registry API version 1](/docs/internals/module-registry-protocol) +* `providers.v1`: [provider registry API version 1](/docs/internals/provider-registry-protocol) ## Authentication If credentials for the given hostname are available in -[the CLI config](/opentf/cli/config/config-file#Credentials) through a `credentials_helper` or a host-specific environment variable, then they will be included in the request for the discovery document. +[the CLI config](/docs/cli/config/config-file#Credentials) through a `credentials_helper` or a host-specific environment variable, then they will be included in the request for the discovery document. The credentials may also be provided to endpoints declared in the discovery document, depending on the requirements of the service in question. diff --git a/website/docs/intro/index.mdx b/website/docs/intro/index.mdx index 02709db32a..a164bed37f 100644 --- a/website/docs/intro/index.mdx +++ b/website/docs/intro/index.mdx @@ -29,11 +29,11 @@ The core OpenTF workflow consists of three stages: ### Manage any infrastructure -Find providers for many of the platforms and services you already use in the [Public Terraform Registry](https://registry.terraform.io/). You can also [write your own](/opentf/plugin). OpenTF takes an [immutable approach to infrastructure](https://www.hashicorp.com/resources/what-is-mutable-vs-immutable-infrastructure), reducing the complexity of upgrading or modifying your services and infrastructure. +Find providers for many of the platforms and services you already use in the [Public Terraform Registry](https://registry.terraform.io/). You can also [write your own](/docs/plugin). OpenTF takes an [immutable approach to infrastructure](https://www.hashicorp.com/resources/what-is-mutable-vs-immutable-infrastructure), reducing the complexity of upgrading or modifying your services and infrastructure. ### Track your infrastructure -OpenTF generates a plan and prompts you for your approval before modifying your infrastructure. It also keeps track of your real infrastructure in a [state file](/opentf/language/state), which acts as a source of truth for your environment. OpenTF uses the state file to determine the changes to make to your infrastructure so that it will match your configuration. +OpenTF generates a plan and prompts you for your approval before modifying your infrastructure. It also keeps track of your real infrastructure in a [state file](/docs/language/state), which acts as a source of truth for your environment. OpenTF uses the state file to determine the changes to make to your infrastructure so that it will match your configuration. ### Automate changes @@ -41,13 +41,13 @@ OpenTF configuration files are declarative, meaning that they describe the end s ### Standardize configurations -OpenTF supports reusable configuration components called [modules](/opentf/language/modules) that define configurable collections of infrastructure, saving time and encouraging best practices. You can use publicly available modules from the Terraform Registry, or write your own. +OpenTF supports reusable configuration components called [modules](/docs/language/modules) that define configurable collections of infrastructure, saving time and encouraging best practices. You can use publicly available modules from the Terraform Registry, or write your own. ### Collaborate Since your configuration is written in a file, you can commit it to a Version Control System (VCS) and use a cloud backend to efficiently manage OpenTF workflows across teams. A cloud backend runs OpenTF in a consistent, reliable environment and provides secure access to shared state and secret data, role-based access controls, a private registry for sharing both modules and providers, and more. --> **Tip:** Learn more about [OpenTF use cases](/opentf/intro/use-cases) and [how OpenTF compares to alternatives](/opentf/intro/vs). +-> **Tip:** Learn more about [OpenTF use cases](/docs/intro/use-cases) and [how OpenTF compares to alternatives](/docs/intro/vs). ## Community diff --git a/website/docs/intro/use-cases.mdx b/website/docs/intro/use-cases.mdx index 366d6cae68..01f2d9535a 100644 --- a/website/docs/intro/use-cases.mdx +++ b/website/docs/intro/use-cases.mdx @@ -8,7 +8,7 @@ description: |- # Use Cases -[OpenTF](/opentf/intro) is an infrastructure as code tool that lets you define infrastructure resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to safely and efficiently provision and manage your infrastructure throughout its lifecycle. +[OpenTF](/docs/intro) is an infrastructure as code tool that lets you define infrastructure resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to safely and efficiently provision and manage your infrastructure throughout its lifecycle. This page describes popular OpenTF use cases and provides related resources that you can use to create OpenTF configurations and workflows. diff --git a/website/docs/intro/vs/index.mdx b/website/docs/intro/vs/index.mdx index cb9579d69e..6cee2dfc3e 100644 --- a/website/docs/intro/vs/index.mdx +++ b/website/docs/intro/vs/index.mdx @@ -16,7 +16,7 @@ entire datacenter. Learn how OpenTF compares to: -- [Chef, Puppet, etc.](/opentf/intro/vs/chef-puppet) -- [CloudFormation, Heat, etc.](/opentf/intro/vs/cloudformation) -- [Boto, Fog, etc.](/opentf/intro/vs/boto) -- [Custom Solutions](/opentf/intro/vs/custom) +- [Chef, Puppet, etc.](/docs/intro/vs/chef-puppet) +- [CloudFormation, Heat, etc.](/docs/intro/vs/cloudformation) +- [Boto, Fog, etc.](/docs/intro/vs/boto) +- [Custom Solutions](/docs/intro/vs/custom) diff --git a/website/docs/language/attr-as-blocks.mdx b/website/docs/language/attr-as-blocks.mdx index 837430d776..ce1c9d323b 100644 --- a/website/docs/language/attr-as-blocks.mdx +++ b/website/docs/language/attr-as-blocks.mdx @@ -23,14 +23,14 @@ is set to an empty list (` = []`). Most users do not need to know any further details of this "nested block or empty list" behavior. However, read further if you need to: -- Use OpenTF's [JSON syntax](/opentf/language/syntax/json) with this +- Use OpenTF's [JSON syntax](/docs/language/syntax/json) with this type of resource. - Create a reusable module that wraps this type of resource. ## Details The language makes a distinction between -[argument syntax and nested block syntax](/opentf/language/syntax/configuration#arguments-and-blocks) +[argument syntax and nested block syntax](/docs/language/syntax/configuration#arguments-and-blocks) within blocks: - Argument syntax sets a named argument for the containing object. If the @@ -44,7 +44,7 @@ within blocks: merging in with any explicitly-defined arguments. The distinction between these is particularly important for -[JSON syntax](/opentf/language/syntax/json) +[JSON syntax](/docs/language/syntax/json) because the same primitive JSON constructs (lists and objects) will be interpreted differently depending on whether a particular name is an argument or a nested block type. @@ -138,7 +138,7 @@ example = [ For the arguments that use the attributes-as-blocks usage mode, the above is a better pattern than using -[`dynamic` blocks](/opentf/language/expressions/dynamic-blocks) +[`dynamic` blocks](/docs/language/expressions/dynamic-blocks) because the case where the caller provides an empty list will result in explicitly assigning an empty list value, rather than assigning no value at all and thus retaining and @@ -148,7 +148,7 @@ dynamically-generating _normal_ nested blocks, though. ## In JSON syntax Arguments that use this special mode are specified in JSON syntax always using -the [JSON expression mapping](/opentf/language/syntax/json#expression-mapping) +the [JSON expression mapping](/docs/language/syntax/json#expression-mapping) to produce a list of objects. The interpretation of these values in JSON syntax is, therefore, equivalent diff --git a/website/docs/language/checks/index.mdx b/website/docs/language/checks/index.mdx index 90e86fef8e..c6d0a597ac 100644 --- a/website/docs/language/checks/index.mdx +++ b/website/docs/language/checks/index.mdx @@ -8,7 +8,7 @@ description: >- The `check` block can validate your infrastructure outside the usual resource lifecycle. Check blocks address a gap between post-apply and functional validation of infrastructure. -Check blocks allow you to define [custom conditions](/opentf/language/expressions/custom-conditions) that execute on every OpenTF plan or apply operation without affecting the overall status of an operation. Check blocks execute as the last step of a plan or apply after OpenTF has planned or provisioned your infrastructure. +Check blocks allow you to define [custom conditions](/docs/language/expressions/custom-conditions) that execute on every OpenTF plan or apply operation without affecting the overall status of an operation. Check blocks execute as the last step of a plan or apply after OpenTF has planned or provisioned your infrastructure. ## Syntax @@ -33,13 +33,13 @@ check "health_check" { You can use any data source from any provider as a scoped data source within a `check` block. -A `check` block can optionally contain a nested (a.k.a. scoped) data source. This `data` block behaves like an external [data source](/opentf/language/data-sources), except you can not reference it outside its enclosing `check` block. Additionally, if a scoped data source's provider raises any errors, they are masked as warnings and do not prevent OpenTF from continuing operation execution. +A `check` block can optionally contain a nested (a.k.a. scoped) data source. This `data` block behaves like an external [data source](/docs/language/data-sources), except you can not reference it outside its enclosing `check` block. Additionally, if a scoped data source's provider raises any errors, they are masked as warnings and do not prevent OpenTF from continuing operation execution. You can use a scoped data source to validate the status of a piece of infrastructure outside of the usual OpenTF resource lifecycle. [In the above example](#syntax), if the `placeholderplaceholderplaceholder_io` data source fails to load, you receive a warning instead of a blocking error, which would occur if you declared this data source outside of a `check` block. #### Meta-Arguments -Scoped data sources support the `depends_on` and `provider` [meta-arguments](/opentf/language/resources/syntax#meta-arguments). Scoped data sources do not support the `count` or`for_each` meta-arguments. +Scoped data sources support the `depends_on` and `provider` [meta-arguments](/docs/language/resources/syntax#meta-arguments). Scoped data sources do not support the `count` or`for_each` meta-arguments. ##### `depends_on` @@ -47,7 +47,7 @@ The `depends_on` meta-argument can be particularly powerful when used within sco The first time OpenTF creates the _initial_ plan for our [previous example](#syntax), the plan fails because OpenTF has not applied its configuration yet. Meaning this test fails because OpenTF must still create the resources to make this website exist. Therefore, the first time OpenTF runs this check, it always throws a potentially distracting error message. -You can fix this by adding [`depends_on`](/opentf/language/meta-arguments/depends_on) to your scoped data source, ensuring it depends on an essential piece of your site's infrastructure, such as the load balancer. The check returns `known after apply` until that crucial piece of your website is ready. This strategy avoids producing unnecessary warnings during setup, and the check executes during subsequent plans and applies. +You can fix this by adding [`depends_on`](/docs/language/meta-arguments/depends_on) to your scoped data source, ensuring it depends on an essential piece of your site's infrastructure, such as the load balancer. The check returns `known after apply` until that crucial piece of your website is ready. This strategy avoids producing unnecessary warnings during setup, and the check executes during subsequent plans and applies. One problem with this strategy is that if the resource your scoped data source `depends_on` changes, the check block returns `known after apply` until OpenTF has updated that resource. Depending on your use case, this behavior could be acceptable or problematic. @@ -55,17 +55,17 @@ We recommend implementing the `depends_on` meta-argument if your scoped data sou ### Assertions -Check blocks validate your custom assertions using `assert` blocks. Each `check` block must have at least one, but potentially many, `assert` blocks. Each `assert` block has a [`condition` attribute](/opentf/language/expressions/custom-conditions#condition-expressions) and an [`error_message` attribute](/opentf/language/expressions/custom-conditions#error-messages). +Check blocks validate your custom assertions using `assert` blocks. Each `check` block must have at least one, but potentially many, `assert` blocks. Each `assert` block has a [`condition` attribute](/docs/language/expressions/custom-conditions#condition-expressions) and an [`error_message` attribute](/docs/language/expressions/custom-conditions#error-messages). -Unlike other [custom conditions](/opentf/language/expressions/custom-conditions), assertions do not affect OpenTF's execution of an operation. A failed assertion reports a warning without halting the ongoing operation. This contrasts with other custom conditions, such as a postcondition, where OpenTF produces an error immediately, halting the operation and blocking the application or planning of future resources. +Unlike other [custom conditions](/docs/language/expressions/custom-conditions), assertions do not affect OpenTF's execution of an operation. A failed assertion reports a warning without halting the ongoing operation. This contrasts with other custom conditions, such as a postcondition, where OpenTF produces an error immediately, halting the operation and blocking the application or planning of future resources. Condition arguments within `assert` blocks can refer to scoped data sources within the enclosing `check` block and any variables, resources, data sources, or module outputs within the current module. -[Learn more about assertions](/opentf/language/expressions/custom-conditions#checks-with-assertions). +[Learn more about assertions](/docs/language/expressions/custom-conditions#checks-with-assertions). ### Meta-Arguments -Check blocks do not currently support [meta-arguments](/opentf/language/resources/syntax#meta-arguments). We are still collecting feedback on this feature, so if your use case would benefit from check blocks supporting meta-arguments, please [let us know](https://github.com/placeholderplaceholderplaceholder/opentf/issues/new/choose). +Check blocks do not currently support [meta-arguments](/docs/language/resources/syntax#meta-arguments). We are still collecting feedback on this feature, so if your use case would benefit from check blocks supporting meta-arguments, please [let us know](https://github.com/placeholderplaceholderplaceholder/opentf/issues/new/choose). ## Continuous validation in TACOS (TF Automation and Collaboration Software) @@ -73,13 +73,13 @@ TACOS (TF Automation and Collaboration Software) can automatically validate whet ## Choosing Checks or other Custom Conditions -Check blocks offer the most _flexible_ validation solution within OpenTF. You can reference outputs, variables, resources, and data sources within check assertions. You can also use checks to model every alternate [Custom Condition](/opentf/language/expressions/custom-conditions). However, that does not mean you should replace all your custom conditions with check blocks. +Check blocks offer the most _flexible_ validation solution within OpenTF. You can reference outputs, variables, resources, and data sources within check assertions. You can also use checks to model every alternate [Custom Condition](/docs/language/expressions/custom-conditions). However, that does not mean you should replace all your custom conditions with check blocks. There are major behavioral differences between check block assertions and other custom conditions, the main one being that check blocks do _not_ affect OpenTF's execution of an operation. You can use this non-blocking behavior to decide the best type of validation for your use case. ### Outputs and variables -[Output postconditions](/opentf/language/expressions/custom-conditions#outputs) and [variable validations](/opentf/language/expressions/custom-conditions#input-variable-validation) both make assertions around inputs and outputs. +[Output postconditions](/docs/language/expressions/custom-conditions#outputs) and [variable validations](/docs/language/expressions/custom-conditions#input-variable-validation) both make assertions around inputs and outputs. This is one of the cases where you might want OpenTF to block further execution. @@ -87,9 +87,9 @@ For example, it is not helpful for OpenTF to warn that an input variable is inva ### Resource Preconditions and Postconditions -The difference between [preconditions and postconditions](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) and check blocks is more nuanced. +The difference between [preconditions and postconditions](/docs/language/expressions/custom-conditions#preconditions-and-postconditions) and check blocks is more nuanced. -Preconditions are unique amongst the custom conditions in that they execute _before_ a resource change is applied or planned. [Choosing Between Preconditions and Postconditions](/opentf/language/expressions/custom-conditions#choosing-between-preconditions-and-postconditions) offers guidance on choosing between a precondition and a postcondition, and the same topics also apply to choosing between a precondition and a check block. +Preconditions are unique amongst the custom conditions in that they execute _before_ a resource change is applied or planned. [Choosing Between Preconditions and Postconditions](/docs/language/expressions/custom-conditions#choosing-between-preconditions-and-postconditions) offers guidance on choosing between a precondition and a postcondition, and the same topics also apply to choosing between a precondition and a check block. You can often use postconditions interchangeably with check blocks to validate resources and data sources. diff --git a/website/docs/language/data-sources/index.mdx b/website/docs/language/data-sources/index.mdx index 101e509051..a60c98e1ec 100644 --- a/website/docs/language/data-sources/index.mdx +++ b/website/docs/language/data-sources/index.mdx @@ -11,8 +11,8 @@ description: >- _Data sources_ allow OpenTF to use information defined outside of OpenTF, defined by another separate OpenTF configuration, or modified by functions. -Each [provider](/opentf/language/providers) may offer data sources -alongside its set of [resource](/opentf/language/resources) +Each [provider](/docs/language/providers) may offer data sources +alongside its set of [resource](/docs/language/resources) types. ## Using Data Sources @@ -59,14 +59,14 @@ Each data resource is associated with a single data source, which determines the kind of object (or objects) it reads and what query constraint arguments are available. -Each data source in turn belongs to a [provider](/opentf/language/providers), +Each data source in turn belongs to a [provider](/docs/language/providers), which is a plugin for OpenTF that offers a collection of resource types and data sources that most often belong to a single cloud or on-premises infrastructure platform. Most of the items within the body of a `data` block are defined by and specific to the selected data source, and these arguments can make full -use of [expressions](/opentf/language/expressions) and other dynamic +use of [expressions](/docs/language/expressions) and other dynamic OpenTF language features. However, there are some "meta-arguments" that are defined by OpenTF itself @@ -113,7 +113,7 @@ operation, and is re-calculated each time a new plan is created. ## Data Resource Dependencies Data resources have the same dependency resolution behavior -[as defined for managed resources](/opentf/language/resources/behavior#resource-dependencies). +[as defined for managed resources](/docs/language/resources/behavior#resource-dependencies). Setting the `depends_on` meta-argument within `data` blocks defers reading of the data source until after all changes to the dependencies have been applied. @@ -145,13 +145,13 @@ data "aws_ami" "example" { Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. -Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. +Refer to [Custom Condition Checks](/docs/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. ## Multiple Resource Instances -Data resources support [`count`](/opentf/language/meta-arguments/count) -and [`for_each`](/opentf/language/meta-arguments/for_each) +Data resources support [`count`](/docs/language/meta-arguments/count) +and [`for_each`](/docs/language/meta-arguments/for_each) meta-arguments as defined for managed resources, with the same syntax and behavior. As with managed resources, when `count` or `for_each` is present it is important to @@ -161,7 +161,7 @@ own variant of the constraint arguments, producing an indexed result. ## Selecting a Non-default Provider Configuration -Data resources support [the `provider` meta-argument](/opentf/language/meta-arguments/resource-provider) +Data resources support [the `provider` meta-argument](/docs/language/meta-arguments/resource-provider) as defined for managed resources, with the same syntax and behavior. ## Lifecycle Customizations @@ -198,7 +198,7 @@ and name must be unique. Within the block (the `{ }`) is configuration for the data instance. The configuration is dependent on the type; as with -[resources](/opentf/language/resources), each provider on the +[resources](/docs/language/resources), each provider on the [Public Terraform Registry](https://registry.terraform.io/browse/providers) has its own documentation for configuring and using the data types it provides. @@ -216,13 +216,13 @@ resource "aws_instance" "web" { ## Meta-Arguments As data sources are essentially a read only subset of resources, they also -support the same [meta-arguments](/opentf/language/resources/syntax#meta-arguments) of resources +support the same [meta-arguments](/docs/language/resources/syntax#meta-arguments) of resources with the exception of the -[`lifecycle` configuration block](/opentf/language/meta-arguments/lifecycle). +[`lifecycle` configuration block](/docs/language/meta-arguments/lifecycle). ### Non-Default Provider Configurations -Similarly to [resources](/opentf/language/resources), when +Similarly to [resources](/docs/language/resources), when a module has multiple configurations for the same provider you can specify which configuration to use with the `provider` meta-argument: @@ -235,7 +235,7 @@ data "aws_ami" "web" { ``` See -[The Resource `provider` Meta-Argument](/opentf/language/meta-arguments/resource-provider) +[The Resource `provider` Meta-Argument](/docs/language/meta-arguments/resource-provider) for more information. ## Data Source Lifecycle diff --git a/website/docs/language/expressions/conditionals.mdx b/website/docs/language/expressions/conditionals.mdx index 27d7ba6966..5e9fa995d0 100644 --- a/website/docs/language/expressions/conditionals.mdx +++ b/website/docs/language/expressions/conditionals.mdx @@ -43,7 +43,7 @@ You can create conditions that produce custom error messages for several types o Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. -Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#input-variable-validation) for details. +Refer to [Custom Condition Checks](/docs/language/expressions/custom-conditions#input-variable-validation) for details. ## Result Types @@ -70,7 +70,7 @@ be some uncertainty about the expected result type. The following example is contrived because it would be easier to write the constant `"12"` instead of the type conversion in this case, but shows how to -use [`tostring`](/opentf/language/functions/tostring) to explicitly convert a number to +use [`tostring`](/docs/language/functions/tostring) to explicitly convert a number to a string. ```hcl diff --git a/website/docs/language/expressions/custom-conditions.mdx b/website/docs/language/expressions/custom-conditions.mdx index a7ab1344f2..d55f034815 100644 --- a/website/docs/language/expressions/custom-conditions.mdx +++ b/website/docs/language/expressions/custom-conditions.mdx @@ -22,7 +22,7 @@ OpenTF's different custom conditions are best suited to various situations. Use 1. [Validation conditions](#input-variable-validation) or [output postconditions](#preconditions-and-postconditions) can ensure your configuration's inputs and outputs meet specific requirements. 1. Resource [preconditions and postconditions](#preconditions-and-postconditions) can validate that OpenTF produces your configuration with predictable results. -For more information on when to use certain custom conditions, see [Choosing Between Preconditions and Postconditions](#choosing-between-preconditions-and-postconditions) and [Choosing Checks or Other Custom Conditions](/opentf/language/checks#choosing-checks-or-other-custom-conditions). +For more information on when to use certain custom conditions, see [Choosing Between Preconditions and Postconditions](#choosing-between-preconditions-and-postconditions) and [Choosing Checks or Other Custom Conditions](/docs/language/checks#choosing-checks-or-other-custom-conditions). ## Input Variable Validation @@ -45,7 +45,7 @@ variable "image_id" { } ``` -If the failure of an expression determines the validation decision, use the [`can` function](/opentf/language/functions/can) as demonstrated in the following example. +If the failure of an expression determines the validation decision, use the [`can` function](/docs/language/functions/can) as demonstrated in the following example. ```hcl variable "image_id" { @@ -205,7 +205,7 @@ You should also consider the following questions when creating preconditions and ## Checks with Assertions -[Check blocks](/opentf/language/checks) can validate your infrastructure outside the usual resource lifecycle. You can add custom conditions via `assert` blocks, which execute at the end of the plan and apply stages and produce warnings to notify you of problems within your infrastructure. +[Check blocks](/docs/language/checks) can validate your infrastructure outside the usual resource lifecycle. You can add custom conditions via `assert` blocks, which execute at the end of the plan and apply stages and produce warnings to notify you of problems within your infrastructure. You can add one or more `assert` blocks within a `check` block to verify custom conditions. Each assertion requires a [`condition` argument](#condition-expressions), a boolean expression that should return `true` if the intended assumption or guarantee is fulfilled or `false` if it does not. Your `condition` expression can refer to any resource, data source, or variable available to the surrounding `check` block. @@ -245,11 +245,11 @@ Use the logical operators `&&` (AND), `||` (OR), and `!` (NOT) to combine multip condition = var.name != "" && lower(var.name) == var.name ``` -You can also use arithmetic operators (e.g. `a + b`), equality operators (eg., `a == b`) and comparison operators (e.g., `a < b`). Refer to [Arithmetic and Logical Operators](/opentf/language/expressions/operators) for details. +You can also use arithmetic operators (e.g. `a + b`), equality operators (eg., `a == b`) and comparison operators (e.g., `a < b`). Refer to [Arithmetic and Logical Operators](/docs/language/expressions/operators) for details. ### `contains` Function -Use the [`contains` function](/opentf/language/functions/contains) to test whether a given value is one of a set of predefined valid values. +Use the [`contains` function](/docs/language/functions/contains) to test whether a given value is one of a set of predefined valid values. ```hcl condition = contains(["STAGE", "PROD"], var.environment) @@ -257,7 +257,7 @@ Use the [`contains` function](/opentf/language/functions/contains) to test wheth ### `length` Function -Use the [`length` function](/opentf/language/functions/length) to test a collection's length and require a non-empty list or map. +Use the [`length` function](/docs/language/functions/length) to test a collection's length and require a non-empty list or map. ```hcl condition = length(var.items) != 0 @@ -266,7 +266,7 @@ This is a better approach than directly comparing with another collection using ### `for` Expressions -Use [`for` expressions](/opentf/language/expressions/for) in conjunction with the functions `alltrue` and `anytrue` to test whether a condition holds for all or for any elements of a collection. +Use [`for` expressions](/docs/language/expressions/for) in conjunction with the functions `alltrue` and `anytrue` to test whether a condition holds for all or for any elements of a collection. ```hcl condition = alltrue([ @@ -276,7 +276,7 @@ Use [`for` expressions](/opentf/language/expressions/for) in conjunction with th ### `can` Function -Use the [`can` function](/opentf/language/functions/can) to concisely use the validity of an expression as a condition. It returns `true` if its given expression evaluates successfully and `false` if it returns any error, so you can use various other functions that typically return errors as a part of your condition expressions. +Use the [`can` function](/docs/language/functions/can) to concisely use the validity of an expression as a condition. It returns `true` if its given expression evaluates successfully and `false` if it returns any error, so you can use various other functions that typically return errors as a part of your condition expressions. For example, you can use `can` with `regex` to test if a string matches a particular pattern because `regex` returns an error when given a non-matching string. @@ -334,7 +334,7 @@ resource "aws_instance" "example" { ### `each` and `count` Objects -In blocks where [`for_each`](/opentf/language/meta-arguments/for_each) or [`count`](/opentf/language/meta-arguments/count) are set, use `each` and `count` objects to refer to other resources that are expanded in a chain. +In blocks where [`for_each`](/docs/language/meta-arguments/for_each) or [`count`](/docs/language/meta-arguments/count) are set, use `each` and `count` objects to refer to other resources that are expanded in a chain. ```hcl variable "vpc_cidrs" { @@ -380,7 +380,7 @@ The selected AMI must be tagged with the Component value "nomad-server". ``` The `error_message` argument can be any expression that evaluates to a string. -This includes literal strings, heredocs, and template expressions. You can use the [`format` function](/opentf/language/functions/format) to convert items of `null`, `list`, or `map` types into a formatted string. Multi-line +This includes literal strings, heredocs, and template expressions. You can use the [`format` function](/docs/language/functions/format) to convert items of `null`, `list`, or `map` types into a formatted string. Multi-line error messages are supported, and lines with leading whitespace will not be word wrapped. diff --git a/website/docs/language/expressions/dynamic-blocks.mdx b/website/docs/language/expressions/dynamic-blocks.mdx index 6966713901..ab32cc2ae6 100644 --- a/website/docs/language/expressions/dynamic-blocks.mdx +++ b/website/docs/language/expressions/dynamic-blocks.mdx @@ -44,7 +44,7 @@ resource "aws_elastic_beanstalk_environment" "tfenvtest" { } ``` -A `dynamic` block acts much like a [`for` expression](/opentf/language/expressions/for), but produces +A `dynamic` block acts much like a [`for` expression](/docs/language/expressions/for), but produces nested blocks instead of a complex typed value. It iterates over a given complex value, and generates a nested block for each element of that complex value. @@ -84,9 +84,9 @@ nested block. If you need to declare resource instances based on a nested data structure or combinations of elements from multiple data structures you can use OpenTF expressions and functions to derive a suitable value. For some common examples of such situations, see the -[`flatten`](/opentf/language/functions/flatten) +[`flatten`](/docs/language/functions/flatten) and -[`setproduct`](/opentf/language/functions/setproduct) +[`setproduct`](/docs/language/functions/setproduct) functions. ## Multi-level Nested Block Structures @@ -151,5 +151,5 @@ nested blocks using directly-corresponding attributes from an input variable then that might suggest that your module is not creating a useful abstraction. It may be better for the calling module to define the resource itself then pass information about it into your module. For more information on this design -tradeoff, see [When to Write a Module](/opentf/language/modules/develop#when-to-write-a-module) -and [Module Composition](/opentf/language/modules/develop/composition). +tradeoff, see [When to Write a Module](/docs/language/modules/develop#when-to-write-a-module) +and [Module Composition](/docs/language/modules/develop/composition). diff --git a/website/docs/language/expressions/for.mdx b/website/docs/language/expressions/for.mdx index 3f3e7ae1ce..5e54ee89a2 100644 --- a/website/docs/language/expressions/for.mdx +++ b/website/docs/language/expressions/for.mdx @@ -127,7 +127,7 @@ using lexical sorting. For sets of strings, OpenTF sorts the elements by their value, using lexical sorting. -For sets of other types, OpenTF uses an arbitrary ordering that may change in future versions. We recommend converting the expression result into a set to make it clear elsewhere in the configuration that the result is unordered. You can use [the `toset` function](/opentf/language/functions/toset) +For sets of other types, OpenTF uses an arbitrary ordering that may change in future versions. We recommend converting the expression result into a set to make it clear elsewhere in the configuration that the result is unordered. You can use [the `toset` function](/docs/language/functions/toset) to concisely convert a `for` expression result to be of a set type. ```hcl @@ -204,4 +204,4 @@ Some resource types also define _nested block types_, which typically represent separate objects that belong to the containing resource in some way. You can't dynamically generate nested blocks using `for` expressions, but you _can_ generate nested blocks for a resource dynamically using -[`dynamic` blocks](/opentf/language/expressions/dynamic-blocks). +[`dynamic` blocks](/docs/language/expressions/dynamic-blocks). diff --git a/website/docs/language/expressions/function-calls.mdx b/website/docs/language/expressions/function-calls.mdx index 79f4d16643..077ea9d0f9 100644 --- a/website/docs/language/expressions/function-calls.mdx +++ b/website/docs/language/expressions/function-calls.mdx @@ -8,7 +8,7 @@ description: >- # Function Calls The OpenTF language has a number of -[built-in functions](/opentf/language/functions) that can be used +[built-in functions](/docs/language/functions) that can be used in expressions to transform and combine values. These are similar to the operators but all follow a common syntax: @@ -33,7 +33,7 @@ A function call expression evaluates to the function's return value. ## Available Functions For a full list of available functions, see -[the function reference](/opentf/language/functions). +[the function reference](/docs/language/functions). ## Expanding Function Arguments @@ -50,8 +50,8 @@ The expansion symbol is three periods (`...`), not a Unicode ellipsis character ## Using Sensitive Data as Function Arguments -When using sensitive data, such as [an input variable](/opentf/language/values/variables#suppressing-values-in-cli-output) -or [an output defined](/opentf/language/values/outputs#sensitive-suppressing-values-in-cli-output) as sensitive +When using sensitive data, such as [an input variable](/docs/language/values/variables#suppressing-values-in-cli-output) +or [an output defined](/docs/language/values/outputs#sensitive-suppressing-values-in-cli-output) as sensitive as function arguments, the result of the function call will be marked as sensitive. This is a conservative behavior that is true irrespective of the function being @@ -80,10 +80,10 @@ those it can be helpful to know when OpenTF will call them in relation to other events that occur in an OpenTF run. The small set of special functions includes -[`file`](/opentf/language/functions/file), -[`templatefile`](/opentf/language/functions/templatefile), -[`timestamp`](/opentf/language/functions/timestamp), -and [`uuid`](/opentf/language/functions/uuid). +[`file`](/docs/language/functions/file), +[`templatefile`](/docs/language/functions/templatefile), +[`timestamp`](/docs/language/functions/timestamp), +and [`uuid`](/docs/language/functions/uuid). If you are not working with these functions then you don't need to read this section, although the information here may still be interesting background information. @@ -102,7 +102,7 @@ both cause the final configuration during the apply step not to match the actions shown in the plan, which violates the OpenTF execution model. For that reason, OpenTF arranges for both of those functions to produce -[unknown value](/opentf/language/expressions/references#values-not-yet-known) results during the +[unknown value](/docs/language/expressions/references#values-not-yet-known) results during the plan step, with the real result being decided only during the apply step. For `timestamp` in particular, this means that the recorded time will be the instant when OpenTF began applying the change, rather than when diff --git a/website/docs/language/expressions/index.mdx b/website/docs/language/expressions/index.mdx index 3e5133870a..365e04abd0 100644 --- a/website/docs/language/expressions/index.mdx +++ b/website/docs/language/expressions/index.mdx @@ -16,54 +16,54 @@ and a number of built-in functions. Expressions can be used in a number of places in the OpenTF language, but some contexts limit which expression constructs are allowed, such as requiring a literal value of a particular type or forbidding -[references to resource attributes](/opentf/language/expressions/references#references-to-resource-attributes). +[references to resource attributes](/docs/language/expressions/references#references-to-resource-attributes). Each language feature's documentation describes any restrictions it places on expressions. You can experiment with the behavior of OpenTF's expressions from the OpenTF expression console, by running -[the `opentf console` command](/opentf/cli/commands/console). +[the `opentf console` command](/docs/cli/commands/console). The other pages in this section describe the features of OpenTF's expression syntax. -- [Types and Values](/opentf/language/expressions/types) +- [Types and Values](/docs/language/expressions/types) documents the data types that OpenTF expressions can resolve to, and the literal syntaxes for values of those types. -- [Strings and Templates](/opentf/language/expressions/strings) +- [Strings and Templates](/docs/language/expressions/strings) documents the syntaxes for string literals, including interpolation sequences and template directives. -- [References to Values](/opentf/language/expressions/references) +- [References to Values](/docs/language/expressions/references) documents how to refer to named values like variables and resource attributes. -- [Operators](/opentf/language/expressions/operators) +- [Operators](/docs/language/expressions/operators) documents the arithmetic, comparison, and logical operators. -- [Function Calls](/opentf/language/expressions/function-calls) +- [Function Calls](/docs/language/expressions/function-calls) documents the syntax for calling OpenTF's built-in functions. -- [Conditional Expressions](/opentf/language/expressions/conditionals) +- [Conditional Expressions](/docs/language/expressions/conditionals) documents the ` ? : ` expression, which chooses between two values based on a bool condition. -- [For Expressions](/opentf/language/expressions/for) +- [For Expressions](/docs/language/expressions/for) documents expressions like `[for s in var.list : upper(s)]`, which can transform a complex type value into another complex type value. -- [Splat Expressions](/opentf/language/expressions/splat) +- [Splat Expressions](/docs/language/expressions/splat) documents expressions like `var.list[*].id`, which can extract simpler collections from more complicated expressions. -- [Dynamic Blocks](/opentf/language/expressions/dynamic-blocks) +- [Dynamic Blocks](/docs/language/expressions/dynamic-blocks) documents a way to create multiple repeatable nested blocks within a resource or other construct. -- [Type Constraints](/opentf/language/expressions/type-constraints) +- [Type Constraints](/docs/language/expressions/type-constraints) documents the syntax for referring to a type, rather than a value of that type. Input variables expect this syntax in their `type` argument. -- [Version Constraints](/opentf/language/expressions/version-constraints) +- [Version Constraints](/docs/language/expressions/version-constraints) documents the syntax of special strings that define a set of allowed software versions. OpenTF uses version constraints in several places. diff --git a/website/docs/language/expressions/operators.mdx b/website/docs/language/expressions/operators.mdx index caa899e5c2..c40a91288e 100644 --- a/website/docs/language/expressions/operators.mdx +++ b/website/docs/language/expressions/operators.mdx @@ -56,9 +56,9 @@ as results: * `-a` returns the result of multiplying `a` by `-1`. OpenTF supports some other less-common numeric operations as -[functions](/opentf/language/expressions/function-calls). For example, you can calculate exponents +[functions](/docs/language/expressions/function-calls). For example, you can calculate exponents using -[the `pow` function](/opentf/language/functions/pow). +[the `pow` function](/docs/language/functions/pow). ## Equality Operators diff --git a/website/docs/language/expressions/references.mdx b/website/docs/language/expressions/references.mdx index b82d962b09..13b17b3829 100644 --- a/website/docs/language/expressions/references.mdx +++ b/website/docs/language/expressions/references.mdx @@ -28,7 +28,7 @@ The main kinds of named values available in OpenTF are: The sections below explain each kind of named value in detail. Although many of these names use dot-separated paths that resemble -[attribute notation](/opentf/language/expressions/types#indices-and-attributes) for elements of object values, they are not +[attribute notation](/docs/language/expressions/types#indices-and-attributes) for elements of object values, they are not implemented as real objects. This means you must use them exactly as written: you cannot use square-bracket notation to replace the dot-separated paths, and you cannot iterate over the "parent object" of a named entity; for example, you @@ -37,7 +37,7 @@ instance resource. ### Resources -`.` represents a [managed resource](/opentf/language/resources) of +`.` represents a [managed resource](/docs/language/resources) of the given type and name. The value of a resource reference can vary, depending on whether the resource @@ -45,7 +45,7 @@ uses `count` or `for_each`: * If the resource doesn't use `count` or `for_each`, the reference's value is an object. The resource's attributes are elements of the object, and you can - access them using [dot or square bracket notation](/opentf/language/expressions/types#indices-and-attributes). + access them using [dot or square bracket notation](/docs/language/expressions/types#indices-and-attributes). * If the resource has the `count` argument set, the reference's value is a _list_ of objects representing its instances. * If the resource has the `for_each` argument set, the reference's value is a @@ -59,7 +59,7 @@ For more information about how to use resource references, see ### Input Variables -`var.` is the value of the [input variable](/opentf/language/values/variables) of the given name. +`var.` is the value of the [input variable](/docs/language/values/variables) of the given name. If the variable has a type constraint (`type` argument) as part of its declaration, OpenTF will automatically convert the caller's given value @@ -77,7 +77,7 @@ constraint all of the attributes you intend to use elsewhere in your module. ### Local Values -`local.` is the value of the [local value](/opentf/language/values/locals) of the given name. +`local.` is the value of the [local value](/docs/language/values/locals) of the given name. Local values can refer to other local values, even within the same `locals` block, as long as you don't introduce circular dependencies. @@ -85,12 +85,12 @@ block, as long as you don't introduce circular dependencies. ### Child Module Outputs `module.` is an value representing the results of -[a `module` block](/opentf/language/modules/syntax). +[a `module` block](/docs/language/modules/syntax). If the corresponding `module` block does not have either `count` nor `for_each` set then the value will be an object with one attribute for each output value defined in the child module. To access one of the module's -[output values](/opentf/language/values/outputs), use `module..`. +[output values](/docs/language/values/outputs), use `module..`. If the corresponding `module` uses `for_each` then the value will be a map of objects whose keys correspond with the keys in the `for_each` expression, @@ -104,7 +104,7 @@ elements, each one representing one module instance. ### Data Sources `data..` is an object representing a -[data resource](/opentf/language/data-sources) of the given data +[data resource](/docs/language/data-sources) of the given data source type and name. If the resource has the `count` argument set, the value is a list of objects representing its instances. If the resource has the `for_each` argument set, the value is a map of objects representing its instances. @@ -132,7 +132,7 @@ The following values are available: directory. We recommend using `path.root` or `path.module` over `path.cwd` where possible. - `terraform.workspace` is the name of the currently selected - [workspace](/opentf/language/state/workspaces). + [workspace](/docs/language/state/workspaces). Use the values in this section carefully, because they include information about the context in which a configuration is being applied and so may @@ -172,19 +172,19 @@ These local names are described in the documentation for the specific contexts where they appear. Some of most common local names are: * `count.index`, in resources that use - [the `count` meta-argument](/opentf/language/meta-arguments/count). + [the `count` meta-argument](/docs/language/meta-arguments/count). * `each.key` / `each.value`, in resources that use - [the `for_each` meta-argument](/opentf/language/meta-arguments/for_each). -* `self`, in [provisioner](/opentf/language/resources/provisioners/syntax) and - [connection](/opentf/language/resources/provisioners/connection) blocks. + [the `for_each` meta-argument](/docs/language/meta-arguments/for_each). +* `self`, in [provisioner](/docs/language/resources/provisioners/syntax) and + [connection](/docs/language/resources/provisioners/connection) blocks. -> **Note:** Local names are often referred to as _variables_ or _temporary variables_ in their documentation. These are not [input -variables](/opentf/language/values/variables); they are just arbitrary names +variables](/docs/language/values/variables); they are just arbitrary names that temporarily represent a value. The names in this section relate to top-level configuration blocks only. -If you use [`dynamic` blocks](/opentf/language/expressions/dynamic-blocks) to dynamically generate +If you use [`dynamic` blocks](/docs/language/expressions/dynamic-blocks) to dynamically generate resource-type-specific _nested_ blocks within `resource` and `data` blocks then you'll refer to the key and value of each element differently. See the `dynamic` blocks documentation for details. @@ -233,7 +233,7 @@ for use in references, as follows: * The `id` attribute exported by this resource type can be read using the same syntax, giving `aws_instance.example.id`. * The arguments of the `ebs_block_device` nested blocks can be accessed using - a [splat expression](/opentf/language/expressions/splat). For example, to obtain a list of + a [splat expression](/docs/language/expressions/splat). For example, to obtain a list of all of the `device_name` values, use `aws_instance.example.ebs_block_device[*].device_name`. * The nested blocks in this particular resource type do not have any exported @@ -259,24 +259,24 @@ for use in references, as follows: as `aws_instance.example.device["foo"].size`. To obtain a map of values of a particular argument for _labelled_ nested - block types, use a [`for` expression](/opentf/language/expressions/for): + block types, use a [`for` expression](/docs/language/expressions/for): `{for k, device in aws_instance.example.device : k => device.size}`. When a resource has the -[`count`](/opentf/language/meta-arguments/count) +[`count`](/docs/language/meta-arguments/count) argument set, the resource itself becomes a _list_ of instance objects rather than a single object. In that case, access the attributes of the instances using -either [splat expressions](/opentf/language/expressions/splat) or index syntax: +either [splat expressions](/docs/language/expressions/splat) or index syntax: * `aws_instance.example[*].id` returns a list of all of the ids of each of the instances. * `aws_instance.example[0].id` returns just the id of the first instance. When a resource has the -[`for_each`](/opentf/language/meta-arguments/for_each) +[`for_each`](/docs/language/meta-arguments/for_each) argument set, the resource itself becomes a _map_ of instance objects rather than a single object, and attributes of instances must be specified by key, or can -be accessed using a [`for` expression](/opentf/language/expressions/for). +be accessed using a [`for` expression](/docs/language/expressions/for). * `aws_instance.example["a"].id` returns the id of the "a"-keyed resource. * `[for value in aws_instance.example: value.id]` returns a list of all of the ids @@ -294,21 +294,21 @@ placeholder marker `(sensitive value)` instead of the actual value when renderin a plan involving that attribute. A provider attribute marked as sensitive behaves similarly to an -[an input variable declared as sensitive](/opentf/language/values/variables#suppressing-values-in-cli-output), +[an input variable declared as sensitive](/docs/language/values/variables#suppressing-values-in-cli-output), where OpenTF will hide the value in the plan and apply messages and will also hide any other values you derive from it as sensitive. However, there are some limitations to that behavior as described in -[Cases where OpenTF may disclose a sensitive variable](/opentf/language/values/variables#cases-where-opentf-may-disclose-a-sensitive-variable). +[Cases where OpenTF may disclose a sensitive variable](/docs/language/values/variables#cases-where-opentf-may-disclose-a-sensitive-variable). If you use a sensitive value from a resource attribute as part of an -[output value](/opentf/language/values/outputs) then OpenTF will require +[output value](/docs/language/values/outputs) then OpenTF will require you to also mark the output value itself as sensitive, to confirm that you intended to export it. -OpenTF will still record sensitive values in the [state](/opentf/language/state), +OpenTF will still record sensitive values in the [state](/docs/language/state), and so anyone who can access the state data will have access to the sensitive values in cleartext. For more information, see -[_Sensitive Data in State_](/opentf/language/state/sensitive-data). +[_Sensitive Data in State_](/docs/language/state/sensitive-data). ### Values Not Yet Known diff --git a/website/docs/language/expressions/splat.mdx b/website/docs/language/expressions/splat.mdx index b71d2ab5f0..74815e54f7 100644 --- a/website/docs/language/expressions/splat.mdx +++ b/website/docs/language/expressions/splat.mdx @@ -43,12 +43,12 @@ The above expression is equivalent to the following `for` expression: The splat expression patterns shown above apply only to lists, sets, and tuples. To get a similar result with a map or object value you must use -[`for` expressions](/opentf/language/expressions/for). +[`for` expressions](/docs/language/expressions/for). Resources that use the `for_each` argument will appear in expressions as a map of objects, so you can't use splat expressions with those resources. For more information, see -[Referring to Resource Instances](/opentf/language/meta-arguments/for_each#referring-to-instances). +[Referring to Resource Instances](/docs/language/meta-arguments/for_each#referring-to-instances). ## Single Values as Lists @@ -85,7 +85,7 @@ resource "aws_s3_bucket" "example" { } ``` -The above example uses a [`dynamic` block](/opentf/language/expressions/dynamic-blocks), which +The above example uses a [`dynamic` block](/docs/language/expressions/dynamic-blocks), which generates zero or more nested blocks based on a collection value. The input variable `var.website_setting` is defined as a single object that might be null, so the `dynamic` block's `for_each` expression uses `[*]` to ensure that diff --git a/website/docs/language/expressions/strings.mdx b/website/docs/language/expressions/strings.mdx index eecd10e040..949ba0f21f 100644 --- a/website/docs/language/expressions/strings.mdx +++ b/website/docs/language/expressions/strings.mdx @@ -77,8 +77,8 @@ allowed, but conventionally this identifier is in all-uppercase and begins with ### Generating JSON or YAML Don't use "heredoc" strings to generate JSON or YAML. Instead, use -[the `jsonencode` function](/opentf/language/functions/jsonencode) or -[the `yamlencode` function](/opentf/language/functions/yamlencode) so that OpenTF +[the `jsonencode` function](/docs/language/functions/jsonencode) or +[the `yamlencode` function](/docs/language/functions/yamlencode) so that OpenTF can be responsible for guaranteeing valid JSON or YAML syntax. ```hcl diff --git a/website/docs/language/expressions/type-constraints.mdx b/website/docs/language/expressions/type-constraints.mdx index b08a47bd87..c58958e42a 100644 --- a/website/docs/language/expressions/type-constraints.mdx +++ b/website/docs/language/expressions/type-constraints.mdx @@ -25,9 +25,9 @@ function-like constructs called _type constructors._ represent a type; instead, it represents a _kind_ of similar types. Type constraints look like other kinds of OpenTF -[expressions](/opentf/language/expressions), but are a special syntax. Within the +[expressions](/docs/language/expressions), but are a special syntax. Within the OpenTF language, they are only valid in the `type` argument of an -[input variable](/opentf/language/values/variables). +[input variable](/docs/language/values/variables). ## Primitive Types @@ -152,7 +152,7 @@ like the following: The OpenTF language has literal expressions for creating tuple and object values, which are described in -[Expressions: Literal Expressions](/opentf/language/expressions/types#literal-expressions) as +[Expressions: Literal Expressions](/docs/language/expressions/types#literal-expressions) as "list/tuple" literals and "map/object" literals, respectively. OpenTF does _not_ provide any way to directly represent lists, maps, or sets. diff --git a/website/docs/language/expressions/types.mdx b/website/docs/language/expressions/types.mdx index baa689b2ad..fd14e621cf 100644 --- a/website/docs/language/expressions/types.mdx +++ b/website/docs/language/expressions/types.mdx @@ -55,7 +55,7 @@ characters, `"like this"`. There is also a "heredoc" syntax for more complex strings. String literals are the most complex kind of literal expression in -OpenTF, and have their own page of documentation. See [Strings](/opentf/language/expressions/strings) +OpenTF, and have their own page of documentation. See [Strings](/docs/language/expressions/strings) for information about escape sequences, the heredoc syntax, interpolation, and template directives. @@ -99,7 +99,7 @@ The values in a map can be arbitrary expressions. The keys in a map must be strings; they can be left unquoted if -they are a valid [identifier](/opentf/language/syntax/configuration#identifiers), but must be quoted +they are a valid [identifier](/docs/language/syntax/configuration#identifiers), but must be quoted otherwise. You can use a non-literal string expression as a key by wrapping it in parentheses, like `(var.business_unit_tag_name) = "SRE"`. @@ -128,7 +128,7 @@ offer different ways to restrict the allowed values for input variables and resource arguments. For complete details about these types (and an explanation of why the difference -usually doesn't matter), see [Type Constraints](/opentf/language/expressions/type-constraints). +usually doesn't matter), see [Type Constraints](/docs/language/expressions/type-constraints). ## Type Conversion diff --git a/website/docs/language/expressions/version-constraints.mdx b/website/docs/language/expressions/version-constraints.mdx index 97556dbec3..be419456b5 100644 --- a/website/docs/language/expressions/version-constraints.mdx +++ b/website/docs/language/expressions/version-constraints.mdx @@ -11,9 +11,9 @@ Anywhere that OpenTF lets you specify a range of acceptable versions for something, it expects a specially formatted string known as a version constraint. Version constraints are used when configuring: -- [Modules](/opentf/language/modules) -- [Provider requirements](/opentf/language/providers/requirements) -- [The `required_version` setting](/opentf/language/settings#specifying-a-required-opentf-version) in the `opentf` block. +- [Modules](/docs/language/modules) +- [Provider requirements](/docs/language/providers/requirements) +- [The `required_version` setting](/docs/language/settings#specifying-a-required-opentf-version) in the `opentf` block. ## Version Constraint Syntax @@ -24,7 +24,7 @@ other dependency management systems like Bundler and NPM. version = ">= 1.2.0, < 2.0.0" ``` -A version constraint is a [string literal](/opentf/language/expressions/strings) +A version constraint is a [string literal](/docs/language/expressions/strings) containing one or more conditions, which are separated by commas. Each condition consists of an operator and a version number. diff --git a/website/docs/language/files/dependency-lock.mdx b/website/docs/language/files/dependency-lock.mdx index 187b8d0059..86c15645fd 100644 --- a/website/docs/language/files/dependency-lock.mdx +++ b/website/docs/language/files/dependency-lock.mdx @@ -10,9 +10,9 @@ description: >- An OpenTF configuration may refer to two different kinds of external dependency that come from outside of its own codebase: -- [Providers](/opentf/language/providers/requirements), which are plugins for OpenTF +- [Providers](/docs/language/providers/requirements), which are plugins for OpenTF that extend it with support for interacting with various external systems. -- [Modules](/opentf/language/modules), which allow +- [Modules](/docs/language/modules), which allow splitting out groups of OpenTF configuration constructs (written in the OpenTF language) into reusable abstractions. @@ -22,7 +22,7 @@ reason, OpenTF must determine which versions of those dependencies are potentially compatible with the current configuration and which versions are currently selected for use. -[Version constraints](/opentf/language/expressions/version-constraints) within the configuration +[Version constraints](/docs/language/expressions/version-constraints) within the configuration itself determine which versions of dependencies are _potentially_ compatible, but after selecting a specific version of each dependency OpenTF remembers the decisions it made in a _dependency lock file_ so that it can (by default) @@ -47,7 +47,7 @@ to signify that it is a lock file for various items that OpenTF caches in the `.terraform` subdirectory of your working directory. OpenTF automatically creates or updates the dependency lock file each time -you run [the `opentf init` command](/opentf/cli/commands/init). You should +you run [the `opentf init` command](/docs/cli/commands/init). You should include this file in your version control repository so that you can discuss potential changes to your external dependencies via code review, just as you would discuss potential changes to your configuration itself. @@ -135,7 +135,7 @@ There are two special considerations with the "trust on first use" model: To avoid this problem you can pre-populate checksums for a variety of different platforms in your lock file using - [the `opentf providers lock` command](/opentf/cli/commands/providers/lock), + [the `opentf providers lock` command](/docs/cli/commands/providers/lock), which will then allow future calls to `opentf init` to verify that the packages available in your chosen mirror match the official packages from the provider's origin registry. @@ -153,7 +153,7 @@ proposed changes. The following sections will describe these common situations. ### Dependency on a new provider If you add a new entry to the -[provider requirements](/opentf/language/providers/requirements) for any module in your +[provider requirements](/docs/language/providers/requirements) for any module in your configuration, or if you add an external module that includes a new provider dependency itself, `opentf init` will respond to that by selecting the newest version of that provider which meets all of the version constraints @@ -300,7 +300,7 @@ The two hashing schemes currently supported are: packages indexed in the origin registry. This is an effective scheme for verifying the official release packages when installed from a registry, but it's not suitable for verifying packages that come from other - [provider installation methods](/opentf/cli/config/config-file#provider-installation), + [provider installation methods](/docs/cli/config/config-file#provider-installation), such as filesystem mirrors using the unpacked directory layout. - `h1:`: a mnemonic for "hash scheme 1", which is the current preferred hashing @@ -341,7 +341,7 @@ your configuration on new target platforms, or if you are installing providers from a mirror that therefore can't provide official signed checksums, you can ask OpenTF to pre-populate hashes for a chosen set of platforms using -[the `opentf providers lock` command](/opentf/cli/commands/providers/lock): +[the `opentf providers lock` command](/docs/cli/commands/providers/lock): ``` opentf providers lock \ diff --git a/website/docs/language/files/index.mdx b/website/docs/language/files/index.mdx index 75e3ac8ba3..ac8a9a0b3f 100644 --- a/website/docs/language/files/index.mdx +++ b/website/docs/language/files/index.mdx @@ -11,7 +11,7 @@ description: >- Code in the OpenTF language is stored in plain text files with the `.tf` file extension. There is also -[a JSON-based variant of the language](/opentf/language/syntax/json) that is named with +[a JSON-based variant of the language](/docs/language/syntax/json) that is named with the `.tf.json` file extension. Files containing OpenTF code are often called _configuration files._ @@ -36,7 +36,7 @@ treating the entire module as a single document. Separating various blocks into different files is purely for the convenience of readers and maintainers, and has no effect on the module's behavior. -An OpenTF module can use [module calls](/opentf/language/modules) to +An OpenTF module can use [module calls](/docs/language/modules) to explicitly include other modules into the configuration. These child modules can come from local directories (nested in the parent module's directory, or anywhere else on disk), or from external sources like the diff --git a/website/docs/language/functions/abspath.mdx b/website/docs/language/functions/abspath.mdx index f93a11fce7..40fe9c157b 100644 --- a/website/docs/language/functions/abspath.mdx +++ b/website/docs/language/functions/abspath.mdx @@ -12,7 +12,7 @@ with the current working directory. Referring directly to filesystem paths in resource arguments may cause spurious diffs if the same configuration is applied from multiple systems or on different host operating systems. We recommend using filesystem paths only -for transient values, such as the argument to [`file`](/opentf/language/functions/file) (where +for transient values, such as the argument to [`file`](/docs/language/functions/file) (where only the contents are then stored) or in `connection` and `provisioner` blocks. ## Examples diff --git a/website/docs/language/functions/base64decode.mdx b/website/docs/language/functions/base64decode.mdx index c8862c9f4e..ddde2e037e 100644 --- a/website/docs/language/functions/base64decode.mdx +++ b/website/docs/language/functions/base64decode.mdx @@ -24,7 +24,7 @@ most cases. Various other functions with names containing "base64" can generate or manipulate Base64 data directly. `base64decode` is, in effect, a shorthand for calling -[`textdecodebase64`](/opentf/language/functions/textdecodebase64) with the encoding name set to +[`textdecodebase64`](/docs/language/functions/textdecodebase64) with the encoding name set to `UTF-8`. ## Examples @@ -36,11 +36,11 @@ Hello World ## Related Functions -* [`base64encode`](/opentf/language/functions/base64encode) performs the opposite operation, +* [`base64encode`](/docs/language/functions/base64encode) performs the opposite operation, encoding the UTF-8 bytes for a string as Base64. -* [`textdecodebase64`](/opentf/language/functions/textdecodebase64) is a more general function that +* [`textdecodebase64`](/docs/language/functions/textdecodebase64) is a more general function that supports character encodings other than UTF-8. -* [`base64gzip`](/opentf/language/functions/base64gzip) applies gzip compression to a string +* [`base64gzip`](/docs/language/functions/base64gzip) applies gzip compression to a string and returns the result with Base64 encoding. -* [`filebase64`](/opentf/language/functions/filebase64) reads a file from the local filesystem +* [`filebase64`](/docs/language/functions/filebase64) reads a file from the local filesystem and returns its raw bytes with Base64 encoding. diff --git a/website/docs/language/functions/base64encode.mdx b/website/docs/language/functions/base64encode.mdx index f9ebfafb2c..ef17433048 100644 --- a/website/docs/language/functions/base64encode.mdx +++ b/website/docs/language/functions/base64encode.mdx @@ -25,7 +25,7 @@ Base64 themselves, and so this function exists primarily to allow string data to be easily provided to resource types that expect Base64 bytes. `base64encode` is, in effect, a shorthand for calling -[`textencodebase64`](/opentf/language/functions/textencodebase64) with the encoding name set to +[`textencodebase64`](/docs/language/functions/textencodebase64) with the encoding name set to `UTF-8`. ## Examples @@ -37,12 +37,12 @@ SGVsbG8gV29ybGQ= ## Related Functions -* [`base64decode`](/opentf/language/functions/base64decode) performs the opposite operation, +* [`base64decode`](/docs/language/functions/base64decode) performs the opposite operation, decoding Base64 data and interpreting it as a UTF-8 string. -* [`textencodebase64`](/opentf/language/functions/textencodebase64) is a more general function that +* [`textencodebase64`](/docs/language/functions/textencodebase64) is a more general function that supports character encodings other than UTF-8. -* [`base64gzip`](/opentf/language/functions/base64gzip) applies gzip compression to a string +* [`base64gzip`](/docs/language/functions/base64gzip) applies gzip compression to a string and returns the result with Base64 encoding all in one operation. -* [`filebase64`](/opentf/language/functions/filebase64) reads a file from the local filesystem +* [`filebase64`](/docs/language/functions/filebase64) reads a file from the local filesystem and returns its raw bytes with Base64 encoding, without creating an intermediate Unicode string. diff --git a/website/docs/language/functions/base64gzip.mdx b/website/docs/language/functions/base64gzip.mdx index 3664a88046..7f13e69f76 100644 --- a/website/docs/language/functions/base64gzip.mdx +++ b/website/docs/language/functions/base64gzip.mdx @@ -25,7 +25,7 @@ an S3 website. ## Related Functions -* [`base64encode`](/opentf/language/functions/base64encode) applies Base64 encoding _without_ +* [`base64encode`](/docs/language/functions/base64encode) applies Base64 encoding _without_ gzip compression. -* [`filebase64`](/opentf/language/functions/filebase64) reads a file from the local filesystem +* [`filebase64`](/docs/language/functions/filebase64) reads a file from the local filesystem and returns its raw bytes with Base64 encoding. diff --git a/website/docs/language/functions/base64sha256.mdx b/website/docs/language/functions/base64sha256.mdx index 1aa0ed1960..055f272195 100644 --- a/website/docs/language/functions/base64sha256.mdx +++ b/website/docs/language/functions/base64sha256.mdx @@ -25,7 +25,7 @@ uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek= ## Related Functions -* [`filebase64sha256`](/opentf/language/functions/filebase64sha256) calculates the same hash from +* [`filebase64sha256`](/docs/language/functions/filebase64sha256) calculates the same hash from the contents of a file rather than from a string value. -* [`sha256`](/opentf/language/functions/sha256) calculates the same hash but returns the result +* [`sha256`](/docs/language/functions/sha256) calculates the same hash but returns the result in a more-verbose hexadecimal encoding. diff --git a/website/docs/language/functions/base64sha512.mdx b/website/docs/language/functions/base64sha512.mdx index 2a332c7c23..e3422ee7a9 100644 --- a/website/docs/language/functions/base64sha512.mdx +++ b/website/docs/language/functions/base64sha512.mdx @@ -25,7 +25,7 @@ MJ7MSJwS1utMxA9QyQLytNDtd+5RGnx6m808qG1M2G+YndNbxf9JlnDaNCVbRbDP2DDoH2Bdz33FVC6T ## Related Functions -* [`filebase64sha512`](/opentf/language/functions/filebase64sha512) calculates the same hash from +* [`filebase64sha512`](/docs/language/functions/filebase64sha512) calculates the same hash from the contents of a file rather than from a string value. -* [`sha512`](/opentf/language/functions/sha512) calculates the same hash but returns the result +* [`sha512`](/docs/language/functions/sha512) calculates the same hash but returns the result in a more-verbose hexadecimal encoding. diff --git a/website/docs/language/functions/basename.mdx b/website/docs/language/functions/basename.mdx index 3c974ac284..f73e2261cc 100644 --- a/website/docs/language/functions/basename.mdx +++ b/website/docs/language/functions/basename.mdx @@ -24,7 +24,7 @@ it uses backslash `\` as the path segment separator. On Unix systems, the slash Referring directly to filesystem paths in resource arguments may cause spurious diffs if the same configuration is applied from multiple systems or on different host operating systems. We recommend using filesystem paths only -for transient values, such as the argument to [`file`](/opentf/language/functions/file) (where +for transient values, such as the argument to [`file`](/docs/language/functions/file) (where only the contents are then stored) or in `connection` and `provisioner` blocks. ## Examples @@ -36,6 +36,6 @@ baz.txt ## Related Functions -* [`dirname`](/opentf/language/functions/dirname) returns all of the segments of a filesystem path +* [`dirname`](/docs/language/functions/dirname) returns all of the segments of a filesystem path _except_ the last, discarding the portion that would be returned by `basename`. diff --git a/website/docs/language/functions/can.mdx b/website/docs/language/functions/can.mdx index d7e405d274..f354005015 100644 --- a/website/docs/language/functions/can.mdx +++ b/website/docs/language/functions/can.mdx @@ -12,12 +12,12 @@ whether the expression produced a result without any errors. This is a special function that is able to catch errors produced when evaluating its argument. For most situations where you could use `can` it's better to use -[`try`](/opentf/language/functions/try) instead, because it allows for more concise definition of +[`try`](/docs/language/functions/try) instead, because it allows for more concise definition of fallback values for failing expressions. The primary purpose of `can` is to turn an error condition into a boolean validation result when writing -[custom variable validation rules](/opentf/language/values/variables#custom-validation-rules). +[custom variable validation rules](/docs/language/values/variables#custom-validation-rules). For example: ``` @@ -41,7 +41,7 @@ as a malformed resource reference. variable validation rules. Although it can technically accept any sort of expression and be used elsewhere in the configuration, we recommend against using it in other contexts. For error handling elsewhere in the configuration, -prefer to use [`try`](/opentf/language/functions/try). +prefer to use [`try`](/docs/language/functions/try). ## Examples @@ -70,5 +70,5 @@ A local value with the name "nonexist" has not been declared. ## Related Functions -* [`try`](/opentf/language/functions/try), which tries evaluating a sequence of expressions and +* [`try`](/docs/language/functions/try), which tries evaluating a sequence of expressions and returns the result of the first one that succeeds. diff --git a/website/docs/language/functions/ceil.mdx b/website/docs/language/functions/ceil.mdx index 855ced0f44..888a21ec33 100644 --- a/website/docs/language/functions/ceil.mdx +++ b/website/docs/language/functions/ceil.mdx @@ -21,5 +21,5 @@ given value, which may be a fraction. ## Related Functions -* [`floor`](/opentf/language/functions/floor), which rounds to the nearest whole number _less than_ +* [`floor`](/docs/language/functions/floor), which rounds to the nearest whole number _less than_ or equal. diff --git a/website/docs/language/functions/chomp.mdx b/website/docs/language/functions/chomp.mdx index 6c34b6c3fe..1fae797a5e 100644 --- a/website/docs/language/functions/chomp.mdx +++ b/website/docs/language/functions/chomp.mdx @@ -23,5 +23,5 @@ hello ## Related Functions -* [`trimspace`](/opentf/language/functions/trimspace), which removes all types of whitespace from +* [`trimspace`](/docs/language/functions/trimspace), which removes all types of whitespace from both the start and the end of a string. diff --git a/website/docs/language/functions/cidrhost.mdx b/website/docs/language/functions/cidrhost.mdx index bfac87a265..4a528e8aa1 100644 --- a/website/docs/language/functions/cidrhost.mdx +++ b/website/docs/language/functions/cidrhost.mdx @@ -21,7 +21,7 @@ cidrhost(prefix, hostnum) no more than the number of digits remaining in the address after the given prefix. For more details on how this function interprets CIDR prefixes and populates host numbers, see the worked example for -[`cidrsubnet`](/opentf/language/functions/cidrsubnet). +[`cidrsubnet`](/docs/language/functions/cidrsubnet). Conventionally host number zero is used to represent the address of the network itself and the host number that would fill all the host bits with @@ -50,5 +50,5 @@ fd00:fd12:3456:7890::22 ## Related Functions -* [`cidrsubnet`](/opentf/language/functions/cidrsubnet) calculates a subnet address under a given +* [`cidrsubnet`](/docs/language/functions/cidrsubnet) calculates a subnet address under a given network address prefix. diff --git a/website/docs/language/functions/cidrsubnet.mdx b/website/docs/language/functions/cidrsubnet.mdx index a905c89abc..ca2290712d 100644 --- a/website/docs/language/functions/cidrsubnet.mdx +++ b/website/docs/language/functions/cidrsubnet.mdx @@ -27,7 +27,7 @@ additional bits added to the prefix. This function accepts both IPv6 and IPv4 prefixes, and the result always uses the same addressing scheme as the given prefix. -Unlike the related function [`cidrsubnets`](/opentf/language/functions/cidrsubnets), `cidrsubnet` +Unlike the related function [`cidrsubnets`](/docs/language/functions/cidrsubnets), `cidrsubnet` allows you to give a specific network number to use. `cidrsubnets` can allocate multiple network addresses at once, but numbers them automatically starting with zero. @@ -93,7 +93,7 @@ This gives us some additional information but also confirms (using a slightly different notation) the conversion from decimal to binary and shows the range of possible host addresses in this network. -While [`cidrhost`](/opentf/language/functions/cidrhost) allows calculating single host IP addresses, +While [`cidrhost`](/docs/language/functions/cidrhost) allows calculating single host IP addresses, `cidrsubnet` on the other hand creates a new network prefix _within_ the given network prefix. In other words, it creates a subnet. @@ -148,7 +148,7 @@ Hosts/Net: 14 Class A, Private Internet The new subnet has four bits available for host numbering, which means that there are 14 host addresses available for assignment once we subtract the network's own address and the broadcast address. You can thus use -[`cidrhost`](/opentf/language/functions/cidrhost) function to calculate those host addresses by +[`cidrhost`](/docs/language/functions/cidrhost) function to calculate those host addresses by providing it a value between 1 and 14: ``` @@ -163,9 +163,9 @@ For more information on CIDR notation and subnetting, see ## Related Functions -* [`cidrhost`](/opentf/language/functions/cidrhost) calculates the IP address for a single host +* [`cidrhost`](/docs/language/functions/cidrhost) calculates the IP address for a single host within a given network address prefix. -* [`cidrnetmask`](/opentf/language/functions/cidrnetmask) converts an IPv4 network prefix in CIDR +* [`cidrnetmask`](/docs/language/functions/cidrnetmask) converts an IPv4 network prefix in CIDR notation into netmask notation. -* [`cidrsubnets`](/opentf/language/functions/cidrsubnets) can allocate multiple consecutive +* [`cidrsubnets`](/docs/language/functions/cidrsubnets) can allocate multiple consecutive addresses under a prefix at once, numbering them automatically. diff --git a/website/docs/language/functions/cidrsubnets.mdx b/website/docs/language/functions/cidrsubnets.mdx index 7331f8bc5c..ffe802c1e8 100644 --- a/website/docs/language/functions/cidrsubnets.mdx +++ b/website/docs/language/functions/cidrsubnets.mdx @@ -23,7 +23,7 @@ value is therefore a list with one element per `newbits` argument, each a string containing an address range in CIDR notation. For more information on IP addressing concepts, see the documentation for the -related function [`cidrsubnet`](/opentf/language/functions/cidrsubnet). `cidrsubnet` calculates +related function [`cidrsubnet`](/docs/language/functions/cidrsubnet). `cidrsubnet` calculates a single subnet address within a prefix while allowing you to specify its subnet number, while `cidrsubnets` can calculate many at once, potentially of different sizes, and assigns subnet numbers automatically. @@ -69,7 +69,7 @@ platforms. ``` You can use nested `cidrsubnets` calls with -[`for` expressions](/opentf/language/expressions/for) +[`for` expressions](/docs/language/expressions/for) to concisely allocate groups of network address blocks: ``` @@ -96,9 +96,9 @@ to concisely allocate groups of network address blocks: ## Related Functions -* [`cidrhost`](/opentf/language/functions/cidrhost) calculates the IP address for a single host +* [`cidrhost`](/docs/language/functions/cidrhost) calculates the IP address for a single host within a given network address prefix. -* [`cidrnetmask`](/opentf/language/functions/cidrnetmask) converts an IPv4 network prefix in CIDR +* [`cidrnetmask`](/docs/language/functions/cidrnetmask) converts an IPv4 network prefix in CIDR notation into netmask notation. -* [`cidrsubnet`](/opentf/language/functions/cidrsubnet) calculates a single subnet address, allowing +* [`cidrsubnet`](/docs/language/functions/cidrsubnet) calculates a single subnet address, allowing you to specify its network number. diff --git a/website/docs/language/functions/coalesce.mdx b/website/docs/language/functions/coalesce.mdx index 5f29e241fd..4c07defabb 100644 --- a/website/docs/language/functions/coalesce.mdx +++ b/website/docs/language/functions/coalesce.mdx @@ -52,5 +52,5 @@ Call to function "coalesce" failed: all arguments must have the same type. ## Related Functions -* [`coalescelist`](/opentf/language/functions/coalescelist) performs a similar operation with +* [`coalescelist`](/docs/language/functions/coalescelist) performs a similar operation with list arguments rather than individual arguments. diff --git a/website/docs/language/functions/coalescelist.mdx b/website/docs/language/functions/coalescelist.mdx index c06ab1f40d..2354268911 100644 --- a/website/docs/language/functions/coalescelist.mdx +++ b/website/docs/language/functions/coalescelist.mdx @@ -38,5 +38,5 @@ symbol to expand the outer list as arguments: ## Related Functions -* [`coalesce`](/opentf/language/functions/coalesce) performs a similar operation with string +* [`coalesce`](/docs/language/functions/coalesce) performs a similar operation with string arguments rather than list arguments. diff --git a/website/docs/language/functions/csvdecode.mdx b/website/docs/language/functions/csvdecode.mdx index 0a92014752..0d2604f74a 100644 --- a/website/docs/language/functions/csvdecode.mdx +++ b/website/docs/language/functions/csvdecode.mdx @@ -39,7 +39,7 @@ number of fields, or this function will produce an error. ## Use with the `for_each` meta-argument You can use the result of `csvdecode` with -[the `for_each` meta-argument](/opentf/language/meta-arguments/for_each) +[the `for_each` meta-argument](/docs/language/meta-arguments/for_each) to describe a collection of similar objects whose differences are described by the rows in the given CSV file. @@ -87,7 +87,7 @@ create or destroy associated instances as appropriate. If there is no reasonable value you can use as a unique identifier in your CSV then you could instead use -[the `count` meta-argument](/opentf/language/meta-arguments/count) +[the `count` meta-argument](/docs/language/meta-arguments/count) to define an object for each CSV row, with each one identified by its index into the list returned by `csvdecode`. However, in that case any future updates to the CSV may be disruptive if they change the positions of particular objects in diff --git a/website/docs/language/functions/dirname.mdx b/website/docs/language/functions/dirname.mdx index 7d4e653502..f3a5ce4700 100644 --- a/website/docs/language/functions/dirname.mdx +++ b/website/docs/language/functions/dirname.mdx @@ -23,7 +23,7 @@ any slashes in the given path will be replaced by backslashes before returning. Referring directly to filesystem paths in resource arguments may cause spurious diffs if the same configuration is applied from multiple systems or on different host operating systems. We recommend using filesystem paths only -for transient values, such as the argument to [`file`](/opentf/language/functions/file) (where +for transient values, such as the argument to [`file`](/docs/language/functions/file) (where only the contents are then stored) or in `connection` and `provisioner` blocks. ## Examples @@ -35,5 +35,5 @@ foo/bar ## Related Functions -* [`basename`](/opentf/language/functions/basename) returns _only_ the last portion of a filesystem +* [`basename`](/docs/language/functions/basename) returns _only_ the last portion of a filesystem path, discarding the portion that would be returned by `dirname`. diff --git a/website/docs/language/functions/element.mdx b/website/docs/language/functions/element.mdx index 9f49f82f83..65f0a059b8 100644 --- a/website/docs/language/functions/element.mdx +++ b/website/docs/language/functions/element.mdx @@ -32,7 +32,7 @@ If the given index is greater than the length of the list then the index is a ``` -To get the last element from the list use [`length`](/opentf/language/functions/length) to find +To get the last element from the list use [`length`](/docs/language/functions/length) to find the size of the list (minus 1 as the list is zero-based) and then pick the last element: @@ -43,5 +43,5 @@ c ## Related Functions -* [`index`](/opentf/language/functions/index_function) finds the index for a particular element value. -* [`lookup`](/opentf/language/functions/lookup) retrieves a value from a _map_ given its _key_. +* [`index`](/docs/language/functions/index_function) finds the index for a particular element value. +* [`lookup`](/docs/language/functions/lookup) retrieves a value from a _map_ given its _key_. diff --git a/website/docs/language/functions/endswith.mdx b/website/docs/language/functions/endswith.mdx index 247a5fcad0..d554134d59 100644 --- a/website/docs/language/functions/endswith.mdx +++ b/website/docs/language/functions/endswith.mdx @@ -24,4 +24,4 @@ false ## Related Functions -- [`startswith`](/opentf/language/functions/startswith) takes two values: a string to check and a prefix string. The function returns true if the string begins with that exact prefix. +- [`startswith`](/docs/language/functions/startswith) takes two values: a string to check and a prefix string. The function returns true if the string begins with that exact prefix. diff --git a/website/docs/language/functions/file.mdx b/website/docs/language/functions/file.mdx index d32ac54eeb..ec0715d4f6 100644 --- a/website/docs/language/functions/file.mdx +++ b/website/docs/language/functions/file.mdx @@ -37,10 +37,10 @@ Hello World ## Related Functions -* [`filebase64`](/opentf/language/functions/filebase64) also reads the contents of a given file, +* [`filebase64`](/docs/language/functions/filebase64) also reads the contents of a given file, but returns the raw bytes in that file Base64-encoded, rather than interpreting the contents as UTF-8 text. -* [`fileexists`](/opentf/language/functions/fileexists) determines whether a file exists +* [`fileexists`](/docs/language/functions/fileexists) determines whether a file exists at a given path. -* [`templatefile`](/opentf/language/functions/templatefile) renders using a file from disk as a +* [`templatefile`](/docs/language/functions/templatefile) renders using a file from disk as a template. diff --git a/website/docs/language/functions/filebase64.mdx b/website/docs/language/functions/filebase64.mdx index f4d401d959..d59022c3b7 100644 --- a/website/docs/language/functions/filebase64.mdx +++ b/website/docs/language/functions/filebase64.mdx @@ -38,9 +38,9 @@ SGVsbG8gV29ybGQ= ## Related Functions -* [`file`](/opentf/language/functions/file) also reads the contents of a given file, +* [`file`](/docs/language/functions/file) also reads the contents of a given file, but interprets the data as UTF-8 text and returns the result directly as a string, without any further encoding. -* [`base64decode`](/opentf/language/functions/base64decode) can decode a Base64 string representing +* [`base64decode`](/docs/language/functions/base64decode) can decode a Base64 string representing bytes in UTF-8, but in practice `base64decode(filebase64(...))` is equivalent to the shorter expression `file(...)`. diff --git a/website/docs/language/functions/filebase64sha256.mdx b/website/docs/language/functions/filebase64sha256.mdx index 09f745f010..af9e3daad7 100644 --- a/website/docs/language/functions/filebase64sha256.mdx +++ b/website/docs/language/functions/filebase64sha256.mdx @@ -7,9 +7,9 @@ description: |- # `filebase64sha256` Function -`filebase64sha256` is a variant of [`base64sha256`](/opentf/language/functions/base64sha256) +`filebase64sha256` is a variant of [`base64sha256`](/docs/language/functions/base64sha256) that hashes the contents of a given file rather than a literal string. This is similar to `base64sha256(file(filename))`, but -because [`file`](/opentf/language/functions/file) accepts only UTF-8 text it cannot be used to +because [`file`](/docs/language/functions/file) accepts only UTF-8 text it cannot be used to create hashes for binary files. diff --git a/website/docs/language/functions/filebase64sha512.mdx b/website/docs/language/functions/filebase64sha512.mdx index 34e5564265..b653359179 100644 --- a/website/docs/language/functions/filebase64sha512.mdx +++ b/website/docs/language/functions/filebase64sha512.mdx @@ -7,9 +7,9 @@ description: |- # `filebase64sha512` Function -`filebase64sha512` is a variant of [`base64sha512`](/opentf/language/functions/base64sha512) +`filebase64sha512` is a variant of [`base64sha512`](/docs/language/functions/base64sha512) that hashes the contents of a given file rather than a literal string. This is similar to `base64sha512(file(filename))`, but -because [`file`](/opentf/language/functions/file) accepts only UTF-8 text it cannot be used to +because [`file`](/docs/language/functions/file) accepts only UTF-8 text it cannot be used to create hashes for binary files. diff --git a/website/docs/language/functions/fileexists.mdx b/website/docs/language/functions/fileexists.mdx index dc9c260b14..f5216b71d4 100644 --- a/website/docs/language/functions/fileexists.mdx +++ b/website/docs/language/functions/fileexists.mdx @@ -31,4 +31,4 @@ fileexists("custom-section.sh") ? file("custom-section.sh") : local.default_cont ## Related Functions -* [`file`](/opentf/language/functions/file) reads the contents of a file at a given path +* [`file`](/docs/language/functions/file) reads the contents of a file at a given path diff --git a/website/docs/language/functions/filemd5.mdx b/website/docs/language/functions/filemd5.mdx index 86685f9bfa..808334b5de 100644 --- a/website/docs/language/functions/filemd5.mdx +++ b/website/docs/language/functions/filemd5.mdx @@ -7,9 +7,9 @@ description: |- # `filemd5` Function -`filemd5` is a variant of [`md5`](/opentf/language/functions/md5) +`filemd5` is a variant of [`md5`](/docs/language/functions/md5) that hashes the contents of a given file rather than a literal string. This is similar to `md5(file(filename))`, but -because [`file`](/opentf/language/functions/file) accepts only UTF-8 text it cannot be used to +because [`file`](/docs/language/functions/file) accepts only UTF-8 text it cannot be used to create hashes for binary files. diff --git a/website/docs/language/functions/fileset.mdx b/website/docs/language/functions/fileset.mdx index 3201309bdf..c8694e37e4 100644 --- a/website/docs/language/functions/fileset.mdx +++ b/website/docs/language/functions/fileset.mdx @@ -66,7 +66,7 @@ before OpenTF takes any actions. ``` A common use of `fileset` is to create one resource instance per matched file, using -[the `for_each` meta-argument](/opentf/language/meta-arguments/for_each): +[the `for_each` meta-argument](/docs/language/meta-arguments/for_each): ```hcl resource "example_thing" "example" { diff --git a/website/docs/language/functions/filesha1.mdx b/website/docs/language/functions/filesha1.mdx index 130754d21f..7f389e952d 100644 --- a/website/docs/language/functions/filesha1.mdx +++ b/website/docs/language/functions/filesha1.mdx @@ -7,9 +7,9 @@ description: |- # `filesha1` Function -`filesha1` is a variant of [`sha1`](/opentf/language/functions/sha1) +`filesha1` is a variant of [`sha1`](/docs/language/functions/sha1) that hashes the contents of a given file rather than a literal string. This is similar to `sha1(file(filename))`, but -because [`file`](/opentf/language/functions/file) accepts only UTF-8 text it cannot be used to +because [`file`](/docs/language/functions/file) accepts only UTF-8 text it cannot be used to create hashes for binary files. diff --git a/website/docs/language/functions/filesha256.mdx b/website/docs/language/functions/filesha256.mdx index ff86fcda1c..03802583e0 100644 --- a/website/docs/language/functions/filesha256.mdx +++ b/website/docs/language/functions/filesha256.mdx @@ -7,9 +7,9 @@ description: |- # `filesha256` Function -`filesha256` is a variant of [`sha256`](/opentf/language/functions/sha256) +`filesha256` is a variant of [`sha256`](/docs/language/functions/sha256) that hashes the contents of a given file rather than a literal string. This is similar to `sha256(file(filename))`, but -because [`file`](/opentf/language/functions/file) accepts only UTF-8 text it cannot be used to +because [`file`](/docs/language/functions/file) accepts only UTF-8 text it cannot be used to create hashes for binary files. diff --git a/website/docs/language/functions/filesha512.mdx b/website/docs/language/functions/filesha512.mdx index 757a03e383..5106542bc7 100644 --- a/website/docs/language/functions/filesha512.mdx +++ b/website/docs/language/functions/filesha512.mdx @@ -7,9 +7,9 @@ description: |- # `filesha512` Function -`filesha512` is a variant of [`sha512`](/opentf/language/functions/sha512) +`filesha512` is a variant of [`sha512`](/docs/language/functions/sha512) that hashes the contents of a given file rather than a literal string. This is similar to `sha512(file(filename))`, but -because [`file`](/opentf/language/functions/file) accepts only UTF-8 text it cannot be used to +because [`file`](/docs/language/functions/file) accepts only UTF-8 text it cannot be used to create hashes for binary files. diff --git a/website/docs/language/functions/flatten.mdx b/website/docs/language/functions/flatten.mdx index 2521145526..97bc7fc42b 100644 --- a/website/docs/language/functions/flatten.mdx +++ b/website/docs/language/functions/flatten.mdx @@ -28,9 +28,9 @@ Indirectly-nested lists, such as those in maps, are _not_ flattened. ## Flattening nested structures for `for_each` The -[resource `for_each`](/opentf/language/meta-arguments/for_each) +[resource `for_each`](/docs/language/meta-arguments/for_each) and -[`dynamic` block](/opentf/language/expressions/dynamic-blocks) +[`dynamic` block](/docs/language/expressions/dynamic-blocks) language features both require a collection value that has one element for each repetition. @@ -101,6 +101,6 @@ the associations between the subnets and their containing networks. ## Related Functions -* [`setproduct`](/opentf/language/functions/setproduct) finds all of the combinations of multiple +* [`setproduct`](/docs/language/functions/setproduct) finds all of the combinations of multiple lists or sets of values, which can also be useful when preparing collections for use with `for_each` constructs. diff --git a/website/docs/language/functions/floor.mdx b/website/docs/language/functions/floor.mdx index cb01071e9c..275d93511c 100644 --- a/website/docs/language/functions/floor.mdx +++ b/website/docs/language/functions/floor.mdx @@ -21,5 +21,5 @@ given value, which may be a fraction. ## Related Functions -* [`ceil`](/opentf/language/functions/ceil), which rounds to the nearest whole number _greater than_ +* [`ceil`](/docs/language/functions/ceil), which rounds to the nearest whole number _greater than_ or equal. diff --git a/website/docs/language/functions/format.mdx b/website/docs/language/functions/format.mdx index 19140165bd..6207877fde 100644 --- a/website/docs/language/functions/format.mdx +++ b/website/docs/language/functions/format.mdx @@ -34,7 +34,7 @@ Hello, Valentina! Hello, Valentina! ``` -The formatting verb `%#v` accepts a value of any type and presents it using JSON encoding, similar to jsonencode. This can be useful for describing the values given to a module in [custom condition check](/opentf/language/expressions/custom-conditions#error-messages) error messages. +The formatting verb `%#v` accepts a value of any type and presents it using JSON encoding, similar to jsonencode. This can be useful for describing the values given to a module in [custom condition check](/docs/language/expressions/custom-conditions#error-messages) error messages. ``` > format("%#v", "hello") @@ -139,7 +139,7 @@ Use the following symbols immediately after the `%` symbol to set additional for ## Related Functions -* [`formatdate`](/opentf/language/functions/formatdate) is a specialized formatting function for +* [`formatdate`](/docs/language/functions/formatdate) is a specialized formatting function for human-readable timestamps. -* [`formatlist`](/opentf/language/functions/formatlist) uses the same specification syntax to +* [`formatlist`](/docs/language/functions/formatlist) uses the same specification syntax to produce a list of strings. diff --git a/website/docs/language/functions/formatdate.mdx b/website/docs/language/functions/formatdate.mdx index dd346f7725..568c7b9f11 100644 --- a/website/docs/language/functions/formatdate.mdx +++ b/website/docs/language/functions/formatdate.mdx @@ -99,7 +99,7 @@ configuration as needed: ## Related Functions -- [`format`](/opentf/language/functions/format) is a more general formatting function for arbitrary +- [`format`](/docs/language/functions/format) is a more general formatting function for arbitrary data. -- [`timestamp`](/opentf/language/functions/timestamp) returns the current date and time in a format +- [`timestamp`](/docs/language/functions/timestamp) returns the current date and time in a format suitable for input to `formatdate`. diff --git a/website/docs/language/functions/formatlist.mdx b/website/docs/language/functions/formatlist.mdx index 44b1b7ce96..3e2f7183fb 100644 --- a/website/docs/language/functions/formatlist.mdx +++ b/website/docs/language/functions/formatlist.mdx @@ -15,7 +15,7 @@ formatlist(spec, values...) ``` The specification string uses -[the same syntax as `format`](/opentf/language/functions/format#specification-syntax). +[the same syntax as `format`](/docs/language/functions/format#specification-syntax). The given values can be a mixture of list and non-list arguments. Any given lists must be the same length, which decides the length of the resulting list. @@ -45,5 +45,5 @@ once per element of the list arguments. ## Related Functions -* [`format`](/opentf/language/functions/format) defines the specification syntax used by this +* [`format`](/docs/language/functions/format) defines the specification syntax used by this function and produces a single string as its result. diff --git a/website/docs/language/functions/index.mdx b/website/docs/language/functions/index.mdx index af5fb19c69..d2b86faaea 100644 --- a/website/docs/language/functions/index.mdx +++ b/website/docs/language/functions/index.mdx @@ -17,7 +17,7 @@ max(5, 12, 9) ``` For more details on syntax, see -[_Function Calls_](/opentf/language/expressions/function-calls) +[_Function Calls_](/docs/language/expressions/function-calls) in the Expressions section. The OpenTF language does not support user-defined functions, and so only @@ -25,7 +25,7 @@ the functions built in to the language are available for use. The documentation You can experiment with the behavior of OpenTF's built-in functions from the OpenTF expression console, by running -[the `opentf console` command](/opentf/cli/commands/console): +[the `opentf console` command](/docs/cli/commands/console): ``` > max(5, 12, 9) diff --git a/website/docs/language/functions/index_function.mdx b/website/docs/language/functions/index_function.mdx index 7c514bba1e..7e89eb0aa2 100644 --- a/website/docs/language/functions/index_function.mdx +++ b/website/docs/language/functions/index_function.mdx @@ -23,5 +23,5 @@ value is not present in the list. ## Related Functions -* [`element`](/opentf/language/functions/element) retrieves a particular element from a list given +* [`element`](/docs/language/functions/element) retrieves a particular element from a list given its index. diff --git a/website/docs/language/functions/join.mdx b/website/docs/language/functions/join.mdx index 1bdb052f6e..7daaa4d4b7 100644 --- a/website/docs/language/functions/join.mdx +++ b/website/docs/language/functions/join.mdx @@ -27,5 +27,5 @@ foo ## Related Functions -* [`split`](/opentf/language/functions/split) performs the opposite operation: producing a list +* [`split`](/docs/language/functions/split) performs the opposite operation: producing a list by separating a single string using a given delimiter. diff --git a/website/docs/language/functions/jsondecode.mdx b/website/docs/language/functions/jsondecode.mdx index 434340a7e1..23963cec2e 100644 --- a/website/docs/language/functions/jsondecode.mdx +++ b/website/docs/language/functions/jsondecode.mdx @@ -13,7 +13,7 @@ of the result of decoding that string. The JSON encoding is defined in [RFC 7159](https://tools.ietf.org/html/rfc7159). This function maps JSON values to -[OpenTF language values](/opentf/language/expressions/types) +[OpenTF language values](/docs/language/expressions/types) in the following way: | JSON type | OpenTF type | @@ -42,5 +42,5 @@ true ## Related Functions -* [`jsonencode`](/opentf/language/functions/jsonencode) performs the opposite operation, _encoding_ +* [`jsonencode`](/docs/language/functions/jsonencode) performs the opposite operation, _encoding_ a value as JSON. diff --git a/website/docs/language/functions/jsonencode.mdx b/website/docs/language/functions/jsonencode.mdx index f5db7ea081..2187a3bd64 100644 --- a/website/docs/language/functions/jsonencode.mdx +++ b/website/docs/language/functions/jsonencode.mdx @@ -10,7 +10,7 @@ description: The jsonencode function encodes a given value as a JSON string. The JSON encoding is defined in [RFC 7159](https://tools.ietf.org/html/rfc7159). This function maps -[OpenTF language values](/opentf/language/expressions/types) +[OpenTF language values](/docs/language/expressions/types) to JSON values in the following way: | OpenTF type | JSON type | @@ -45,5 +45,5 @@ The `jsonencode` command outputs a minified representation of the input. ## Related Functions -* [`jsondecode`](/opentf/language/functions/jsondecode) performs the opposite operation, _decoding_ +* [`jsondecode`](/docs/language/functions/jsondecode) performs the opposite operation, _decoding_ a JSON string to obtain its represented value. diff --git a/website/docs/language/functions/keys.mdx b/website/docs/language/functions/keys.mdx index af6e58a4b8..d63a9bbf6f 100644 --- a/website/docs/language/functions/keys.mdx +++ b/website/docs/language/functions/keys.mdx @@ -23,4 +23,4 @@ be identical as long as the keys in the map don't change. ## Related Functions -* [`values`](/opentf/language/functions/values) returns a list of the _values_ from a map. +* [`values`](/docs/language/functions/values) returns a list of the _values_ from a map. diff --git a/website/docs/language/functions/lookup.mdx b/website/docs/language/functions/lookup.mdx index 03d25e0be5..d458e20cac 100644 --- a/website/docs/language/functions/lookup.mdx +++ b/website/docs/language/functions/lookup.mdx @@ -27,4 +27,4 @@ what? ## Related Functions -* [`element`](/opentf/language/functions/element) retrieves a value from a _list_ given its _index_. +* [`element`](/docs/language/functions/element) retrieves a value from a _list_ given its _index_. diff --git a/website/docs/language/functions/lower.mdx b/website/docs/language/functions/lower.mdx index a9465e4027..bb80370018 100644 --- a/website/docs/language/functions/lower.mdx +++ b/website/docs/language/functions/lower.mdx @@ -22,5 +22,5 @@ This function uses Unicode's definition of letters and of upper- and lowercase. ## Related Functions -* [`upper`](/opentf/language/functions/upper) converts letters in a string to _uppercase_. -* [`title`](/opentf/language/functions/title) converts the first letter of each word in a string to uppercase. +* [`upper`](/docs/language/functions/upper) converts letters in a string to _uppercase_. +* [`title`](/docs/language/functions/title) converts the first letter of each word in a string to uppercase. diff --git a/website/docs/language/functions/max.mdx b/website/docs/language/functions/max.mdx index 623f7be01c..ce8c9b7db9 100644 --- a/website/docs/language/functions/max.mdx +++ b/website/docs/language/functions/max.mdx @@ -24,4 +24,4 @@ to individual arguments: ## Related Functions -* [`min`](/opentf/language/functions/min), which returns the _smallest_ number from a set. +* [`min`](/docs/language/functions/min), which returns the _smallest_ number from a set. diff --git a/website/docs/language/functions/md5.mdx b/website/docs/language/functions/md5.mdx index 110b6018bd..1d64d01ac1 100644 --- a/website/docs/language/functions/md5.mdx +++ b/website/docs/language/functions/md5.mdx @@ -27,5 +27,5 @@ considerations applying to the MD5 algorithm. ## Related Functions -* [`filemd5`](/opentf/language/functions/filemd5) calculates the same hash from +* [`filemd5`](/docs/language/functions/filemd5) calculates the same hash from the contents of a file rather than from a string value. diff --git a/website/docs/language/functions/merge.mdx b/website/docs/language/functions/merge.mdx index 5e93535149..220676b780 100644 --- a/website/docs/language/functions/merge.mdx +++ b/website/docs/language/functions/merge.mdx @@ -39,7 +39,7 @@ type structure of the attributes after the merging rules have been applied. } ``` -The following example uses the expansion symbol (...) to transform the value into separate arguments. Refer to [Expanding Function Argument](/opentf/language/expressions/function-calls#expanding-function-arguments) for details. +The following example uses the expansion symbol (...) to transform the value into separate arguments. Refer to [Expanding Function Argument](/docs/language/expressions/function-calls#expanding-function-arguments) for details. ``` > merge([{a="b", c="d"}, {}, {e="f", c="z"}]...) diff --git a/website/docs/language/functions/min.mdx b/website/docs/language/functions/min.mdx index e2836dcb8b..dd518ad72f 100644 --- a/website/docs/language/functions/min.mdx +++ b/website/docs/language/functions/min.mdx @@ -24,4 +24,4 @@ to individual arguments: ## Related Functions -* [`max`](/opentf/language/functions/max), which returns the _greatest_ number from a set. +* [`max`](/docs/language/functions/max), which returns the _greatest_ number from a set. diff --git a/website/docs/language/functions/one.mdx b/website/docs/language/functions/one.mdx index cc80cd5c0d..af805a93a7 100644 --- a/website/docs/language/functions/one.mdx +++ b/website/docs/language/functions/one.mdx @@ -45,7 +45,7 @@ no instances were created. ## Relationship to the "Splat" Operator The OpenTF language has a built-in operator `[*]`, known as -[the _splat_ operator](/opentf/language/expressions/splat), and one of its functions +[the _splat_ operator](/docs/language/expressions/splat), and one of its functions is to translate a primitive value that might be null into a list of either zero or one elements: diff --git a/website/docs/language/functions/parseint.mdx b/website/docs/language/functions/parseint.mdx index 4f8f9a77e5..283af2f388 100644 --- a/website/docs/language/functions/parseint.mdx +++ b/website/docs/language/functions/parseint.mdx @@ -46,5 +46,5 @@ Invalid value for "number" parameter: cannot parse "12" as a base 2 integer. ## Related Functions -* [`format`](/opentf/language/functions/format) can format numbers and other values into strings, +* [`format`](/docs/language/functions/format) can format numbers and other values into strings, with optional zero padding, alignment, etc. diff --git a/website/docs/language/functions/plantimestamp.mdx b/website/docs/language/functions/plantimestamp.mdx index 0b8505d4d9..ef092f2220 100644 --- a/website/docs/language/functions/plantimestamp.mdx +++ b/website/docs/language/functions/plantimestamp.mdx @@ -15,10 +15,10 @@ strings using [RFC 3339](https://tools.ietf.org/html/rfc3339) in this format. The result of this function will change for every plan operation. It is intended -for use within [Custom Conditions](/opentf/language/expressions/custom-conditions) +for use within [Custom Conditions](/docs/language/expressions/custom-conditions) as a way to validate time sensitive resources such as TLS certificates. -There are circumstances, such as during an OpenTF [Refresh-only](/opentf/cli/commands/plan#planning-modes) plan, where +There are circumstances, such as during an OpenTF [Refresh-only](/docs/cli/commands/plan#planning-modes) plan, where the value for this function will be recomputed but not propagated to resources defined within the configuration. As such, it is recommended that this function only be used to compare against timestamps exported by providers and not against @@ -48,5 +48,5 @@ check "placeholderplaceholderplaceholder_io_certificate" { ## Related Functions -* [`timestamp`](/opentf/language/functions/timestamp) returns the current timestamp when it is evaluated +* [`timestamp`](/docs/language/functions/timestamp) returns the current timestamp when it is evaluated during the apply step. diff --git a/website/docs/language/functions/regex.mdx b/website/docs/language/functions/regex.mdx index b10fb94a01..09c02eca09 100644 --- a/website/docs/language/functions/regex.mdx +++ b/website/docs/language/functions/regex.mdx @@ -30,7 +30,7 @@ It's not valid to mix both named and unnamed capture groups in the same pattern. If the given pattern does not match at all, the `regex` raises an error. To _test_ whether a given pattern matches a string, use -[`regexall`](/opentf/language/functions/regexall) and test that the result has length greater than +[`regexall`](/docs/language/functions/regexall) and test that the result has length greater than zero. The pattern is a string containing a mixture of literal characters and special @@ -152,8 +152,8 @@ string. ## Related Functions -- [`regexall`](/opentf/language/functions/regexall) searches for potentially multiple matches of a given pattern in a string. -- [`replace`](/opentf/language/functions/replace) replaces a substring of a string with another string, optionally matching using the same regular expression syntax as `regex`. +- [`regexall`](/docs/language/functions/regexall) searches for potentially multiple matches of a given pattern in a string. +- [`replace`](/docs/language/functions/replace) replaces a substring of a string with another string, optionally matching using the same regular expression syntax as `regex`. If OpenTF already has a more specialized function to parse the syntax you are trying to match, prefer to use that function instead. Regular expressions diff --git a/website/docs/language/functions/regexall.mdx b/website/docs/language/functions/regexall.mdx index 487e84550c..f21741ebd1 100644 --- a/website/docs/language/functions/regexall.mdx +++ b/website/docs/language/functions/regexall.mdx @@ -15,7 +15,7 @@ to a string and returns a list of all matches. regexall(pattern, string) ``` -`regexall` is a variant of [`regex`](/opentf/language/functions/regex) and uses the same pattern +`regexall` is a variant of [`regex`](/docs/language/functions/regex) and uses the same pattern syntax. For any given input to `regex`, `regexall` returns a list of whatever type `regex` would've returned, with one element per match. That is: @@ -48,7 +48,7 @@ false ## Related Functions -- [`regex`](/opentf/language/functions/regex) searches for a single match of a given pattern, and +- [`regex`](/docs/language/functions/regex) searches for a single match of a given pattern, and returns an error if no match is found. If OpenTF already has a more specialized function to parse the syntax you diff --git a/website/docs/language/functions/replace.mdx b/website/docs/language/functions/replace.mdx index 8056ffc5b6..0114341b04 100644 --- a/website/docs/language/functions/replace.mdx +++ b/website/docs/language/functions/replace.mdx @@ -16,7 +16,7 @@ replace(string, substring, replacement) If `substring` is wrapped in forward slashes, it is treated as a regular expression, using the same pattern syntax as -[`regex`](/opentf/language/functions/regex). If using a regular expression for the substring +[`regex`](/docs/language/functions/regex). If using a regular expression for the substring argument, the `replacement` string can incorporate captured strings from the input by using an `$n` sequence, where `n` is the index or name of a capture group. @@ -33,5 +33,5 @@ hello everybody ## Related Functions -- [`regex`](/opentf/language/functions/regex) searches a given string for a substring matching a +- [`regex`](/docs/language/functions/regex) searches a given string for a substring matching a given regular expression pattern. diff --git a/website/docs/language/functions/reverse.mdx b/website/docs/language/functions/reverse.mdx index da20b62a43..4bf23fa710 100644 --- a/website/docs/language/functions/reverse.mdx +++ b/website/docs/language/functions/reverse.mdx @@ -21,4 +21,4 @@ with all of the same elements as the given sequence but in reverse order. ## Related Functions -* [`strrev`](/opentf/language/functions/strrev) reverses a string. +* [`strrev`](/docs/language/functions/strrev) reverses a string. diff --git a/website/docs/language/functions/sensitive.mdx b/website/docs/language/functions/sensitive.mdx index 538abd7002..c73906139f 100644 --- a/website/docs/language/functions/sensitive.mdx +++ b/website/docs/language/functions/sensitive.mdx @@ -7,7 +7,7 @@ description: The sensitive function marks a value as being sensitive. `sensitive` takes any value and returns a copy of it marked so that OpenTF will treat it as sensitive, with the same meaning and behavior as for -[sensitive input variables](/opentf/language/values/variables#suppressing-values-in-cli-output). +[sensitive input variables](/docs/language/values/variables#suppressing-values-in-cli-output). Wherever possible we recommend marking your input variable and/or output value declarations as sensitive directly, instead of using this function, because in diff --git a/website/docs/language/functions/setintersection.mdx b/website/docs/language/functions/setintersection.mdx index 433dd44656..9337e5be11 100644 --- a/website/docs/language/functions/setintersection.mdx +++ b/website/docs/language/functions/setintersection.mdx @@ -30,10 +30,10 @@ the ordering of the given elements is not preserved. ## Related Functions -* [`contains`](/opentf/language/functions/contains) tests whether a given list or set contains +* [`contains`](/docs/language/functions/contains) tests whether a given list or set contains a given element value. -* [`setproduct`](/opentf/language/functions/setproduct) computes the _Cartesian product_ of multiple +* [`setproduct`](/docs/language/functions/setproduct) computes the _Cartesian product_ of multiple sets. -* [`setsubtract`](/opentf/language/functions/setsubtract) computes the _relative complement_ of two sets -* [`setunion`](/opentf/language/functions/setunion) computes the _union_ of +* [`setsubtract`](/docs/language/functions/setsubtract) computes the _relative complement_ of two sets +* [`setunion`](/docs/language/functions/setunion) computes the _union_ of multiple sets. diff --git a/website/docs/language/functions/setproduct.mdx b/website/docs/language/functions/setproduct.mdx index cea692e79d..2cb4d202d0 100644 --- a/website/docs/language/functions/setproduct.mdx +++ b/website/docs/language/functions/setproduct.mdx @@ -115,9 +115,9 @@ elements all have a consistent type: ## Finding combinations for `for_each` The -[resource `for_each`](/opentf/language/meta-arguments/for_each) +[resource `for_each`](/docs/language/meta-arguments/for_each) and -[`dynamic` block](/opentf/language/expressions/dynamic-blocks) +[`dynamic` block](/docs/language/expressions/dynamic-blocks) language features both require a collection value that has one element for each repetition. @@ -269,13 +269,13 @@ The `network_subnets` output would look similar to the following: ## Related Functions -- [`contains`](/opentf/language/functions/contains) tests whether a given list or set contains +- [`contains`](/docs/language/functions/contains) tests whether a given list or set contains a given element value. -- [`flatten`](/opentf/language/functions/flatten) is useful for flattening hierarchical data +- [`flatten`](/docs/language/functions/flatten) is useful for flattening hierarchical data into a single list, for situations where the relationships between two object types are defined explicitly. -- [`setintersection`](/opentf/language/functions/setintersection) computes the _intersection_ of +- [`setintersection`](/docs/language/functions/setintersection) computes the _intersection_ of multiple sets. -- [`setsubtract`](/opentf/language/functions/setsubtract) computes the _relative complement_ of two sets -- [`setunion`](/opentf/language/functions/setunion) computes the _union_ of multiple +- [`setsubtract`](/docs/language/functions/setsubtract) computes the _relative complement_ of two sets +- [`setunion`](/docs/language/functions/setunion) computes the _union_ of multiple sets. diff --git a/website/docs/language/functions/setsubtract.mdx b/website/docs/language/functions/setsubtract.mdx index cc2f67754e..e91a408769 100644 --- a/website/docs/language/functions/setsubtract.mdx +++ b/website/docs/language/functions/setsubtract.mdx @@ -35,8 +35,8 @@ toset([ ## Related Functions -* [`setintersection`](/opentf/language/functions/setintersection) computes the _intersection_ of multiple sets -* [`setproduct`](/opentf/language/functions/setproduct) computes the _Cartesian product_ of multiple +* [`setintersection`](/docs/language/functions/setintersection) computes the _intersection_ of multiple sets +* [`setproduct`](/docs/language/functions/setproduct) computes the _Cartesian product_ of multiple sets. -* [`setunion`](/opentf/language/functions/setunion) computes the _union_ of +* [`setunion`](/docs/language/functions/setunion) computes the _union_ of multiple sets. diff --git a/website/docs/language/functions/setunion.mdx b/website/docs/language/functions/setunion.mdx index 7574f1cf85..7f9e9e2805 100644 --- a/website/docs/language/functions/setunion.mdx +++ b/website/docs/language/functions/setunion.mdx @@ -33,10 +33,10 @@ the ordering of the given elements is not preserved. ## Related Functions -* [`contains`](/opentf/language/functions/contains) tests whether a given list or set contains +* [`contains`](/docs/language/functions/contains) tests whether a given list or set contains a given element value. -* [`setintersection`](/opentf/language/functions/setintersection) computes the _intersection_ of +* [`setintersection`](/docs/language/functions/setintersection) computes the _intersection_ of multiple sets. -* [`setproduct`](/opentf/language/functions/setproduct) computes the _Cartesian product_ of multiple +* [`setproduct`](/docs/language/functions/setproduct) computes the _Cartesian product_ of multiple sets. -* [`setsubtract`](/opentf/language/functions/setsubtract) computes the _relative complement_ of two sets +* [`setsubtract`](/docs/language/functions/setsubtract) computes the _relative complement_ of two sets diff --git a/website/docs/language/functions/sha1.mdx b/website/docs/language/functions/sha1.mdx index e1decf06bd..dcffab0c78 100644 --- a/website/docs/language/functions/sha1.mdx +++ b/website/docs/language/functions/sha1.mdx @@ -27,5 +27,5 @@ relevant literature to understand the security implications. ## Related Functions -* [`filesha1`](/opentf/language/functions/filesha1) calculates the same hash from +* [`filesha1`](/docs/language/functions/filesha1) calculates the same hash from the contents of a file rather than from a string value. diff --git a/website/docs/language/functions/sha256.mdx b/website/docs/language/functions/sha256.mdx index 32c294f779..677a886a8e 100644 --- a/website/docs/language/functions/sha256.mdx +++ b/website/docs/language/functions/sha256.mdx @@ -25,7 +25,7 @@ b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 ## Related Functions -* [`filesha256`](/opentf/language/functions/filesha256) calculates the same hash from +* [`filesha256`](/docs/language/functions/filesha256) calculates the same hash from the contents of a file rather than from a string value. -* [`base64sha256`](/opentf/language/functions/base64sha256) calculates the same hash but returns +* [`base64sha256`](/docs/language/functions/base64sha256) calculates the same hash but returns the result in a more-compact Base64 encoding. diff --git a/website/docs/language/functions/sha512.mdx b/website/docs/language/functions/sha512.mdx index f055123172..fe079817b4 100644 --- a/website/docs/language/functions/sha512.mdx +++ b/website/docs/language/functions/sha512.mdx @@ -23,7 +23,7 @@ then encoded to lowercase hexadecimal digits before returning. ## Related Functions -* [`filesha512`](/opentf/language/functions/filesha512) calculates the same hash from +* [`filesha512`](/docs/language/functions/filesha512) calculates the same hash from the contents of a file rather than from a string value. -* [`base64sha512`](/opentf/language/functions/base64sha512) calculates the same hash but returns +* [`base64sha512`](/docs/language/functions/base64sha512) calculates the same hash but returns the result in a more-compact Base64 encoding. diff --git a/website/docs/language/functions/slice.mdx b/website/docs/language/functions/slice.mdx index 8ea9ce6290..c5a671cf17 100644 --- a/website/docs/language/functions/slice.mdx +++ b/website/docs/language/functions/slice.mdx @@ -27,5 +27,5 @@ list. ## Related Functions -* [`substr`](/opentf/language/functions/substr) performs a similar function for characters in a +* [`substr`](/docs/language/functions/substr) performs a similar function for characters in a string, although it uses a length instead of an end index. diff --git a/website/docs/language/functions/split.mdx b/website/docs/language/functions/split.mdx index f51b546d51..478852f7ee 100644 --- a/website/docs/language/functions/split.mdx +++ b/website/docs/language/functions/split.mdx @@ -35,5 +35,5 @@ split(separator, string) ## Related Functions -* [`join`](/opentf/language/functions/join) performs the opposite operation: producing a string +* [`join`](/docs/language/functions/join) performs the opposite operation: producing a string joining together a list of strings with a given separator. diff --git a/website/docs/language/functions/startswith.mdx b/website/docs/language/functions/startswith.mdx index f155f1be05..4124ac02b0 100644 --- a/website/docs/language/functions/startswith.mdx +++ b/website/docs/language/functions/startswith.mdx @@ -24,4 +24,4 @@ false ## Related Functions -- [`endswith`](/opentf/language/functions/endswith) takes two values: a string to check and a suffix string. The function returns true if the first string ends with that exact suffix. +- [`endswith`](/docs/language/functions/endswith) takes two values: a string to check and a suffix string. The function returns true if the first string ends with that exact suffix. diff --git a/website/docs/language/functions/strrev.mdx b/website/docs/language/functions/strrev.mdx index a954c6e9d1..958a2a7d4e 100644 --- a/website/docs/language/functions/strrev.mdx +++ b/website/docs/language/functions/strrev.mdx @@ -23,4 +23,4 @@ olleh ## Related Functions -* [`reverse`](/opentf/language/functions/reverse) reverses a sequence. +* [`reverse`](/docs/language/functions/reverse) reverses a sequence. diff --git a/website/docs/language/functions/templatefile.mdx b/website/docs/language/functions/templatefile.mdx index 540f14d57f..2e96d98f39 100644 --- a/website/docs/language/functions/templatefile.mdx +++ b/website/docs/language/functions/templatefile.mdx @@ -15,7 +15,7 @@ templatefile(path, vars) ``` The template syntax is the same as for -[string templates](/opentf/language/expressions/strings#string-templates) +[string templates](/docs/language/expressions/strings#string-templates) in the main OpenTF language, including interpolation sequences delimited with `${` ... `}`. This function just allows longer template sequences to be factored out into a separate file for readability. @@ -99,9 +99,9 @@ YAML that will be interpreted correctly when using lots of individual interpolation sequences and directives. Instead, you can write a template that consists only of a single interpolated -call to either [`jsonencode`](/opentf/language/functions/jsonencode) or -[`yamlencode`](/opentf/language/functions/yamlencode), specifying the value to encode using -[normal OpenTF expression syntax](/opentf/language/expressions) +call to either [`jsonencode`](/docs/language/functions/jsonencode) or +[`yamlencode`](/docs/language/functions/yamlencode), specifying the value to encode using +[normal OpenTF expression syntax](/docs/language/expressions) as in the following examples: ``` @@ -121,9 +121,9 @@ this will produce a valid JSON or YAML representation of the given data structure, without the need to manually handle escaping or delimiters. In the latest examples above, the repetition based on elements of `ip_addrs` is achieved by using a -[`for` expression](/opentf/language/expressions/for) +[`for` expression](/docs/language/expressions/for) rather than by using -[template directives](/opentf/language/expressions/strings#directives). +[template directives](/docs/language/expressions/strings#directives). ```json {"backends":["10.0.0.1:8080","10.0.0.2:8080"]} @@ -142,9 +142,9 @@ locals { ``` For more information, see the main documentation for -[`jsonencode`](/opentf/language/functions/jsonencode) and [`yamlencode`](/opentf/language/functions/yamlencode). +[`jsonencode`](/docs/language/functions/jsonencode) and [`yamlencode`](/docs/language/functions/yamlencode). ## Related Functions -* [`file`](/opentf/language/functions/file) reads a file from disk and returns its literal contents +* [`file`](/docs/language/functions/file) reads a file from disk and returns its literal contents without any template interpretation. diff --git a/website/docs/language/functions/textdecodebase64.mdx b/website/docs/language/functions/textdecodebase64.mdx index 31b54d8206..8348f2217c 100644 --- a/website/docs/language/functions/textdecodebase64.mdx +++ b/website/docs/language/functions/textdecodebase64.mdx @@ -23,7 +23,7 @@ OpenTF supports only a subset of the registered encodings, and the encoding support may vary between OpenTF versions. OpenTF accepts the encoding name `UTF-8`, which will produce the same result -as [`base64decode`](/opentf/language/functions/base64decode). +as [`base64decode`](/docs/language/functions/base64decode). ## Examples @@ -34,7 +34,7 @@ Hello World ## Related Functions -* [`textencodebase64`](/opentf/language/functions/textencodebase64) performs the opposite operation, +* [`textencodebase64`](/docs/language/functions/textencodebase64) performs the opposite operation, applying target encoding and then Base64 to a string. -* [`base64decode`](/opentf/language/functions/base64decode) is effectively a shorthand for +* [`base64decode`](/docs/language/functions/base64decode) is effectively a shorthand for `textdecodebase64` where the character encoding is fixed as `UTF-8`. diff --git a/website/docs/language/functions/textencodebase64.mdx b/website/docs/language/functions/textencodebase64.mdx index 4b624fd91a..8e4b057bcd 100644 --- a/website/docs/language/functions/textencodebase64.mdx +++ b/website/docs/language/functions/textencodebase64.mdx @@ -29,7 +29,7 @@ support may vary between OpenTF versions. In particular OpenTF supports therefore sometimes expected by Windows-originated software such as PowerShell. OpenTF also accepts the encoding name `UTF-8`, which will produce the same -result as [`base64encode`](/opentf/language/functions/base64encode). +result as [`base64encode`](/docs/language/functions/base64encode). ## Examples @@ -40,10 +40,10 @@ SABlAGwAbABvACAAVwBvAHIAbABkAA== ## Related Functions -* [`textdecodebase64`](/opentf/language/functions/textdecodebase64) performs the opposite operation, +* [`textdecodebase64`](/docs/language/functions/textdecodebase64) performs the opposite operation, decoding Base64 data and interpreting it as a particular character encoding. -* [`base64encode`](/opentf/language/functions/base64encode) applies Base64 encoding of the UTF-8 +* [`base64encode`](/docs/language/functions/base64encode) applies Base64 encoding of the UTF-8 encoding of a string. -* [`filebase64`](/opentf/language/functions/filebase64) reads a file from the local filesystem +* [`filebase64`](/docs/language/functions/filebase64) reads a file from the local filesystem and returns its raw bytes with Base64 encoding, without creating an intermediate Unicode string. diff --git a/website/docs/language/functions/timeadd.mdx b/website/docs/language/functions/timeadd.mdx index 90558c7412..c0a608c031 100644 --- a/website/docs/language/functions/timeadd.mdx +++ b/website/docs/language/functions/timeadd.mdx @@ -35,4 +35,4 @@ of adding the given direction to the given timestamp. # Related Functions -* [`timecmp`](/opentf/language/functions/timecmp) determines an ordering for two timestamps. +* [`timecmp`](/docs/language/functions/timecmp) determines an ordering for two timestamps. diff --git a/website/docs/language/functions/timecmp.mdx b/website/docs/language/functions/timecmp.mdx index 9326da3eb5..8dc0bf9009 100644 --- a/website/docs/language/functions/timecmp.mdx +++ b/website/docs/language/functions/timecmp.mdx @@ -44,7 +44,7 @@ both be strings conforming to this syntax. ``` `timecmp` can be particularly useful in defining -[custom condition checks](/opentf/language/expressions/custom-conditions) that +[custom condition checks](/docs/language/expressions/custom-conditions) that involve a specified timestamp being within a particular range. For example, the following resource postcondition would raise an error if a TLS certificate (or other expiring object) expires sooner than 30 days from the time of @@ -61,6 +61,6 @@ the "apply" step: ## Related Functions -* [`timestamp`](/opentf/language/functions/timestamp) returns the current timestamp when it is evaluated +* [`timestamp`](/docs/language/functions/timestamp) returns the current timestamp when it is evaluated during the apply step. -* [`timeadd`](/opentf/language/functions/timeadd) can perform arithmetic on timestamps by adding or removing a specified duration. +* [`timeadd`](/docs/language/functions/timeadd) can perform arithmetic on timestamps by adding or removing a specified duration. diff --git a/website/docs/language/functions/timestamp.mdx b/website/docs/language/functions/timestamp.mdx index 2f12a2aea1..fcf009ef91 100644 --- a/website/docs/language/functions/timestamp.mdx +++ b/website/docs/language/functions/timestamp.mdx @@ -18,7 +18,7 @@ The result of this function will change every second, so using this function directly with resource attributes will cause a diff to be detected on every OpenTF run. We do not recommend using this function in resource attributes, but in rare cases it can be used in conjunction with -[the `ignore_changes` lifecycle meta-argument](/opentf/language/meta-arguments/lifecycle#ignore_changes) +[the `ignore_changes` lifecycle meta-argument](/docs/language/meta-arguments/lifecycle#ignore_changes) to take the timestamp only on initial creation of the resource. For more stable time handling, see the [Time Provider](https://registry.terraform.io/providers/hashicorp/time). @@ -35,7 +35,7 @@ taken only once the plan is being applied. ## Related Functions -* [`formatdate`](/opentf/language/functions/formatdate) can convert the resulting timestamp to +* [`formatdate`](/docs/language/functions/formatdate) can convert the resulting timestamp to other date and time formats. -* [`plantimestamp`](/opentf/language/functions/plantimestamp) will return a consistent timestamp +* [`plantimestamp`](/docs/language/functions/plantimestamp) will return a consistent timestamp representing the date and time during the plan. diff --git a/website/docs/language/functions/title.mdx b/website/docs/language/functions/title.mdx index 3b268b244a..41f1d5a607 100644 --- a/website/docs/language/functions/title.mdx +++ b/website/docs/language/functions/title.mdx @@ -20,5 +20,5 @@ This function uses Unicode's definition of letters and of upper- and lowercase. ## Related Functions -* [`upper`](/opentf/language/functions/upper) converts _all_ letters in a string to uppercase. -* [`lower`](/opentf/language/functions/lower) converts all letters in a string to lowercase. +* [`upper`](/docs/language/functions/upper) converts _all_ letters in a string to uppercase. +* [`lower`](/docs/language/functions/lower) converts all letters in a string to lowercase. diff --git a/website/docs/language/functions/trim.mdx b/website/docs/language/functions/trim.mdx index 899232fb0b..7e77fc5bb9 100644 --- a/website/docs/language/functions/trim.mdx +++ b/website/docs/language/functions/trim.mdx @@ -34,7 +34,7 @@ and end of the string specified in the first argument. ## Related Functions -* [`trimprefix`](/opentf/language/functions/trimprefix) removes a word from the start of a string. -* [`trimsuffix`](/opentf/language/functions/trimsuffix) removes a word from the end of a string. -* [`trimspace`](/opentf/language/functions/trimspace) removes all types of whitespace from +* [`trimprefix`](/docs/language/functions/trimprefix) removes a word from the start of a string. +* [`trimsuffix`](/docs/language/functions/trimsuffix) removes a word from the end of a string. +* [`trimspace`](/docs/language/functions/trimspace) removes all types of whitespace from both the start and the end of a string. diff --git a/website/docs/language/functions/trimprefix.mdx b/website/docs/language/functions/trimprefix.mdx index adab04b5fb..7a87bbf7ea 100644 --- a/website/docs/language/functions/trimprefix.mdx +++ b/website/docs/language/functions/trimprefix.mdx @@ -23,7 +23,7 @@ helloworld ## Related Functions -* [`trim`](/opentf/language/functions/trim) removes characters at the start and end of a string. -* [`trimsuffix`](/opentf/language/functions/trimsuffix) removes a word from the end of a string. -* [`trimspace`](/opentf/language/functions/trimspace) removes all types of whitespace from +* [`trim`](/docs/language/functions/trim) removes characters at the start and end of a string. +* [`trimsuffix`](/docs/language/functions/trimsuffix) removes a word from the end of a string. +* [`trimspace`](/docs/language/functions/trimspace) removes all types of whitespace from both the start and the end of a string. diff --git a/website/docs/language/functions/trimspace.mdx b/website/docs/language/functions/trimspace.mdx index e417c0ab3e..270fad791c 100644 --- a/website/docs/language/functions/trimspace.mdx +++ b/website/docs/language/functions/trimspace.mdx @@ -23,5 +23,5 @@ hello ## Related Functions -* [`chomp`](/opentf/language/functions/chomp) removes just line ending characters from the _end_ of +* [`chomp`](/docs/language/functions/chomp) removes just line ending characters from the _end_ of a string. diff --git a/website/docs/language/functions/trimsuffix.mdx b/website/docs/language/functions/trimsuffix.mdx index 85c463e0bd..c028d669fb 100644 --- a/website/docs/language/functions/trimsuffix.mdx +++ b/website/docs/language/functions/trimsuffix.mdx @@ -18,7 +18,7 @@ hello ## Related Functions -* [`trim`](/opentf/language/functions/trim) removes characters at the start and end of a string. -* [`trimprefix`](/opentf/language/functions/trimprefix) removes a word from the start of a string. -* [`trimspace`](/opentf/language/functions/trimspace) removes all types of whitespace from +* [`trim`](/docs/language/functions/trim) removes characters at the start and end of a string. +* [`trimprefix`](/docs/language/functions/trimprefix) removes a word from the start of a string. +* [`trimspace`](/docs/language/functions/trimspace) removes all types of whitespace from both the start and the end of a string. diff --git a/website/docs/language/functions/try.mdx b/website/docs/language/functions/try.mdx index 02d2d76c4c..32e1fc09f2 100644 --- a/website/docs/language/functions/try.mdx +++ b/website/docs/language/functions/try.mdx @@ -107,5 +107,5 @@ A local value with the name "nonexist" has not been declared. ## Related Functions -* [`can`](/opentf/language/functions/can), which tries evaluating an expression and returns a +* [`can`](/docs/language/functions/can), which tries evaluating an expression and returns a boolean value indicating whether it succeeded. diff --git a/website/docs/language/functions/upper.mdx b/website/docs/language/functions/upper.mdx index 1231d2da63..1840c7d75a 100644 --- a/website/docs/language/functions/upper.mdx +++ b/website/docs/language/functions/upper.mdx @@ -22,5 +22,5 @@ This function uses Unicode's definition of letters and of upper- and lowercase. ## Related Functions -* [`lower`](/opentf/language/functions/lower) converts letters in a string to _lowercase_. -* [`title`](/opentf/language/functions/title) converts the first letter of each word in a string to uppercase. +* [`lower`](/docs/language/functions/lower) converts letters in a string to _lowercase_. +* [`title`](/docs/language/functions/title) converts the first letter of each word in a string to uppercase. diff --git a/website/docs/language/functions/uuid.mdx b/website/docs/language/functions/uuid.mdx index f3158898d2..56198ea515 100644 --- a/website/docs/language/functions/uuid.mdx +++ b/website/docs/language/functions/uuid.mdx @@ -16,11 +16,11 @@ This function produces a new value each time it is called, and so using it directly in resource arguments will result in spurious diffs. We do not recommend using the `uuid` function in resource configurations, but it can be used with care in conjunction with -[the `ignore_changes` lifecycle meta-argument](/opentf/language/meta-arguments/lifecycle#ignore_changes). +[the `ignore_changes` lifecycle meta-argument](/docs/language/meta-arguments/lifecycle#ignore_changes). In most cases we recommend using [the `random` provider](https://registry.terraform.io/providers/hashicorp/random/latest/docs) instead, since it allows the one-time generation of random values that are -then retained in the OpenTF [state](/opentf/language/state) for use by +then retained in the OpenTF [state](/docs/language/state) for use by future operations. In particular, [`random_id`](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/id) can generate results with equivalent randomness to the `uuid` function. @@ -34,4 +34,4 @@ b5ee72a3-54dd-c4b8-551c-4bdc0204cedb ## Related Functions -* [`uuidv5`](/opentf/language/functions/uuidv5), which generates name-based UUIDs. +* [`uuidv5`](/docs/language/functions/uuidv5), which generates name-based UUIDs. diff --git a/website/docs/language/functions/uuidv5.mdx b/website/docs/language/functions/uuidv5.mdx index 572187cb85..cc78a566ef 100644 --- a/website/docs/language/functions/uuidv5.mdx +++ b/website/docs/language/functions/uuidv5.mdx @@ -16,7 +16,7 @@ uuidv5(namespace, name) ``` Unlike the pseudo-random UUIDs generated by -[`uuid`](/opentf/language/functions/uuid), name-based UUIDs derive from namespace and an name, +[`uuid`](/docs/language/functions/uuid), name-based UUIDs derive from namespace and an name, producing the same UUID value every time if the namespace and name are unchanged. @@ -77,4 +77,4 @@ defined it. ## Related Functions -* [`uuid`](/opentf/language/functions/uuid), which generates pseudorandom UUIDs. +* [`uuid`](/docs/language/functions/uuid), which generates pseudorandom UUIDs. diff --git a/website/docs/language/functions/values.mdx b/website/docs/language/functions/values.mdx index 26d04e58df..cc6e186e2b 100644 --- a/website/docs/language/functions/values.mdx +++ b/website/docs/language/functions/values.mdx @@ -10,7 +10,7 @@ in that map. The values are returned in lexicographical order by their corresponding _keys_, so the values will be returned in the same order as their keys would be -returned from [`keys`](/opentf/language/functions/keys). +returned from [`keys`](/docs/language/functions/keys). ## Examples @@ -25,4 +25,4 @@ returned from [`keys`](/opentf/language/functions/keys). ## Related Functions -* [`keys`](/opentf/language/functions/keys) returns a list of the _keys_ from a map. +* [`keys`](/docs/language/functions/keys) returns a list of the _keys_ from a map. diff --git a/website/docs/language/functions/yamldecode.mdx b/website/docs/language/functions/yamldecode.mdx index db76d508ee..8e9714b9b4 100644 --- a/website/docs/language/functions/yamldecode.mdx +++ b/website/docs/language/functions/yamldecode.mdx @@ -14,7 +14,7 @@ This function supports a subset of [YAML 1.2](https://yaml.org/spec/1.2/spec.htm as described below. This function maps YAML values to -[OpenTF language values](/opentf/language/expressions/types) +[OpenTF language values](/docs/language/expressions/types) in the following way: | YAML type | OpenTF type | @@ -93,7 +93,7 @@ Call to function "yamldecode" failed: unsupported tag "!not-supported". ## Related Functions -- [`jsondecode`](/opentf/language/functions/jsondecode) is a similar operation using JSON instead +- [`jsondecode`](/docs/language/functions/jsondecode) is a similar operation using JSON instead of YAML. -- [`yamlencode`](/opentf/language/functions/yamlencode) performs the opposite operation, _encoding_ +- [`yamlencode`](/docs/language/functions/yamlencode) performs the opposite operation, _encoding_ a value as YAML. diff --git a/website/docs/language/functions/yamlencode.mdx b/website/docs/language/functions/yamlencode.mdx index 23c104b70b..4b534214c1 100644 --- a/website/docs/language/functions/yamlencode.mdx +++ b/website/docs/language/functions/yamlencode.mdx @@ -9,7 +9,7 @@ description: The yamlencode function encodes a given value as a YAML string. [YAML 1.2](https://yaml.org/spec/1.2/spec.html) block syntax. This function maps -[OpenTF language values](/opentf/language/expressions/types) +[OpenTF language values](/docs/language/expressions/types) to YAML tags in the following way: | OpenTF type | YAML type | @@ -33,7 +33,7 @@ identical value, but the OpenTF language automatic type conversion rules mean that this is rarely a problem in practice. YAML is a superset of JSON, and so where possible we recommend generating -JSON using [`jsonencode`](/opentf/language/functions/jsonencode) instead, even if +JSON using [`jsonencode`](/docs/language/functions/jsonencode) instead, even if a remote system supports YAML. JSON syntax is equivalent to flow-style YAML and OpenTF can present detailed structural change information for JSON values in plans, whereas OpenTF will treat block-style YAML just as a normal @@ -66,12 +66,12 @@ humans. `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`](/opentf/language/functions/jsonencode) instead: YAML flow-style is a superset +[`jsonencode`](/docs/language/functions/jsonencode) instead: YAML flow-style is a superset of JSON syntax. ## Related Functions -- [`jsonencode`](/opentf/language/functions/jsonencode) is a similar operation using JSON instead +- [`jsonencode`](/docs/language/functions/jsonencode) is a similar operation using JSON instead of YAML. -- [`yamldecode`](/opentf/language/functions/yamldecode) performs the opposite operation, _decoding_ +- [`yamldecode`](/docs/language/functions/yamldecode) performs the opposite operation, _decoding_ a YAML string to obtain its represented value. diff --git a/website/docs/language/import/generating-configuration.mdx b/website/docs/language/import/generating-configuration.mdx index 680cd2ac8b..f52825c869 100644 --- a/website/docs/language/import/generating-configuration.mdx +++ b/website/docs/language/import/generating-configuration.mdx @@ -8,7 +8,7 @@ description: >- ~> **Experimental:** Configuration generation is available in OpenTF v1.6 as an experimental feature. Later minor versions may contain changes to the formatting of generated configuration and behavior of the `opentf plan` command using the `-generate-config-out` flag. -OpenTF can generate code for the resources you define in [`import` blocks](/opentf/language/import) that do not already exist in your configuration. OpenTF produces HCL to act as a template that contains OpenTF's best guess at the appropriate value for each resource argument. +OpenTF can generate code for the resources you define in [`import` blocks](/docs/language/import) that do not already exist in your configuration. OpenTF produces HCL to act as a template that contains OpenTF's best guess at the appropriate value for each resource argument. Starting with OpenTF's generated HCL, we recommend iterating to find your ideal configuration by removing some attributes, adjusting the value of others, and rearranging `resource` blocks into files and modules as appropriate. @@ -22,7 +22,7 @@ If any resources targeted by an `import` block do not exist in your configuratio ## Workflow -The workflow for generating configuration is similar to the [`import` block workflow](/opentf/language/import#plan-and-apply-an-import), with the extra step of generating configuration during the planning stage. You can then review and modify the generated configuration before applying. +The workflow for generating configuration is similar to the [`import` block workflow](/docs/language/import#plan-and-apply-an-import), with the extra step of generating configuration during the planning stage. You can then review and modify the generated configuration before applying. ### 1. Add the `import` block @@ -37,7 +37,7 @@ import { The import block's `to` argument points to the address a `resource` will have in your state file. If a resource address in your state matches an `import` block's `to` argument, OpenTF attempts to import into that resource. In future planning, OpenTF knows it doesn't need to generate configuration for resources that already exist in your state. -The import block's `id` argument uses that resource's [import ID](/opentf/language/import#import-id). +The import block's `id` argument uses that resource's [import ID](/docs/language/import#import-id). If your configuration does not contain other resources for your selected provider, you must add a `provider` block to inform OpenTF which provider it should use to generate configuration. Otherwise, OpenTF displays an error if it can not determine which provider to use. If you add a new `provider` block to your configuration, you must run `opentf init` again. diff --git a/website/docs/language/import/index.mdx b/website/docs/language/import/index.mdx index bfe6db27dc..46ef8c9d00 100644 --- a/website/docs/language/import/index.mdx +++ b/website/docs/language/import/index.mdx @@ -35,7 +35,7 @@ The above `import` block defines an import of the AWS instance with the ID "i-ab The `import` block has the following arguments: - `to` - The instance address this resource will have in your state file. - `id` - A string with the [import ID](#import-id) of the resource. -- `provider` (optional) - An optional custom resource provider, see [The Resource provider Meta-Argument](/opentf/language/meta-arguments/resource-provider) for details. +- `provider` (optional) - An optional custom resource provider, see [The Resource provider Meta-Argument](/docs/language/meta-arguments/resource-provider) for details. If you do not set the `provider` argument, OpenTF attempts to import from the default provider. @@ -51,21 +51,21 @@ OpenTF processes the `import` block during the plan stage. Once a plan is approv To import a resource using `import` blocks, you must: 1. Define an `import` block for the resource(s). -1. Add a corresponding `resource` block to your configuration , or [generate configuration](/opentf/language/import/generating-configuration) for that resource. +1. Add a corresponding `resource` block to your configuration , or [generate configuration](/docs/language/import/generating-configuration) for that resource. 1. Run `opentf plan` to review how OpenTF will import the resource(s). 1. Apply the configuration to import the resources and update your OpenTF state. The `import` block is [_idempotent_](https://en.wikipedia.org/wiki/Idempotence), meaning that applying an import action and running another plan will not generate another import action as long as that resource remains in your state. -OpenTF only needs to import a given resource once. Attempting to import a resource into the same address again is a harmless no-op. You can remove `import` blocks after completing the import or safely leave them in your configuration as a record of the resource's origin for future module maintainers. For more information on maintaining configurations over time, see [Refactoring](/opentf/language/modules/develop/refactoring). +OpenTF only needs to import a given resource once. Attempting to import a resource into the same address again is a harmless no-op. You can remove `import` blocks after completing the import or safely leave them in your configuration as a record of the resource's origin for future module maintainers. For more information on maintaining configurations over time, see [Refactoring](/docs/language/modules/develop/refactoring). ## Resource configuration -Before importing, you must add configuration for every resource you want OpenTF to import. Otherwise, OpenTF throws an error during planning, insisting you add resource configuration before it can successfully import. You can create resource configuration manually or [generate it using OpenTF](/opentf/language/import/generating-configuration). +Before importing, you must add configuration for every resource you want OpenTF to import. Otherwise, OpenTF throws an error during planning, insisting you add resource configuration before it can successfully import. You can create resource configuration manually or [generate it using OpenTF](/docs/language/import/generating-configuration). -We recommend writing a `resource` block if you know what most of the [resource's arguments](/opentf/language/resources/syntax#resource-arguments) will be. For example, your configuration may already contain a similar resource whose configuration you can copy and modify. +We recommend writing a `resource` block if you know what most of the [resource's arguments](/docs/language/resources/syntax#resource-arguments) will be. For example, your configuration may already contain a similar resource whose configuration you can copy and modify. -We recommend [generating configuration](/opentf/language/import/generating-configuration) when importing multiple resources or a single complex resource that you do not already have the configuration for. +We recommend [generating configuration](/docs/language/import/generating-configuration) when importing multiple resources or a single complex resource that you do not already have the configuration for. ### Add a `resource` block @@ -85,7 +85,7 @@ resource "aws_instance" "example" { ### Generate configuration OpenTF can generate HCL for resources that do not already exist in configuration. -For more details, see [Generating Configuration](/opentf/language/import/generating-configuration). +For more details, see [Generating Configuration](/docs/language/import/generating-configuration). ## Examples @@ -98,7 +98,7 @@ import { } ``` -The below example shows how to import a resource that includes [`count`](/opentf/language/meta-arguments/count). +The below example shows how to import a resource that includes [`count`](/docs/language/meta-arguments/count). ```hcl import { @@ -108,7 +108,7 @@ import { ``` -The below example shows how to import a resource that includes [`for_each`](/opentf/language/meta-arguments/for_each). +The below example shows how to import a resource that includes [`for_each`](/docs/language/meta-arguments/for_each). ```hcl import { to = aws_instance.example["foo"] diff --git a/website/docs/language/index.mdx b/website/docs/language/index.mdx index 50dee15793..685e75592f 100644 --- a/website/docs/language/index.mdx +++ b/website/docs/language/index.mdx @@ -7,7 +7,7 @@ description: >- # OpenTF Language Documentation This is the documentation for OpenTF's configuration language. It is relevant -to users of [OpenTF CLI](/opentf/cli), and TACOS (TF Automation and Collaboration Software). +to users of [OpenTF CLI](/docs/cli), and TACOS (TF Automation and Collaboration Software). OpenTF's language is its primary user interface. Configuration files you write in OpenTF language tell OpenTF what plugins to install, what infrastructure to create, and what data to fetch. OpenTF language also lets you define dependencies @@ -17,7 +17,7 @@ configuration block. ## About the OpenTF Language The main purpose of the OpenTF language is declaring -[resources](/opentf/language/resources), which represent infrastructure objects. All other +[resources](/docs/language/resources), which represent infrastructure objects. All other language features exist only to make the definition of resources more flexible and convenient. diff --git a/website/docs/language/meta-arguments/count.mdx b/website/docs/language/meta-arguments/count.mdx index a01ebd7860..504b7f9317 100644 --- a/website/docs/language/meta-arguments/count.mdx +++ b/website/docs/language/meta-arguments/count.mdx @@ -9,14 +9,14 @@ description: >- -> **Note:** A given resource or module block cannot use both `count` and `for_each`. -By default, a [resource block](/opentf/language/resources/syntax) configures one real +By default, a [resource block](/docs/language/resources/syntax) configures one real infrastructure object. (Similarly, a -[module block](/opentf/language/modules/syntax) includes a +[module block](/docs/language/modules/syntax) includes a child module's contents into the configuration one time.) However, sometimes you want to manage several similar objects (like a fixed pool of compute instances) without writing a separate block for each one. OpenTF has two ways to do this: -`count` and [`for_each`](/opentf/language/meta-arguments/for_each). +`count` and [`for_each`](/docs/language/meta-arguments/for_each). If a resource or module block includes a `count` argument whose value is a whole number, OpenTF will create that many instances. @@ -55,7 +55,7 @@ This object has one attribute: ## Using Expressions in `count` -The `count` meta-argument accepts numeric [expressions](/opentf/language/expressions). +The `count` meta-argument accepts numeric [expressions](/docs/language/expressions). However, unlike most arguments, the `count` value must be known _before_ OpenTF 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.mdx index 8d1eebb761..1e960e59a5 100644 --- a/website/docs/language/meta-arguments/depends_on.mdx +++ b/website/docs/language/meta-arguments/depends_on.mdx @@ -11,11 +11,11 @@ Use the `depends_on` meta-argument to handle hidden resource or module dependenc ## Processing and Planning Consequences -The `depends_on` meta-argument instructs OpenTF to complete all actions on the dependency object (including Read actions) before performing actions on the object declaring the dependency. When the dependency object is an entire module, `depends_on` affects the order in which OpenTF processes all of the resources and data sources associated with that module. Refer to [Resource Dependencies](/opentf/language/resources/behavior#resource-dependencies) and [Data Resource Dependencies](/opentf/language/data-sources#data-resource-dependencies) for more details. +The `depends_on` meta-argument instructs OpenTF to complete all actions on the dependency object (including Read actions) before performing actions on the object declaring the dependency. When the dependency object is an entire module, `depends_on` affects the order in which OpenTF processes all of the resources and data sources associated with that module. Refer to [Resource Dependencies](/docs/language/resources/behavior#resource-dependencies) and [Data Resource Dependencies](/docs/language/data-sources#data-resource-dependencies) for more details. You should use `depends_on` as a last resort because it can cause OpenTF to create more conservative plans that replace more resources than necessary. For example, OpenTF may treat more values as unknown “(known after apply)” because it is uncertain what changes will occur on the upstream object. This is especially likely when you use `depends_on` for modules. -Instead of `depends_on`, we recommend using [expression references](/opentf/language/expressions/references) to imply dependencies when possible. Expression references let OpenTF understand which value the reference derives from and avoid planning changes if that particular value hasn’t changed, even if other parts of the upstream object have planned changes. +Instead of `depends_on`, we recommend using [expression references](/docs/language/expressions/references) to imply dependencies when possible. Expression references let OpenTF understand which value the reference derives from and avoid planning changes if that particular value hasn’t changed, even if other parts of the upstream object have planned changes. ## Usage diff --git a/website/docs/language/meta-arguments/for_each.mdx b/website/docs/language/meta-arguments/for_each.mdx index d1f4d77b0e..588d7ed0f1 100644 --- a/website/docs/language/meta-arguments/for_each.mdx +++ b/website/docs/language/meta-arguments/for_each.mdx @@ -7,14 +7,14 @@ description: >- # The `for_each` Meta-Argument -By default, a [resource block](/opentf/language/resources/syntax) configures one real +By default, a [resource block](/docs/language/resources/syntax) configures one real infrastructure object (and similarly, a -[module block](/opentf/language/modules/syntax) includes a +[module block](/docs/language/modules/syntax) includes a child module's contents into the configuration one time). However, sometimes you want to manage several similar objects (like a fixed pool of compute instances) without writing a separate block for each one. OpenTF has two ways to do this: -[`count`](/opentf/language/meta-arguments/count) and `for_each`. +[`count`](/docs/language/meta-arguments/count) and `for_each`. If a resource or module block includes a `for_each` argument whose value is a map or a set of strings, OpenTF creates one instance for each member of @@ -103,16 +103,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](/opentf/language/values/variables#suppressing-values-in-cli-output), -[sensitive outputs](/opentf/language/values/outputs#sensitive-suppressing-values-in-cli-output), -or [sensitive resource attributes](/opentf/language/expressions/references#sensitive-resource-attributes), +Sensitive values, such as [sensitive input variables](/docs/language/values/variables#suppressing-values-in-cli-output), +[sensitive outputs](/docs/language/values/outputs#sensitive-suppressing-values-in-cli-output), +or [sensitive resource attributes](/docs/language/expressions/references#sensitive-resource-attributes), cannot be used as arguments to `for_each`. The value used in `for_each` is used to identify the resource instance and will always be disclosed in UI output, which is why sensitive values are not allowed. Attempts to use sensitive values as `for_each` arguments will result in an error. If you transform a value containing sensitive data into an argument to be used in `for_each`, be aware that -[most functions in OpenTF will return a sensitive result if given an argument with any sensitive content](/opentf/language/expressions/function-calls#using-sensitive-data-as-function-arguments). +[most functions in OpenTF will return a sensitive result if given an argument with any sensitive content](/docs/language/expressions/function-calls#using-sensitive-data-as-function-arguments). In many cases, you can achieve similar results to a function used for this purpose by using a `for` expression. For example, if you would like to call `keys(local.map)`, where `local.map` is an object with sensitive values (but non-sensitive keys), you can create a @@ -120,7 +120,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](/opentf/language/expressions). +The `for_each` meta-argument accepts map or set [expressions](/docs/language/expressions). However, unlike most arguments, the `for_each` value must be known _before_ OpenTF performs any remote resource actions. This means `for_each` can't refer to any resource attributes that aren't known until after a @@ -129,7 +129,7 @@ an object is created). The `for_each` value must be a map or set with one element per desired resource instance. To use a sequence as the `for_each` value, you must use an expression -that explicitly returns a set value, like the [toset](/opentf/language/functions/toset) +that explicitly returns a set value, like the [toset](/docs/language/functions/toset) function. To prevent unwanted surprises during conversion, the `for_each` argument does not implicitly convert lists or tuples to sets. If you need to declare resource instances based on a nested @@ -138,10 +138,10 @@ can use OpenTF 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](/opentf/language/functions/flatten#flattening-nested-structures-for-for_each). + [using nested `for` expressions with the `flatten` function](/docs/language/functions/flatten#flattening-nested-structures-for-for_each). - Produce an exhaustive list of combinations of elements from two or more collections by - [using the `setproduct` function inside a `for` expression](/opentf/language/functions/setproduct#finding-combinations-for-for_each). + [using the `setproduct` function inside a `for` expression](/docs/language/functions/setproduct#finding-combinations-for-for_each). ### Chaining `for_each` Between Resources @@ -221,7 +221,7 @@ as a whole. ## Using Sets The OpenTF language doesn't have a literal syntax for -[set values](/opentf/language/expressions/type-constraints#collection-types), but you can use the `toset` +[set values](/docs/language/expressions/type-constraints#collection-types), but you can use the `toset` function to explicitly convert a list of strings to a set: ```hcl @@ -250,7 +250,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](/opentf/language/values/variables) that +If you are writing a module with an [input variable](/docs/language/values/variables) that will be used as a set of strings for `for_each`, you can set its type to `set(string)` to avoid the need for an explicit type conversion: diff --git a/website/docs/language/meta-arguments/lifecycle.mdx b/website/docs/language/meta-arguments/lifecycle.mdx index 0fb1c45795..ff5d8dc05b 100644 --- a/website/docs/language/meta-arguments/lifecycle.mdx +++ b/website/docs/language/meta-arguments/lifecycle.mdx @@ -7,7 +7,7 @@ description: >- # The `lifecycle` Meta-Argument -The [Resource Behavior](/opentf/language/resources/behavior) page describes the general lifecycle for resources. Some details of +The [Resource Behavior](/docs/language/resources/behavior) page describes the general lifecycle for resources. Some details of that behavior can be customized using the special nested `lifecycle` block within a resource block body: @@ -147,7 +147,7 @@ The arguments available within a `lifecycle` block are `create_before_destroy`, } ``` - `replace_triggered_by` allows only resource addresses because the decision is based on the planned actions for all of the given resources. Plain values such as local values or input variables do not have planned actions of their own, but you can treat them with a resource-like lifecycle by using them with [the `terraform_data` resource type](/opentf/language/resources/tf-data). + `replace_triggered_by` allows only resource addresses because the decision is based on the planned actions for all of the given resources. Plain values such as local values or input variables do not have planned actions of their own, but you can treat them with a resource-like lifecycle by using them with [the `terraform_data` resource type](/docs/language/resources/tf-data). ## Custom Condition Checks @@ -171,7 +171,7 @@ resource "aws_instance" "example" { Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. -Refer to [Custom Conditions](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. +Refer to [Custom Conditions](/docs/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. ## Literal Values Only diff --git a/website/docs/language/meta-arguments/module-providers.mdx b/website/docs/language/meta-arguments/module-providers.mdx index 85fe9b487c..e1e6fe674d 100644 --- a/website/docs/language/meta-arguments/module-providers.mdx +++ b/website/docs/language/meta-arguments/module-providers.mdx @@ -7,9 +7,9 @@ description: >- # The Module `providers` Meta-Argument -In a [module call](/opentf/language/modules/syntax) block, the +In a [module call](/docs/language/modules/syntax) block, the optional `providers` meta-argument specifies which -[provider configurations](/opentf/language/providers/configuration) from the parent +[provider configurations](/docs/language/providers/configuration) from the parent module will be available inside the child module. ```hcl @@ -38,7 +38,7 @@ module "example" { ## Default Behavior: Inherit Default Providers -If the child module does not declare any [configuration aliases](/opentf/language/modules/develop/providers#provider-aliases-within-modules), +If the child module does not declare any [configuration aliases](/docs/language/modules/develop/providers#provider-aliases-within-modules), the `providers` argument is optional. If you omit it, a child module inherits all of the _default_ provider configurations from its parent module. (Default provider configurations are ones that don't use the `alias` argument.) @@ -123,4 +123,4 @@ names it needs. For more details and guidance about working with providers inside a re-usable child module, see -[Module Development: Providers Within Modules](/opentf/language/modules/develop/providers). +[Module Development: Providers Within Modules](/docs/language/modules/develop/providers). diff --git a/website/docs/language/meta-arguments/resource-provider.mdx b/website/docs/language/meta-arguments/resource-provider.mdx index ed35c5f068..9b5033ad0f 100644 --- a/website/docs/language/meta-arguments/resource-provider.mdx +++ b/website/docs/language/meta-arguments/resource-provider.mdx @@ -11,7 +11,7 @@ The `provider` meta-argument specifies which provider configuration to use for a overriding OpenTF's default behavior of selecting one based on the resource type name. Its value should be an unquoted `.` reference. -As described in [Provider Configuration](/opentf/language/providers/configuration), you can optionally +As described in [Provider Configuration](/docs/language/providers/configuration), you can optionally create multiple configurations for a single provider (usually to manage resources in different regions of multi-region services). Each provider can have one default configuration, and any number of alternate configurations that @@ -53,7 +53,7 @@ ensure that the provider is fully configured before any resource actions are taken. The `provider` meta-argument expects -[a `.` reference](/opentf/language/providers/configuration#referring-to-alternate-provider-configurations), +[a `.` reference](/docs/language/providers/configuration#referring-to-alternate-provider-configurations), which does not need to be quoted. Arbitrary expressions are not permitted for `provider` because it must be resolved while OpenTF 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.mdx index 6c89e06781..5b0f6b96be 100644 --- a/website/docs/language/modules/develop/composition.mdx +++ b/website/docs/language/modules/develop/composition.mdx @@ -193,7 +193,7 @@ Every module has implicit assumptions and guarantees that define what data it ex - **Assumption:** A condition that must be true in order for the configuration of a particular resource to be usable. For example, an `aws_instance` configuration can have the assumption that the given AMI will always be configured for the `x86_64` CPU architecture. - **Guarantee:** A characteristic or behavior of an object that the rest of the configuration should be able to rely on. For example, an `aws_instance` configuration can have the guarantee that an EC2 instance will be running in a network that assigns it a private DNS record. -We recommend using [custom conditions](/opentf/language/expressions/custom-conditions) to help capture and test for assumptions and guarantees. This helps future maintainers understand the configuration design and intent. Custom conditions also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. +We recommend using [custom conditions](/docs/language/expressions/custom-conditions) to help capture and test for assumptions and guarantees. This helps future maintainers understand the configuration design and intent. Custom conditions also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. The following examples creates a precondition that checks whether the EC2 instance has an encrypted root volume. @@ -331,7 +331,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](/opentf/language/data-sources). +[data sources](/docs/language/data-sources). As with conventional modules, we suggest using this technique only when the module raises the level of abstraction in some way, in this case by @@ -367,7 +367,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`](/opentf/language/state/remote-state-data). +[`terraform_remote_state`](/docs/language/state/remote-state-data). The key benefit of this approach is that the source of this information can change over time without updating every configuration that depends on it. diff --git a/website/docs/language/modules/develop/index.mdx b/website/docs/language/modules/develop/index.mdx index 97384198d3..8a5b163960 100644 --- a/website/docs/language/modules/develop/index.mdx +++ b/website/docs/language/modules/develop/index.mdx @@ -12,27 +12,27 @@ You can use modules 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 [`opentf plan`](/opentf/cli/commands/plan) -or [`opentf apply`](/opentf/cli/commands/apply) together form the _root_ -module. That module may [call other modules](/opentf/language/modules/syntax#calling-a-child-module) +The `.tf` files in your working directory when you run [`opentf plan`](/docs/cli/commands/plan) +or [`opentf apply`](/docs/cli/commands/apply) together form the _root_ +module. That module may [call other modules](/docs/language/modules/syntax#calling-a-child-module) and connect them together by passing output values from one to input values of another. -To learn how to _use_ modules, see [the Modules configuration section](/opentf/language/modules). +To learn how to _use_ modules, see [the Modules configuration section](/docs/language/modules). This section is about _creating_ re-usable modules that other configurations can include using `module` blocks. ## Module structure Re-usable modules are defined using all of the same -[configuration language](/opentf/language) concepts we use in root modules. +[configuration language](/docs/language) concepts we use in root modules. Most commonly, modules use: -* [Input variables](/opentf/language/values/variables) to accept values from +* [Input variables](/docs/language/values/variables) to accept values from the calling module. -* [Output values](/opentf/language/values/outputs) to return results to the +* [Output values](/docs/language/values/outputs) to return results to the calling module, which it can then use to populate arguments elsewhere. -* [Resources](/opentf/language/resources) to define one or more +* [Resources](/docs/language/resources) to define one or more infrastructure objects that the module will manage. To define a module, create a new directory for it and place one or more `.tf` @@ -42,7 +42,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](/opentf/language/modules/develop/composition) +keeping the module tree relatively flat and using [module composition](/docs/language/modules/develop/composition) as an alternative to a deeply-nested tree of modules, because this makes the individual modules easier to re-use in different combinations. @@ -70,7 +70,7 @@ calling module instead. ## Refactoring module resources -You can include [refactoring blocks](/opentf/language/modules/develop/refactoring) to record how resource +You can include [refactoring blocks](/docs/language/modules/develop/refactoring) to record how resource names and module structure have changed from previous module versions. OpenTF 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.mdx index f31e6378cd..2d99f2d8c3 100644 --- a/website/docs/language/modules/develop/providers.mdx +++ b/website/docs/language/modules/develop/providers.mdx @@ -42,10 +42,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](/opentf/language/providers/requirements), so that +declare its own [provider requirements](/docs/language/providers/requirements), so that OpenTF 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](/opentf/language/providers/requirements#source-addresses) that serves as +[source address](/docs/language/providers/requirements#source-addresses) that serves as the global (module-agnostic) identifier for a provider. To declare that a module requires particular versions of a specific provider, @@ -68,7 +68,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 OpenTF configuration can potentially have -[several different configurations for the same provider](/opentf/language/providers/configuration#alias-multiple-provider-configurations). +[several different configurations for the same provider](/docs/language/providers/configuration#alias-multiple-provider-configurations). ## Provider Aliases Within Modules @@ -100,7 +100,7 @@ features are needed by other parts of their overall configuration. ## Implicit Provider Inheritance For convenience in simple configurations, a child module automatically inherits -[default provider configurations](/opentf/language/providers/configuration#default-provider-configurations) from its parent. This means that +[default provider configurations](/docs/language/providers/configuration#default-provider-configurations) from its parent. This means that explicit `provider` blocks appear only in the root module, and downstream modules can simply declare resources for that provider and have them automatically associated with the root provider configurations. @@ -130,10 +130,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](/opentf/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). This is especially important for non-HashiCorp providers. In more complex situations there may be -[multiple provider configurations](/opentf/language/providers/configuration#alias-multiple-provider-configurations), +[multiple provider configurations](/docs/language/providers/configuration#alias-multiple-provider-configurations), or a child module may need to use different provider settings than its parent. For such situations, you must pass providers explicitly. @@ -170,7 +170,7 @@ module "example" { ``` The `providers` argument within a `module` block is similar to -[the `provider` argument](/opentf/language/meta-arguments/resource-provider) +[the `provider` argument](/docs/language/meta-arguments/resource-provider) within a resource, but is a map rather than a single string because a module may contain resources from many different providers. diff --git a/website/docs/language/modules/develop/publish.mdx b/website/docs/language/modules/develop/publish.mdx index fd22a7a4e4..e7ddcd9247 100644 --- a/website/docs/language/modules/develop/publish.mdx +++ b/website/docs/language/modules/develop/publish.mdx @@ -6,12 +6,12 @@ description: A module is a container for multiple resources that are used togeth # Publishing Modules If you've built a module that you intend to be reused, we recommend -[publishing the module](/opentf/registry/modules/publish) on the +[publishing the module](/docs/registry/modules/publish) on the [Public Terraform Registry](https://registry.terraform.io). This will version your module, generate documentation, and more. Published modules can be easily consumed by OpenTF, and users can -[constrain module versions](/opentf/language/modules/syntax#version) +[constrain module versions](/docs/language/modules/syntax#version) for safe and predictable updates. The following example shows how a caller might use a module from the Module Registry: @@ -22,7 +22,7 @@ module "consul" { ``` If you do not wish to publish your modules in the public registry, you can -instead use a [private registry](/opentf/registry/private) to get +instead use a [private registry](/docs/registry/private) to get the same benefits. We welcome contributions of 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 OpenTF community. Both types of modules have their place in the registry, accessible to practitioners who can decide which modules best fit their requirements. @@ -31,11 +31,11 @@ We welcome contributions of modules from our community members, partners, and cu Although the registry is the native mechanism for distributing re-usable modules, OpenTF can also install modules from -[various other sources](/opentf/language/modules/sources). The alternative sources +[various other sources](/docs/language/modules/sources). The alternative sources do not support the first-class versioning mechanism, but some sources have their own mechanisms for selecting particular VCS commits, etc. We recommend that modules distributed via other protocols still use the -[standard module structure](/opentf/language/modules/develop/structure) so that they can +[standard module structure](/docs/language/modules/develop/structure) so that they can be used in a similar way as a registry module or be published on the registry at a later time. diff --git a/website/docs/language/modules/develop/refactoring.mdx b/website/docs/language/modules/develop/refactoring.mdx index 8a77da1db1..31b81f22c4 100644 --- a/website/docs/language/modules/develop/refactoring.mdx +++ b/website/docs/language/modules/develop/refactoring.mdx @@ -116,7 +116,7 @@ resource "aws_instance" "a" { Applying this configuration would lead to OpenTF creating an object bound to the address `aws_instance.a`. -Later, you use [`for_each`](/opentf/language/meta-arguments/for_each) with this +Later, you use [`for_each`](/docs/language/meta-arguments/for_each) with this resource to systematically declare multiple instances. To preserve an object that was previously associated with `aws_instance.a` alone, you must add a `moved` block to specify which instance key the object will take in the new @@ -255,7 +255,7 @@ Applying this configuration would cause OpenTF to create objects whose addresses begin with `module.a`. In later module versions, you may need to use -[`count`](/opentf/language/meta-arguments/count) with this resource to systematically +[`count`](/docs/language/meta-arguments/count) with this resource to systematically declare multiple instances. To preserve an object that was previously associated with `aws_instance.a` alone, you can add a `moved` block to specify which instance key that object will take in the new configuration: @@ -392,7 +392,7 @@ 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](/opentf/language/modules/sources#modules-in-package-sub-directories). +[module package](/docs/language/modules/sources#modules-in-package-sub-directories). OpenTF resolves module references in `moved` blocks relative to the module instance they are defined in. For example, if the original module above were diff --git a/website/docs/language/modules/develop/structure.mdx b/website/docs/language/modules/develop/structure.mdx index d5e370a30a..7a4c7e28be 100644 --- a/website/docs/language/modules/develop/structure.mdx +++ b/website/docs/language/modules/develop/structure.mdx @@ -55,8 +55,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](/opentf/language/values/variables) and - [output configuration](/opentf/language/values/outputs) for more details. + [variable configuration](/docs/language/values/variables) and + [output configuration](/docs/language/values/outputs) for more details. * **Nested modules**. Nested modules should exist under the `modules/` subdirectory. Any nested module with a `README.md` is considered usable @@ -76,7 +76,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](/opentf/language/modules/develop/composition) by the caller, rather than + ideally be [composable](/docs/language/modules/develop/composition) by the caller, rather than calling directly to each other and creating a deeply-nested tree of modules. * **Examples**. Examples of using the module should exist under the diff --git a/website/docs/language/modules/index.mdx b/website/docs/language/modules/index.mdx index f82daf0e87..1a094d2a4e 100644 --- a/website/docs/language/modules/index.mdx +++ b/website/docs/language/modules/index.mdx @@ -47,21 +47,21 @@ module registry for sharing modules internally within your organization. ## Using Modules -- [Module Blocks](/opentf/language/modules/syntax) documents the syntax for +- [Module Blocks](/docs/language/modules/syntax) documents the syntax for calling a child module from a parent module, including meta-arguments like `for_each`. -- [Module Sources](/opentf/language/modules/sources) documents what kinds of paths, +- [Module Sources](/docs/language/modules/sources) documents what kinds of paths, addresses, and URIs can be used in the `source` argument of a module block. - The Meta-Arguments section documents special arguments that can be used with every module, including - [`providers`](/opentf/language/meta-arguments/module-providers), - [`depends_on`](/opentf/language/meta-arguments/depends_on), - [`count`](/opentf/language/meta-arguments/count), - and [`for_each`](/opentf/language/meta-arguments/for_each). + [`providers`](/docs/language/meta-arguments/module-providers), + [`depends_on`](/docs/language/meta-arguments/depends_on), + [`count`](/docs/language/meta-arguments/count), + and [`for_each`](/docs/language/meta-arguments/for_each). ## Developing Modules For information about developing reusable modules, see -[Module Development](/opentf/language/modules/develop). +[Module Development](/docs/language/modules/develop). diff --git a/website/docs/language/modules/sources.mdx b/website/docs/language/modules/sources.mdx index 3ec3fed4d3..67f0278dae 100644 --- a/website/docs/language/modules/sources.mdx +++ b/website/docs/language/modules/sources.mdx @@ -8,7 +8,7 @@ description: >- # Module Sources -The `source` argument in [a `module` block](/opentf/language/modules/syntax) +The `source` argument in [a `module` block](/docs/language/modules/syntax) tells OpenTF where to find the source code for the desired child module. OpenTF uses this during the module installation step of `opentf init` @@ -95,10 +95,10 @@ to get started with OpenTF and find modules created by others in the community. You can also use a -[private registry](/opentf/registry/private), either +[private registry](/docs/registry/private), either via TACOS (TF Automation and Collaboration Software), or by running a custom service that implements -[the module registry protocol](/opentf/registry/api-docs). +[the module registry protocol](/docs/registry/api-docs). Modules on the public registry can be referenced using a registry source address of the form `//`, with each @@ -128,13 +128,13 @@ module "consul" { Registry modules support versioning. You can provide a specific version as shown in the above examples, or use flexible -[version constraints](/opentf/language/modules/syntax#version). +[version constraints](/docs/language/modules/syntax#version). You can learn more about the registry at the -[Module Registry documentation](/opentf/registry/modules/use#using-modules). +[Module Registry documentation](/docs/registry/modules/use#using-modules). To access modules from a private registry, you may need to configure an access -token [in the CLI config](/opentf/cli/config/config-file#credentials). Use the +token [in the CLI config](/docs/cli/config/config-file#credentials). Use the same hostname as used in the module source string. For a private registry within TACOS (TF Automation and Collaboration Software), use the same authentication token as you would use with the API or command-line clients. diff --git a/website/docs/language/modules/syntax.mdx b/website/docs/language/modules/syntax.mdx index e24e2b205f..f7a5c8bf87 100644 --- a/website/docs/language/modules/syntax.mdx +++ b/website/docs/language/modules/syntax.mdx @@ -21,13 +21,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](/opentf/language/modules/develop). +about creating re-usable child modules, see [Module Development](/docs/language/modules/develop). ## Calling a Child Module To _call_ a module means to include the contents of that module into the configuration with specific values for its -[input variables](/opentf/language/values/variables). Modules are called +[input variables](/docs/language/values/variables). Modules are called from within other modules using `module` blocks: ```hcl @@ -51,7 +51,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](/opentf/language/values/variables) +- Most other arguments correspond to [input variables](/docs/language/values/variables) defined by the module. (The `servers` argument in the example above is one of these.) @@ -65,7 +65,7 @@ OpenTF. Its value is either the path to a local directory containing the module's configuration files, or a remote module source that OpenTF 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](/opentf/language/modules/sources). +possible values for this argument, see [Module Sources](/docs/language/modules/sources). The same source address can be specified in multiple `module` blocks to create multiple copies of the resources defined within, possibly with different @@ -93,7 +93,7 @@ module "consul" { } ``` -The `version` argument accepts a [version constraint string](/opentf/language/expressions/version-constraints). +The `version` argument accepts a [version constraint string](/docs/language/expressions/version-constraints). OpenTF 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. @@ -114,22 +114,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](/opentf/language/meta-arguments/count) + See [the `count` page](/docs/language/meta-arguments/count) for details. - `for_each` - Creates multiple instances of a module from a single `module` block. See - [the `for_each` page](/opentf/language/meta-arguments/for_each) + [the `for_each` page](/docs/language/meta-arguments/for_each) for details. - `providers` - Passes provider configurations to a child module. See - [the `providers` page](/opentf/language/meta-arguments/module-providers) + [the `providers` page](/docs/language/meta-arguments/module-providers) for details. If not specified, the child module inherits all of the default (un-aliased) provider configurations from the calling module. - `depends_on` - Creates explicit dependencies between the entire module and the listed targets. See - [the `depends_on` page](/opentf/language/meta-arguments/depends_on) + [the `depends_on` page](/docs/language/meta-arguments/depends_on) for details. OpenTF does not use the `lifecycle` argument. However, the `lifecycle` block is reserved for future versions. @@ -138,7 +138,7 @@ OpenTF does not use the `lifecycle` argument. However, the `lifecycle` block is 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](/opentf/language/values/outputs) to selectively +declare [output values](/docs/language/values/outputs) to selectively export certain values to be accessed by the calling module. For example, if the `./app-cluster` module referenced in the example above @@ -154,7 +154,7 @@ resource "aws_elb" "example" { ``` For more information about referring to named values, see -[Expressions](/opentf/language/expressions). +[Expressions](/docs/language/expressions). ## Transferring Resource State Into Modules @@ -164,7 +164,7 @@ result, OpenTF 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](/opentf/language/modules/develop/refactoring) to record the old and new +[refactoring blocks](/docs/language/modules/develop/refactoring) to record the old and new addresses for each resource instance. This directs OpenTF to treat existing objects at the old addresses as if they had originally been created at the corresponding new addresses. @@ -174,7 +174,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 OpenTF, such as if a particular virtual machine is running on degraded underlying hardware. In this case, you can use -[the `-replace=...` planning option](/opentf/cli/commands/plan#replace-address) +[the `-replace=...` planning option](/docs/cli/commands/plan#replace-address) to force OpenTF 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/providers/configuration.mdx b/website/docs/language/providers/configuration.mdx index c81bff5701..945ad0d45e 100644 --- a/website/docs/language/providers/configuration.mdx +++ b/website/docs/language/providers/configuration.mdx @@ -16,7 +16,7 @@ configure settings for providers. Additionally, all OpenTF configurations must declare which providers they require so that OpenTF can install and use them. The -[Provider Requirements](/opentf/language/providers/requirements) +[Provider Requirements](/docs/language/providers/requirements) page documents how to declare providers so OpenTF can install them. ## Provider Configuration @@ -24,8 +24,8 @@ page documents how to declare providers so OpenTF can install them. Provider configurations belong in the root module of an OpenTF configuration. (Child modules receive their provider configurations from the root module; for more information, see -[The Module `providers` Meta-Argument](/opentf/language/meta-arguments/module-providers) -and [Module Development: Providers Within Modules](/opentf/language/modules/develop/providers).) +[The Module `providers` Meta-Argument](/docs/language/meta-arguments/module-providers) +and [Module Development: Providers Within Modules](/docs/language/modules/develop/providers).) A provider configuration is created using a `provider` block: @@ -37,7 +37,7 @@ provider "google" { ``` The name given in the block header (`"google"` in this example) is the -[local name](/opentf/language/providers/requirements#local-names) of the provider to +[local name](/docs/language/providers/requirements#local-names) of the provider to configure. This provider should already be included in a `required_providers` block. @@ -46,7 +46,7 @@ the provider. Most arguments in this section are defined by the provider itself; in this example both `project` and `region` are specific to the `google` provider. -You can use [expressions](/opentf/language/expressions) in the values of these +You can use [expressions](/docs/language/expressions) in the values of these configuration arguments, but can only reference values that are known before the configuration is applied. This means you can safely reference input variables, but not attributes exported by resources (with an exception for resource @@ -68,7 +68,7 @@ and available for all `provider` blocks: - [`alias`, for using the same provider with different configurations for different resources][inpage-alias] - [`version`, which we no longer recommend][inpage-versions] (use - [provider requirements](/opentf/language/providers/requirements) instead) + [provider requirements](/docs/language/providers/requirements) instead) Unlike many other objects in the OpenTF language, a `provider` block may be omitted if its contents would otherwise be empty. OpenTF assumes an @@ -175,7 +175,7 @@ module "aws_vpc" { ``` Modules have some special requirements when passing in providers; see -[The Module `providers` Meta-Argument](/opentf/language/meta-arguments/module-providers) +[The Module `providers` Meta-Argument](/docs/language/meta-arguments/module-providers) for more details. In most cases, only _root modules_ should define provider configurations, with all child modules obtaining their provider configurations from their parents. @@ -190,9 +190,9 @@ 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](/opentf/language/providers/requirements). The version +[`required_providers` block](/docs/language/providers/requirements). The version constraint in a provider configuration is only used if `required_providers` does not include one for that provider. Always declare provider version constraints in -[the `required_providers` block](/opentf/language/providers/requirements). +[the `required_providers` block](/docs/language/providers/requirements). diff --git a/website/docs/language/providers/index.mdx b/website/docs/language/providers/index.mdx index 16ce6d394f..a71a6191f9 100644 --- a/website/docs/language/providers/index.mdx +++ b/website/docs/language/providers/index.mdx @@ -16,8 +16,8 @@ configuration (like endpoint URLs or cloud regions) before they can be used. ## What Providers Do -Each provider adds a set of [resource types](/opentf/language/resources) -and/or [data sources](/opentf/language/data-sources) that OpenTF can +Each provider adds a set of [resource types](/docs/language/resources) +and/or [data sources](/docs/language/data-sources) that OpenTF can manage. Every resource type is implemented by a provider; without providers, OpenTF @@ -49,7 +49,7 @@ 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](/opentf/registry/providers/docs). +see the [provider publishing documentation](/docs/registry/providers/docs). ## How to Use Providers @@ -58,13 +58,13 @@ Providers are released separately from OpenTF itself and have their own version 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](/opentf/language/providers/requirements) +- [Provider Requirements](/docs/language/providers/requirements) documents how to declare providers so OpenTF can install them. -- [Provider Configuration](/opentf/language/providers/configuration) +- [Provider Configuration](/docs/language/providers/configuration) documents how to configure settings for providers. -- [Dependency Lock File](/opentf/language/files/dependency-lock) +- [Dependency Lock File](/docs/language/files/dependency-lock) documents an additional HCL file that can be included with a configuration, which tells OpenTF to always use a specific set of provider versions. @@ -73,18 +73,18 @@ about it in your configuration. See the following pages for details: - TACOS (TF Automation and Collaboration Software) install providers as part of every run. - OpenTF CLI finds and installs providers when - [initializing a working directory](/opentf/cli/init). It can + [initializing a working directory](/docs/cli/init). It can automatically download providers from a provider 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, OpenTF CLI supports an optional plugin cache. You can enable the cache using the `plugin_cache_dir` setting in - [the CLI configuration file](/opentf/cli/config/config-file). + [the CLI configuration file](/docs/cli/config/config-file). To ensure OpenTF always installs the same provider versions for a given configuration, you can use OpenTF CLI to create a -[dependency lock file](/opentf/language/files/dependency-lock) +[dependency lock file](/docs/language/files/dependency-lock) and commit it to version control along with your configuration. If a lock file is present, OpenTF CLI, and TACOS (TF Automation and Collaboration Software) will all obey it when installing providers. @@ -105,4 +105,4 @@ develops and maintains a given provider. ## How to Develop Providers Providers are written in Go, using the Terraform Plugin SDK. For more -information on developing providers, see the [Plugin Development](/opentf/plugin) documentation. +information on developing providers, see the [Plugin Development](/docs/plugin) documentation. diff --git a/website/docs/language/providers/requirements.mdx b/website/docs/language/providers/requirements.mdx index 767e6c22ff..7fad05261f 100644 --- a/website/docs/language/providers/requirements.mdx +++ b/website/docs/language/providers/requirements.mdx @@ -14,7 +14,7 @@ so OpenTF can install them. Additionally, some providers require configuration (like endpoint URLs or cloud regions) before they can be used. The [Provider -Configuration](/opentf/language/providers/configuration) page documents how +Configuration](/docs/language/providers/configuration) page documents how to configure settings for providers. ## Requiring Providers @@ -38,7 +38,7 @@ terraform { ``` The `required_providers` block must be nested inside the top-level -[`terraform` block](/opentf/language/settings) (which can also contain other settings). +[`terraform` block](/docs/language/settings) (which can also contain other settings). Each argument in the `required_providers` block enables one provider. The key determines the provider's [local name](#local-names) (its unique identifier @@ -65,7 +65,7 @@ Local names must be unique per-module. Outside of the `required_providers` block, OpenTF 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](/opentf/language/providers/configuration): +name when [configuring the provider](/docs/language/providers/configuration): ```hcl terraform { @@ -191,7 +191,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](/opentf/language/expressions/version-constraints) given in +declare should have a [version constraint](/docs/language/expressions/version-constraints) given in the `version` argument so OpenTF can select a single version per provider that all modules are compatible with. @@ -201,7 +201,7 @@ a version constraint for every provider your module depends on. To ensure OpenTF always installs the same provider versions for a given configuration, you can use OpenTF CLI to create a -[dependency lock file](/opentf/language/files/dependency-lock) +[dependency lock file](/docs/language/files/dependency-lock) and commit it to version control along with your configuration. If a lock file is present, OpenTF CLI, and TACOS (TF Automation and Collaboration Software) will all obey it when installing providers. @@ -252,7 +252,7 @@ incompatibilities, and let the root module manage the maximum version. Most providers are distributed separately as plugins, but there is one provider that is built into OpenTF itself. This provider enables the -[the `terraform_remote_state` data source](/opentf/language/state/remote-state-data). +[the `terraform_remote_state` data source](/docs/language/state/remote-state-data). Because this provider is built in to OpenTF, you don't need to declare it in the `required_providers` block in order to use its features. However, for @@ -277,11 +277,11 @@ publishing them on a registry. One option for distributing such a provider is to run an in-house _private_ registry, by implementing -[the provider registry protocol](/opentf/internals/provider-registry-protocol). +[the provider registry protocol](/docs/internals/provider-registry-protocol). Running an additional service just to distribute a single provider internally may be undesirable, so OpenTF also supports -[other provider installation methods](/opentf/cli/config/config-file#provider-installation), +[other provider installation methods](/docs/cli/config/config-file#provider-installation), including placing provider plugins directly in specific directories in the local filesystem, via _filesystem mirrors_. @@ -310,7 +310,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](/opentf/cli/config/config-file#implied-local-mirror-directories) +[implied local mirror directories](/docs/cli/config/config-file#implied-local-mirror-directories) and create a directory structure under it like this: ``` diff --git a/website/docs/language/resources/behavior.mdx b/website/docs/language/resources/behavior.mdx index 796da68444..c87fda46b5 100644 --- a/website/docs/language/resources/behavior.mdx +++ b/website/docs/language/resources/behavior.mdx @@ -20,7 +20,7 @@ match the configuration. When OpenTF creates a new infrastructure object represented by a `resource` block, the identifier for that real object is saved in OpenTF's -[state](/opentf/language/state), allowing it to be updated and destroyed +[state](/docs/language/state), allowing it to be updated and destroyed in response to future changes. For resource blocks that already have an associated infrastructure object in the state, OpenTF compares the actual configuration of the object with the arguments given in the @@ -44,7 +44,7 @@ customized on a per-resource basis. ## Accessing Resource Attributes -[Expressions](/opentf/language/expressions) within an OpenTF module can access +[Expressions](/docs/language/expressions) within an OpenTF 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. @@ -54,7 +54,7 @@ read-only attributes with information obtained from the remote API; this often includes things that can't be known until the resource is created, like the resource's unique random ID. -Many providers also include [data sources](/opentf/language/data-sources), +Many providers also include [data sources](/docs/language/data-sources), which are a special type of resource used only for looking up information. For a list of the attributes a resource or data source type provides, consult @@ -62,7 +62,7 @@ its documentation; these are generally included in a second list below its list of configurable arguments. For more information about referencing resource attributes in expressions, see -[Expressions: References to Resource Attributes](/opentf/language/expressions/references#references-to-resource-attributes). +[Expressions: References to Resource Attributes](/docs/language/expressions/references#references-to-resource-attributes). ## Resource Dependencies @@ -75,7 +75,7 @@ resource's configuration just requires information generated by another resource. Most resource dependencies are handled automatically. OpenTF analyses any -[expressions](/opentf/language/expressions) within a `resource` block to find references +[expressions](/docs/language/expressions) within a `resource` block to find references to other objects, and treats those references as implicit ordering requirements when creating, updating, or destroying resources. Since most resources with behavioral dependencies on other resources also refer to those resources' data, @@ -86,10 +86,10 @@ example, if OpenTF 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](/opentf/language/meta-arguments/depends_on) +[the `depends_on` meta-argument](/docs/language/meta-arguments/depends_on) can explicitly specify a dependency. -You can also use the [`replace_triggered_by` meta-argument](/opentf/language/meta-arguments/lifecycle#replace_triggered_by) to add dependencies between otherwise independent resources. It forces OpenTF to replace the parent resource when there is a change to a referenced resource or resource attribute. +You can also use the [`replace_triggered_by` meta-argument](/docs/language/meta-arguments/lifecycle#replace_triggered_by) to add dependencies between otherwise independent resources. It forces OpenTF to replace the parent resource when there is a change to a referenced resource or resource attribute. ## Local-only Resources diff --git a/website/docs/language/resources/index.mdx b/website/docs/language/resources/index.mdx index b78fa6bf55..d258232823 100644 --- a/website/docs/language/resources/index.mdx +++ b/website/docs/language/resources/index.mdx @@ -12,22 +12,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](/opentf/language/resources/syntax) documents +- [Resource Blocks](/docs/language/resources/syntax) documents the syntax for declaring resources. -- [Resource Behavior](/opentf/language/resources/behavior) explains in +- [Resource Behavior](/docs/language/resources/behavior) explains in more detail how OpenTF 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`](/opentf/language/meta-arguments/depends_on), - [`count`](/opentf/language/meta-arguments/count), - [`for_each`](/opentf/language/meta-arguments/for_each), - [`provider`](/opentf/language/meta-arguments/resource-provider), - and [`lifecycle`](/opentf/language/meta-arguments/lifecycle). + [`depends_on`](/docs/language/meta-arguments/depends_on), + [`count`](/docs/language/meta-arguments/count), + [`for_each`](/docs/language/meta-arguments/for_each), + [`provider`](/docs/language/meta-arguments/resource-provider), + and [`lifecycle`](/docs/language/meta-arguments/lifecycle). -- [Provisioners](/opentf/language/resources/provisioners/syntax) +- [Provisioners](/docs/language/resources/provisioners/syntax) 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/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx index 3a06813b75..19826c369c 100644 --- a/website/docs/language/resources/provisioners/connection.mdx +++ b/website/docs/language/resources/provisioners/connection.mdx @@ -11,7 +11,7 @@ Most provisioners require access to the remote resource via SSH or WinRM and expect a nested `connection` block with details about how to connect. ~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to -[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details. +[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details. ## Connection Block @@ -78,8 +78,8 @@ The `connection` block supports the following arguments. Some arguments are only | `port` | Both| The port to connect to. | `22` for type `"ssh"`
`5985` for type `"winrm"` | | `timeout` | Both | The timeout to wait for the connection to become available. Should be provided as a string (e.g., `"30s"` or `"5m"`.) | `"5m"` | | `script_path` | Both | The path used to copy scripts meant for remote execution. Refer to [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below for more details. | (details below) | -| `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/opentf/language/functions/file). This takes preference over `password` if provided. | | -| `certificate` | SSH | 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](/opentf/language/functions/file). | | +| `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/docs/language/functions/file). This takes preference over `password` if provided. | | +| `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/docs/language/functions/file). | | | `agent` | SSH | 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). | | | `agent_identity` | SSH | The preferred identity from the ssh agent for authentication. | | | `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | | @@ -104,8 +104,8 @@ indirectly with a [bastion host](https://en.wikipedia.org/wiki/Bastion_host). | `bastion_port` | The port to use connect to the bastion host. | The value of the `port` field.| | `bastion_user`| The user for the connection to the bastion host. | The value of the `user` field. | | `bastion_password` | The password to use for the bastion host. | The value of the `password` field. | -| `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](/opentf/language/functions/file). | 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](/opentf/language/functions/file). | +| `bastion_private_key` | The contents of an SSH key file to use for the bastion host. These can be loaded from a file on disk using [the `file` function](/docs/language/functions/file). | The value of the `private_key` field. | +| `bastion_certificate` | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `bastion_private_key`. These can be loaded from a file on disk using the [the `file` function](/docs/language/functions/file). | ## Connection through a HTTP Proxy with SSH diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.mdx index e528e65c98..001de4659b 100644 --- a/website/docs/language/resources/provisioners/file.mdx +++ b/website/docs/language/resources/provisioners/file.mdx @@ -10,10 +10,10 @@ description: >- The `file` provisioner copies files or directories from the machine running OpenTF to the newly created resource. The `file` provisioner -supports both `ssh` and `winrm` type [connections](/opentf/language/resources/provisioners/connection). +supports both `ssh` and `winrm` type [connections](/docs/language/resources/provisioners/connection). ~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to -[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details. +[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details. ## Example usage diff --git a/website/docs/language/resources/provisioners/local-exec.mdx b/website/docs/language/resources/provisioners/local-exec.mdx index 8782795794..8b9719b12b 100644 --- a/website/docs/language/resources/provisioners/local-exec.mdx +++ b/website/docs/language/resources/provisioners/local-exec.mdx @@ -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 OpenTF, not on the resource. See the `remote-exec` -[provisioner](/opentf/language/resources/provisioners/remote-exec) to run commands on the +[provisioner](/docs/language/resources/provisioners/remote-exec) to run commands on the resource. Note that even though the resource will be fully created when the provisioner is @@ -19,7 +19,7 @@ run, there is no guarantee that it will be in an operable state - for example system services such as `sshd` may not be started yet on compute resources. ~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to -[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details. +[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details. ## Example usage @@ -59,7 +59,7 @@ The following arguments are supported: * `when` - (Optional) If provided, specifies when OpenTF will execute the command. For example, `when = destroy` specifies that the provisioner will run when the associated resource - is destroyed. Refer to [Destroy-Time Provisioners](/opentf/language/resources/provisioners/syntax#destroy-time-provisioners) + is destroyed. Refer to [Destroy-Time Provisioners](/docs/language/resources/provisioners/syntax#destroy-time-provisioners) for details. * `quiet` - (Optional) If set to `true`, OpenTF will not print the command to be executed to stdout, and will instead print "Suppressed by quiet=true". Note that the output of the command will still be printed in any case. diff --git a/website/docs/language/resources/provisioners/null_resource.mdx b/website/docs/language/resources/provisioners/null_resource.mdx index 358a5c9e0e..8771ebb1a5 100644 --- a/website/docs/language/resources/provisioners/null_resource.mdx +++ b/website/docs/language/resources/provisioners/null_resource.mdx @@ -10,16 +10,16 @@ description: >- If you need to run provisioners that aren't directly associated with a specific resource, you can associate them with a `terraform_data`. -Instances of [`terraform_data`](/opentf/language/resources/tf-data) are treated +Instances of [`terraform_data`](/docs/language/resources/tf-data) are treated like normal resources, but they don't do anything. Like with any other resource -type, you can configure [provisioners](/opentf/language/resources/provisioners/syntax) -and [connection details](/opentf/language/resources/provisioners/connection) on a +type, you can configure [provisioners](/docs/language/resources/provisioners/syntax) +and [connection details](/docs/language/resources/provisioners/connection) on a `terraform_data` resource. You can also use its `input` argument, `triggers_replace` argument, and any meta-arguments to control exactly where in the dependency graph its provisioners will run. ~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to -[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details. +[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details. ## Example usage diff --git a/website/docs/language/resources/provisioners/remote-exec.mdx b/website/docs/language/resources/provisioners/remote-exec.mdx index 9bb5bed4a6..0e7c42f3c6 100644 --- a/website/docs/language/resources/provisioners/remote-exec.mdx +++ b/website/docs/language/resources/provisioners/remote-exec.mdx @@ -13,12 +13,12 @@ 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](/opentf/language/resources/provisioners/local-exec) instead. The `remote-exec` -provisioner requires a [connection](/opentf/language/resources/provisioners/connection) +[provisioner](/docs/language/resources/provisioners/local-exec) instead. The `remote-exec` +provisioner requires a [connection](/docs/language/resources/provisioners/connection) and supports both `ssh` and `winrm`. ~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to -[Declaring Provisioners](/opentf/language/resources/provisioners/syntax) for more details. +[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details. ## Example usage @@ -60,14 +60,14 @@ The following arguments are supported: that will be copied to the remote resource and then executed. They are executed in the order they are provided. This cannot be provided with `inline` or `script`. --> **Note:** Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/opentf/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#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](/opentf/language/resources/provisioners/file) +[file provisioner](/docs/language/resources/provisioners/file) and then use `inline` to call it. Example: ```hcl diff --git a/website/docs/language/resources/provisioners/syntax.mdx b/website/docs/language/resources/provisioners/syntax.mdx index 9f9aa8eeaa..1ebc97e39b 100644 --- a/website/docs/language/resources/provisioners/syntax.mdx +++ b/website/docs/language/resources/provisioners/syntax.mdx @@ -93,7 +93,7 @@ remote access credentials to be provided. You can add the [`cloudinit_config`](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs) data source to your OpenTF configuration and specify the files you want to provision as `text/cloud-config` content. The `cloudinit_config` data source renders multi-part MIME configurations for use with [cloud-init](https://cloudinit.readthedocs.io/en/latest/). Pass the files in the `content` field as YAML-encoded configurations using the `write_files` block. -In the following example, the `my_cloud_config` data source specifies a `text/cloud-config` MIME part named `cloud.conf`. The `part.content` field is set to [`yamlencode`](/opentf/language/functions/yamlencode), which encodes the `write_files` JSON object as YAML so that the system can provision the referenced files. +In the following example, the `my_cloud_config` data source specifies a `text/cloud-config` MIME part named `cloud.conf`. The `part.content` field is set to [`yamlencode`](/docs/language/functions/yamlencode), which encodes the `write_files` JSON object as YAML so that the system can provision the referenced files. ```hcl data "cloudinit_config" "my_cloud_config" { @@ -191,7 +191,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](/opentf/language/resources/provisioners/connection) so that OpenTF knows how to communicate with the server. +You must include [a `connection` block](/docs/language/resources/provisioners/connection) so that OpenTF knows how to communicate with the server. OpenTF includes several built-in provisioners. You can also use third-party provisioners as plugins, by placing them in `%APPDATA%\terraform.d\plugins`, `~/.terraform.d/plugins`, or the same @@ -219,8 +219,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](/opentf/language/values/variables#suppressing-values-in-cli-output) or -[`sensitive` output values](/opentf/language/values/outputs#sensitive-suppressing-values-in-cli-output). +[`sensitive` variables](/docs/language/values/variables#suppressing-values-in-cli-output) or +[`sensitive` output values](/docs/language/values/outputs#sensitive-suppressing-values-in-cli-output). In this case, all log output from the provisioner is automatically suppressed to prevent the sensitive values from being displayed. diff --git a/website/docs/language/resources/syntax.mdx b/website/docs/language/resources/syntax.mdx index bb4341e7db..3055a0c942 100644 --- a/website/docs/language/resources/syntax.mdx +++ b/website/docs/language/resources/syntax.mdx @@ -51,7 +51,7 @@ attributes the resource supports. ### Providers -Each resource type is implemented by a [provider](/opentf/language/providers/requirements), +Each resource type is implemented by a [provider](/docs/language/providers/requirements), which is a plugin for OpenTF 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 OpenTF @@ -64,16 +64,16 @@ access their remote APIs, and the root module must provide that configuration. For more information, see: -- [Provider Requirements](/opentf/language/providers/requirements), for declaring which +- [Provider Requirements](/docs/language/providers/requirements), for declaring which providers a module uses. -- [Provider Configuration](/opentf/language/providers/configuration), for configuring provider settings. +- [Provider Configuration](/docs/language/providers/configuration), for configuring provider settings. OpenTF 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](/opentf/language/meta-arguments/resource-provider) for more details. +[the `provider` meta-argument](/docs/language/meta-arguments/resource-provider) for more details. ### Resource Arguments @@ -82,7 +82,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](/opentf/language/expressions) and other dynamic OpenTF +[expressions](/docs/language/expressions) and other dynamic OpenTF language features. There are also some _meta-arguments_ that are defined by OpenTF itself @@ -112,7 +112,7 @@ public provider docs. For more information about how OpenTF manages resources when applying a configuration, see -[Resource Behavior](/opentf/language/resources/behavior). +[Resource Behavior](/docs/language/resources/behavior). ## Meta-Arguments @@ -121,12 +121,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](/opentf/language/meta-arguments/depends_on) -- [`count`, for creating multiple resource instances according to a count](/opentf/language/meta-arguments/count) -- [`for_each`, to create multiple instances according to a map, or set of strings](/opentf/language/meta-arguments/for_each) -- [`provider`, for selecting a non-default provider configuration](/opentf/language/meta-arguments/resource-provider) -- [`lifecycle`, for lifecycle customizations](/opentf/language/meta-arguments/lifecycle) -- [`provisioner`, for taking extra actions after resource creation](/opentf/language/resources/provisioners/syntax) +- [`depends_on`, for specifying hidden dependencies](/docs/language/meta-arguments/depends_on) +- [`count`, for creating multiple resource instances according to a count](/docs/language/meta-arguments/count) +- [`for_each`, to create multiple instances according to a map, or set of strings](/docs/language/meta-arguments/for_each) +- [`provider`, for selecting a non-default provider configuration](/docs/language/meta-arguments/resource-provider) +- [`lifecycle`, for lifecycle customizations](/docs/language/meta-arguments/lifecycle) +- [`provisioner`, for taking extra actions after resource creation](/docs/language/resources/provisioners/syntax) ## Custom Condition Checks @@ -150,7 +150,7 @@ resource "aws_instance" "example" { Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. -Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. +Refer to [Custom Condition Checks](/docs/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. ## Operation Timeouts diff --git a/website/docs/language/resources/tf-data.mdx b/website/docs/language/resources/tf-data.mdx index bd9533ccf5..50abdcbe99 100644 --- a/website/docs/language/resources/tf-data.mdx +++ b/website/docs/language/resources/tf-data.mdx @@ -8,7 +8,7 @@ description: >- # The `terraform_data` Managed Resource Type The `terraform_data` implements the standard resource lifecycle, but does not directly take any other actions. -You can use the `terraform_data` resource without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/opentf/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. +You can use the `terraform_data` resource without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/docs/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. The `terraform_data` resource is useful for storing values which need to follow a manage resource lifecycle, and for triggering provisioners when there is no other logical managed resource in which to place them. @@ -16,9 +16,9 @@ The `terraform_data` resource is useful for storing values which need to follow ## Example Usage (data for `replace_triggered_by`) -[The `replace_triggered_by` lifecycle argument](/opentf/language/meta-arguments/lifecycle#replace_triggered_by) requires all of the given addresses to be for resources, because the decision to force replacement is based on the planned actions for all of the mentioned resources. +[The `replace_triggered_by` lifecycle argument](/docs/language/meta-arguments/lifecycle#replace_triggered_by) requires all of the given addresses to be for resources, because the decision to force replacement is based on the planned actions for all of the mentioned resources. -Plain data values such as [Local Values](/opentf/language/values/locals) and [Input Variables](/opentf/language/values/variables) don't have any side-effects to plan against and so they aren't valid in `replace_triggered_by`. You can use `terraform_data`'s behavior of planning an action each time `input` changes to _indirectly_ use a plain value to trigger replacement. +Plain data values such as [Local Values](/docs/language/values/locals) and [Input Variables](/docs/language/values/variables) don't have any side-effects to plan against and so they aren't valid in `replace_triggered_by`. You can use `terraform_data`'s behavior of planning an action each time `input` changes to _indirectly_ use a plain value to trigger replacement. ```hcl diff --git a/website/docs/language/settings/backends/azurerm.mdx b/website/docs/language/settings/backends/azurerm.mdx index 90341a6aae..459984375c 100644 --- a/website/docs/language/settings/backends/azurerm.mdx +++ b/website/docs/language/settings/backends/azurerm.mdx @@ -115,7 +115,7 @@ terraform { } ``` --> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/opentf/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#partial-configuration) for the credentials. ## Data Source Configuration @@ -230,7 +230,7 @@ data "terraform_remote_state" "foo" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options are supported: diff --git a/website/docs/language/settings/backends/configuration.mdx b/website/docs/language/settings/backends/configuration.mdx index 8a071fbf11..71c9f01180 100644 --- a/website/docs/language/settings/backends/configuration.mdx +++ b/website/docs/language/settings/backends/configuration.mdx @@ -6,7 +6,7 @@ description: >- # Backend Configuration -A backend defines where OpenTF stores its [state](/opentf/language/state) data files. +A backend defines where OpenTF stores its [state](/docs/language/state) data files. OpenTF uses persisted state data to keep track of the resources it manages. Most non-trivial OpenTF configurations either intergrate with TACOS (TF Automation and Collaboration Software) or use a backend to store state remotely. This lets multiple people access the state data and work together on that collection of infrastructure resources. @@ -14,14 +14,14 @@ This page describes how to configure a backend by adding the [`backend` block](# ## Available Backends -By default, OpenTF uses a backend called [`local`](/opentf/language/settings/backends/local), which stores state as a local file on disk. You can also configure one of the built-in backends included in this documentation. +By default, OpenTF uses a backend called [`local`](/docs/language/settings/backends/local), which stores state as a local file on disk. You can also configure one of the built-in backends included in this documentation. Some of these backends act like plain remote disks for state files, while others support locking the state while operations are being performed. This helps prevent conflicts and inconsistencies. The built-in backends listed are the only backends. You cannot load additional backends as plugins. ## Using a Backend Block You do not need to configure a backend when using TACOS (TF Automation and Collaboration Software) because -it automatically manages state in the workspaces associated with your configuration. If your configuration includes a [`cloud` block](/opentf/language/settings/tf-cloud), it cannot include a `backend` block. +it automatically manages state in the workspaces associated with your configuration. If your configuration includes a [`cloud` block](/docs/language/settings/tf-cloud), it cannot include a `backend` block. To configure a backend, add a nested `backend` block within the top-level `opentf` block. The following example configures the `remote` backend. @@ -77,7 +77,7 @@ or state operations. After you initialize, OpenTF creates a `.terraform/` directory locally. This directory contains the most recent backend configuration, including any authentication parameters you provided to the OpenTF CLI. Do not check this directory into Git, as it may contain sensitive credentials for your remote backend. -The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](/opentf/language/state) about your real-world infrastruture. OpenTF stores the `terraform.tfstate` file in your remote backend. +The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](/docs/language/state) about your real-world infrastruture. OpenTF stores the `terraform.tfstate` file in your remote backend. When you change backends, OpenTF gives you the option to migrate your state to the new backend. This lets you adopt backends without losing @@ -94,7 +94,7 @@ automatically by an automation script running OpenTF. 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](/opentf/cli/init). +provided as part of [the initialization process](/docs/cli/init). There are several ways to supply the remaining arguments: @@ -177,12 +177,12 @@ both the configuration itself as well as the type of backend (for example from "consul" to "s3"). OpenTF will automatically detect any changes in your configuration -and request a [reinitialization](/opentf/cli/init). As part of +and request a [reinitialization](/docs/cli/init). As part of the reinitialization process, OpenTF 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](/opentf/language/state/workspaces), +If you're using multiple [workspaces](/docs/language/state/workspaces), OpenTF can copy all workspaces to the destination. If OpenTF detects you have multiple workspaces, it will ask if this is what you want to do. @@ -193,7 +193,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. OpenTF will detect this like any other -change and prompt you to [reinitialize](/opentf/cli/init). +change and prompt you to [reinitialize](/docs/cli/init). As part of the reinitialization, OpenTF 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.mdx b/website/docs/language/settings/backends/consul.mdx index b7de41a47b..047dd02e80 100644 --- a/website/docs/language/settings/backends/consul.mdx +++ b/website/docs/language/settings/backends/consul.mdx @@ -7,7 +7,7 @@ description: OpenTF can store state in Consul. Stores the state in the [Consul](https://www.consul.io/) KV store at a given path. -This backend supports [state locking](/opentf/language/state/locking). +This backend supports [state locking](/docs/language/state/locking). ## Example Configuration @@ -22,7 +22,7 @@ terraform { ``` Note that for the access credentials we recommend using a -[partial configuration](/opentf/language/settings/backends/configuration#partial-configuration). +[partial configuration](/docs/language/settings/backends/configuration#partial-configuration). ## Data Source Configuration @@ -37,7 +37,7 @@ data "terraform_remote_state" "foo" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options / environment variables are supported: diff --git a/website/docs/language/settings/backends/cos.mdx b/website/docs/language/settings/backends/cos.mdx index e1151b0c43..4f29bfc64d 100644 --- a/website/docs/language/settings/backends/cos.mdx +++ b/website/docs/language/settings/backends/cos.mdx @@ -9,7 +9,7 @@ description: >- Stores the state as an object in a configurable prefix in a given bucket on [Tencent Cloud Object Storage](https://intl.cloud.tencent.com/product/cos) (COS). -This backend supports [state locking](/opentf/language/state/locking). Storing your state in a COS bucket requires the following permissions: +This backend supports [state locking](/docs/language/state/locking). Storing your state in a COS bucket requires the following permissions: - `CreateTag`, `DeleteTag`, and `DescribeTags` on the tag key `tencentcloud-terraform-lock` - `Put`, `Get`, and `Delete` files for the specified bucket's prefix @@ -34,7 +34,7 @@ OpenTF state will be written into the file `opentf/state/terraform.tfstate`. ## Data Source Configuration -To make use of the COS remote state in another configuration, use the [`terraform_remote_state` data source](/opentf/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). ```hcl data "terraform_remote_state" "foo" { @@ -50,7 +50,7 @@ data "terraform_remote_state" "foo" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options or environment variables are supported: diff --git a/website/docs/language/settings/backends/gcs.mdx b/website/docs/language/settings/backends/gcs.mdx index 51eae1b911..a5acda3b91 100644 --- a/website/docs/language/settings/backends/gcs.mdx +++ b/website/docs/language/settings/backends/gcs.mdx @@ -10,7 +10,7 @@ description: >- Stores the state as an object in a configurable prefix in a pre-existing bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS). The bucket must exist prior to configuring the backend. -This backend supports [state locking](/opentf/language/state/locking). +This backend supports [state locking](/docs/language/state/locking). ~> **Warning!** It is highly recommended that you enable [Object Versioning](https://cloud.google.com/storage/docs/object-versioning) @@ -88,13 +88,13 @@ To get started, follow this guide: [Use customer-managed encryption keys](https: If you want to remove customer-managed keys from your backend configuration or change to a different customer-managed key, OpenTF _can_ manage a state migration without manual intervention. This ability is because GCP stores customer-managed encryption keys and are accessible during the state migration process. However, these changes do not fully come into effect until the first write operation occurs on the state file after state migration occurs. In the first write operation after state migration, the file decrypts with the old key and then writes with the new encryption method. This method is equivalent to the [rewrite](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) operation described in the customer-supplied encryption keys section. Because of the importance of the first write to state after state migration, you should not delete old KMS keys until any state file(s) encrypted with that key update. -Customer-managed keys do not need to be sent in requests to read files from GCS buckets because decryption occurs automatically within GCS. This process means that if you use the `terraform_remote_state` [data source](/opentf/language/state/remote-state-data) to access KMS-encrypted state, you do not need to specify the KMS key in the data source's `config` object. +Customer-managed keys do not need to be sent in requests to read files from GCS buckets because decryption occurs automatically within GCS. This process means that if you use the `terraform_remote_state` [data source](/docs/language/state/remote-state-data) to access KMS-encrypted state, you do not need to specify the KMS key in the data source's `config` object. ~> **Important:** To use customer-managed encryption keys, you need to create a key and give your project's GCS service agent permission to use it with the Cloud KMS CryptoKey Encrypter/Decrypter predefined role. ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF includes these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF includes these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options are supported: diff --git a/website/docs/language/settings/backends/http.mdx b/website/docs/language/settings/backends/http.mdx index a74fc968f2..c5167b1fb8 100644 --- a/website/docs/language/settings/backends/http.mdx +++ b/website/docs/language/settings/backends/http.mdx @@ -9,7 +9,7 @@ Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representat State will be fetched via GET, updated via POST, and purged with DELETE. The method used for updating is configurable. -This backend optionally supports [state locking](/opentf/language/state/locking). When locking +This backend optionally supports [state locking](/docs/language/state/locking). When locking support is enabled it will use LOCK and UNLOCK requests providing the lock info in the body. The endpoint should return a 423: Locked or 409: Conflict with the holding lock info when it's already taken, 200: OK for success. Any other status will be considered an error. The ID of the holding lock @@ -40,7 +40,7 @@ data "terraform_remote_state" "foo" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options / environment variables are supported: diff --git a/website/docs/language/settings/backends/kubernetes.mdx b/website/docs/language/settings/backends/kubernetes.mdx index a319c73e0a..c262db9f28 100644 --- a/website/docs/language/settings/backends/kubernetes.mdx +++ b/website/docs/language/settings/backends/kubernetes.mdx @@ -9,7 +9,7 @@ description: OpenTF can store state remotely in Kubernetes and lock that state. Stores the state in a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/). -This backend supports [state locking](/opentf/language/state/locking), with locking done using a Lease resource. +This backend supports [state locking](/docs/language/state/locking), with locking done using a Lease resource. ## Example Configuration @@ -30,7 +30,7 @@ If the `in_cluster_config` flag is set the backend will attempt to use a [servic 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](/opentf/language/settings/backends/configuration#partial-configuration). +Note that for the access credentials we recommend using a [partial configuration](/docs/language/settings/backends/configuration#partial-configuration). ## Example Referencing @@ -46,7 +46,7 @@ data "terraform_remote_state" "foo" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options are supported: diff --git a/website/docs/language/settings/backends/local.mdx b/website/docs/language/settings/backends/local.mdx index 1705287bbf..e1a415570f 100644 --- a/website/docs/language/settings/backends/local.mdx +++ b/website/docs/language/settings/backends/local.mdx @@ -77,7 +77,7 @@ the three arguments would typically all be paths within a temporary directory used just for one operation. Because these old workflows predate the introduction of the possibility of -[multiple workspaces](/opentf/language/state/workspaces), setting them +[multiple workspaces](/docs/language/state/workspaces), setting them overrides Terraform's usual behavior of selecting a different state filename based on the selected workspace. If you use all three of these options then the selected workspace has no effect on which filenames Terraform will select @@ -89,7 +89,7 @@ backend type selected. We do not recommend using these options in new systems, even if you are running Terraform in automation. Instead, -[select a different backend which supports remote state](/opentf/language/settings/backends/configuration) and configure it +[select a different backend which supports remote state](/docs/language/settings/backends/configuration) 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/oss.mdx b/website/docs/language/settings/backends/oss.mdx index 701a145554..f1bf717c19 100644 --- a/website/docs/language/settings/backends/oss.mdx +++ b/website/docs/language/settings/backends/oss.mdx @@ -11,7 +11,7 @@ This backend also supports state locking and consistency checking via [Alibaba Cloud Table Store](https://www.alibabacloud.com/help/doc-detail/27280.htm), which can be enabled by setting the `tablestore_table` field to an existing TableStore table name. -This backend supports [state locking](/opentf/language/state/locking) via TableStore. +This backend supports [state locking](/docs/language/state/locking) via TableStore. ## Example Configuration @@ -37,7 +37,7 @@ OpenTF state will be written into the file `path/mystate/version-1.tfstate`. The To make use of the OSS remote state in another configuration, use the [`terraform_remote_state` data -source](/opentf/language/state/remote-state-data). +source](/docs/language/state/remote-state-data). ```hcl terraform { @@ -69,7 +69,7 @@ data "terraform_remote_state" "network" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options or environment variables are supported: diff --git a/website/docs/language/settings/backends/pg.mdx b/website/docs/language/settings/backends/pg.mdx index 9db45115b3..20452bebe7 100644 --- a/website/docs/language/settings/backends/pg.mdx +++ b/website/docs/language/settings/backends/pg.mdx @@ -7,7 +7,7 @@ description: OpenTF can store state remotely in a Postgres database with locking Stores the state in a [Postgres database](https://www.postgresql.org) version 10 or newer. -This backend supports [state locking](/opentf/language/state/locking). +This backend supports [state locking](/docs/language/state/locking). ## Example Configuration @@ -69,7 +69,7 @@ $ opentf init ## Data Source Configuration -To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/opentf/language/state/remote-state-data). +To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/docs/language/state/remote-state-data). ```hcl data "terraform_remote_state" "network" { @@ -82,7 +82,7 @@ data "terraform_remote_state" "network" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options or environment variables are supported: @@ -96,9 +96,9 @@ The following configuration options or environment variables are supported: 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](/opentf/language/state/workspaces) name. If workspaces are not in use, the name `default` is used. +The table is keyed by the [workspace](/docs/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`](/opentf/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). +Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](/docs/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: diff --git a/website/docs/language/settings/backends/remote.mdx b/website/docs/language/settings/backends/remote.mdx index 4445473ca7..92a6bb914d 100644 --- a/website/docs/language/settings/backends/remote.mdx +++ b/website/docs/language/settings/backends/remote.mdx @@ -7,9 +7,9 @@ description: >- # remote --> **Note:** **We recommend using the [`cloud` built-in integration](/opentf/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features. +-> **Note:** **We recommend using the [`cloud` built-in integration](/docs/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features. -The remote backend is unique among all other OpenTF backends because it can both store state snapshots and execute operations for TACOS (TF Automation and Collaboration Software) [CLI-driven run workflow](/opentf/cloud-docs/run/cli). It used to be called an "enhanced" backend. +The remote backend is unique among all other OpenTF backends because it can both store state snapshots and execute operations for TACOS (TF Automation and Collaboration Software) [CLI-driven run workflow](/docs/cloud-docs/run/cli). It used to be called an "enhanced" backend. When using full remote operations, operations like `opentf plan` or `opentf apply` can be executed in TACOS (TF Automation and Collaboration Software) run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated remote workspace. @@ -50,7 +50,7 @@ determines which mode it uses: all of the desired remote workspace names. For example, set `prefix = "networking-"` to use remote workspaces with names like `networking-dev` and `networking-prod`. This is helpful when - mapping multiple OpenTF CLI [workspaces](/opentf/language/state/workspaces) + mapping multiple OpenTF CLI [workspaces](/docs/language/state/workspaces) used in a single OpenTF configuration to multiple remote workspaces. @@ -67,14 +67,14 @@ running any remote operations against them. OpenTF uses shortened names without the common prefix to interact with workspaces on the command line. For example, if `prefix = "networking-"`, use `opentf workspace select prod` to switch to the OpenTF CLI workspace `prod` within the current configuration. However, remote OpenTF operations such as `plan` and `apply` for that OpenTF CLI workspace will take place in the remote workspace `networking-prod`. -Because of this, the [`terraform.workspace`](/opentf/language/state/workspaces#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following: +Because of this, the [`terraform.workspace`](/docs/language/state/workspaces#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following: - For local operations, `terraform.workspace` = `prod` - For remote operations, `terraform.workspace`= `networking-prod` ### Determining Run Environment -If you need to determine whether a run is local or remote in your OpenTF configuration, we recommend using [run environment variables](/opentf/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`. +If you need to determine whether a run is local or remote in your OpenTF configuration, we recommend using [run environment variables](/docs/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`. ``` output "current_workspace_name" { @@ -95,8 +95,8 @@ output "remote_execution_determine" { ## Example Configurations -> **Note:** We recommend omitting the token from the configuration, and instead using -[`opentf login`](/opentf/cli/commands/login) or manually configuring -`credentials` in the [CLI config file](/opentf/cli/config/config-file#credentials). +[`opentf login`](/docs/cli/commands/login) or manually configuring +`credentials` in the [CLI config file](/docs/cli/config/config-file#credentials). ### Basic Configuration @@ -170,7 +170,7 @@ data "terraform_remote_state" "foo" { ## Configuration Variables -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration options are supported: @@ -179,9 +179,9 @@ The following configuration options are supported: targeted workspace(s). - `token` - (Optional) The token used to authenticate with the remote backend. We recommend omitting the token from the configuration, and instead using - [`opentf login`](/opentf/cli/commands/login) or manually configuring + [`opentf login`](/docs/cli/commands/login) or manually configuring `credentials` in the - [CLI config file](/opentf/cli/config/config-file#credentials). + [CLI config file](/docs/cli/config/config-file#credentials). - `workspaces` - (Required) A block specifying which remote workspace(s) to use. The `workspaces` block supports the following keys: @@ -219,7 +219,7 @@ the remote workspace accept the following option to modify that behavior: ## Excluding Files from Upload with .terraformignore -When executing a remote `plan` or `apply` in a [CLI-driven run](/opentf/cloud-docs/run/cli), +When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud-docs/run/cli), an archive of your configuration directory is uploaded to TACOS (TF Automation and Collaboration Software). 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: diff --git a/website/docs/language/settings/backends/s3.mdx b/website/docs/language/settings/backends/s3.mdx index 6ad2a6d00d..656720283b 100644 --- a/website/docs/language/settings/backends/s3.mdx +++ b/website/docs/language/settings/backends/s3.mdx @@ -32,7 +32,7 @@ This assumes we have a bucket created called `mybucket`. The OpenTF state is written to the key `path/to/my/key`. Note that for the access credentials we recommend using a -[partial configuration](/opentf/language/settings/backends/configuration#partial-configuration). +[partial configuration](/docs/language/settings/backends/configuration#partial-configuration). ### S3 Bucket Permissions @@ -104,7 +104,7 @@ This is seen in the following AWS IAM Statement: ## Data Source Configuration To make use of the S3 remote state in another configuration, use the -[`terraform_remote_state` data source](/opentf/language/state/remote-state-data). +[`terraform_remote_state` data source](/docs/language/state/remote-state-data). ```hcl data "terraform_remote_state" "network" { @@ -143,7 +143,7 @@ This backend requires the configuration of the AWS Region and S3 state storage. ### Credentials and Shared Configuration -!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details. +!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details. The following configuration is required: @@ -181,7 +181,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](/opentf/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), the state path will be `/workspace_key_prefix/workspace_name/key` (see also the `workspace_key_prefix` configuration). The following configuration is optional: @@ -213,7 +213,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 -[OpenTF's workspaces feature](/opentf/language/state/workspaces) to switch +[OpenTF's workspaces feature](/docs/language/state/workspaces) to switch conveniently between multiple isolated deployments of the same configuration. Use this section as a starting-point for your approach, but note that @@ -321,7 +321,7 @@ provider "aws" { If workspace IAM roles are centrally managed and shared across many separate OpenTF configurations, the role ARNs could also be obtained via a data -source such as [`terraform_remote_state`](/opentf/language/state/remote-state-data) +source such as [`terraform_remote_state`](/docs/language/state/remote-state-data) to avoid repeating these values. ### Creating and Selecting Workspaces diff --git a/website/docs/language/settings/index.mdx b/website/docs/language/settings/index.mdx index dbe05e9801..8fa9f1c4fe 100644 --- a/website/docs/language/settings/index.mdx +++ b/website/docs/language/settings/index.mdx @@ -35,18 +35,18 @@ following sections. The nested `backend` block configures which state backend OpenTF should use. The syntax and behavior of the `backend` block is described in [Backend -Configuration](/opentf/language/settings/backends/configuration). +Configuration](/docs/language/settings/backends/configuration). ## Specifying a Required OpenTF Version The `required_version` setting accepts a [version constraint -string,](/opentf/language/expressions/version-constraints) which specifies which versions of OpenTF +string,](/docs/language/expressions/version-constraints) which specifies which versions of OpenTF can be used with your configuration. If the running version of OpenTF doesn't match the constraints specified, OpenTF will produce an error and exit without taking any further actions. -When you use [child modules](/opentf/language/modules), each module can specify its own +When you use [child modules](/docs/language/modules), each module can specify its own version requirements. The requirements of all modules in the tree must be satisfied. @@ -57,7 +57,7 @@ a minimum OpenTF version that has behavior expected by the configuration. The `required_version` setting applies only to the version of OpenTF CLI. OpenTF's resource types are implemented by provider plugins, whose release cycles are independent of OpenTF CLI and of each other. -Use [the `required_providers` block](/opentf/language/providers/requirements) to manage +Use [the `required_providers` block](/docs/language/providers/requirements) to manage the expected versions for each provider you use. ## Specifying Provider Requirements @@ -77,7 +77,7 @@ terraform { } ``` -For more information, see [Provider Requirements](/opentf/language/providers/requirements). +For more information, see [Provider Requirements](/docs/language/providers/requirements). ## Experimental Language Features @@ -122,4 +122,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](/opentf/internals/provider-meta). +For more information, see [Provider Metadata](/docs/internals/provider-meta). diff --git a/website/docs/language/settings/tf-cloud.mdx b/website/docs/language/settings/tf-cloud.mdx index 4ba2f5b851..4f2b821973 100644 --- a/website/docs/language/settings/tf-cloud.mdx +++ b/website/docs/language/settings/tf-cloud.mdx @@ -6,14 +6,14 @@ description: >- # Cloud Configuration -The main module of an OpenTF configuration can integrate with a cloud backend to enable its [CLI-driven run workflow](/opentf/cloud-docs/run/cli). You only need to configure these settings when you want to use OpenTF CLI to interact with a cloud backend. +The main module of an OpenTF configuration can integrate with a cloud backend to enable its [CLI-driven run workflow](/docs/cloud-docs/run/cli). You only need to configure these settings when you want to use OpenTF CLI to interact with a cloud backend. A cloud backend ignores them when interacting with OpenTF through version control or the API. ## Usage Example -To configure the cloud CLI integration, add a nested `cloud` block within the `terraform` block. You cannot use the CLI integration and a [state backend](/opentf/language/settings/backends/configuration) in the same configuration. +To configure the cloud CLI integration, add a nested `cloud` block within the `terraform` block. You cannot use the CLI integration and a [state backend](/docs/language/settings/backends/configuration) in the same configuration. -Refer to [Using the Cloud Backend](/opentf/cli/cloud) in the OpenTF CLI documentation for full configuration details, migration instructions, and command line arguments. +Refer to [Using the Cloud Backend](/docs/cli/cloud) in the OpenTF CLI documentation for full configuration details, migration instructions, and command line arguments. ```hcl terraform { diff --git a/website/docs/language/state/backends.mdx b/website/docs/language/state/backends.mdx index 5678cb2a1c..9a0962ca58 100644 --- a/website/docs/language/state/backends.mdx +++ b/website/docs/language/state/backends.mdx @@ -8,7 +8,7 @@ description: >- # State Storage and Locking Backends are responsible for storing state and providing an API for -[state locking](/opentf/language/state/locking). State locking is optional. +[state locking](/docs/language/state/locking). State locking is optional. Despite the state being stored remotely, all OpenTF commands such as `opentf console`, the `opentf state` operations, `opentf taint`, @@ -63,10 +63,10 @@ prior to forcing the overwrite. ## State Locking -Backends are responsible for supporting [state locking](/opentf/language/state/locking) +Backends are responsible for supporting [state locking](/docs/language/state/locking) if possible. -Not all backends support locking. The [documentation for each backend](/opentf/language/settings/backends/configuration#available-backends) includes details about whether it supports locking or not. +Not all backends support locking. The [documentation for each backend](/docs/language/settings/backends/configuration#available-backends) includes details about whether it supports locking or not. For more information on state locking, view the -[page dedicated to state locking](/opentf/language/state/locking). +[page dedicated to state locking](/docs/language/state/locking). diff --git a/website/docs/language/state/import.mdx b/website/docs/language/state/import.mdx index e188ab6ddb..fa8630652d 100644 --- a/website/docs/language/state/import.mdx +++ b/website/docs/language/state/import.mdx @@ -10,4 +10,4 @@ description: >- OpenTF is able to import existing infrastructure. This allows you to take resources you have created by some other means and bring them under OpenTF management. -To learn more, see [Import](/opentf/language/import). +To learn more, see [Import](/docs/language/import). diff --git a/website/docs/language/state/index.mdx b/website/docs/language/state/index.mdx index f5b635eb3c..e71c1560ea 100644 --- a/website/docs/language/state/index.mdx +++ b/website/docs/language/state/index.mdx @@ -18,7 +18,7 @@ to version, encrypt, and securely share it with your team. OpenTF uses state to determine which changes to make to your infrastructure. Prior to any operation, OpenTF does a -[refresh](/opentf/cli/commands/refresh) to update the state with the +[refresh](/docs/cli/commands/refresh) to update the state with the real infrastructure. The primary purpose of OpenTF state is to store bindings between objects in @@ -29,13 +29,13 @@ resource instance, and then potentially update or delete that object in response to future configuration changes. For more information on why OpenTF requires state and why OpenTF cannot -function without state, please see the page [state purpose](/opentf/language/state/purpose). +function without state, please see the page [state purpose](/docs/language/state/purpose). ## Inspection and Modification While the format of the state files are just JSON, direct file editing of the state is discouraged. OpenTF provides the -[opentf state](/opentf/cli/commands/state) command to perform +[opentf state](/docs/cli/commands/state) command to perform basic modifications of the state using the CLI. The CLI usage and output of the state commands is structured to be @@ -68,10 +68,10 @@ in new versions. Alternatively, there are several integration points which produce JSON output that is specifically intended for consumption by external software: -* [The `opentf output` command](/opentf/cli/commands/output) +* [The `opentf output` command](/docs/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 `opentf show` command](/opentf/cli/commands/show) has a `-json` +* [The `opentf show` command](/docs/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. diff --git a/website/docs/language/state/locking.mdx b/website/docs/language/state/locking.mdx index 97e9a4c04c..5708a6fd3a 100644 --- a/website/docs/language/state/locking.mdx +++ b/website/docs/language/state/locking.mdx @@ -7,7 +7,7 @@ description: >- # State Locking -If supported by your [backend](/opentf/language/settings/backends/configuration), OpenTF will lock your +If supported by your [backend](/docs/language/settings/backends/configuration), OpenTF 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 +21,12 @@ a status message. If OpenTF 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](/opentf/language/settings/backends/configuration) +[documentation for each backend](/docs/language/settings/backends/configuration) includes details on whether it supports locking or not. ## Force Unlock -OpenTF has a [force-unlock command](/opentf/cli/commands/force-unlock) +OpenTF has a [force-unlock command](/docs/cli/commands/force-unlock) to manually unlock the state if unlocking failed. **Be very careful with this command.** If you unlock the state when someone diff --git a/website/docs/language/state/purpose.mdx b/website/docs/language/state/purpose.mdx index 4c0f032446..81efc92f3e 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.mdx @@ -102,7 +102,7 @@ started, but when using OpenTF 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](/opentf/language/state/remote) is the recommended solution +[Remote state](/docs/language/state/remote) is the recommended solution to this problem. With a fully-featured state backend, OpenTF can use remote locking as a measure to avoid two or more different users accidentally running OpenTF at the same time, and thus ensure that each OpenTF run diff --git a/website/docs/language/state/remote-state-data.mdx b/website/docs/language/state/remote-state-data.mdx index 9a97653c07..ff9f21c35a 100644 --- a/website/docs/language/state/remote-state-data.mdx +++ b/website/docs/language/state/remote-state-data.mdx @@ -10,7 +10,7 @@ description: >- The `terraform_remote_state` data source uses the latest state snapshot from a specified state backend to retrieve the root module output values from some other OpenTF configuration. -You can use the `terraform_remote_state` data source without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/opentf/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. That provider does not include any other resources or data sources. +You can use the `terraform_remote_state` data source without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/docs/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. That provider does not include any other resources or data sources. ## Alternative Ways to Share Data Between Configurations @@ -72,14 +72,14 @@ use of. For example: 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](/opentf/language/functions/jsonencode) +[the `jsonencode` function](/docs/language/functions/jsonencode) and -[the `jsondecode` function](/opentf/language/functions/jsondecode) respectively +[the `jsondecode` function](/docs/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](/opentf/language/modules/develop/composition#data-only-modules) +[data-only module](/docs/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 @@ -135,7 +135,7 @@ The following arguments are supported: The `config` object can use any arguments that would be valid in the equivalent `terraform { backend "" { ... } }` block. See - [the documentation of your chosen backend](/opentf/language/settings/backends/configuration) + [the documentation of your chosen backend](/docs/language/settings/backends/configuration) for details. -> **Note:** If the backend configuration requires a nested block, specify @@ -149,7 +149,7 @@ The following arguments are supported: In addition to the above, the following attributes are exported: * `outputs` - An object containing every root-level - [output](/opentf/language/values/outputs) in the remote state. + [output](/docs/language/values/outputs) in the remote state. ## Root Outputs Only diff --git a/website/docs/language/state/remote.mdx b/website/docs/language/state/remote.mdx index db48cf4215..7a8a72f512 100644 --- a/website/docs/language/state/remote.mdx +++ b/website/docs/language/state/remote.mdx @@ -18,13 +18,13 @@ which can then be shared between all members of a team. OpenTF supports storing state in TACOS (TF Automation and Collaboration Software), [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](/opentf/language/settings/backends/configuration) or by +Remote state is implemented by a [backend](/docs/language/settings/backends/configuration) or by TACOS (TF Automation and Collaboration Software), both of which you can configure in your configuration's root module. ## Delegation and Teamwork Remote state allows you to share -[output values](/opentf/language/values/outputs) with other configurations. +[output values](/docs/language/values/outputs) with other configurations. This allows your infrastructure to be decomposed into smaller components. Put another way, remote state also allows teams to share infrastructure @@ -38,7 +38,7 @@ you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through remote state and have other OpenTF states consume that. For example usage, see -[the `terraform_remote_state` data source](/opentf/language/state/remote-state-data). +[the `terraform_remote_state` data source](/docs/language/state/remote-state-data). While remote state can be a convenient, built-in mechanism for sharing data between configurations, you may prefer to use more general stores to @@ -52,7 +52,7 @@ another that consumes those values using ## Locking and Teamwork For fully-featured remote backends, OpenTF can also use -[state locking](/opentf/language/state/locking) to prevent concurrent runs of +[state locking](/docs/language/state/locking) to prevent concurrent runs of OpenTF against the same state. TACOS (TF Automation and Collaboration Software) is a commercial offering diff --git a/website/docs/language/state/sensitive-data.mdx b/website/docs/language/state/sensitive-data.mdx index 7a273641d5..4c3d5f0e39 100644 --- a/website/docs/language/state/sensitive-data.mdx +++ b/website/docs/language/state/sensitive-data.mdx @@ -12,7 +12,7 @@ passwords. When using local state, state is stored in plain-text JSON files. -When using [remote state](/opentf/language/state/remote), state is only ever held in +When using [remote state](/docs/language/state/remote), state is only ever held in memory when used by OpenTF. It may be encrypted at rest, but this depends on the specific remote state backend. diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index 9dadb6c5a7..0cc0cf24ad 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -7,7 +7,7 @@ description: >- # Workspaces -Each OpenTF configuration has an associated [backend](/opentf/language/settings/backends/configuration) that defines how OpenTF executes operations and where OpenTF stores persistent data, like [state](/opentf/language/state/purpose). +Each OpenTF configuration has an associated [backend](/docs/language/settings/backends/configuration) that defines how OpenTF executes operations and where OpenTF stores persistent data, like [state](/docs/language/state/purpose). The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one OpenTF state associated with that configuration. Some backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. The configuration still has only one backend, but you can deploy multiple distinct instances of that configuration without configuring a new backend or changing authentication credentials. @@ -16,27 +16,27 @@ credentials. You can use multiple workspaces with the following backends: -- [AzureRM](/opentf/language/settings/backends/azurerm) -- [Consul](/opentf/language/settings/backends/consul) -- [COS](/opentf/language/settings/backends/cos) -- [GCS](/opentf/language/settings/backends/gcs) -- [Kubernetes](/opentf/language/settings/backends/kubernetes) -- [Local](/opentf/language/settings/backends/local) -- [OSS](/opentf/language/settings/backends/oss) -- [Postgres](/opentf/language/settings/backends/pg) -- [Remote](/opentf/language/settings/backends/remote) -- [S3](/opentf/language/settings/backends/s3) +- [AzureRM](/docs/language/settings/backends/azurerm) +- [Consul](/docs/language/settings/backends/consul) +- [COS](/docs/language/settings/backends/cos) +- [GCS](/docs/language/settings/backends/gcs) +- [Kubernetes](/docs/language/settings/backends/kubernetes) +- [Local](/docs/language/settings/backends/local) +- [OSS](/docs/language/settings/backends/oss) +- [Postgres](/docs/language/settings/backends/pg) +- [Remote](/docs/language/settings/backends/remote) +- [S3](/docs/language/settings/backends/s3) ## Using Workspaces -~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/opentf/cli/workspaces#use-cases) in the OpenTF CLI documentation for details and recommended alternatives. +~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/docs/cli/workspaces#use-cases) in the OpenTF CLI documentation for details and recommended alternatives. OpenTF starts with a single, default workspace named `default` that you cannot delete. If you have not created a new workspace, you are using the default workspace in your OpenTF working directory. When you run `opentf plan` in a new workspace, OpenTF does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them. -Refer to the [OpenTF CLI workspaces](/opentf/cli/workspaces) documentation for full details about how to create and use workspaces. +Refer to the [OpenTF CLI workspaces](/docs/cli/workspaces) documentation for full details about how to create and use workspaces. ## Current Workspace Interpolation diff --git a/website/docs/language/syntax/configuration.mdx b/website/docs/language/syntax/configuration.mdx index 974f6f95e5..797b640ae2 100644 --- a/website/docs/language/syntax/configuration.mdx +++ b/website/docs/language/syntax/configuration.mdx @@ -15,7 +15,7 @@ those constructs are built from. This page describes the _native syntax_ of the OpenTF language, which is a rich language designed to be relatively easy for humans to read and write. The constructs in the OpenTF language can also be expressed in -[JSON syntax](/opentf/language/syntax/json), which is harder for humans +[JSON syntax](/docs/language/syntax/json), which is harder for humans to read and edit but easier to generate and parse programmatically. This low-level syntax of the OpenTF language is defined in terms of a @@ -46,7 +46,7 @@ after the equals sign is the argument's value. The context where the argument appears determines what value types are valid (for example, each resource type has a schema that defines the types of its arguments), but many arguments accept arbitrary -[expressions](/opentf/language/expressions), which allow the value to +[expressions](/docs/language/expressions), which allow the value to either be specified literally or generated from other values programmatically. -> **Note:** OpenTF's configuration language is based on a more general diff --git a/website/docs/language/syntax/index.mdx b/website/docs/language/syntax/index.mdx index 69519fe67b..dfebd15f87 100644 --- a/website/docs/language/syntax/index.mdx +++ b/website/docs/language/syntax/index.mdx @@ -11,13 +11,13 @@ The majority of the OpenTF 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 OpenTF language. -- [Configuration Syntax](/opentf/language/syntax/configuration) describes the native +- [Configuration Syntax](/docs/language/syntax/configuration) describes the native grammar of the OpenTF language. -- [JSON Configuration Syntax](/opentf/language/syntax/json) documents +- [JSON Configuration Syntax](/docs/language/syntax/json) documents how to represent OpenTF language constructs in the pure JSON variant of the OpenTF language. OpenTF'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](/opentf/language/syntax/style) documents some commonly +- [Style Conventions](/docs/language/syntax/style) documents some commonly accepted formatting guidelines for OpenTF code. These conventions can be - enforced automatically with [`opentf fmt`](/opentf/cli/commands/fmt). + enforced automatically with [`opentf fmt`](/docs/cli/commands/fmt). diff --git a/website/docs/language/syntax/json.mdx b/website/docs/language/syntax/json.mdx index 34b77592a2..c01010edc0 100644 --- a/website/docs/language/syntax/json.mdx +++ b/website/docs/language/syntax/json.mdx @@ -8,7 +8,7 @@ description: >- # JSON Configuration Syntax Most OpenTF configurations are written in -[the native OpenTF language syntax](/opentf/language/syntax/configuration), which is designed to be +[the native OpenTF language syntax](/docs/language/syntax/configuration), which is designed to be relatively easy for humans to read and update. OpenTF also supports an alternative syntax that is JSON-compatible. This @@ -92,7 +92,7 @@ different (see the [block-type-specific exceptions](#block-type-specific-excepti correspond either to argument names or to nested block type names. * Where a property corresponds to an argument that accepts - [arbitrary expressions](/opentf/language/expressions) in the native syntax, the + [arbitrary expressions](/docs/language/expressions) in the native syntax, the property value is mapped to an expression as described under [_Expression Mapping_](#expression-mapping) below. For arguments that do _not_ accept arbitrary expressions, the interpretation of the property @@ -109,7 +109,7 @@ different (see the [block-type-specific exceptions](#block-type-specific-excepti ## Expression Mapping Since JSON grammar is not able to represent all of the OpenTF language -[expression syntax](/opentf/language/expressions), JSON values interpreted as expressions +[expression syntax](/docs/language/expressions), JSON values interpreted as expressions are mapped as follows: | JSON | OpenTF Language Interpretation | diff --git a/website/docs/language/syntax/style.mdx b/website/docs/language/syntax/style.mdx index c870c05e32..9b1231d514 100644 --- a/website/docs/language/syntax/style.mdx +++ b/website/docs/language/syntax/style.mdx @@ -14,7 +14,7 @@ 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 [`opentf fmt`](/opentf/cli/commands/fmt). +-> **Note**: You can enforce these conventions automatically by running [`opentf fmt`](/docs/cli/commands/fmt). * Indent two spaces for each nesting level. diff --git a/website/docs/language/upgrade-guides/index.mdx b/website/docs/language/upgrade-guides/index.mdx index bb5d85452f..1bfdf575cb 100644 --- a/website/docs/language/upgrade-guides/index.mdx +++ b/website/docs/language/upgrade-guides/index.mdx @@ -8,7 +8,7 @@ description: Upgrading to OpenTF v1.6 OpenTF v1.6 is the first release in the stable OpenTF v1.0 series. OpenTF v1.6 honors the -[OpenTF v1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises), +[OpenTF v1.0 Compatibility Promises](/docs/language/v1-compatibility-promises), but there are some behavior changes outside of those promises that may affect a small number of users. Specifically, the following updates may require additional upgrade steps: diff --git a/website/docs/language/v1-compatibility-promises.mdx b/website/docs/language/v1-compatibility-promises.mdx index febda1b506..dae82ff539 100644 --- a/website/docs/language/v1-compatibility-promises.mdx +++ b/website/docs/language/v1-compatibility-promises.mdx @@ -65,35 +65,35 @@ The following top-level blocks and their defined "meta-arguments" (that is, arguments defined by OpenTF Core rather than by external plugins such as providers) will retain their current functionality: -* [`resource`](/opentf/language/resources) and - [`data`](/opentf/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`](/opentf/language/modules/syntax) blocks to call other modules, +* [`module`](/docs/language/modules/syntax) blocks to call other modules, and its meta-argument `providers`. -* The [`count`](/opentf/language/meta-arguments/count), - [`for_each`](/opentf/language/meta-arguments/for_each), and - [`depends_on`](/opentf/language/meta-arguments/depends_on) meta-arguments +* The [`count`](/docs/language/meta-arguments/count), + [`for_each`](/docs/language/meta-arguments/for_each), and + [`depends_on`](/docs/language/meta-arguments/depends_on) meta-arguments in `resource`, `data`, and `module` blocks. -* [`provider`](/opentf/language/providers/configuration) blocks to configure +* [`provider`](/docs/language/providers/configuration) blocks to configure providers, and the `alias` meta-argument. -* [`variable`](/opentf/language/values/variables#declaring-an-input-variable), - [`output`](/opentf/language/values/outputs#declaring-an-output-value), and - [`locals`](/opentf/language/values/locals#declaring-a-local-value) blocks +* [`variable`](/docs/language/values/variables#declaring-an-input-variable), + [`output`](/docs/language/values/outputs#declaring-an-output-value), and + [`locals`](/docs/language/values/locals#declaring-a-local-value) blocks for declaring the various kinds of named values in a module. -* [`terraform`](/opentf/language/settings) blocks, including the nested - [`required_version`](/opentf/language/settings#specifying-a-required-opentf-version) +* [`terraform`](/docs/language/settings) blocks, including the nested + [`required_version`](/docs/language/settings#specifying-a-required-opentf-version) and - [`required_providers`](/opentf/language/providers/requirements#requiring-providers) + [`required_providers`](/docs/language/providers/requirements#requiring-providers) arguments, and nested - [`backend`](/opentf/language/settings/backends/configuration#using-a-backend-block) + [`backend`](/docs/language/settings/backends/configuration#using-a-backend-block) blocks for backend configuration. We also intend to keep compatibility with all -[expression operators](/opentf/language/expressions) and -[built-in functions](/opentf/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`](/opentf/language/expressions/references#terraform-workspace), +[`terraform.workspace`](/docs/language/expressions/references#terraform-workspace), whose behavior may change as part of future changes to the workspace model. We intend to retain broad compatibility with OpenTF language features, with @@ -189,18 +189,18 @@ if you are still using an OpenTF v1.x release. ### Provider Installation Methods OpenTF normally installs providers from a provider registry implementing -[the Provider Registry Protocol](/opentf/internals/provider-registry-protocol), +[the Provider Registry Protocol](/docs/internals/provider-registry-protocol), version 1. All OpenTF v1.x releases will remain compatible with that protocol, and so correctly-implemented provider registries will stay compatible. OpenTF also supports installation of providers from -[local filesystem directories](/opentf/cli/config/config-file#filesystem_mirror) +[local filesystem directories](/docs/cli/config/config-file#filesystem_mirror) (filesystem mirrors) and from -[network mirrors](/opentf/cli/config/config-file#network_mirror) -(implementing [the Provider Mirror Protocol](/opentf/internals/provider-network-mirror-protocol). +[network mirrors](/docs/cli/config/config-file#network_mirror) +(implementing [the Provider Mirror Protocol](/docs/internals/provider-network-mirror-protocol). All OpenTF v1.x releases will remain compatible with those installation methods, including -[the Implied Local Mirror Directories](/opentf/cli/config/config-file#implied-local-mirror-directories). +[the Implied Local Mirror Directories](/docs/cli/config/config-file#implied-local-mirror-directories). Specific provider registries or network mirrors are run independently from OpenTF itself and so their own behaviors are not subject to these @@ -236,11 +236,11 @@ and of OpenTF itself. ### Module Installation Methods OpenTF supports installing child modules from a number of different -[module source types](/opentf/language/modules/sources). We will continue +[module source types](/docs/language/modules/sources). We will continue to support all of the existing source types throughout the v1.x releases. One of the supported source types is a module registry implementing -[the Module Registry Protocol](/opentf/internals/module-registry-protocol) +[the Module Registry Protocol](/docs/internals/module-registry-protocol) version 1. All OpenTF v1.x releases will remain compatible with correct implementations of that protocol. @@ -377,7 +377,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`](/opentf/cli/commands/init) +* [`init`](/docs/cli/commands/init) * `-backend=false` * `-backend-config=FILE` * `-backend-config="KEY=VALUE"` @@ -389,10 +389,10 @@ Any natural-language output from these commands might change in later releases. * `-plugin-dir=DIR` * `-reconfigure` * `-upgrade` -* [`validate`](/opentf/cli/commands/validate) +* [`validate`](/docs/cli/commands/validate) * `-json` * `-no-color` -* [`plan`](/opentf/cli/commands/plan) +* [`plan`](/docs/cli/commands/plan) * `-compact-warnings` * `-destroy` * `-detailed-exitcode` @@ -409,7 +409,7 @@ Any natural-language output from these commands might change in later releases. * `-target=ADDRESS` * `-var 'NAME=VALUE'` * `-var-file=FILE` -* [`apply`](/opentf/cli/commands/apply) +* [`apply`](/docs/cli/commands/apply) * `-auto-approve` * `-compact-warnings` * `-lock=false` @@ -424,53 +424,53 @@ Any natural-language output from these commands might change in later releases. * `-target=ADDRESS` * `-var 'NAME=VALUE'` * `-var-file=FILE` -* [`show`](/opentf/cli/commands/show) +* [`show`](/docs/cli/commands/show) * `-no-color` * `-json` * (both with and without a plan file) -* [`providers`](/opentf/cli/commands/providers) (with no subcommand) -* [`providers lock`](/opentf/cli/commands/providers/lock) +* [`providers`](/docs/cli/commands/providers) (with no subcommand) +* [`providers lock`](/docs/cli/commands/providers/lock) * `-fs-mirror=PATH` * `-net-mirror=URL` * `-platform=OS_ARCH` -* [`providers mirror`](/opentf/cli/commands/providers/mirror) +* [`providers mirror`](/docs/cli/commands/providers/mirror) * `-platform=OS_ARCH` -* [`providers schema`](/opentf/cli/commands/providers/schema) +* [`providers schema`](/docs/cli/commands/providers/schema) * `-json` -* [`fmt`](/opentf/cli/commands/fmt) +* [`fmt`](/docs/cli/commands/fmt) * `-list=false` * `-write=false` * `-diff` * `-recursive` * `-check` -* [`version`](/opentf/cli/commands/version) +* [`version`](/docs/cli/commands/version) * `-json` -* [`output`](/opentf/cli/commands/output) +* [`output`](/docs/cli/commands/output) * `-no-color` * `-json` * `-raw` -* [`taint`](/opentf/cli/commands/taint) +* [`taint`](/docs/cli/commands/taint) * `-allow-missing` * `-lock=false` * `-lock-timeout=DURATION` * `-ignore-remote-version` -* [`untaint`](/opentf/cli/commands/untaint) +* [`untaint`](/docs/cli/commands/untaint) * `-allow-missing` * `-lock=false` * `-lock-timeout=DURATION` * `-ignore-remote-version` -* [`force-unlock`](/opentf/cli/commands/force-unlock) +* [`force-unlock`](/docs/cli/commands/force-unlock) * `-force` -* [`state list`](/opentf/cli/commands/state/list) +* [`state list`](/docs/cli/commands/state/list) * `-id=ID` -* [`state pull`](/opentf/cli/commands/state/pull) -* [`state push`](/opentf/cli/commands/state/push) +* [`state pull`](/docs/cli/commands/state/pull) +* [`state push`](/docs/cli/commands/state/push) * `-force` * `-lock=false` * `-lock-timeout=DURATION` -* [`state show`](/opentf/cli/commands/state/show) +* [`state show`](/docs/cli/commands/state/show) * `-ignore-remote-version` -* [`login`](/opentf/cli/commands/login) +* [`login`](/docs/cli/commands/login) For commands or options not in the above list, we will still avoid breaking changes where possible, but can't promise full compatibility throughout the diff --git a/website/docs/language/values/index.mdx b/website/docs/language/values/index.mdx index 97ff89ed38..6f5cbe82ce 100644 --- a/website/docs/language/values/index.mdx +++ b/website/docs/language/values/index.mdx @@ -10,10 +10,10 @@ description: >- The OpenTF language includes a few kinds of blocks for requesting or publishing named values. -- [Input Variables](/opentf/language/values/variables) serve as parameters for +- [Input Variables](/docs/language/values/variables) serve as parameters for a module, so users can customize behavior without editing the source. -- [Output Values](/opentf/language/values/outputs) are like return values for a module. +- [Output Values](/docs/language/values/outputs) are like return values for a module. -- [Local Values](/opentf/language/values/locals) are a convenience feature for +- [Local Values](/docs/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.mdx index fc12960c74..b2393c6b9a 100644 --- a/website/docs/language/values/locals.mdx +++ b/website/docs/language/values/locals.mdx @@ -7,15 +7,15 @@ description: >- # Local Values -A local value assigns a name to an [expression](/opentf/language/expressions), +A local value assigns a name to an [expression](/docs/language/expressions), so you can use the name multiple times within a module instead of repeating the expression. If you're familiar with traditional programming languages, it can be useful to compare modules to function definitions: -- [Input variables](/opentf/language/values/variables) are like function arguments. -- [Output values](/opentf/language/values/outputs) are like function return values. +- [Input variables](/docs/language/values/variables) are like function arguments. +- [Output values](/docs/language/values/outputs) are like function return values. - Local values are like a function's temporary local variables. -> **Note:** For brevity, local values are often referred to as just "locals" @@ -55,7 +55,7 @@ locals { ## Using Local Values Once a local value is declared, you can reference it in -[expressions](/opentf/language/expressions) as `local.`. +[expressions](/docs/language/expressions) as `local.`. -> **Note:** Local values are _created_ by a `locals` block (plural), but you _reference_ them as attributes on an object named `local` (singular). Make sure diff --git a/website/docs/language/values/outputs.mdx b/website/docs/language/values/outputs.mdx index dadc523836..4f3c8fd4a3 100644 --- a/website/docs/language/values/outputs.mdx +++ b/website/docs/language/values/outputs.mdx @@ -15,9 +15,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 `opentf apply`. -- When using [remote state](/opentf/language/state/remote), root module outputs can be +- When using [remote state](/docs/language/state/remote), root module outputs can be accessed by other configurations via a - [`terraform_remote_state` data source](/opentf/language/state/remote-state-data). + [`terraform_remote_state` data source](/docs/language/state/remote-state-data). Resource instances managed by OpenTF each export attributes whose values can be used elsewhere in configuration. Output values are a way to expose some @@ -38,11 +38,11 @@ output "instance_ip_addr" { ``` The label immediately after the `output` keyword is the name, which must be a -valid [identifier](/opentf/language/syntax/configuration#identifiers). In a root module, this name is +valid [identifier](/docs/language/syntax/configuration#identifiers). In a root module, this name is displayed to the user; in a child module, it can be used to access the output's value. -The `value` argument takes an [expression](/opentf/language/expressions) +The `value` argument takes an [expression](/docs/language/expressions) whose result is to be returned to the user. In this example, the expression refers to the `private_ip` attribute exposed by an `aws_instance` resource defined elsewhere in this module (not shown). Any valid expression is allowed @@ -77,7 +77,7 @@ output "api_base_url" { Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations. -Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. +Refer to [Custom Condition Checks](/docs/language/expressions/custom-conditions#preconditions-and-postconditions) for more details. ## Optional Arguments @@ -164,10 +164,10 @@ Changes to Outputs: + out = (sensitive value) ``` -OpenTF will still record sensitive values in the [state](/opentf/language/state), +OpenTF will still record sensitive values in the [state](/docs/language/state), and so anyone who can access the state data will have access to the sensitive values in cleartext. For more information, see -[_Sensitive Data in State_](/opentf/language/state/sensitive-data). +[_Sensitive Data in State_](/docs/language/state/sensitive-data). @@ -183,7 +183,7 @@ correctly determine the dependencies between resources defined in different modules. Just as with -[resource dependencies](/opentf/language/resources/behavior#resource-dependencies), +[resource dependencies](/docs/language/resources/behavior#resource-dependencies), OpenTF 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.mdx index 3e9552b55f..dcb5b8bd2c 100644 --- a/website/docs/language/values/variables.mdx +++ b/website/docs/language/values/variables.mdx @@ -13,22 +13,22 @@ OpenTF 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](/opentf/language/modules), +When you declare them in [child modules](/docs/language/modules), the calling module should pass values in the `module` block. If you're familiar with traditional programming languages, it can be useful to compare modules to function definitions: * Input variables are like function arguments. -* [Output values](/opentf/language/values/outputs) are like function return values. -* [Local values](/opentf/language/values/locals) are like a function's temporary local variables. +* [Output values](/docs/language/values/outputs) are like function return values. +* [Local values](/docs/language/values/locals) are like a function's temporary local variables. -> **Note:** For brevity, input variables are often referred to as just "variables" or "OpenTF variables" when it is clear from context what sort of variable is being discussed. Other kinds of variables in OpenTF include _environment variables_ (set by the shell where OpenTF runs) and _expression variables_ (used to indirectly represent a value in an -[expression](/opentf/language/expressions)). +[expression](/docs/language/expressions)). ## Declaring an Input Variable @@ -66,11 +66,11 @@ 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](/opentf/language/syntax/configuration#identifiers) +The name of a variable can be any valid [identifier](/docs/language/syntax/configuration#identifiers) _except_ the following: `source`, `version`, `providers`, `count`, `for_each`, `lifecycle`, `depends_on`, `locals`. These names are reserved for meta-arguments in -[module configuration blocks](/opentf/language/modules/syntax), and cannot be +[module configuration blocks](/docs/language/modules/syntax), and cannot be declared as variable names. ## Arguments @@ -99,7 +99,7 @@ configuration. [inpage-type]: #type-constraints The `type` argument in a `variable` block allows you to restrict the -[type of value](/opentf/language/expressions/types) that will be accepted as +[type of value](/docs/language/expressions/types) that will be accepted as the value for a variable. If no type constraint is set then a value of any type is accepted. @@ -126,7 +126,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](/opentf/language/expressions/types). +[Type Constraints](/docs/language/expressions/types). If both the `type` and `default` arguments are specified, the given default value must be convertible to the specified type. @@ -169,7 +169,7 @@ variable "image_id" { } } ``` -Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#input-variable-validation) for more details. +Refer to [Custom Condition Checks](/docs/language/expressions/custom-conditions#input-variable-validation) for more details. ### Suppressing Values in CLI Output @@ -179,10 +179,10 @@ Setting a variable as `sensitive` prevents OpenTF from showing its value in the `plan` or `apply` output, when you use that variable elsewhere in your configuration. -OpenTF will still record sensitive values in the [state](/opentf/language/state), +OpenTF will still record sensitive values in the [state](/docs/language/state), and so anyone who can access the state data will have access to the sensitive values in cleartext. For more information, see -[_Sensitive Data in State_](/opentf/language/state/sensitive-data). +[_Sensitive Data in State_](/docs/language/state/sensitive-data). Declare a variable as sensitive by setting the `sensitive` argument to `true`: @@ -233,13 +233,13 @@ disclosing the content of one block might imply the content of a sibling block. ``` A provider can also -[declare an attribute as sensitive](/opentf/plugin/sdkv2/best-practices/sensitive-state#using-the-sensitive-flag), +[declare an attribute as sensitive](/docs/plugin/sdkv2/best-practices/sensitive-state#using-the-sensitive-flag), which will cause OpenTF to hide it from regular output regardless of how you assign it a value. For more information, see -[Sensitive Resource Attributes](/opentf/language/expressions/references#sensitive-resource-attributes). +[Sensitive Resource Attributes](/docs/language/expressions/references#sensitive-resource-attributes). If you use a sensitive value as part of an -[output value](/opentf/language/values/outputs) then OpenTF will require +[output value](/docs/language/values/outputs) then OpenTF will require you to also mark the output value itself as sensitive, to confirm that you intended to export it. @@ -297,7 +297,7 @@ 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](/opentf/language/expressions) as `var.`, +within [expressions](/docs/language/expressions) as `var.`, where `` matches the label given in the declaration block: -> **Note:** Input variables are _created_ by a `variable` block, but you @@ -326,7 +326,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_](/opentf/language/modules). +[_Modules_](/docs/language/modules). ### Variables on the Command Line @@ -342,7 +342,7 @@ opentf apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def45 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](/opentf/cli/commands/plan#input-variables-on-the-command-line). +[Input Variables on the Command Line](/docs/cli/commands/plan#input-variables-on-the-command-line). You can use the `-var` option multiple times in a single command to set several different variables. @@ -412,7 +412,7 @@ and lower case letters as in the above example. When variable values are provided in a variable definitions file, you can use OpenTF's usual syntax for -[literal expressions](/opentf/language/expressions/types#literal-expressions) +[literal expressions](/docs/language/expressions/types#literal-expressions) to assign complex-typed values, like lists and maps. Some special rules apply to the `-var` command line option and to environment @@ -438,7 +438,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](/opentf/cli/commands/plan#input-variables-on-the-command-line). +[Input Variables on the Command Line](/docs/cli/commands/plan#input-variables-on-the-command-line). ### Values for Undeclared Variables @@ -471,7 +471,7 @@ Will cause OpenTF to warn you that there is no variable declared `"mosse"`, whic 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`](/opentf/cli/commands/plan#compact-warnings) +you can use the [`-compact-warnings`](/docs/cli/commands/plan#compact-warnings) option to simplify your output. If you provide values for undeclared variables on the [command line](#variables-on-the-command-line),