From 4d665a00910f25e7ddc1f6716323ac5d8f67fef6 Mon Sep 17 00:00:00 2001 From: Kuba Martin Date: Fri, 25 Aug 2023 11:09:18 +0200 Subject: [PATCH] Update `website/docs/cli`. (#171) * Initial renaming, rewriting and cleaning up wave for the CLI docs. Signed-off-by: Jakub Martin * More renaming. Signed-off-by: Jakub Martin * More renaming. Signed-off-by: Jakub Martin * More renaming. Signed-off-by: Jakub Martin * Remove tutorial references. Signed-off-by: Jakub Martin * Post-review fixes. Signed-off-by: Jakub Martin --------- Signed-off-by: Jakub Martin --- website/docs/cli/auth/index.mdx | 29 ++- .../docs/cli/cloud/command-line-arguments.mdx | 10 +- website/docs/cli/cloud/index.mdx | 27 +-- website/docs/cli/cloud/migrating.mdx | 43 ++-- website/docs/cli/cloud/settings.mdx | 74 +++---- website/docs/cli/code/index.mdx | 36 ++-- website/docs/cli/commands/0.12upgrade.mdx | 117 ----------- website/docs/cli/commands/0.13upgrade.mdx | 89 -------- website/docs/cli/commands/apply.mdx | 79 +++---- website/docs/cli/commands/console.mdx | 34 +-- website/docs/cli/commands/destroy.mdx | 24 +-- website/docs/cli/commands/env.mdx | 6 +- website/docs/cli/commands/fmt.mdx | 34 +-- website/docs/cli/commands/force-unlock.mdx | 4 +- website/docs/cli/commands/get.mdx | 8 +- website/docs/cli/commands/graph.mdx | 16 +- website/docs/cli/commands/import.mdx | 82 ++++---- website/docs/cli/commands/index.mdx | 63 +++--- website/docs/cli/commands/init.mdx | 86 +++----- website/docs/cli/commands/login.mdx | 31 ++- website/docs/cli/commands/logout.mdx | 16 +- website/docs/cli/commands/output.mdx | 38 ++-- website/docs/cli/commands/plan.mdx | 193 ++++++++---------- website/docs/cli/commands/providers.mdx | 8 +- website/docs/cli/commands/providers/lock.mdx | 72 ++++--- .../docs/cli/commands/providers/mirror.mdx | 34 ++- .../docs/cli/commands/providers/schema.mdx | 16 +- website/docs/cli/commands/push.mdx | 14 -- website/docs/cli/commands/refresh.mdx | 37 ++-- website/docs/cli/commands/show.mdx | 30 ++- website/docs/cli/commands/state/index.mdx | 22 +- website/docs/cli/commands/state/list.mdx | 22 +- website/docs/cli/commands/state/mv.mdx | 80 ++++---- website/docs/cli/commands/state/pull.mdx | 16 +- website/docs/cli/commands/state/push.mdx | 24 +-- .../cli/commands/state/replace-provider.mdx | 24 +-- website/docs/cli/commands/state/rm.mdx | 60 +++--- website/docs/cli/commands/state/show.mdx | 36 ++-- website/docs/cli/commands/taint.mdx | 34 +-- website/docs/cli/commands/test.mdx | 4 +- website/docs/cli/commands/untaint.mdx | 38 ++-- website/docs/cli/commands/validate.mdx | 46 ++--- website/docs/cli/commands/version.mdx | 27 +-- .../docs/cli/commands/workspace/delete.mdx | 20 +- website/docs/cli/commands/workspace/index.mdx | 6 +- website/docs/cli/commands/workspace/list.mdx | 8 +- website/docs/cli/commands/workspace/new.mdx | 14 +- .../docs/cli/commands/workspace/select.mdx | 10 +- website/docs/cli/commands/workspace/show.mdx | 8 +- website/docs/cli/config/config-file.mdx | 187 +++++++---------- .../docs/cli/config/environment-variables.mdx | 60 +++--- website/docs/cli/config/index.mdx | 18 +- website/docs/cli/import/importability.mdx | 12 +- website/docs/cli/import/index.mdx | 20 +- website/docs/cli/import/usage.mdx | 37 ++-- website/docs/cli/index.mdx | 22 +- website/docs/cli/init/index.mdx | 38 ++-- website/docs/cli/inspect/index.mdx | 22 +- website/docs/cli/install/apt.mdx | 59 ++---- website/docs/cli/install/yum.mdx | 47 ++--- website/docs/cli/plugins/index.mdx | 40 ++-- website/docs/cli/plugins/signing.mdx | 10 +- website/docs/cli/run/index.mdx | 44 ++-- website/docs/cli/state/index.mdx | 26 ++- website/docs/cli/state/inspect.mdx | 12 +- website/docs/cli/state/move.mdx | 32 ++- website/docs/cli/state/recover.mdx | 14 +- .../docs/cli/state/resource-addressing.mdx | 16 +- website/docs/cli/state/taint.mdx | 38 ++-- website/docs/cli/workspaces/index.mdx | 47 ++--- 70 files changed, 1090 insertions(+), 1560 deletions(-) delete mode 100644 website/docs/cli/commands/0.12upgrade.mdx delete mode 100644 website/docs/cli/commands/0.13upgrade.mdx delete mode 100644 website/docs/cli/commands/push.mdx diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index f283418fc0..373b2f0456 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -1,31 +1,26 @@ --- -page_title: Authentication - Terraform CLI +page_title: Authentication - OpenTF CLI description: >- Documentation about the login and logout commands that help automate getting - an API token for your Terraform Cloud account. + an API token for your cloud backend account. --- # CLI Authentication -> **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](/terraform/tutorials/cloud/cloud-login?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +TACOS (TF Automation and Collaboration Software) are platforms that perform as part of their +offering OpenTF runs to provision infrastructure, offering a collaboration-focused +environment that makes it easier for teams to use OpenTF together. -[Terraform Cloud](https://cloud.hashicorp.com/products/terraform) and -[Terraform Enterprise](/terraform/enterprise) are platforms that perform -Terraform runs to provision infrastructure, offering a collaboration-focused -environment that makes it easier for teams to use Terraform together. (For -expediency, the content below refers to both products as "Terraform Cloud.") - -Terraform CLI integrates with Terraform Cloud in several ways — it can be a -front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in Terraform Cloud, -and can also use Terraform Cloud as a state backend and a private module -registry. All of these integrations require you to authenticate Terraform CLI -with your Terraform Cloud account. +OpenTF CLI integrates with TACOS in several ways — it can be a +front-end for CLI-driven runs, and can also use some TACOS as a state backend, a private module +registry, or a private provider registry. All of these integrations require you to authenticate OpenTF CLI +with your TACOS account. The best way to handle CLI authentication is with the `login` and `logout` commands, which help automate the process of getting an API token for your -Terraform Cloud user account. +TACOS user account. For details, see: -- [The `terraform login` command](/terraform/cli/commands/login) -- [The `terraform logout` command](/terraform/cli/commands/logout) +- [The `opentf login` command](/opentf/cli/commands/login) +- [The `opentf logout` command](/opentf/cli/commands/logout) diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx index 81897cfe66..531516fec9 100644 --- a/website/docs/cli/cloud/command-line-arguments.mdx +++ b/website/docs/cli/cloud/command-line-arguments.mdx @@ -6,19 +6,19 @@ description: Command Line Arguments # Command Line Arguments When your configuration includes a `cloud` block, commands that -make local modifications to Terraform state and then push them back up to the remote workspace +make local modifications to OpenTF state and then push them back up to the remote workspace accept the following option to modify that behavior: - `-ignore-remote-version` - Override checking that the local and remote - Terraform versions agree, making an operation proceed even when there is + OpenTF versions agree, making an operation proceed even when there is a mismatch. State-modification operations usually require using a local version of the - Terraform CLI that is compatible with the Terraform version selected + OpenTF CLI that is compatible with the OpenTF version selected in the remote workspace settings. This prevents the local operation from creating a new state snapshot that the workspace's remote execution environment cannot decode. We recommend against using this option unless absolutely necessary. Overriding this check can result - in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently - selected version of Terraform. + in a cloud backend workspace that is no longer able to complete remote operations with the currently + selected version of OpenTF. diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx index 51136e4cd1..2cae6e21f9 100644 --- a/website/docs/cli/cloud/index.mdx +++ b/website/docs/cli/cloud/index.mdx @@ -1,27 +1,20 @@ --- -page_title: Using Terraform Cloud - Terraform CLI +page_title: Using the Cloud Backend - OpenTF CLI description: >- - Learn how to use Terraform Cloud and Terraform Enterprise on the command line with the Terraform CLI. + Learn how to use a cloud backend on the command line with the OpenTF CLI. --- -# Using Terraform Cloud with Terraform CLI +# Using the Cloud Backend with OpenTF CLI -The Terraform CLI integration with Terraform Cloud lets you use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated. +The OpenTF CLI lets you use cloud backends on the command line. -Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/terraform/cloud-docs/run/cli). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking. +When you use the cloud backend CLI workflow, operations like `opentf plan` or `opentf apply` are remotely executed in the cloud backend's run environment by default, with log output streaming to the local terminal. This lets you use cloud backend's features within the familiar OpenTF CLI workflow. Cloud backend services may choose to implement only a subset of the available features. -> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial. - -Workspaces can also be configured for local execution, in which case Terraform Cloud only stores state. In this mode, Terraform Cloud behaves just like a standard state backend. - --> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/terraform/language/settings/backends/remote). Refer to [Migrating from the remote -backend](/terraform/cli/cloud/migrating) for details about switching to the CLI integration. +Workspaces can also be configured for local execution, in which case the cloud backend only stores state. In this mode, the cloud backend behaves just like a standard state backend. ## Documentation Summary -- [Terraform Cloud Settings](/terraform/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support. -- [Initializing and Migrating](/terraform/cli/cloud/migrating) describes - how to start using Terraform Cloud with a working directory that already has state data. -- [Command Line Arguments](/terraform/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud. - -Refer to the [CLI-driven Run Workflow](/terraform/cloud-docs/run/cli) for more details about how to use Terraform Cloud from the command line. +- [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 + 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. diff --git a/website/docs/cli/cloud/migrating.mdx b/website/docs/cli/cloud/migrating.mdx index 118fd60786..f97d94ab3a 100644 --- a/website/docs/cli/cloud/migrating.mdx +++ b/website/docs/cli/cloud/migrating.mdx @@ -1,50 +1,47 @@ --- -page_title: Initializing and Migrating to Terraform Cloud - Terraform CLI +page_title: Initializing and Migrating to a Cloud Backend - OpenTF CLI description: >- - Learn how to use the Terraform CLI to migrate local or remote state to Terraform Cloud. + Learn how to use the OpenTF CLI to migrate local or remote state to a Cloud Backend. --- # Initializing and Migrating -After [configuring Terraform Cloud settings](/terraform/cli/cloud/settings) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/terraform/cloud-docs/run/cli) for more details. +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. -When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces. +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. -1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces. +1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, OpenTF will ask if you would like to migrate that state to new cloud backend workspaces. -1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block. +1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to a cloud backend with the `remote` backend, OpenTF can continue using the same cloud backend workspaces. You will need to switch the `remote` backend block to the `cloud` block. ## Migrating from Local State or State Backends -> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial. - If the working directory already has state data available (using either local state or a [state -backend](/terraform/language/settings/backends/configuration)), Terraform asks your approval to migrate -that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles +backend](/opentf/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. -Terraform may also prompt you to rename your workspaces during the migration, to either give a name to -the unnamed `default` workspace (Terraform Cloud requires all workspaces to have a name) or give -your workspace names more contextual information. Unlike Terraform CLI-only workspaces, which represent +OpenTF may also prompt you to rename your workspaces during the migration, to either give a name to +the unnamed `default` workspace (the cloud backend requires all workspaces to have a name) or give +your workspace names more contextual information. Unlike OpenTF CLI-only workspaces, which represent multiple environments associated with the same configuration (e.g. production, staging, development), -Terraform Cloud workspaces can represent totally independent configurations, and must have unique names within the Terraform Cloud organization. +cloud backend workspaces can represent totally independent configurations, and must have unique names within the cloud backend organization. -Because of this, Terraform will prompt you to rename the working directory's workspaces +Because of this, OpenTF will prompt you to rename the working directory's workspaces according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is `--` (e.g., `networking-prod-us-east`, -`networking-staging-us-east`). Refer to [Workspace -Naming](/terraform/cloud-docs/workspaces/naming) in the Terraform Cloud documentation for more detail. +`networking-staging-us-east`). ## Migrating from the `remote` Backend -If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names. +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](/terraform/language/settings/backends/remote) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/terraform/cloud-docs/run/cli) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements. +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. ### Block Replacement -When switching from the `remote` backend to a `cloud` block, Terraform will continue using the same -set of Terraform Cloud workspaces. Replace your `backend "remote"` block with an equivalent `cloud` +When switching from the `remote` backend to a `cloud` block, OpenTF will continue using the same +set of cloud backend workspaces. Replace your `backend "remote"` block with an equivalent `cloud` block. #### Single Workspace @@ -69,7 +66,7 @@ terraform { If you were using multiple workspaces with the `prefix` argument, replace it with a `cloud` block that uses the `tags` argument. You may specify any number of tags to distinguish the workspaces for your working directory, but a good starting point may be to use whatever the prefix was before. -The tags you configure do not need to be present on the existing workspaces. When you initialize, Terraform will add the specified tags to the workspaces if necessary. +The tags you configure do not need to be present on the existing workspaces. When you initialize, OpenTF will add the specified tags to the workspaces if necessary. ```diff terraform { @@ -85,4 +82,4 @@ terraform { } ``` -~> **Warning**: Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the Terraform CLI. For example, rather than `terraform workspace select prod`, you must run the command `terraform workspace select my-app-prod`. +~> **Warning**: Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the OpenTF CLI. For example, rather than `opentf workspace select prod`, you must run the command `opentf workspace select my-app-prod`. diff --git a/website/docs/cli/cloud/settings.mdx b/website/docs/cli/cloud/settings.mdx index 0c10dbb375..f64d370ad6 100644 --- a/website/docs/cli/cloud/settings.mdx +++ b/website/docs/cli/cloud/settings.mdx @@ -1,38 +1,35 @@ --- -page_title: Terraform Cloud Settings - Terraform CLI +page_title: Cloud Backend Settings - OpenTF CLI description: >- - Configure the Terraform Cloud CLI integration. + Configure the Cloud Backend CLI integration. --- -# Terraform Cloud Settings +# Cloud Backend Settings -Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's -[CLI-driven run workflow](/terraform/cloud-docs/run/cli). +OpenTF CLI can integrate with a cloud backend, acting as a client for it. -> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial. +You must configure the following settings to use the cloud backend for a particular working directory: -You must configure the following settings to use Terraform Cloud for a particular working directory: - -- Provide credentials to access Terraform Cloud, preferably by using the - [`terraform login`](/terraform/cli/commands/login) command. -- Add a `cloud` block to the directory's Terraform configuration, to specify +- Provide credentials to access the cloud backend, preferably by using the + [`opentf login`](/opentf/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 - uploaded with the Terraform configuration when running plans and applies. + uploaded with the OpenTF configuration when running plans and applies. -After adding or changing a `cloud` block, you must run `terraform init`. +After adding or changing a `cloud` block, you must run `opentf init`. ## The `cloud` Block The `cloud` block is a nested block within the top-level `terraform` settings -block. It specifies which Terraform Cloud workspaces to use for the current +block. It specifies which cloud backend workspaces to use for the current working directory. ```hcl terraform { cloud { organization = "my-org" - hostname = "app.terraform.io" # Optional; defaults to app.terraform.io + hostname = "app.example.org" # Optional; defaults to app.terraform.io workspaces { project = "networking-development" @@ -45,12 +42,12 @@ 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](/terraform/language/settings/backends/configuration). +- A `cloud` block cannot be used with [state backends](/opentf/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). -The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration +The `cloud` block only affects OpenTF CLI's behavior. When the cloud backend uses a configuration that contains a cloud block - for example, when a workspace is configured to use a VCS provider directly - it ignores the block and behaves according to its own workspace settings. @@ -61,56 +58,53 @@ The `cloud` block supports the following configuration arguments: - `organization` - (Required) The name of the organization containing the workspace(s) the current configuration should use. -- `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to +- `workspaces` - (Required) A nested block that specifies which remote cloud backend workspaces to use for the current configuration. The `workspaces` block must contain **exactly one** of the following arguments, each denoting a strategy for how workspaces should be mapped: - - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use + - `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 `terraform workspace` commands](/terraform/cli/workspaces) + and can use [the `opentf workspace` commands](/opentf/cli/workspaces) to switch between them or create new workspaces. New workspaces will automatically have the specified tags. This option conflicts with `name`. - - `name` - (Optional) The name of a single Terraform Cloud workspace. You will + - `name` - (Optional) The name of a single cloud backend workspace. You will only be able to use the workspace specified in the configuration with this working - directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or - `terraform workspace new`). This option conflicts with `tags`. + directory, and cannot manage workspaces from the CLI (e.g. `opentf workspace select` or + `opentf workspace new`). This option conflicts with `tags`. - - `project` - (Optional) The name of a Terraform Cloud project. Workspaces that need created will - will be created within this project. `terraform workspace list` will be filtered by workspaces + - `project` - (Optional) The name of a cloud backend project. Workspaces that need created will + will be created within this project. `opentf workspace list` will be filtered by workspaces in the supplied project. -- `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform - Enterprise. Defaults to Terraform Cloud (app.terraform.io). +- `hostname` - (Optional) The hostname of the cloud backend. -- `token` - (Optional) The token used to authenticate with Terraform Cloud. +- `token` - (Optional) The token used to authenticate with the cloud backend. We recommend omitting the token from the configuration, and instead using - [`terraform login`](/terraform/cli/commands/login) or manually configuring + [`opentf login`](/opentf/cli/commands/login) or manually configuring `credentials` in the - [CLI config file](/terraform/cli/config/config-file#credentials). + [CLI config file](/opentf/cli/config/config-file#credentials). ### Environment Variables --> **Note:** CLI integration environment variables are supported in Terraform v1.2.0 and later. +You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure OpenTF as part of a Continuous Integration (CI) pipeline. OpenTF only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file. -You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure Terraform as part of a Continuous Integration (CI) pipeline. Terraform only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file. - -~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Refer to [Non-Interactive Workflows](/terraform/cloud-docs/run/cli#non-interactive-workflows) for details. +~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. Use the following environment variables to configure the `cloud` block: -- `TF_CLOUD_ORGANIZATION` - The name of the organization. Terraform reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence. +- `TF_CLOUD_ORGANIZATION` - The name of the organization. OpenTF reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence. -- `TF_CLOUD_HOSTNAME` - The hostname of a Terraform Enterprise installation. Terraform reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence. +- `TF_CLOUD_HOSTNAME` - The hostname of the cloud backend. OpenTF reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence. -- `TF_CLOUD_PROJECT` - The name of a Terraform Cloud project. Terraform reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence. +- `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 Terraform Cloud workspace. Terraform reads this when `workspaces` is omitted from the `cloud` block. Terraform Cloud will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/terraform/cli/config/environment-variables#tf_workspace) for details. +- `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. ## Excluding Files from Upload with .terraformignore -When executing a remote `plan` or `apply` in a [CLI-driven run](/terraform/cloud-docs/run/cli), -a copy of your configuration directory is uploaded to Terraform Cloud. You can define +When executing a remote `plan` or `apply` in a CLI-driven run, +a copy of your configuration directory is uploaded to the cloud backend. You can define paths to exclude from upload by adding a `.terraformignore` file at the root of your configuration directory. If this file is not present, the upload will exclude the following by default: diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 714f94227e..59860f4aef 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -1,44 +1,34 @@ --- -page_title: Writing and Modifying Code - Terraform CLI +page_title: Writing and Modifying Code - OpenTF CLI description: >- Learn commands that help validate, format, and upgrade code written in the - Terraform Configuration Language. + OpenTF Configuration Language. --- -# Writing and Modifying Terraform Code +# Writing and Modifying OpenTF Code -The [Terraform language](/terraform/language) is Terraform's primary -user interface, and all of Terraform's workflows rely on configurations written -in the Terraform language. +The [OpenTF language](/opentf/language) is OpenTF's primary +user interface, and all of OpenTF's workflows rely on configurations written +in the OpenTF language. -Terraform CLI includes several commands to make Terraform code more convenient +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 `terraform console` command](/terraform/cli/commands/console) starts an - interactive shell for evaluating Terraform - [expressions](/terraform/language/expressions), which can be a faster way +- [The `opentf console` command](/opentf/cli/commands/console) starts an + interactive shell for evaluating OpenTF + [expressions](/opentf/language/expressions), which can be a faster way to verify that a particular resource argument results in the value you expect. -- [The `terraform fmt` command](/terraform/cli/commands/fmt) rewrites Terraform +- [The `opentf fmt` command](/opentf/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 `terraform validate` command](/terraform/cli/commands/validate) validates the - syntax and arguments of the Terraform configuration files in a directory, +- [The `opentf validate` command](/opentf/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 performing any other work, so `validate` isn't a crucial part of the core workflow, but it can be very useful as a pre-commit hook or as part of a continuous integration pipeline. - -- [The `0.13upgrade` command](/terraform/cli/commands/0.13upgrade) and - [the `0.12upgrade` command](/terraform/cli/commands/0.12upgrade) can automatically - modify the configuration files in a Terraform module to help deal with major - syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both - of these commands are only available in the Terraform version they are - associated with, and you are expected to upgrade older code to be compatible - with 0.12 before attempting to make it compatible with 0.13. For more detailed - information about updating code for new Terraform versions, see the [upgrade - guides](/terraform/language/upgrade-guides) in the Terraform language docs. diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.mdx deleted file mode 100644 index eb4acc2a2a..0000000000 --- a/website/docs/cli/commands/0.12upgrade.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -page_title: 'Command: 0.12upgrade' -description: >- - The 0.12upgrade subcommand automatically rewrites existing configurations for - Terraform 0.12 compatibility. ---- - -# Command: 0.12upgrade - -The `terraform 0.12upgrade` command applies several automatic upgrade rules to -help prepare a module that was written for Terraform v0.11 to be used -with Terraform v0.12. - --> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12). - -## Usage - -Usage: `terraform 0.12upgrade [options] [dir]` - -By default, `0.12upgrade` changes configuration files in the current working -directory. However, you can provide an explicit path to another directory if -desired, which may be useful for automating migrations of several modules in -the same repository. - -When run with no other options, the command will first explain what it is -going to do and prompt for confirmation: - -``` -$ terraform 0.12upgrade - -This command will rewrite the configuration files in the given directory so -that they use the new syntax features from Terraform v0.12, and will identify -any constructs that may need to be adjusted for correct operation with -Terraform v0.12. - -We recommend using this command in a clean version control work tree, so that -you can easily see the proposed changes as a diff against the latest commit. -If you have uncommitted changes already present, we recommend aborting this -command and dealing with them before running this command again. - -Would you like to upgrade the module in the current directory? - Only 'yes' will be accepted to confirm. - - Enter a value: yes -``` - -The `0.12upgrade` subcommand requires access to providers used in the -configuration in order to analyze their resource types, so it's important to -run `terraform init` first to install these. In some rare cases, a configuration -that worked in v0.11 may have syntax errors in v0.12, in which case -`terraform init` will run in a special mode where it installs only enough to -run the upgrade command, after which you can run `terraform init` again to -complete initialization. - -Many of the rewrite rules are completely automatic, but in some cases the -tool cannot determine enough information from the configuration alone to make -a decision, and so it will instead add a comment to the configuration for -user review. All such comments contain the string `TF-UPGRADE-TODO` to make -them easier to find. - -After upgrading, the configuration will also be reformatted into the standard -Terraform style and expressions rewritten to use the more-readable v0.12 syntax -features. - -We recommend running this command with a clean version control work tree so -that you can use VCS tools to review the proposed changes, including any -`TF-UPGRADE-TODO` comments, and make any revisions required before committing -the change. - -Once upgraded the configuration will no longer be compatible with Terraform -v0.11 and earlier. When upgrading a shared module that is called from multiple -configurations, you may need to -[fix existing configurations to a previous version](/terraform/language/modules/syntax#version) -to allow for a gradual upgrade. If the module is published via -[a Terraform registry](/terraform/registry), assign a new _major_ version number -to the upgraded module source to represent the fact that this is a breaking -change for v0.11 callers. If a module is installed directly from a version -control system such as Git, -[use specific revisions](/terraform/language/modules/sources#selecting-a-revision) -to control which version is used by which caller. - -The command-line options are all optional. The available options are: - -* `-yes` - Skip the initial introduction messages and interactive confirmation. - Use this when running the command in batch from a script. - -* `-force` - Override the heuristic that attempts to detect if a configuration - is already written for v0.12 or later. Some of the transformations made by - this command are not idempotent, so re-running against the same module may - change the meanings of some expressions in the module. - -## Batch Usage - -After you've experimented with the `0.12upgrade` command in some confined -situations, if you have a repository containing multiple modules you may -wish to batch-upgrade them all and review them together. Recursive upgrades -are not supported by the tool itself, but if you are on a Unix-style system -you can achieve this using the `find` command as follows: - -``` -find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes -``` - -On Mac OS X, the `find` included with the system does not support the `-printf` argument. You can install GNU find using Homebrew in order to use that argument: - -``` -brew install findutils -``` - -Once installed, run the above command line using `gfind` instead of `find`. - -Note that the above includes the `-yes` option to override the interactive -prompt, so be sure you have a clean work tree before running it. - -Because upgrading requires access to the configuration's provider plugins, -all of the directories must be initialized with `terraform init` prior to -running the above. diff --git a/website/docs/cli/commands/0.13upgrade.mdx b/website/docs/cli/commands/0.13upgrade.mdx deleted file mode 100644 index 51c5f45150..0000000000 --- a/website/docs/cli/commands/0.13upgrade.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -page_title: 'Command: 0.13upgrade' -description: >- - The 0.13upgrade subcommand updates existing configurations to use the new - provider source features from Terraform 0.13. ---- - -# Command: 0.13upgrade - -The `terraform 0.13upgrade` command updates existing configuration to add an -explicit `source` attribute for each provider used in a given module. The -provider source settings are stored in a `required_providers` block. - --> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-13). - -## Usage - -Usage: `terraform 0.13upgrade [options] [dir]` - -The primary purpose of the `0.13upgrade` command is to determine which -providers are in use for a module, detect the source address for those -providers where possible, and record this information in a -[`required_providers` block][required-providers]. - -[required-providers]: /terraform/language/providers/requirements - -~> Note: the command ignores `.tf.json` files and override files in the module. - -If the module already has a `required_providers` block, the command updates it -in-place. Otherwise, a new block is added to the `versions.tf` file. - -By default, `0.13upgrade` changes configuration files in the current working -directory. However, you can provide an explicit path to another directory if -desired, which may be useful for automating migrations of several modules in -the same repository. - -When run with no other options, the command will first explain what it is -going to do and prompt for confirmation: - -``` -$ terraform 0.13upgrade - -This command will update the configuration files in the given directory to use -the new provider source features from Terraform v0.13. It will also highlight -any providers for which the source cannot be detected, and advise how to -proceed. - -We recommend using this command in a clean version control work tree, so that -you can easily see the proposed changes as a diff against the latest commit. -If you have uncommited changes already present, we recommend aborting this -command and dealing with them before running this command again. - -Would you like to upgrade the module in the current directory? - Only 'yes' will be accepted to confirm. - - Enter a value: yes -``` - -We recommend running this command with a clean version control work tree so -that you can use VCS tools to review the proposed changes, including any -`TF-UPGRADE-TODO` comments, and make any revisions required before committing -the change. - -There is one command-line option: - -* `-yes` - Skip the initial introduction messages and interactive confirmation. - Use this when running the command in batch from a script. - -## Batch Usage - -After you've experimented with the `0.13upgrade` command in some confined -situations, if you have a repository containing multiple modules you may -wish to batch-upgrade them all and review them together. Recursive upgrades -are not supported by the tool itself, but if you are on a Unix-style system -you can achieve this using the `find` command as follows: - -``` -$ find . -name '*.tf' | xargs -n1 dirname | uniq | xargs -n1 terraform 0.13upgrade -yes -``` - -On a Windows system with PowerShell, you can use this command: - -``` -Get-Childitem -Recurse -Include *.tf | Split-Path | ` -Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName } -``` - -Note that the above commands include the `-yes` option to override the -interactive prompt, so be sure you have a clean work tree before running it. diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index 641b09eba0..6e3c7a7b13 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -1,48 +1,46 @@ --- page_title: 'Command: apply' description: >- - The terraform apply command executes the actions proposed in a Terraform plan + The opentf apply command executes the actions proposed in a OpenTF plan to create, update, or destroy infrastructure. --- # Command: apply -The `terraform apply` command executes the actions proposed in a Terraform +The `opentf apply` command executes the actions proposed in a OpenTF plan. -> **Hands On:** Try the [Apply Terraform Configuration](/terraform/tutorials/cli/apply?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial to learn how Terraform applies a configuration, how Terraform recovers from errors during apply, and common ways to use this command. - ## Usage -Usage: `terraform apply [options] [plan file]` +Usage: `opentf apply [options] [plan file]` ### Automatic Plan Mode -When you run `terraform apply` without passing a saved plan file, Terraform automatically creates a new execution plan as if you had run [`terraform plan`](/terraform/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/terraform/cli/commands/plan#planning-modes) and -[planning options](/terraform/cli/commands/plan#planning-options) to customize how Terraform 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`](/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. -You can pass the `-auto-approve` option to instruct Terraform to apply the plan without asking for confirmation. +You can pass the `-auto-approve` option to instruct OpenTF to apply the plan without asking for confirmation. -!> **Warning:** If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your Terraform workflow. This minimizes the risk of unpredictable changes and configuration drift. +!> **Warning:** If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your OpenTF workflow. This minimizes the risk of unpredictable changes and configuration drift. ### Saved Plan Mode -When you pass a [saved plan file](/terraform/cli/commands/plan#out-filename) to `terraform apply`, Terraform takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when [running Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). +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. -Use [`terraform show`](/terraform/cli/commands/show) to inspect a saved plan file before applying it. +Use [`opentf show`](/opentf/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 Terraform's decisions about which +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 decisions. ### Plan Options -Without a saved plan file, `terraform apply` supports all planning modes and planning options available for `terraform plan`. +Without a saved plan file, `opentf apply` supports all planning modes and planning options available for `opentf plan`. -- **[Planning Modes](/terraform/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update Terraform state and root module output values. -- **[Planning Options](/terraform/cli/commands/plan#planning-options):** These include specifying which resource instances Terraform should replace, setting Terraform input variables, etc. +- **[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. ### Apply Options @@ -50,7 +48,7 @@ The following options change how the apply command executes and reports on the a - `-auto-approve` - Skips interactive approval of plan before applying. This option is ignored when you pass a previously-saved plan file, because - Terraform considers you passing the plan file as the approval and so + OpenTF considers you passing the plan file as the approval and so will never prompt in that case. - `-compact-warnings` - Shows any warning messages in a compact form which @@ -58,63 +56,48 @@ The following options change how the apply command executes and reports on the a at least one error and thus the warning text might be useful context for the errors. -- `-input=false` - Disables all of Terraform's interactive prompts. Note that - this also prevents Terraform from prompting for interactive approval of a - plan, so Terraform will conservatively assume that you do not wish to - apply the plan, causing the operation to fail. If you wish to run Terraform - in a non-interactive context, see - [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) for some - different approaches. +- `-input=false` - Disables all of OpenTF's interactive prompts. Note that + this also prevents OpenTF from prompting for interactive approval of a + plan, so OpenTF will conservatively assume that you do not wish to + apply the plan, causing the operation to fail. - `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output. This implies `-input=false`, so the configuration must have no unassigned variable values to continue. To enable this flag, you must also either enable the `-auto-approve` flag or specify a previously-saved plan. - [machine-readable-ui]: /terraform/internals/machine-readable-ui + [machine-readable-ui]: /opentf/internals/machine-readable-ui - `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - instructs Terraform to retry acquiring a lock for a period of time before + instructs OpenTF to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. - `-no-color` - Disables terminal formatting sequences in the output. Use this - if you are running Terraform in a context where its output will be + if you are running OpenTF in a context where its output will be rendered by a system that cannot interpret terminal formatting. -- `-parallelism=n` - Limit the number of concurrent operation as Terraform - [walks the graph](/terraform/internals/graph#walking-the-graph). Defaults to +- `-parallelism=n` - Limit the number of concurrent operation as OpenTF + [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults to 10\. -- All [planning modes](/terraform/cli/commands/plan#planning-modes) and -[planning options](/terraform/cli/commands/plan#planning-options) for -`terraform plan` - Customize how Terraform will create the plan. Only available when you run `terraform apply` without a saved plan file. +- All [planning modes](/opentf/cli/commands/plan#planning-modes) and +[planning options](/opentf/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](/terraform/language/settings/backends/local) only, -`terraform apply` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` backend](/opentf/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). ## Passing a Different Configuration Directory -Terraform v0.13 and earlier also accepted a directory path in place of the -plan file argument to `terraform apply`, in which case Terraform would use -that directory as the root module instead of the current working directory. - -That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir) -instead, which works across all commands and makes Terraform consistently look +[the `-chdir` global option](/opentf/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. - -If your previous use of this legacy pattern was also relying on Terraform -writing the `.terraform` subdirectory into the current working directory even -though the root module directory was overridden, use -[the `TF_DATA_DIR` environment variable](/terraform/cli/config/environment-variables#tf_data_dir) -to direct Terraform to write the `.terraform` directory to a location other -than the current working directory. diff --git a/website/docs/cli/commands/console.mdx b/website/docs/cli/commands/console.mdx index ca8a0bae20..1d469757d7 100644 --- a/website/docs/cli/commands/console.mdx +++ b/website/docs/cli/commands/console.mdx @@ -1,44 +1,44 @@ --- page_title: 'Command: console' description: >- - The terraform console command provides an interactive console for evaluating + The opentf console command provides an interactive console for evaluating expressions. --- # Command: console -The `terraform console` command provides an interactive console for -evaluating [expressions](/terraform/language/expressions). +The `opentf console` command provides an interactive console for +evaluating [expressions](/opentf/language/expressions). ## Usage -Usage: `terraform console [options]` +Usage: `opentf console [options]` This command provides an interactive command-line console for evaluating and -experimenting with [expressions](/terraform/language/expressions). +experimenting with [expressions](/opentf/language/expressions). You can use it to test interpolations before using them in configurations and to interact with any values currently saved in -[state](/terraform/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](/terraform/language/functions). The console holds a [lock on the state](/terraform/language/state/locking), and you will not be able to use the console while performing other actions that modify state. +[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. To close the console, enter the `exit` command or press Control-C or Control-D. For configurations using -[the `local` backend](/terraform/language/settings/backends/local) only, -`terraform console` accepts the legacy command line option -[`-state`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` backend](/opentf/language/settings/backends/local) only, +`opentf console` accepts the legacy command line option +[`-state`](/opentf/language/settings/backends/local#command-line-arguments). ## Scripting -The `terraform console` command can be used in non-interactive scripts +The `opentf console` command can be used in non-interactive scripts by piping newline-separated commands to it. Only the output from the final command is printed unless an error occurs earlier. For example: ```shell -$ echo 'split(",", "foo,bar,baz")' | terraform console +$ echo 'split(",", "foo,bar,baz")' | opentf console tolist([ "foo", "bar", @@ -48,14 +48,14 @@ tolist([ ## Remote State -If [remote state](/terraform/language/state/remote) is used by the current backend, -Terraform will read the state for the current workspace from the backend +If [remote state](/opentf/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. ## Examples -The `terraform console` command will read the Terraform configuration in the -current working directory and the Terraform state file from the configured +The `opentf console` command will read the OpenTF configuration in the +current working directory and the OpenTF state file from the configured backend so that interpolations can be tested against both the values in the configuration and the state file. @@ -82,7 +82,7 @@ resource "random_pet" "example" { } ``` -Executing `terraform console` will drop you into an interactive shell where you +Executing `opentf console` will drop you into an interactive shell where you can test interpolations to: Print a value from a map: diff --git a/website/docs/cli/commands/destroy.mdx b/website/docs/cli/commands/destroy.mdx index a0d8713dab..841db0b455 100644 --- a/website/docs/cli/commands/destroy.mdx +++ b/website/docs/cli/commands/destroy.mdx @@ -1,33 +1,33 @@ --- page_title: 'Command: destroy' description: >- - The terraform destroy command destroys all objects managed by a Terraform + The opentf destroy command destroys all objects managed by a OpenTF configuration. --- # Command: destroy -The `terraform destroy` command is a convenient way to destroy all remote -objects managed by a particular Terraform configuration. +The `opentf destroy` command is a convenient way to destroy all remote +objects managed by a particular OpenTF configuration. While you will typically not want to destroy long-lived objects in a production -environment, Terraform is sometimes used to manage ephemeral infrastructure -for development purposes, in which case you can use `terraform destroy` to +environment, OpenTF is sometimes used to manage ephemeral infrastructure +for development purposes, in which case you can use `opentf destroy` to conveniently clean up all of those temporary objects once you are finished with your work. ## Usage -Usage: `terraform destroy [options]` +Usage: `opentf destroy [options]` This command is just a convenience alias for the following command: ``` -terraform apply -destroy +opentf apply -destroy ``` For that reason, this command accepts most of the options that -[`terraform apply`](/terraform/cli/commands/apply) accepts, although it does +[`opentf apply`](/opentf/cli/commands/apply) accepts, although it does not accept a plan file argument and forces the selection of the "destroy" planning mode. @@ -35,12 +35,8 @@ You can also create a speculative destroy plan, to see what the effect of destroying would be, by running the following command: ``` -terraform plan -destroy +opentf plan -destroy ``` -This will run [`terraform plan`](/terraform/cli/commands/plan) in _destroy_ mode, showing +This will run [`opentf plan`](/opentf/cli/commands/plan) in _destroy_ mode, showing you the proposed destroy changes without executing them. - --> **Note:** The `-destroy` option to `terraform apply` exists only in -Terraform v0.15.2 and later. For earlier versions, you _must_ use -`terraform destroy` to get the effect of `terraform apply -destroy`. diff --git a/website/docs/cli/commands/env.mdx b/website/docs/cli/commands/env.mdx index bb98c9fd15..da52258c3f 100644 --- a/website/docs/cli/commands/env.mdx +++ b/website/docs/cli/commands/env.mdx @@ -1,12 +1,12 @@ --- page_title: 'Command: env' description: >- - The terraform env command is a deprecated form of the terraform workspace + The opentf env command is a deprecated form of the opentf workspace command. --- # Command: env -The `terraform env` command is deprecated. -[The `terraform workspace` command](/terraform/cli/commands/workspace) +The `opentf env` command is deprecated. +[The `opentf workspace` command](/opentf/cli/commands/workspace) should be used instead. diff --git a/website/docs/cli/commands/fmt.mdx b/website/docs/cli/commands/fmt.mdx index 4b2661ad2a..944ae5daef 100644 --- a/website/docs/cli/commands/fmt.mdx +++ b/website/docs/cli/commands/fmt.mdx @@ -1,51 +1,51 @@ --- page_title: 'Command: fmt' description: >- - The terraform fmt command rewrites configuration files to a canonical format + The opentf fmt command rewrites configuration files to a canonical format and style. --- # Command: fmt -The `terraform fmt` command is used to rewrite Terraform configuration files +The `opentf fmt` command is used to rewrite OpenTF configuration files to a canonical format and style. This command applies a subset of -the [Terraform language style conventions](/terraform/language/syntax/style), +the [OpenTF language style conventions](/opentf/language/syntax/style), along with other minor adjustments for readability. -Other Terraform commands that generate Terraform configuration will produce -configuration files that conform to the style imposed by `terraform fmt`, so +Other OpenTF commands that generate OpenTF configuration will produce +configuration files that conform to the style imposed by `opentf fmt`, so using this style in your own files will ensure consistency. -The canonical format may change in minor ways between Terraform versions, so -after upgrading Terraform we recommend to proactively run `terraform fmt` +The canonical format may change in minor ways between OpenTF versions, so +after upgrading OpenTF we recommend to proactively run `opentf fmt` on your modules along with any other changes you are making to adopt the new version. -We don't consider new formatting rules in `terraform fmt` to be a breaking -change in new versions of Terraform, but we do aim to minimize changes for +We don't consider new formatting rules in `opentf fmt` to be a breaking +change in new versions of OpenTF, but we do aim to minimize changes for configurations that are already following the style examples shown in the -Terraform documentation. When adding new formatting rules, they will usually +OpenTF documentation. When adding new formatting rules, they will usually aim to apply more of the rules already shown in the configuration examples in the documentation, and so we recommend following the documented style even -for decisions that `terraform fmt` doesn't yet apply automatically. +for decisions that `opentf fmt` doesn't yet apply automatically. Formatting decisions are always subjective and so you might disagree with the -decisions that `terraform fmt` makes. This command is intentionally opinionated +decisions that `opentf fmt` makes. This command is intentionally opinionated and has no customization options because its primary goal is to encourage -consistency of style between different Terraform codebases, even though the +consistency of style between different OpenTF codebases, even though the chosen style can never be everyone's favorite. -We recommend that you follow the style conventions applied by `terraform fmt` -when writing Terraform modules, but if you find the results particularly +We recommend that you follow the style conventions applied by `opentf fmt` +when writing OpenTF modules, but if you find the results particularly objectionable then you may choose not to use this command, and possibly choose to use a third-party formatting tool instead. If you choose to use a third-party tool then you should also run it on files that are generated -automatically by Terraform, to get consistency between your hand-written files +automatically by OpenTF, to get consistency between your hand-written files and the generated files. ## Usage -Usage: `terraform fmt [options] [target...]` +Usage: `opentf fmt [options] [target...]` By default, `fmt` scans the current directory for configuration files. If you provide a directory for the `target` argument, then `fmt` will scan that diff --git a/website/docs/cli/commands/force-unlock.mdx b/website/docs/cli/commands/force-unlock.mdx index 705d04427a..f95664f333 100644 --- a/website/docs/cli/commands/force-unlock.mdx +++ b/website/docs/cli/commands/force-unlock.mdx @@ -1,7 +1,7 @@ --- page_title: 'Command: force-unlock' description: >- - The terraform force-unlock command unlocks the state for a configuration. It + The opentf force-unlock command unlocks the state for a configuration. It does not modify your infrastructure. --- @@ -16,7 +16,7 @@ process. ## Usage -Usage: `terraform force-unlock [options] LOCK_ID` +Usage: `opentf force-unlock [options] LOCK_ID` Manually unlock the state for the defined configuration. diff --git a/website/docs/cli/commands/get.mdx b/website/docs/cli/commands/get.mdx index f46b8776b9..0a50c72662 100644 --- a/website/docs/cli/commands/get.mdx +++ b/website/docs/cli/commands/get.mdx @@ -1,16 +1,16 @@ --- page_title: 'Command: get' -description: The terraform get command downloads and updates modules. +description: The opentf get command downloads and updates modules. --- # Command: get -The `terraform get` command is used to download and update -[modules](/terraform/language/modules/develop) mentioned in the root module. +The `opentf get` command is used to download and update +[modules](/opentf/language/modules/develop) mentioned in the root module. ## Usage -Usage: `terraform get [options]` +Usage: `opentf get [options]` The modules are downloaded into a `.terraform` subdirectory of the current working directory. Don't commit this directory to your version control diff --git a/website/docs/cli/commands/graph.mdx b/website/docs/cli/commands/graph.mdx index 9f59ee564b..a3cba56dbe 100644 --- a/website/docs/cli/commands/graph.mdx +++ b/website/docs/cli/commands/graph.mdx @@ -1,29 +1,29 @@ --- page_title: 'Command: graph' description: >- - The terraform graph command generates a visual representation of a + The opentf graph command generates a visual representation of a configuration or execution plan that you can use to generate charts. --- # Command: graph -The `terraform graph` command is used to generate a visual +The `opentf graph` command is used to generate a visual representation of either a configuration or execution plan. The output is in the DOT format, which can be used by [GraphViz](http://www.graphviz.org) to generate charts. ## Usage -Usage: `terraform graph [options]` +Usage: `opentf graph [options]` -Outputs the visual execution graph of Terraform resources according to +Outputs the visual execution graph of OpenTF resources according to either the current configuration or an execution plan. The graph is outputted in DOT format. The typical program that can read this format is GraphViz, but many web services are also available to read this format. -The `-type` flag can be used to control the type of graph shown. Terraform +The `-type` flag can be used to control the type of graph shown. OpenTF creates different graphs for different operations. See the options below for the list of types supported. The default type is "plan" if a configuration is given, and "apply" if a plan file is passed as an @@ -39,17 +39,17 @@ Options: * `-type=plan` - Type of graph to output. Can be: `plan`, `plan-refresh-only`, `plan-destroy`, or `apply`. -* `-module-depth=n` - (deprecated) In prior versions of Terraform, specified the +* `-module-depth=n` - (deprecated) In prior versions of OpenTF, specified the depth of modules to show in the output. ## Generating Images -The output of `terraform graph` is in the DOT format, which can +The output of `opentf graph` is in the DOT format, which can easily be converted to an image by making use of `dot` provided by GraphViz: ```shellsession -$ terraform graph | dot -Tsvg > graph.svg +$ opentf graph | dot -Tsvg > graph.svg ``` Here is an example graph output: diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx index f9ffd3de77..387ac02a9e 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.mdx @@ -1,23 +1,21 @@ --- page_title: 'Command: import' -description: The terraform import command brings existing resources into Terraform state. +description: The opentf import command brings existing resources into OpenTF state. --- # Command: import -> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. - -The `terraform import` command [imports existing resources](/terraform/cli/import) -into Terraform. +The `opentf import` command [imports existing resources](/opentf/cli/import) +into OpenTF. ## Usage -Usage: `terraform import [options] ADDRESS ID` +Usage: `opentf import [options] ADDRESS ID` -Import will find the existing resource from ID and import it into your Terraform +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](/terraform/cli/state/resource-addressing). +ADDRESS must be a valid [resource address](/opentf/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. @@ -27,19 +25,19 @@ it is the zone ID (`Z12ABC4UGMOZ2N`). Please reference the provider documentatio on the ID format. If you're unsure, feel free to just try an ID. If the ID is invalid, you'll just receive an error message. -~> Warning: Terraform expects that each remote object it is managing will be -bound to only one resource address, which is normally guaranteed by Terraform -itself having created all objects. If you import existing objects into Terraform, -be careful to import each remote object to only one Terraform resource address. -If you import the same object multiple times, Terraform may exhibit unwanted +~> Warning: OpenTF expects that each remote object it is managing will be +bound to only one resource address, which is normally guaranteed by OpenTF +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](/terraform/language/state). +[the State section](/opentf/language/state). The command-line flags are all optional. The following flags are available: -- `-config=path` - Path to directory of Terraform configuration files that +- `-config=path` - Path to directory of OpenTF configuration files that configure the provider for import. This defaults to your working directory. - If this directory contains no Terraform configuration files, the provider + If this directory contains no OpenTF configuration files, the provider must be configured via manual input or environmental variables. - `-input=true` - Whether to ask for input for provider configuration. @@ -52,21 +50,21 @@ 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 Terraform - [walks the graph](/terraform/internals/graph#walking-the-graph). Defaults +- `-parallelism=n` - Limit the number of concurrent operation as OpenTF + [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults to 10. - `-provider=provider` - **Deprecated** Override the provider configuration to - use when importing the object. By default, Terraform uses the provider specified + use when importing the object. By default, OpenTF uses the provider specified in the configuration for the target resource, and that is the best behavior in most cases. -- `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag +- `-var 'foo=bar'` - Set a variable in the OpenTF configuration. This flag can be set multiple times. Variable values are interpreted as - [literal expressions](/terraform/language/expressions/types) in the - Terraform language, so list and map values can be specified via this flag. + [literal expressions](/opentf/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 Terraform configuration from - a [variable file](/terraform/language/values/variables#variable-definitions-tfvars-files). If +- `-var-file=foo` - Set variables in the OpenTF configuration from + a [variable file](/opentf/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 @@ -74,31 +72,31 @@ 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 [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) -only, `terraform import` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +only, `opentf import` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` backend](/terraform/language/settings/backends/local) only, -`terraform import` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` backend](/opentf/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). ## Provider Configuration -Terraform will attempt to load configuration files that configure the +OpenTF will attempt to load configuration files that configure the provider being used for import. If no configuration files are present or -no configuration for that specific provider is present, Terraform will +no configuration for that specific provider is present, OpenTF will prompt you for access credentials. You may also specify environmental variables to configure the provider. -The only limitation Terraform has when reading the configuration files +The only limitation OpenTF has when reading the configuration files is that the import provider configurations must not depend on non-variable inputs. For example, a provider configuration cannot depend on a data source. As a working example, if you're importing AWS resources and you have a -configuration file with the contents below, then Terraform will configure +configuration file with the contents below, then OpenTF will configure the AWS provider with this file. ```hcl @@ -116,7 +114,7 @@ provider "aws" { This example will import an AWS instance into the `aws_instance` resource named `foo`: ```shell -$ terraform import aws_instance.foo i-abcd1234 +$ opentf import aws_instance.foo i-abcd1234 ``` ## Example: Import into Module @@ -124,37 +122,37 @@ $ terraform import aws_instance.foo i-abcd1234 The example below will import an AWS instance into the `aws_instance` resource named `bar` into a module named `foo`: ```shell -$ terraform import module.foo.aws_instance.bar i-abcd1234 +$ 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`](/terraform/language/meta-arguments/count): +[`count`](/opentf/language/meta-arguments/count): ```shell -$ terraform import 'aws_instance.baz[0]' i-abcd1234 +$ 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`](/terraform/language/meta-arguments/for_each): +[`for_each`](/opentf/language/meta-arguments/for_each): Linux, Mac OS, and UNIX: ```shell -$ terraform import 'aws_instance.baz["example"]' i-abcd1234 +$ opentf import 'aws_instance.baz["example"]' i-abcd1234 ``` PowerShell: ```shell -$ terraform import 'aws_instance.baz[\"example\"]' i-abcd1234 +$ opentf import 'aws_instance.baz[\"example\"]' i-abcd1234 ``` Windows `cmd.exe`: ```shell -$ terraform import aws_instance.baz[\"example\"] i-abcd1234 +$ opentf import aws_instance.baz[\"example\"] i-abcd1234 ``` diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx index a8a3838ffa..3b43335bd1 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.mdx @@ -1,27 +1,18 @@ --- page_title: Basic CLI Features -description: An introduction to the terraform command and its available subcommands. +description: An introduction to the opentf command and its available subcommands. --- # Basic CLI Features -> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. +The command line interface to OpenTF is the `opentf` command, which +accepts a variety of subcommands such as `opentf init` or `opentf plan`. -The command line interface to Terraform is the `terraform` command, which -accepts a variety of subcommands such as `terraform init` or `terraform plan`. - -We refer to the `terraform` command line tool as "Terraform CLI" elsewhere -in the documentation. This terminology is often used to distinguish it from -other components you might use in the Terraform product family, such as -[Terraform Cloud](/terraform/cloud-docs) or -the various [Terraform providers](/terraform/language/providers), which -are developed and released separately from Terraform CLI. - -To view a list of the commands available in your current Terraform version, -run `terraform` with no additional arguments: +To view a list of the commands available in your current OpenTF version, +run `opentf` with no additional arguments: ```text -Usage: terraform [global options] [args] +Usage: opentf [global options] [args] The available commands for execution are listed below. The primary workflow commands are given first, followed by @@ -35,12 +26,12 @@ Main commands: destroy Destroy previously-created infrastructure All other commands: - console Try Terraform expressions at an interactive command prompt + console Try OpenTF expressions at an interactive command prompt fmt Reformat your configuration in the standard style force-unlock Release a stuck lock on the current workspace - get Install or upgrade remote Terraform modules + get Install or upgrade remote OpenTF modules graph Generate a Graphviz graph of the steps in an operation - import Associate existing infrastructure with a Terraform resource + import Associate existing infrastructure with a OpenTF resource login Obtain and save credentials for a remote host logout Remove locally-stored credentials for a remote host metadata Metadata related commands @@ -51,7 +42,7 @@ All other commands: state Advanced state management taint Mark a resource instance as not fully functional untaint Remove the 'tainted' state from a resource instance - version Show the current Terraform version + version Show the current OpenTF version workspace Workspace management Global options (use these before the subcommand, if any): @@ -61,43 +52,43 @@ Global options (use these before the subcommand, if any): -version An alias for the "version" subcommand. ``` -(The output from your current Terraform version may be different than the +(The output from your current OpenTF version may be different than the above example.) To get specific help for any specific command, use the `-help` option with the relevant subcommand. For example, to see help about the "validate" subcommand -you can run `terraform validate -help`. +you can run `opentf validate -help`. -The inline help built in to Terraform CLI describes the most important +The inline help built in to OpenTF CLI describes the most important characteristics of each command. For more detailed information, refer to each command's page for details. ## Switching working directory with `-chdir` -The usual way to run Terraform is to first switch to the directory containing +The usual way to run OpenTF is to first switch to the directory containing the `.tf` files for your root module (for example, using the `cd` command), so -that Terraform will find those files automatically without any extra arguments. +that OpenTF will find those files automatically without any extra arguments. -In some cases though — particularly when wrapping Terraform in automation -scripts — it can be convenient to run Terraform from a different directory than -the root module directory. To allow that, Terraform supports a global option +In some cases though — particularly when wrapping OpenTF in automation +scripts — it can be convenient to run OpenTF from a different directory than +the root module directory. To allow that, OpenTF supports a global option `-chdir=...` which you can include before the name of the subcommand you intend to run: ``` -terraform -chdir=environments/production apply +opentf -chdir=environments/production apply ``` -The `chdir` option instructs Terraform to change its working directory to the +The `chdir` option instructs OpenTF to change its working directory to the given directory before running the given subcommand. This means that any files -that Terraform would normally read or write in the current working directory +that OpenTF would normally read or write in the current working directory will be read or written in the given directory instead. -There are two exceptions where Terraform will use the original working directory +There are two exceptions where OpenTF will use the original working directory even when you specify `-chdir=...`: -* Settings in the [CLI Configuration](/terraform/cli/config/config-file) are not for a specific - subcommand and Terraform processes them before acting on the `-chdir` +* Settings in the [CLI Configuration](/opentf/cli/config/config-file) are not for a specific + subcommand and OpenTF processes them before acting on the `-chdir` option. * In case you need to use files from the original working directory as part @@ -107,13 +98,13 @@ even when you specify `-chdir=...`: ## Shell Tab-completion -If you use either `bash` or `zsh` as your command shell, Terraform can provide +If you use either `bash` or `zsh` as your command shell, OpenTF can provide tab-completion support for all command names and some command arguments. To add the necessary commands to your shell profile, run the following command: ```bash -terraform -install-autocomplete +opentf -install-autocomplete ``` After installation, it is necessary to restart your shell or to re-read its @@ -123,5 +114,5 @@ To uninstall the completion hook, assuming that it has not been modified manually in the shell profile, run the following command: ```bash -terraform -uninstall-autocomplete +opentf -uninstall-autocomplete ``` diff --git a/website/docs/cli/commands/init.mdx b/website/docs/cli/commands/init.mdx index 95f75ec96d..0898003af9 100644 --- a/website/docs/cli/commands/init.mdx +++ b/website/docs/cli/commands/init.mdx @@ -1,25 +1,23 @@ --- page_title: 'Command: init' description: >- - The terraform init command initializes a working directory containing + The opentf init command initializes a working directory containing configuration files and installs plugins for required providers. --- # Command: init -> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. For more in-depth details on the `init` command, check out the [Initialize Terraform Configuration tutorial](/terraform/tutorials/cli/init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). - -The `terraform init` command initializes a working directory -containing Terraform configuration files. This is the first command that should -be run after writing a new Terraform configuration or cloning an existing one +The `opentf init` command initializes a working directory +containing OpenTF configuration files. This is the first command that should +be run after writing a new OpenTF configuration or cloning an existing one from version control. It is safe to run this command multiple times. ## Usage -Usage: `terraform init [options]` +Usage: `opentf init [options]` This command performs several different initialization steps in order to -prepare the current working directory for use with Terraform. More details on +prepare the current working directory for use with OpenTF. More details on these are in the sections below, but in most cases it is not necessary to worry about these individual steps. @@ -37,7 +35,7 @@ The following options apply to all of (or several of) the initialization steps: * `-lock=false` Disable locking of state files during state-related operations. -* `-lock-timeout=` Override the time Terraform will wait to acquire +* `-lock-timeout=` Override the time OpenTF will wait to acquire a state lock. The default is `0s` (zero seconds), which causes immediate failure if the lock is already held by another process. @@ -48,7 +46,7 @@ The following options apply to all of (or several of) the initialization steps: ## Copy a Source Module -By default, `terraform init` assumes that the working directory already +By default, `opentf init` assumes that the working directory already contains a configuration and will attempt to initialize that configuration. Optionally, init can be run against an empty directory with the @@ -69,12 +67,12 @@ For routine use it is recommended to check out configuration from version control separately, using the version control system's own commands. This way it is possible to pass extra flags to the version control system when necessary, and to perform other preparation steps (such as configuration generation, or -activating credentials) before running `terraform init`. +activating credentials) before running `opentf init`. ## Backend Initialization During init, the root configuration directory is consulted for -[backend configuration](/terraform/language/settings/backends/configuration) and the chosen backend +[backend configuration](/opentf/language/settings/backends/configuration) and the chosen backend is initialized using the given configuration settings. Re-running init with an already-initialized backend will update the working @@ -96,14 +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](/terraform/language/settings/backends/configuration#partial-configuration), +[partial backend configuration](/opentf/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](/terraform/language/modules/develop) is retrieved from the locations +code for referenced [modules](/opentf/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 @@ -118,47 +116,40 @@ initialized with its child modules. ## Plugin Installation -Most Terraform providers are published separately from Terraform as plugins. -During init, Terraform searches the configuration for both direct and indirect +Most OpenTF providers are published separately from OpenTF as plugins. +During init, OpenTF searches the configuration for both direct and indirect references to providers and attempts to install the plugins for those providers. For providers that are published in either [the public Terraform Registry](https://registry.terraform.io/) or in a -third-party provider registry, `terraform init` will automatically find, +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 -Terraform installs providers using -[the provider installation settings in the CLI configuration](/terraform/cli/config/config-file#provider-installation). +OpenTF installs providers using +[the provider installation settings in the CLI configuration](/opentf/cli/config/config-file#provider-installation). For more information about specifying which providers are required for each -of your modules, see [Provider Requirements](/terraform/language/providers/requirements). +of your modules, see [Provider Requirements](/opentf/language/providers/requirements). -After successful installation, Terraform writes information about the selected -providers to [the dependency lock file](/terraform/language/files/dependency-lock). +After successful installation, OpenTF writes information about the selected +providers to [the dependency lock file](/opentf/language/files/dependency-lock). You should commit this file to your version control system to ensure that -when you run `terraform init` again in future Terraform will select exactly -the same provider versions. Use the `-upgrade` option if you want Terraform +when you run `opentf init` again in future OpenTF will select exactly +the same provider versions. Use the `-upgrade` option if you want OpenTF to ignore the dependency lock file and consider installing newer versions. -You can modify `terraform init`'s plugin behavior with the following options: +You can modify `opentf init`'s plugin behavior with the following options: * `-upgrade` Upgrade all previously-selected plugins to the newest version that complies with the configuration's version constraints. This will - cause Terraform to ignore any selections recorded in the dependency lock + cause OpenTF to ignore any selections recorded in the dependency lock file, and to take the newest available version matching the configured version constraints. -* `-get-plugins=false` — Skip plugin installation. - - -> Note: Since Terraform 0.13, this option has been superseded by the - [`provider_installation`](/terraform/cli/config/config-file#provider-installation) and - [`plugin_cache_dir`](/terraform/cli/config/config-file#plugin_cache_dir) settings. - It should not be used in Terraform versions 0.13+, and this option - was removed in Terraform 0.15. * `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from the specified directory, as if it had been configured as a `filesystem_mirror` in the CLI configuration. If you intend to routinely use a particular filesystem mirror then we recommend - [configuring Terraform's installation methods globally](/terraform/cli/config/config-file#provider-installation). + [configuring OpenTF's installation methods globally](/opentf/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. @@ -171,35 +162,22 @@ The valid values for the lockfile mode are as follows: update the lockfile with third-party dependency management tools, it would be useful to control when it changes explicitly. -## Running `terraform init` in automation +## Running `opentf init` in automation -For teams that use Terraform as a key part of a change management and -deployment pipeline, it can be desirable to orchestrate Terraform runs in some +For teams that use OpenTF as a key part of a change management and +deployment pipeline, it can be desirable to orchestrate OpenTF runs in some sort of automation in order to ensure consistency between runs, and provide other interesting features such as integration with version control hooks. There are some special concerns when running `init` in such an environment, including optionally making plugins available locally to avoid repeated -re-installation. For more information, see -the [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +re-installation. ## Passing a Different Configuration Directory -Terraform v0.13 and earlier also accepted a directory path in place of the -plan file argument to `terraform apply`, in which case Terraform would use -that directory as the root module instead of the current working directory. - -That usage is still supported in Terraform v0.14, but is now deprecated and removed in -Terraform v0.15. If your workflow relies on overriding +If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir) -instead, which works across all commands and makes Terraform consistently look +[the `-chdir` global option](/opentf/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. - -If your previous use of this legacy pattern was also relying on Terraform -writing the `.terraform` subdirectory into the current working directory even -though the root module directory was overridden, use -[the `TF_DATA_DIR` environment variable](/terraform/cli/config/environment-variables#tf_data_dir) -to direct Terraform to write the `.terraform` directory to a location other -than the current working directory. diff --git a/website/docs/cli/commands/login.mdx b/website/docs/cli/commands/login.mdx index 96f4e35ea4..e463b3dad7 100644 --- a/website/docs/cli/commands/login.mdx +++ b/website/docs/cli/commands/login.mdx @@ -1,45 +1,40 @@ --- page_title: 'Command: login' description: >- - The terraform login command can be used to automatically obtain and save an - API token for Terraform Cloud, Terraform Enterprise, or any other host that - offers Terraform services. + The opentf login command can be used to automatically obtain and save an + API token for any host that offers OpenTF-compatible services. --- # Command: login -The `terraform login` command can be used to automatically obtain and save an -API token for Terraform Cloud, Terraform Enterprise, or any other host that offers Terraform services. +The `opentf login` command can be used to automatically obtain and save an +API token for any host that offers OpenTF-compatible services. -> **Note:** This command is suitable only for use in interactive scenarios -where it is possible to launch a web browser on the same host where Terraform -is running. If you are running Terraform in an unattended automation scenario, +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](/terraform/cli/config/config-file#credentials). +[configure credentials manually in the CLI configuration](/opentf/cli/config/config-file#credentials). ## Usage -Usage: `terraform login [hostname]` - -If you don't provide an explicit hostname, Terraform will assume you want to -log in to Terraform Cloud at `app.terraform.io`. +Usage: `opentf login [hostname]` ## Credentials Storage -By default, Terraform will obtain an API token and save it in plain text in a +By default, OpenTF will obtain an API token and save it in plain text in a local CLI configuration file called `credentials.tfrc.json`. When you run -`terraform login`, it will explain specifically where it intends to save +`opentf login`, it will explain specifically where it intends to save the API token and give you a chance to cancel if the current configuration is 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](/terraform/cli/config/config-file#credentials-helpers) which knows +[credentials helper program](/opentf/cli/config/config-file#credentials-helpers) which knows how to store and later retrieve credentials in some other system, such as your organization's existing secrets management system. ## Login Server Support -The `terraform login` command works with any server supporting the -[login protocol](/terraform/internals/login-protocol), including Terraform Cloud -and Terraform Enterprise. +The `opentf login` command works with any server supporting the +[login protocol](/opentf/internals/login-protocol). diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.mdx index cc1a88817d..0865a5e408 100644 --- a/website/docs/cli/commands/logout.mdx +++ b/website/docs/cli/commands/logout.mdx @@ -1,29 +1,25 @@ --- page_title: 'Command: logout' description: >- - The terraform logout command is used to remove credentials stored by terraform + The opentf logout command is used to remove credentials stored by opentf login. --- # Command: logout -The `terraform logout` command is used to remove credentials stored by -`terraform login`. These credentials are API tokens for Terraform Cloud, -Terraform Enterprise, or any other host that offers Terraform services. +The `opentf logout` command is used to remove credentials stored by +`opentf login`. These credentials are API tokens for any host that offers OpenTF-compatible services. ## Usage -Usage: `terraform logout [hostname]` - -If you don't provide an explicit hostname, Terraform will assume you want to -log out of Terraform Cloud at `app.terraform.io`. +Usage: `opentf logout [hostname]` -> **Note:** the API token is only removed from local storage, not destroyed on the remote server, so it will remain valid until manually revoked. ## Credentials Storage -By default, Terraform will remove the token stored in plain text in a local CLI +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](/terraform/cli/config/config-file#credentials-helpers), Terraform +[credentials helper program](/opentf/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 8c4a5fdb77..fe739ee28e 100644 --- a/website/docs/cli/commands/output.mdx +++ b/website/docs/cli/commands/output.mdx @@ -1,18 +1,18 @@ --- page_title: 'Command: output' description: >- - The `terraform output` command is used to extract the value of an output + The `opentf output` command is used to extract the value of an output variable from the state file. --- # Command: output -The `terraform output` command is used to extract the value of +The `opentf output` command is used to extract the value of an output variable from the state file. ## Usage -Usage: `terraform output [options] [NAME]` +Usage: `opentf output [options] [NAME]` With no additional arguments, `output` will display all the outputs for the root module. If an output `NAME` is specified, only the value of that @@ -23,22 +23,22 @@ The command-line flags are all optional. The following flags are available: * `-json` - If specified, the outputs are formatted as a JSON object, with a key per output. If `NAME` is specified, only the output specified will be returned. This can be piped into tools such as `jq` for further processing. -* `-raw` - If specified, Terraform will convert the specified output value to a +* `-raw` - If specified, OpenTF will convert the specified output value to a string and print that string directly to the output, without any special formatting. This can be convenient when working with shell scripts, but it only supports string, number, and boolean values. Use `-json` instead for processing complex data types. * `-no-color` - If specified, output won't contain any color. -* `-state=path` - Path to the state file. Defaults to "terraform.tfstate". - Ignored when [remote state](/terraform/language/state/remote) is used. +* `-state=path` - Path to the state file. Defaults to "opentf.tfstate". + Ignored when [remote state](/opentf/language/state/remote) is used. -> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive -values in Terraform state will be displayed in plain text. For more information, -see [Sensitive Data in State](/terraform/language/state/sensitive-data). +values in OpenTF state will be displayed in plain text. For more information, +see [Sensitive Data in State](/opentf/language/state/sensitive-data). ## Examples -These examples assume the following Terraform output snippet. +These examples assume the following OpenTF output snippet. ```hcl output "instance_ips" { @@ -58,7 +58,7 @@ output "password" { To list all outputs: ```shellsession -$ terraform output +$ opentf output instance_ips = [ "54.43.114.12", "52.122.13.4", @@ -71,21 +71,21 @@ password = Note that outputs with the `sensitive` attribute will be redacted: ```shellsession -$ terraform output password +$ opentf output password password = ``` To query for the DNS address of the load balancer: ```shellsession -$ terraform output lb_address +$ opentf output lb_address "my-app-alb-1657023003.us-east-1.elb.amazonaws.com" ``` To query for all instance IP addresses: ```shellsession -$ terraform output instance_ips +$ opentf output instance_ips instance_ips = [ "54.43.114.12", "52.122.13.4", @@ -95,7 +95,7 @@ instance_ips = [ ## Use in automation -The `terraform output` command by default displays in a human-readable format, +The `opentf output` command by default displays in a human-readable format, which can change over time to improve clarity. For scripting and automation, use `-json` to produce the stable JSON format. @@ -103,7 +103,7 @@ You can parse the output using a JSON command-line parser such as [jq](https://stedolan.github.io/jq/): ```shellsession -$ terraform output -json instance_ips | jq -r '.[0]' +$ opentf output -json instance_ips | jq -r '.[0]' 54.43.114.12 ``` @@ -112,15 +112,15 @@ can use `-raw` instead, which will print the string directly with no extra escaping or whitespace. ```shellsession -$ terraform output -raw lb_address +$ opentf output -raw lb_address my-app-alb-1657023003.us-east-1.elb.amazonaws.com ``` -The `-raw` option works only with values that Terraform can automatically +The `-raw` option works only with values that OpenTF can automatically convert to strings. Use `-json` instead, possibly combined with `jq`, to work with complex-typed values such as objects. -Terraform strings are sequences of Unicode characters rather than raw bytes, +OpenTF strings are sequences of Unicode characters rather than raw bytes, so the `-raw` output will be UTF-8 encoded when it contains non-ASCII characters. If you need a different character encoding, use a separate command -such as `iconv` to transcode Terraform's raw output. +such as `iconv` to transcode OpenTF's raw output. diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 7aa7b42cc4..81a6165663 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -1,45 +1,42 @@ --- page_title: 'Command: plan' description: >- - The terraform plan command creates an execution plan with a preview of the - changes that Terraform will make to your infrastructure. + The opentf plan command creates an execution plan with a preview of the + changes that OpenTF will make to your infrastructure. --- # Command: plan -The `terraform plan` command creates an execution plan, which lets you preview -the changes that Terraform plans to make to your infrastructure. By default, -when Terraform creates a plan it: +The `opentf plan` command creates an execution plan, which lets you preview +the changes that OpenTF plans to make to your infrastructure. By default, +when OpenTF creates a plan it: * Reads the current state of any already-existing remote objects to make sure - that the Terraform state is up-to-date. + that the OpenTF state is up-to-date. * Compares the current configuration to the prior state and noting any differences. * Proposes a set of change actions that should, if applied, make the remote objects match the configuration. -> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. For more in-depth details on the `plan` command, check out the [Create a Terraform Plan tutorial](/terraform/tutorials/cli/plan?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). - The `plan` command alone does not actually carry out the proposed changes You can use this command to check whether the proposed changes match what you expected before you apply the changes or share your changes with your team for broader review. -If Terraform detects that no changes are needed to resource instances or to -root module output values, `terraform plan` will report that no actions need +If OpenTF detects that no changes are needed to resource instances or to +root module output values, `opentf plan` will report that no actions need to be taken. -If you are using Terraform directly in an interactive terminal and you expect -to apply the changes Terraform proposes, you can alternatively run -[`terraform apply`](/terraform/cli/commands/apply) directly. By default, the "apply" command +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 automatically generates a new plan and prompts for you to approve it. You can use the optional `-out=FILE` option to save the generated plan to a file on disk, which you can later execute by passing the file to -[`terraform apply`](/terraform/cli/commands/apply) as an extra argument. This two-step workflow -is primarily intended for when -[running Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). +[`opentf apply`](/opentf/cli/commands/apply) as an extra argument. This two-step workflow +is primarily intended for when running OpenTF in automation. -If you run `terraform plan` without the `-out=FILE` option then it will create +If you run `opentf plan` without the `-out=FILE` option then it will create a _speculative plan_, which is a description of the effect of the plan but without any intent to actually apply it. @@ -54,15 +51,15 @@ matches your intent. ## Usage -Usage: `terraform plan [options]` +Usage: `opentf plan [options]` The `plan` subcommand looks in the current working directory for the root module configuration. -Because the plan command is one of the main commands of Terraform, it has +Because the plan command is one of the main commands of OpenTF, it has a variety of different options, described in the following sections. However, most of the time you should not need to set any of these options, because -a Terraform configuration should typically be designed to work with no special +a OpenTF configuration should typically be designed to work with no special additional options for routine work. The remaining sections on this page describe the various options: @@ -81,97 +78,87 @@ The remaining sections on this page describe the various options: ## Planning Modes -The previous section describes Terraform's default planning behavior, which +The previous section describes OpenTF's default planning behavior, which changes the remote system to match the changes you make to -your configuration. Terraform has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `terraform plan` and [`terraform apply`](/terraform/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`](/opentf/cli/commands/apply). * **Destroy mode:** creates a plan whose goal is to destroy all remote objects - that currently exist, leaving an empty Terraform state. It is the same as running [`terraform destroy`](/terraform/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`](/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. Activate destroy mode using the `-destroy` command line option. * **Refresh-only mode:** creates a plan whose goal is only to update the - Terraform state and any root module output values to match changes made to - remote objects outside of Terraform. This can be useful if you've + OpenTF state and any root module output values to match changes made to + remote objects outside of OpenTF. This can be useful if you've intentionally changed one or more remote objects outside of the usual workflow (e.g. while responding to an incident) and you now need to reconcile - Terraform's records with those changes. + OpenTF's records with those changes. Activate refresh-only mode using the `-refresh-only` command line option. -In situations where we need to discuss the default planning mode that Terraform +In situations where we need to discuss the default planning mode that OpenTF uses when none of the alternative modes are selected, we refer to it as "Normal mode". Because these alternative modes are for specialized situations -only, some other Terraform documentation only discusses the normal planning +only, some other OpenTF documentation only discusses the normal planning mode. The planning modes are all mutually-exclusive, so activating any non-default planning mode disables the "normal" planning mode, and you can't use more than one alternative mode at the same time. --> **Note:** In Terraform v0.15 and earlier, the `-destroy` option is -supported only by the `terraform plan` command, and not by the -`terraform apply` command. To create and apply a plan in destroy mode in -earlier versions you must run [`terraform destroy`](/terraform/cli/commands/destroy). - --> **Note:** The `-refresh-only` option is available only in Terraform v0.15.4 -and later. - -> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. - ## Planning Options -In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for both `terraform plan` and [`terraform apply`](/terraform/cli/commands/apply). +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). - `-refresh=false` - Disables the default behavior of synchronizing the - Terraform 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 Terraform 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. + 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. -- `-replace=ADDRESS` - Instructs Terraform to plan to replace the - resource instance with the given address. This is helpful when one or more remote objects have become degraded, and you can use replacement objects with the same configuration to align with immutable infrastructure patterns. Terraform will use a "replace" action if the specified resource would normally cause an "update" action or no action at all. Include this option multiple times to replace several objects at once. You cannot use `-replace` with the `-destroy` option, and it is only available from Terraform v0.15.2 onwards. For earlier versions, use [`terraform taint`](/terraform/cli/commands/taint) to achieve a similar result. +- `-replace=ADDRESS` - Instructs OpenTF to plan to replace the + resource instance with the given address. This is helpful when one or more remote objects have become degraded, and you can use replacement objects with the same configuration to align with immutable infrastructure patterns. OpenTF will use a "replace" action if the specified resource would normally cause an "update" action or no action at all. Include this option multiple times to replace several objects at once. You cannot use `-replace` with the `-destroy` option. -- `-target=ADDRESS` - Instructs Terraform to focus its planning efforts only +- `-target=ADDRESS` - Instructs OpenTF to focus its planning efforts only on resource instances which match the given address and on any objects that those instances depend on. - -> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around Terraform limitations. Refer to [Resource Targeting](#resource-targeting) for more details. + -> **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](/terraform/language/values/variables) declared in the + [input variable](/opentf/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](/terraform/language/values/variables) declared in the + [input variables](/opentf/language/values/variables) declared in the root module of the configuration, using definitions from a - ["tfvars" file](/terraform/language/values/variables#variable-definitions-tfvars-files). + ["tfvars" file](/opentf/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](/terraform/language/values/variables#assigning-values-to-root-module-variables) for more information. +[Assigning Values to Root Module Variables](/opentf/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](/terraform/language/values/variables) declared in your +[input variables](/opentf/language/values/variables) declared in your root module. However, to do so will require writing a command line that is parsable both -by your chosen command line shell _and_ Terraform, which can be complicated +by your chosen command line shell _and_ OpenTF, which can be complicated for expressions involving lots of quotes and escape sequences. In most cases we recommend using the `-var-file` option instead, and write your actual values -in a separate file so that Terraform can parse them directly, rather than +in a separate file so that OpenTF can parse them directly, rather than interpreting the result of your shell's parsing. -~> **Warning:** Terraform will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`). +~> **Warning:** OpenTF will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`). To use `-var` on a Unix-style shell on a system like Linux or macOS we recommend writing the option argument in single quotes `'` to ensure the shell will interpret the value literally: ``` -terraform plan -var 'name=value' +opentf plan -var 'name=value' ``` If your intended value also includes a single quote then you'll still need to @@ -180,82 +167,80 @@ temporarily ending the quoted sequence so that the backslash escape character will be significant: ``` -terraform plan -var 'name=va'\''lue' +opentf plan -var 'name=va'\''lue' ``` -When using Terraform on Windows, we recommend using the Windows Command Prompt -(`cmd.exe`). When you pass a variable value to Terraform from the Windows +When using OpenTF on Windows, we recommend using the Windows Command Prompt +(`cmd.exe`). When you pass a variable value to OpenTF from the Windows Command Prompt, use double quotes `"` around the argument: ``` -terraform plan -var "name=value" +opentf plan -var "name=value" ``` If your intended value includes literal double quotes then you'll need to escape those with a backslash: ``` -terraform plan -var "name=va\"lue" +opentf plan -var "name=va\"lue" ``` PowerShell on Windows cannot correctly pass literal quotes to external programs, -so we do not recommend using Terraform with PowerShell when you are on Windows. +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](/terraform/language/expressions/type-constraints). +on the variable's [type constraint](/opentf/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, map, and set types and the special `any` keyword, you must write a valid -Terraform language expression representing the value, and write any necessary +OpenTF language expression representing the value, and write any necessary quoting or escape characters to ensure it will pass through your shell -literally to Terraform. For example, for a `list(string)` type constraint: +literally to OpenTF. For example, for a `list(string)` type constraint: ``` # Unix-style shell -terraform plan -var 'name=["a", "b", "c"]' +opentf plan -var 'name=["a", "b", "c"]' # Windows Command Prompt (do not use PowerShell on Windows) -terraform plan -var "name=[\"a\", \"b\", \"c\"]" +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](/terraform/language/values/variables#assigning-values-to-root-module-variables). +[Assigning Values to Root Module Variables](/opentf/language/values/variables#assigning-values-to-root-module-variables). ### Resource Targeting -> **Hands-on:** Try the [Target resources](/terraform/tutorials/state/resource-targeting?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. - -You can use the `-target` option to focus Terraform's attention on only a +You can use the `-target` option to focus OpenTF's attention on only a subset of resources. -You can use [resource address syntax](/terraform/cli/state/resource-addressing) -to specify the constraint. Terraform interprets the resource address as follows: +You can use [resource address syntax](/opentf/cli/state/resource-addressing) +to specify the constraint. OpenTF interprets the resource address as follows: -* If the given address identifies one specific resource instance, Terraform +* If the given address identifies one specific resource instance, OpenTF will select that instance alone. For resources with either `count` or `for_each` set, a resource instance address must include the instance index part, like `aws_instance.example[0]`. -* If the given address identifies a resource as a whole, Terraform will select +* If the given address identifies a resource as a whole, OpenTF will select all of the instances of that resource. For resources with either `count` or `for_each` set, this means selecting _all_ instance indexes currently associated with that resource. For single-instance resources (without either `count` or `for_each`), the resource address and the resource instance address are identical, so this possibility does not apply. -* If the given address identifies an entire module instance, Terraform will +* If the given address identifies an entire module instance, OpenTF will select all instances of all resources that belong to that module instance and all of its child module instances. -Once Terraform has selected one or more resource instances that you've directly +Once OpenTF has selected one or more resource instances that you've directly targeted, it will also then extend the selection to include all other objects that those selections depend on either directly or indirectly. This targeting capability is provided for exceptional circumstances, such -as recovering from mistakes or working around Terraform limitations. It +as recovering from mistakes or working around OpenTF limitations. It is _not recommended_ to use `-target` for routine operations, since this can lead to undetected configuration drift and confusion about how the true state of resources relates to configuration. @@ -263,17 +248,17 @@ 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](/terraform/language/data-sources) can be used to access +[Data sources](/opentf/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. ## Other Options -The `terraform plan` command also has some other options that are related to +The `opentf plan` command also has some other options that are related to the input and output of the planning command, rather than customizing what -sort of plan Terraform will create. These commands are not necessarily also -available on `terraform apply`, unless otherwise stated in the documentation +sort of plan OpenTF will create. These commands are not necessarily also +available on `opentf apply`, unless otherwise stated in the documentation for that command. The available options are: @@ -290,76 +275,64 @@ The available options are: * 1 = Error * 2 = Succeeded with non-empty diff (changes present) -- `-generate-config-out=PATH` - (Experimental) If `import` blocks are present in configuration, instructs Terraform to generate HCL for any imported resources not already present. The configuration is written to a new file at PATH, which must not already exist, or Terraform will error. If the plan fails for another reason, Terraform may still attempt to write configuration. +- `-generate-config-out=PATH` - (Experimental) If `import` blocks are present in configuration, instructs OpenTF to generate HCL for any imported resources not already present. The configuration is written to a new file at PATH, which must not already exist, or OpenTF will error. If the plan fails for another reason, OpenTF may still attempt to write configuration. -* `-input=false` - Disables Terraform's default behavior of prompting for +* `-input=false` - Disables OpenTF's default behavior of prompting for input for root module input variables that have not otherwise been assigned - a value. This option is particularly useful when running Terraform in + a value. This option is particularly useful when running OpenTF in non-interactive automation systems. * `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output. This implies `-input=false`, so the configuration must have no unassigned variable values to continue. - [machine-readable-ui]: /terraform/internals/machine-readable-ui + [machine-readable-ui]: /opentf/internals/machine-readable-ui * `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - instructs Terraform to retry acquiring a lock for a period of time before + instructs OpenTF to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. * `-no-color` - Disables terminal formatting sequences in the output. Use this - if you are running Terraform in a context where its output will be + if you are running OpenTF in a context where its output will be rendered by a system that cannot interpret terminal formatting. * `-out=FILENAME` - Writes the generated plan to the given filename in an - opaque file format that you can later pass to `terraform apply` to execute - the planned changes, and to some other Terraform commands that can work with + opaque file format that you can later pass to `opentf apply` to execute + the planned changes, and to some other OpenTF commands that can work with saved plan files. - Terraform will allow any filename for the plan file, but a typical + OpenTF will allow any filename for the plan file, but a typical convention is to name it `tfplan`. **Do not** name the file with a suffix - that Terraform recognizes as another file format; if you use a `.tf` suffix - then Terraform will try to interpret the file as a configuration source + that OpenTF recognizes as another file format; if you use a `.tf` suffix + then OpenTF will try to interpret the file as a configuration source file, which will then cause syntax errors for subsequent commands. The generated file is not in any standard format intended for consumption by other software, but the file _does_ contain your full configuration, all of the values associated with planned changes, and all of the plan options including the input variables. If your plan includes any sort of - sensitive data, even if obscured in Terraform's terminal output, it will + sensitive data, even if obscured in OpenTF's terminal output, it will be saved in cleartext in the plan file. You should therefore treat any saved plan files as potentially-sensitive artifacts. -* `-parallelism=n` - Limit the number of concurrent operations as Terraform - [walks the graph](/terraform/internals/graph#walking-the-graph). Defaults +* `-parallelism=n` - Limit the number of concurrent operations as OpenTF + [walks the graph](/opentf/internals/graph#walking-the-graph). Defaults to 10. For configurations using -[the `local` backend](/terraform/language/settings/backends/local) only, -`terraform plan` accepts the legacy command line option -[`-state`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` backend](/opentf/language/settings/backends/local) only, +`opentf plan` accepts the legacy command line option +[`-state`](/opentf/language/settings/backends/local#command-line-arguments). ### Passing a Different Configuration Directory -Terraform v0.13 and earlier accepted an additional positional argument giving -a directory path, in which case Terraform would use that directory as the root -module instead of the current working directory. - -That usage was deprecated in Terraform v0.14 and removed in Terraform v0.15. If your workflow relies on overriding the root module directory, use -[the `-chdir` global option](/terraform/cli/commands#switching-working-directory-with-chdir) -instead, which works across all commands and makes Terraform consistently look +[the `-chdir` global option](/opentf/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. - -If your previous use of this legacy pattern was also relying on Terraform -writing the `.terraform` subdirectory into the current working directory even -though the root module directory was overridden, use -[the `TF_DATA_DIR` environment variable](/terraform/cli/config/environment-variables#tf_data_dir) -to direct Terraform to write the `.terraform` directory to a location other -than the current working directory. diff --git a/website/docs/cli/commands/providers.mdx b/website/docs/cli/commands/providers.mdx index 3222d8f637..0f92f4b918 100644 --- a/website/docs/cli/commands/providers.mdx +++ b/website/docs/cli/commands/providers.mdx @@ -1,14 +1,14 @@ --- page_title: 'Command: providers' description: >- - The terraform providers command prints information about the providers + The opentf providers command prints information about the providers required in the current configuration. --- # Command: providers -The `terraform providers` command shows information about the -[provider requirements](/terraform/language/providers/requirements) of the +The `opentf providers` command shows information about the +[provider requirements](/opentf/language/providers/requirements) of the configuration in the current working directory, as an aid to understanding where each requirement was detected from. @@ -16,4 +16,4 @@ This command also has several subcommands with different purposes. ## Usage -Usage: `terraform providers` +Usage: `opentf providers` diff --git a/website/docs/cli/commands/providers/lock.mdx b/website/docs/cli/commands/providers/lock.mdx index c75455fd96..79363047e0 100644 --- a/website/docs/cli/commands/providers/lock.mdx +++ b/website/docs/cli/commands/providers/lock.mdx @@ -1,57 +1,55 @@ --- page_title: 'Command: providers lock' description: |- - The `terraform providers lock` command adds new provider selection information + The `opentf providers lock` command adds new provider selection information to the dependency lock file without initializing the referenced providers. --- -# Command: terraform providers lock +# Command: opentf providers lock -The `terraform providers lock` consults upstream registries (by default) in +The `opentf providers lock` consults upstream registries (by default) in order to write provider dependency information into -[the dependency lock file](/terraform/language/files/dependency-lock). +[the dependency lock file](/opentf/language/files/dependency-lock). The common way to update the dependency lock file is as a side-effect of normal provider installation during -[`terraform init`](/terraform/cli/commands/init), but there are several situations where that +[`opentf init`](/opentf/cli/commands/init), but there are several situations where that automatic approach may not be sufficient: -* If you are running Terraform in an environment that uses - [alternative provider installation methods](/terraform/cli/config/config-file#provider-installation), +* If you are running OpenTF in an environment that uses + [alternative provider installation methods](/opentf/cli/config/config-file#provider-installation), such as filesystem or network mirrors, normal provider installation will not - access the origin registry for a provider and therefore Terraform will not + 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 provider versions. - If you use `terraform lock` to write the official release checksums for a - provider into the dependency lock file then future `terraform init` runs + If you use `opentf lock` to write the official release checksums for a + provider into the dependency lock file then future `opentf init` runs will verify the packages available in your selected mirror against the official checksums previously recorded, giving additional certainty that the mirror is serving the provider packages it is claiming to. -* If your team runs Terraform across a number of different platforms (e.g. +* If your team runs OpenTF across a number of different platforms (e.g. on both Windows and Linux) and the upstream registry for a provider is unable to provide signed checksums using the latest hashing scheme, subsequent runs - of Terraform on other platforms may - [add additional checksums to the lock file](/terraform/language/files/dependency-lock#new-provider-package-checksums). + of OpenTF on other platforms may + [add additional checksums to the lock file](/opentf/language/files/dependency-lock#new-provider-package-checksums). You can avoid that by pre-populating hashes for all of the platforms you - intend to use, using the `terraform providers lock` command. - --> `terraform providers lock` is available only in Terraform v0.14 or later. + intend to use, using the `opentf providers lock` command. ## Usage -Usage: `terraform providers lock [options] [providers...]` +Usage: `opentf providers lock [options] [providers...]` -With no additional command line arguments, `terraform providers lock` will +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](/terraform/language/files/dependency-lock) to +[the dependency lock file](/opentf/language/files/dependency-lock) to include a selected version for each provider and all of the package checksums that are covered by the provider developer's cryptographic signature. -~> **Warning:** The `terraform providers lock` command prints information +~> **Warning:** The `opentf providers lock` command prints information about what it has fetched and whether each package was signed using a cryptographic signature, but it cannot automatically verify that the providers are trustworthy and that they comply with your local system @@ -60,22 +58,22 @@ in the output to confirm that you trust all of the signers before committing the updated lock file to your version control system. If you list one or more provider source addresses on the command line then -`terraform providers lock` will restrict its work only to those providers, +`opentf providers lock` will restrict its work only to those providers, leaving the lock entries for other providers (if any) unchanged. You can customize the default behavior using the following additional option: -* `-fs-mirror=PATH` - Direct Terraform to look for provider packages in the +* `-fs-mirror=PATH` - Direct OpenTF to look for provider packages in the given local filesystem mirror directory, instead of in upstream registries. The given directory must use the usual filesystem mirror directory layout. -* `-net-mirror=URL` - Direct Terraform to look for provider packages in the +* `-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 Terraform provider network mirror protocol](/terraform/internals/provider-network-mirror-protocol). + [the OpenTF provider network mirror protocol](/opentf/internals/provider-network-mirror-protocol). * `-platform=OS_ARCH` - Specify a platform you intend to use to work with this - Terraform configuration. Terraform will ensure that the providers are all + OpenTF configuration. OpenTF will ensure that the providers are all available for the given platform and will save enough package checksums in the lock file to support _at least_ the specified platforms. @@ -91,16 +89,16 @@ You can customize the default behavior using the following additional option: ## Specifying Target Platforms In your environment you may, for example, have both developers who work with -your Terraform configuration on their Windows or macOS workstations _and_ +your OpenTF configuration on their Windows or macOS workstations _and_ automated systems that apply the configuration while running on Linux. In that situation, you could choose to verify that all of your providers support all of those platforms, and to pre-populate the lock file with the necessary -checksums, by running `terraform providers lock` and specifying those three +checksums, by running `opentf providers lock` and specifying those three platforms: ``` -terraform providers lock \ +opentf providers lock \ -platform=windows_amd64 \ # 64-bit Windows -platform=darwin_amd64 \ # 64-bit macOS -platform=linux_amd64 # 64-bit Linux @@ -112,12 +110,12 @@ arguments on a single line, and remove the backslashes and comments.) ## Lock Entries for In-house Providers -An _in-house provider_ is one that isn't published on a real Terraform provider +An _in-house provider_ is one that isn't published on a real OpenTF provider registry because it's developed and used only within a particular organization and distributed via either a filesystem mirror or network mirror. -By default, `terraform providers lock` assumes all providers are available -at a Terraform provider registry and tries to contact the origin registries +By default, `opentf providers lock` assumes all providers are available +at a OpenTF provider registry and tries to contact the origin registries in order to get access to the most detailed information about the provider packages. @@ -127,8 +125,8 @@ line options to override the default behavior of consulting the provider's origin registry: ``` -terraform providers lock \ - -fs-mirror=/usr/local/terraform/providers +opentf providers lock \ + -fs-mirror=/usr/local/opentf/providers -platform=windows_amd64 \ -platform=darwin_amd64 \ -platform=linux_amd64 \ @@ -140,15 +138,15 @@ you are running the command on Windows then you will need to put all of the arguments on a single line, and remove the backslashes.) Because the command above includes the provider source address -`tf.example.com/ourcompany/ourplatform`, `terraform providers lock` will only +`tf.example.com/ourcompany/ourplatform`, `opentf providers lock` will only attempt to access that particular provider and will leave the lock entries for any other providers unchanged. If you have a variety of different providers -available from different sources, you can run `terraform providers lock` +available from different sources, you can run `opentf providers lock` 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](/terraform/cli/config/config-file#provider-installation), +[the provider installation methods configuration](/opentf/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. @@ -165,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](/terraform/internals/provider-registry-protocol). +[the provider registry protocol](/opentf/internals/provider-registry-protocol). diff --git a/website/docs/cli/commands/providers/mirror.mdx b/website/docs/cli/commands/providers/mirror.mdx index 129c55a658..aa516f23c0 100644 --- a/website/docs/cli/commands/providers/mirror.mdx +++ b/website/docs/cli/commands/providers/mirror.mdx @@ -1,53 +1,51 @@ --- page_title: 'Command: providers mirror' description: |- - The `terraform providers mirror` command downloads the providers required + The `opentf providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local filesystem. --- -# Command: terraform providers mirror +# Command: opentf providers mirror -The `terraform providers mirror` command downloads the providers required +The `opentf providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local filesystem. -In normal use, `terraform init` will automatically download needed providers +In normal use, `opentf init` will automatically download needed providers from provider registries as part of initializing the current working directory. -Sometimes Terraform is running in an environment where that isn't possible, -such as on an isolated network without access to the Terraform Registry. In +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](/terraform/cli/config/config-file#explicit-installation-method-configuration) -allows you to configure Terraform, when running on a particular system, to +[explicit installation method configuration](/opentf/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. -The `terraform providers mirror` command can automatically populate a directory +The `opentf providers mirror` command can automatically populate a directory that will be used as a local filesystem mirror in the provider installation configuration. --> `terraform providers mirror` is available only in Terraform v0.13 or later. - ## Usage -Usage: `terraform providers mirror [options] ` +Usage: `opentf providers mirror [options] ` -A single target directory is required. Terraform will create under that +A single target directory is required. OpenTF will create under that directory the path structure that is expected for filesystem-based provider plugin mirrors, populating it with `.zip` files containing the plugins themselves. -Terraform will also generate various `.json` index files which contain suitable +OpenTF will also generate various `.json` index files which contain suitable responses to implement -[the network mirror protocol](/terraform/internals/provider-network-mirror-protocol), -if you upload the resulting directory to a static website host. Terraform +[the network mirror protocol](/opentf/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. This command supports the following additional option: * `-platform=OS_ARCH` - Choose which target platform to build a mirror for. - By default Terraform will obtain plugin packages suitable for the platform + By default OpenTF will obtain plugin packages suitable for the platform where you run this command. Use this flag multiple times to include packages for multiple target systems. @@ -55,7 +53,7 @@ This command supports the following additional option: architecture. For example, `linux_amd64` selects the Linux operating system running on an AMD64 or x86_64 CPU. -You can run `terraform providers mirror` again on an existing mirror directory +You can run `opentf providers mirror` again on an existing mirror directory to update it with new packages. For example, you can add packages for a new target platform by re-running the command with the desired new `-platform=...` option, and it will place the packages for that new platform without removing diff --git a/website/docs/cli/commands/providers/schema.mdx b/website/docs/cli/commands/providers/schema.mdx index 3b2490037b..74f64710b1 100644 --- a/website/docs/cli/commands/providers/schema.mdx +++ b/website/docs/cli/commands/providers/schema.mdx @@ -1,21 +1,19 @@ --- page_title: 'Command: providers schema' description: >- - The `terraform providers schema` command prints detailed schemas for the + The `opentf providers schema` command prints detailed schemas for the providers used in the current configuration. --- -# Command: terraform providers schema +# Command: opentf providers schema -The `terraform providers schema` command is used to print detailed schemas for the providers used in the current configuration. - --> `terraform providers schema` requires **Terraform v0.12 or later**. +The `opentf providers schema` command is used to print detailed schemas for the providers used in the current configuration. ## Usage -Usage: `terraform providers schema [options]` +Usage: `opentf providers schema [options]` The following flags are available: @@ -23,7 +21,7 @@ The following flags are available: Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. -The output includes a `format_version` key, which as of Terraform 1.1.0 has +The output includes a `format_version` key, which has value `"1.0"`. The semantics of this version are: - We will increment the minor version, e.g. `"1.1"`, for backward-compatible @@ -34,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 Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). ## Format Summary @@ -44,7 +42,7 @@ To avoid excessive repetition, we've split the complete format into several disc The JSON output format consists of the following objects and sub-objects: -- [Providers Schema Representation](#providers-schema-representation) - the top-level object returned by `terraform providers schema -json` +- [Providers Schema Representation](#providers-schema-representation) - the top-level object returned by `opentf providers schema -json` - [Schema Representation](#schema-representation) - a sub-object of providers, resources, and data sources that describes their schema - [Block Representation](#block-representation) - a sub-object of schemas that describes attributes and nested blocks diff --git a/website/docs/cli/commands/push.mdx b/website/docs/cli/commands/push.mdx deleted file mode 100644 index 4bbff18d59..0000000000 --- a/website/docs/cli/commands/push.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -page_title: 'Command: push' -description: >- - DISCONTINUED. Terraform Cloud and the modern "remote" backend have replaced - the old `terraform push` command. ---- - -# Command: push - -!> **Important:** The `terraform push` command is no longer functional. We recommend the [Terraform Cloud CLI integration](/terraform/cli/cloud) instead, which allows you to run remote operations in Terraform Cloud directly from the command line. - -The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise. - -The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional. diff --git a/website/docs/cli/commands/refresh.mdx b/website/docs/cli/commands/refresh.mdx index d44f4f1abf..b6b983b62d 100644 --- a/website/docs/cli/commands/refresh.mdx +++ b/website/docs/cli/commands/refresh.mdx @@ -1,68 +1,59 @@ --- page_title: 'Command: refresh' description: |- - The `terraform refresh` command reads the current settings from all managed - remote objects and updates the Terraform state to match. + The `opentf refresh` command reads the current settings from all managed + remote objects and updates the OpenTF state to match. --- # Command: refresh -> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. - -The `terraform refresh` command reads the current settings from all managed -remote objects and updates the Terraform state to match. +The `opentf refresh` command reads the current settings from all managed +remote objects and updates the OpenTF state to match. ~> _Warning:_ This command is deprecated, because its default behavior is unsafe if you have misconfigured credentials for any of your providers. See below for more information and recommended alternatives. This won't modify your real remote objects, but it will modify the -[Terraform state](/terraform/language/state). +[OpenTF state](/opentf/language/state). -You shouldn't typically need to use this command, because Terraform +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 -[`terraform plan`](/terraform/cli/commands/plan) +[`opentf plan`](/opentf/cli/commands/plan) and -[`terraform apply`](/terraform/cli/commands/apply) +[`opentf apply`](/opentf/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. ## Usage -Usage: `terraform refresh [options]` +Usage: `opentf refresh [options]` This command is effectively an alias for the following command: ``` -terraform apply -refresh-only -auto-approve +opentf apply -refresh-only -auto-approve ``` Consequently, it supports all of the same options as -[`terraform apply`](/terraform/cli/commands/apply) except that it does not accept a saved +[`opentf apply`](/opentf/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. Automatically applying the effect of a refresh is risky. If you have -misconfigured credentials for one or more providers, Terraform may +misconfigured credentials for one or more providers, OpenTF may be misled into thinking that all of the managed objects have been deleted, causing it to remove all of the tracked objects without any confirmation prompt. Instead, we recommend using the following command in order to get the same -effect but with the opportunity to review the changes that Terraform has +effect but with the opportunity to review the changes that OpenTF has detected before committing them to the state: ``` -terraform apply -refresh-only +opentf apply -refresh-only ``` This alternative command will present an interactive prompt for you to confirm the detected changes. - -The `-refresh-only` option for `terraform plan` and `terraform apply` was -introduced in Terraform v0.15.4. For prior versions you must use -`terraform refresh` directly if you need this behavior, while taking into -account the warnings above. Wherever possible, avoid using `terraform refresh` -explicitly and instead rely on Terraform's behavior of automatically refreshing -existing objects as part of creating a normal plan. diff --git a/website/docs/cli/commands/show.mdx b/website/docs/cli/commands/show.mdx index cbde69f54e..cac828abca 100644 --- a/website/docs/cli/commands/show.mdx +++ b/website/docs/cli/commands/show.mdx @@ -1,48 +1,48 @@ --- page_title: 'Command: show' description: >- - The `terraform show` command is used to provide human-readable output from a + The `opentf show` command is used to provide human-readable output from a state or plan file. This can be used to inspect a plan to ensure that the - planned operations are expected, or to inspect the current state as Terraform + planned operations are expected, or to inspect the current state as OpenTF sees it. --- # Command: show -The `terraform show` command is used to provide human-readable output +The `opentf show` command is used to provide human-readable output from a state or plan file. This can be used to inspect a plan to ensure that the planned operations are expected, or to inspect the current state -as Terraform sees it. +as OpenTF sees it. Machine-readable output is generated by adding the `-json` command-line flag. -> **Note:** When using the `-json` command-line flag, any sensitive values in -Terraform state will be displayed in plain text. For more information, see -[Sensitive Data in State](/terraform/language/state/sensitive-data). +OpenTF state will be displayed in plain text. For more information, see +[Sensitive Data in State](/opentf/language/state/sensitive-data). ## JSON Output -For Terraform state files (including when no path is provided), -`terraform show -json` will show a JSON representation of the state. +For OpenTF state files (including when no path is provided), +`opentf show -json` will show a JSON representation of the state. -For Terraform plan files, `terraform show -json` will show a JSON representation +For OpenTF plan files, `opentf show -json` will show a JSON representation of the plan, configuration, and current state. If you've updated providers which contain new schema versions since the state was written, the state needs to be upgraded before it can be displayed with `show -json`. If you are viewing a plan, it must be created without -`-refresh=false`. If you are viewing a state file, run `terraform refresh` +`-refresh=false`. If you are viewing a state file, run `opentf refresh` first. -The output format is covered in detail in [JSON Output Format](/terraform/internals/json-format). +The output format is covered in detail in [JSON Output Format](/opentf/internals/json-format). ## Usage -Usage: `terraform show [options] [file]` +Usage: `opentf show [options] [file]` -You may use `show` with a path to either a Terraform state file or plan -file. If you don't specify a file path, Terraform will show the latest state +You may use `show` with a path to either a OpenTF state file or plan +file. If you don't specify a file path, OpenTF will show the latest state snapshot. This command accepts the following options: @@ -50,5 +50,3 @@ This command accepts the following options: * `-no-color` - Disables output with coloring * `-json` - Displays machine-readable output from a state or plan file - --> JSON output via the `-json` option requires **Terraform v0.12 or later**. diff --git a/website/docs/cli/commands/state/index.mdx b/website/docs/cli/commands/state/index.mdx index 0d5a46be8c..7d083e0950 100644 --- a/website/docs/cli/commands/state/index.mdx +++ b/website/docs/cli/commands/state/index.mdx @@ -1,14 +1,14 @@ --- page_title: 'Command: state' -description: The `terraform state` command is used for advanced state management. +description: The `opentf state` command is used for advanced state management. --- # State Command -The `terraform state` command is used for advanced state management. -As your Terraform usage becomes more advanced, there are some cases where -you may need to modify the [Terraform state](/terraform/language/state). -Rather than modify the state directly, the `terraform state` commands can +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). +Rather than modify the state directly, the `opentf state` commands can be used in many cases instead. This command is a nested subcommand, meaning that it has further subcommands. @@ -16,27 +16,27 @@ These subcommands are listed to the left. ## Usage -Usage: `terraform state [options] [args]` +Usage: `opentf state [options] [args]` Please click a subcommand to the left for more information. ## Remote State -The Terraform state subcommands all work with remote state just as if it +The OpenTF state subcommands all work with remote state just as if it was local state. Reads and writes may take longer than normal as each read and each write do a full network roundtrip. Otherwise, backups are still written to disk and the CLI usage is the same as if it were local state. ## Backups -All `terraform state` subcommands that modify the state write backup +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](/terraform/cli/commands/state/list)) +Subcommands that are read-only (such as [list](/opentf/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 -the sensitivity of the state file, Terraform forces every state modification +the sensitivity of the state file, OpenTF forces every state modification command to write a backup file. You'll have to remove these files manually if you don't want to keep them around. @@ -46,5 +46,5 @@ The output and command-line structure of the state subcommands is designed to be usable with Unix command-line tools such as grep, awk, and similar PowerShell commands. -For advanced filtering and modification, we recommend piping Terraform +For advanced filtering and modification, we recommend piping OpenTF state subcommands together with other command line tools. diff --git a/website/docs/cli/commands/state/list.mdx b/website/docs/cli/commands/state/list.mdx index 8471fbe89a..02b9c2f333 100644 --- a/website/docs/cli/commands/state/list.mdx +++ b/website/docs/cli/commands/state/list.mdx @@ -1,18 +1,18 @@ --- page_title: 'Command: state list' description: >- - The terraform state list command is used to list resources within a Terraform + The opentf state list command is used to list resources within a OpenTF state. --- # Command: state list -The `terraform state list` command is used to list resources within a -[Terraform state](/terraform/language/state). +The `opentf state list` command is used to list resources within a +[OpenTF state](/opentf/language/state). ## Usage -Usage: `terraform state list [options] [address...]` +Usage: `opentf state list [options] [address...]` The command will list all resources in the state file matching the given addresses (if any). If no addresses are given, all resources are listed. @@ -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](/terraform/cli/state/resource-addressing). +in [resource addressing format](/opentf/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 "terraform.tfstate". - Ignored when [remote state](/terraform/language/state/remote) is used. +* `-state=path` - Path to the state file. Defaults to "opentf.tfstate". + Ignored when [remote state](/opentf/language/state/remote) is used. * `-id=id` - ID of resources to show. Ignored when unset. ## Example: All Resources @@ -37,7 +37,7 @@ The command-line flags are all optional. The following flags are available: This example will list all resources, including modules: ``` -$ terraform state list +$ opentf state list aws_instance.foo aws_instance.bar[0] aws_instance.bar[1] @@ -49,7 +49,7 @@ module.elb.aws_elb.main This example will only list resources for the given name: ``` -$ terraform state list aws_instance.bar +$ opentf state list aws_instance.bar aws_instance.bar[0] aws_instance.bar[1] ``` @@ -59,7 +59,7 @@ aws_instance.bar[1] This example will list resources in the given module and any submodules: ``` -$ terraform state list module.elb +$ opentf state list module.elb module.elb.aws_elb.main module.elb.module.secgroups.aws_security_group.sg ``` @@ -71,6 +71,6 @@ command line. This is useful to find where in your configuration a specific resource is located. ``` -$ terraform state list -id=sg-1234abcd +$ opentf state list -id=sg-1234abcd module.elb.aws_security_group.sg ``` diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.mdx index 4c124bfea9..4d653178e4 100644 --- a/website/docs/cli/commands/state/mv.mdx +++ b/website/docs/cli/commands/state/mv.mdx @@ -1,54 +1,54 @@ --- page_title: 'Command: state mv' description: >- - The `terraform state mv` command changes bindings in Terraform state, + The `opentf state mv` command changes bindings in OpenTF state, associating existing remote objects with new resource instances. --- # Command: state mv -The main function of [Terraform state](/terraform/language/state) is +The main function of [OpenTF state](/opentf/language/state) is to track the bindings between resource instance addresses in your configuration -and the remote objects they represent. Normally Terraform automatically +and the remote objects they represent. Normally OpenTF automatically updates the state in response to actions taken when applying a plan, such as removing a binding for an remote object that has now been deleted. -You can use `terraform state mv` in the less common situation where you wish +You can use `opentf state mv` in the less common situation where you wish to retain an existing remote object but track it as a different resource -instance address in Terraform, such as if you have renamed a resource block +instance address in OpenTF, such as if you have renamed a resource block or you have moved it into a different module in your configuration. ## Usage -Usage: `terraform state mv [options] SOURCE DESTINATION` +Usage: `opentf state mv [options] SOURCE DESTINATION` -Terraform will look in the current state for a resource instance, resource, +OpenTF will look in the current state for a resource instance, resource, or module that matches the given address, and if successful it will move the 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](/terraform/cli/state/resource-addressing), and +[resource address syntax](/opentf/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 a resource instance then you can only move it to a new address with the same resource type. -The most common uses for `terraform state mv` are when you have renamed a +The most common uses for `opentf state mv` are when you have renamed a resource block in your configuration or you've moved a resource block into a child module, in both cases with the intention of retaining the existing -object but tracking it under a new name. By default Terraform will understand +object but tracking it under a new name. By default OpenTF will understand moving or renaming a resource configuration as a request to delete the old -object and create a new object at the new address, and so `terraform state mv` +object and create a new object at the new address, and so `opentf state mv` allows you to override that interpretation by pre-emptively attaching the -existing object to the new address in Terraform. +existing object to the new address in OpenTF. -~> _Warning:_ If you are using Terraform in a collaborative environment, you -must ensure that when you are using `terraform state mv` for a code refactoring +~> _Warning:_ If you are using OpenTF in a collaborative environment, you +must ensure that when you are using `opentf state mv` for a code refactoring purpose you communicate carefully with your coworkers to ensure that nobody makes any other changes between your configuration change and your -`terraform state mv` command, because otherwise they might inadvertently create +`opentf state mv` command, because otherwise they might inadvertently create a plan that will destroy the old object and create a new object at the new address. @@ -62,26 +62,26 @@ This command also accepts the following options: workspace. - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - instructs Terraform to retry acquiring a lock for a period of time before + instructs OpenTF to retry acquiring a lock for a period of time before 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 [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) -only, `terraform state mv` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +only, `opentf state mv` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). -The legacy options [`-backup` and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments) +The legacy options [`-backup` and `-backup-out`](/opentf/language/settings/backends/local#command-line-arguments) operate on a local state file only. Configurations using -[the `remote` backend](/terraform/language/settings/backends/remote) -must specify a local state file with the [`-state`](/terraform/language/settings/backends/local#command-line-arguments) -option in order to use the [`-backup` and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments) +[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) options. For configurations using -[the `local` state mv](/terraform/language/settings/backends/local) only, -`terraform state mv` also accepts the legacy options -[`-state`, `-state-out`, `-backup`, and `-backup-out`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` state mv](/opentf/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). ## Example: Rename a Resource @@ -94,12 +94,12 @@ Renaming a resource means making a configuration change like the following: } ``` -To tell Terraform that it should treat the new "helper" resource as a rename +To tell OpenTF that it should treat the new "helper" resource as a rename of the old "worker" resource, you can pair the above configuration change with the following command: ```shell -terraform state mv packet_device.worker packet_device.helper +opentf state mv packet_device.worker packet_device.helper ``` ## Example: Move a Resource Into a Module @@ -107,10 +107,10 @@ terraform state mv packet_device.worker packet_device.helper If you originally wrote a resource in your root module but now wish to refactor it into a child module, you can move the `resource` block into the child module configuration, removing the original in the root module, and then -run the following command to tell Terraform to treat it as a move: +run the following command to tell OpenTF to treat it as a move: ```shell -terraform state mv packet_device.worker module.worker.packet_device.worker +opentf state mv packet_device.worker module.worker.packet_device.worker ``` In the above example the new resource has the same name but a different module @@ -118,7 +118,7 @@ address. You could also change the resource name at the same time, if the new module organization suggests a different naming scheme: ```shell -terraform state mv packet_device.worker module.worker.packet_device.main +opentf state mv packet_device.worker module.worker.packet_device.main ``` ## Example: Move a Module Into a Module @@ -128,18 +128,18 @@ configuration, move the `module` block representing the module into a different module and then pair that change with a command like the following: ```shell -terraform state mv module.app module.parent.module.app +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](/terraform/language/meta-arguments/count) +A resource defined with [the `count` meta-argument](/opentf/language/meta-arguments/count) has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address: ```shell -$ terraform state mv 'packet_device.worker[0]' 'packet_device.helper[0]' +$ opentf state mv 'packet_device.worker[0]' 'packet_device.helper[0]' ``` A resource that doesn't use `count` or `for_each` has only a single resource @@ -149,16 +149,16 @@ or the opposite, as long as the address type you use matches whether and how each resource is configured: ```shell -$ terraform state mv 'packet_device.main' 'packet_device.all[0]' +$ opentf state mv 'packet_device.main' 'packet_device.all[0]' ``` Brackets (`[`, `]`) have a special meaning in some shells, so you may need to -quote or escape the address in order to pass it literally to Terraform. +quote or escape the address in order to pass it literally to OpenTF. 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](/terraform/language/meta-arguments/for_each) +A resource defined with [the `for_each` meta-argument](/opentf/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. @@ -170,19 +170,19 @@ quoting and/or escaping syntax for the shell you are using. For example: Unix-style shells, such as on Linux or macOS: ```shell -terraform state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]' +opentf state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]' ``` Windows Command Prompt (`cmd.exe`): ```shell -terraform state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"] +opentf state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"] ``` PowerShell: ```shell -terraform state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]' +opentf state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]' ``` Aside from the use of strings instead of integers for instance keys, the diff --git a/website/docs/cli/commands/state/pull.mdx b/website/docs/cli/commands/state/pull.mdx index 115b5c6c3f..5fd7cd39ce 100644 --- a/website/docs/cli/commands/state/pull.mdx +++ b/website/docs/cli/commands/state/pull.mdx @@ -1,30 +1,30 @@ --- page_title: 'Command: state pull' description: >- - The `terraform state pull` command is used to manually download and output the + The `opentf state pull` command is used to manually download and output the state from remote state. --- # Command: state pull -The `terraform state pull` command is used to manually download and output -the state from [remote state](/terraform/language/state/remote). This command also +The `opentf state pull` command is used to manually download and output +the state from [remote state](/opentf/language/state/remote). This command also works with local state. ## Usage -Usage: `terraform state pull` +Usage: `opentf state pull` This command downloads the state from its current location, upgrades the local copy to the latest state file version that is compatible with -locally-installed Terraform, and outputs the raw format to stdout. +locally-installed OpenTF, and outputs the raw format to stdout. This is useful for reading values out of state (potentially pairing this command with something like [jq](https://stedolan.github.io/jq/)). It is also useful if you need to make manual modifications to state. -You cannot use this command to inspect the Terraform version of -the remote state, as it will always be converted to the current Terraform +You cannot use this command to inspect the OpenTF version of +the remote state, as it will always be converted to the current OpenTF version before output. --> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state pull | sc terraform.tfstate`. +-> **Note:** OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state pull | sc opentf.tfstate`. diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx index 2372c5a713..a02b186f47 100644 --- a/website/docs/cli/commands/state/push.mdx +++ b/website/docs/cli/commands/state/push.mdx @@ -1,12 +1,12 @@ --- page_title: 'Command: state push' -description: The `terraform state push` command pushes items to the Terraform state. +description: The `opentf state push` command pushes items to the OpenTF state. --- # Command: state push -The `terraform state push` command is used to manually upload a local -state file to [remote state](/terraform/language/state/remote). This command also +The `opentf state push` command is used to manually upload a local +state file to [remote state](/opentf/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 @@ -14,27 +14,27 @@ manual intervention is necessary with the remote state. ## Usage -Usage: `terraform state push [options] PATH` +Usage: `opentf state push [options] PATH` This command pushes the state specified by PATH to the currently -configured [backend](/terraform/language/settings/backends/configuration). +configured [backend](/opentf/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 the destination state. --> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state push | sc terraform.tfstate`. +-> **Note:** OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state push | sc opentf.tfstate`. -Terraform will perform a number of safety checks to prevent you from +OpenTF will perform a number of safety checks to prevent you from making changes that appear to be unsafe: - **Differing lineage**: If the "lineage" value in the state differs, - Terraform will not allow you to push the state. A differing lineage + OpenTF will not allow you to push the state. A differing lineage suggests that the states are completely different and you may lose data. - **Higher remote serial**: If the "serial" value in the destination state - is higher than the state being pushed, Terraform will prevent the push. + is higher than the state being pushed, OpenTF will prevent the push. A higher serial suggests that data is in the destination state that isn't accounted for in the local state being pushed. @@ -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 [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) -only, `terraform state push` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +only, `opentf state push` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/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 1c6360119f..2f68092d23 100644 --- a/website/docs/cli/commands/state/replace-provider.mdx +++ b/website/docs/cli/commands/state/replace-provider.mdx @@ -1,18 +1,18 @@ --- page_title: 'Command: state replace-provider' description: >- - The `terraform state replace-provider` command replaces the provider for - resources in the Terraform state. + The `opentf state replace-provider` command replaces the provider for + resources in the OpenTF state. --- # Command: state replace-provider -The `terraform state replace-provider` command is used to replace the provider -for resources in a [Terraform state](/terraform/language/state). +The `opentf state replace-provider` command is used to replace the provider +for resources in a [OpenTF state](/opentf/language/state). ## Usage -Usage: `terraform state replace-provider [options] FROM_PROVIDER_FQN TO_PROVIDER_FQN` +Usage: `opentf state replace-provider [options] FROM_PROVIDER_FQN TO_PROVIDER_FQN` This command will update all resources using the "from" provider, setting the provider to the specified "to" provider. This allows changing the source of a @@ -32,20 +32,20 @@ This command also accepts the following options: - `-lock-timeout=0s` - Duration to retry a state lock. -For configurations using the [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) -only, `terraform state replace-provider` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +only, `opentf state replace-provider` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` state](/terraform/language/settings/backends/local) only, -`terraform state replace-provider` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` state](/opentf/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). ## Example The example below replaces the `hashicorp/aws` provider with a fork by `acme`, hosted at a private registry at `registry.acme.corp`: ```shell -$ terraform state replace-provider hashicorp/aws registry.acme.corp/acme/aws +$ opentf state replace-provider hashicorp/aws registry.acme.corp/acme/aws ``` diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.mdx index 7391f9abb0..bd8f330ab6 100644 --- a/website/docs/cli/commands/state/rm.mdx +++ b/website/docs/cli/commands/state/rm.mdx @@ -1,35 +1,35 @@ --- page_title: 'Command: state rm' description: >- - The `terraform state rm` command removes bindings from the Terraform state, - causing Terraform to "forget about" existing objects. + The `opentf state rm` command removes bindings from the OpenTF state, + causing OpenTF to "forget about" existing objects. --- # Command: state rm -The main function of [Terraform state](/terraform/language/state) is +The main function of [OpenTF state](/opentf/language/state) is to track the bindings between resource instance addresses in your configuration -and the remote objects they represent. Normally Terraform automatically +and the remote objects they represent. Normally OpenTF automatically updates the state in response to actions taken when applying a plan, such as removing a binding for a remote object that has now been deleted. -You can use `terraform state rm` in the less common situation where you wish +You can use `opentf state rm` in the less common situation where you wish to remove a binding to an existing remote object without first destroying it, -which will effectively make Terraform "forget" the object while it continues +which will effectively make OpenTF "forget" the object while it continues to exist in the remote system. ## Usage -Usage: `terraform state rm [options] ADDRESS...` +Usage: `opentf state rm [options] ADDRESS...` -Terraform will search the state for any instances matching the given -[resource address](/terraform/cli/state/resource-addressing), and remove -the record of each one so that Terraform will no longer be tracking the +OpenTF will search the state for any instances matching the given +[resource address](/opentf/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 -[`terraform plan`](/terraform/cli/commands/plan) +[`opentf plan`](/opentf/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 @@ -45,27 +45,27 @@ This command also accepts the following options: workspace. - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - instructs Terraform to retry acquiring a lock for a period of time before + instructs OpenTF to retry acquiring a lock for a period of time before 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 [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) -only, `terraform state rm` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +only, `opentf state rm` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` state rm](/terraform/language/settings/backends/local) only, -`terraform state rm` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` state rm](/opentf/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). ## Example: Remove all Instances of a Resource -The following example will cause Terraform to "forget" all of the instances +The following example will cause OpenTF to "forget" all of the instances of the `packet_device` resource named "worker". ```shell -$ terraform state rm 'packet_device.worker' +$ opentf state rm 'packet_device.worker' ``` A resource that doesn't use `count` or `for_each` has only one instance, so @@ -77,37 +77,37 @@ To select a resource that you've defined in a child module you must specify the path of that module as part of the resource address: ```shell -$ terraform state rm 'module.foo.packet_device.worker' +$ opentf state rm 'module.foo.packet_device.worker' ``` ## Example: Remove all Instances of all Resources in a Module -The following example will cause Terraform to "forget" all of the instances +The following example will cause OpenTF to "forget" all of the instances associated with all resources defined in all instances of the module named `foo`: ```shell -$ terraform state rm 'module.foo' +$ opentf state rm 'module.foo' ``` ## Example: Remove a Particular Instance of a Resource using `count` -A resource defined with [the `count` meta-argument](/terraform/language/meta-arguments/count) +A resource defined with [the `count` meta-argument](/opentf/language/meta-arguments/count) has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address: ```shell -$ terraform state rm 'packet_device.worker[0]' +$ opentf state rm 'packet_device.worker[0]' ``` Brackets (`[`, `]`) have a special meaning in some shells, so you may need to -quote or escape the address in order to pass it literally to Terraform. +quote or escape the address in order to pass it literally to OpenTF. 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](/terraform/language/meta-arguments/for_each) +A resource defined with [the `for_each` meta-argument](/opentf/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. @@ -119,17 +119,17 @@ quoting and/or escaping syntax for the shell you are using. For example: Unix-style shells, such as on Linux or macOS: ```shell -$ terraform state rm 'packet_device.worker["example"]' +$ opentf state rm 'packet_device.worker["example"]' ``` Windows Command Prompt (`cmd.exe`): ```shell -$ terraform state rm packet_device.worker[\"example\"] +$ opentf state rm packet_device.worker[\"example\"] ``` PowerShell: ```shell -$ terraform state rm 'packet_device.worker[\"example\"]' +$ opentf state rm 'packet_device.worker[\"example\"]' ``` diff --git a/website/docs/cli/commands/state/show.mdx b/website/docs/cli/commands/state/show.mdx index b646362003..bfe64b8d6c 100644 --- a/website/docs/cli/commands/state/show.mdx +++ b/website/docs/cli/commands/state/show.mdx @@ -1,35 +1,35 @@ --- page_title: 'Command: state show' description: >- - The `terraform state show` command is used to show the attributes of a single - resource in the Terraform state. + The `opentf state show` command is used to show the attributes of a single + resource in the OpenTF state. --- # Command: state show -The `terraform state show` command is used to show the attributes of a +The `opentf state show` command is used to show the attributes of a single resource in the -[Terraform state](/terraform/language/state). +[OpenTF state](/opentf/language/state). ## Usage -Usage: `terraform state show [options] ADDRESS` +Usage: `opentf state show [options] ADDRESS` The command will show the attributes of a single resource in the 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](/terraform/cli/state/resource-addressing). +in [resource addressing format](/opentf/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 "terraform.tfstate". - Ignored when [remote state](/terraform/language/state/remote) is used. +* `-state=path` - Path to the state file. Defaults to "opentf.tfstate". + Ignored when [remote state](/opentf/language/state/remote) is used. -The output of `terraform state show` is intended for human consumption, not +The output of `opentf state show` is intended for human consumption, not programmatic consumption. To extract state data for use in other software, use -[`terraform show -json`](/terraform/cli/commands/show#json-output) and decode the result +[`opentf show -json`](/opentf/cli/commands/show#json-output) and decode the result using the documented structure. ## Example: Show a Resource @@ -37,7 +37,7 @@ using the documented structure. The example below shows a `packet_device` resource named `worker`: ``` -$ terraform state show 'packet_device.worker' +$ opentf state show 'packet_device.worker' # packet_device.worker: resource "packet_device" "worker" { billing_cycle = "hourly" @@ -54,36 +54,36 @@ resource "packet_device" "worker" { The example below shows a `packet_device` resource named `worker` inside a module named `foo`: ```shell -$ terraform state show 'module.foo.packet_device.worker' +$ 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`](/terraform/language/meta-arguments/count): +[`count`](/opentf/language/meta-arguments/count): ```shell -$ terraform state show 'packet_device.worker[0]' +$ 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`](/terraform/language/meta-arguments/for_each) meta-argument. You must place the resource name in single quotes when it contains special characters like double quotes. +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. Linux, Mac OS, and UNIX: ```shell -$ terraform state show 'packet_device.worker["example"]' +$ opentf state show 'packet_device.worker["example"]' ``` PowerShell: ```shell -$ terraform state show 'packet_device.worker[\"example\"]' +$ opentf state show 'packet_device.worker[\"example\"]' ``` Windows `cmd.exe`: ```shell -$ terraform state show packet_device.worker[\"example\"] +$ opentf state show packet_device.worker[\"example\"] ``` diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index c96a43713a..34fc4b4363 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -1,38 +1,38 @@ --- page_title: 'Command: taint' description: |- - The `terraform taint` command informs Terraform that a particular object + The `opentf taint` command informs OpenTF that a particular object is damaged or degraded. --- # Command: taint -The `terraform taint` command informs Terraform that a particular object has -become degraded or damaged. Terraform represents this by marking the -object as "tainted" in the Terraform state, and Terraform will +The `opentf taint` command informs OpenTF that a particular object has +become degraded or damaged. OpenTF represents this by marking the +object as "tainted" in the OpenTF state, and OpenTF will propose to replace it in the next plan you create. -~> **Warning:** This command is deprecated. For Terraform v0.15.2 and later, we recommend using the `-replace` option with `terraform apply` instead (details below). +~> **Warning:** This command is deprecated, we recommend using the `-replace` option with `opentf apply` instead (details below). ## Recommended Alternative -For Terraform v0.15.2 and later, we recommend using the [`-replace` option](/terraform/cli/commands/plan#replace-address) with `terraform apply` to force Terraform to replace an object even though there are no configuration changes that would require it. +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. ``` -$ terraform apply -replace="aws_instance.example[0]" +$ opentf apply -replace="aws_instance.example[0]" ``` -We recommend the `-replace` option because the change will be reflected in the Terraform plan, letting you understand how it will affect your infrastructure before you take any externally-visible action. When you use `terraform taint`, other users could create a new plan against your tainted object before you can review the effects. +We recommend the `-replace` option because the change will be reflected in the OpenTF plan, letting you understand how it will affect your infrastructure before you take any externally-visible action. When you use `opentf taint`, other users could create a new plan against your tainted object before you can review the effects. ## Usage ``` -$ terraform taint [options]
+$ opentf taint [options]
``` The `address` argument is the address of the resource to mark as tainted. The address is in -[the resource address syntax](/terraform/cli/state/resource-addressing), +[the resource address syntax](/opentf/cli/state/resource-addressing), as shown in the output from other commands, such as: - `aws_instance.foo` @@ -47,19 +47,19 @@ This command accepts the following options: for other situations, such as if there is a problem reading or writing the state. -- `-lock=false` - Disables Terraform's default behavior of attempting to take +- `-lock=false` - Disables OpenTF's default behavior of attempting to take a read/write lock on the state for the duration of the operation. - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - instructs Terraform to retry acquiring a lock for a period of time before + instructs OpenTF to retry acquiring a lock for a period of time before 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 [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) only, `terraform taint` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) only, `opentf taint` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` backend](/terraform/language/settings/backends/local) only, -`terraform taint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` backend](/opentf/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). diff --git a/website/docs/cli/commands/test.mdx b/website/docs/cli/commands/test.mdx index 57f9e9dc02..e404025cef 100644 --- a/website/docs/cli/commands/test.mdx +++ b/website/docs/cli/commands/test.mdx @@ -5,8 +5,8 @@ description: Part of the ongoing design research for module integration testing. # Command: test -The `terraform test` command is currently serving as part of -[the module integration testing experiment](/terraform/language/modules/testing-experiment). +The `opentf test` command is currently serving as part of +[the module integration testing experiment](/opentf/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 98fb32a2d5..145168e7da 100644 --- a/website/docs/cli/commands/untaint.mdx +++ b/website/docs/cli/commands/untaint.mdx @@ -1,27 +1,27 @@ --- page_title: 'Command: untaint' description: |- - The `terraform untaint` command tells Terraform that an object is functioning + The `opentf untaint` command tells OpenTF that an object is functioning correctly, even though its creation failed or it was previously manually marked as degraded. --- # Command: untaint -Terraform has a marker called "tainted" which it uses to track that an object -might be damaged and so a future Terraform plan ought to replace it. +OpenTF has a marker called "tainted" which it uses to track that an object +might be damaged and so a future OpenTF plan ought to replace it. -Terraform automatically marks an object as "tainted" if an error occurs during -a multi-step "create" action, because Terraform can't be sure that the object +OpenTF automatically marks an object as "tainted" if an error occurs during +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 -[`terraform taint`](/terraform/cli/commands/taint), although we no longer recommend that +[`opentf taint`](/opentf/cli/commands/taint), although we no longer recommend that workflow. -If Terraform currently considers a particular object as tainted but you've +If OpenTF currently considers a particular object as tainted but you've determined that it's actually functioning correctly and need _not_ be replaced, -you can use `terraform untaint` to remove the taint marker from that object. +you can use `opentf untaint` to remove the taint marker from that object. This command _will not_ modify any real remote objects, but will modify the state in order to remove the tainted status. @@ -31,14 +31,14 @@ was degraded after all, you can create and apply a plan to replace it without first re-tainting the object, by using a command like the following: ``` -terraform apply -replace="aws_instance.example[0]" +opentf apply -replace="aws_instance.example[0]" ``` ## Usage -Usage: `terraform untaint [options] address` +Usage: `opentf untaint [options] address` -The `address` argument is a [resource address](/terraform/cli/state/resource-addressing) +The `address` argument is a [resource address](/opentf/cli/state/resource-addressing) identifying a particular resource instance which is currently tainted. This command also accepts the following options: @@ -53,20 +53,20 @@ This command also accepts the following options: workspace. - `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, - instructs Terraform to retry acquiring a lock for a period of time before + instructs OpenTF to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. - `-no-color` - Disables terminal formatting sequences in the output. Use this - if you are running Terraform in a context where its output will be + 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 [Terraform Cloud CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/settings/backends/remote) -only, `terraform untaint` +For configurations using the [`cloud` backend](/opentf/cli/cloud) or the [`remote` backend](/opentf/language/settings/backends/remote) +only, `opentf untaint` also accepts the option -[`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). +[`-ignore-remote-version`](/opentf/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using -[the `local` backend](/terraform/language/settings/backends/local) only, -`terraform untaint` also accepts the legacy options -[`-state`, `-state-out`, and `-backup`](/terraform/language/settings/backends/local#command-line-arguments). +[the `local` backend](/opentf/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). diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.mdx index 1ae22f36b1..a598202ffb 100644 --- a/website/docs/cli/commands/validate.mdx +++ b/website/docs/cli/commands/validate.mdx @@ -1,13 +1,13 @@ --- page_title: 'Command: validate' description: >- - The `terraform validate` command is used to validate the syntax of the - terraform files. + The `opentf validate` command is used to validate the syntax of the + opentf files. --- # Command: validate -The `terraform validate` command validates the configuration files in a +The `opentf validate` command validates the configuration files in a directory, referring only to the configuration and not accessing any remote services such as remote state, provider APIs, etc. @@ -23,16 +23,16 @@ system. Validation requires an initialized working directory with any referenced plugins and modules installed. To initialize a working directory for validation without accessing any configured backend, use: ``` -$ terraform init -backend=false +$ opentf init -backend=false ``` To verify configuration in the context of a particular run (a particular -target workspace, input variable values, etc), use the `terraform plan` +target workspace, input variable values, etc), use the `opentf plan` command instead, which includes an implied validation check. ## Usage -Usage: `terraform validate [options]` +Usage: `opentf validate [options]` This command accepts the following options: @@ -44,17 +44,17 @@ This command accepts the following options: ## JSON Output Format -When you use the `-json` option, Terraform will produce validation results +When you use the `-json` option, OpenTF will produce validation results in JSON format to allow using the validation result for tool integrations, such as highlighting errors in a text editor. -As with all JSON output options, it's possible that Terraform will encounter +As with all JSON output options, it's possible that OpenTF will encounter an error prior to beginning the validation task that will thus not be subject to the JSON output setting. For that reason, external software consuming -Terraform's output should be prepared to find data on stdout that _isn't_ valid +OpenTF's output should be prepared to find data on stdout that _isn't_ valid JSON, which it should then treat as a generic error case. -The output includes a `format_version` key, which as of Terraform 1.1.0 has +The output includes a `format_version` key, which has value `"1.0"`. The semantics of this version are: * We will increment the minor version, e.g. `"1.1"`, for backward-compatible @@ -65,43 +65,43 @@ value `"1.0"`. The semantics of this version are: version. We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). +[the OpenTF 1.0 Compatibility Promises](/opentf/language/v1-compatibility-promises). -In the normal case, Terraform will print a JSON object to the standard output +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: - `valid` (boolean): Summarizes the overall validation result, by indicating - `true` if Terraform considers the current configuration to be valid or + `true` if OpenTF considers the current configuration to be valid or `false` if it detected any errors. - `error_count` (number): A zero or positive whole number giving the count - of errors Terraform detected. If `valid` is `true` then `error_count` will + of errors OpenTF detected. If `valid` is `true` then `error_count` will always be zero, because it is the presence of errors that indicates that a configuration is invalid. - `warning_count` (number): A zero or positive whole number giving the count - of warnings Terraform detected. Warnings do not cause Terraform to consider + of warnings OpenTF detected. Warnings do not cause OpenTF to consider a configuration to be invalid, but they do indicate potential caveats that a user should consider and possibly resolve. - `diagnostics` (array of objects): A JSON array of nested objects that each - describe an error or warning from Terraform. + describe an error or warning from OpenTF. The nested objects in `diagnostics` have the following properties: - `severity` (string): A string keyword, either `"error"` or `"warning"`, indicating the diagnostic severity. - The presence of errors causes Terraform to consider a configuration to be + The presence of errors causes OpenTF to consider a configuration to be invalid, while warnings are just advice or caveats to the user which do not - block working with the configuration. Later versions of Terraform may + block working with the configuration. Later versions of OpenTF may introduce new severity keywords, so consumers should be prepared to accept and ignore severity values they don't understand. - `summary` (string): A short description of the nature of the problem that the diagnostic is reporting. - In Terraform's usual human-oriented diagnostic messages, the summary serves + In OpenTF's usual human-oriented diagnostic messages, the summary serves as a sort of "heading" for the diagnostic, printed after the "Error:" or "Warning:" indicator. @@ -114,7 +114,7 @@ The nested objects in `diagnostics` have the following properties: - `detail` (string): An optional additional message giving more detail about the problem. - In Terraform's usual human-oriented diagnostic messages, the detail provides + In OpenTF's usual human-oriented diagnostic messages, the detail provides the paragraphs of text that appear after the heading and the source location reference. @@ -125,7 +125,7 @@ The nested objects in `diagnostics` have the following properties: text. Renderers should then soft-wrap the paragraphs to fit the width of the rendering container, but leave the preformatted lines unwrapped. - Some Terraform detail messages contain an approximation of bullet + Some OpenTF detail messages contain an approximation of bullet lists using ASCII characters to mark the bullets. This is not a contractural formatting convention, so renderers should avoid depending on it and should instead treat those lines as either paragraphs or preformatted @@ -155,7 +155,7 @@ The nested objects in `diagnostics` have the following properties: expression which triggered the diagnostic. For some diagnostics this information is not available, and then this property will be `null`. - - `code` (string): A snippet of Terraform configuration including the + - `code` (string): A snippet of OpenTF configuration including the source of the diagnostic. This can be multiple lines and may include additional configuration source code around the expression which triggered the diagnostic. @@ -210,4 +210,4 @@ exactly which values are responsible for an error. The object has two properties - `statement` (string): A short English-language fragment describing the value of the expression when the diagnostic was triggered. The contents of this string are intended to be human-readable and are subject to change in future - versions of Terraform. + versions of OpenTF. diff --git a/website/docs/cli/commands/version.mdx b/website/docs/cli/commands/version.mdx index 378ec3ae79..632c2c2716 100644 --- a/website/docs/cli/commands/version.mdx +++ b/website/docs/cli/commands/version.mdx @@ -1,54 +1,47 @@ --- page_title: 'Command: version' description: >- - The terraform version command displays the Terraform version and the version + The opentf version command displays the OpenTF version and the version of all installed plugins. --- # Command: version -The `terraform version` displays the current version of Terraform and all +The `opentf version` displays the current version of OpenTF and all installed plugins. ## Usage -Usage: `terraform version [options]` +Usage: `opentf version [options]` -With no additional arguments, `version` will display the version of Terraform, -the platform it's installed on, installed providers, and the results of upgrade -and security checks [unless disabled](/terraform/cli/commands#upgrade-and-security-bulletin-checks). +With no additional arguments, `version` will display the version of OpenTF, +the platform it's installed on, and installed providers. This command has one optional flag: * `-json` - If specified, the version information is formatted as a JSON object, and no upgrade or security information is included. --> **Note:** Platform information was added to the `version` command in Terraform 0.15. - ## Example -Basic usage, with upgrade and security information shown if relevant: +Basic usage, with security information shown if relevant: ```shellsession -$ terraform version -Terraform v0.15.0 +$ opentf version +OpenTF v1.6.0 on darwin_amd64 + provider registry.terraform.io/hashicorp/null v3.0.0 - -Your version of Terraform is out of date! The latest version -is X.Y.Z. You can update by downloading from https://www.terraform.io/downloads.html ``` As JSON: ```shellsession -$ terraform version -json +$ opentf version -json { "terraform_version": "0.15.0", "platform": "darwin_amd64", "provider_selections": { "registry.terraform.io/hashicorp/null": "3.0.0" - }, - "terraform_outdated": true + } } ``` diff --git a/website/docs/cli/commands/workspace/delete.mdx b/website/docs/cli/commands/workspace/delete.mdx index 8475440c61..2dbcb1f1ef 100644 --- a/website/docs/cli/commands/workspace/delete.mdx +++ b/website/docs/cli/commands/workspace/delete.mdx @@ -1,35 +1,35 @@ --- page_title: 'Command: workspace delete' -description: The terraform workspace delete command is used to delete a workspace. +description: The opentf workspace delete command is used to delete a workspace. --- # Command: workspace delete -The `terraform workspace delete` command is used to delete an existing workspace. +The `opentf workspace delete` command is used to delete an existing workspace. ## Usage -Usage: `terraform workspace delete [OPTIONS] NAME [DIR]` +Usage: `opentf workspace delete [OPTIONS] NAME [DIR]` This command will delete the specified workspace. 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, -Terraform will not allow you to delete it unless the `-force` flag is specified. +OpenTF will not allow you to delete it unless the `-force` flag is specified. -Additionally, different [backends](/terraform/language/settings/backends/configuration#backend-types) may implement other +Additionally, different [backends](/opentf/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 may become "dangling". These are resources that physically exist but that -Terraform can no longer manage. This is sometimes preferred: you may want -Terraform to stop managing resources, so they can be managed some other way. -Most of the time, however, this is not intended and so Terraform protects you +OpenTF can no longer manage. This is sometimes preferred: you may want +OpenTF to stop managing resources, so they can be managed some other way. +Most of the time, however, this is not intended and so OpenTF protects you from getting into this situation. The command-line flags are all optional. The only supported flags are: -* `-force` - Delete the workspace even if it is tracking resources. After deletion, Terraform can no longer track or manage the workspace's infrastructure. Defaults to false. +* `-force` - Delete the workspace even if it is tracking resources. After deletion, OpenTF can no longer track or manage the workspace's infrastructure. Defaults to false. * `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. @@ -38,6 +38,6 @@ The command-line flags are all optional. The only supported flags are: ## Example ``` -$ terraform workspace delete example +$ opentf workspace delete example Deleted workspace "example". ``` diff --git a/website/docs/cli/commands/workspace/index.mdx b/website/docs/cli/commands/workspace/index.mdx index d3a9798f6d..3060ed77d1 100644 --- a/website/docs/cli/commands/workspace/index.mdx +++ b/website/docs/cli/commands/workspace/index.mdx @@ -5,13 +5,13 @@ description: The workspace command helps you manage workspaces. # Command: workspace -The `terraform workspace` command is used to manage -[workspaces](/terraform/language/state/workspaces). +The `opentf workspace` command is used to manage +[workspaces](/opentf/language/state/workspaces). This command is a container for further subcommands that each have their own page in the documentation. ## Usage -Usage: `terraform workspace [options] [args]` +Usage: `opentf workspace [options] [args]` Choose a subcommand page for more information. diff --git a/website/docs/cli/commands/workspace/list.mdx b/website/docs/cli/commands/workspace/list.mdx index d7d2e6eee2..a767ee86d3 100644 --- a/website/docs/cli/commands/workspace/list.mdx +++ b/website/docs/cli/commands/workspace/list.mdx @@ -1,15 +1,15 @@ --- page_title: 'Command: workspace list' -description: The terraform workspace list command is used to list all existing workspaces. +description: The opentf workspace list command is used to list all existing workspaces. --- # Command: workspace list -The `terraform workspace list` command is used to list all existing workspaces. +The `opentf workspace list` command is used to list all existing workspaces. ## Usage -Usage: `terraform workspace list [DIR]` +Usage: `opentf workspace list [DIR]` The command will list all existing workspaces. The current workspace is indicated using an asterisk (`*`) marker. @@ -17,7 +17,7 @@ indicated using an asterisk (`*`) marker. ## Example ``` -$ terraform workspace list +$ opentf workspace list default * development jsmith-test diff --git a/website/docs/cli/commands/workspace/new.mdx b/website/docs/cli/commands/workspace/new.mdx index 28b4d1c30d..c2a7e3b754 100644 --- a/website/docs/cli/commands/workspace/new.mdx +++ b/website/docs/cli/commands/workspace/new.mdx @@ -1,15 +1,15 @@ --- page_title: 'Command: workspace new' -description: The terraform workspace new command is used to create a new workspace. +description: The opentf workspace new command is used to create a new workspace. --- # Command: workspace new -The `terraform workspace new` command is used to create a new workspace. +The `opentf workspace new` command is used to create a new workspace. ## Usage -Usage: `terraform workspace new [OPTIONS] NAME [DIR]` +Usage: `opentf workspace new [OPTIONS] NAME [DIR]` This command will create a new workspace with the given name. A workspace with this name must not already exist. @@ -28,11 +28,11 @@ The command-line flags are all optional. The supported flags are: ## Example: Create ``` -$ terraform workspace new example +$ opentf workspace new example Created and switched to workspace "example"! You're now on a new, empty workspace. Workspaces isolate their state, -so if you run "terraform plan" Terraform will not see any existing state +so if you run "opentf plan" OpenTF will not see any existing state for this configuration. ``` @@ -41,10 +41,10 @@ for this configuration. To create a new workspace from a pre-existing local state file: ``` -$ terraform workspace new -state=old.terraform.tfstate example +$ opentf workspace new -state=old.opentf.tfstate example Created and switched to workspace "example". You're now on a new, empty workspace. Workspaces isolate their state, -so if you run "terraform plan" Terraform will not see any existing state +so if you run "opentf plan" OpenTF will not see any existing state for this configuration. ``` diff --git a/website/docs/cli/commands/workspace/select.mdx b/website/docs/cli/commands/workspace/select.mdx index 497a565446..f733284c56 100644 --- a/website/docs/cli/commands/workspace/select.mdx +++ b/website/docs/cli/commands/workspace/select.mdx @@ -1,16 +1,16 @@ --- page_title: 'Command: workspace select' -description: The terraform workspace select command is used to choose a workspace. +description: The opentf workspace select command is used to choose a workspace. --- # Command: workspace select -The `terraform workspace select` command is used to choose a different +The `opentf workspace select` command is used to choose a different workspace to use for further operations. ## Usage -Usage: `terraform workspace select NAME [DIR]` +Usage: `opentf workspace select NAME [DIR]` This command will select another workspace. The named workspace must already exist. @@ -22,11 +22,11 @@ The supported flags are: ## Example ``` -$ terraform workspace list +$ opentf workspace list default * development jsmith-test -$ terraform workspace select default +$ opentf workspace select default Switched to workspace "default". ``` diff --git a/website/docs/cli/commands/workspace/show.mdx b/website/docs/cli/commands/workspace/show.mdx index c6063f22fd..897fa0d92c 100644 --- a/website/docs/cli/commands/workspace/show.mdx +++ b/website/docs/cli/commands/workspace/show.mdx @@ -1,21 +1,21 @@ --- page_title: 'Command: workspace show' -description: The terraform workspace show command is used to output the current workspace. +description: The opentf workspace show command is used to output the current workspace. --- # Command: workspace show -The `terraform workspace show` command is used to output the current workspace. +The `opentf workspace show` command is used to output the current workspace. ## Usage -Usage: `terraform workspace show` +Usage: `opentf workspace show` The command will display the current workspace. ## Example ``` -$ terraform workspace show +$ opentf workspace show development ``` diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.mdx index da9d4be2a6..e16a3757c4 100644 --- a/website/docs/cli/config/config-file.mdx +++ b/website/docs/cli/config/config-file.mdx @@ -8,8 +8,8 @@ description: >- # CLI Configuration File (`.opentfrc` or `opentf.rc`) The CLI configuration file configures per-user settings for CLI behaviors, -which apply across all Terraform working directories. This is separate from -[your infrastructure configuration](/terraform/language). +which apply across all OpenTF working directories. This is separate from +[your infrastructure configuration](/opentf/language). ## Locations @@ -34,8 +34,8 @@ CLI configuration file, even though Windows Explorer may _display_ its name as just `opentf.rc`. Use `dir` from PowerShell or Command Prompt to confirm the filename. -The location of the Terraform CLI configuration file can also be specified -using the `TF_CLI_CONFIG_FILE` [environment variable](/terraform/cli/config/environment-variables). +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). Any such file should follow the naming pattern `*.tfrc`. ## Configuration File Syntax @@ -53,12 +53,11 @@ plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" The following settings can be set in the CLI configuration file: -* `credentials` - configures credentials for use with Terraform Cloud or - Terraform Enterprise. See [Credentials](#credentials) below for more - information. +* `credentials` - configures credentials for use with a cloud backend. + See [Credentials](#credentials) below for more information. * `credentials_helper` - configures an external helper program for the storage - and retrieval of credentials for Terraform Cloud or Terraform Enterprise. + and retrieval of credentials for cloud backends. See [Credentials Helpers](#credentials-helpers) below for more information. * `plugin_cache_dir` — enables @@ -66,59 +65,38 @@ The following settings can be set in the CLI configuration file: and specifies, as a string, the location of the plugin cache directory. * `provider_installation` - customizes the installation methods used by - `terraform init` when installing provider plugins. See + `opentf init` when installing provider plugins. See [Provider Installation](#provider-installation) below for more information. ## Credentials -[Terraform Cloud](https://cloud.hashicorp.com/products/terraform) provides a number of remote network -services for use with Terraform, and -[Terraform Enterprise](/terraform/enterprise) allows hosting those -services inside your own infrastructure. For example, these systems offer both -[remote operations](/terraform/cloud-docs/run/cli) and a -[private module registry](/terraform/cloud-docs/registry). - -When interacting with Terraform-specific network services, Terraform expects +When interacting with OpenTF-specific network services, OpenTF expects to find API tokens in CLI configuration files in `credentials` blocks: ```hcl -credentials "app.terraform.io" { +credentials "app.placeholderplaceholderplaceholder.io" { token = "xxxxxx.atlasv1.zzzzzzzzzzzzz" } ``` -If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/terraform/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](/opentf/cli/commands/login) to get credentials and automatically save them in the CLI configuration. If not, you can manually write `credentials` blocks. You can have multiple `credentials` blocks if you regularly use services from -multiple hosts. Many users will configure only one, for either -Terraform Cloud (at `app.terraform.io`) or for their organization's own -Terraform Enterprise host. Each `credentials` block contains a `token` argument +multiple hosts. Each `credentials` block contains a `token` argument giving the API token to use for that host. -~> **Important:** If you are using Terraform Cloud or Terraform Enterprise, -the token provided must be either a -[user token](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) -or a -[team token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens); -organization tokens cannot be used for command-line Terraform actions. - -> **Note:** The credentials hostname must match the hostname in your module -sources and/or backend configuration. If your Terraform Enterprise instance -is available at multiple hostnames, use only one of them consistently. -Terraform Cloud responds to API calls at both its current hostname -`app.terraform.io`, and its historical hostname `atlas.hashicorp.com`. +sources and/or backend configuration. ### Environment Variable Credentials --> **Note:** Environment variable credentials are supported in Terraform v1.2.0 and later. - If you would prefer not to store your API tokens directly in the CLI configuration, you may use a host-specific environment variable. Environment variable names should have the prefix `TF_TOKEN_` added to the domain name, with periods encoded as underscores. For example, the -value of a variable named `TF_TOKEN_app_terraform_io` will be used as a bearer authorization -token when the CLI makes service requests to the hostname `app.terraform.io`. +value of a variable named `TF_TOKEN_app_placeholderplaceholderplaceholder_io` will be used as a bearer authorization +token when the CLI makes service requests to the hostname `app.placeholderplaceholderplaceholder.io`. You must convert domain names containing non-ASCII characters to their [punycode equivalent](https://www.charset.org/punycode) with an ACE prefix. For example, token credentials for 例えば.com must be set in a variable @@ -127,12 +105,12 @@ called `TF_TOKEN_xn--r8j3dr99h_com`. Hyphens are also valid within host names but usually invalid as variable names and may be encoded as double underscores. For example, you can set a token for the domain name `café.fr` as `TF_TOKEN_xn--caf-dma.fr`, `TF_TOKEN_xn--caf-dma_fr`, or `TF_TOKEN_xn____caf__dma_fr`. -If multiple variables evaluate to the same hostname, Terraform will choose the one defined last +If multiple variables evaluate to the same hostname, OpenTF will choose the one defined last in the operating system's variable table. ### Credentials Helpers -You can configure a `credentials_helper` to instruct Terraform to use a different credentials storage mechanism. +You can configure a `credentials_helper` to instruct OpenTF to use a different credentials storage mechanism. ```hcl credentials_helper "example" { @@ -153,43 +131,39 @@ Conversely, this means you can override the credentials returned by the helper for a specific hostname by writing a `credentials` block alongside the `credentials_helper` block. -Terraform does not include any credentials helpers in the main distribution. +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](/terraform/internals/credentials-helpers). +[the guide to Credentials Helper internals](/opentf/internals/credentials-helpers). ### Credentials Source Priority Order Credentials found in an environment variable for a particular service host -as described above will be preferred over those in CLI config as set by `terraform login`. +as described above will be preferred over those in CLI config as set by `opentf login`. If neither are set, any configured credentials helper will be consulted. -~> **Note:** For users of [terraform-credentials-helper](https://github.com/apparentlymart/terraform-credentials-env), this priority has been effectively reversed following the -release of Terraform 1.2. Previously, credentials found within CLI config or set by -`terraform login` were preferred to `TF_TOKEN_*` variables. - ## Provider Installation The default way to install provider plugins is from a provider registry. The origin registry for a provider is encoded in the provider's source address, like `registry.terraform.io/hashicorp/aws`. For convenience in the common case, -Terraform allows omitting the hostname portion for providers on +OpenTF allows omitting the hostname portion for providers on `registry.terraform.io`, so you can write shorter public provider addresses like `hashicorp/aws`. Downloading a plugin directly from its origin registry is not always -appropriate, though. For example, the system where you are running Terraform +appropriate, though. For example, the system where you are running OpenTF may not be able to access an origin registry due to firewall restrictions within your organization or your locality. -To allow using Terraform providers in these situations, there are some -alternative options for making provider plugins available to Terraform which +To allow using OpenTF providers in these situations, there are some +alternative options for making provider plugins available to OpenTF which we'll describe in the following sections. ### Explicit Installation Method Configuration A `provider_installation` block in the CLI configuration allows overriding -Terraform's default installation behaviors, so you can force Terraform to use +OpenTF's default installation behaviors, so you can force OpenTF to use a local mirror for some or all of the providers you intend to use. The general structure of a `provider_installation` block is as follows: @@ -238,7 +212,7 @@ The following are the two supported installation method types: providers. This method requires the additional argument `path` to indicate which directory to look in. - Terraform expects the given directory to contain a nested directory structure + OpenTF expects the given directory to contain a nested directory structure where the path segments together provide metadata about the available providers. The following two directory structures are supported: @@ -251,10 +225,10 @@ The following are the two supported installation method types: specifies a particular target platform using a format like `darwin_amd64`, `linux_arm`, `windows_amd64`, etc. - If you use the unpacked layout, Terraform will attempt to create a symbolic + If you use the unpacked layout, OpenTF will attempt to create a symbolic link to the mirror directory when installing the provider, rather than creating a deep copy of the directory. The packed layout prevents this - because Terraform must extract the zip file during installation. + because OpenTF must extract the zip file during installation. You can include multiple `filesystem_mirror` blocks in order to specify several different directories to search. @@ -264,8 +238,8 @@ The following are the two supported installation method types: additional argument `url` to indicate the mirror base URL, which should use the `https:` scheme and end with a trailing slash. - Terraform expects the given URL to be a base URL for an implementation of - [the provider network mirror protocol](/terraform/internals/provider-network-mirror-protocol), + 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), which is designed to be relatively easy to implement using typical static website hosting mechanisms. @@ -274,23 +248,23 @@ Provider mirror servers are subject to TLS certificate checks to verify identity, but a network mirror with a TLS certificate can potentially serve modified copies of upstream providers with malicious content. -Terraform will try all of the specified methods whose include and exclude +OpenTF will try all of the specified methods whose include and exclude patterns match a given provider, and select the newest version available across all of those methods that matches the version constraint given in each -Terraform configuration. If you have a local mirror of a particular provider -and intend Terraform to use that local mirror exclusively, you must either +OpenTF configuration. If you have a local mirror of a particular provider +and intend OpenTF to use that local mirror exclusively, you must either remove the `direct` installation method altogether or use its `exclude` argument to disable its use for specific providers. ### Implied Local Mirror Directories If your CLI configuration does not include a `provider_installation` block at -all, Terraform produces an _implied_ configuration. The implied configuration +all, OpenTF produces an _implied_ configuration. The implied configuration includes a selection of `filesystem_mirror` methods and then the `direct` method. -The set of directories Terraform can select as filesystem mirrors depends on -the operating system where you are running Terraform: +The set of directories OpenTF can select as filesystem mirrors depends on +the operating system where you are running OpenTF: * **Windows:** `%APPDATA%/terraform.d/plugins` and `%APPDATA%/HashiCorp/Terraform/plugins` * **Mac OS X:** `$HOME/.terraform.d/plugins`, @@ -300,21 +274,21 @@ the operating system where you are running Terraform: `terraform/plugins` located within a valid [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) data directory such as `$XDG_DATA_HOME/terraform/plugins`. - Without any XDG environment variables set, Terraform will use + Without any XDG environment variables set, OpenTF will use `~/.local/share/terraform/plugins`, `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`. If a `terraform.d/plugins` directory exists in the current working directory -then Terraform will also include that directory, regardless of your operating -system. This behavior changes when you use the `-chdir` option with the `init` command. In that case, Terraform checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`. +then OpenTF will also include that directory, regardless of your operating +system. This behavior changes when you use the `-chdir` option with the `init` command. In that case, OpenTF checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`. -Terraform will check each of the paths above to see if it exists, and if so +OpenTF will check each of the paths above to see if it exists, and if so treat it as a filesystem mirror. The directory structure inside each one must therefore match one of the two structures described for `filesystem_mirror` blocks in [Explicit Installation Method Configuration](#explicit-installation-method-configuration). -In addition to the zero or more implied `filesystem_mirror` blocks, Terraform -also creates an implied `direct` block. Terraform will scan all of the +In addition to the zero or more implied `filesystem_mirror` blocks, OpenTF +also creates an implied `direct` block. OpenTF will scan all of the filesystem mirror directories to see which providers are placed there and automatically exclude all of those providers from the implied `direct` block. (This automatic `exclude` behavior applies only to _implicit_ `direct` blocks; @@ -323,14 +297,14 @@ exclusions out yourself.) ### Provider Plugin Cache -By default, `terraform init` downloads plugins into a subdirectory of the +By default, `opentf init` downloads plugins into a subdirectory of the working directory so that each working directory is self-contained. As a consequence, if you have multiple configurations that use the same provider then a separate copy of its plugin will be downloaded for each configuration. Given that provider plugins can be quite large (on the order of hundreds of megabytes), this default behavior can be inconvenient for those with slow -or metered Internet connections. Therefore Terraform optionally allows the +or metered Internet connections. Therefore OpenTF optionally allows the use of a local directory as a shared plugin cache, which then allows each distinct plugin binary to be downloaded only once. @@ -341,8 +315,8 @@ the CLI configuration file. For example: plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" ``` -This directory must already exist before Terraform will cache plugins; -Terraform will not create the directory itself. +This directory must already exist before OpenTF will cache plugins; +OpenTF will not create the directory itself. Please note that on Windows it is necessary to use forward slash separators (`/`) rather than the conventional backslash (`\`) since the configuration @@ -357,16 +331,16 @@ directory within a particular shell session: export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache" ``` -When a plugin cache directory is enabled, the `terraform init` command will +When a plugin cache directory is enabled, the `opentf init` command will still use the configured or implied installation methods to obtain metadata about which plugins are available, but once a suitable version has been selected it will first check to see if the chosen plugin is already available -in the cache directory. If so, Terraform will use the previously-downloaded +in the cache directory. If so, OpenTF will use the previously-downloaded copy. -If the selected plugin is not already in the cache, Terraform will download +If the selected plugin is not already in the cache, OpenTF will download it into the cache first and then copy it from there into the correct location -under your current working directory. When possible Terraform will use +under your current working directory. When possible OpenTF will use symbolic links to avoid storing a separate copy of a cached plugin in multiple directories. @@ -374,12 +348,12 @@ The plugin cache directory _must not_ also be one of the configured or implied filesystem mirror directories, since the cache management logic conflicts with the filesystem mirror logic when operating on the same directory. -Terraform will never itself delete a plugin from the plugin cache once it has +OpenTF will never itself delete a plugin from the plugin cache once it has been placed there. Over time, as plugins are upgraded, the cache directory may grow to contain several unused versions which you must delete manually. -> **Note:** The plugin cache directory is not guaranteed to be concurrency -safe. The provider installer's behavior in environments with multiple `terraform +safe. The provider installer's behavior in environments with multiple `opentf init` calls is undefined. ### Allowing the Provider Plugin Cache to break the dependency lock file @@ -388,21 +362,21 @@ init` calls is undefined. only. Do not set this option unless you are sure you need it and you fully understand the consequences of enabling it. -By default Terraform will use packages from the global cache directory only +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](/terraform/language/files/dependency-lock) -for that provider. This ensures that Terraform can always +[dependency lock file](/opentf/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. However, we know that in some special situations teams have been unable to use the dependency lock file as intended, and so they don't include it in their -version control as recommended and instead let Terraform re-generate it each +version control as recommended and instead let OpenTF re-generate it each time it installs providers. For those teams that don't preserve the dependency lock file in their version -control systems between runs, Terraform allows an additional CLI Configuration -setting which tells Terraform to always treat a package in the cache directory +control systems between runs, OpenTF allows an additional CLI Configuration +setting which tells OpenTF to always treat a package in the cache directory as valid even if there isn't already an entry in the dependency lock file to confirm it: @@ -414,19 +388,19 @@ Alternatively, you can set the environment variable `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to any value other than the empty string or `0`, which is equivalent to the above setting. -Setting this option gives Terraform CLI permission to create an incomplete -dependency lock file entry for a provider if that would allow Terraform to +Setting this option gives OpenTF CLI permission to create an incomplete +dependency lock file entry for a provider if that would allow OpenTF to use the cache to install that provider. In that situation the dependency lock file will be valid for use on the current system but may not be valid for use on another computer with a different operating system or CPU architecture, because it will include only a checksum of the package in the global cache. -We recommend that most users leave this option unset, in which case Terraform +We recommend that most users leave this option unset, in which case OpenTF will always install a provider from upstream the first time you use it with a particular configuration, but can then re-use the cache entry on later runs once the dependency lock file records valid checksums for the provider package. -~> **Note:** The Terraform team intends to improve the dependency lock file +~> **Note:** The OpenTF team intends to improve the dependency lock file mechanism in future versions so that it will be usable in more situations. At that time this option will become silently ignored. If your workflow relies on the use of this option, please open a GitHub issue to share details about your @@ -435,11 +409,7 @@ dependency lock file. ### Development Overrides for Provider Developers --> **Note:** Development overrides work only in Terraform v0.14 and later. -Using a `dev_overrides` block in your CLI configuration will cause Terraform -v0.13 to reject the configuration as invalid. - -Normally Terraform verifies version selections and checksums for providers +Normally OpenTF verifies version selections and checksums for providers in order to help ensure that all operations are made with the intended version of a provider, and that authors can gradually upgrade to newer provider versions in a controlled manner. @@ -449,7 +419,7 @@ though, because we often want to try a test configuration against a development build of a provider that doesn't even have an associated version number yet, and doesn't have an official set of checksums listed in a provider registry. -As a convenience for provider development, Terraform supports a special +As a convenience for provider development, OpenTF supports a special additional block `dev_overrides` in `provider_installation` blocks. The contents of this block effectively override all of the other configured installation methods, so a block of this type must always appear first in the sequence: @@ -459,27 +429,27 @@ provider_installation { # Use /home/developer/tmp/terraform-null as an overridden package directory # for the hashicorp/null provider. This disables the version and checksum - # verifications for this provider and forces Terraform to look for the + # verifications for this provider and forces OpenTF to look for the # null provider plugin in the given directory. dev_overrides { "hashicorp/null" = "/home/developer/tmp/terraform-null" } # For all other providers, install them directly from their origin provider - # registries as normal. If you omit this, Terraform will _only_ use + # registries as normal. If you omit this, OpenTF will _only_ use # the dev_overrides block, and so no other providers will be available. direct {} } ``` -With development overrides in effect, the `terraform init` command will still +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](/terraform/language/files/dependency-lock) +[the dependency lock file](/opentf/language/files/dependency-lock) for future use, but other commands like -`terraform apply` will disregard the lock file's entry for `hashicorp/null` and +`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 -published release of the provider, you can use `terraform init -upgrade` to +published release of the provider, you can use `opentf init -upgrade` to select the new version in the dependency lock file and remove your development override. @@ -494,7 +464,7 @@ You may wish to enable a development override only for shell sessions where you are actively working on provider development. If so, you can write a local CLI configuration file with content like the above in your development directory, perhaps called `dev.tfrc` for the sake of example, and then use the -`TF_CLI_CONFIG_FILE` environment variable to instruct Terraform to use that +`TF_CLI_CONFIG_FILE` environment variable to instruct OpenTF to use that localized CLI configuration instead of the default one: ``` @@ -502,7 +472,7 @@ export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc ``` Development overrides are not intended for general use as a way to have -Terraform look for providers on the local filesystem. If you wish to put +OpenTF look for providers on the local filesystem. If you wish to put copies of _released_ providers in your local filesystem, see [Implied Local Mirror Directories](#implied-local-mirror-directories) or @@ -512,17 +482,6 @@ instead. This development overrides mechanism is intended as a pragmatic way to enable smoother provider development. The details of how it behaves, how to configure it, and how it interacts with the dependency lock file may all evolve -in future Terraform releases, including possible breaking changes. We therefore +in future OpenTF releases, including possible breaking changes. We therefore recommend using development overrides only temporarily during provider development work. - -## Removed Settings - -The following settings are supported in Terraform 0.12 and earlier but are -no longer recommended for use: - -* `providers` - a configuration block that allows specifying the locations of - specific plugins for each named provider. This mechanism is deprecated - because it is unable to specify a version number and source for each provider. - See [Provider Installation](#provider-installation) above for the replacement - of this setting in Terraform 0.13 and later. diff --git a/website/docs/cli/config/environment-variables.mdx b/website/docs/cli/config/environment-variables.mdx index 746e29267f..99051760a6 100644 --- a/website/docs/cli/config/environment-variables.mdx +++ b/website/docs/cli/config/environment-variables.mdx @@ -1,15 +1,15 @@ --- page_title: Environment Variables description: >- - Learn to use environment variables to change Terraform's default behavior. + Learn to use environment variables to change OpenTF's default behavior. Configure log content and output, set variables, and more. --- # Environment Variables -Terraform refers to a number of environment variables to customize various +OpenTF refers to a number of environment variables to customize various aspects of its behavior. None of these environment variables are required -when using Terraform, but they can be used to change some of Terraform's +when using OpenTF, but they can be used to change some of OpenTF's default behaviors in unusual situations, or to increase output verbosity for debugging. @@ -27,21 +27,21 @@ To disable, either unset it, or set it to `off`. For example: export TF_LOG=off ``` -For more on debugging Terraform, check out the section on [Debugging](/terraform/internals/debugging). +For more on debugging OpenTF, check out the section on [Debugging](/opentf/internals/debugging). ## TF_LOG_PATH -This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running terraform from: +This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running opentf from: ```shell export TF_LOG_PATH=./terraform.log ``` -For more on debugging Terraform, check out the section on [Debugging](/terraform/internals/debugging). +For more on debugging OpenTF, check out the section on [Debugging](/opentf/internals/debugging). ## TF_INPUT -If set to "false" or "0", causes terraform commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example: +If set to "false" or "0", causes opentf commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example: ```shell export TF_INPUT=0 @@ -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](/terraform/language/values/variables). +For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](/opentf/language/values/variables). ## TF_CLI_ARGS and TF_CLI_ARGS_name @@ -66,17 +66,17 @@ For more on how to use `TF_VAR_name` in context, check out the section on [Varia The value of `TF_CLI_ARGS` will specify additional arguments to the command-line. This allows easier automation in CI environments as well as -modifying default behavior of Terraform on your own system. +modifying default behavior of OpenTF on your own system. These arguments are inserted directly _after_ the subcommand (such as `plan`) and _before_ any flags specified directly on the command-line. This behavior ensures that flags on the command-line take precedence over environment variables. -For example, the following command: `TF_CLI_ARGS="-input=false" terraform apply -force` -is the equivalent to manually typing: `terraform apply -input=false -force`. +For example, the following command: `TF_CLI_ARGS="-input=false" opentf apply -force` +is the equivalent to manually typing: `opentf apply -input=false -force`. -The flag `TF_CLI_ARGS` affects all Terraform commands. If you specify a +The flag `TF_CLI_ARGS` affects all OpenTF commands. If you specify a named command in the form of `TF_CLI_ARGS_name` then it will only affect that command. As an example, to specify that only plans never refresh, you can set `TF_CLI_ARGS_plan="-refresh=false"`. @@ -87,7 +87,7 @@ be separated by spaces otherwise. ## TF_DATA_DIR -`TF_DATA_DIR` changes the location where Terraform keeps its +`TF_DATA_DIR` changes the location where OpenTF keeps its per-working-directory data, such as the current backend configuration. By default this data is written into a `.terraform` subdirectory of the @@ -99,12 +99,12 @@ be useful to do so if e.g. the working directory is not writable. The data directory is used to retain data that must persist from one command to the next, so it's important to have this variable set consistently throughout -all of the Terraform workflow commands (starting with `terraform init`) or else -Terraform may be unable to find providers, modules, and other artifacts. +all of the OpenTF workflow commands (starting with `opentf init`) or else +OpenTF may be unable to find providers, modules, and other artifacts. ## TF_WORKSPACE -For multi-environment deployment, in order to select a workspace, instead of doing `terraform workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection. +For multi-environment deployment, in order to select a workspace, instead of doing `opentf workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection. For example: @@ -114,20 +114,18 @@ 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](/terraform/language/state/workspaces). +For more information regarding workspaces, check out the section on [Using Workspaces](/opentf/language/state/workspaces). ## TF_IN_AUTOMATION -If `TF_IN_AUTOMATION` is set to any non-empty value, Terraform adjusts its +If `TF_IN_AUTOMATION` is set to any non-empty value, OpenTF adjusts its output to avoid suggesting specific commands to run next. This can make the output more consistent and less confusing in workflows where users don't -directly execute Terraform commands, like in CI systems or other wrapping +directly execute OpenTF commands, like in CI systems or other wrapping applications. -This is a purely cosmetic change to Terraform's human-readable output, and the -exact output differences can change between minor Terraform versions. - -For more details, see [Running Terraform in Automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). +This is a purely cosmetic change to OpenTF's human-readable output, and the +exact output differences can change between minor OpenTF versions. ## TF_REGISTRY_DISCOVERY_RETRY @@ -145,7 +143,7 @@ export TF_REGISTRY_CLIENT_TIMEOUT=15 ## TF_CLI_CONFIG_FILE -The location of the [Terraform CLI configuration file](/terraform/cli/config/config-file). +The location of the [OpenTF CLI configuration file](/opentf/cli/config/config-file). ```shell export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom" @@ -153,22 +151,22 @@ 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](/terraform/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](/opentf/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`](/terraform/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`](/opentf/cli/config/config-file#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file). ## TF_IGNORE -If `TF_IGNORE` is set to "trace", Terraform will output debug messages to display ignored files and folders. This is useful when debugging large repositories with `.terraformignore` files. +If `TF_IGNORE` is set to "trace", OpenTF will output debug messages to display ignored files and folders. This is useful when debugging large repositories with `.terraformignore` files. ```shell export TF_IGNORE=trace ``` -For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/terraform/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore). +For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](/opentf/language/settings/backends/remote#excluding-files-from-upload-with-terraformignore). -## Terraform Cloud CLI Integration +## Cloud Backend CLI Integration -The CLI integration with Terraform Cloud lets you use Terraform Cloud and Terraform Enterprise on the command line. The integration requires including a `cloud` block in your Terraform configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI). +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 [Terraform Cloud Settings](/terraform/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables. +Refer to [Cloud Backend Settings](/opentf/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 77022d1335..d7ea70c762 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.mdx @@ -1,24 +1,24 @@ --- -page_title: CLI Configuration - Terraform CLI +page_title: CLI Configuration - OpenTF CLI description: >- - Find documentation about the CLI config file and customizing Terraform + Find documentation about the CLI config file and customizing OpenTF environment variables. --- # CLI Configuration -Terraform CLI can be configured with some global settings, which are separate -from any Terraform configuration and which apply across all working directories. +OpenTF CLI can be configured with some global settings, which are separate +from any OpenTF configuration and which apply across all working directories. -We've designed Terraform such that an average user running Terraform CLI +We've designed OpenTF such that an average user running OpenTF CLI interactively will not need to interact with any of these settings. As a result, most of the global settings relate to advanced or automated workflows, or -unusual environmental conditions like running Terraform on an airgapped +unusual environmental conditions like running OpenTF on an airgapped instance. -- The [CLI config file](/terraform/cli/config/config-file) configures provider +- The [CLI config file](/opentf/cli/config/config-file) configures provider installation and security features. -- Several [environment variables](/terraform/cli/config/environment-variables) can - configure Terraform's inputs and outputs; this includes some alternate ways to +- Several [environment variables](/opentf/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 fdc3fe91c0..d5a9f164c6 100644 --- a/website/docs/cli/import/importability.mdx +++ b/website/docs/cli/import/importability.mdx @@ -1,16 +1,16 @@ --- page_title: 'Import: Resource Importability' description: |- - Each resource in Terraform must implement some basic logic to become - importable. As a result, you cannot import all Terraform resources. + Each resource in OpenTF must implement some basic logic to become + importable. As a result, you cannot import all OpenTF resources. --- # Resource Importability -Each resource in Terraform must implement some basic logic to become -importable. As a result, you cannot import all Terraform resources. +Each resource in OpenTF must implement some basic logic to become +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 [Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository. +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 Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import). +To make a resource importable, refer to [Extending OpenTF: Resources — Import](/opentf/plugin/sdkv2/resources/import). diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx index 17a9a4e17d..41ea41dd97 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.mdx @@ -1,26 +1,24 @@ --- page_title: Import description: >- - Terraform can import and manage existing infrastructure. This can help you - transition your infrastructure to Terraform. + OpenTF can import and manage existing infrastructure. This can help you + transition your infrastructure to OpenTF. --- # Import -> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +OpenTF can import existing infrastructure resources. This functionality lets you bring existing resources under OpenTF management. -Terraform can import existing infrastructure resources. This functionality lets you bring existing resources under Terraform management. - --> **Note:** Terraform v1.5.0 and later supports `import` blocks. Unlike the `terraform import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/terraform/language/import). +-> **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). ## State Only -~> **Warning:** Terraform expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. See [State](/terraform/language/state) for more details. +~> **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. -The `terraform import` CLI command can only import resources into the [state](/terraform/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/terraform/language/import). +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). -Before you run `terraform import` you must manually write a `resource` configuration block for the resource. The resource block describes where Terraform should map the imported object. +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. -## Terraform Cloud +## Cloud Backend -When you use Terraform on the command line with Terraform Cloud, many commands like `apply` run inside your Terraform Cloud environment. However, the `import` command runs locally, so it does not have access to information from Terraform Cloud. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in Terraform Cloud. +When you use OpenTF on the command line with a cloud backend, many commands like `apply` run inside your cloud backend's environment. However, the `import` command runs locally, so it does not have access to information from the cloud backend. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in the cloud backend. diff --git a/website/docs/cli/import/usage.mdx b/website/docs/cli/import/usage.mdx index f5d95be0f6..0c534b275d 100644 --- a/website/docs/cli/import/usage.mdx +++ b/website/docs/cli/import/usage.mdx @@ -1,27 +1,24 @@ --- page_title: 'Import: Usage' -description: The `terraform import` command is used to import existing infrastructure. +description: The `opentf import` command is used to import existing infrastructure. --- # Import Usage -> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +Use the `opentf import` command to import existing infrastructure to OpenTF state. +The `opentf import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC. -Use the `terraform import` command to import existing infrastructure to Terraform state. - -The `terraform import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC. - -~> Warning: Terraform expects that each remote object it is managing will be -bound to only one resource address, which is normally guaranteed by Terraform -itself having created all objects. If you import existing objects into Terraform, -be careful to import each remote object to only one Terraform resource address. -If you import the same object multiple times, Terraform may exhibit unwanted +~> Warning: OpenTF expects that each remote object it is managing will be +bound to only one resource address, which is normally guaranteed by OpenTF +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](/terraform/language/state). +[the State section](/opentf/language/state). To import a resource, first write a resource block for it in your -configuration, establishing the name by which it will be known to Terraform: +configuration, establishing the name by which it will be known to OpenTF: ``` resource "aws_instance" "example" { @@ -37,22 +34,22 @@ remains constant. If desired, you can leave the body of the resource block blank for now and return to fill it in once the instance is imported. -Now `terraform import` can be run to attach an existing instance to this +Now `opentf import` can be run to attach an existing instance to this resource configuration: ```shell -$ terraform import aws_instance.example i-abcd1234 +$ opentf import aws_instance.example i-abcd1234 ``` This command locates the AWS EC2 instance with ID `i-abcd1234`. Then it attaches the existing settings of the instance, as described by the EC2 API, to the name `aws_instance.example` of a module. In this example the module path implies that the root module is used. Finally, the mapping is saved in the -Terraform state. +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_](/terraform/cli/state/resource-addressing) for more +[_Resource Addressing_](/opentf/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. @@ -61,7 +58,7 @@ AWS Route53 Zones use the domain name itself. Consult the documentation for each importable resource for details on what form of ID is required. As a result of the above command, the resource is recorded in the state file. -You can now run `terraform plan` to see how the configuration compares to +You can now run `opentf plan` to see how the configuration compares to the imported resource, and make any adjustments to the configuration to align with the current (or desired) state of the imported object. @@ -75,7 +72,7 @@ an `aws_network_acl` but also one `aws_network_acl_rule` for each rule. In this scenario, the secondary resources will not already exist in configuration, so it is necessary to consult the import output and create a `resource` block in configuration for each secondary resource. If this is -not done, Terraform will plan to destroy the imported objects on the next run. +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](/terraform/cli/commands/state) can be used. +[state management commands](/opentf/cli/commands/state) can be used. diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.mdx index d9e5bb8288..b715d138dc 100644 --- a/website/docs/cli/index.mdx +++ b/website/docs/cli/index.mdx @@ -1,19 +1,17 @@ --- -page_title: Terraform CLI Documentation +page_title: OpenTF CLI Documentation description: >- - Learn Terraform's CLI-based workflows. You can use the CLI alone or - with Terraform Cloud or Terraform Enterprise. + Learn OpenTF's CLI-based workflows. You can use the CLI alone or + with cloud backends. --- -# Terraform CLI Documentation +# OpenTF CLI Documentation -> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. +This is the documentation for OpenTF CLI. It is relevant to anyone working +with OpenTF's CLI-based workflows; this includes people who use OpenTF CLI +by itself, as well as those who use OpenTF CLI in conjunction with +TACOS (TF Automation and Collaboration Software). -This is the documentation for Terraform CLI. It is relevant to anyone working -with Terraform's CLI-based workflows; this includes people who use Terraform CLI -by itself, as well as those who use Terraform CLI in conjunction with Terraform -Cloud or Terraform Enterprise. - -Notably, this documentation does not cover the syntax and usage of the Terraform +Notably, this documentation does not cover the syntax and usage of the OpenTF language. For that, see the -[Terraform Language Documentation](/terraform/language). +[OpenTF Language Documentation](/opentf/language). diff --git a/website/docs/cli/init/index.mdx b/website/docs/cli/init/index.mdx index 5b763eb9da..2fc9f119d7 100644 --- a/website/docs/cli/init/index.mdx +++ b/website/docs/cli/init/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Initializing Working Directories - Terraform CLI +page_title: Initializing Working Directories - OpenTF CLI description: >- Working directories contain configurations, settings, cached plugins and modules, and state data. Learn how to initialize and manage working @@ -8,37 +8,37 @@ description: >- # Initializing Working Directories -Terraform expects to be invoked from a working directory that contains +OpenTF expects to be invoked from a working directory that contains configuration files written in -[the Terraform language](/terraform/language). Terraform uses +[the OpenTF language](/opentf/language). OpenTF uses configuration content from this directory, and also uses the directory to store settings, cached plugins and modules, and sometimes state data. -A working directory must be initialized before Terraform can perform any +A working directory must be initialized before OpenTF can perform any operations in it (like provisioning infrastructure or modifying state). ## Working Directory Contents -A Terraform working directory typically contains: +A OpenTF working directory typically contains: -- A Terraform configuration describing resources Terraform should manage. This +- A OpenTF configuration describing resources OpenTF should manage. This configuration is expected to change over time. -- A hidden `.terraform` directory, which Terraform uses to manage cached +- A hidden `.terraform` directory, which OpenTF uses to manage cached provider plugins and modules, record which - [workspace](/terraform/cli/workspaces) is currently active, and + [workspace](/opentf/cli/workspaces) is currently active, and record the last known backend configuration in case it needs to migrate state - on the next run. This directory is automatically managed by Terraform, and is + on the next run. This directory is automatically managed by OpenTF, and is created during initialization. - State data, if the configuration uses the default `local` backend. This is - managed by Terraform in a `terraform.tfstate` file (if the directory only uses + managed by OpenTF in a `terraform.tfstate` file (if the directory only uses the default workspace) or a `terraform.tfstate.d` directory (if the directory uses multiple workspaces). ## Initialization -Run the `terraform init` command to initialize a working directory that contains -a Terraform configuration. After initialization, you will be able to perform -other commands, like `terraform plan` and `terraform apply`. +Run the `opentf init` command to initialize a working directory that contains +a OpenTF configuration. After initialization, you will be able to perform +other commands, like `opentf plan` and `opentf apply`. If you try to run a command that relies on initialization without first initializing, the command will fail with an error and explain that you need to @@ -50,16 +50,16 @@ plugins, and downloading modules. Under some conditions (usually when changing from one backend to another), it might ask the user for guidance or confirmation. -For details, see [the `terraform init` command](/terraform/cli/commands/init). +For details, see [the `opentf init` command](/opentf/cli/commands/init). ## Reinitialization -Certain types of changes to a Terraform configuration can require +Certain types of changes to a OpenTF configuration can require reinitialization before normal operations can continue. This includes changes to provider requirements, module sources or version constraints, and backend configurations. -You can reinitialize a directory by running `terraform init` again. In fact, you +You can reinitialize a directory by running `opentf init` again. In fact, you can reinitialize at any time; the init command is idempotent, and will have no effect if no changes are required. @@ -68,7 +68,7 @@ fail with an error and tell you so. ## Reinitializing Only Modules -The `terraform get` command will download modules referenced in the +The `opentf get` command will download modules referenced in the configuration, but will not perform the other required initialization tasks. -This command is only useful for niche workflows, and most Terraform users can -ignore it in favor of `terraform init`. +This command is only useful for niche workflows, and most OpenTF users can +ignore it in favor of `opentf init`. diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx index 113594c58a..02c7cffe13 100644 --- a/website/docs/cli/inspect/index.mdx +++ b/website/docs/cli/inspect/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Inspecting Infrastructure - Terraform CLI +page_title: Inspecting Infrastructure - OpenTF CLI description: >- Learn commands to inspect dependency information, outputs, etc. Use them for integration or to understand your infrastructure. @@ -7,29 +7,29 @@ description: >- # Inspecting Infrastructure -Terraform configurations and state data include some highly structured +OpenTF configurations and state data include some highly structured information about the resources they manage; this includes dependency information, outputs (which are pieces of generated or discovered data that the configuration's author considers important enough to surface to users), and more. -Terraform CLI includes some commands for inspecting or transforming this data. -You can use these to integrate other tools with Terraform's infrastructure data, +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 `terraform graph` command](/terraform/cli/commands/graph) creates a visual +- [The `opentf graph` command](/opentf/cli/commands/graph) creates a visual representation of a configuration or a set of planned changes. -- [The `terraform output` command](/terraform/cli/commands/output) can get the - values for the top-level [output values](/terraform/language/values/outputs) of +- [The `opentf output` command](/opentf/cli/commands/output) can get the + values for the top-level [output values](/opentf/language/values/outputs) of a configuration, which are often helpful when making use of the infrastructure - Terraform has provisioned. -- [The `terraform show` command](/terraform/cli/commands/show) can generate + OpenTF has provisioned. +- [The `opentf show` command](/opentf/cli/commands/show) can generate human-readable versions of a state file or plan file, or generate machine-readable versions that can be integrated with other tools. -- [The `terraform state list` command](/terraform/cli/commands/state/list) can list +- [The `opentf state list` command](/opentf/cli/commands/state/list) can list the resources being managed by the current working directory and workspace, providing a complete or filtered list. -- [The `terraform state show` command](/terraform/cli/commands/state/show) can print +- [The `opentf state show` command](/opentf/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 e8ca55f431..309d60d8e5 100644 --- a/website/docs/cli/install/apt.mdx +++ b/website/docs/cli/install/apt.mdx @@ -1,90 +1,65 @@ --- page_title: APT Packages for Debian and Ubuntu description: >- - The HashiCorp APT repositories contain distribution-specific Terraform + The OpenTF APT repositories contain distribution-specific OpenTF packages for both Debian and Ubuntu systems. --- # APT Packages for Debian and Ubuntu -The primary distribution packages for Terraform are `.zip` archives containing +The primary distribution packages for OpenTF are `.zip` archives containing single executable files that you can extract anywhere on your system. However, for easier integration with configuration management tools and other systematic system configuration strategies, we also offer package repositories for -Debian and Ubuntu systems, which allow you to install Terraform using the +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 Terraform from our Yum repositories](/terraform/cli/install/yum). - --> **Note:** The APT repositories discussed on this page are generic HashiCorp -repositories that contain packages for a variety of different HashiCorp -products, rather than just Terraform. Adding these repositories to your -system will, by default, therefore make several other non-Terraform -packages available for installation. That might then mask some packages that -are available for some HashiCorp products in the main Debian and Ubuntu -package repositories. +might prefer to [install OpenTF from our Yum repositories](/opentf/cli/install/yum). ## Repository Configuration -Please follow the instructions in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide). +Please follow the instructions in the [Official Packaging Guide](https://www.placeholderplaceholderplaceholder.com/official-packaging-guide). ## Supported Architectures -The HashiCorp APT server has packages only for the `amd64` +The OpenTF APT server has packages only for the `amd64` architecture, which is also sometimes known as `x86_64`. There are no official packages available for other architectures, such as -`arm64`. If you wish to use Terraform on a non-`amd64` system, -[download a normal release `.zip` file](/terraform/downloads) instead. +`arm64`. If you wish to use OpenTF on a non-`amd64` system, +[download a normal release `.zip` file](/opentf/downloads) instead. -## Supported Debian and Ubuntu Releases +## Installing a Specific Version of OpenTF -The HashiCorp APT server contains release repositories for a variety of -supported distributions, which are outlined in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide). - -## Installing a Specific Version of Terraform - -The HashiCorp APT repositories contain multiple versions of Terraform, but -because the packages are all named `terraform` it is impossible to install +The OpenTF APT repositories contain multiple versions of OpenTF, but +because the packages are all named `opentf` it is impossible to install more than one version at a time, and `apt install` will default to selecting the latest version. -It's often necessary to match your Terraform version with what a particular +It's often necessary to match your OpenTF version with what a particular configuration is currently expecting. You can use the following command to see which versions are currently available in the repository index: ```bash -apt policy terraform +apt policy opentf ``` -If your workflow requires using multiple versions of Terraform at the same +If your workflow requires using multiple versions of OpenTF at the same time, for example when working through a gradual upgrade where not all of your configurations are upgraded yet, we recommend that you use the official release `.zip` files instead of the APT packages, so you can install multiple versions at once and then select which to use for each command you run. -### Terraform 1.4.3 and Later - -As of Terraform 1.4.3, all published packages include a revision number by +All published packages include a revision number by default, starting with `-1`. This change means that in the case that we need to publish an updated package for any reason, installers can automatically -retrieve the latest revision. You can learn more about this packaging change -in [the announcement](https://discuss.hashicorp.com/t/linux-packaging-debian-revision-change/42403). +retrieve the latest revision. You can install the latest revision for a particular version by including the version in the `apt install` command, as follows: ```bash -sudo apt install terraform=1.4.4-* -``` - -### Terraform 1.4.2 and Earlier - -Terraform 1.4.2 and earlier did not include a revision number for the first -revision, so you can use the following pattern to install a specific version: - -```bash -sudo apt install terraform=1.4.0 +sudo apt install opentf=1.4.4-* ``` diff --git a/website/docs/cli/install/yum.mdx b/website/docs/cli/install/yum.mdx index b6b4b80970..4b85c2fd6e 100644 --- a/website/docs/cli/install/yum.mdx +++ b/website/docs/cli/install/yum.mdx @@ -1,28 +1,21 @@ --- page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux' description: >- - The HashiCorp Yum repositories contain distribution-specific Terraform + The OpenTF Yum repositories contain distribution-specific OpenTF packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems. --- # Yum/DNF Packages for RHEL, CentOS, and Fedora -The primary distribution packages for Terraform are `.zip` archives containing +The primary distribution packages for OpenTF are `.zip` archives containing single executable files that you can extract anywhere on your system. However, for easier integration with configuration management tools and other systematic system configuration strategies, we also offer package repositories for RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to -install Terraform using the `yum install` or `dnf install` commands. +install OpenTF using the `yum install` or `dnf install` commands. If you are instead using Debian or Ubuntu, you -might prefer to [install Terraform from our APT repositories](/terraform/cli/install/apt). - --> **Note:** The Yum repositories discussed on this page are generic HashiCorp -repositories that contain packages for a variety of different HashiCorp -products, rather than just Terraform. Adding these repositories to your -system will, by default, therefore make a number of other non-Terraform -packages available for installation. That might then mask the packages that are -available for some HashiCorp products in the main distribution repositories. +might prefer to [install OpenTF from our APT repositories](/opentf/cli/install/apt). ## Repository Configuration @@ -39,7 +32,7 @@ If you are using a Yum-based distribution, add the repository using ```bash sudo yum install -y yum-utils -sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo +sudo yum-config-manager --add-repo https://rpm.releases.placeholderplaceholderplaceholder.com/$release/hashicorp.repo ``` If you are using a DNF-based distribution, add the repository using @@ -47,27 +40,27 @@ If you are using a DNF-based distribution, add the repository using ```bash sudo dnf install -y dnf-plugins-core -sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo +sudo dnf config-manager --add-repo https://rpm.releases.placeholderplaceholderplaceholder.com/$release/hashicorp.repo ``` -In both cases, the Terraform package name is `terraform`. For example: +In both cases, the OpenTF package name is `opentf`. For example: ```bash -yum install terraform +yum install opentf ``` ## Supported Architectures -The HashiCorp Yum/DNF server has packages only for the `x86_64` +The OpenTF Yum/DNF server has packages only for the `x86_64` architecture, which is also sometimes known as `amd64`. There are no official packages available for other architectures, such as -`aarch64`. If you wish to use Terraform on a non-`x86_64` system, -[download a normal release `.zip` file](/terraform/downloads) instead. +`aarch64`. If you wish to use OpenTF on a non-`x86_64` system, +[download a normal release `.zip` file](/opentf/downloads) instead. ## Supported Distribution Releases -The HashiCorp Yum server contains release repositories for the +The OpenTF Yum server contains release repositories for the following distribution releases: * AmazonLinux 2 and "latest" @@ -85,35 +78,35 @@ any other RPM-based Linux distributions. If you add the repository using the above commands on other systems then you will see a 404 Not Found error. Over time we will change the set of supported distributions, including both -adding support for new releases and ceasing to publish new Terraform versions +adding support for new releases and ceasing to publish new OpenTF versions under older releases. -## Choosing Terraform Versions +## Choosing OpenTF Versions -The HashiCorp Yum repositories contain multiple versions of Terraform, but -because the packages are all named `terraform` it is impossible to install +The OpenTF Yum repositories contain multiple versions of OpenTF, but +because the packages are all named `opentf` it is impossible to install more than one version at a time, and `yum install` or `dnf install` will default to selecting the latest version. -It's often necessary to match your Terraform version with what a particular +It's often necessary to match your OpenTF version with what a particular configuration is currently expecting. Use the following command to retrieve the available versions in the repository index: ```bash -yum --showduplicate list terraform +yum --showduplicate list opentf ``` You can select a specific version to install by including it in the `yum install` command line, as follows: ```bash -yum install terraform-0.14.0-2.x86_64 +yum install opentf-0.14.0-2.x86_64 ``` If you are using a DNF-based distribution, similar use `dnf` instead of `yum` when following the above steps. -If your workflow requires using multiple versions of Terraform at the same +If your workflow requires using multiple versions of OpenTF at the same time, for example when working through a gradual upgrade where not all of your configurations are upgraded yet, we recommend that you use the official release `.zip` files instead of the Yum packages, so you can install diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.mdx index 97f6182422..be67617d9a 100644 --- a/website/docs/cli/plugins/index.mdx +++ b/website/docs/cli/plugins/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Managing Plugins - Terraform CLI +page_title: Managing Plugins - OpenTF CLI description: >- Commands to install, configure, and show information about providers. Also commands to reduce install effort in air-gapped environments. @@ -7,53 +7,53 @@ description: >- # Managing Plugins -Terraform relies on plugins called "providers" in order to manage various types +OpenTF relies on plugins called "providers" in order to manage various types of resources. (For more information about providers, see -[Providers](/terraform/language/providers) in the Terraform +[Providers](/opentf/language/providers) in the OpenTF language docs.) --> **Note:** Providers are the only plugin type most Terraform users interact with. Terraform also supports third-party provisioner plugins, but +-> **Note:** Providers are the only plugin type most OpenTF users interact with. OpenTF also supports third-party provisioner plugins, but we discourage their use. -Terraform downloads and/or installs any providers -[required](/terraform/language/providers/requirements) by a configuration -when [initializing](/terraform/cli/init) a working directory. By default, +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, this works without any additional interaction but requires network access to download providers from their source registry. -You can configure Terraform's provider installation behavior to limit or skip +You can configure OpenTF's provider installation behavior to limit or skip network access, and to enable use of providers that aren't available via a -networked source. Terraform also includes some commands to show information +networked source. OpenTF also includes some commands to show information about providers and to reduce the effort of installing providers in airgapped environments. ## Configuring Plugin Installation -Terraform's configuration file includes options for caching downloaded plugins, +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](/terraform/cli/config/config-file). +more information, see [CLI Config File](/opentf/cli/config/config-file). ## Getting Plugin Information -Use the [`terraform providers`](/terraform/cli/commands/providers) command to get information +Use the [`opentf providers`](/opentf/cli/commands/providers) command to get information about the providers required by the current working directory's configuration. -Use the [`terraform version`](/terraform/cli/commands/version) command (or -`terraform -version`) to show the specific provider versions installed for the +Use the [`opentf version`](/opentf/cli/commands/version) command (or +`opentf -version`) to show the specific provider versions installed for the current working directory. -Use the [`terraform providers schema`](/terraform/cli/commands/providers/schema) command to +Use the [`opentf providers schema`](/opentf/cli/commands/providers/schema) command to get machine-readable information about the resources and configuration options offered by each provider. ## Managing Plugin Installation -Use the [`terraform providers mirror`](/terraform/cli/commands/providers/mirror) command to +Use the [`opentf providers mirror`](/opentf/cli/commands/providers/mirror) command to download local copies of every provider required by the current working directory's configuration. This directory will use the nested directory layout -that Terraform expects when installing plugins from a local source, so you can -transfer it directly to an airgapped system that runs Terraform. +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 [`terraform providers lock`](/terraform/cli/commands/providers/lock) command -to update the lock file that Terraform uses to ensure predictable runs when +Use the [`opentf providers lock`](/opentf/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/plugins/signing.mdx b/website/docs/cli/plugins/signing.mdx index 7eac2efd30..63a535614d 100644 --- a/website/docs/cli/plugins/signing.mdx +++ b/website/docs/cli/plugins/signing.mdx @@ -1,7 +1,7 @@ --- page_title: Plugin Signing description: >- - Learn about the types of signatures providers can have on the Terraform + Learn about the types of signatures providers can have on the OpenTF Registry. --- @@ -9,19 +9,19 @@ description: >- # Plugin Signing -~> **Note** Terraform only authenticates provider plugins fetched from a registry. +~> **Note** OpenTF only authenticates provider plugins fetched from a registry. -Terraform providers installed from the Registry are cryptographically signed, and the signature is verified at time of installation. There are three types of provider signatures, each with different trust implications: +OpenTF providers installed from the Registry are cryptographically signed, and the signature is verified at time of installation. There are three types of provider signatures, each with different trust implications: * **Signed by HashiCorp** - are built, signed, and supported by HashiCorp. * **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has verified the ownership of the private key and we provide a chain of trust to the CLI to verify this programatically. -* **Self-signed** - are built, signed, and supported by a third party. HashiCorp does not provide a +* **Self-signed** - are built, signed, and supported by a third party. OpenTF does not provide a verification or chain of trust for the signature. You may obtain and validate fingerprints manually if you want to ensure you are using a binary you can trust. -Terraform does **NOT** support fetching and using unsigned binaries, but you can manually install +OpenTF does **NOT** support fetching and using unsigned binaries, but you can manually install unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed. Usage of plugins from the registry is subject to the Registry's [Terms of Use](https://registry.terraform.io/terms). diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx index 3fc3538f98..ba7f33d87b 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.mdx @@ -1,27 +1,27 @@ --- -page_title: Provisioning Infrastructure - Terraform CLI +page_title: Provisioning Infrastructure - OpenTF CLI description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.' --- -# Provisioning Infrastructure with Terraform +# Provisioning Infrastructure with OpenTF -Terraform's primary function is to create, modify, and destroy infrastructure +OpenTF's primary function is to create, modify, and destroy infrastructure resources to match the desired state described in a -[Terraform configuration](/terraform/language). +[OpenTF configuration](/opentf/language). -When people refer to "running Terraform," they generally mean performing these +When people refer to "running OpenTF," they generally mean performing these provisioning actions in order to affect real infrastructure objects. The -Terraform binary has many other subcommands for a wide variety of administrative -actions, but these basic provisioning tasks are the core of Terraform. +OpenTF binary has many other subcommands for a wide variety of administrative +actions, but these basic provisioning tasks are the core of OpenTF. -Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and +OpenTF's provisioning workflow relies on three commands: `plan`, `apply`, and `destroy`. All of these commands require an -[initialized](/terraform/cli/init) working directory, and all of them act -only upon the currently selected [workspace](/terraform/cli/workspaces). +[initialized](/opentf/cli/init) working directory, and all of them act +only upon the currently selected [workspace](/opentf/cli/workspaces). ## Planning -The `terraform plan` command evaluates a Terraform configuration to determine +The `opentf plan` command evaluates a OpenTF configuration to determine the desired state of all the resources it declares, then compares that desired state to the real infrastructure objects being managed with the current working directory and workspace. It uses state data to determine which real objects @@ -29,38 +29,38 @@ correspond to which declared resources, and checks the current state of each resource using the relevant infrastructure provider's API. Once it has determined the difference between the current state and the desired -state, `terraform plan` presents a description of the changes necessary to +state, `opentf plan` presents a description of the changes necessary to achieve the desired state. It _does not_ perform any actual changes to real world infrastructure objects; it only presents a plan for making changes. Plans are usually run to validate configuration changes and confirm that the -resulting actions are as expected. However, `terraform plan` can also save its -plan as a runnable artifact, which `terraform apply` can use to carry out those +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 `terraform plan` command](/terraform/cli/commands/plan). +For details, see [the `opentf plan` command](/opentf/cli/commands/plan). ## Applying -The `terraform apply` command performs a plan just like `terraform plan` does, +The `opentf apply` command performs a plan just like `opentf plan` does, but then actually carries out the planned changes to each resource using the relevant infrastructure provider's API. It asks for confirmation from the user before making any changes, unless it was explicitly told to skip approval. -By default, `terraform apply` performs a fresh plan right before applying +By default, `opentf apply` performs a fresh plan right before applying changes, and displays the plan to the user when asking for confirmation. -However, it can also accept a plan file produced by `terraform plan` in lieu of +However, it can also accept a plan file produced by `opentf plan` in lieu of running a new plan. You can use this to reliably perform an exact set of pre-approved changes, even if the configuration or the state of the real infrastructure has changed in the minutes since the original plan was created. -For details, see [the `terraform apply` command](/terraform/cli/commands/apply). +For details, see [the `opentf apply` command](/opentf/cli/commands/apply). ## Destroying -The `terraform destroy` command destroys all of the resources being managed by +The `opentf destroy` command destroys all of the resources being managed by the current working directory and workspace, using state data to determine which -real world objects correspond to managed resources. Like `terraform apply`, it +real world objects correspond to managed resources. Like `opentf apply`, it asks for confirmation before proceeding. A destroy behaves exactly like deleting every resource from the configuration @@ -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 `terraform destroy` command](/terraform/cli/commands/destroy). +For details, see [the `opentf destroy` command](/opentf/cli/commands/destroy). diff --git a/website/docs/cli/state/index.mdx b/website/docs/cli/state/index.mdx index b5d39bd528..e080ebe109 100644 --- a/website/docs/cli/state/index.mdx +++ b/website/docs/cli/state/index.mdx @@ -1,34 +1,32 @@ --- -page_title: Manipulating State - Terraform CLI +page_title: Manipulating State - OpenTF CLI description: >- State data tracks which real-world object corresponds to each resource. Inspect state, move or import resources, and more. --- -# Manipulating Terraform State +# Manipulating OpenTF State -> **Hands-on:** Try the [Manage Resources in Terraform State](/terraform/tutorials/state/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. - -Terraform uses [state data](/terraform/language/state) to remember which +OpenTF uses [state data](/opentf/language/state) to remember which real-world object corresponds to each resource in the configuration; this allows it to modify an existing object when its resource declaration changes. -Terraform updates state automatically during plans and applies. However, it's -sometimes necessary to make deliberate adjustments to Terraform's state data, +OpenTF updates state automatically during plans and applies. However, it's +sometimes necessary to make deliberate adjustments to OpenTF's state data, usually to compensate for changes to the configuration or the real managed infrastructure. -Terraform CLI supports several workflows for interacting with state: +OpenTF CLI supports several workflows for interacting with state: -- [Inspecting State](/terraform/cli/state/inspect) -- [Forcing Re-creation](/terraform/cli/state/taint) -- [Moving Resources](/terraform/cli/state/move) +- [Inspecting State](/opentf/cli/state/inspect) +- [Forcing Re-creation](/opentf/cli/state/taint) +- [Moving Resources](/opentf/cli/state/move) - Importing Pre-existing Resources (documented in the - [Importing Infrastructure](/terraform/cli/import) section) -- [Disaster Recovery](/terraform/cli/state/recover) + [Importing Infrastructure](/opentf/cli/import) section) +- [Disaster Recovery](/opentf/cli/state/recover) ~> **Important:** Modifying state data outside a normal plan or apply can cause -Terraform to lose track of managed resources, which might waste money, annoy +OpenTF to lose track of managed resources, which might waste money, annoy your colleagues, or even compromise the security of your operations. Make sure to keep backups of your state data when modifying state out-of-band. diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.mdx index 439a0646f8..bee9216a84 100644 --- a/website/docs/cli/state/inspect.mdx +++ b/website/docs/cli/state/inspect.mdx @@ -1,21 +1,21 @@ --- -page_title: Inspecting State - Terraform CLI +page_title: Inspecting State - OpenTF CLI description: Commands that allow you to read and update state. --- # Inspecting State -Terraform includes some commands for reading and updating state without taking +OpenTF includes some commands for reading and updating state without taking any other actions. -- [The `terraform state list` command](/terraform/cli/commands/state/list) - shows the resource addresses for every resource Terraform knows about in a +- [The `opentf state list` command](/opentf/cli/commands/state/list) + shows the resource addresses for every resource OpenTF knows about in a configuration, optionally filtered by partial resource address. -- [The `terraform state show` command](/terraform/cli/commands/state/show) +- [The `opentf state show` command](/opentf/cli/commands/state/show) displays detailed state data about one resource. -- [The `terraform refresh` command](/terraform/cli/commands/refresh) updates +- [The `opentf refresh` command](/opentf/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 326cd9f8fc..5fdea47303 100644 --- a/website/docs/cli/state/move.mdx +++ b/website/docs/cli/state/move.mdx @@ -1,5 +1,5 @@ --- -page_title: Moving Resources - Terraform CLI +page_title: Moving Resources - OpenTF CLI description: >- Commands that allow you to manage the way that resources are tracked in state. They are helpful when you move or change resources. @@ -7,41 +7,39 @@ description: >- # Moving Resources -Terraform's state associates each real-world object with a configured resource -at a specific [resource address](/terraform/cli/state/resource-addressing). This -is seamless when changing a resource's attributes, but Terraform will lose track +OpenTF's state associates each real-world object with a configured resource +at a specific [resource address](/opentf/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. -Usually that's fine: Terraform will destroy the old resource, replace it with a +Usually that's fine: OpenTF will destroy the old resource, replace it with a new one (using the new resource address), and update any resources that rely on its attributes. In cases where it's important to preserve an existing infrastructure object, you -can explicitly tell Terraform to associate it with a different configured +can explicitly tell OpenTF to associate it with a different configured resource. For most cases we recommend using -[the Terraform language's refactoring features](/terraform/language/modules/develop/refactoring) +[the OpenTF language's refactoring features](/opentf/language/modules/develop/refactoring) to document in your module exactly how the resource names have changed over -time. Terraform reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps. - -> **Hands On:** Try the [Use Configuration to Move Resources](/terraform/tutorials/configuration-language/move-config) tutorial. +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 Terraform commands: +though. For those, consider the following OpenTF commands: -- [The `terraform state mv` command](/terraform/cli/commands/state/mv) changes +- [The `opentf state mv` command](/opentf/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 `terraform state rm` command](/terraform/cli/commands/state/rm) tells - Terraform to stop managing a resource as part of the current working directory +- [The `opentf state rm` command](/opentf/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 `terraform import` to start managing that resource in a - different workspace or a different Terraform configuration.) + can later use `opentf import` to start managing that resource in a + different workspace or a different OpenTF configuration.) -- [The `terraform state replace-provider` command](/terraform/cli/commands/state/replace-provider) +- [The `opentf state replace-provider` command](/opentf/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 07675491c0..b54790164f 100644 --- a/website/docs/cli/state/recover.mdx +++ b/website/docs/cli/state/recover.mdx @@ -1,7 +1,7 @@ --- -page_title: Recovering from State Disasters - Terraform CLI +page_title: Recovering from State Disasters - OpenTF CLI description: >- - Learn how to restore state backups and override Terraform state protections to fix state errors with the Terraform CLI. + Learn how to restore state backups and override OpenTF state protections to fix state errors with the OpenTF CLI. --- @@ -11,15 +11,15 @@ If something has gone horribly wrong (possibly due to accidents when performing other state manipulation actions), you might need to take drastic actions with your state data. -- [The `terraform force-unlock` command](/terraform/cli/commands/force-unlock) can - override the protections Terraform uses to prevent two processes from - modifying state at the same time. You might need this if a Terraform process +- [The `opentf force-unlock` command](/opentf/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 destruction of the VM it's running in) before it can release its lock on the state backend. Do not run this until you are completely certain what happened to the process that caused the lock to get stuck. -- [The `terraform state pull` command](/terraform/cli/commands/state/pull) and - [the `terraform state push` command](/terraform/cli/commands/state/push) can +- [The `opentf state pull` command](/opentf/cli/commands/state/pull) and + [the `opentf state push` command](/opentf/cli/commands/state/push) can directly read and write entire state files from and to the configured backend. You might need this for obtaining or restoring a state backup. diff --git a/website/docs/cli/state/resource-addressing.mdx b/website/docs/cli/state/resource-addressing.mdx index 072e9c205c..f6305f82e0 100644 --- a/website/docs/cli/state/resource-addressing.mdx +++ b/website/docs/cli/state/resource-addressing.mdx @@ -16,7 +16,7 @@ An address is made up of two parts: [module path][resource spec] ``` -In some contexts Terraform might allow for an incomplete resource address that +In some contexts OpenTF might allow for an incomplete resource address that only refers to a module as a whole, or that omits the index for a multi-instance resource. In those cases, the meaning depends on the context, so you'll need to refer to the documentation for the specific feature you @@ -50,9 +50,6 @@ An example of the `module` keyword delineating between two modules that have mul module.foo[0].module.bar["a"] ``` --> Module index only applies to modules in Terraform v0.13 or later. In earlier -versions of Terraform, a module could not have multiple instances. - ## Resource spec A resource spec addresses a specific resource instance in the selected module. @@ -68,10 +65,7 @@ resource_type.resource_name[instance index] to select an instance from a resource that has multiple instances, surrounded by square bracket characters (`[` and `]`). --> In Terraform v0.12 and later, a resource spec without a module path prefix -matches only resources in the root module. In earlier versions, a resource spec -without a module path prefix would match resources with the same type and name -in any descendent module. +A resource spec without a module path prefix matches only resources in the root module. ## Index values for Modules and Resources @@ -88,7 +82,7 @@ The following specifications apply to index values on modules and resources with ### count Example -Given a Terraform config that includes: +Given a OpenTF config that includes: ```hcl resource "aws_instance" "web" { @@ -113,13 +107,13 @@ Refers to all four "web" instances. ### for_each Example -Given a Terraform config that includes: +Given a OpenTF config that includes: ```hcl resource "aws_instance" "web" { # ... for_each = { - "terraform": "value1", + "opentf": "value1", "resource": "value2", "indexing": "value3", "example": "value4", diff --git a/website/docs/cli/state/taint.mdx b/website/docs/cli/state/taint.mdx index aadf703513..18ff36e1c5 100644 --- a/website/docs/cli/state/taint.mdx +++ b/website/docs/cli/state/taint.mdx @@ -1,28 +1,28 @@ --- -page_title: Forcing Re-creation of Resources - Terraform CLI +page_title: Forcing Re-creation of Resources - OpenTF CLI description: Commands that allow you to destroy and re-create resources manually. --- # Forcing Re-creation of Resources -During planning, by default Terraform retrieves the latest state of each +During planning, by default OpenTF retrieves the latest state of each existing object and compares it with the current configuration, planning actions only against objects whose current state does not match the configuration. However, in some cases a remote object may become damaged or degraded in a -way that Terraform cannot automatically detect. For example, if software +way that OpenTF cannot automatically detect. For example, if software running inside a virtual machine crashes but the virtual machine itself is -still running then Terraform will typically have no way to detect and respond -to the problem, because Terraform only directly manages the machine as a whole. +still running then OpenTF will typically have no way to detect and respond +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 Terraform to -replace it for any other reason, you can override Terraform's default behavior -using [the `-replace=...` planning option](/terraform/cli/commands/plan#replace-address) -when you run either `terraform plan` or `terraform apply`: +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) +when you run either `opentf plan` or `opentf apply`: ```shellsession -$ terraform apply -replace="aws_instance.example" +$ opentf apply -replace="aws_instance.example" # ... # aws_instance.example will be replaced, as requested @@ -33,13 +33,13 @@ $ terraform apply -replace="aws_instance.example" ## The "tainted" status -Sometimes Terraform is able to infer automatically that an object is in an +Sometimes OpenTF is able to infer automatically that an object is in an incomplete or degraded state. For example, if creation of a complex object fails in such a way that parts of it already exist in the remote system, or if object creation succeeded but a provisioner step subsequently failed, -Terraform must remember that the object exists but may not be fully-functional. +OpenTF must remember that the object exists but may not be fully-functional. -Terraform represents this situation by marking an object in the state as +OpenTF represents this situation by marking an object in the state as "tainted". When an object is marked with this status, the next plan will force replacing that object in a similar way to if you had specified that object's address using `-replace=...` as described above. @@ -51,13 +51,13 @@ address using `-replace=...` as described above. } ``` -If Terraform has marked an object as tainted but you consider it to be working -correctly and do not want to replace it, you can override Terraform's -determination using [the `terraform untaint` command](/terraform/cli/commands/untaint), -after which Terraform will consider the object to be ready for use by any +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), +after which OpenTF will consider the object to be ready for use by any downstream resource declarations. -You can also _force_ Terraform to mark a particular object as tainted using -[the `terraform taint` command](/terraform/cli/commands/taint), but that approach is +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 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 700733df14..4c0e69bc63 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Managing Workspaces - Terraform CLI +page_title: Managing Workspaces - OpenTF CLI description: >- Commands to list, select, create, and output workspaces. Workspaces help manage different groups of resources with one configuration. @@ -7,27 +7,27 @@ description: >- # Managing Workspaces -Workspaces in the Terraform CLI refer to separate instances of [state data](/terraform/language/state) inside the same Terraform working directory. They are distinctly different from [workspaces in Terraform Cloud](/terraform/cloud-docs/workspaces), which each have their own Terraform configuration and function as separate working directories. +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. -Terraform relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, Terraform can manage multiple sets of non-overlapping resources. +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. -Workspaces can be helpful for specific [use cases](#use-cases), but they are not required to use the Terraform CLI. We recommend using [alternative approaches](#alternatives-to-workspaces) for complex deployments requiring separate credentials and access controls. +Workspaces can be helpful for specific [use cases](#use-cases), but they are not required to use the OpenTF CLI. We recommend using [alternative approaches](#alternatives-to-workspaces) for complex deployments requiring separate credentials and access controls. ## Managing CLI Workspaces -Every [initialized working directory](/terraform/cli/init) starts with one workspace named `default`. +Every [initialized working directory](/opentf/cli/init) starts with one workspace named `default`. -Use the [`terraform workspace list`](/terraform/cli/commands/workspace/list), [`terraform workspace new`](/terraform/cli/commands/workspace/new), and [`terraform workspace delete`](/terraform/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory. +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 `terraform workspace select` command](/terraform/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 Terraform commands only interact with the currently selected workspace. This includes [provisioning](/terraform/cli/run) and [state manipulation](/terraform/cli/state). +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). -When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/terraform/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region. +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. ## Use Cases -You can create multiple [working directories](/terraform/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, Terraform installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches. +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. 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. @@ -40,7 +40,7 @@ The default workspace might correspond to the `main` or `trunk` branch, which de Workspaces let you quickly switch between multiple instances of a **single configuration** within its **single backend**. They are not designed to solve all problems. -When using Terraform to manage larger systems, you should create separate Terraform configurations that correspond to architectural boundaries within the system. This lets teams manage different components separately. Workspaces alone are not a suitable tool for system decomposition because each subsystem should have its own separate configuration and backend. +When using OpenTF to manage larger systems, you should create separate OpenTF configurations that correspond to architectural boundaries within the system. This lets teams manage different components separately. Workspaces alone are not a suitable tool for system decomposition because each subsystem should have its own separate configuration and backend. In particular, organizations commonly want to create a strong separation between multiple deployments of the same infrastructure serving different @@ -48,39 +48,26 @@ 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](/terraform/language/modules/develop) to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different [backend](/terraform/language/settings/backends/configuration). The root module of each configuration consists only of a backend configuration and a small number of `module` blocks with arguments describing any small differences between the deployments. +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. 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. -- When a shared [Consul](https://www.consul.io/) cluster is available, use [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys) to retrieve those values in other configurations. +- If you have a configuration management system accessible from all configurations, then one can use a `resource` to export variables, while another configuration can use a `datasource` to import them. - In systems that support user-defined labels or tags, use a tagging convention to make resources automatically discoverable. For example, use [the `aws_vpc` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) to assign suitable tags and then [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) to query by those tags in other configurations. - 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 Terraform state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/terraform/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system. - - -## Interactions with Terraform Cloud Workspaces - -Terraform Cloud organizes infrastructure using workspaces, but its workspaces -act more like completely separate working directories. Each Terraform Cloud -workspace has its own Terraform configuration, set of variable values, state -data, run history, and settings. - -When you [integrate Terraform CLI with Terraform Cloud](/terraform/cli/cloud), you can associate the current CLI working directory with one or more remote Terraform Cloud workspaces. Then, use the `terraform workspace` commands to select the remote workspace you want to use for each run. - -Refer to [CLI-driven Runs](/terraform/cloud-docs/run/cli) in the Terraform Cloud documentation for more details. - +- 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. ## Workspace Internals -Workspaces are technically equivalent to renaming your state file. Terraform then includes a set of protections and support for remote state. +Workspaces are technically equivalent to renaming your state file. OpenTF then includes a set of protections and support for remote state. Workspaces are also meant to be a shared resource. They are not private, unless you use purely local state and do not commit your state to version control. -For local state, Terraform 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 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](/terraform/language/state/remote), the workspaces are stored directly in the configured [backend](/terraform/language/settings/backends/configuration). For example, if you use [Consul](/terraform/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](/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. -Terraform 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 Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [CLI Integration (recommended)](/terraform/cli/cloud/settings#arguments) and [remote backend](/terraform/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)](/opentf/cli/cloud/settings#arguments) and [remote backend](/opentf/language/settings/backends/remote#workspaces) and documentation.