jprdonnelly/opentf
1
0
Fork 0
mirror of https://github.com/opentffoundation/opentf.git synced 2025-12-19 17:59:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Rename website to OpenTofu (#516)

Browse Source 
Co-authored-by: Damian Stasik <920747+damianstasik@users.noreply.github.com>
Co-authored-by: Roman Grinovski <roman.grinovski@gmail.com>
This commit is contained in:
Julien Levasseur
2023-09-21 05:57:47 -04:00
committed by GitHub
parent e5878055b6
commit 4c0bda5386
221 changed files with 2497 additions and 2497 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
website/README.md
View File

@@ -1,12 +1,12 @@
# OpenTF Documentation
# OpenTofu Documentation
This directory contains the portions of [the OpenTF website](https://placeholderplaceholderplaceholder.io/) that pertain to the core functionality, excluding providers and the overall configuration.
This directory contains the portions of [the OpenTofu website](https://opentofu.org) that pertain to the core functionality, excluding providers and the overall configuration.
## Suggesting Changes
You can [submit an issue](https://github.com/opentffoundation/opentf/issues/new/choose) with documentation requests or submit a pull request with suggested changes.
You can [submit an issue](https://github.com/opentofu/opentofu/issues/new/choose) with documentation requests or submit a pull request with suggested changes.
Click **Edit this page** at the bottom of any OpenTF website page to go directly to the associated markdown file in GitHub.
Click **Edit this page** at the bottom of any OpenTofu website page to go directly to the associated markdown file in GitHub.
## Validating Content
@@ -24,9 +24,9 @@ You must update the sidebar navigation when you add or delete documentation .mdx
To update the sidebar navigation, you must edit the appropriate `nav-data.json` file. This repository contains the sidebar navigation files for the following documentation sets:
- OpenTF Language: [`language-nav-data.json`](https://github.com/opentffoundation/opentf/blob/main/website/data/language-nav-data.json)
- OpenTF CLI: [`cli-nav-data.json`](https://github.com/opentffoundation/opentf/blob/main/website/data/cli-nav-data.json)
- Introduction to OpenTF: [`intro-nav-data.json`](https://github.com/opentffoundation/opentf/blob/main/website/data/intro-nav-data.json)
- OpenTofu Language: [`language-nav-data.json`](https://github.com/opentofu/opentofu/blob/main/website/data/language-nav-data.json)
- OpenTofu CLI: [`cli-nav-data.json`](https://github.com/opentofu/opentofu/blob/main/website/data/cli-nav-data.json)
- Introduction to OpenTofu: [`intro-nav-data.json`](https://github.com/opentofu/opentofu/blob/main/website/data/intro-nav-data.json)
## Previewing Changes

2
website/data/cli-nav-data.json
View File

@@ -1,5 +1,5 @@
[
{ "heading": "OpenTF CLI" },
{ "heading": "OpenTofu CLI" },
{ "title": "Overview", "path": "cli/index" },
{ "title": "Basic CLI Features", "path": "cli/commands/index" },
{

4
website/data/internals-nav-data.json
View File

@@ -1,5 +1,5 @@
[
{ "heading": "OpenTF Internals" },
{ "heading": "OpenTofu Internals" },
{
"title": "Overview",
"path": "internals/index"
@@ -9,7 +9,7 @@
"path": "internals/credentials-helpers"
},
{
"title": "Debugging OpenTF",
"title": "Debugging OpenTofu",
"path": "internals/debugging"
},
{

8
website/data/intro-nav-data.json
View File

@@ -1,10 +1,10 @@
[
{ "heading": "Introduction to OpenTF" },
{ "title": "What is OpenTF?", "path": "intro/index" },
{ "heading": "Introduction to OpenTofu" },
{ "title": "What is OpenTofu?", "path": "intro/index" },
{ "title": "Use Cases", "path": "intro/use-cases" },
{ "title": "The Core OpenTF Workflow", "path": "intro/core-workflow" },
{ "title": "The Core OpenTofu Workflow", "path": "intro/core-workflow" },
{
"title": "OpenTF vs. Alternatives",
"title": "OpenTofu vs. Alternatives",
"routes": [
{ "title": "Overview", "path": "intro/vs/index" },
{ "title": "Chef, Puppet, etc.", "path": "intro/vs/chef-puppet" },

6
website/data/language-nav-data.json
View File

@@ -1,5 +1,5 @@
[
{ "heading": "OpenTF Language" },
{ "heading": "OpenTofu Language" },
{ "title": "Overview", "path": "language/index" },
{
"title": "Attributes as Blocks - Configuration Language",
@@ -1188,7 +1188,7 @@
]
},
{
"title": "OpenTF Settings",
"title": "OpenTofu Settings",
"routes": [
{ "title": "Overview", "path": "language/settings/index" },
{
@@ -1333,7 +1333,7 @@
]
},
{
"title": "Upgrading to OpenTF v1.5",
"title": "Upgrading to OpenTofu v1.5",
"path": "language/upgrade-guides/index"
},
{

12
website/docs/cli/auth/index.mdx
View File

@@ -7,12 +7,12 @@ description: >-
# CLI Authentication
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.
offering OpenTofu runs to provision infrastructure, offering a collaboration-focused
environment that makes it easier for teams to use OpenTofu together.
OpenTF CLI integrates with TACOS in several ways — it can be a
OpenTofu 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
registry, or a private provider registry. All of these integrations require you to authenticate OpenTofu CLI
with your TACOS account.
The best way to handle CLI authentication is with the `login` and `logout`
@@ -21,5 +21,5 @@ TACOS user account.
For details, see:
- [The `opentf login` command](/docs/cli/commands/login)
- [The `opentf logout` command](/docs/cli/commands/logout)
- [The `tofu login` command](/docs/cli/commands/login)
- [The `tofu logout` command](/docs/cli/commands/logout)

8
website/docs/cli/cloud/command-line-arguments.mdx
View File

@@ -5,19 +5,19 @@ description: Command Line Arguments
# Command Line Arguments
When your configuration includes a `cloud` block, commands that
make local modifications to OpenTF state and then push them back up to the remote workspace
make local modifications to OpenTofu 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
OpenTF versions agree, making an operation proceed even when there is
OpenTofu versions agree, making an operation proceed even when there is
a mismatch.
State-modification operations usually require using a local version of the
OpenTF CLI that is compatible with the OpenTF version selected
OpenTofu CLI that is compatible with the OpenTofu 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 cloud backend workspace that is no longer able to complete remote operations with the currently
selected version of OpenTF.
selected version of OpenTofu.

10
website/docs/cli/cloud/index.mdx
View File

@@ -1,13 +1,13 @@
---
description: >-
Learn how to use a cloud backend on the command line with the OpenTF CLI.
Learn how to use a cloud backend on the command line with the OpenTofu CLI.
---
# Using the Cloud Backend with OpenTF CLI
# Using the Cloud Backend with OpenTofu CLI
The OpenTF CLI lets you use cloud backends on the command line.
The OpenTofu CLI lets you use cloud backends on the command line.
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.
When you use the cloud backend CLI workflow, operations like `tofu plan` or `tofu 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 OpenTofu CLI workflow. Cloud backend services may choose to implement only a subset of the available features.
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.
@@ -16,4 +16,4 @@ Workspaces can also be configured for local execution, in which case the cloud b
- [Cloud Backend Settings](/docs/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable cloud backend support.
- [Initializing and Migrating](/docs/cli/cloud/migrating) describes
how to start using the cloud backend with a working directory that already has state data.
- [Command Line Arguments](/docs/cli/cloud/command-line-arguments) lists the OpenTF command flags that are specific to using OpenTF with the cloud backend.
- [Command Line Arguments](/docs/cli/cloud/command-line-arguments) lists the OpenTofu command flags that are specific to using OpenTofu with the cloud backend.

28
website/docs/cli/cloud/migrating.mdx
View File

@@ -1,45 +1,45 @@
---
description: >-
Learn how to use the OpenTF CLI to migrate local or remote state to a Cloud Backend.
Learn how to use the OpenTofu CLI to migrate local or remote state to a Cloud Backend.
---
# Initializing and Migrating
After [configuring cloud backend settings](/docs/cli/cloud/settings) for a working directory, you must run `opentf init` to finish setting up. If the working directory has no existing OpenTF state, you can start using OpenTF with a cloud backend right away.
After [configuring cloud backend settings](/docs/cli/cloud/settings) for a working directory, you must run `tofu init` to finish setting up. If the working directory has no existing OpenTofu state, you can start using OpenTofu with a cloud backend right away.
When you run `opentf init` in the following scenarios, OpenTF will ask you to choose whether or not to migrate state from any existing workspaces.
When you run `tofu init` in the following scenarios, OpenTofu 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, OpenTF will ask if you would like to migrate that state to new cloud backend 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, OpenTofu 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 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.
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, OpenTofu 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
If the working directory already has state data available (using either local state or a [state
backend](/docs/language/settings/backends/configuration)), OpenTF asks your approval to migrate
backend](/docs/language/settings/backends/configuration)), OpenTofu 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.
OpenTF may also prompt you to rename your workspaces during the migration, to either give a name to
OpenTofu 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
your workspace names more contextual information. Unlike OpenTofu CLI-only workspaces, which represent
multiple environments associated with the same configuration (e.g. production, staging, development),
cloud backend workspaces can represent totally independent configurations, and must have unique names within the cloud backend organization.
Because of this, OpenTF will prompt you to rename the working directory's workspaces
Because of this, OpenTofu 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
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`,
`networking-staging-us-east`).
## 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. 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, OpenTofu 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](/docs/language/settings/backends/remote) was the primary implementation for cloud backends for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for OpenTF and Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements.
The [`remote` backend](/docs/language/settings/backends/remote) was the primary implementation for cloud backends for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for OpenTofu 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, OpenTF will continue using the same
When switching from the `remote` backend to a `cloud` block, OpenTofu will continue using the same
set of cloud backend workspaces. Replace your `backend "remote"` block with an equivalent `cloud`
block.
@@ -65,7 +65,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, OpenTF 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, OpenTofu will add the specified tags to the workspaces if necessary.
```diff
terraform {
@@ -82,5 +82,5 @@ 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 OpenTF CLI. For example, rather than `opentf workspace select prod`, you must run the command `opentf workspace select my-app-prod`.
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 OpenTofu CLI. For example, rather than `tofu workspace select prod`, you must run the command `tofu workspace select my-app-prod`.
:::

32
website/docs/cli/cloud/settings.mdx
View File

@@ -5,18 +5,18 @@ description: >-
# Cloud Backend Settings
OpenTF CLI can integrate with a cloud backend, acting as a client for it.
OpenTofu CLI can integrate with a cloud backend, acting as a client for it.
You must configure the following settings to use the cloud backend for a particular working directory:
- Provide credentials to access the cloud backend, preferably by using the
[`opentf login`](/docs/cli/commands/login) command.
- Add a `cloud` block to the directory's OpenTF configuration, to specify
[`tofu login`](/docs/cli/commands/login) command.
- Add a `cloud` block to the directory's OpenTofu 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 OpenTF configuration when running plans and applies.
uploaded with the OpenTofu configuration when running plans and applies.
After adding or changing a `cloud` block, you must run `opentf init`.
After adding or changing a `cloud` block, you must run `tofu init`.
## The `cloud` Block
@@ -46,7 +46,7 @@ The `cloud` block also has some special restrictions:
- A `cloud` block cannot refer to named values (like input variables, locals, or
data source attributes).
The `cloud` block only affects OpenTF CLI's behavior. When the cloud backend uses a configuration
The `cloud` block only affects OpenTofu 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.
@@ -65,28 +65,28 @@ The `cloud` block supports the following configuration arguments:
- `tags` - (Optional) A set of cloud backend workspace tags. You will be able to use
this working directory with any workspaces that have all of the specified tags,
and can use [the `opentf workspace` commands](/docs/cli/workspaces)
and can use [the `tofu workspace` commands](/docs/cli/workspaces)
to switch between them or create new workspaces. New workspaces will automatically have
the specified tags. This option conflicts with `name`.
- `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. `opentf workspace select` or
`opentf workspace new`). This option conflicts with `tags`.
directory, and cannot manage workspaces from the CLI (e.g. `tofu workspace select` or
`tofu workspace new`). This option conflicts with `tags`.
- `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
will be created within this project. `tofu workspace list` will be filtered by workspaces
in the supplied project.
- `token` - (Optional) The token used to authenticate with the cloud backend.
We recommend omitting the token from the configuration, and instead using
[`opentf login`](/docs/cli/commands/login) or manually configuring
[`tofu login`](/docs/cli/commands/login) or manually configuring
`credentials` in the
[CLI config file](/docs/cli/config/config-file#credentials).
### Environment Variables
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 OpenTofu as part of a Continuous Integration (CI) pipeline. OpenTofu 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.
@@ -94,13 +94,13 @@ Remote execution with non-interactive workflows requires auto-approved deploymen
Use the following environment variables to configure the `cloud` block:
- `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_ORGANIZATION` - The name of the organization. OpenTofu reads this variable when `organization` 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_HOSTNAME` - The hostname of the cloud backend. OpenTofu 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 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_CLOUD_PROJECT` - The name of a cloud backend project. OpenTofu reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence.
- `TF_WORKSPACE` - The name of a single cloud backend workspace. OpenTF reads this when `workspaces` is omitted from the `cloud` block. The cloud backend will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/docs/cli/config/environment-variables#tf_workspace) for details.
- `TF_WORKSPACE` - The name of a single cloud backend workspace. OpenTofu reads this when `workspaces` is omitted from the `cloud` block. The cloud backend will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/docs/cli/config/environment-variables#tf_workspace) for details.
## Excluding Files from Upload with .terraformignore

22
website/docs/cli/code/index.mdx
View File

@@ -1,31 +1,31 @@
---
description: >-
Learn commands that help validate, format, and upgrade code written in the
OpenTF Configuration Language.
OpenTofu Configuration Language.
---
# Writing and Modifying OpenTF Code
# Writing and Modifying OpenTofu Code
The [OpenTF language](/docs/language) is OpenTF's primary
user interface, and all of OpenTF's workflows rely on configurations written
in the OpenTF language.
The [OpenTofu language](/docs/language) is OpenTofu's primary
user interface, and all of OpenTofu's workflows rely on configurations written
in the OpenTofu language.
OpenTF CLI includes several commands to make OpenTF code more convenient
OpenTofu CLI includes several commands to make OpenTofu code more convenient
to work with. Integrating these commands into your editing workflow can
potentially save you time and effort.
- [The `opentf console` command](/docs/cli/commands/console) starts an
interactive shell for evaluating OpenTF
- [The `tofu console` command](/docs/cli/commands/console) starts an
interactive shell for evaluating OpenTofu
[expressions](/docs/language/expressions), which can be a faster way
to verify that a particular resource argument results in the value you expect.
- [The `opentf fmt` command](/docs/cli/commands/fmt) rewrites OpenTF
- [The `tofu fmt` command](/docs/cli/commands/fmt) rewrites OpenTofu
configuration files to a canonical format and style, so you don't have to
waste time making minor adjustments for readability and consistency. It works
well as a pre-commit hook in your version control system.
- [The `opentf validate` command](/docs/cli/commands/validate) validates the
syntax and arguments of the OpenTF configuration files in a directory,
- [The `tofu validate` command](/docs/cli/commands/validate) validates the
syntax and arguments of the OpenTofu 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

46
website/docs/cli/commands/apply.mdx
View File

@@ -1,47 +1,47 @@
---
description: >-
The opentf apply command executes the actions proposed in a OpenTF plan
The tofu apply command executes the actions proposed in a OpenTofu plan
to create, update, or destroy infrastructure.
---
# Command: apply
The `opentf apply` command executes the actions proposed in a OpenTF
The `tofu apply` command executes the actions proposed in a OpenTofu
plan.
## Usage
Usage: `opentf apply [options] [plan file]`
Usage: `tofu apply [options] [plan file]`
### Automatic Plan Mode
When you run `opentf apply` without passing a saved plan file, OpenTF automatically creates a new execution plan as if you had run [`opentf plan`](/docs/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/docs/cli/commands/plan#planning-modes) and
[planning options](/docs/cli/commands/plan#planning-options) to customize how OpenTF will create the plan.
When you run `tofu apply` without passing a saved plan file, OpenTofu automatically creates a new execution plan as if you had run [`tofu plan`](/docs/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/docs/cli/commands/plan#planning-modes) and
[planning options](/docs/cli/commands/plan#planning-options) to customize how OpenTofu will create the plan.
You can pass the `-auto-approve` option to instruct OpenTF to apply the plan without asking for confirmation.
You can pass the `-auto-approve` option to instruct OpenTofu to apply the plan without asking for confirmation.
:::danger 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.
If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your OpenTofu workflow. This minimizes the risk of unpredictable changes and configuration drift.
:::
### Saved Plan Mode
When you pass a [saved plan file](/docs/cli/commands/plan#out-filename) to `opentf apply`, OpenTF takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when running OpenTF in automation.
When you pass a [saved plan file](/docs/cli/commands/plan#out-filename) to `tofu apply`, OpenTofu takes the actions in the saved plan without prompting you for confirmation. You may want to use this two-step workflow when running OpenTofu in automation.
Use [`opentf show`](/docs/cli/commands/show) to inspect a saved plan file before applying it.
Use [`tofu show`](/docs/cli/commands/show) to inspect a saved plan file before applying it.
When using a saved plan, you cannot specify any additional planning modes or options. These options only affect OpenTF's decisions about which
When using a saved plan, you cannot specify any additional planning modes or options. These options only affect OpenTofu'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, `opentf apply` supports all planning modes and planning options available for `opentf plan`.
Without a saved plan file, `tofu apply` supports all planning modes and planning options available for `tofu plan`.
- **[Planning Modes](/docs/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update OpenTF state and root module output values.
- **[Planning Options](/docs/cli/commands/plan#planning-options):** These include specifying which resource instances OpenTF should replace, setting OpenTF input variables, etc.
- **[Planning Modes](/docs/cli/commands/plan#planning-modes):** These include `-destroy`, which creates a plan to destroy all remote objects, and `-refresh-only`, which creates a plan to update OpenTofu state and root module output values.
- **[Planning Options](/docs/cli/commands/plan#planning-options):** These include specifying which resource instances OpenTofu should replace, setting OpenTofu input variables, etc.
### Apply Options
@@ -49,7 +49,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
OpenTF considers you passing the plan file as the approval and so
OpenTofu 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
@@ -57,9 +57,9 @@ 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 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
- `-input=false` - Disables all of OpenTofu's interactive prompts. Note that
this also prevents OpenTofu from prompting for interactive approval of a
plan, so OpenTofu 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.
@@ -74,31 +74,31 @@ The following options change how the apply command executes and reports on the a
workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs OpenTF to retry acquiring a lock for a period of time before
instructs OpenTofu 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 OpenTF in a context where its output will be
if you are running OpenTofu 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 OpenTF
- `-parallelism=n` - Limit the number of concurrent operation as OpenTofu
[walks the graph](/docs/internals/graph#walking-the-graph). Defaults to
10\.
- All [planning modes](/docs/cli/commands/plan#planning-modes) and
[planning options](/docs/cli/commands/plan#planning-options) for
`opentf plan` - Customize how OpenTF will create the plan. Only available when you run `opentf apply` without a saved plan file.
`tofu plan` - Customize how OpenTofu will create the plan. Only available when you run `tofu apply` without a saved plan file.
For configurations using
[the `local` backend](/docs/language/settings/backends/local) only,
`opentf apply` also accepts the legacy options
`tofu apply` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments).
## Passing a Different Configuration Directory
If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](/docs/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes OpenTF consistently look
instead, which works across all commands and makes OpenTofu consistently look
in the given directory for all files it would normally read or write in the
current working directory.

20
website/docs/cli/commands/console.mdx
View File

@@ -1,17 +1,17 @@
---
description: >-
The opentf console command provides an interactive console for evaluating
The tofu console command provides an interactive console for evaluating
expressions.
---
# Command: console
The `opentf console` command provides an interactive console for
The `tofu console` command provides an interactive console for
evaluating [expressions](/docs/language/expressions).
## Usage
Usage: `opentf console [options]`
Usage: `tofu console [options]`
This command provides an interactive command-line console for evaluating and
experimenting with [expressions](/docs/language/expressions).
@@ -25,19 +25,19 @@ or Control-D.
For configurations using
[the `local` backend](/docs/language/settings/backends/local) only,
`opentf console` accepts the legacy command line option
`tofu console` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local#command-line-arguments).
## Scripting
The `opentf console` command can be used in non-interactive scripts
The `tofu 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")' | opentf console
$ echo 'split(",", "foo,bar,baz")' | tofu console
tolist([
"foo",
"bar",
@@ -48,13 +48,13 @@ tolist([
## Remote State
If [remote state](/docs/language/state/remote) is used by the current backend,
OpenTF will read the state for the current workspace from the backend
OpenTofu will read the state for the current workspace from the backend
before evaluating any expressions.
## Examples
The `opentf console` command will read the OpenTF configuration in the
current working directory and the OpenTF state file from the configured
The `tofu console` command will read the OpenTofu configuration in the
current working directory and the OpenTofu state file from the configured
backend so that interpolations can be tested against both the values in the
configuration and the state file.
@@ -81,7 +81,7 @@ resource "random_pet" "example" {
}
```
Executing `opentf console` will drop you into an interactive shell where you
Executing `tofu console` will drop you into an interactive shell where you
can test interpolations to:
Print a value from a map:

20
website/docs/cli/commands/destroy.mdx
View File

@@ -1,32 +1,32 @@
---
description: >-
The opentf destroy command destroys all objects managed by a OpenTF
The tofu destroy command destroys all objects managed by a OpenTofu
configuration.
---
# Command: destroy
The `opentf destroy` command is a convenient way to destroy all remote
objects managed by a particular OpenTF configuration.
The `tofu destroy` command is a convenient way to destroy all remote
objects managed by a particular OpenTofu configuration.
While you will typically not want to destroy long-lived objects in a production
environment, OpenTF is sometimes used to manage ephemeral infrastructure
for development purposes, in which case you can use `opentf destroy` to
environment, OpenTofu is sometimes used to manage ephemeral infrastructure
for development purposes, in which case you can use `tofu destroy` to
conveniently clean up all of those temporary objects once you are finished
with your work.
## Usage
Usage: `opentf destroy [options]`
Usage: `tofu destroy [options]`
This command is just a convenience alias for the following command:
```
opentf apply -destroy
tofu apply -destroy
```
For that reason, this command accepts most of the options that
[`opentf apply`](/docs/cli/commands/apply) accepts, although it does
[`tofu apply`](/docs/cli/commands/apply) accepts, although it does
not accept a plan file argument and forces the selection of the "destroy"
planning mode.
@@ -34,8 +34,8 @@ You can also create a speculative destroy plan, to see what the effect of
destroying would be, by running the following command:
```
opentf plan -destroy
tofu plan -destroy
```
This will run [`opentf plan`](/docs/cli/commands/plan) in _destroy_ mode, showing
This will run [`tofu plan`](/docs/cli/commands/plan) in _destroy_ mode, showing
you the proposed destroy changes without executing them.

6
website/docs/cli/commands/env.mdx
View File

@@ -1,11 +1,11 @@
---
description: >-
The opentf env command is a deprecated form of the opentf workspace
The tofu env command is a deprecated form of the tofu workspace
command.
---
# Command: env
The `opentf env` command is deprecated.
[The `opentf workspace` command](/docs/cli/commands/workspace)
The `tofu env` command is deprecated.
[The `tofu workspace` command](/docs/cli/commands/workspace)
should be used instead.

34
website/docs/cli/commands/fmt.mdx
View File

@@ -1,50 +1,50 @@
---
description: >-
The opentf fmt command rewrites configuration files to a canonical format
The tofu fmt command rewrites configuration files to a canonical format
and style.
---
# Command: fmt
The `opentf fmt` command is used to rewrite OpenTF configuration files
The `tofu fmt` command is used to rewrite OpenTofu configuration files
to a canonical format and style. This command applies a subset of
the [OpenTF language style conventions](/docs/language/syntax/style),
the [OpenTofu language style conventions](/docs/language/syntax/style),
along with other minor adjustments for readability.
Other OpenTF commands that generate OpenTF configuration will produce
configuration files that conform to the style imposed by `opentf fmt`, so
Other OpenTofu commands that generate OpenTofu configuration will produce
configuration files that conform to the style imposed by `tofu fmt`, so
using this style in your own files will ensure consistency.
The canonical format may change in minor ways between OpenTF versions, so
after upgrading OpenTF we recommend to proactively run `opentf fmt`
The canonical format may change in minor ways between OpenTofu versions, so
after upgrading OpenTofu we recommend to proactively run `tofu 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 `opentf fmt` to be a breaking
change in new versions of OpenTF, but we do aim to minimize changes for
We don't consider new formatting rules in `tofu fmt` to be a breaking
change in new versions of OpenTofu, but we do aim to minimize changes for
configurations that are already following the style examples shown in the
OpenTF documentation. When adding new formatting rules, they will usually
OpenTofu 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 `opentf fmt` doesn't yet apply automatically.
for decisions that `tofu fmt` doesn't yet apply automatically.
Formatting decisions are always subjective and so you might disagree with the
decisions that `opentf fmt` makes. This command is intentionally opinionated
decisions that `tofu fmt` makes. This command is intentionally opinionated
and has no customization options because its primary goal is to encourage
consistency of style between different OpenTF codebases, even though the
consistency of style between different OpenTofu codebases, even though the
chosen style can never be everyone's favorite.
We recommend that you follow the style conventions applied by `opentf fmt`
when writing OpenTF modules, but if you find the results particularly
We recommend that you follow the style conventions applied by `tofu fmt`
when writing OpenTofu 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 OpenTF, to get consistency between your hand-written files
automatically by OpenTofu, to get consistency between your hand-written files
and the generated files.
## Usage
Usage: `opentf fmt [options] [target...]`
Usage: `tofu 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

4
website/docs/cli/commands/force-unlock.mdx
View File

@@ -1,6 +1,6 @@
---
description: >-
The opentf force-unlock command unlocks the state for a configuration. It
The tofu force-unlock command unlocks the state for a configuration. It
does not modify your infrastructure.
---
@@ -15,7 +15,7 @@ process.
## Usage
Usage: `opentf force-unlock [options] LOCK_ID`
Usage: `tofu force-unlock [options] LOCK_ID`
Manually unlock the state for the defined configuration.

6
website/docs/cli/commands/get.mdx
View File

@@ -1,15 +1,15 @@
---
description: The opentf get command downloads and updates modules.
description: The tofu get command downloads and updates modules.
---
# Command: get
The `opentf get` command is used to download and update
The `tofu get` command is used to download and update
[modules](/docs/language/modules/develop) mentioned in the root module.
## Usage
Usage: `opentf get [options]`
Usage: `tofu get [options]`
The modules are downloaded into a `.terraform` subdirectory of the current
working directory. Don't commit this directory to your version control

16
website/docs/cli/commands/graph.mdx
View File

@@ -1,28 +1,28 @@
---
description: >-
The opentf graph command generates a visual representation of a
The tofu graph command generates a visual representation of a
configuration or execution plan that you can use to generate charts.
---
# Command: graph
The `opentf graph` command is used to generate a visual
The `tofu 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: `opentf graph [options]`
Usage: `tofu graph [options]`
Outputs the visual execution graph of OpenTF resources according to
Outputs the visual execution graph of OpenTofu 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. OpenTF
The `-type` flag can be used to control the type of graph shown. OpenTofu
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
@@ -38,17 +38,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 OpenTF, specified the
* `-module-depth=n` - (deprecated) In prior versions of OpenTofu, specified the
depth of modules to show in the output.
## Generating Images
The output of `opentf graph` is in the DOT format, which can
The output of `tofu graph` is in the DOT format, which can
easily be converted to an image by making use of `dot` provided
by GraphViz:
```shellsession
$ opentf graph | dot -Tsvg > graph.svg
$ tofu graph | dot -Tsvg > graph.svg
```
Here is an example graph output:

58
website/docs/cli/commands/import.mdx
View File

@@ -1,17 +1,17 @@
---
description: The opentf import command brings existing resources into OpenTF state.
description: The tofu import command brings existing resources into OpenTofu state.
---
# Command: import
The `opentf import` command [imports existing resources](/docs/cli/import)
into OpenTF.
The `tofu import` command [imports existing resources](/docs/cli/import)
into OpenTofu.
## Usage
Usage: `opentf import [options] ADDRESS ID`
Usage: `tofu import [options] ADDRESS ID`
Import will find the existing resource from ID and import it into your OpenTF
Import will find the existing resource from ID and import it into your OpenTofu
state at the given ADDRESS.
ADDRESS must be a valid [resource address](/docs/cli/state/resource-addressing).
@@ -25,20 +25,20 @@ 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
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
OpenTofu expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by OpenTofu
itself having created all objects. If you import existing objects into OpenTofu,
be careful to import each remote object to only one OpenTofu resource address.
If you import the same object multiple times, OpenTofu may exhibit unwanted
behavior. For more information on this assumption, see
[the State section](/docs/language/state).
:::
The command-line flags are all optional. The following flags are available:
- `-config=path` - Path to directory of OpenTF configuration files that
- `-config=path` - Path to directory of OpenTofu configuration files that
configure the provider for import. This defaults to your working directory.
If this directory contains no OpenTF configuration files, the provider
If this directory contains no OpenTofu configuration files, the provider
must be configured via manual input or environmental variables.
- `-input=true` - Whether to ask for input for provider configuration.
@@ -51,20 +51,20 @@ The command-line flags are all optional. The following flags are available:
- `-no-color` - If specified, output won't contain any color.
- `-parallelism=n` - Limit the number of concurrent operation as OpenTF
- `-parallelism=n` - Limit the number of concurrent operation as OpenTofu
[walks the graph](/docs/internals/graph#walking-the-graph). Defaults
to 10.
- `-provider=provider` - **Deprecated** Override the provider configuration to
use when importing the object. By default, OpenTF uses the provider specified
use when importing the object. By default, OpenTofu 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 OpenTF configuration. This flag
- `-var 'foo=bar'` - Set a variable in the OpenTofu configuration. This flag
can be set multiple times. Variable values are interpreted as
[literal expressions](/docs/language/expressions/types) in the
OpenTF language, so list and map values can be specified via this flag.
OpenTofu language, so list and map values can be specified via this flag.
- `-var-file=foo` - Set variables in the OpenTF configuration from
- `-var-file=foo` - Set variables in the OpenTofu configuration from
a [variable file](/docs/language/values/variables#variable-definitions-tfvars-files). If
a `terraform.tfvars` or any `.auto.tfvars` files are present in the current
directory, they will be automatically loaded. `terraform.tfvars` is loaded
@@ -74,30 +74,30 @@ The command-line flags are all optional. The following flags are available:
useful with the `-config` flag.
For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote)
only, `opentf import`
only, `tofu import`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using
[the `local` backend](/docs/language/settings/backends/local) only,
`opentf import` also accepts the legacy options
`tofu import` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments).
## Provider Configuration
OpenTF will attempt to load configuration files that configure the
OpenTofu 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, OpenTF will
no configuration for that specific provider is present, OpenTofu will
prompt you for access credentials. You may also specify environmental variables
to configure the provider.
The only limitation OpenTF has when reading the configuration files
The only limitation OpenTofu 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 OpenTF will configure
configuration file with the contents below, then OpenTofu will configure
the AWS provider with this file.
```hcl
@@ -115,7 +115,7 @@ provider "aws" {
This example will import an AWS instance into the `aws_instance` resource named `foo`:
```shell
$ opentf import aws_instance.foo i-abcd1234
$ tofu import aws_instance.foo i-abcd1234
```
## Example: Import into Module
@@ -123,7 +123,7 @@ $ opentf 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
$ opentf import module.foo.aws_instance.bar i-abcd1234
$ tofu import module.foo.aws_instance.bar i-abcd1234
```
## Example: Import into Resource configured with count
@@ -132,7 +132,7 @@ The example below will import an AWS instance into the first instance of the `aw
[`count`](/docs/language/meta-arguments/count):
```shell
$ opentf import 'aws_instance.baz[0]' i-abcd1234
$ tofu import 'aws_instance.baz[0]' i-abcd1234
```
## Example: Import into Resource configured with for_each
@@ -143,17 +143,17 @@ The example below will import an AWS instance into the `"example"` instance of t
Linux, Mac OS, and UNIX:
```shell
$ opentf import 'aws_instance.baz["example"]' i-abcd1234
$ tofu import 'aws_instance.baz["example"]' i-abcd1234
```
PowerShell:
```shell
$ opentf import 'aws_instance.baz[\"example\"]' i-abcd1234
$ tofu import 'aws_instance.baz[\"example\"]' i-abcd1234
```
Windows `cmd.exe`:
```shell
$ opentf import aws_instance.baz[\"example\"] i-abcd1234
$ tofu import aws_instance.baz[\"example\"] i-abcd1234
```

52
website/docs/cli/commands/index.mdx
View File

@@ -1,17 +1,17 @@
---
description: An introduction to the opentf command and its available subcommands.
description: An introduction to the tofu command and its available subcommands.
---
# Basic CLI Features
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 OpenTofu is the `tofu` command, which
accepts a variety of subcommands such as `tofu init` or `tofu plan`.
To view a list of the commands available in your current OpenTF version,
run `opentf` with no additional arguments:
To view a list of the commands available in your current OpenTofu version,
run `tofu` with no additional arguments:
```text
Usage: opentf [global options] <subcommand> [args]
Usage: tofu [global options] <subcommand> [args]
The available commands for execution are listed below.
The primary workflow commands are given first, followed by
@@ -25,12 +25,12 @@ Main commands:
destroy Destroy previously-created infrastructure
All other commands:
console Try OpenTF expressions at an interactive command prompt
console Try OpenTofu 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 OpenTF modules
get Install or upgrade remote OpenTofu modules
graph Generate a Graphviz graph of the steps in an operation
import Associate existing infrastructure with a OpenTF resource
import Associate existing infrastructure with a OpenTofu resource
login Obtain and save credentials for a remote host
logout Remove locally-stored credentials for a remote host
metadata Metadata related commands
@@ -41,7 +41,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 OpenTF version
version Show the current OpenTofu version
workspace Workspace management
Global options (use these before the subcommand, if any):
@@ -51,43 +51,43 @@ Global options (use these before the subcommand, if any):
-version An alias for the "version" subcommand.
```
(The output from your current OpenTF version may be different than the
(The output from your current OpenTofu 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 `opentf validate -help`.
you can run `tofu validate -help`.
The inline help built in to OpenTF CLI describes the most important
The inline help built in to OpenTofu 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 OpenTF is to first switch to the directory containing
The usual way to run OpenTofu is to first switch to the directory containing
the `.tf` files for your root module (for example, using the `cd` command), so
that OpenTF will find those files automatically without any extra arguments.
that OpenTofu will find those files automatically without any extra arguments.
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
In some cases though — particularly when wrapping OpenTofu in automation
scripts — it can be convenient to run OpenTofu from a different directory than
the root module directory. To allow that, OpenTofu supports a global option
`-chdir=...` which you can include before the name of the subcommand you intend
to run:
```
opentf -chdir=environments/production apply
tofu -chdir=environments/production apply
```
The `chdir` option instructs OpenTF to change its working directory to the
The `chdir` option instructs OpenTofu to change its working directory to the
given directory before running the given subcommand. This means that any files
that OpenTF would normally read or write in the current working directory
that OpenTofu 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 OpenTF will use the original working directory
There are two exceptions where OpenTofu will use the original working directory
even when you specify `-chdir=...`:
* Settings in the [CLI Configuration](/docs/cli/config/config-file) are not for a specific
subcommand and OpenTF processes them before acting on the `-chdir`
subcommand and OpenTofu processes them before acting on the `-chdir`
option.
* In case you need to use files from the original working directory as part
@@ -97,13 +97,13 @@ even when you specify `-chdir=...`:
## Shell Tab-completion
If you use either `bash` or `zsh` as your command shell, OpenTF can provide
If you use either `bash` or `zsh` as your command shell, OpenTofu 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
opentf -install-autocomplete
tofu -install-autocomplete
```
After installation, it is necessary to restart your shell or to re-read its
@@ -113,5 +113,5 @@ To uninstall the completion hook, assuming that it has not been modified
manually in the shell profile, run the following command:
```bash
opentf -uninstall-autocomplete
tofu -uninstall-autocomplete
```

46
website/docs/cli/commands/init.mdx
View File

@@ -1,22 +1,22 @@
---
description: >-
The opentf init command initializes a working directory containing
The tofu init command initializes a working directory containing
configuration files and installs plugins for required providers.
---
# Command: init
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
The `tofu init` command initializes a working directory
containing OpenTofu configuration files. This is the first command that should
be run after writing a new OpenTofu configuration or cloning an existing one
from version control. It is safe to run this command multiple times.
## Usage
Usage: `opentf init [options]`
Usage: `tofu init [options]`
This command performs several different initialization steps in order to
prepare the current working directory for use with OpenTF. More details on
prepare the current working directory for use with OpenTofu. More details on
these are in the sections below, but in most cases it is not necessary to worry
about these individual steps.
@@ -34,7 +34,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=<duration>` Override the time OpenTF will wait to acquire
* `-lock-timeout=<duration>` Override the time OpenTofu 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.
@@ -45,7 +45,7 @@ The following options apply to all of (or several of) the initialization steps:
## Copy a Source Module
By default, `opentf init` assumes that the working directory already
By default, `tofu 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
@@ -66,7 +66,7 @@ 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 `opentf init`.
activating credentials) before running `tofu init`.
## Backend Initialization
@@ -115,40 +115,40 @@ initialized with its child modules.
## Plugin Installation
Most OpenTF providers are published separately from OpenTF as plugins.
During init, OpenTF searches the configuration for both direct and indirect
Most OpenTofu providers are published separately from OpenTofu as plugins.
During init, OpenTofu 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, `opentf init` will automatically find,
third-party provider registry, `tofu init` will automatically find,
download, and install the necessary provider plugins. If you cannot or do not
wish to install providers from their origin registries, you can customize how
OpenTF installs providers using
OpenTofu installs providers using
[the provider installation settings in the CLI configuration](/docs/cli/config/config-file#provider-installation).
For more information about specifying which providers are required for each
of your modules, see [Provider Requirements](/docs/language/providers/requirements).
After successful installation, OpenTF writes information about the selected
After successful installation, OpenTofu writes information about the selected
providers to [the dependency lock file](/docs/language/files/dependency-lock).
You should commit this file to your version control system to ensure that
when you run `opentf init` again in future OpenTF will select exactly
the same provider versions. Use the `-upgrade` option if you want OpenTF
when you run `tofu init` again in future OpenTofu will select exactly
the same provider versions. Use the `-upgrade` option if you want OpenTofu
to ignore the dependency lock file and consider installing newer versions.
You can modify `opentf init`'s plugin behavior with the following options:
You can modify `tofu 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 OpenTF to ignore any selections recorded in the dependency lock
cause OpenTofu to ignore any selections recorded in the dependency lock
file, and to take the newest available version matching the configured
version constraints.
* `-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 OpenTF's installation methods globally](/docs/cli/config/config-file#provider-installation).
[configuring OpenTofu's installation methods globally](/docs/cli/config/config-file#provider-installation).
You can use `-plugin-dir` as a one-time override for exceptional situations,
such as if you are testing a local build of a provider plugin you are
currently developing.
@@ -161,10 +161,10 @@ 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 `opentf init` in automation
## Running `tofu init` in automation
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
For teams that use OpenTofu as a key part of a change management and
deployment pipeline, it can be desirable to orchestrate OpenTofu 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.
@@ -177,6 +177,6 @@ re-installation.
If your workflow relies on overriding
the root module directory, use
[the `-chdir` global option](/docs/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes OpenTF consistently look
instead, which works across all commands and makes OpenTofu consistently look
in the given directory for all files it would normally read or write in the
current working directory.

20
website/docs/cli/commands/login.mdx
View File

@@ -1,31 +1,31 @@
---
description: >-
The opentf login command can be used to automatically obtain and save an
API token for any host that offers OpenTF-compatible services.
The tofu login command can be used to automatically obtain and save an
API token for any host that offers OpenTofu-compatible services.
---
# Command: login
The `opentf login` command can be used to automatically obtain and save an
API token for any host that offers OpenTF-compatible services.
The `tofu login` command can be used to automatically obtain and save an
API token for any host that offers OpenTofu-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 OpenTF
is running. If you are running OpenTF in an unattended automation scenario,
where it is possible to launch a web browser on the same host where OpenTofu
is running. If you are running OpenTofu in an unattended automation scenario,
you can
[configure credentials manually in the CLI configuration](/docs/cli/config/config-file#credentials).
:::
## Usage
Usage: `opentf login [hostname]`
Usage: `tofu login [hostname]`
## Credentials Storage
By default, OpenTF will obtain an API token and save it in plain text in a
By default, OpenTofu will obtain an API token and save it in plain text in a
local CLI configuration file called `credentials.tfrc.json`. When you run
`opentf login`, it will explain specifically where it intends to save
`tofu 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.
@@ -37,5 +37,5 @@ your organization's existing secrets management system.
## Login Server Support
The `opentf login` command works with any server supporting the
The `tofu login` command works with any server supporting the
[login protocol](/docs/internals/login-protocol).

12
website/docs/cli/commands/logout.mdx
View File

@@ -1,17 +1,17 @@
---
description: >-
The opentf logout command is used to remove credentials stored by opentf
The tofu logout command is used to remove credentials stored by tofu
login.
---
# Command: logout
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.
The `tofu logout` command is used to remove credentials stored by
`tofu login`. These credentials are API tokens for any host that offers OpenTofu-compatible services.
## Usage
Usage: `opentf logout [hostname]`
Usage: `tofu logout [hostname]`
:::note
The API token is only removed from local storage, not destroyed on
@@ -20,7 +20,7 @@ the remote server, so it will remain valid until manually revoked.
## Credentials Storage
By default, OpenTF will remove the token stored in plain text in a local CLI
By default, OpenTofu will remove the token stored in plain text in a local CLI
configuration file called `credentials.tfrc.json`. If you have configured a
[credentials helper program](/docs/cli/config/config-file#credentials-helpers), OpenTF
[credentials helper program](/docs/cli/config/config-file#credentials-helpers), OpenTofu
will use the helper's `forget` command to remove it.

34
website/docs/cli/commands/output.mdx
View File

@@ -1,17 +1,17 @@
---
description: >-
The `opentf output` command is used to extract the value of an output
The `tofu output` command is used to extract the value of an output
variable from the state file.
---
# Command: output
The `opentf output` command is used to extract the value of
The `tofu output` command is used to extract the value of
an output variable from the state file.
## Usage
Usage: `opentf output [options] [NAME]`
Usage: `tofu 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
@@ -22,24 +22,24 @@ 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, OpenTF will convert the specified output value to a
* `-raw` - If specified, OpenTofu 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 "opentf.tfstate".
* `-state=path` - Path to the state file. Defaults to "tofu.tfstate".
Ignored when [remote state](/docs/language/state/remote) is used.
:::note
When using the `-json` or `-raw` command-line flag, any sensitive
values in OpenTF state will be displayed in plain text. For more information,
values in OpenTofu state will be displayed in plain text. For more information,
see [Sensitive Data in State](/docs/language/state/sensitive-data).
:::
## Examples
These examples assume the following OpenTF output snippet.
These examples assume the following OpenTofu output snippet.
```hcl
output "instance_ips" {
@@ -59,7 +59,7 @@ output "password" {
To list all outputs:
```shellsession
$ opentf output
$ tofu output
instance_ips = [
"54.43.114.12",
"52.122.13.4",
@@ -72,21 +72,21 @@ password = <sensitive>
Note that outputs with the `sensitive` attribute will be redacted:
```shellsession
$ opentf output password
$ tofu output password
password = <sensitive>
```
To query for the DNS address of the load balancer:
```shellsession
$ opentf output lb_address
$ tofu output lb_address
"my-app-alb-1657023003.us-east-1.elb.amazonaws.com"
```
To query for all instance IP addresses:
```shellsession
$ opentf output instance_ips
$ tofu output instance_ips
instance_ips = [
"54.43.114.12",
"52.122.13.4",
@@ -96,7 +96,7 @@ instance_ips = [
## Use in automation
The `opentf output` command by default displays in a human-readable format,
The `tofu 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.
@@ -104,7 +104,7 @@ You can parse the output using a JSON command-line parser such as
[jq](https://stedolan.github.io/jq/):
```shellsession
$ opentf output -json instance_ips | jq -r '.[0]'
$ tofu output -json instance_ips | jq -r '.[0]'
54.43.114.12
```
@@ -113,15 +113,15 @@ can use `-raw` instead, which will print the string directly with no extra
escaping or whitespace.
```shellsession
$ opentf output -raw lb_address
$ tofu output -raw lb_address
my-app-alb-1657023003.us-east-1.elb.amazonaws.com
```
The `-raw` option works only with values that OpenTF can automatically
The `-raw` option works only with values that OpenTofu can automatically
convert to strings. Use `-json` instead, possibly combined with `jq`, to
work with complex-typed values such as objects.
OpenTF strings are sequences of Unicode characters rather than raw bytes,
OpenTofu 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 OpenTF's raw output.
such as `iconv` to transcode OpenTofu's raw output.

138
website/docs/cli/commands/plan.mdx
View File

@@ -1,17 +1,17 @@
---
description: >-
The opentf plan command creates an execution plan with a preview of the
changes that OpenTF will make to your infrastructure.
The tofu plan command creates an execution plan with a preview of the
changes that OpenTofu will make to your infrastructure.
---
# Command: plan
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:
The `tofu plan` command creates an execution plan, which lets you preview
the changes that OpenTofu plans to make to your infrastructure. By default,
when OpenTofu creates a plan it:
* Reads the current state of any already-existing remote objects to make sure
that the OpenTF state is up-to-date.
that the OpenTofu 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
@@ -21,21 +21,21 @@ The `plan` command alone does not actually carry out the proposed changes You ca
you expected before you apply the changes or share your changes with your
team for broader review.
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
If OpenTofu detects that no changes are needed to resource instances or to
root module output values, `tofu plan` will report that no actions need
to be taken.
If you are using OpenTF directly in an interactive terminal and you expect
to apply the changes OpenTF proposes, you can alternatively run
[`opentf apply`](/docs/cli/commands/apply) directly. By default, the "apply" command
If you are using OpenTofu directly in an interactive terminal and you expect
to apply the changes OpenTofu proposes, you can alternatively run
[`tofu apply`](/docs/cli/commands/apply) directly. By default, the "apply" command
automatically generates a new plan and prompts for you to approve it.
You can use the optional `-out=FILE` option to save the generated plan to a
file on disk, which you can later execute by passing the file to
[`opentf apply`](/docs/cli/commands/apply) as an extra argument. This two-step workflow
is primarily intended for when running OpenTF in automation.
[`tofu apply`](/docs/cli/commands/apply) as an extra argument. This two-step workflow
is primarily intended for when running OpenTofu in automation.
If you run `opentf plan` without the `-out=FILE` option then it will create
If you run `tofu 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.
@@ -50,15 +50,15 @@ matches your intent.
## Usage
Usage: `opentf plan [options]`
Usage: `tofu 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 OpenTF, it has
Because the plan command is one of the main commands of OpenTofu, 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 OpenTF configuration should typically be designed to work with no special
a OpenTofu 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:
@@ -77,28 +77,28 @@ The remaining sections on this page describe the various options:
## Planning Modes
The previous section describes OpenTF's default planning behavior, which
The previous section describes OpenTofu's default planning behavior, which
changes the remote system to match the changes you make to
your configuration. OpenTF has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `opentf plan` and [`opentf apply`](/docs/cli/commands/apply).
your configuration. OpenTofu has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both `tofu plan` and [`tofu apply`](/docs/cli/commands/apply).
* **Destroy mode:** creates a plan whose goal is to destroy all remote objects
that currently exist, leaving an empty OpenTF state. It is the same as running [`opentf destroy`](/docs/cli/commands/destroy). Destroy mode can be useful for situations like transient development environments, where the managed objects cease to be useful once the development task is complete.
that currently exist, leaving an empty OpenTofu state. It is the same as running [`tofu destroy`](/docs/cli/commands/destroy). Destroy mode can be useful for situations like transient development environments, where the managed objects cease to be useful once the development task is complete.
Activate destroy mode using the `-destroy` command line option.
* **Refresh-only mode:** creates a plan whose goal is only to update the
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
OpenTofu state and any root module output values to match changes made to
remote objects outside of OpenTofu. 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
OpenTF's records with those changes.
OpenTofu'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 OpenTF
In situations where we need to discuss the default planning mode that OpenTofu
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 OpenTF documentation only discusses the normal planning
only, some other OpenTofu documentation only discusses the normal planning
mode.
The planning modes are all mutually-exclusive, so activating any non-default
@@ -107,20 +107,20 @@ one alternative mode at the same time.
## Planning Options
In addition to alternate [planning modes](#planning-modes), there are several options that can modify planning behavior. These options are available for both `opentf plan` and [`opentf apply`](/docs/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 `tofu plan` and [`tofu apply`](/docs/cli/commands/apply).
- `-refresh=false` - Disables the default behavior of synchronizing the
OpenTF state with remote objects before checking for configuration changes. This can make the planning operation faster by reducing the number of remote API requests. However, setting `refresh=false` causes OpenTF to ignore external changes, which could result in an incomplete or incorrect plan. You cannot use `refresh=false` in refresh-only planning mode because it would effectively disable the entirety of the planning operation.
OpenTofu 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 OpenTofu 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 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.
- `-replace=ADDRESS` - Instructs OpenTofu 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. OpenTofu 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 OpenTF to focus its planning efforts only
- `-target=ADDRESS` - Instructs OpenTofu 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 OpenTF limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around OpenTofu limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
:::
- `-var 'NAME=VALUE'` - Sets a value for a single
@@ -146,14 +146,14 @@ You can use the `-var` command line option to specify values for
root module.
However, to do so will require writing a command line that is parsable both
by your chosen command line shell _and_ OpenTF, which can be complicated
by your chosen command line shell _and_ OpenTofu, 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 OpenTF can parse them directly, rather than
in a separate file so that OpenTofu can parse them directly, rather than
interpreting the result of your shell's parsing.
:::warning
OpenTF will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`).
OpenTofu 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
@@ -161,7 +161,7 @@ recommend writing the option argument in single quotes `'` to ensure the
shell will interpret the value literally:
```
opentf plan -var 'name=value'
tofu plan -var 'name=value'
```
If your intended value also includes a single quote then you'll still need to
@@ -170,26 +170,26 @@ temporarily ending the quoted sequence so that the backslash escape character
will be significant:
```
opentf plan -var 'name=va'\''lue'
tofu plan -var 'name=va'\''lue'
```
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
When using OpenTofu on Windows, we recommend using the Windows Command Prompt
(`cmd.exe`). When you pass a variable value to OpenTofu from the Windows
Command Prompt, use double quotes `"` around the argument:
```
opentf plan -var "name=value"
tofu plan -var "name=value"
```
If your intended value includes literal double quotes then you'll need to
escape those with a backslash:
```
opentf plan -var "name=va\"lue"
tofu plan -var "name=va\"lue"
```
PowerShell on Windows cannot correctly pass literal quotes to external programs,
so we do not recommend using OpenTF with PowerShell when you are on Windows.
so we do not recommend using OpenTofu with PowerShell when you are on Windows.
Use Windows Command Prompt instead.
The appropriate syntax for writing the variable value is different depending
@@ -198,16 +198,16 @@ 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
OpenTF language expression representing the value, and write any necessary
OpenTofu language expression representing the value, and write any necessary
quoting or escape characters to ensure it will pass through your shell
literally to OpenTF. For example, for a `list(string)` type constraint:
literally to OpenTofu. For example, for a `list(string)` type constraint:
```
# Unix-style shell
opentf plan -var 'name=["a", "b", "c"]'
tofu plan -var 'name=["a", "b", "c"]'
# Windows Command Prompt (do not use PowerShell on Windows)
opentf plan -var "name=[\"a\", \"b\", \"c\"]"
tofu plan -var "name=[\"a\", \"b\", \"c\"]"
```
Similar constraints apply when setting input variables using environment
@@ -217,33 +217,33 @@ input variables, see
### Resource Targeting
You can use the `-target` option to focus OpenTF's attention on only a
You can use the `-target` option to focus OpenTofu's attention on only a
subset of resources.
You can use [resource address syntax](/docs/cli/state/resource-addressing)
to specify the constraint. OpenTF interprets the resource address as follows:
to specify the constraint. OpenTofu interprets the resource address as follows:
* If the given address identifies one specific resource instance, OpenTF
* If the given address identifies one specific resource instance, OpenTofu
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, OpenTF will select
* If the given address identifies a resource as a whole, OpenTofu 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, OpenTF will
* If the given address identifies an entire module instance, OpenTofu will
select all instances of all resources that belong to that module instance
and all of its child module instances.
Once OpenTF has selected one or more resource instances that you've directly
Once OpenTofu 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 OpenTF limitations. It
as recovering from mistakes or working around OpenTofu 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.
@@ -258,10 +258,10 @@ that can be updated independently.
## Other Options
The `opentf plan` command also has some other options that are related to
The `tofu 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 OpenTF will create. These commands are not necessarily also
available on `opentf apply`, unless otherwise stated in the documentation
sort of plan OpenTofu will create. These commands are not necessarily also
available on `tofu apply`, unless otherwise stated in the documentation
for that command.
The available options are:
@@ -278,11 +278,11 @@ 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 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.
- `-generate-config-out=PATH` - (Experimental) If `import` blocks are present in configuration, instructs OpenTofu 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 OpenTofu will error. If the plan fails for another reason, OpenTofu may still attempt to write configuration.
* `-input=false` - Disables OpenTF's default behavior of prompting for
* `-input=false` - Disables OpenTofu'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 OpenTF in
a value. This option is particularly useful when running OpenTofu in
non-interactive automation systems.
* `-json` - Enables the [machine readable JSON UI][machine-readable-ui] output.
@@ -296,46 +296,46 @@ The available options are:
workspace.
* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs OpenTF to retry acquiring a lock for a period of time before
instructs OpenTofu 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 OpenTF in a context where its output will be
if you are running OpenTofu 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 `opentf apply` to execute
the planned changes, and to some other OpenTF commands that can work with
opaque file format that you can later pass to `tofu apply` to execute
the planned changes, and to some other OpenTofu commands that can work with
saved plan files.
OpenTF will allow any filename for the plan file, but a typical
OpenTofu 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 OpenTF recognizes as another file format; if you use a `.tf` suffix
then OpenTF will try to interpret the file as a configuration source
that OpenTofu recognizes as another file format; if you use a `.tf` suffix
then OpenTofu 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 OpenTF's terminal output, it will
sensitive data, even if obscured in OpenTofu'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 OpenTF
* `-parallelism=n` - Limit the number of concurrent operations as OpenTofu
[walks the graph](/docs/internals/graph#walking-the-graph). Defaults
to 10.
For configurations using
[the `local` backend](/docs/language/settings/backends/local) only,
`opentf plan` accepts the legacy command line option
`tofu plan` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local#command-line-arguments).
### Passing a Different Configuration Directory
If your workflow relies on overriding the root module directory, use
[the `-chdir` global option](/docs/cli/commands#switching-working-directory-with-chdir)
instead, which works across all commands and makes OpenTF consistently look
instead, which works across all commands and makes OpenTofu consistently look
in the given directory for all files it would normally read or write in the
current working directory.

6
website/docs/cli/commands/providers.mdx
View File

@@ -1,12 +1,12 @@
---
description: >-
The opentf providers command prints information about the providers
The tofu providers command prints information about the providers
required in the current configuration.
---
# Command: providers
The `opentf providers` command shows information about the
The `tofu providers` command shows information about the
[provider requirements](/docs/language/providers/requirements) of the
configuration in the current working directory, as an aid to understanding
where each requirement was detected from.
@@ -15,4 +15,4 @@ This command also has several subcommands with different purposes.
## Usage
Usage: `opentf providers`
Usage: `tofu providers`

56
website/docs/cli/commands/providers/lock.mdx
View File

@@ -1,46 +1,46 @@
---
description: |-
The `opentf providers lock` command adds new provider selection information
The `tofu providers lock` command adds new provider selection information
to the dependency lock file without initializing the referenced providers.
---
# Command: providers lock
The `opentf providers lock` consults upstream registries (by default) in
The `tofu providers lock` consults upstream registries (by default) in
order to write provider dependency information into
[the dependency lock file](/docs/language/files/dependency-lock).
The common way to update the dependency lock file is as a side-effect of normal
provider installation during
[`opentf init`](/docs/cli/commands/init), but there are several situations where that
[`tofu init`](/docs/cli/commands/init), but there are several situations where that
automatic approach may not be sufficient:
* If you are running OpenTF in an environment that uses
* If you are running OpenTofu in an environment that uses
[alternative provider installation methods](/docs/cli/config/config-file#provider-installation),
such as filesystem or network mirrors, normal provider installation will not
access the origin registry for a provider and therefore OpenTF will not
access the origin registry for a provider and therefore OpenTofu will not
be able to populate all of the possible package checksums for the selected
provider versions.
If you use `opentf lock` to write the official release checksums for a
provider into the dependency lock file then future `opentf init` runs
If you use `tofu lock` to write the official release checksums for a
provider into the dependency lock file then future `tofu 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 OpenTF across a number of different platforms (e.g.
* If your team runs OpenTofu 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 OpenTF on other platforms may
of OpenTofu on other platforms may
[add additional checksums to the lock file](/docs/language/files/dependency-lock#new-provider-package-checksums).
You can avoid that by pre-populating hashes for all of the platforms you
intend to use, using the `opentf providers lock` command.
intend to use, using the `tofu providers lock` command.
## Usage
Usage: `opentf providers lock [options] [providers...]`
Usage: `tofu providers lock [options] [providers...]`
With no additional command line arguments, `opentf providers lock` will
With no additional command line arguments, `tofu 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
@@ -49,7 +49,7 @@ 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 `opentf providers lock` command prints information
The `tofu 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
@@ -59,22 +59,22 @@ the updated lock file to your version control system.
:::
If you list one or more provider source addresses on the command line then
`opentf providers lock` will restrict its work only to those providers,
`tofu 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 OpenTF to look for provider packages in the
* `-fs-mirror=PATH` - Direct OpenTofu 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 OpenTF to look for provider packages in the
* `-net-mirror=URL` - Direct OpenTofu to look for provider packages in the
given network mirror service, instead of in upstream registries. The
given URL must implement
[the OpenTF provider network mirror protocol](/docs/internals/provider-network-mirror-protocol).
[the OpenTofu provider network mirror protocol](/docs/internals/provider-network-mirror-protocol).
* `-platform=OS_ARCH` - Specify a platform you intend to use to work with this
OpenTF configuration. OpenTF will ensure that the providers are all
OpenTofu configuration. OpenTofu 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.
@@ -90,16 +90,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 OpenTF configuration on their Windows or macOS workstations _and_
your OpenTofu 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 `opentf providers lock` and specifying those three
checksums, by running `tofu providers lock` and specifying those three
platforms:
```
opentf providers lock \
tofu providers lock \
-platform=windows_amd64 \ # 64-bit Windows
-platform=darwin_amd64 \ # 64-bit macOS
-platform=linux_amd64 # 64-bit Linux
@@ -111,12 +111,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 OpenTF provider
An _in-house provider_ is one that isn't published on a real OpenTofu 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, `opentf providers lock` assumes all providers are available
at a OpenTF provider registry and tries to contact the origin registries
By default, `tofu providers lock` assumes all providers are available
at a OpenTofu provider registry and tries to contact the origin registries
in order to get access to the most detailed information about the provider
packages.
@@ -126,8 +126,8 @@ line options to override the default behavior of consulting the provider's
origin registry:
```
opentf providers lock \
-fs-mirror=/usr/local/opentf/providers
tofu providers lock \
-fs-mirror=/usr/local/tofu/providers
-platform=windows_amd64 \
-platform=darwin_amd64 \
-platform=linux_amd64 \
@@ -139,10 +139,10 @@ 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`, `opentf providers lock` will only
`tf.example.com/ourcompany/ourplatform`, `tofu 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 `opentf providers lock`
available from different sources, you can run `tofu 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

26
website/docs/cli/commands/providers/mirror.mdx
View File

@@ -1,50 +1,50 @@
---
description: |-
The `opentf providers mirror` command downloads the providers required
The `tofu providers mirror` command downloads the providers required
for the current configuration and copies them into a directory in the local
filesystem.
---
# Command: providers mirror
The `opentf providers mirror` command downloads the providers required
The `tofu providers mirror` command downloads the providers required
for the current configuration and copies them into a directory in the local
filesystem.
In normal use, `opentf init` will automatically download needed providers
In normal use, `tofu init` will automatically download needed providers
from provider registries as part of initializing the current working directory.
Sometimes OpenTF is running in an environment where that isn't possible,
such as on an isolated network without access to an OpenTF Registry. In
Sometimes OpenTofu is running in an environment where that isn't possible,
such as on an isolated network without access to an OpenTofu Registry. In
that case,
[explicit installation method configuration](/docs/cli/config/config-file#explicit-installation-method-configuration)
allows you to configure OpenTF, when running on a particular system, to
allows you to configure OpenTofu, 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 `opentf providers mirror` command can automatically populate a directory
The `tofu providers mirror` command can automatically populate a directory
that will be used as a local filesystem mirror in the provider installation
configuration.
## Usage
Usage: `opentf providers mirror [options] <target-dir>`
Usage: `tofu providers mirror [options] <target-dir>`
A single target directory is required. OpenTF will create under that
A single target directory is required. OpenTofu 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.
OpenTF will also generate various `.json` index files which contain suitable
OpenTofu will also generate various `.json` index files which contain suitable
responses to implement
[the network mirror protocol](/docs/internals/provider-network-mirror-protocol),
if you upload the resulting directory to a static website host. OpenTF
if you upload the resulting directory to a static website host. OpenTofu
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 OpenTF will obtain plugin packages suitable for the platform
By default OpenTofu 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.
@@ -52,7 +52,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 `opentf providers mirror` again on an existing mirror directory
You can run `tofu 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

10
website/docs/cli/commands/providers/schema.mdx
View File

@@ -1,6 +1,6 @@
---
description: >-
The `opentf providers schema` command prints detailed schemas for the
The `tofu providers schema` command prints detailed schemas for the
providers used
in the current configuration.
@@ -8,11 +8,11 @@ description: >-
# Command: providers schema
The `opentf providers schema` command is used to print detailed schemas for the providers used in the current configuration.
The `tofu providers schema` command is used to print detailed schemas for the providers used in the current configuration.
## Usage
Usage: `opentf providers schema [options]`
Usage: `tofu providers schema [options]`
The following flags are available:
@@ -31,7 +31,7 @@ value `"1.0"`. The semantics of this version are:
version.
We will introduce new major versions only within the bounds of
[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
[the OpenTofu 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
## Format Summary
@@ -41,7 +41,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 `opentf providers schema -json`
- [Providers Schema Representation](#providers-schema-representation) - the top-level object returned by `tofu 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

28
website/docs/cli/commands/refresh.mdx
View File

@@ -1,13 +1,13 @@
---
description: |-
The `opentf refresh` command reads the current settings from all managed
remote objects and updates the OpenTF state to match.
The `tofu refresh` command reads the current settings from all managed
remote objects and updates the OpenTofu state to match.
---
# Command: refresh
The `opentf refresh` command reads the current settings from all managed
remote objects and updates the OpenTF state to match.
The `tofu refresh` command reads the current settings from all managed
remote objects and updates the OpenTofu state to match.
:::warning
This command is deprecated, because its default behavior is
@@ -16,44 +16,44 @@ See below for more information and recommended alternatives.
:::
This won't modify your real remote objects, but it will modify the
[OpenTF state](/docs/language/state).
[OpenTofu state](/docs/language/state).
You shouldn't typically need to use this command, because OpenTF
You shouldn't typically need to use this command, because OpenTofu
automatically performs the same refreshing actions as a part of creating
a plan in both the
[`opentf plan`](/docs/cli/commands/plan)
[`tofu plan`](/docs/cli/commands/plan)
and
[`opentf apply`](/docs/cli/commands/apply)
[`tofu apply`](/docs/cli/commands/apply)
commands. This command is here primarily for backward compatibility, but
we don't recommend using it because it provides no opportunity to review
the effects of the operation before updating the state.
## Usage
Usage: `opentf refresh [options]`
Usage: `tofu refresh [options]`
This command is effectively an alias for the following command:
```
opentf apply -refresh-only -auto-approve
tofu apply -refresh-only -auto-approve
```
Consequently, it supports all of the same options as
[`opentf apply`](/docs/cli/commands/apply) except that it does not accept a saved
[`tofu apply`](/docs/cli/commands/apply) except that it does not accept a saved
plan file, it doesn't allow selecting a planning mode other than "refresh only",
and `-auto-approve` is always enabled.
Automatically applying the effect of a refresh is risky. If you have
misconfigured credentials for one or more providers, OpenTF may
misconfigured credentials for one or more providers, OpenTofu 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 OpenTF has
effect but with the opportunity to review the changes that OpenTofu has
detected before committing them to the state:
```
opentf apply -refresh-only
tofu apply -refresh-only
```
This alternative command will present an interactive prompt for you to confirm

24
website/docs/cli/commands/show.mdx
View File

@@ -1,49 +1,49 @@
---
description: >-
The `opentf show` command is used to provide human-readable output from a
The `tofu 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 OpenTF
planned operations are expected, or to inspect the current state as OpenTofu
sees it.
---
# Command: show
The `opentf show` command is used to provide human-readable output
The `tofu 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 OpenTF sees it.
as OpenTofu 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
OpenTF state will be displayed in plain text. For more information, see
OpenTofu state will be displayed in plain text. For more information, see
[Sensitive Data in State](/docs/language/state/sensitive-data).
:::
## JSON Output
For OpenTF state files (including when no path is provided),
`opentf show -json` will show a JSON representation of the state.
For OpenTofu state files (including when no path is provided),
`tofu show -json` will show a JSON representation of the state.
For OpenTF plan files, `opentf show -json` will show a JSON representation
For OpenTofu plan files, `tofu 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 `opentf refresh`
`-refresh=false`. If you are viewing a state file, run `tofu refresh`
first.
The output format is covered in detail in [JSON Output Format](/docs/internals/json-format).
## Usage
Usage: `opentf show [options] [file]`
Usage: `tofu show [options] [file]`
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
You may use `show` with a path to either a OpenTofu state file or plan
file. If you don't specify a file path, OpenTofu will show the latest state
snapshot.
This command accepts the following options:

20
website/docs/cli/commands/state/index.mdx
View File

@@ -1,13 +1,13 @@
---
description: The `opentf state` command is used for advanced state management.
description: The `tofu state` command is used for advanced state management.
---
# Command: state
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](/docs/language/state).
Rather than modify the state directly, the `opentf state` commands can
The `tofu state` command is used for advanced state management.
As your OpenTofu usage becomes more advanced, there are some cases where
you may need to modify the [OpenTofu state](/docs/language/state).
Rather than modify the state directly, the `tofu state` commands can
be used in many cases instead.
This command is a nested subcommand, meaning that it has further subcommands.
@@ -15,27 +15,27 @@ These subcommands are listed to the left.
## Usage
Usage: `opentf state <subcommand> [options] [args]`
Usage: `tofu state <subcommand> [options] [args]`
Please click a subcommand to the left for more information.
## Remote State
The OpenTF state subcommands all work with remote state just as if it
The OpenTofu 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 `opentf state` subcommands that modify the state write backup
All `tofu state` subcommands that modify the state write backup
files. The path of these backup file can be controlled with `-backup`.
Subcommands that are read-only (such as [list](/docs/cli/commands/state/list))
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, OpenTF forces every state modification
the sensitivity of the state file, OpenTofu 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.
@@ -45,5 +45,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 OpenTF
For advanced filtering and modification, we recommend piping OpenTofu
state subcommands together with other command line tools.

18
website/docs/cli/commands/state/list.mdx
View File

@@ -1,17 +1,17 @@
---
description: >-
The opentf state list command is used to list resources within a OpenTF
The tofu state list command is used to list resources within a OpenTofu
state.
---
# Command: state list
The `opentf state list` command is used to list resources within a
[OpenTF state](/docs/language/state).
The `tofu state list` command is used to list resources within a
[OpenTofu state](/docs/language/state).
## Usage
Usage: `opentf state list [options] [address...]`
Usage: `tofu 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.
@@ -27,7 +27,7 @@ in [resource addressing format](/docs/cli/state/resource-addressing).
The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "opentf.tfstate".
* `-state=path` - Path to the state file. Defaults to "tofu.tfstate".
Ignored when [remote state](/docs/language/state/remote) is used.
* `-id=id` - ID of resources to show. Ignored when unset.
@@ -36,7 +36,7 @@ The command-line flags are all optional. The following flags are available:
This example will list all resources, including modules:
```
$ opentf state list
$ tofu state list
aws_instance.foo
aws_instance.bar[0]
aws_instance.bar[1]
@@ -48,7 +48,7 @@ module.elb.aws_elb.main
This example will only list resources for the given name:
```
$ opentf state list aws_instance.bar
$ tofu state list aws_instance.bar
aws_instance.bar[0]
aws_instance.bar[1]
```
@@ -58,7 +58,7 @@ aws_instance.bar[1]
This example will list resources in the given module and any submodules:
```
$ opentf state list module.elb
$ tofu state list module.elb
module.elb.aws_elb.main
module.elb.module.secgroups.aws_security_group.sg
```
@@ -70,6 +70,6 @@ command line. This is useful to find where in your configuration a
specific resource is located.
```
$ opentf state list -id=sg-1234abcd
$ tofu state list -id=sg-1234abcd
module.elb.aws_security_group.sg
```

58
website/docs/cli/commands/state/mv.mdx
View File

@@ -1,27 +1,27 @@
---
description: >-
The `opentf state mv` command changes bindings in OpenTF state,
The `tofu state mv` command changes bindings in OpenTofu state,
associating existing remote objects with new resource instances.
---
# Command: state mv
The main function of [OpenTF state](/docs/language/state) is
The main function of [OpenTofu state](/docs/language/state) is
to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally OpenTF automatically
and the remote objects they represent. Normally OpenTofu 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 `opentf state mv` in the less common situation where you wish
You can use `tofu 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 OpenTF, such as if you have renamed a resource block
instance address in OpenTofu, such as if you have renamed a resource block
or you have moved it into a different module in your configuration.
## Usage
Usage: `opentf state mv [options] SOURCE DESTINATION`
Usage: `tofu state mv [options] SOURCE DESTINATION`
OpenTF will look in the current state for a resource instance, resource,
OpenTofu 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.
@@ -34,21 +34,21 @@ 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 `opentf state mv` are when you have renamed a
The most common uses for `tofu 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 OpenTF will understand
object but tracking it under a new name. By default OpenTofu 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 `opentf state mv`
object and create a new object at the new address, and so `tofu state mv`
allows you to override that interpretation by pre-emptively attaching the
existing object to the new address in OpenTF.
existing object to the new address in OpenTofu.
:::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
If you are using OpenTofu in a collaborative environment, you
must ensure that when you are using `tofu 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
`opentf state mv` command, because otherwise they might inadvertently create
`tofu 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.
:::
@@ -63,12 +63,12 @@ This command also accepts the following options:
workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs OpenTF to retry acquiring a lock for a period of time before
instructs OpenTofu 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 [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote)
only, `opentf state mv`
only, `tofu state mv`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
@@ -81,7 +81,7 @@ options.
For configurations using
[the `local` state mv](/docs/language/settings/backends/local) only,
`opentf state mv` also accepts the legacy options
`tofu state mv` also accepts the legacy options
[`-state`, `-state-out`, `-backup`, and `-backup-out`](/docs/language/settings/backends/local#command-line-arguments).
## Example: Rename a Resource
@@ -95,12 +95,12 @@ Renaming a resource means making a configuration change like the following:
}
```
To tell OpenTF that it should treat the new "helper" resource as a rename
To tell OpenTofu 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
opentf state mv packet_device.worker packet_device.helper
tofu state mv packet_device.worker packet_device.helper
```
## Example: Move a Resource Into a Module
@@ -108,10 +108,10 @@ opentf 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 OpenTF to treat it as a move:
run the following command to tell OpenTofu to treat it as a move:
```shell
opentf state mv packet_device.worker module.worker.packet_device.worker
tofu 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
@@ -119,7 +119,7 @@ address. You could also change the resource name at the same time, if the new
module organization suggests a different naming scheme:
```shell
opentf state mv packet_device.worker module.worker.packet_device.main
tofu state mv packet_device.worker module.worker.packet_device.main
```
## Example: Move a Module Into a Module
@@ -129,7 +129,7 @@ configuration, move the `module` block representing the module into a different
module and then pair that change with a command like the following:
```shell
opentf state mv module.app module.parent.module.app
tofu state mv module.app module.parent.module.app
```
## Example: Move a Particular Instance of a Resource using `count`
@@ -140,7 +140,7 @@ select a particular instance by including an explicit index in your given
address:
```shell
$ opentf state mv 'packet_device.worker[0]' 'packet_device.helper[0]'
$ tofu 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
@@ -150,11 +150,11 @@ or the opposite, as long as the address type you use matches whether and how
each resource is configured:
```shell
$ opentf state mv 'packet_device.main' 'packet_device.all[0]'
$ tofu 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 OpenTF.
quote or escape the address in order to pass it literally to OpenTofu.
The above examples show the typical quoting syntax for Unix-style shells.
## Example: Move a Resource configured with for_each
@@ -171,19 +171,19 @@ quoting and/or escaping syntax for the shell you are using. For example:
Unix-style shells, such as on Linux or macOS:
```shell
opentf state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'
tofu state mv 'packet_device.worker["example123"]' 'packet_device.helper["example456"]'
```
Windows Command Prompt (`cmd.exe`):
```shell
opentf state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]
tofu state mv packet_device.worker[\"example123\"] packet_device.helper[\"example456\"]
```
PowerShell:
```shell
opentf state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'
tofu state mv 'packet_device.worker[\"example123\"]' 'packet_device.helper[\"example456\"]'
```
Aside from the use of strings instead of integers for instance keys, the

14
website/docs/cli/commands/state/pull.mdx
View File

@@ -1,31 +1,31 @@
---
description: >-
The `opentf state pull` command is used to manually download and output the
The `tofu state pull` command is used to manually download and output the
state from remote state.
---
# Command: state pull
The `opentf state pull` command is used to manually download and output
The `tofu state pull` command is used to manually download and output
the state from [remote state](/docs/language/state/remote). This command also
works with local state.
## Usage
Usage: `opentf state pull`
Usage: `tofu 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 OpenTF, and outputs the raw format to stdout.
locally-installed OpenTofu, 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 OpenTF version of
the remote state, as it will always be converted to the current OpenTF
You cannot use this command to inspect the OpenTofu version of
the remote state, as it will always be converted to the current OpenTofu
version before output.
:::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`.
OpenTofu 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 `tofu state pull | sc tofu.tfstate`.
:::

16
website/docs/cli/commands/state/push.mdx
View File

@@ -1,10 +1,10 @@
---
description: The `opentf state push` command pushes items to the OpenTF state.
description: The `tofu state push` command pushes items to the OpenTofu state.
---
# Command: state push
The `opentf state push` command is used to manually upload a local
The `tofu state push` command is used to manually upload a local
state file to [remote state](/docs/language/state/remote). This command also
works with local state.
@@ -13,7 +13,7 @@ manual intervention is necessary with the remote state.
## Usage
Usage: `opentf state push [options] PATH`
Usage: `tofu state push [options] PATH`
This command pushes the state specified by PATH to the currently
configured [backend](/docs/language/settings/backends/configuration).
@@ -23,19 +23,19 @@ is loaded completely into memory and verified prior to being written to
the destination state.
:::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`.
OpenTofu 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 `tofu state push | sc tofu.tfstate`.
:::
OpenTF will perform a number of safety checks to prevent you from
OpenTofu 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,
OpenTF will not allow you to push the state. A differing lineage
OpenTofu 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, OpenTF will prevent the push.
is higher than the state being pushed, OpenTofu 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.
@@ -44,6 +44,6 @@ Both of these safety checks can be disabled with the `-force` flag.
pushing state, the destination state will be overwritten.
For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote)
only, `opentf state push`
only, `tofu state push`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).

16
website/docs/cli/commands/state/replace-provider.mdx
View File

@@ -1,17 +1,17 @@
---
description: >-
The `opentf state replace-provider` command replaces the provider for
resources in the OpenTF state.
The `tofu state replace-provider` command replaces the provider for
resources in the OpenTofu state.
---
# Command: state replace-provider
The `opentf state replace-provider` command is used to replace the provider
for resources in a [OpenTF state](/docs/language/state).
The `tofu state replace-provider` command is used to replace the provider
for resources in a [OpenTofu state](/docs/language/state).
## Usage
Usage: `opentf state replace-provider [options] FROM_PROVIDER_FQN TO_PROVIDER_FQN`
Usage: `tofu 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,13 +32,13 @@ This command also accepts the following options:
- `-lock-timeout=0s` - Duration to retry a state lock.
For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote)
only, `opentf state replace-provider`
only, `tofu state replace-provider`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using
[the `local` state](/docs/language/settings/backends/local) only,
`opentf state replace-provider` also accepts the legacy options
`tofu state replace-provider` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments).
## Example
@@ -46,5 +46,5 @@ For configurations using
The example below replaces the `hashicorp/aws` provider with a fork by `acme`, hosted at a private registry at `registry.acme.corp`:
```shell
$ opentf state replace-provider hashicorp/aws registry.acme.corp/acme/aws
$ tofu state replace-provider hashicorp/aws registry.acme.corp/acme/aws
```

46
website/docs/cli/commands/state/rm.mdx
View File

@@ -1,34 +1,34 @@
---
description: >-
The `opentf state rm` command removes bindings from the OpenTF state,
causing OpenTF to "forget about" existing objects.
The `tofu state rm` command removes bindings from the OpenTofu state,
causing OpenTofu to "forget about" existing objects.
---
# Command: state rm
The main function of [OpenTF state](/docs/language/state) is
The main function of [OpenTofu state](/docs/language/state) is
to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally OpenTF automatically
and the remote objects they represent. Normally OpenTofu 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 `opentf state rm` in the less common situation where you wish
You can use `tofu 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 OpenTF "forget" the object while it continues
which will effectively make OpenTofu "forget" the object while it continues
to exist in the remote system.
## Usage
Usage: `opentf state rm [options] ADDRESS...`
Usage: `tofu state rm [options] ADDRESS...`
OpenTF will search the state for any instances matching the given
OpenTofu will search the state for any instances matching the given
[resource address](/docs/cli/state/resource-addressing), and remove
the record of each one so that OpenTF will no longer be tracking the
the record of each one so that OpenTofu will no longer be tracking the
corresponding remote objects.
This means that although the objects will still continue to exist in the
remote system, a subsequent
[`opentf plan`](/docs/cli/commands/plan)
[`tofu plan`](/docs/cli/commands/plan)
will include an action to create a new object for each of the "forgotten"
instances. Depending on the constraints imposed by the remote system, creating
those objects might fail if their names or other identifiers conflict with
@@ -44,27 +44,27 @@ This command also accepts the following options:
workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs OpenTF to retry acquiring a lock for a period of time before
instructs OpenTofu 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 [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote)
only, `opentf state rm`
only, `tofu state rm`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using
[the `local` state rm](/docs/language/settings/backends/local) only,
`opentf state rm` also accepts the legacy options
`tofu state rm` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments).
## Example: Remove all Instances of a Resource
The following example will cause OpenTF to "forget" all of the instances
The following example will cause OpenTofu to "forget" all of the instances
of the `packet_device` resource named "worker".
```shell
$ opentf state rm 'packet_device.worker'
$ tofu state rm 'packet_device.worker'
```
A resource that doesn't use `count` or `for_each` has only one instance, so
@@ -76,17 +76,17 @@ 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
$ opentf state rm 'module.foo.packet_device.worker'
$ tofu state rm 'module.foo.packet_device.worker'
```
## Example: Remove all Instances of all Resources in a Module
The following example will cause OpenTF to "forget" all of the instances
The following example will cause OpenTofu to "forget" all of the instances
associated with all resources defined in all instances of the module named
`foo`:
```shell
$ opentf state rm 'module.foo'
$ tofu state rm 'module.foo'
```
## Example: Remove a Particular Instance of a Resource using `count`
@@ -97,11 +97,11 @@ select a particular instance by including an explicit index in your given
address:
```shell
$ opentf state rm 'packet_device.worker[0]'
$ tofu 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 OpenTF.
quote or escape the address in order to pass it literally to OpenTofu.
The above shows the typical quoting syntax for Unix-style shells.
## Example: Remove a Particular Instance of a Resource using `for_each`
@@ -118,17 +118,17 @@ quoting and/or escaping syntax for the shell you are using. For example:
Unix-style shells, such as on Linux or macOS:
```shell
$ opentf state rm 'packet_device.worker["example"]'
$ tofu state rm 'packet_device.worker["example"]'
```
Windows Command Prompt (`cmd.exe`):
```shell
$ opentf state rm packet_device.worker[\"example\"]
$ tofu state rm packet_device.worker[\"example\"]
```
PowerShell:
```shell
$ opentf state rm 'packet_device.worker[\"example\"]'
$ tofu state rm 'packet_device.worker[\"example\"]'
```

28
website/docs/cli/commands/state/show.mdx
View File

@@ -1,18 +1,18 @@
---
description: >-
The `opentf state show` command is used to show the attributes of a single
resource in the OpenTF state.
The `tofu state show` command is used to show the attributes of a single
resource in the OpenTofu state.
---
# Command: state show
The `opentf state show` command is used to show the attributes of a
The `tofu state show` command is used to show the attributes of a
single resource in the
[OpenTF state](/docs/language/state).
[OpenTofu state](/docs/language/state).
## Usage
Usage: `opentf state show [options] ADDRESS`
Usage: `tofu state show [options] ADDRESS`
The command will show the attributes of a single resource in the
state file that matches the given address.
@@ -23,12 +23,12 @@ in [resource addressing format](/docs/cli/state/resource-addressing).
The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "opentf.tfstate".
* `-state=path` - Path to the state file. Defaults to "tofu.tfstate".
Ignored when [remote state](/docs/language/state/remote) is used.
The output of `opentf state show` is intended for human consumption, not
The output of `tofu state show` is intended for human consumption, not
programmatic consumption. To extract state data for use in other software, use
[`opentf show -json`](/docs/cli/commands/show#json-output) and decode the result
[`tofu show -json`](/docs/cli/commands/show#json-output) and decode the result
using the documented structure.
## Example: Show a Resource
@@ -36,7 +36,7 @@ using the documented structure.
The example below shows a `packet_device` resource named `worker`:
```
$ opentf state show 'packet_device.worker'
$ tofu state show 'packet_device.worker'
# packet_device.worker:
resource "packet_device" "worker" {
billing_cycle = "hourly"
@@ -53,7 +53,7 @@ resource "packet_device" "worker" {
The example below shows a `packet_device` resource named `worker` inside a module named `foo`:
```shell
$ opentf state show 'module.foo.packet_device.worker'
$ tofu state show 'module.foo.packet_device.worker'
```
## Example: Show a Resource configured with count
@@ -62,7 +62,7 @@ The example below shows the first instance of a `packet_device` resource named `
[`count`](/docs/language/meta-arguments/count):
```shell
$ opentf state show 'packet_device.worker[0]'
$ tofu state show 'packet_device.worker[0]'
```
## Example: Show a Resource configured with for_each
@@ -72,17 +72,17 @@ The following example shows the `"example"` instance of a `packet_device` resour
Linux, Mac OS, and UNIX:
```shell
$ opentf state show 'packet_device.worker["example"]'
$ tofu state show 'packet_device.worker["example"]'
```
PowerShell:
```shell
$ opentf state show 'packet_device.worker[\"example\"]'
$ tofu state show 'packet_device.worker[\"example\"]'
```
Windows `cmd.exe`:
```shell
$ opentf state show packet_device.worker[\"example\"]
$ tofu state show packet_device.worker[\"example\"]
```

26
website/docs/cli/commands/taint.mdx
View File

@@ -1,34 +1,34 @@
---
description: |-
The `opentf taint` command informs OpenTF that a particular object
The `tofu taint` command informs OpenTofu that a particular object
is damaged or degraded.
---
# Command: taint
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
The `tofu taint` command informs OpenTofu that a particular object has
become degraded or damaged. OpenTofu represents this by marking the
object as "tainted" in the OpenTofu state, and OpenTofu will
propose to replace it in the next plan you create.
:::warning
This command is deprecated, we recommend using the `-replace` option with `opentf apply` instead (details below).
This command is deprecated, we recommend using the `-replace` option with `tofu apply` instead (details below).
:::
## Recommended Alternative
We recommend using the [`-replace` option](/docs/cli/commands/plan#replace-address) with `opentf apply` to force OpenTF to replace an object even though there are no configuration changes that would require it.
We recommend using the [`-replace` option](/docs/cli/commands/plan#replace-address) with `tofu apply` to force OpenTofu to replace an object even though there are no configuration changes that would require it.
```
$ opentf apply -replace="aws_instance.example[0]"
$ tofu apply -replace="aws_instance.example[0]"
```
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.
We recommend the `-replace` option because the change will be reflected in the OpenTofu plan, letting you understand how it will affect your infrastructure before you take any externally-visible action. When you use `tofu taint`, other users could create a new plan against your tainted object before you can review the effects.
## Usage
```
$ opentf taint [options] <address>
$ tofu taint [options] <address>
```
The `address` argument is the address of the resource to mark as tainted.
@@ -48,19 +48,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 OpenTF's default behavior of attempting to take
- `-lock=false` - Disables OpenTofu'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 OpenTF to retry acquiring a lock for a period of time before
instructs OpenTofu 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 [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `opentf taint`
For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote) only, `tofu taint`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using
[the `local` backend](/docs/language/settings/backends/local) only,
`opentf taint` also accepts the legacy options
`tofu taint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments).

2
website/docs/cli/commands/test.mdx
View File

@@ -4,7 +4,7 @@ description: Part of the ongoing design research for module integration testing.
# Command: test
The `opentf test` command is currently serving as part of
The `tofu test` command is currently serving as part of
[the module integration testing experiment](/docs/language/modules/testing-experiment).
It's not ready for routine use, but if you'd be interested in trying the

28
website/docs/cli/commands/untaint.mdx
View File

@@ -1,26 +1,26 @@
---
description: |-
The `opentf untaint` command tells OpenTF that an object is functioning
The `tofu untaint` command tells OpenTofu that an object is functioning
correctly, even though its creation failed or it was previously manually
marked as degraded.
---
# Command: untaint
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.
OpenTofu has a marker called "tainted" which it uses to track that an object
might be damaged and so a future OpenTofu plan ought to replace it.
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
OpenTofu automatically marks an object as "tainted" if an error occurs during
a multi-step "create" action, because OpenTofu can't be sure that the object
was left in a fully-functional state.
You can also manually mark an object as "tainted" using the deprecated command
[`opentf taint`](/docs/cli/commands/taint), although we no longer recommend that
[`tofu taint`](/docs/cli/commands/taint), although we no longer recommend that
workflow.
If OpenTF currently considers a particular object as tainted but you've
If OpenTofu 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 `opentf untaint` to remove the taint marker from that object.
you can use `tofu 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.
@@ -30,12 +30,12 @@ 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:
```
opentf apply -replace="aws_instance.example[0]"
tofu apply -replace="aws_instance.example[0]"
```
## Usage
Usage: `opentf untaint [options] address`
Usage: `tofu untaint [options] address`
The `address` argument is a [resource address](/docs/cli/state/resource-addressing)
identifying a particular resource instance which is currently tainted.
@@ -52,20 +52,20 @@ This command also accepts the following options:
workspace.
- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
instructs OpenTF to retry acquiring a lock for a period of time before
instructs OpenTofu 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 OpenTF in a context where its output will be
if you are running OpenTofu in a context where its output will be
rendered by a system that cannot interpret terminal formatting.
For configurations using the [`cloud` backend](/docs/cli/cloud) or the [`remote` backend](/docs/language/settings/backends/remote)
only, `opentf untaint`
only, `tofu untaint`
also accepts the option
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
For configurations using
[the `local` backend](/docs/language/settings/backends/local) only,
`opentf untaint` also accepts the legacy options
`tofu untaint` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local#command-line-arguments).

44
website/docs/cli/commands/validate.mdx
View File

@@ -1,12 +1,12 @@
---
description: >-
The `opentf validate` command is used to validate the syntax of the
opentf files.
The `tofu validate` command is used to validate the syntax of the
tofu files.
---
# Command: validate
The `opentf validate` command validates the configuration files in a
The `tofu 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.
@@ -22,16 +22,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:
```
$ opentf init -backend=false
$ tofu init -backend=false
```
To verify configuration in the context of a particular run (a particular
target workspace, input variable values, etc), use the `opentf plan`
target workspace, input variable values, etc), use the `tofu plan`
command instead, which includes an implied validation check.
## Usage
Usage: `opentf validate [options]`
Usage: `tofu validate [options]`
This command accepts the following options:
@@ -43,14 +43,14 @@ This command accepts the following options:
## JSON Output Format
When you use the `-json` option, OpenTF will produce validation results
When you use the `-json` option, OpenTofu 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 OpenTF will encounter
As with all JSON output options, it's possible that OpenTofu 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
OpenTF's output should be prepared to find data on stdout that _isn't_ valid
OpenTofu'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 has
@@ -64,43 +64,43 @@ value `"1.0"`. The semantics of this version are:
version.
We will introduce new major versions only within the bounds of
[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
[the OpenTofu 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
In the normal case, OpenTF will print a JSON object to the standard output
In the normal case, OpenTofu 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 OpenTF considers the current configuration to be valid or
`true` if OpenTofu 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 OpenTF detected. If `valid` is `true` then `error_count` will
of errors OpenTofu 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 OpenTF detected. Warnings do not cause OpenTF to consider
of warnings OpenTofu detected. Warnings do not cause OpenTofu 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 OpenTF.
describe an error or warning from OpenTofu.
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 OpenTF to consider a configuration to be
The presence of errors causes OpenTofu 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 OpenTF may
block working with the configuration. Later versions of OpenTofu 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 OpenTF's usual human-oriented diagnostic messages, the summary serves
In OpenTofu's usual human-oriented diagnostic messages, the summary serves
as a sort of "heading" for the diagnostic, printed after the "Error:" or
"Warning:" indicator.
@@ -113,7 +113,7 @@ The nested objects in `diagnostics` have the following properties:
- `detail` (string): An optional additional message giving more detail about
the problem.
In OpenTF's usual human-oriented diagnostic messages, the detail provides
In OpenTofu's usual human-oriented diagnostic messages, the detail provides
the paragraphs of text that appear after the heading and the source location
reference.
@@ -124,7 +124,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 OpenTF detail messages contain an approximation of bullet
Some OpenTofu 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
@@ -154,7 +154,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 OpenTF configuration including the
- `code` (string): A snippet of OpenTofu 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.
@@ -209,4 +209,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 OpenTF.
versions of OpenTofu.

14
website/docs/cli/commands/version.mdx
View File

@@ -1,19 +1,19 @@
---
description: >-
The opentf version command displays the OpenTF version and the version
The tofu version command displays the OpenTofu version and the version
of all installed plugins.
---
# Command: version
The `opentf version` displays the current version of OpenTF and all
The `tofu version` displays the current version of OpenTofu and all
installed plugins.
## Usage
Usage: `opentf version [options]`
Usage: `tofu version [options]`
With no additional arguments, `version` will display the version of OpenTF,
With no additional arguments, `version` will display the version of OpenTofu,
the platform it's installed on, and installed providers.
This command has one optional flag:
@@ -26,8 +26,8 @@ This command has one optional flag:
Basic usage, with security information shown if relevant:
```shellsession
$ opentf version
OpenTF v1.6.0
$ tofu version
OpenTofu v1.6.0
on darwin_amd64
+ provider registry.terraform.io/hashicorp/null v3.0.0
```
@@ -35,7 +35,7 @@ on darwin_amd64
As JSON:
```shellsession
$ opentf version -json
$ tofu version -json
{
"terraform_version": "0.15.0",
"platform": "darwin_amd64",

18
website/docs/cli/commands/workspace/delete.mdx
View File

@@ -1,34 +1,34 @@
---
description: The opentf workspace delete command is used to delete a workspace.
description: The tofu workspace delete command is used to delete a workspace.
---
# Command: workspace delete
The `opentf workspace delete` command is used to delete an existing workspace.
The `tofu workspace delete` command is used to delete an existing workspace.
## Usage
Usage: `opentf workspace delete [OPTIONS] NAME [DIR]`
Usage: `tofu 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,
OpenTF will not allow you to delete it unless the `-force` flag is specified.
OpenTofu will not allow you to delete it unless the `-force` flag is specified.
Additionally, different [backends](/docs/language/settings/backends/configuration#backend-types) may implement other
restrictions on whether a workspace is considered safe to delete without the `-force` flag, such as whether the workspace is locked.
If you delete a workspace which is tracking resources (via `-force`), then resources
may become "dangling". These are resources that physically exist but that
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
OpenTofu can no longer manage. This is sometimes preferred: you may want
OpenTofu to stop managing resources, so they can be managed some other way.
Most of the time, however, this is not intended and so OpenTofu 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, OpenTF 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, OpenTofu 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.
@@ -37,6 +37,6 @@ The command-line flags are all optional. The only supported flags are:
## Example
```
$ opentf workspace delete example
$ tofu workspace delete example
Deleted workspace "example".
```

4
website/docs/cli/commands/workspace/index.mdx
View File

@@ -4,13 +4,13 @@ description: The workspace command helps you manage workspaces.
# Command: workspace
The `opentf workspace` command is used to manage
The `tofu workspace` command is used to manage
[workspaces](/docs/language/state/workspaces).
This command is a container for further subcommands that each have their own page in the documentation.
## Usage
Usage: `opentf workspace <subcommand> [options] [args]`
Usage: `tofu workspace <subcommand> [options] [args]`
Choose a subcommand page for more information.

8
website/docs/cli/commands/workspace/list.mdx
View File

@@ -1,14 +1,14 @@
---
description: The opentf workspace list command is used to list all existing workspaces.
description: The tofu workspace list command is used to list all existing workspaces.
---
# Command: workspace list
The `opentf workspace list` command is used to list all existing workspaces.
The `tofu workspace list` command is used to list all existing workspaces.
## Usage
Usage: `opentf workspace list [DIR]`
Usage: `tofu workspace list [DIR]`
The command will list all existing workspaces. The current workspace is
indicated using an asterisk (`*`) marker.
@@ -16,7 +16,7 @@ indicated using an asterisk (`*`) marker.
## Example
```
$ opentf workspace list
$ tofu workspace list
default
* development
jsmith-test

14
website/docs/cli/commands/workspace/new.mdx
View File

@@ -1,14 +1,14 @@
---
description: The opentf workspace new command is used to create a new workspace.
description: The tofu workspace new command is used to create a new workspace.
---
# Command: workspace new
The `opentf workspace new` command is used to create a new workspace.
The `tofu workspace new` command is used to create a new workspace.
## Usage
Usage: `opentf workspace new [OPTIONS] NAME [DIR]`
Usage: `tofu 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.
@@ -27,11 +27,11 @@ The command-line flags are all optional. The supported flags are:
## Example: Create
```
$ opentf workspace new example
$ tofu 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 "opentf plan" OpenTF will not see any existing state
so if you run "tofu plan" OpenTofu will not see any existing state
for this configuration.
```
@@ -40,10 +40,10 @@ for this configuration.
To create a new workspace from a pre-existing local state file:
```
$ opentf workspace new -state=old.opentf.tfstate example
$ tofu workspace new -state=old.tofu.tfstate example
Created and switched to workspace "example".
You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "opentf plan" OpenTF will not see any existing state
so if you run "tofu plan" OpenTofu will not see any existing state
for this configuration.
```

10
website/docs/cli/commands/workspace/select.mdx
View File

@@ -1,15 +1,15 @@
---
description: The opentf workspace select command is used to choose a workspace.
description: The tofu workspace select command is used to choose a workspace.
---
# Command: workspace select
The `opentf workspace select` command is used to choose a different
The `tofu workspace select` command is used to choose a different
workspace to use for further operations.
## Usage
Usage: `opentf workspace select NAME [DIR]`
Usage: `tofu workspace select NAME [DIR]`
This command will select another workspace. The named workspace must already
exist.
@@ -21,11 +21,11 @@ The supported flags are:
## Example
```
$ opentf workspace list
$ tofu workspace list
default
* development
jsmith-test
$ opentf workspace select default
$ tofu workspace select default
Switched to workspace "default".
```

8
website/docs/cli/commands/workspace/show.mdx
View File

@@ -1,20 +1,20 @@
---
description: The opentf workspace show command is used to output the current workspace.
description: The tofu workspace show command is used to output the current workspace.
---
# Command: workspace show
The `opentf workspace show` command is used to output the current workspace.
The `tofu workspace show` command is used to output the current workspace.
## Usage
Usage: `opentf workspace show`
Usage: `tofu workspace show`
The command will display the current workspace.
## Example
```
$ opentf workspace show
$ tofu workspace show
development
```

132
website/docs/cli/config/config-file.mdx
View File

@@ -5,10 +5,10 @@ description: >-
including credentials, plugin caching, provider installation methods, etc.
---
# CLI Configuration File (`.opentfrc` or `opentf.rc`)
# CLI Configuration File (`.tofurc` or `tofu.rc`)
The CLI configuration file configures per-user settings for CLI behaviors,
which apply across all OpenTF working directories. This is separate from
which apply across all OpenTofu working directories. This is separate from
[your infrastructure configuration](/docs/language).
## Locations
@@ -16,25 +16,25 @@ which apply across all OpenTF working directories. This is separate from
The configuration can be placed in a single file whose location depends
on the host operating system:
* On Windows, the file must be named `opentf.rc` and placed
* On Windows, the file must be named `tofu.rc` and placed
in the relevant user's `%APPDATA%` directory. The physical location
of this directory depends on your Windows version and system configuration;
use `$env:APPDATA` in PowerShell to find its location on your system.
The `terraform.rc` is supported for backward-compatability purposes.
If both `terraform.rc` and `opentf.rc` files exists, the later would take precedence.
* On all other systems, the file must be named `.opentfrc` (note
If both `terraform.rc` and `tofu.rc` files exists, the later would take precedence.
* On all other systems, the file must be named `.tofurc` (note
the leading period) and placed directly in the home directory
of the relevant user.
The `.terraformrc` is supported for backward-compatability purposes.
If both `.terraformrc` and `.opentfrc` files exists, the later would take precedence.
If both `.terraformrc` and `.tofurc` files exists, the later would take precedence.
On Windows, beware of Windows Explorer's default behavior of hiding filename
extensions. OpenTF will not recognize a file named `opentfc.rc.txt` as a
extensions. OpenTofu will not recognize a file named `tofuc.rc.txt` as a
CLI configuration file, even though Windows Explorer may _display_ its name
as just `opentf.rc`. Use `dir` from PowerShell or Command Prompt to
as just `tofu.rc`. Use `dir` from PowerShell or Command Prompt to
confirm the filename.
The location of the OpenTF CLI configuration file can also be specified
The location of the OpenTofu CLI configuration file can also be specified
using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/cli/config/environment-variables).
Any such file should follow the naming pattern `*.tfrc`.
@@ -65,12 +65,12 @@ 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
`opentf init` when installing provider plugins. See
`tofu init` when installing provider plugins. See
[Provider Installation](#provider-installation) below for more information.
## Credentials
When interacting with OpenTF-specific network services, OpenTF expects
When interacting with OpenTofu-specific network services, OpenTofu expects
to find API tokens in CLI configuration files in `credentials` blocks:
```hcl
@@ -79,7 +79,7 @@ credentials "app.placeholderplaceholderplaceholder.io" {
}
```
If you are running the OpenTF CLI interactively on a computer with a web browser, you can use [the `opentf login` command](/docs/cli/commands/login)
If you are running the OpenTofu CLI interactively on a computer with a web browser, you can use [the `tofu login` command](/docs/cli/commands/login)
to get credentials and automatically save them in the CLI configuration. If
not, you can manually write `credentials` blocks.
@@ -107,12 +107,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, OpenTF will choose the one defined last
If multiple variables evaluate to the same hostname, OpenTofu will choose the one defined last
in the operating system's variable table.
### Credentials Helpers
You can configure a `credentials_helper` to instruct OpenTF to use a different credentials storage mechanism.
You can configure a `credentials_helper` to instruct OpenTofu to use a different credentials storage mechanism.
```hcl
credentials_helper "example" {
@@ -133,7 +133,7 @@ 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.
OpenTF does not include any credentials helpers in the main distribution.
OpenTofu does not include any credentials helpers in the main distribution.
To learn how to write and install your own credentials helpers to integrate
with existing in-house credentials management systems, see
[the guide to Credentials Helper internals](/docs/internals/credentials-helpers).
@@ -141,7 +141,7 @@ with existing in-house credentials management systems, see
### 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 `opentf login`.
as described above will be preferred over those in CLI config as set by `tofu login`.
If neither are set, any configured credentials helper will be consulted.
## Provider Installation
@@ -149,23 +149,23 @@ If neither are set, any configured credentials helper will be consulted.
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,
OpenTF allows omitting the hostname portion for providers on
OpenTofu 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 OpenTF
appropriate, though. For example, the system where you are running OpenTofu
may not be able to access an origin registry due to firewall restrictions
within your organization or your locality.
To allow using OpenTF providers in these situations, there are some
alternative options for making provider plugins available to OpenTF which
To allow using OpenTofu providers in these situations, there are some
alternative options for making provider plugins available to OpenTofu which
we'll describe in the following sections.
### Explicit Installation Method Configuration
A `provider_installation` block in the CLI configuration allows overriding
OpenTF's default installation behaviors, so you can force OpenTF to use
OpenTofu's default installation behaviors, so you can force OpenTofu 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:
@@ -214,7 +214,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.
OpenTF expects the given directory to contain a nested directory structure
OpenTofu 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:
@@ -227,10 +227,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, OpenTF will attempt to create a symbolic
If you use the unpacked layout, OpenTofu 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 OpenTF must extract the zip file during installation.
because OpenTofu must extract the zip file during installation.
You can include multiple `filesystem_mirror` blocks in order to specify
several different directories to search.
@@ -240,7 +240,7 @@ 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.
OpenTF expects the given URL to be a base URL for an implementation of
OpenTofu expects the given URL to be a base URL for an implementation of
[the provider network mirror protocol](/docs/internals/provider-network-mirror-protocol),
which is designed to be relatively easy to implement using typical static
website hosting mechanisms.
@@ -252,23 +252,23 @@ identity, but a network mirror with a TLS certificate can potentially serve
modified copies of upstream providers with malicious content.
:::
OpenTF will try all of the specified methods whose include and exclude
OpenTofu 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
OpenTF configuration. If you have a local mirror of a particular provider
and intend OpenTF to use that local mirror exclusively, you must either
OpenTofu configuration. If you have a local mirror of a particular provider
and intend OpenTofu 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, OpenTF produces an _implied_ configuration. The implied configuration
all, OpenTofu produces an _implied_ configuration. The implied configuration
includes a selection of `filesystem_mirror` methods and then the `direct`
method.
The set of directories OpenTF can select as filesystem mirrors depends on
the operating system where you are running OpenTF:
The set of directories OpenTofu can select as filesystem mirrors depends on
the operating system where you are running OpenTofu:
* **Windows:** `%APPDATA%/terraform.d/plugins` and `%APPDATA%/HashiCorp/Terraform/plugins`
* **Mac OS X:** `$HOME/.terraform.d/plugins`,
@@ -278,21 +278,21 @@ the operating system where you are running OpenTF:
`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, OpenTF will use
Without any XDG environment variables set, OpenTofu 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 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`.
then OpenTofu 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, OpenTofu checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`.
OpenTF will check each of the paths above to see if it exists, and if so
OpenTofu 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, OpenTF
also creates an implied `direct` block. OpenTF will scan all of the
In addition to the zero or more implied `filesystem_mirror` blocks, OpenTofu
also creates an implied `direct` block. OpenTofu 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;
@@ -301,14 +301,14 @@ exclusions out yourself.)
### Provider Plugin Cache
By default, `opentf init` downloads plugins into a subdirectory of the
By default, `tofu 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 OpenTF optionally allows the
or metered Internet connections. Therefore OpenTofu 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.
@@ -319,8 +319,8 @@ the CLI configuration file. For example:
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
```
This directory must already exist before OpenTF will cache plugins;
OpenTF will not create the directory itself.
This directory must already exist before OpenTofu will cache plugins;
OpenTofu 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
@@ -335,16 +335,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 `opentf init` command will
When a plugin cache directory is enabled, the `tofu 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, OpenTF will use the previously-downloaded
in the cache directory. If so, OpenTofu will use the previously-downloaded
copy.
If the selected plugin is not already in the cache, OpenTF will download
If the selected plugin is not already in the cache, OpenTofu will download
it into the cache first and then copy it from there into the correct location
under your current working directory. When possible OpenTF will use
under your current working directory. When possible OpenTofu will use
symbolic links to avoid storing a separate copy of a cached plugin in multiple
directories.
@@ -352,13 +352,13 @@ 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.
OpenTF will never itself delete a plugin from the plugin cache once it has
OpenTofu 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 `opentf
safe. The provider installer's behavior in environments with multiple `tofu
init` calls is undefined.
:::
@@ -370,21 +370,21 @@ only. Do not set this option unless you are sure you need it and you fully
understand the consequences of enabling it.
:::
By default OpenTF will use packages from the global cache directory only
By default OpenTofu will use packages from the global cache directory only
if they match at least one of the checksums recorded in the
[dependency lock file](/docs/language/files/dependency-lock)
for that provider. This ensures that OpenTF can always
for that provider. This ensures that OpenTofu 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 OpenTF re-generate it each
version control as recommended and instead let OpenTofu 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, OpenTF allows an additional CLI Configuration
setting which tells OpenTF to always treat a package in the cache directory
control systems between runs, OpenTofu allows an additional CLI Configuration
setting which tells OpenTofu 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:
@@ -396,20 +396,20 @@ 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 OpenTF CLI permission to create an incomplete
dependency lock file entry for a provider if that would allow OpenTF to
Setting this option gives OpenTofu CLI permission to create an incomplete
dependency lock file entry for a provider if that would allow OpenTofu 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 OpenTF
We recommend that most users leave this option unset, in which case OpenTofu
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.
:::warning Note
The OpenTF team intends to improve the dependency lock file
The OpenTofu 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
@@ -419,7 +419,7 @@ dependency lock file.
### Development Overrides for Provider Developers
Normally OpenTF verifies version selections and checksums for providers
Normally OpenTofu 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.
@@ -429,7 +429,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, OpenTF supports a special
As a convenience for provider development, OpenTofu 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:
@@ -439,27 +439,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 OpenTF to look for the
# verifications for this provider and forces OpenTofu 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, OpenTF will _only_ use
# registries as normal. If you omit this, OpenTofu will _only_ use
# the dev_overrides block, and so no other providers will be available.
direct {}
}
```
With development overrides in effect, the `opentf init` command will still
With development overrides in effect, the `tofu init` command will still
attempt to select a suitable published version of your provider to install and
record in
[the dependency lock file](/docs/language/files/dependency-lock)
for future use, but other commands like
`opentf apply` will disregard the lock file's entry for `hashicorp/null` and
`tofu 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 `opentf init -upgrade` to
published release of the provider, you can use `tofu init -upgrade` to
select the new version in the dependency lock file and remove your development
override.
@@ -474,7 +474,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 OpenTF to use that
`TF_CLI_CONFIG_FILE` environment variable to instruct OpenTofu to use that
localized CLI configuration instead of the default one:
```
@@ -482,7 +482,7 @@ export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc
```
Development overrides are not intended for general use as a way to have
OpenTF look for providers on the local filesystem. If you wish to put
OpenTofu 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
@@ -492,6 +492,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 OpenTF releases, including possible breaking changes. We therefore
in future OpenTofu releases, including possible breaking changes. We therefore
recommend using development overrides only temporarily during provider
development work.

46
website/docs/cli/config/environment-variables.mdx
View File

@@ -1,14 +1,14 @@
---
description: >-
Learn to use environment variables to change OpenTF's default behavior.
Learn to use environment variables to change OpenTofu's default behavior.
Configure log content and output, set variables, and more.
---
# Environment Variables
OpenTF refers to a number of environment variables to customize various
OpenTofu refers to a number of environment variables to customize various
aspects of its behavior. None of these environment variables are required
when using OpenTF, but they can be used to change some of OpenTF's
when using OpenTofu, but they can be used to change some of OpenTofu's
default behaviors in unusual situations, or to increase output verbosity
for debugging.
@@ -26,21 +26,21 @@ To disable, either unset it, or set it to `off`. For example:
export TF_LOG=off
```
For more on debugging OpenTF, check out the section on [Debugging](/docs/internals/debugging).
For more on debugging OpenTofu, check out the section on [Debugging](/docs/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 opentf 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 tofu from:
```shell
export TF_LOG_PATH=./terraform.log
```
For more on debugging OpenTF, check out the section on [Debugging](/docs/internals/debugging).
For more on debugging OpenTofu, check out the section on [Debugging](/docs/internals/debugging).
## TF_INPUT
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:
If set to "false" or "0", causes tofu 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
@@ -65,17 +65,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 OpenTF on your own system.
modifying default behavior of OpenTofu 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" opentf apply -force`
is the equivalent to manually typing: `opentf apply -input=false -force`.
For example, the following command: `TF_CLI_ARGS="-input=false" tofu apply -force`
is the equivalent to manually typing: `tofu apply -input=false -force`.
The flag `TF_CLI_ARGS` affects all OpenTF commands. If you specify a
The flag `TF_CLI_ARGS` affects all OpenTofu 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"`.
@@ -86,7 +86,7 @@ be separated by spaces otherwise.
## TF_DATA_DIR
`TF_DATA_DIR` changes the location where OpenTF keeps its
`TF_DATA_DIR` changes the location where OpenTofu keeps its
per-working-directory data, such as the current backend configuration.
By default this data is written into a `.terraform` subdirectory of the
@@ -98,12 +98,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 OpenTF workflow commands (starting with `opentf init`) or else
OpenTF may be unable to find providers, modules, and other artifacts.
all of the OpenTofu workflow commands (starting with `tofu init`) or else
OpenTofu 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 `opentf 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 `tofu workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection.
For example:
@@ -117,14 +117,14 @@ For more information regarding workspaces, check out the section on [Using Works
## TF_IN_AUTOMATION
If `TF_IN_AUTOMATION` is set to any non-empty value, OpenTF adjusts its
If `TF_IN_AUTOMATION` is set to any non-empty value, OpenTofu 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 OpenTF commands, like in CI systems or other wrapping
directly execute OpenTofu commands, like in CI systems or other wrapping
applications.
This is a purely cosmetic change to OpenTF's human-readable output, and the
exact output differences can change between minor OpenTF versions.
This is a purely cosmetic change to OpenTofu's human-readable output, and the
exact output differences can change between minor OpenTofu versions.
## TF_REGISTRY_DISCOVERY_RETRY
@@ -142,10 +142,10 @@ export TF_REGISTRY_CLIENT_TIMEOUT=15
## TF_CLI_CONFIG_FILE
The location of the [OpenTF CLI configuration file](/docs/cli/config/config-file).
The location of the [OpenTofu CLI configuration file](/docs/cli/config/config-file).
```shell
export TF_CLI_CONFIG_FILE="$HOME/.opentfrc-custom"
export TF_CLI_CONFIG_FILE="$HOME/.tofurc-custom"
```
## TF_PLUGIN_CACHE_DIR
@@ -156,7 +156,7 @@ You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [t
## TF_IGNORE
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.
If `TF_IGNORE` is set to "trace", OpenTofu 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
@@ -166,6 +166,6 @@ For more details on `.terraformignore`, please see [Excluding Files from Upload
## Cloud Backend CLI Integration
The CLI integration with cloud backends lets you use them on the command line. The integration requires including a `cloud` block in your OpenTF configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI).
The CLI integration with cloud backends lets you use them on the command line. The integration requires including a `cloud` block in your OpenTofu configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI).
Refer to [Cloud Backend Settings](/docs/cli/cloud/settings#environment-variables) for a full list of `cloud` block environment variables.

12
website/docs/cli/config/index.mdx
View File

@@ -1,23 +1,23 @@
---
description: >-
Find documentation about the CLI config file and customizing OpenTF
Find documentation about the CLI config file and customizing OpenTofu
environment variables.
---
# CLI Configuration
OpenTF CLI can be configured with some global settings, which are separate
from any OpenTF configuration and which apply across all working directories.
OpenTofu CLI can be configured with some global settings, which are separate
from any OpenTofu configuration and which apply across all working directories.
We've designed OpenTF such that an average user running OpenTF CLI
We've designed OpenTofu such that an average user running OpenTofu 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 OpenTF on an airgapped
unusual environmental conditions like running OpenTofu on an airgapped
instance.
- The [CLI config file](/docs/cli/config/config-file) configures provider
installation and security features.
- Several [environment variables](/docs/cli/config/environment-variables) can
configure OpenTF's inputs and outputs; this includes some alternate ways to
configure OpenTofu'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.

10
website/docs/cli/import/importability.mdx
View File

@@ -1,15 +1,15 @@
---
description: |-
Each resource in OpenTF must implement some basic logic to become
importable. As a result, you cannot import all OpenTF resources.
Each resource in OpenTofu must implement some basic logic to become
importable. As a result, you cannot import all OpenTofu resources.
---
# Resource Importability
Each resource in OpenTF must implement some basic logic to become
importable. As a result, you cannot import all OpenTF resources.
Each resource in OpenTofu must implement some basic logic to become
importable. As a result, you cannot import all OpenTofu resources.
The resources that you can import are documented at the bottom of
each resource documentation page in the [public Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository.
To make a resource importable, refer to [Extending OpenTF: Resources — Import](/docs/plugin/sdkv2/resources/import).
To make a resource importable, refer to [Extending OpenTofu: Resources — Import](/docs/plugin/sdkv2/resources/import).

16
website/docs/cli/import/index.mdx
View File

@@ -1,27 +1,27 @@
---
description: >-
OpenTF can import and manage existing infrastructure. This can help you
transition your infrastructure to OpenTF.
OpenTofu can import and manage existing infrastructure. This can help you
transition your infrastructure to OpenTofu.
---
# Import
OpenTF can import existing infrastructure resources. This functionality lets you bring existing resources under OpenTF management.
OpenTofu can import existing infrastructure resources. This functionality lets you bring existing resources under OpenTofu management.
:::note
OpenTF supports `import` blocks. Unlike the `opentf import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/docs/language/import).
OpenTofu supports `import` blocks. Unlike the `tofu import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/docs/language/import).
:::
## State Only
:::warning
OpenTF expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. See [State](/docs/language/state) for more details.
OpenTofu expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTofu resource address. If you import the same object multiple times, OpenTofu may exhibit unwanted behavior. See [State](/docs/language/state) for more details.
:::
The `opentf import` CLI command can only import resources into the [state](/docs/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/docs/language/import).
The `tofu import` CLI command can only import resources into the [state](/docs/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/docs/language/import).
Before you run `opentf import` you must manually write a `resource` configuration block for the resource. The resource block describes where OpenTF should map the imported object.
Before you run `tofu import` you must manually write a `resource` configuration block for the resource. The resource block describes where OpenTofu should map the imported object.
## Cloud Backend
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.
When you use OpenTofu 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.

28
website/docs/cli/import/usage.mdx
View File

@@ -1,25 +1,25 @@
---
description: The `opentf import` command is used to import existing infrastructure.
description: The `tofu import` command is used to import existing infrastructure.
---
# Import Usage
Use the `opentf import` command to import existing infrastructure to OpenTF state.
Use the `tofu import` command to import existing infrastructure to OpenTofu 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.
The `tofu import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC.
:::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
OpenTofu expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by OpenTofu
itself having created all objects. If you import existing objects into OpenTofu,
be careful to import each remote object to only one OpenTofu resource address.
If you import the same object multiple times, OpenTofu may exhibit unwanted
behavior. For more information on this assumption, see
[the State section](/docs/language/state).
:::
To import a resource, first write a resource block for it in your
configuration, establishing the name by which it will be known to OpenTF:
configuration, establishing the name by which it will be known to OpenTofu:
```
resource "aws_instance" "example" {
@@ -35,18 +35,18 @@ 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 `opentf import` can be run to attach an existing instance to this
Now `tofu import` can be run to attach an existing instance to this
resource configuration:
```shell
$ opentf import aws_instance.example i-abcd1234
$ tofu 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
OpenTF state.
OpenTofu 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
@@ -59,7 +59,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 `opentf plan` to see how the configuration compares to
You can now run `tofu 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.
@@ -73,7 +73,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, OpenTF will plan to destroy the imported objects on the next run.
not done, OpenTofu will plan to destroy the imported objects on the next run.
If you want to rename or otherwise move the imported resources, the
[state management commands](/docs/cli/commands/state) can be used.

14
website/docs/cli/index.mdx
View File

@@ -1,17 +1,17 @@
---
sidebar_position: 1
description: >-
Learn OpenTF's CLI-based workflows. You can use the CLI alone or
Learn OpenTofu's CLI-based workflows. You can use the CLI alone or
with cloud backends.
---
# OpenTF CLI Documentation
# OpenTofu CLI Documentation
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
This is the documentation for OpenTofu CLI. It is relevant to anyone working
with OpenTofu's CLI-based workflows; this includes people who use OpenTofu CLI
by itself, as well as those who use OpenTofu CLI in conjunction with
TACOS (TF Automation and Collaboration Software).
Notably, this documentation does not cover the syntax and usage of the OpenTF
Notably, this documentation does not cover the syntax and usage of the OpenTofu
language. For that, see the
[OpenTF Language Documentation](/docs/language).
[OpenTofu Language Documentation](/docs/language).

34
website/docs/cli/init/index.mdx
View File

@@ -7,37 +7,37 @@ description: >-
# Initializing Working Directories
OpenTF expects to be invoked from a working directory that contains
OpenTofu expects to be invoked from a working directory that contains
configuration files written in
[the OpenTF language](/docs/language). OpenTF uses
[the OpenTofu language](/docs/language). OpenTofu 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 OpenTF can perform any
A working directory must be initialized before OpenTofu can perform any
operations in it (like provisioning infrastructure or modifying state).
## Working Directory Contents
A OpenTF working directory typically contains:
A OpenTofu working directory typically contains:
- A OpenTF configuration describing resources OpenTF should manage. This
- A OpenTofu configuration describing resources OpenTofu should manage. This
configuration is expected to change over time.
- A hidden `.terraform` directory, which OpenTF uses to manage cached
- A hidden `.terraform` directory, which OpenTofu uses to manage cached
provider plugins and modules, record which
[workspace](/docs/cli/workspaces) is currently active, and
record the last known backend configuration in case it needs to migrate state
on the next run. This directory is automatically managed by OpenTF, and is
on the next run. This directory is automatically managed by OpenTofu, and is
created during initialization.
- State data, if the configuration uses the default `local` backend. This is
managed by OpenTF in a `terraform.tfstate` file (if the directory only uses
managed by OpenTofu 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 `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`.
Run the `tofu init` command to initialize a working directory that contains
a OpenTofu configuration. After initialization, you will be able to perform
other commands, like `tofu plan` and `tofu 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
@@ -49,16 +49,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 `opentf init` command](/docs/cli/commands/init).
For details, see [the `tofu init` command](/docs/cli/commands/init).
## Reinitialization
Certain types of changes to a OpenTF configuration can require
Certain types of changes to a OpenTofu 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 `opentf init` again. In fact, you
You can reinitialize a directory by running `tofu 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.
@@ -67,7 +67,7 @@ fail with an error and tell you so.
## Reinitializing Only Modules
The `opentf get` command will download modules referenced in the
The `tofu 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 OpenTF users can
ignore it in favor of `opentf init`.
This command is only useful for niche workflows, and most OpenTofu users can
ignore it in favor of `tofu init`.

18
website/docs/cli/inspect/index.mdx
View File

@@ -6,29 +6,29 @@ description: >-
# Inspecting Infrastructure
OpenTF configurations and state data include some highly structured
OpenTofu 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.
OpenTF CLI includes some commands for inspecting or transforming this data.
You can use these to integrate other tools with OpenTF's infrastructure data,
OpenTofu CLI includes some commands for inspecting or transforming this data.
You can use these to integrate other tools with OpenTofu's infrastructure data,
or just to gain a deeper or more holistic understanding of your infrastructure.
- [The `opentf graph` command](/docs/cli/commands/graph) creates a visual
- [The `tofu graph` command](/docs/cli/commands/graph) creates a visual
representation of a configuration or a set of planned changes.
- [The `opentf output` command](/docs/cli/commands/output) can get the
- [The `tofu output` command](/docs/cli/commands/output) can get the
values for the top-level [output values](/docs/language/values/outputs) of
a configuration, which are often helpful when making use of the infrastructure
OpenTF has provisioned.
- [The `opentf show` command](/docs/cli/commands/show) can generate
OpenTofu has provisioned.
- [The `tofu show` command](/docs/cli/commands/show) can generate
human-readable versions of a state file or plan file, or generate
machine-readable versions that can be integrated with other tools.
- [The `opentf state list` command](/docs/cli/commands/state/list) can list
- [The `tofu state list` command](/docs/cli/commands/state/list) can list
the resources being managed by the current working directory and workspace,
providing a complete or filtered list.
- [The `opentf state show` command](/docs/cli/commands/state/show) can print
- [The `tofu state show` command](/docs/cli/commands/state/show) can print
all of the attributes of a given resource being managed by the current working
directory and workspace, including generated read-only attributes like the
unique ID assigned by the cloud provider.

26
website/docs/cli/install/apt.mdx
View File

@@ -1,20 +1,20 @@
---
description: >-
The OpenTF APT repositories contain distribution-specific OpenTF
The OpenTofu APT repositories contain distribution-specific OpenTofu
packages for both Debian and Ubuntu systems.
---
# APT Packages for Debian and Ubuntu
The primary distribution packages for OpenTF are `.zip` archives containing
The primary distribution packages for OpenTofu 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 OpenTF using the
Debian and Ubuntu systems, which allow you to install OpenTofu using the
`apt install` command or any other APT frontend.
If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you
might prefer to [install OpenTF from our Yum repositories](/docs/cli/install/yum).
might prefer to [install OpenTofu from our Yum repositories](/docs/cli/install/yum).
## Repository Configuration
@@ -22,29 +22,29 @@ Please follow the instructions in the [Official Packaging Guide](https://www.pla
## Supported Architectures
The OpenTF APT server has packages only for the `amd64`
The OpenTofu 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 OpenTF on a non-`amd64` system,
`arm64`. If you wish to use OpenTofu on a non-`amd64` system,
[download a normal release `.zip` file](/docs/downloads) instead.
## Installing a Specific Version of OpenTF
## Installing a Specific Version of OpenTofu
The OpenTF APT repositories contain multiple versions of OpenTF, but
because the packages are all named `opentf` it is impossible to install
The OpenTofu APT repositories contain multiple versions of OpenTofu, but
because the packages are all named `tofu` 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 OpenTF version with what a particular
It's often necessary to match your OpenTofu 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 opentf
apt policy tofu
```
If your workflow requires using multiple versions of OpenTF at the same
If your workflow requires using multiple versions of OpenTofu 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
@@ -60,5 +60,5 @@ 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 opentf=1.4.4-*
sudo apt install tofu=1.4.4-*
```

34
website/docs/cli/install/yum.mdx
View File

@@ -1,21 +1,21 @@
---
title: Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux
description: >-
The OpenTF Yum repositories contain distribution-specific OpenTF
The OpenTofu Yum repositories contain distribution-specific OpenTofu
packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems.
---
# Yum/DNF Packages for RHEL, CentOS, and Fedora
The primary distribution packages for OpenTF are `.zip` archives containing
The primary distribution packages for OpenTofu 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 OpenTF using the `yum install` or `dnf install` commands.
install OpenTofu using the `yum install` or `dnf install` commands.
If you are instead using Debian or Ubuntu, you
might prefer to [install OpenTF from our APT repositories](/docs/cli/install/apt).
might prefer to [install OpenTofu from our APT repositories](/docs/cli/install/apt).
## Repository Configuration
@@ -43,24 +43,24 @@ sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://rpm.releases.placeholderplaceholderplaceholder.com/$release/hashicorp.repo
```
In both cases, the OpenTF package name is `opentf`. For example:
In both cases, the OpenTofu package name is `tofu`. For example:
```bash
yum install opentf
yum install tofu
```
## Supported Architectures
The OpenTF Yum/DNF server has packages only for the `x86_64`
The OpenTofu 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 OpenTF on a non-`x86_64` system,
`aarch64`. If you wish to use OpenTofu on a non-`x86_64` system,
[download a normal release `.zip` file](/docs/downloads) instead.
## Supported Distribution Releases
The OpenTF Yum server contains release repositories for the
The OpenTofu Yum server contains release repositories for the
following distribution releases:
* AmazonLinux 2 and "latest"
@@ -78,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 OpenTF versions
adding support for new releases and ceasing to publish new OpenTofu versions
under older releases.
## Choosing OpenTF Versions
## Choosing OpenTofu Versions
The OpenTF Yum repositories contain multiple versions of OpenTF, but
because the packages are all named `opentf` it is impossible to install
The OpenTofu Yum repositories contain multiple versions of OpenTofu, but
because the packages are all named `tofu` 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 OpenTF version with what a particular
It's often necessary to match your OpenTofu 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 opentf
yum --showduplicate list tofu
```
You can select a specific version to install by including it in the
`yum install` command line, as follows:
```bash
yum install opentf-0.14.0-2.x86_64
yum install tofu-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 OpenTF at the same
If your workflow requires using multiple versions of OpenTofu 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

32
website/docs/cli/plugins/index.mdx
View File

@@ -6,55 +6,55 @@ description: >-
# Managing Plugins
OpenTF relies on plugins called "providers" in order to manage various types
OpenTofu relies on plugins called "providers" in order to manage various types
of resources. (For more information about providers, see
[Providers](/docs/language/providers) in the OpenTF
[Providers](/docs/language/providers) in the OpenTofu
language docs.)
:::note
Providers are the only plugin type most OpenTF users interact with. OpenTF also supports third-party provisioner plugins, but
Providers are the only plugin type most OpenTofu users interact with. OpenTofu also supports third-party provisioner plugins, but
we discourage their use.
:::
OpenTF downloads and/or installs any providers
OpenTofu downloads and/or installs any providers
[required](/docs/language/providers/requirements) by a configuration
when [initializing](/docs/cli/init) a working directory. By default,
this works without any additional interaction but requires network access to
download providers from their source registry.
You can configure OpenTF's provider installation behavior to limit or skip
You can configure OpenTofu's provider installation behavior to limit or skip
network access, and to enable use of providers that aren't available via a
networked source. OpenTF also includes some commands to show information
networked source. OpenTofu also includes some commands to show information
about providers and to reduce the effort of installing providers in airgapped
environments.
## Configuring Plugin Installation
OpenTF's configuration file includes options for caching downloaded plugins,
OpenTofu's configuration file includes options for caching downloaded plugins,
or explicitly specifying a local or HTTPS mirror to install plugins from. For
more information, see [CLI Config File](/docs/cli/config/config-file).
## Getting Plugin Information
Use the [`opentf providers`](/docs/cli/commands/providers) command to get information
Use the [`tofu providers`](/docs/cli/commands/providers) command to get information
about the providers required by the current working directory's configuration.
Use the [`opentf version`](/docs/cli/commands/version) command (or
`opentf -version`) to show the specific provider versions installed for the
Use the [`tofu version`](/docs/cli/commands/version) command (or
`tofu -version`) to show the specific provider versions installed for the
current working directory.
Use the [`opentf providers schema`](/docs/cli/commands/providers/schema) command to
Use the [`tofu providers schema`](/docs/cli/commands/providers/schema) command to
get machine-readable information about the resources and configuration options
offered by each provider.
## Managing Plugin Installation
Use the [`opentf providers mirror`](/docs/cli/commands/providers/mirror) command to
Use the [`tofu providers mirror`](/docs/cli/commands/providers/mirror) command to
download local copies of every provider required by the current working
directory's configuration. This directory will use the nested directory layout
that OpenTF expects when installing plugins from a local source, so you can
transfer it directly to an airgapped system that runs OpenTF.
that OpenTofu expects when installing plugins from a local source, so you can
transfer it directly to an airgapped system that runs OpenTofu.
Use the [`opentf providers lock`](/docs/cli/commands/providers/lock) command
to update the lock file that OpenTF uses to ensure predictable runs when
Use the [`tofu providers lock`](/docs/cli/commands/providers/lock) command
to update the lock file that OpenTofu uses to ensure predictable runs when
using ambiguous provider version constraints.

10
website/docs/cli/plugins/signing.mdx
View File

@@ -1,6 +1,6 @@
---
description: >-
Learn about the types of signatures providers can have on the OpenTF
Learn about the types of signatures providers can have on the OpenTofu
Registry.
---
@@ -9,20 +9,20 @@ description: >-
<!-- THIS PAGED IS LINKED TO IN THE CLI -->
:::warning Note
OpenTF only authenticates provider plugins fetched from a registry.
OpenTofu only authenticates provider plugins fetched from a registry.
:::
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:
OpenTofu 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. OpenTF does not provide a
* **Self-signed** - are built, signed, and supported by a third party. OpenTofu 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.
OpenTF does **NOT** support fetching and using unsigned binaries, but you can manually install
OpenTofu 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).

38
website/docs/cli/run/index.mdx
View File

@@ -2,25 +2,25 @@
description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.'
---
# Provisioning Infrastructure with OpenTF
# Provisioning Infrastructure with OpenTofu
OpenTF's primary function is to create, modify, and destroy infrastructure
OpenTofu's primary function is to create, modify, and destroy infrastructure
resources to match the desired state described in a
[OpenTF configuration](/docs/language).
[OpenTofu configuration](/docs/language).
When people refer to "running OpenTF," they generally mean performing these
When people refer to "running OpenTofu," they generally mean performing these
provisioning actions in order to affect real infrastructure objects. The
OpenTF binary has many other subcommands for a wide variety of administrative
actions, but these basic provisioning tasks are the core of OpenTF.
OpenTofu binary has many other subcommands for a wide variety of administrative
actions, but these basic provisioning tasks are the core of OpenTofu.
OpenTF's provisioning workflow relies on three commands: `plan`, `apply`, and
OpenTofu's provisioning workflow relies on three commands: `plan`, `apply`, and
`destroy`. All of these commands require an
[initialized](/docs/cli/init) working directory, and all of them act
only upon the currently selected [workspace](/docs/cli/workspaces).
## Planning
The `opentf plan` command evaluates a OpenTF configuration to determine
The `tofu plan` command evaluates a OpenTofu 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
@@ -28,38 +28,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, `opentf plan` presents a description of the changes necessary to
state, `tofu 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, `opentf plan` can also save its
plan as a runnable artifact, which `opentf apply` can use to carry out those
resulting actions are as expected. However, `tofu plan` can also save its
plan as a runnable artifact, which `tofu apply` can use to carry out those
exact changes.
For details, see [the `opentf plan` command](/docs/cli/commands/plan).
For details, see [the `tofu plan` command](/docs/cli/commands/plan).
## Applying
The `opentf apply` command performs a plan just like `opentf plan` does,
The `tofu apply` command performs a plan just like `tofu 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, `opentf apply` performs a fresh plan right before applying
By default, `tofu 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 `opentf plan` in lieu of
However, it can also accept a plan file produced by `tofu 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 `opentf apply` command](/docs/cli/commands/apply).
For details, see [the `tofu apply` command](/docs/cli/commands/apply).
## Destroying
The `opentf destroy` command destroys all of the resources being managed by
The `tofu 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 `opentf apply`, it
real world objects correspond to managed resources. Like `tofu apply`, it
asks for confirmation before proceeding.
A destroy behaves exactly like deleting every resource from the configuration
@@ -67,4 +67,4 @@ and then running an apply, except that it doesn't require editing the
configuration. This is more convenient if you intend to provision similar
resources at a later date.
For details, see [the `opentf destroy` command](/docs/cli/commands/destroy).
For details, see [the `tofu destroy` command](/docs/cli/commands/destroy).

12
website/docs/cli/state/index.mdx
View File

@@ -4,19 +4,19 @@ description: >-
Inspect state, move or import resources, and more.
---
# Manipulating OpenTF State
# Manipulating OpenTofu State
OpenTF uses [state data](/docs/language/state) to remember which
OpenTofu uses [state data](/docs/language/state) to remember which
real-world object corresponds to each resource in the configuration;
this allows it to modify an existing object when its resource declaration
changes.
OpenTF updates state automatically during plans and applies. However, it's
sometimes necessary to make deliberate adjustments to OpenTF's state data,
OpenTofu updates state automatically during plans and applies. However, it's
sometimes necessary to make deliberate adjustments to OpenTofu's state data,
usually to compensate for changes to the configuration or the real managed
infrastructure.
OpenTF CLI supports several workflows for interacting with state:
OpenTofu CLI supports several workflows for interacting with state:
- [Inspecting State](/docs/cli/state/inspect)
- [Forcing Re-creation](/docs/cli/state/taint)
@@ -27,7 +27,7 @@ OpenTF CLI supports several workflows for interacting with state:
:::warning Important
Modifying state data outside a normal plan or apply can cause
OpenTF to lose track of managed resources, which might waste money, annoy
OpenTofu 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.
:::

10
website/docs/cli/state/inspect.mdx
View File

@@ -4,17 +4,17 @@ description: Commands that allow you to read and update state.
# Inspecting State
OpenTF includes some commands for reading and updating state without taking
OpenTofu includes some commands for reading and updating state without taking
any other actions.
- [The `opentf state list` command](/docs/cli/commands/state/list)
shows the resource addresses for every resource OpenTF knows about in a
- [The `tofu state list` command](/docs/cli/commands/state/list)
shows the resource addresses for every resource OpenTofu knows about in a
configuration, optionally filtered by partial resource address.
- [The `opentf state show` command](/docs/cli/commands/state/show)
- [The `tofu state show` command](/docs/cli/commands/state/show)
displays detailed state data about one resource.
- [The `opentf refresh` command](/docs/cli/commands/refresh) updates
- [The `tofu refresh` command](/docs/cli/commands/refresh) updates
state data to match the real-world condition of the managed resources. This is
done automatically during plans and applies, but not when interacting with
state directly.

26
website/docs/cli/state/move.mdx
View File

@@ -6,39 +6,39 @@ description: >-
# Moving Resources
OpenTF's state associates each real-world object with a configured resource
OpenTofu's state associates each real-world object with a configured resource
at a specific [resource address](/docs/cli/state/resource-addressing). This
is seamless when changing a resource's attributes, but OpenTF will lose track
is seamless when changing a resource's attributes, but OpenTofu 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: OpenTF will destroy the old resource, replace it with a
Usually that's fine: OpenTofu 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 OpenTF to associate it with a different configured
can explicitly tell OpenTofu to associate it with a different configured
resource.
For most cases we recommend using
[the OpenTF language's refactoring features](/docs/language/modules/develop/refactoring)
[the OpenTofu language's refactoring features](/docs/language/modules/develop/refactoring)
to document in your module exactly how the resource names have changed over
time. OpenTF reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps.
time. OpenTofu reacts to this information automatically during planning, so users of your module do not need to take any unusual extra steps.
There are some other situations which require explicit state modifications,
though. For those, consider the following OpenTF commands:
though. For those, consider the following OpenTofu commands:
- [The `opentf state mv` command](/docs/cli/commands/state/mv) changes
- [The `tofu state mv` command](/docs/cli/commands/state/mv) changes
which resource address in your configuration is associated with a particular
real-world object. Use this to preserve an object when renaming a resource, or
when moving a resource into or out of a child module.
- [The `opentf state rm` command](/docs/cli/commands/state/rm) tells
OpenTF to stop managing a resource as part of the current working directory
- [The `tofu state rm` command](/docs/cli/commands/state/rm) tells
OpenTofu to stop managing a resource as part of the current working directory
and workspace, _without_ destroying the corresponding real-world object. (You
can later use `opentf import` to start managing that resource in a
different workspace or a different OpenTF configuration.)
can later use `tofu import` to start managing that resource in a
different workspace or a different OpenTofu configuration.)
- [The `opentf state replace-provider` command](/docs/cli/commands/state/replace-provider)
- [The `tofu state replace-provider` command](/docs/cli/commands/state/replace-provider)
transfers existing resources to a new provider without requiring them to be
re-created.

12
website/docs/cli/state/recover.mdx
View File

@@ -1,6 +1,6 @@
---
description: >-
Learn how to restore state backups and override OpenTF state protections to fix state errors with the OpenTF CLI.
Learn how to restore state backups and override OpenTofu state protections to fix state errors with the OpenTofu CLI.
---
@@ -10,15 +10,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 `opentf force-unlock` command](/docs/cli/commands/force-unlock) can
override the protections OpenTF uses to prevent two processes from
modifying state at the same time. You might need this if a OpenTF process
- [The `tofu force-unlock` command](/docs/cli/commands/force-unlock) can
override the protections OpenTofu uses to prevent two processes from
modifying state at the same time. You might need this if a OpenTofu 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 `opentf state pull` command](/docs/cli/commands/state/pull) and
[the `opentf state push` command](/docs/cli/commands/state/push) can
- [The `tofu state pull` command](/docs/cli/commands/state/pull) and
[the `tofu state push` command](/docs/cli/commands/state/push) can
directly read and write entire state files from and to the configured backend.
You might need this for obtaining or restoring a state backup.

8
website/docs/cli/state/resource-addressing.mdx
View File

@@ -15,7 +15,7 @@ An address is made up of two parts:
[module path][resource spec]
```
In some contexts OpenTF might allow for an incomplete resource address that
In some contexts OpenTofu 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
@@ -81,7 +81,7 @@ The following specifications apply to index values on modules and resources with
### count Example
Given a OpenTF config that includes:
Given a OpenTofu config that includes:
```hcl
resource "aws_instance" "web" {
@@ -106,13 +106,13 @@ Refers to all four "web" instances.
### for_each Example
Given a OpenTF config that includes:
Given a OpenTofu config that includes:
```hcl
resource "aws_instance" "web" {
# ...
for_each = {
"opentf": "value1",
"tofu": "value1",
"resource": "value2",
"indexing": "value3",
"example": "value4",

34
website/docs/cli/state/taint.mdx
View File

@@ -4,24 +4,24 @@ description: Commands that allow you to destroy and re-create resources manually
# Forcing Re-creation of Resources
During planning, by default OpenTF retrieves the latest state of each
During planning, by default OpenTofu 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 OpenTF cannot automatically detect. For example, if software
way that OpenTofu cannot automatically detect. For example, if software
running inside a virtual machine crashes but the virtual machine itself is
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.
still running then OpenTofu will typically have no way to detect and respond
to the problem, because OpenTofu only directly manages the machine as a whole.
If you know that an object is damaged, or if you want to force OpenTF to
replace it for any other reason, you can override OpenTF's default behavior
If you know that an object is damaged, or if you want to force OpenTofu to
replace it for any other reason, you can override OpenTofu's default behavior
using [the `-replace=...` planning option](/docs/cli/commands/plan#replace-address)
when you run either `opentf plan` or `opentf apply`:
when you run either `tofu plan` or `tofu apply`:
```shellsession
$ opentf apply -replace="aws_instance.example"
$ tofu apply -replace="aws_instance.example"
# ...
# aws_instance.example will be replaced, as requested
@@ -32,13 +32,13 @@ $ opentf apply -replace="aws_instance.example"
## The "tainted" status
Sometimes OpenTF is able to infer automatically that an object is in an
Sometimes OpenTofu 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,
OpenTF must remember that the object exists but may not be fully-functional.
OpenTofu must remember that the object exists but may not be fully-functional.
OpenTF represents this situation by marking an object in the state as
OpenTofu 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.
@@ -50,13 +50,13 @@ address using `-replace=...` as described above.
}
```
If OpenTF has marked an object as tainted but you consider it to be working
correctly and do not want to replace it, you can override OpenTF's
determination using [the `opentf untaint` command](/docs/cli/commands/untaint),
after which OpenTF will consider the object to be ready for use by any
If OpenTofu has marked an object as tainted but you consider it to be working
correctly and do not want to replace it, you can override OpenTofu's
determination using [the `tofu untaint` command](/docs/cli/commands/untaint),
after which OpenTofu will consider the object to be ready for use by any
downstream resource declarations.
You can also _force_ OpenTF to mark a particular object as tainted using
[the `opentf taint` command](/docs/cli/commands/taint), but that approach is
You can also _force_ OpenTofu to mark a particular object as tainted using
[the `tofu taint` command](/docs/cli/commands/taint), but that approach is
deprecated in favor of the `-replace=...` option, which avoids the need to
create an interim state snapshot with a tainted object.

22
website/docs/cli/workspaces/index.mdx
View File

@@ -6,27 +6,27 @@ description: >-
# Managing Workspaces
Workspaces in the OpenTF CLI refer to separate instances of [state data](/docs/language/state) inside the same OpenTF working directory. They are distinctly different from workspaces in a cloud backend, which each have their own OpenTF configuration and function as separate working directories.
Workspaces in the OpenTofu CLI refer to separate instances of [state data](/docs/language/state) inside the same OpenTofu working directory. They are distinctly different from workspaces in a cloud backend, which each have their own OpenTofu configuration and function as separate working directories.
OpenTF relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, OpenTF can manage multiple sets of non-overlapping resources.
OpenTofu relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, OpenTofu 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 OpenTF 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 OpenTofu 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](/docs/cli/init) starts with one workspace named `default`.
Use the [`opentf workspace list`](/docs/cli/commands/workspace/list), [`opentf workspace new`](/docs/cli/commands/workspace/new), and [`opentf workspace delete`](/docs/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory.
Use the [`tofu workspace list`](/docs/cli/commands/workspace/list), [`tofu workspace new`](/docs/cli/commands/workspace/new), and [`tofu workspace delete`](/docs/cli/commands/workspace/delete) commands to manage the available workspaces in the current working directory.
Use [the `opentf workspace select` command](/docs/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most OpenTF commands only interact with the currently selected workspace. This includes [provisioning](/docs/cli/run) and [state manipulation](/docs/cli/state).
Use [the `tofu workspace select` command](/docs/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most OpenTofu commands only interact with the currently selected workspace. This includes [provisioning](/docs/cli/run) and [state manipulation](/docs/cli/state).
When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/docs/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region.
## Use Cases
You can create multiple [working directories](/docs/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, OpenTF installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches.
You can create multiple [working directories](/docs/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, OpenTofu 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.
@@ -39,7 +39,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 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.
When using OpenTofu to manage larger systems, you should create separate OpenTofu 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
@@ -57,16 +57,16 @@ When multiple configurations represent distinct system components rather than mu
- For server addresses, use a provider-specific resource to create a DNS record with a predictable name. Then you can either use that name directly or use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve the published addresses in other configurations.
- If you store a OpenTF state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/docs/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system.
- If you store a OpenTofu state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/docs/language/state/remote-state-data) to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system.
## Workspace Internals
Workspaces are technically equivalent to renaming your state file. OpenTF then includes a set of protections and support for remote state.
Workspaces are technically equivalent to renaming your state file. OpenTofu 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, 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 local state, OpenTofu 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](/docs/language/state/remote), the workspaces are stored directly in the configured [backend](/docs/language/settings/backends/configuration). For example, if you use [Consul](/docs/language/settings/backends/consul), the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping.
OpenTF stores the current workspace name locally in the ignored `.terraform` directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in a cloud backend. For more details about workspace names in cloud backends, refer to the [CLI Integration (recommended)](/docs/cli/cloud/settings#arguments) and [remote backend](/docs/language/settings/backends/remote#workspaces) and documentation.
OpenTofu stores the current workspace name locally in the ignored `.terraform` directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in a cloud backend. For more details about workspace names in cloud backends, refer to the [CLI Integration (recommended)](/docs/cli/cloud/settings#arguments) and [remote backend](/docs/language/settings/backends/remote#workspaces) and documentation.

36
website/docs/internals/credentials-helpers.mdx
View File

@@ -1,25 +1,25 @@
---
description: >-
Credentials helpers are external programs that know how to store and retrieve
API tokens for remote OpenTF services.
API tokens for remote OpenTofu services.
---
# Credentials Helpers
For OpenTF-specific features that interact with remote network services,
such as [module registries](/docs/registry), OpenTF by default looks for
For OpenTofu-specific features that interact with remote network services,
such as [module registries](/docs/registry), OpenTofu by default looks for
API credentials to use in these calls in
[the CLI configuration](/docs/cli/config/config-file).
Credentials helpers offer an alternative approach that allows you to customize
how OpenTF obtains credentials using an external program, which can then
how OpenTofu obtains credentials using an external program, which can then
directly access an existing secrets management system in your organization.
This page is about how to write and install a credentials helper. To learn
how to configure a credentials helper that was already installed, see
[the CLI config Credentials Helpers section](/docs/cli/config/config-file#credentials-helpers).
## How OpenTF finds Credentials Helpers
## How OpenTofu finds Credentials Helpers
A credentials helper is a normal executable program that is installed in a
particular location and whose name follows a specific naming convention.
@@ -27,11 +27,11 @@ particular location and whose name follows a specific naming convention.
A credentials helper called "credstore", for example, would be implemented as
an executable program named `terraform-credentials-credstore` (with an `.exe`
extension on Windows only), and installed in one of the
[default plugin search locations](/docs/plugin/how-opentf-works#plugin-locations).
[default plugin search locations](/docs/plugin/how-opentofu-works#plugin-locations).
## How OpenTF runs Credentials Helpers
## How OpenTofu runs Credentials Helpers
Once OpenTF has located the configured credentials helper, it will execute
Once OpenTofu has located the configured credentials helper, it will execute
it once for each credentials request that cannot be satisfied by a `credentials`
block in the CLI configuration.
@@ -44,7 +44,7 @@ credentials_helper "credstore" {
}
```
OpenTF runs the helper program with each of the arguments given in `args`,
OpenTofu runs the helper program with each of the arguments given in `args`,
followed by an _verb_ and then the hostname that the verb will apply to.
The current set of verbs are:
@@ -69,7 +69,7 @@ three verbs.
## `get`: retrieve the credentials for the given hostname
To retrieve credentials for `app.example.io`, OpenTF would run the
To retrieve credentials for `app.example.io`, OpenTofu would run the
"credstore" helper as follows:
```
@@ -89,14 +89,14 @@ to its stderr stream and then exit with a _non-zero_ status code.
## `store`: store new credentials for the given hostname
To store new credentials for `app.example.io`, OpenTF would run the
To store new credentials for `app.example.io`, OpenTofu would run the
"credstore" helper as follows:
```
terraform-credentials-credstore --host=credstore.example.com store app.example.io
```
OpenTF then writes a JSON credentials object to the helper program's stdin
OpenTofu then writes a JSON credentials object to the helper program's stdin
stream. If the helper is able to store the given credentials then it must do
so and then exit with status code zero and no output on stdout or stderr to
indicate success.
@@ -111,7 +111,7 @@ given hostname.
## `forget`: delete any stored credentials for the given hostname
To forget any existing credentials for `app.example.io`, OpenTF would run
To forget any existing credentials for `app.example.io`, OpenTofu would run
the "credstore" helper as follows:
```
@@ -138,7 +138,7 @@ stream and then exiting with a non-zero status code.
## Handling Unsupported Credentials Object Properties
OpenTF defines only the `token` property within JSON credentials
OpenTofu defines only the `token` property within JSON credentials
objects.
If a credentials helper is asked to store an object that has any properties
@@ -155,9 +155,9 @@ other properties as described above.
## Installing a Credentials Helper
OpenTF does not have any automatic installation mechanism for credentials
OpenTofu does not have any automatic installation mechanism for credentials
helpers. Instead, the user must extract the helper program executable into
one of the [default plugin search locations](/docs/plugin/how-opentf-works#plugin-locations).
one of the [default plugin search locations](/docs/plugin/how-opentofu-works#plugin-locations).
If you are packaging a credentials helper for distribution, place it in an
named with the expected naming scheme (`terraform-credentials-example`) and,
@@ -165,7 +165,7 @@ if the containing archive format supports it and it's meaningful for the
target operating system, mark the file as executable to increase the chances
that it will work immediately after extraction.
OpenTF does _not_ honor the `-plugin-dir` argument to `opentf init` when
OpenTofu does _not_ honor the `-plugin-dir` argument to `tofu init` when
searching for credentials helpers, because credentials are also used by other
commands that can be run prior to `opentf init`. Only the default search
commands that can be run prior to `tofu init`. Only the default search
locations are supported.

10
website/docs/internals/debugging.mdx
View File

@@ -1,13 +1,13 @@
---
description: >-
OpenTF has detailed logs which can be enabled by setting the TF_LOG
OpenTofu has detailed logs which can be enabled by setting the TF_LOG
environment variable to any value. This will cause detailed logs to appear on
stderr
---
# Debugging OpenTF
# Debugging OpenTofu
OpenTF has detailed logs that you can enable by setting the `TF_LOG` environment variable to any value. Enabling this setting causes detailed logs to appear on `stderr`.
OpenTofu has detailed logs that you can enable by setting the `TF_LOG` environment variable to any value. Enabling this setting causes detailed logs to appear on `stderr`.
You can set `TF_LOG` to one of the log levels (in order of decreasing verbosity) `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR` to change the verbosity of the logs.
@@ -17,10 +17,10 @@ Setting `TF_LOG` to `JSON` outputs logs at the `TRACE` level or higher, and uses
The JSON encoding of log files is not considered a stable interface. It may change at any time, without warning. It is meant to support tooling that will be forthcoming, and that tooling is the only supported way to interact with JSON formatted logs.
:::
Logging can be enabled separately for opentf itself and the provider plugins
Logging can be enabled separately for tofu itself and the provider plugins
using the `TF_LOG_CORE` or `TF_LOG_PROVIDER` environment variables. These take
the same level arguments as `TF_LOG`, but only activate a subset of the logs.
To persist logged output you can set `TF_LOG_PATH` in order to force the log to always be appended to a specific file when logging is enabled. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled.
If you find a bug with OpenTF, please include the detailed log by using a service such as gist.
If you find a bug with OpenTofu, please include the detailed log by using a service such as gist.

12
website/docs/internals/functions-meta.mdx
View File

@@ -1,16 +1,16 @@
---
description: >-
The `opentf metadata functions` command prints signatures for all the
functions available in the current OpenTF version.
The `tofu metadata functions` command prints signatures for all the
functions available in the current OpenTofu version.
---
# Functions Metadata
The `opentf metadata functions` command is used to print signatures for the functions available in the current OpenTF version.
The `tofu metadata functions` command is used to print signatures for the functions available in the current OpenTofu version.
## Usage
Usage: `opentf metadata functions [options]`
Usage: `tofu metadata functions [options]`
The following flags are available:
@@ -29,7 +29,7 @@ value `"1.0"`. The semantics of this version are:
version.
We will introduce new major versions only within the bounds of
[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
[the OpenTofu 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
## Format Summary
@@ -39,7 +39,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:
- [Function Signature Representation](#function-signature-representation) - the top-level object returned by `opentf metadata functions -json`
- [Function Signature Representation](#function-signature-representation) - the top-level object returned by `tofu metadata functions -json`
- [Parameter Representation](#parameter-representation) - a sub-object of signatures that describes their parameters
## Function Signature Representation

22
website/docs/internals/graph.mdx
View File

@@ -1,6 +1,6 @@
---
description: >-
OpenTF builds a dependency graph from the OpenTF configurations, and
OpenTofu builds a dependency graph from the OpenTofu configurations, and
walks this graph to generate plans, refresh state, and more. This page
documents the details of what are contained in this graph, what types of nodes
there are, and how the edges of the graph are determined.
@@ -8,23 +8,23 @@ description: >-
# Resource Graph
OpenTF builds a
OpenTofu builds a
[dependency graph](https://en.wikipedia.org/wiki/Dependency_graph)
from the OpenTF configurations, and walks this graph to
from the OpenTofu configurations, and walks this graph to
generate plans, refresh state, and more. This page documents
the details of what are contained in this graph, what types
of nodes there are, and how the edges of the graph are determined.
:::warning Advanced Topic!
This page covers technical details
of OpenTF. You don't need to understand these details to
effectively use OpenTF. The details are documented here for
of OpenTofu. You don't need to understand these details to
effectively use OpenTofu. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code.
:::
For some background on graph theory, and a summary of how
OpenTF applies it, see the HashiCorp 2016 presentation
OpenTofu applies it, see the HashiCorp 2016 presentation
[_Applying Graph Theory to Infrastructure as Code_](https://www.youtube.com/watch?v=Ce3RNfRbdZ0).
This presentation also covers some similar ideas to the following
guide.
@@ -50,7 +50,7 @@ determined and built:
node is only present for resources that have a `count`
parameter greater than 1.
When visualizing a configuration with `opentf graph`, you can
When visualizing a configuration with `tofu graph`, you can
see all of these nodes present.
## Building the Graph
@@ -109,16 +109,16 @@ dependencies are walked.
The amount of parallelism is limited using a semaphore to prevent too many
concurrent operations from overwhelming the resources of the machine running
OpenTF. By default, up to 10 nodes in the graph will be processed
OpenTofu. By default, up to 10 nodes in the graph will be processed
concurrently. This number can be set using the `-parallelism` flag on the
[plan](/docs/cli/commands/plan), [apply](/docs/cli/commands/apply), and
[destroy](/docs/cli/commands/destroy) commands.
Setting `-parallelism` is considered an advanced operation and should not be
necessary for normal usage of OpenTF. It may be helpful in certain special
use cases or to help debug OpenTF issues.
necessary for normal usage of OpenTofu. It may be helpful in certain special
use cases or to help debug OpenTofu issues.
Note that some providers (AWS, for example), handle API rate limiting issues at
a lower level by implementing graceful backoff/retry in their respective API
clients. For this reason, OpenTF does not use this `parallelism` feature to
clients. For this reason, OpenTofu does not use this `parallelism` feature to
address API rate limits directly.

16
website/docs/internals/index.mdx
View File

@@ -1,19 +1,19 @@
---
sidebar_position: 1
description: >-
Learn how OpenTF generates the resource dependency graph and executes other internal processes.
Learn how OpenTofu generates the resource dependency graph and executes other internal processes.
---
# OpenTF Internals
# OpenTofu Internals
This section covers the internals of OpenTF and explains how
This section covers the internals of OpenTofu and explains how
plans are generated, the lifecycle of a provider, etc. The goal
of this section is to remove any notion of "magic" from OpenTF.
We want you to be able to trust and understand what OpenTF is
of this section is to remove any notion of "magic" from OpenTofu.
We want you to be able to trust and understand what OpenTofu is
doing to function.
:::note
Knowledge of OpenTF internals is not
required to use OpenTF. If you aren't interested in the internals
of OpenTF, you may safely skip this section.
Knowledge of OpenTofu internals is not
required to use OpenTofu. If you aren't interested in the internals
of OpenTofu, you may safely skip this section.
:::

64
website/docs/internals/json-format.mdx
View File

@@ -1,16 +1,16 @@
---
description: >-
OpenTF provides a machine-readable JSON representation of state,
OpenTofu provides a machine-readable JSON representation of state,
configuration and plan.
---
# JSON Output Format
When OpenTF plans to make changes, it prints a human-readable summary to the terminal. It can also, when run with `-out=<PATH>`, write a much more detailed binary plan file, which can later be used to apply those changes.
When OpenTofu plans to make changes, it prints a human-readable summary to the terminal. It can also, when run with `-out=<PATH>`, write a much more detailed binary plan file, which can later be used to apply those changes.
Since the format of plan files isn't suited for use with external tools (and likely never will be), OpenTF can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility.
Since the format of plan files isn't suited for use with external tools (and likely never will be), OpenTofu can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility.
Use `opentf show -json <FILE>` to generate a JSON representation of a plan or state file. See [the `opentf show` documentation](/docs/cli/commands/show) for more details.
Use `tofu show -json <FILE>` to generate a JSON representation of a plan or state file. See [the `tofu show` documentation](/docs/cli/commands/show) for more details.
The output includes a `format_version` key, which has
value `"1.0"`. The semantics of this version are:
@@ -23,7 +23,7 @@ value `"1.0"`. The semantics of this version are:
version.
We will introduce new major versions only within the bounds of
[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
[the OpenTofu 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
## Format Summary
@@ -35,10 +35,10 @@ 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:
- [State Representation](#state-representation) — The complete top-level object returned by `opentf show -json <STATE FILE>`.
- [Plan Representation](#plan-representation) — The complete top-level object returned by `opentf show -json <PLAN FILE>`.
- [State Representation](#state-representation) — The complete top-level object returned by `tofu show -json <STATE FILE>`.
- [Plan Representation](#plan-representation) — The complete top-level object returned by `tofu show -json <PLAN FILE>`.
- [Values Representation](#values-representation) — A sub-object of both plan and state output that describes current state or planned state.
- [Configuration Representation](#configuration-representation) — A sub-object of plan output that describes a parsed OpenTF configuration.
- [Configuration Representation](#configuration-representation) — A sub-object of plan output that describes a parsed OpenTofu configuration.
- [Expression Representation](#expression-representation) — A sub-object of a configuration representation that describes an unevaluated expression.
- [Block Expressions Representation](#block-expressions-representation) — A sub-object of a configuration representation that describes the expressions nested inside a block.
- [Change Representation](#change-representation) — A sub-object of plan output that describes changes to an object.
@@ -54,14 +54,14 @@ State does not have any significant metadata not included in the common [values
// state. Because the state is always fully known, this is always complete.
"values": <values-representation>
// The key here is left unchanged in OpenTF for compatibility reasons.
// The key here is left unchanged in OpenTofu for compatibility reasons.
"terraform_version": "version.string"
}
```
## Plan Representation
A plan consists of a prior state, the configuration that is being applied to that state, and the set of changes OpenTF plans to make to achieve that.
A plan consists of a prior state, the configuration that is being applied to that state, and the set of changes OpenTofu plans to make to achieve that.
For ease of consumption by callers, the plan representation includes a partial representation of the values in the final state (using a [value representation](#values-representation)), allowing callers to easily analyze the planned outcome using similar code as for analyzing the prior state.
@@ -96,7 +96,7 @@ For ease of consumption by callers, the plan representation includes a partial r
},
// "resource_changes" is a description of the individual change actions that
// OpenTF plans to use to move from the prior state to a new state
// OpenTofu plans to use to move from the prior state to a new state
// matching the configuration.
"resource_changes": [
// Each element of this array describes the action to take
@@ -109,7 +109,7 @@ For ease of consumption by callers, the plan representation includes a partial r
"address": "module.child.aws_instance.foo[0]",
// "previous_address" is the full absolute address of this resource
// instance as it was known after the previous OpenTF run.
// instance as it was known after the previous OpenTofu run.
// Included only if the address has changed, e.g. by handling
// a "moved" block in the configuration.
"previous_address": "module.instances.aws_instance.foo[0]",
@@ -149,14 +149,14 @@ For ease of consumption by callers, the plan representation includes a partial r
//
// The current set of possible values is:
// - "replace_because_tainted": the object in question is marked as
// "tainted" in the prior state, so OpenTF planned to replace it.
// "tainted" in the prior state, so OpenTofu planned to replace it.
// - "replace_because_cannot_update": the provider indicated that one
// of the requested changes isn't possible without replacing the
// existing object with a new object.
// - "replace_by_request": the user explicitly called for this object
// to be replaced as an option when creating the plan, which therefore
// overrode what would have been a "no-op" or "update" action otherwise.
// - "delete_because_no_resource_config": OpenTF found no resource
// - "delete_because_no_resource_config": OpenTofu found no resource
// configuration corresponding to this instance.
// - "delete_because_no_module": The resource instance belongs to a
// module instance that's no longer declared, perhaps due to changing
@@ -170,21 +170,21 @@ For ease of consumption by callers, the plan representation includes a partial r
// - "delete_because_each_key": The corresponding resource uses for_each,
// but the instance key doesn't match any of the keys in the
// currently-configured for_each value.
// - "read_because_config_unknown": For a data resource, OpenTF cannot
// - "read_because_config_unknown": For a data resource, OpenTofu cannot
// read the data during the plan phase because of values in the
// configuration that won't be known until the apply phase.
// - "read_because_dependency_pending": For a data resource, OpenTF
// - "read_because_dependency_pending": For a data resource, OpenTofu
// cannot read the data during the plan phase because the data
// resource depends on at least one managed resource that also has
// a pending change in the same plan.
//
// If there is no special reason to note, OpenTF will omit this
// If there is no special reason to note, OpenTofu will omit this
// property altogether.
action_reason: "replace_because_tainted"
}
],
// "resource_drift" is a description of the changes OpenTF detected
// "resource_drift" is a description of the changes OpenTofu detected
// when it compared the most recent state to the prior saved state.
"resource_drift": [
{
@@ -216,7 +216,7 @@ For ease of consumption by callers, the plan representation includes a partial r
// ["create"]
// ["update"]
// ["delete"]
// OpenTF is not yet fully able to
// OpenTofu is not yet fully able to
// track changes to output values, so the actions indicated may not be
// fully accurate, but the "after" value will always be correct.
"change": <change-representation>,
@@ -224,7 +224,7 @@ For ease of consumption by callers, the plan representation includes a partial r
},
// "checks" describes the partial results for any checkable objects, such as
// resources with postconditions, with as much information as OpenTF can
// resources with postconditions, with as much information as OpenTofu can
// recognize at plan time. Some objects will have status "unknown" to
// indicate that their status will only be determined after applying the plan.
"checks" <checks-representation>,
@@ -235,7 +235,7 @@ For ease of consumption by callers, the plan representation includes a partial r
}
```
This overall plan structure, fully expanded, is what will be printed by the `opentf show -json <planfile>` command.
This overall plan structure, fully expanded, is what will be printed by the `tofu show -json <planfile>` command.
## Values Representation
@@ -262,7 +262,7 @@ The following example illustrates the structure of a `<values-representation>`:
{
// "address" is the absolute resource address, which callers must consider
// opaque but may do full string comparisons with other address strings or
// pass this verbatim to other OpenTF commands that are documented to
// pass this verbatim to other OpenTofu commands that are documented to
// accept absolute resource addresses. The module-local portions of this
// address are extracted in other properties below.
"address": "aws_instance.example[1]",
@@ -318,7 +318,7 @@ The following example illustrates the structure of a `<values-representation>`:
{
// "address" is the absolute module address, which callers must treat as
// opaque but may do full string comparisons with other module address
// strings and may pass verbatim to other OpenTF commands that are
// strings and may pass verbatim to other OpenTofu commands that are
// documented as accepting absolute module addresses.
"address": "module.child",
@@ -340,7 +340,7 @@ The following example illustrates the structure of a `<values-representation>`:
}
```
The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by OpenTF's [`jsonencode`](/docs/language/functions/jsonencode) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null.
The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by OpenTofu's [`jsonencode`](/docs/language/functions/jsonencode) function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null.
Output values include a `"type"` field, which is a [serialization of the value's type](https://pkg.go.dev/github.com/zclconf/go-cty/cty#Type.MarshalJSON). For primitive types this is a string value, such as `"number"` or `"bool"`. Complex types are represented as a nested JSON array, such as `["map","string"]` or `["object",{"a":"number"}]`. This can be used to reconstruct the output value with the correct type.
@@ -350,7 +350,7 @@ The intent of this structure is to give a caller access to a similar level of de
## Configuration Representation
Configuration is the most complicated structure in OpenTF, since it includes unevaluated expression nodes and other complexities.
Configuration is the most complicated structure in OpenTofu, since it includes unevaluated expression nodes and other complexities.
Because the configuration models are produced at a stage prior to expression evaluation, it is not possible to produce a values representation for configuration. Instead, we describe the physical structure of the configuration, giving access to constant values where possible and allowing callers to analyze any references to other objects that are present:
@@ -358,7 +358,7 @@ Because the configuration models are produced at a stage prior to expression eva
{
// "provider_configs" describes all of the provider configurations throughout
// the configuration tree, flattened into a single map for convenience since
// provider configurations are the one concept in OpenTF that can span
// provider configurations are the one concept in OpenTofu that can span
// across module boundaries.
"provider_config": {
@@ -517,7 +517,7 @@ Each unevaluated expression in the configuration is represented with an `<expres
"var.example", // implied by the previous
// Partial references like "data" and "module" are not included, because
// OpenTF considers "module.foo" to be an atomic reference, not an
// OpenTofu considers "module.foo" to be an atomic reference, not an
// attribute access.
]
}
@@ -618,8 +618,8 @@ A `<change-representation>` describes the change to the indicated object.
:::warning
The JSON representation of checks is experimental
and some details may change in future OpenTF versions based on feedback,
even in minor releases of OpenTF CLI.
and some details may change in future OpenTofu versions based on feedback,
even in minor releases of OpenTofu CLI.
:::
A `<checks-representation>` describes the current state of a checkable object in the configuration. For example, a resource with one or more preconditions or postconditions is an example of a checkable object, and its check state represents the results of those conditions.
@@ -713,7 +713,7 @@ A `<checks-representation>` describes the current state of a checkable object in
// "problems" might be included for statuses "fail" or "error", in
// which case it describes the individual conditions that failed for
// this instance, if any.
// When a condition expression is invalid, OpenTF returns that as
// When a condition expression is invalid, OpenTofu returns that as
// a normal error message rather than as a problem in this list.
"problems": [
{
@@ -733,7 +733,7 @@ those objects to ensure that the set of checkable objects will be consistent
even if an error prevents full evaluation of the configuration. Any object
in the configuration which has associated checks, such as a resource with
preconditions or postconditions, will always be included as a checkable object
even if a runtime error prevents OpenTF from evaluating its "count" or
even if a runtime error prevents OpenTofu from evaluating its "count" or
"for_each" argument and therefore determining which instances of that object
exist dynamically.
@@ -741,5 +741,5 @@ When summarizing checks in a UI, we recommend preferring to list only the
individual instances and typically ignoring the top-level objects altogether.
However, in any case where an object has _zero_ instances, the UI should show
the top-level object instead to serve as a placeholder so that the user can
see that OpenTF recognized the existence of the checks, even if it wasn't
see that OpenTofu recognized the existence of the checks, even if it wasn't
able to evaluate them on the most recent run.

42
website/docs/internals/login-protocol.mdx
View File

@@ -1,25 +1,25 @@
---
description: >-
The login protocol is used for authenticating OpenTF against servers
providing OpenTF-native services.
The login protocol is used for authenticating OpenTofu against servers
providing OpenTofu-native services.
---
# Server-side Login Protocol
:::warning Note
You don't need to read these docs to _use_
[`opentf login`](/docs/cli/commands/login). The information below is for
anyone intending to implement the server side of `opentf login` in order to
offer OpenTF-native services in a third-party system.
[`tofu login`](/docs/cli/commands/login). The information below is for
anyone intending to implement the server side of `tofu login` in order to
offer OpenTofu-native services in a third-party system.
:::
The `opentf login` command supports performing an OAuth 2.0 authorization
The `tofu login` command supports performing an OAuth 2.0 authorization
request using configuration provided by the target host. You may wish to
implement this protocol if you are producing a third-party implementation of
any [OpenTF-native services](/docs/internals/remote-service-discovery),
such as an OpenTF module registry.
any [OpenTofu-native services](/docs/internals/remote-service-discovery),
such as an OpenTofu module registry.
First, OpenTF uses
First, OpenTofu uses
[remote service discovery](/docs/internals/remote-service-discovery) to
find the OAuth configuration for the host. The host must support the service
name `login.v1` and define for it an object containing OAuth client
@@ -28,7 +28,7 @@ configuration values, like this:
```json
{
"login.v1": {
"client": "opentf-cli",
"client": "tofu-cli",
"grant_types": ["authz_code"],
"authz": "/oauth/authorization",
"token": "/oauth/token",
@@ -42,17 +42,17 @@ The properties within the discovery object are as follows:
* `client` (Required): The `client_id` value to use when making requests, as
defined in [RFC 6749 section 2.2](https://tools.ietf.org/html/rfc6749#section-2.2).
Because OpenTF is a _public client_ (it is installed on end-user systems
Because OpenTofu is a _public client_ (it is installed on end-user systems
and thus cannot protect an OAuth client secret), the `client_id` is purely
advisory and the server must not use it as a guarantee that an authorization
request is truly coming from OpenTF.
request is truly coming from OpenTofu.
* `grant_types` (Optional): A JSON array of strings describing a set of OAuth
2.0 grant types the server is able to support. A "grant type" selects a
specific mechanism by which an OAuth server authenticates the request and
issues an authorization token.
OpenTF CLI supports a single grant type:
OpenTofu CLI supports a single grant type:
* `authz_code`: [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1).
Both the `authz` and `token` properties are required when `authz_code` is
@@ -71,16 +71,16 @@ The properties within the discovery object are as follows:
service discovery document.
* `ports` (Optional): A two-element JSON array giving an inclusive range of
TCP ports that OpenTF may use for the temporary HTTP server it will start
TCP ports that OpenTofu may use for the temporary HTTP server it will start
to provide the [redirection endpoint](https://tools.ietf.org/html/rfc6749#section-3.1.2)
for the first step of an authorization code grant. OpenTF opens a TCP
for the first step of an authorization code grant. OpenTofu opens a TCP
listen port on the loopback interface in order to receive the response from
the server's authorization endpoint.
If not specified, OpenTF is free to select any TCP port greater than or
If not specified, OpenTofu is free to select any TCP port greater than or
equal to 1024.
OpenTF allows constraining this port range for interoperability with OAuth
OpenTofu allows constraining this port range for interoperability with OAuth
server implementations that require each `client_id` to be associated with
a fixed set of valid redirection endpoint URLs. Configure such a server
to expect a range of URLs of the form `http://localhost:10000/`
@@ -92,14 +92,14 @@ The properties within the discovery object are as follows:
risk that all of the possible ports will already be in use on a particular
system.
When requesting an authorization code grant, OpenTF CLI implements the
When requesting an authorization code grant, OpenTofu CLI implements the
[Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) extension in
order to protect against other applications on the system intercepting the
incoming request to the redirection endpoint. We strongly recommend that you
select an OAuth server implementation that also implements this extension and
verifies the code challenge sent to the token endpoint.
OpenTF CLI does not support OAuth refresh tokens or token expiration. If your
server issues time-limited tokens, OpenTF CLI will simply begin receiving
OpenTofu CLI does not support OAuth refresh tokens or token expiration. If your
server issues time-limited tokens, OpenTofu CLI will simply begin receiving
authorization errors once the token expires, after which the user can run
`opentf login` again to obtain a new token.
`tofu login` again to obtain a new token.

76
website/docs/internals/machine-readable-ui.mdx
View File

@@ -1,12 +1,12 @@
---
description: >-
OpenTF provides a machine-readable streaming JSON UI output for plan,
OpenTofu provides a machine-readable streaming JSON UI output for plan,
apply, and refresh operations.
---
# Machine-Readable UI
By default, many OpenTF commands display UI output as unstructured text, intended to be read by a user via a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface.
By default, many OpenTofu commands display UI output as unstructured text, intended to be read by a user via a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface.
For long-running commands such as `plan`, `apply`, and `refresh`, the `-json` flag outputs a stream of JSON UI messages, one per line. These can be processed one message at a time, with integrating software filtering, combining, or modifying the output as desired.
@@ -21,33 +21,33 @@ value `"1.0"`. The semantics of this version are:
version.
We will introduce new major versions only within the bounds of
[the OpenTF 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
[the OpenTofu 1.0 Compatibility Promises](/docs/language/v1-compatibility-promises).
## Sample JSON Output
Below is sample output from running `opentf apply -json`:
Below is sample output from running `tofu apply -json`:
```javascript
{"@level":"info","@message":"OpenTF 1.6.0","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.275359-04:00","opentf":"0.15.4","type":"version","ui":"0.1.0"}
{"@level":"info","@message":"random_pet.animal: Plan to create","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.705503-04:00","change":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"planned_change"}
{"@level":"info","@message":"Plan: 1 to add, 0 to change, 0 to destroy.","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.705638-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"plan"},"type":"change_summary"}
{"@level":"info","@message":"random_pet.animal: Creating...","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.825308-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"apply_start"}
{"@level":"info","@message":"random_pet.animal: Creation complete after 0s [id=smart-lizard]","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.826179-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create","id_key":"id","id_value":"smart-lizard","elapsed_seconds":0},"type":"apply_complete"}
{"@level":"info","@message":"Apply complete! Resources: 1 added, 0 changed, 0 destroyed.","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.869168-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"apply"},"type":"change_summary"}
{"@level":"info","@message":"Outputs: 1","@module":"opentf.ui","@timestamp":"2021-05-25T13:32:41.869280-04:00","outputs":{"pets":{"sensitive":false,"type":"string","value":"smart-lizard"}},"type":"outputs"}
{"@level":"info","@message":"OpenTofu 1.6.0","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.275359-04:00","tofu":"0.15.4","type":"version","ui":"0.1.0"}
{"@level":"info","@message":"random_pet.animal: Plan to create","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.705503-04:00","change":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"planned_change"}
{"@level":"info","@message":"Plan: 1 to add, 0 to change, 0 to destroy.","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.705638-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"plan"},"type":"change_summary"}
{"@level":"info","@message":"random_pet.animal: Creating...","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.825308-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create"},"type":"apply_start"}
{"@level":"info","@message":"random_pet.animal: Creation complete after 0s [id=smart-lizard]","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.826179-04:00","hook":{"resource":{"addr":"random_pet.animal","module":"","resource":"random_pet.animal","implied_provider":"random","resource_type":"random_pet","resource_name":"animal","resource_key":null},"action":"create","id_key":"id","id_value":"smart-lizard","elapsed_seconds":0},"type":"apply_complete"}
{"@level":"info","@message":"Apply complete! Resources: 1 added, 0 changed, 0 destroyed.","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.869168-04:00","changes":{"add":1,"change":0,"remove":0,"operation":"apply"},"type":"change_summary"}
{"@level":"info","@message":"Outputs: 1","@module":"tofu.ui","@timestamp":"2021-05-25T13:32:41.869280-04:00","outputs":{"pets":{"sensitive":false,"type":"string","value":"smart-lizard"}},"type":"outputs"}
```
Each line consists of a JSON object with several keys common to all messages. These are:
- `@level`: this is normally "info", but can be "error" or "warn" when showing diagnostics
- `@message`: a human-readable summary of the contents of this message
- `@module`: always "opentf.ui" when rendering UI output
- `@module`: always "tofu.ui" when rendering UI output
- `@timestamp`: an RFC3339 timestamp of when the message was output
- `type`: defines which kind of message this is and determines how to interpret other keys which may be present
Clients presenting the logs as a user interface should handle unexpected message types by presenting at least the `@message` field to the user.
Messages will be emitted as events occur to trigger them. This means that messages related to several resources may be interleaved (if OpenTF is running with concurrency above 1). The [`resource` object value](#resource-object) can be used to link multiple messages about a single resource.
Messages will be emitted as events occur to trigger them. This means that messages related to several resources may be interleaved (if OpenTofu is running with concurrency above 1). The [`resource` object value](#resource-object) can be used to link multiple messages about a single resource.
## Message Types
@@ -55,13 +55,13 @@ The following message types are supported:
### Generic Messages
- `version`: information about the OpenTF version and the version of the schema used for the following messages
- `version`: information about the OpenTofu version and the version of the schema used for the following messages
- `log`: unstructured human-readable log lines
- `diagnostic`: diagnostic warning or error messages; [see the `opentf validate` docs for more details on the format](/docs/cli/commands/validate#json)
- `diagnostic`: diagnostic warning or error messages; [see the `tofu validate` docs for more details on the format](/docs/cli/commands/validate#json)
### Operation Results
- `resource_drift`: describes a detected change to a single resource made outside of OpenTF
- `resource_drift`: describes a detected change to a single resource made outside of OpenTofu
- `planned_change`: describes a planned change to a single resource
- `change_summary`: summary of all planned or applied changes
- `outputs`: list of all root module outputs
@@ -76,7 +76,7 @@ The following message types are supported:
A machine-readable UI command output will always begin with a `version` message. The following message-specific keys are defined:
- `opentf`: the OpenTF version which emitted this message
- `tofu`: the OpenTofu version which emitted this message
- `ui`: the machine-readable UI schema version defining the meaning of the following messages
### Example
@@ -84,10 +84,10 @@ A machine-readable UI command output will always begin with a `version` message.
```json
{
"@level": "info",
"@message": "OpenTF 0.15.4",
"@module": "opentf.ui",
"@message": "OpenTofu 0.15.4",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.275359-04:00",
"opentf": "0.15.4",
"tofu": "0.15.4",
"type": "version",
"ui": "0.1.0"
}
@@ -95,7 +95,7 @@ A machine-readable UI command output will always begin with a `version` message.
## Resource Drift
If drift is detected during planning, OpenTF will emit a `resource_drift` message for each resource which has changed outside of OpenTF. This message has an embedded `change` object with the following keys:
If drift is detected during planning, OpenTofu will emit a `resource_drift` message for each resource which has changed outside of OpenTofu. This message has an embedded `change` object with the following keys:
- `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details
- `action`: the action planned to be taken for the resource. Values: `update`, `delete`.
@@ -108,7 +108,7 @@ This message does not include details about the exact changes which caused the c
{
"@level": "info",
"@message": "random_pet.animal: Drift detected (update)",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.705503-04:00",
"change": {
"resource": {
@@ -128,7 +128,7 @@ This message does not include details about the exact changes which caused the c
## Planned Change
At the end of a plan or before an apply, OpenTF will emit a `planned_change` message for each resource which has changes to apply. This message has an embedded `change` object with the following keys:
At the end of a plan or before an apply, OpenTofu will emit a `planned_change` message for each resource which has changes to apply. This message has an embedded `change` object with the following keys:
- `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details
- `previous_resource`: object describing the previous address of the resource, if this change includes a configuration-driven move
@@ -151,7 +151,7 @@ This message does not include details about the exact changes which caused the c
{
"@level": "info",
"@message": "random_pet.animal: Plan to create",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.705503-04:00",
"change": {
"resource": {
@@ -171,7 +171,7 @@ This message does not include details about the exact changes which caused the c
## Change Summary
OpenTF outputs a change summary when a plan or apply operation completes. Both message types include a `changes` object, which has the following keys:
OpenTofu outputs a change summary when a plan or apply operation completes. Both message types include a `changes` object, which has the following keys:
- `add`: count of resources to be created (including as part of replacement)
- `change`: count of resources to be changed in-place
@@ -184,7 +184,7 @@ OpenTF outputs a change summary when a plan or apply operation completes. Both m
{
"@level": "info",
"@message": "Apply complete! Resources: 1 added, 0 changed, 0 destroyed.",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.869168-04:00",
"changes": {
"add": 1,
@@ -213,7 +213,7 @@ Note that `sensitive` outputs still include the `value` field, and integrating s
{
"@level": "info",
"@message": "Outputs: 1",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.869280-04:00",
"outputs": {
"pets": {
@@ -228,7 +228,7 @@ Note that `sensitive` outputs still include the `value` field, and integrating s
## Operation Messages
Performing OpenTF operations to a resource will often result in several messages being emitted. The message types include:
Performing OpenTofu operations to a resource will often result in several messages being emitted. The message types include:
- `apply_start`: when starting to apply changes for a resource
- `apply_progress`: periodically, showing elapsed time output
@@ -257,7 +257,7 @@ The `apply_start` message `hook` object has the following keys:
{
"@level": "info",
"@message": "random_pet.animal: Creating...",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.825308-04:00",
"hook": {
"resource": {
@@ -289,7 +289,7 @@ The `apply_progress` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[4]: Still creating... [30s elapsed]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-17T09:34:26.222465-04:00",
"hook": {
"resource": {
@@ -323,7 +323,7 @@ The `apply_complete` message `hook` object has the following keys:
{
"@level": "info",
"@message": "random_pet.animal: Creation complete after 0s [id=smart-lizard]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-05-25T13:32:41.826179-04:00",
"hook": {
"resource": {
@@ -360,7 +360,7 @@ The exact detail of the error will be rendered as a separate `diagnostic` messag
{
"@level": "info",
"@message": "null_resource.none[0]: Creation errored after 10s",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:54.013910-04:00",
"hook": {
"resource": {
@@ -392,7 +392,7 @@ The `provision_start` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: Provisioning with 'local-exec'...",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:43.997431-04:00",
"hook": {
"resource": {
@@ -426,7 +426,7 @@ One `provision_progress` message is output for each log line received from the p
{
"@level": "info",
"@message": "null_resource.none[0]: (local-exec): Executing: [\"/bin/sh\" \"-c\" \"sleep 10 && exit 1\"]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:43.997869-04:00",
"hook": {
"resource": {
@@ -458,7 +458,7 @@ The `provision_complete` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: (local-exec) Provisioning complete",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-17T09:34:06.239043-04:00",
"hook": {
"resource": {
@@ -489,7 +489,7 @@ The `provision_errored` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: (local-exec) Provisioning errored",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T16:38:54.013572-04:00",
"hook": {
"resource": {
@@ -520,7 +520,7 @@ The `refresh_start` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: Refreshing state... [id=1971614370559474622]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T14:18:06.508915-04:00",
"hook": {
"resource": {
@@ -552,7 +552,7 @@ The `refresh_complete` message `hook` object has the following keys:
{
"@level": "info",
"@message": "null_resource.none[0]: Refresh complete [id=1971614370559474622]",
"@module": "opentf.ui",
"@module": "tofu.ui",
"@timestamp": "2021-03-26T14:18:06.509371-04:00",
"hook": {
"resource": {

30
website/docs/internals/module-registry-protocol.mdx
View File

@@ -1,13 +1,13 @@
---
description: |-
The module registry protocol is implemented by a host intending to be the
host of one or more OpenTF modules, specifying which modules are available
host of one or more OpenTofu modules, specifying which modules are available
and where to find their distribution packages.
---
# Module Registry Protocol
The module registry protocol is what OpenTF CLI uses to discover metadata
The module registry protocol is what OpenTofu CLI uses to discover metadata
about modules available for installation and to locate the distribution
package for a selected module.
@@ -20,13 +20,13 @@ publishing them on the public Terraform Registry.
The public Terraform Registry implements a superset of the API described on
this page, in order to capture additional information used in the registry UI.
For information on those extensions, see
[OpenTF Registry HTTP API](/docs/registry/api-docs). Third-party registry
[OpenTofu Registry HTTP API](/docs/registry/api-docs). Third-party registry
implementations may choose to implement those extensions if desired, but
OpenTF CLI itself does not use them.
OpenTofu CLI itself does not use them.
## Module Addresses
Each OpenTF module has an associated address. A module address has the
Each OpenTofu module has an associated address. A module address has the
syntax `hostname/namespace/name/system`, where:
- `hostname` is the hostname of the module registry that serves this module.
@@ -58,7 +58,7 @@ For example:
- `example.com/awesomecorp/consul/happycloud` is a hypothetical module published
on a third-party registry.
If you intend to share a module you've developed for use by all OpenTF
If you intend to share a module you've developed for use by all OpenTofu
users, please consider publishing it into the public
[Terraform Registry](https://registry.terraform.io/) to make your module more
discoverable. You only need to implement this module registry protocol if you
@@ -68,7 +68,7 @@ under your control.
## Module Versions
Each distinct module address has associated with it a set of versions, each
of which has an associated version number. OpenTF assumes version numbers
of which has an associated version number. OpenTofu assumes version numbers
follow the [Semantic Versioning 2.0](https://semver.org/) conventions, with
the user-facing behavior of the module serving as the "public API".
@@ -77,8 +77,8 @@ blocks have the same source address.
## Service Discovery
The module registry protocol begins with OpenTF CLI using
[OpenTF's remote service discovery protocol](/docs/internals/remote-service-discovery),
The module registry protocol begins with OpenTofu CLI using
[OpenTofu's remote service discovery protocol](/docs/internals/remote-service-discovery),
with the hostname in the module address acting as the "User-facing Hostname".
The service identifier for the module registry protocol is `modules.v1`.
@@ -90,18 +90,18 @@ the module registry protocol might contain the following:
```json
{
"modules.v1": "/opentf/modules/v1/"
"modules.v1": "/tofu/modules/v1/"
}
```
If the given URL is a relative URL then OpenTF will interpret it as relative
If the given URL is a relative URL then OpenTofu will interpret it as relative
to the discovery document itself. The specific module registry protocol
endpoints are defined as URLs relative to the given base URL, and so the
specified base URL should generally end with a slash to ensure that those
relative paths will be resolved as expected.
The following sections describe the various operations that a module
registry must implement to be compatible with OpenTF CLI's module
registry must implement to be compatible with OpenTofu CLI's module
installer. The indicated URLs are all relative to the URL resulting from
service discovery, as described above. We use a hypothetical URL for a provider
registry, assuming that the caller already performed service discovery on a hypothetical
@@ -144,9 +144,9 @@ $ curl 'https://registry.example.io/v1/modules/hashicorp/consul/aws/versions'
The `modules` array in the response always includes the requested module as the
first element.
OpenTF does not use the other elements of this list. However, third-party implementations should always use a single-element list for forward compatiblity.
OpenTofu does not use the other elements of this list. However, third-party implementations should always use a single-element list for forward compatiblity.
Each returned module has an array of available versions, which OpenTF
Each returned module has an array of available versions, which OpenTofu
matches against any version constraints given in configuration.
```json
@@ -205,7 +205,7 @@ X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tar
A successful response has no body, and includes the location from which the
module version's source can be downloaded in the `X-Terraform-Get` header.
The value of this header accepts the same values as the `source` argument
in a `module` block in OpenTF configuration, as described in
in a `module` block in OpenTofu configuration, as described in
[Module Sources](/docs/language/modules/sources),
except that it may not recursively refer to another module registry address.

12
website/docs/internals/provider-meta.mdx
View File

@@ -24,8 +24,8 @@ rather than the module developer.
:::warning Advanced Topic!
This page covers technical details
of OpenTF. You don't need to understand these details to
effectively use OpenTF. The details are documented here for
of OpenTofu. You don't need to understand these details to
effectively use OpenTofu. The details are documented here for
module authors and provider developers working on advanced
functionality.
:::
@@ -33,7 +33,7 @@ functionality.
:::warning Experimental Feature!
This functionality is still considered
experimental, and anyone taking advantage of it should [coordinate
with the OpenTF team](https://github.com/opentofu/opentofu/issues/new)
with the OpenTofu team](https://github.com/opentofu/opentofu/issues/new)
to help the team understand how the feature is being used and to make
sure their use case is taken into account as the feature develops.
:::
@@ -48,7 +48,7 @@ functions similarly to the provider config: a map of strings to the
## Using the Data
When OpenTF calls your provider, you can use the `schema.ResourceData`
When OpenTofu calls your provider, you can use the `schema.ResourceData`
that your `Create`, `Read`, and `Update` functions already use to get
access to the provider metadata being passed. First define a struct
that matches your schema, then call the `GetProviderSchema` method on
@@ -76,9 +76,9 @@ The `provider_meta` block must match the schema the provider has defined.
Any module taking advantage of this functionality must make sure that the
provider metadata supplied matches the schema defined in the provider, and
that the version of OpenTF that is being run has support for the provider
that the version of OpenTofu that is being run has support for the provider
metadata functionality. It's therefore recommended that any module taking
advantage of this functionality should specify a minimum OpenTF version of
advantage of this functionality should specify a minimum OpenTofu version of
0.13.0 or higher, and a minimum version of each of the providers it specifies
metadata as the first version the schema being used was supported by the
provider.

66
website/docs/internals/provider-network-mirror-protocol.mdx
View File

@@ -1,7 +1,7 @@
---
description: |-
The provider network mirror protocol is implemented by a server intending
to provide a mirror or read-through caching proxy for OpenTF providers,
to provide a mirror or read-through caching proxy for OpenTofu providers,
as an alternative distribution source from the provider's origin provider
registry.
---
@@ -12,15 +12,15 @@ The provider network mirror protocol is an optional protocol which you can
implement to provide an alternative installation source for Terraform providers,
regardless of their origin registries.
OpenTF uses network mirrors only if you activate them explicitly in
OpenTofu uses network mirrors only if you activate them explicitly in
[the CLI configuration's `provider_installation` block](/docs/cli/config/config-file#provider-installation).
When enabled, a network mirror can serve providers belonging to any registry
hostname, which can allow an organization to serve all of the OpenTF
hostname, which can allow an organization to serve all of the OpenTofu
providers they intend to use from an internal server, rather than from each
provider's origin registry.
This is _not_ the protocol that should be implemented by a host intending to
serve as an origin registry for OpenTF Providers. To provide an origin
serve as an origin registry for OpenTofu Providers. To provide an origin
registry (whose hostname would then be included in the source addresses of the
providers it hosts), implement
[the provider registry protocol](/docs/internals/provider-registry-protocol)
@@ -28,14 +28,14 @@ instead.
## Provider Addresses
Each OpenTF provider has an associated address which uniquely identifies it
within OpenTF. A provider address has the syntax `hostname/namespace/type`,
Each OpenTofu provider has an associated address which uniquely identifies it
within OpenTofu. A provider address has the syntax `hostname/namespace/type`,
which is described in more detail in
[the Provider Requirements documentation](/docs/language/providers/requirements).
By default, the `hostname` portion of a provider address serves both as part
of its unique identifier _and_ as the location of the registry to retrieve it
from. However, when you configure OpenTF to install providers from a network
from. However, when you configure OpenTofu to install providers from a network
mirror, the `hostname` serves _only_ as an identifier and no longer as
an installation source. A provider mirror can therefore serve providers
belonging to a variety of different provider registry hostnames, including
@@ -48,13 +48,13 @@ the hostname where the provider network mirror is deployed.
## Protocol Base URL
Most OpenTF-native services use
Most OpenTofu-native services use
[the remote service discovery protocol](/docs/internals/remote-service-discovery) so
that the physical location of the endpoints can potentially be separated from
the hostname used in identifiers. The Provider Network Mirror protocol does
_not_ use the service discovery indirection, because a network mirror location
is only a physical location and is never used as part of the identifier of a
dependency in a OpenTF configuration.
dependency in a OpenTofu configuration.
Instead, the provider installation section of the CLI configuration accepts
a base URL directly. The given URL must use the scheme `https:`, and should
@@ -64,18 +64,18 @@ endpoints will be resolved beneath it.
```hcl
provider_installation {
network_mirror {
url = "https://opentf.example.com/providers/"
url = "https://tofu.example.com/providers/"
}
}
```
OpenTF uses the base URL only as a stem to resolve the operation endpoint
OpenTofu uses the base URL only as a stem to resolve the operation endpoint
URLs against, and so it will never access the base URL directly. You can
therefore, if desired, publish human-readable usage documentation for your
network mirror at that URL.
The following sections describe the various operations that a provider
network mirror server must implement to be compatible with OpenTF CLI's
network mirror server must implement to be compatible with OpenTofu CLI's
provider installer. The indicated URLs are all relative to the given base URL,
as described above.
@@ -92,14 +92,14 @@ base URL from the above CLI configuration example.
If the CLI configuration includes
[credentials](/docs/cli/config/config-file#credentials) for the hostname
given in the network mirror base URL, OpenTF will include those credentials
given in the network mirror base URL, OpenTofu will include those credentials
in its requests for operations described below.
If the given URL uses a non-standard port number (other than 443) then the
credentials must be associated with a hostname that includes the port number,
such as `opentf.example.com:8443`.
such as `tofu.example.com:8443`.
OpenTF does _not_ send credentials when retrieving the archives whose
OpenTofu does _not_ send credentials when retrieving the archives whose
URLs are given in the "List Available Installation Packages" response below.
If a particular mirror considers the distribution packages themselves to be
sensitive then it must use cryptographically-secure, user-specific, and
@@ -126,7 +126,7 @@ particular provider.
### Sample Request
```
curl 'https://opentf.example.com/providers/registry.opentf.io/hashicorp/random/index.json'
curl 'https://tofu.example.com/providers/registry.tofu.io/hashicorp/random/index.json'
```
### Sample Response
@@ -159,9 +159,9 @@ distribution packages for a particular version of a provider.
Each distribution package is associated with a particular operating system
and architecture. A network mirror may host only a subset of the available
packages for a provider version, if the users of the mirror are known to all
use only a subset of the target platforms that OpenTF supports.
use only a subset of the target platforms that OpenTofu supports.
OpenTF CLI uses this operation after it has selected the newest available
OpenTofu CLI uses this operation after it has selected the newest available
version matching the configured version constraints, in order to find a zip
archive containing the plugin itself.
@@ -183,7 +183,7 @@ archive containing the plugin itself.
### Sample Request
```
curl 'https://opentf.example.com/providers/registry.opentf.io/hashicorp/random/2.0.0.json'
curl 'https://tofu.example.com/providers/registry.tofu.io/hashicorp/random/2.0.0.json'
```
### Sample Response
@@ -219,31 +219,31 @@ with an underscore (`_`).
Each property value in the `archives` object is itself a nested object with
the following properties:
* `url` (required): a string specifying the URL from which OpenTF should
* `url` (required): a string specifying the URL from which OpenTofu should
download the `.zip` archive containing the requested provider plugin version.
OpenTF resolves the URL relative to the URL from which the current
OpenTofu resolves the URL relative to the URL from which the current
JSON document was returned, so the examples above containing only a
filename would cause OpenTF to construct a URL like:
filename would cause OpenTofu to construct a URL like:
```
https://opentf.example.com/providers/registry.terraform.io/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip
https://tofu.example.com/providers/registry.terraform.io/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip
```
* `hashes` (optional): a JSON array of strings containing one or more hash
values for the indicated archive. These hashes use OpenTF's provider
values for the indicated archive. These hashes use OpenTofu's provider
package hashing algorithm. At present, the easiest way to populate these
is to construct a mirror's JSON indices using the `opentf providers mirror`
is to construct a mirror's JSON indices using the `tofu providers mirror`
command, as described in a later section, which will include the calculated
hashes of each provider.
If the response includes at least one hash, OpenTF will select the hash
If the response includes at least one hash, OpenTofu will select the hash
whose algorithm it considers to be strongest and verify that the downloaded
package matches that hash. If the response does not include a `hashes`
property then OpenTF will install the indicated archive with no
property then OpenTofu will install the indicated archive with no
verification.
OpenTF CLI will only attempt to download versions that it has previously
OpenTofu CLI will only attempt to download versions that it has previously
seen in response to [List Available Versions](#list-available-versions).
## Provider Mirror as a Static Website
@@ -254,17 +254,17 @@ strategy, implement the JSON index responses described above as `.json` files
in the appropriate nested subdirectories, and ensure that your system is
configured to serve `.json` files with the `application/json` media type.
As a convenience, OpenTF CLI includes
[the `opentf providers mirror` subcommand](/docs/cli/commands/providers/mirror),
As a convenience, OpenTofu CLI includes
[the `tofu providers mirror` subcommand](/docs/cli/commands/providers/mirror),
which will analyze the current configuration for the providers it requires,
download the packages for those providers from their origin registries, and
place them into a local directory suitable for use as a mirror.
The `opentf providers mirror` subcommand also generates `index.json` and
The `tofu providers mirror` subcommand also generates `index.json` and
version-specific `.json` files that can, when placed in a static website hosting
system, produce responses compatible with the provider mirror protocol.
If you wish to create a mirror with providers for a number of different
OpenTF configurations, run `opentf providers mirror` in each configuration
in turn while providing the same output directory each time. OpenTF will
OpenTofu configurations, run `tofu providers mirror` in each configuration
in turn while providing the same output directory each time. OpenTofu will
then merge together all of the requirements into a single set of JSON indices.

56
website/docs/internals/provider-registry-protocol.mdx
View File

@@ -1,7 +1,7 @@
---
description: |-
The provider registry protocol is implemented by a host intending to be the
origin host for one or more OpenTF providers, specifying which providers
origin host for one or more OpenTofu providers, specifying which providers
are available and where to find their distribution packages.
---
@@ -19,18 +19,18 @@ alternative to publishing them on the public Terraform Registry.
This page describes the provider _registry_ protocol, which is the protocol
for finding providers available for installation. It _doesn't_ describe the
API that provider plugins themselves implement to serve requests from OpenTF
CLI at runtime. For more information on the provider API, see the OpenTF
API that provider plugins themselves implement to serve requests from OpenTofu
CLI at runtime. For more information on the provider API, see the OpenTofu
SDK documentation.
## Provider Addresses
Each OpenTF provider has an associated address which uniquely identifies it
within OpenTF. A provider address has the syntax `hostname/namespace/type`,
Each OpenTofu provider has an associated address which uniquely identifies it
within OpenTofu. A provider address has the syntax `hostname/namespace/type`,
where:
* `hostname` is the registry host that the provider is considered to have
originated from, and the default location OpenTF will consult for
originated from, and the default location OpenTofu will consult for
information about the provider
[unless overridden in the CLI configuration](/docs/cli/config/config-file#provider-installation).
* `namespace` is the name of a namespace, unique on a particular hostname, that
@@ -54,16 +54,16 @@ For example:
third-party provider registry on `example.com`.
If you intend only to share a provider you've developed for use by all
OpenTF users, please consider publishing it into the public
OpenTofu users, please consider publishing it into the public
[Terraform Registry](https://registry.terraform.io/), which will make your
provider discoverable. You only need to implement this provider registry
protocol if you wish to publish providers whose addresses include a different
hostname that is under your control.
OpenTF uses the full address (after normalization to always include a
OpenTofu uses the full address (after normalization to always include a
hostname) as its global identifier for providers internally, and so it's
important to note that re-uploading the `hashicorp/azurerm` provider into
another namespace or publishing it on a different hostname will cause OpenTF
another namespace or publishing it on a different hostname will cause OpenTofu
to see it as an entirely separate provider that will _not_ be usable by modules
that declare a dependency on `hashicorp/azurerm`. If your goal is to create
an alternative local distribution source for an existing provider -- that is,
@@ -74,21 +74,21 @@ instead.
## Provider Versions
Each distinct provider address has associated with it a set of versions, each
of which has an associated version number. OpenTF assumes version numbers
of which has an associated version number. OpenTofu assumes version numbers
follow the [Semantic Versioning 2.0](https://semver.org/) conventions, with
the schema and behavior of the provider as documented from the perspective of
an end-user of OpenTF serving as the "public API".
an end-user of OpenTofu serving as the "public API".
All available versions for a particular provider address are considered to be
the same provider by OpenTF. Each OpenTF configuration selects only one
the same provider by OpenTofu. Each OpenTofu configuration selects only one
version of each provider for use in the entire configuration, so the version
constraints across all modules are considered together for the purposes of
version selection.
## Service Discovery
The providers protocol begins with OpenTF CLI using
[OpenTF's remote service discovery protocol](/docs/internals/remote-service-discovery),
The providers protocol begins with OpenTofu CLI using
[OpenTofu's remote service discovery protocol](/docs/internals/remote-service-discovery),
with the hostname in the provider address acting as the "User-facing Hostname".
The service identifier for the provider registry protocol is `providers.v1`.
@@ -100,18 +100,18 @@ the provider registry protocol might contain the following:
```json
{
"providers.v1": "/opentf/providers/v1/"
"providers.v1": "/tofu/providers/v1/"
}
```
If the given URL is a relative URL then OpenTF will interpret it as relative
If the given URL is a relative URL then OpenTofu will interpret it as relative
to the discovery document itself. The specific provider registry protocol
endpoints are defined as URLs relative to the given base URL, and so the
specified base URL should generally end with a slash to ensure that those
relative paths will be resolved as expected.
The following sections describe the various operations that a provider
registry must implement to be compatible with OpenTF CLI's provider
registry must implement to be compatible with OpenTofu CLI's provider
installer. The indicated URLs are all relative to the URL resulting from
service discovery, as described above. We use a hypothetical URL for a provider
registry, assuming that the caller already performed service discovery on a hypothetical
@@ -182,15 +182,15 @@ with the following properties:
* `version` (required): the version number this object is describing, using
the semantic versioning string notation. `version` must be unique across
all objects in the response.
* `protocols` (recommended): an array of OpenTF provider API versions that
* `protocols` (recommended): an array of OpenTofu provider API versions that
this version supports, each given in `MAJOR.MINOR` format where each major
version appears only once and the given minor version is the highest minor
version supported. For example, `5.1` means that the provider supports both
protocol `5.0` and protocol `5.1`.
OpenTF uses this information, when available, to provide hints to users
OpenTofu uses this information, when available, to provide hints to users
about upgrading or downgrading their version of a particular provider to
work with their current version of OpenTF, if their currently-selected
work with their current version of OpenTofu, if their currently-selected
versions are not compatible.
Which API versions are supported is, for most providers, decided by which
@@ -216,7 +216,7 @@ This operation returns the download URL of and associated metadata about the
distribution package for a particular version of a provider for a particular
operating system and architecture.
OpenTF CLI uses this operation after it has selected the newest available
OpenTofu CLI uses this operation after it has selected the newest available
version matching the configured version constraints, in order to find the zip
archive containing the plugin itself.
@@ -273,12 +273,12 @@ curl 'https://registry.example.io/v1/providers/hashicorp/random/2.0.0/download/l
A successful result is a JSON object with the following properties:
* `protocols` (required): an array of OpenTF provider API versions that
* `protocols` (required): an array of OpenTofu provider API versions that
the provider supports, in the same format as for
[List Available Versions](#list-available-versions).
While this property is optional when listing available options, it is
_required_ for describing an individual provider package so that OpenTF
_required_ for describing an individual provider package so that OpenTofu
CLI can avoid downloading a package that will not be compatible with it.
* `os` (required): this must echo back the `os` parameter from the
@@ -288,14 +288,14 @@ A successful result is a JSON object with the following properties:
request.
* `filename` (required): the filename for this provider's zip archive as
recorded in the "shasums" document, so that OpenTF CLI can determine which
recorded in the "shasums" document, so that OpenTofu CLI can determine which
of the given checksums should be used for this specific package.
* `download_url` (required): a URL from which OpenTF can retrieve the
* `download_url` (required): a URL from which OpenTofu can retrieve the
provider's zip archive. If this is a relative URL then it will be resolved
relative to the URL that returned the containing JSON object.
* `shasums_url` (required): a URL from which OpenTF can retrieve a text
* `shasums_url` (required): a URL from which OpenTofu can retrieve a text
document recording expected SHA256 checksums for this package and possibly
other packages for the same provider version on other platforms.
@@ -303,7 +303,7 @@ A successful result is a JSON object with the following properties:
command available on many Unix systems, with one entry recording the
same filename given in the `filename` property (case sensitive).
* `shasums_signature_url` (required): a URL from which OpenTF can retrieve
* `shasums_signature_url` (required): a URL from which OpenTofu can retrieve
a binary, detached GPG signature for the document at `shasums_url`, signed
by one of the keys indicated in the `signing_keys` property.
@@ -326,6 +326,6 @@ A successful result is a JSON object with the following properties:
associated with this GPG key.
Return `404 Not Found` to signal that the given provider version isn't
available for the requested operating system and/or architecture. OpenTF
available for the requested operating system and/or architecture. OpenTofu
CLI will only attempt to download versions that it has previously seen in
response to [List Available Versions](#list-available-versions).

26
website/docs/internals/remote-service-discovery.mdx
View File

@@ -1,32 +1,32 @@
---
description: |-
Remote service discovery is a protocol used to locate OpenTF-native
Remote service discovery is a protocol used to locate OpenTofu-native
services provided at a user-friendly hostname.
---
# Remote Service Discovery
OpenTF implements much of its functionality in terms of remote services.
OpenTofu implements much of its functionality in terms of remote services.
While in many cases these are generic third-party services that are useful
to many applications, some of these services are tailored specifically to
OpenTF's needs. We call these _OpenTF-native services_, and OpenTF
OpenTofu's needs. We call these _OpenTofu-native services_, and OpenTofu
interacts with them via the remote service discovery protocol described below.
## User-facing Hostname
OpenTF-native services are provided, from a user's perspective, at a
OpenTofu-native services are provided, from a user's perspective, at a
user-facing "friendly hostname" which serves as the key for configuration and
for any authentication credentials required.
The discovery protocol's purpose is to map from a user-provided hostname to
the base URL of a particular service. Each host can provide different
combinations of services -- or no services at all! -- and so the discovery
protocol has a secondary purpose of allowing OpenTF to identify _which_
protocol has a secondary purpose of allowing OpenTofu to identify _which_
services are valid for a given hostname.
For example, module source strings can include a module registry hostname
as their first segment, like `example.com/namespace/name/provider`, and
OpenTF uses service discovery to determine whether `example.com` _has_
OpenTofu uses service discovery to determine whether `example.com` _has_
a module registry, and if so where its API is available.
A user-facing hostname is a fully-specified
@@ -50,17 +50,17 @@ using that hostname with the `https:` scheme and the fixed path
For example, given the hostname `example.com` the initial discovery URL
would be `https://example.com/.well-known/terraform.json`.
OpenTF then sends a `GET` request to this discovery URL and expects a
OpenTofu then sends a `GET` request to this discovery URL and expects a
JSON response. If the response does not have status 200, does not have a media
type of `application/json` or, if the body cannot be parsed as a JSON object,
then discovery fails and OpenTF considers the host to not support _any_
OpenTF-native services.
then discovery fails and OpenTofu considers the host to not support _any_
OpenTofu-native services.
If the response is an HTTP redirect then OpenTF repeats this step with the
new location as its discovery URL. OpenTF is guaranteed to follow at least
If the response is an HTTP redirect then OpenTofu repeats this step with the
new location as its discovery URL. OpenTofu is guaranteed to follow at least
one redirect, but nested redirects are not guaranteed nor recommended.
If the response is a valid JSON object then its keys are OpenTF native
If the response is a valid JSON object then its keys are OpenTofu native
service identifiers, consisting of a service type name and a version string
separated by a period. For example, the service identifier for version 1 of
the module registry protocol is `modules.v1`.
@@ -98,7 +98,7 @@ document, depending on the requirements of the service in question.
It is strongly recommended to provide the discovery document for a hostname
on the standard HTTPS port 443. However, in development environments this is
not always possible or convenient, so OpenTF allows a hostname to end
not always possible or convenient, so OpenTofu allows a hostname to end
with a port specification consisting of a colon followed by one or more
decimal digits.

48
website/docs/intro/core-workflow.mdx
View File

@@ -1,10 +1,10 @@
---
description: 'An overview of how individuals, teams, and organizations can use OpenTF. '
description: 'An overview of how individuals, teams, and organizations can use OpenTofu. '
---
# The Core OpenTF Workflow
# The Core OpenTofu Workflow
The core OpenTF workflow has three steps:
The core OpenTofu workflow has three steps:
1. **Write** - Author infrastructure as code.
1. **Plan** - Preview changes before applying.
@@ -22,7 +22,7 @@ on infrastructure as code.
### Write
You write OpenTF configuration just like you write code: in your editor of
You write OpenTofu configuration just like you write code: in your editor of
choice. It's common practice to store your work in a version controlled
repository even when you're just operating as an individual.
@@ -35,12 +35,12 @@ Initialized empty Git repository in /.../my-infra/.git/
# Write initial config
$ vim main.tf
# Initialize OpenTF
$ opentf init
# Initialize OpenTofu
$ tofu init
Initializing provider plugins...
# ...
OpenTF has been successfully initialized!
OpenTofu has been successfully initialized!
```
As you make progress on authoring your config, repeatedly running plans can help
@@ -52,7 +52,7 @@ expect.
$ vim main.tf
# Review plan
$ opentf plan
$ tofu plan
# Make additional edits, and repeat
$ vim main.tf
@@ -74,12 +74,12 @@ $ git commit -m 'Managing infrastructure as code!'
1 file changed, 1 insertion(+)
```
Because `opentf apply` will display a plan for confirmation before
Because `tofu apply` will display a plan for confirmation before
proceeding to change any infrastructure, that's the command you run for final
review.
```sh
$ opentf apply
$ tofu apply
An execution plan has been generated and is shown below.
# ...
@@ -87,13 +87,13 @@ An execution plan has been generated and is shown below.
### Apply
After one last check, you are ready to tell OpenTF to provision real
After one last check, you are ready to tell OpenTofu to provision real
infrastructure.
```sh
Do you want to perform these actions?
OpenTF will perform the actions described above.
OpenTofu will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
@@ -115,11 +115,11 @@ the process over from the beginning.
Notice how closely this workflow parallels the process of writing application
code or scripts as an individual? This is what we mean when we talk about
OpenTF enabling infrastructure as code.
OpenTofu enabling infrastructure as code.
## Working as a Team
Once multiple people are collaborating on OpenTF configuration, new steps
Once multiple people are collaborating on OpenTofu configuration, new steps
must be added to each part of the core workflow to ensure everyone is working
together smoothly. You'll see that many of these steps parallel the workflow
changes we make when we work on application code as teams rather than as
@@ -127,7 +127,7 @@ individuals.
### Write
While each individual on a team still makes changes to OpenTF configuration
While each individual on a team still makes changes to OpenTofu configuration
in their editor of choice, they save their changes to version control _branches_
to avoid colliding with each other's work. Working in branches enables team
members to resolve mutually incompatible infrastructure changes using their
@@ -147,20 +147,20 @@ required to run a plan.
To avoid the burden and the security risk of each team member arranging all
sensitive inputs locally, it's common for teams to migrate to a model in which
OpenTF operations are executed in a shared Continuous Integration (CI)
OpenTofu operations are executed in a shared Continuous Integration (CI)
environment. The work needed to create such a CI environment is nontrivial, and
is outside the scope of this core workflow overview.
This longer iteration cycle of committing changes to version control and then
waiting for the CI pipeline to execute is often lengthy enough to prohibit using
speculative plans as a feedback loop while authoring individual OpenTF
configuration changes. Speculative plans are still useful before new OpenTF
speculative plans as a feedback loop while authoring individual OpenTofu
configuration changes. Speculative plans are still useful before new OpenTofu
changes are applied or even merged to the main development branch, however, as
we'll see in a minute.
### Plan
For teams collaborating on infrastructure, OpenTF's plan output creates an
For teams collaborating on infrastructure, OpenTofu's plan output creates an
opportunity for team members to review each other's work. This allows the team
to ask questions, evaluate risks, and catch mistakes before any potentially
harmful changes are made.
@@ -172,7 +172,7 @@ config changes alongside speculative plan output, they can evaluate whether the
intent of the change is being achieved by the plan.
The problem becomes producing that speculative plan output for the team to
review. Some teams that still run OpenTF locally make a practice that pull
review. Some teams that still run OpenTofu locally make a practice that pull
requests should include an attached copy of speculative plan output generated
by the change author. Others arrange for their CI system to post speculative
plan output to pull requests automatically.
@@ -201,8 +201,8 @@ anything in our system that we should be watching as we apply this? Is there
anyone we need to notify that this change is happening?
Depending on the change, sometimes team members will want to watch the apply
output as it is happening. For teams that are running OpenTF locally, this
may involve a screen share with the team. For teams running OpenTF in CI,
output as it is happening. For teams that are running OpenTofu locally, this
may involve a screen share with the team. For teams running OpenTofu in CI,
this may involve gathering around the build log.
Just like the workflow for individuals, the core workflow for teams is a loop
@@ -211,9 +211,9 @@ week, for others, many times a day.
## Conclusion
There are many different ways to use OpenTF: as an individual user, a single
There are many different ways to use OpenTofu: as an individual user, a single
team, or an entire organization at scale. Choosing the best approach for the
density of collaboration needed will provide the most return on your investment
in the core OpenTF workflow. For organizations using OpenTF at scale,
in the core OpenTofu workflow. For organizations using OpenTofu at scale,
TACOS (TF Automation and Collaboration Software) introduces new layers that build on this core workflow to
solve problems unique to teams and organizations.

38
website/docs/intro/index.mdx
View File

@@ -1,59 +1,59 @@
---
sidebar_position: 1
description: |-
OpenTF is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently.
OpenTofu is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently.
---
# What is OpenTF?
# What is OpenTofu?
OpenTF is an infrastructure as code tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to provision and manage all of your infrastructure throughout its lifecycle. OpenTF can manage low-level components like compute, storage, and networking resources, as well as high-level components like DNS entries and SaaS features.
OpenTofu is an infrastructure as code tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to provision and manage all of your infrastructure throughout its lifecycle. OpenTofu can manage low-level components like compute, storage, and networking resources, as well as high-level components like DNS entries and SaaS features.
## How does OpenTF work?
## How does OpenTofu work?
OpenTF creates and manages resources on cloud platforms and other services through their application programming interfaces (APIs). Providers enable OpenTF to work with virtually any platform or service with an accessible API.
OpenTofu creates and manages resources on cloud platforms and other services through their application programming interfaces (APIs). Providers enable OpenTofu to work with virtually any platform or service with an accessible API.
![OpenTF creates and manages cloud platforms and services through their APIs](/img/docs/intro-opentf-apis.png)
![OpenTofu creates and manages cloud platforms and services through their APIs](/img/docs/intro-opentf-apis.png)
The OpenTF community have already written **thousands of providers** to manage many different types of resources and services. You can find all publicly available providers on the [Public Terraform Registry](https://registry.terraform.io/), including Amazon Web Services (AWS), Azure, Google Cloud Platform (GCP), Kubernetes, Helm, GitHub, Splunk, DataDog, and many more.
The OpenTofu community have already written **thousands of providers** to manage many different types of resources and services. You can find all publicly available providers on the [Public Terraform Registry](https://registry.terraform.io/), including Amazon Web Services (AWS), Azure, Google Cloud Platform (GCP), Kubernetes, Helm, GitHub, Splunk, DataDog, and many more.
The core OpenTF workflow consists of three stages:
The core OpenTofu workflow consists of three stages:
- **Write:** You define resources, which may be across multiple cloud providers and services. For example, you might create a configuration to deploy an application on virtual machines in a Virtual Private Cloud (VPC) network with security groups and a load balancer.
- **Plan:** OpenTF creates an execution plan describing the infrastructure it will create, update, or destroy based on the existing infrastructure and your configuration.
- **Apply:** On approval, OpenTF performs the proposed operations in the correct order, respecting any resource dependencies. For example, if you update the properties of a VPC and change the number of virtual machines in that VPC, OpenTF will recreate the VPC before scaling the virtual machines.
- **Plan:** OpenTofu creates an execution plan describing the infrastructure it will create, update, or destroy based on the existing infrastructure and your configuration.
- **Apply:** On approval, OpenTofu performs the proposed operations in the correct order, respecting any resource dependencies. For example, if you update the properties of a VPC and change the number of virtual machines in that VPC, OpenTofu will recreate the VPC before scaling the virtual machines.
![The OpenTF workflow has three steps: Write, Plan, and Apply](/img/docs/intro-opentf-workflow.png)
![The OpenTofu workflow has three steps: Write, Plan, and Apply](/img/docs/intro-opentf-workflow.png)
## Why OpenTF?
## Why OpenTofu?
### Manage any infrastructure
Find providers for many of the platforms and services you already use in the [Public Terraform Registry](https://registry.terraform.io/). You can also [write your own](/docs/plugin). OpenTF takes an [immutable approach to infrastructure](https://www.hashicorp.com/resources/what-is-mutable-vs-immutable-infrastructure), reducing the complexity of upgrading or modifying your services and infrastructure.
Find providers for many of the platforms and services you already use in the [Public Terraform Registry](https://registry.terraform.io/). You can also [write your own](/docs/plugin). OpenTofu takes an [immutable approach to infrastructure](https://www.hashicorp.com/resources/what-is-mutable-vs-immutable-infrastructure), reducing the complexity of upgrading or modifying your services and infrastructure.
### Track your infrastructure
OpenTF generates a plan and prompts you for your approval before modifying your infrastructure. It also keeps track of your real infrastructure in a [state file](/docs/language/state), which acts as a source of truth for your environment. OpenTF uses the state file to determine the changes to make to your infrastructure so that it will match your configuration.
OpenTofu generates a plan and prompts you for your approval before modifying your infrastructure. It also keeps track of your real infrastructure in a [state file](/docs/language/state), which acts as a source of truth for your environment. OpenTofu uses the state file to determine the changes to make to your infrastructure so that it will match your configuration.
### Automate changes
OpenTF configuration files are declarative, meaning that they describe the end state of your infrastructure. You do not need to write step-by-step instructions to create resources because OpenTF handles the underlying logic. OpenTF builds a resource graph to determine resource dependencies and creates or modifies non-dependent resources in parallel. This allows OpenTF to provision resources efficiently.
OpenTofu configuration files are declarative, meaning that they describe the end state of your infrastructure. You do not need to write step-by-step instructions to create resources because OpenTofu handles the underlying logic. OpenTofu builds a resource graph to determine resource dependencies and creates or modifies non-dependent resources in parallel. This allows OpenTofu to provision resources efficiently.
### Standardize configurations
OpenTF supports reusable configuration components called [modules](/docs/language/modules) that define configurable collections of infrastructure, saving time and encouraging best practices. You can use publicly available modules from the Terraform Registry, or write your own.
OpenTofu supports reusable configuration components called [modules](/docs/language/modules) that define configurable collections of infrastructure, saving time and encouraging best practices. You can use publicly available modules from the Terraform Registry, or write your own.
### Collaborate
Since your configuration is written in a file, you can commit it to a Version Control System (VCS) and use a cloud backend to efficiently manage OpenTF workflows across teams. A cloud backend runs OpenTF in a consistent, reliable environment and provides secure access to shared state and secret data, role-based access controls, a private registry for sharing both modules and providers, and more.
Since your configuration is written in a file, you can commit it to a Version Control System (VCS) and use a cloud backend to efficiently manage OpenTofu workflows across teams. A cloud backend runs OpenTofu in a consistent, reliable environment and provides secure access to shared state and secret data, role-based access controls, a private registry for sharing both modules and providers, and more.
:::note Tip
Learn more about [OpenTF use cases](/docs/intro/use-cases) and [how OpenTF compares to alternatives](/docs/intro/vs).
Learn more about [OpenTofu use cases](/docs/intro/use-cases) and [how OpenTofu compares to alternatives](/docs/intro/vs).
:::
## Community
We welcome questions, suggestions, and contributions from the community.
- Ask questions in [OpenTF Discuss](https://github.com/orgs/opentofu/discussions).
- Ask questions in [OpenTofu Discuss](https://github.com/orgs/opentofu/discussions).
- Read our [contributing guide](https://github.com/opentofu/opentofu/blob/main/CONTRIBUTING.md).
- [Submit an issue](https://github.com/opentofu/opentofu/issues) for bugs and feature requests.

24
website/docs/intro/use-cases.mdx
View File

@@ -1,17 +1,17 @@
---
description: |-
Learn how OpenTF enables multi-cloud deployments, application management, policy compliance, and self-service infrastructure.
Learn how OpenTofu enables multi-cloud deployments, application management, policy compliance, and self-service infrastructure.
---
# Use Cases
[OpenTF](/docs/intro) is an infrastructure as code tool that lets you define infrastructure resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to safely and efficiently provision and manage your infrastructure throughout its lifecycle.
[OpenTofu](/docs/intro) is an infrastructure as code tool that lets you define infrastructure resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to safely and efficiently provision and manage your infrastructure throughout its lifecycle.
This page describes popular OpenTF use cases and provides related resources that you can use to create OpenTF configurations and workflows.
This page describes popular OpenTofu use cases and provides related resources that you can use to create OpenTofu configurations and workflows.
## Multi-Cloud Deployment
Provisioning infrastructure across multiple clouds increases fault-tolerance, allowing for more graceful recovery from cloud provider outages. However, multi-cloud deployments add complexity because each provider has its own interfaces, tools, and workflows. OpenTF lets you use the same workflow to manage multiple providers and handle cross-cloud dependencies. This simplifies management and orchestration for large-scale, multi-cloud infrastructures.
Provisioning infrastructure across multiple clouds increases fault-tolerance, allowing for more graceful recovery from cloud provider outages. However, multi-cloud deployments add complexity because each provider has its own interfaces, tools, and workflows. OpenTofu lets you use the same workflow to manage multiple providers and handle cross-cloud dependencies. This simplifies management and orchestration for large-scale, multi-cloud infrastructures.
### Resources
@@ -19,32 +19,32 @@ Provisioning infrastructure across multiple clouds increases fault-tolerance, al
## Application Infrastructure Deployment, Scaling, and Monitoring Tools
You can use OpenTF to efficiently deploy, release, scale, and monitor infrastructure for multi-tier applications. N-tier application architecture lets you scale application components independently and provides a separation of concerns. An application could consist of a pool of web servers that use a database tier, with additional tiers for API servers, caching servers, and routing meshes. OpenTF allows you to manage the resources in each tier together, and automatically handles dependencies between tiers. For example, OpenTF will deploy a database tier before provisioning the web servers that depend on it.
You can use OpenTofu to efficiently deploy, release, scale, and monitor infrastructure for multi-tier applications. N-tier application architecture lets you scale application components independently and provides a separation of concerns. An application could consist of a pool of web servers that use a database tier, with additional tiers for API servers, caching servers, and routing meshes. OpenTofu allows you to manage the resources in each tier together, and automatically handles dependencies between tiers. For example, OpenTofu will deploy a database tier before provisioning the web servers that depend on it.
## Self-Service Clusters
At a large organization, your centralized operations team may get many repetitive infrastructure requests. You can use OpenTF to build a "self-serve" infrastructure model that lets product teams manage their own infrastructure independently. You can create and use OpenTF modules that codify the standards for deploying and managing services in your organization, allowing teams to efficiently deploy services in compliance with your organization’s practices. A cloud backend can also integrate with ticketing systems like ServiceNow to automatically generate new infrastructure requests.
At a large organization, your centralized operations team may get many repetitive infrastructure requests. You can use OpenTofu to build a "self-serve" infrastructure model that lets product teams manage their own infrastructure independently. You can create and use OpenTofu modules that codify the standards for deploying and managing services in your organization, allowing teams to efficiently deploy services in compliance with your organization’s practices. A cloud backend can also integrate with ticketing systems like ServiceNow to automatically generate new infrastructure requests.
## Policy Compliance and Management
OpenTF can help you enforce policies on the types of resources teams can provision and use. Ticket-based review processes are a bottleneck that can slow down development. Instead, you can use Sentinel, a policy-as-code framework, to automatically enforce compliance and governance policies before OpenTF makes infrastructure changes. Sentinel policies are available in cloud backends.
OpenTofu can help you enforce policies on the types of resources teams can provision and use. Ticket-based review processes are a bottleneck that can slow down development. Instead, you can use Sentinel, a policy-as-code framework, to automatically enforce compliance and governance policies before OpenTofu makes infrastructure changes. Sentinel policies are available in cloud backends.
## PaaS Application Setup
Platform as a Service (PaaS) vendors like Heroku allow you to create web applications and attach add-ons, such as databases or email providers. Heroku can elastically scale the number of dynos or workers, but most non-trivial applications need many add-ons and external services. You can use OpenTF to codify the setup required for a Heroku application, configure a DNSimple to set a CNAME, and set up Cloudflare as a Content Delivery Network (CDN) for the app. OpenTF can quickly and consistently do all of this without a web interface.
Platform as a Service (PaaS) vendors like Heroku allow you to create web applications and attach add-ons, such as databases or email providers. Heroku can elastically scale the number of dynos or workers, but most non-trivial applications need many add-ons and external services. You can use OpenTofu to codify the setup required for a Heroku application, configure a DNSimple to set a CNAME, and set up Cloudflare as a Content Delivery Network (CDN) for the app. OpenTofu can quickly and consistently do all of this without a web interface.
## Software Defined Networking
OpenTF can interact with Software Defined Networks (SDNs) to automatically configure the network according to the needs of the applications running in it. This lets you move from a ticket-based workflow to an automated one, reducing deployment times.
OpenTofu can interact with Software Defined Networks (SDNs) to automatically configure the network according to the needs of the applications running in it. This lets you move from a ticket-based workflow to an automated one, reducing deployment times.
## Kubernetes
Kubernetes is an open-source workload scheduler for containerized applications. OpenTF lets you both deploy a Kubernetes cluster and manage its resources (e.g., pods, deployments, services, etc.).
Kubernetes is an open-source workload scheduler for containerized applications. OpenTofu lets you both deploy a Kubernetes cluster and manage its resources (e.g., pods, deployments, services, etc.).
## Parallel Environments
You may have staging or QA environments that you use to test new applications before releasing them in production. As the production environment grows larger and more complex, it can be increasingly difficult to maintain an up-to-date environment for each stage of the development process. OpenTF lets you rapidly spin up and decommission infrastructure for development, test, QA, and production. Using OpenTF to create disposable environments as needed is more cost-efficient than maintaining each one indefinitely.
You may have staging or QA environments that you use to test new applications before releasing them in production. As the production environment grows larger and more complex, it can be increasingly difficult to maintain an up-to-date environment for each stage of the development process. OpenTofu lets you rapidly spin up and decommission infrastructure for development, test, QA, and production. Using OpenTofu to create disposable environments as needed is more cost-efficient than maintaining each one indefinitely.
## Software Demos
You can use OpenTF to create, provision, and bootstrap a demo on various cloud providers. This lets end users easily try the software on their own infrastructure and even enables them to adjust parameters like cluster size to more rigorously test tools at any scale.
You can use OpenTofu to create, provision, and bootstrap a demo on various cloud providers. This lets end users easily try the software on their own infrastructure and even enables them to adjust parameters like cluster size to more rigorously test tools at any scale.

8
website/docs/intro/vs/boto.mdx
View File

@@ -1,8 +1,8 @@
---
description: 'How OpenTF compares to cloud provider client libraries like Boto and Fog. '
description: 'How OpenTofu compares to cloud provider client libraries like Boto and Fog. '
---
# OpenTF vs. Boto, Fog, etc.
# OpenTofu vs. Boto, Fog, etc.
Libraries like Boto, Fog, etc. are used to provide native access
to cloud providers and services by using their APIs. Some
@@ -11,9 +11,9 @@ to bridge them all and mask the semantic differences. Using a client
library only provides low-level access to APIs, requiring application
developers to create their own tooling to build and manage their infrastructure.
OpenTF is not intended to give low-level programmatic access to
OpenTofu is not intended to give low-level programmatic access to
providers, but instead provides a high level syntax for describing
how cloud resources and services should be created, provisioned, and
combined. OpenTF is very flexible, using a plugin-based model to
combined. OpenTofu is very flexible, using a plugin-based model to
support providers and provisioners, giving it the ability to support
almost any service that exposes APIs.

10
website/docs/intro/vs/chef-puppet.mdx
View File

@@ -1,22 +1,22 @@
---
description: >-
How OpenTF compares to configuration management tools like Chef and
How OpenTofu compares to configuration management tools like Chef and
Puppet.
---
# OpenTF vs. Chef, Puppet, etc.
# OpenTofu vs. Chef, Puppet, etc.
Configuration management tools install and manage software on a machine
that already exists. OpenTF is not a configuration management tool,
that already exists. OpenTofu is not a configuration management tool,
and it allows existing tooling to focus on their strengths: bootstrapping
and initializing resources.
OpenTF focuses on the higher-level abstraction of the datacenter and
OpenTofu focuses on the higher-level abstraction of the datacenter and
associated services, while allowing you to use configuration management
tools on individual systems. It also aims to bring the same benefits of
codification of your system configuration to infrastructure management.
If you are using traditional configuration management within your compute
instances, you can use OpenTF to configure bootstrapping software like
instances, you can use OpenTofu to configure bootstrapping software like
cloud-init to activate your configuration management software on first
system boot.

22
website/docs/intro/vs/cloudformation.mdx
View File

@@ -1,38 +1,38 @@
---
description: >-
How OpenTF compares to other infrastructure as code tools like
CloudFormation and Heat. OpenTF can simultaneously manage multiple cloud
How OpenTofu compares to other infrastructure as code tools like
CloudFormation and Heat. OpenTofu can simultaneously manage multiple cloud
providers (AWS, OpenStack, etc.) and services (Cloudflare, DNSimple, etc.).
---
# OpenTF vs. CloudFormation, Heat, etc.
# OpenTofu vs. CloudFormation, Heat, etc.
Tools like CloudFormation, Heat, etc. allow the details of an infrastructure
to be codified into a configuration file. The configuration files allow
the infrastructure to be elastically created, modified and destroyed. OpenTF
the infrastructure to be elastically created, modified and destroyed. OpenTofu
is inspired by the problems they solve.
OpenTF similarly uses configuration files to detail the infrastructure
OpenTofu similarly uses configuration files to detail the infrastructure
setup, but it goes further by being both cloud-agnostic and enabling
multiple providers and services to be combined and composed. For example,
OpenTF can be used to orchestrate an AWS and OpenStack cluster simultaneously,
OpenTofu can be used to orchestrate an AWS and OpenStack cluster simultaneously,
while enabling 3rd-party providers like Cloudflare and DNSimple to be integrated
to provide CDN and DNS services. This enables OpenTF to represent and
to provide CDN and DNS services. This enables OpenTofu to represent and
manage the entire infrastructure with its supporting services, instead of
only the subset that exists within a single provider. It provides a single
unified syntax, instead of requiring operators to use independent and
non-interoperable tools for each platform and service.
OpenTF also separates the planning phase from the execution phase,
by using the concept of an execution plan. By running `opentf plan`,
OpenTofu also separates the planning phase from the execution phase,
by using the concept of an execution plan. By running `tofu plan`,
the current state is refreshed and the configuration is consulted to
generate an action plan. The plan includes all actions to be taken:
which resources will be created, destroyed or modified. It can be
inspected by operators to ensure it is exactly what is expected. Using
`opentf graph`, the plan can be visualized to show dependent ordering.
`tofu graph`, the plan can be visualized to show dependent ordering.
Once the plan is captured, the execution phase can be limited to only
the actions in the plan. Other tools combine the planning and execution
phases, meaning operators are forced to mentally reason about the effects
of a change, which quickly becomes intractable in large infrastructures.
OpenTF lets operators apply changes with confidence, as they know exactly
OpenTofu lets operators apply changes with confidence, as they know exactly
what will happen beforehand.

10
website/docs/intro/vs/custom.mdx
View File

@@ -1,10 +1,10 @@
---
description: >-
Why OpenTF is easier to use and maintain than custom, internal
Why OpenTofu is easier to use and maintain than custom, internal
infrastructure solutions.
---
# OpenTF vs. Custom Solutions
# OpenTofu vs. Custom Solutions
Most organizations start by manually managing infrastructure through
simple scripts or web-based interfaces. As the infrastructure grows,
@@ -21,7 +21,7 @@ updated in lockstep with any new features or infrastructure,
it becomes the limiting factor for how quickly the infrastructure
can evolve.
OpenTF is designed to tackle these challenges. It provides a simple,
OpenTofu is designed to tackle these challenges. It provides a simple,
unified syntax, allowing almost any resource to be managed without
learning new tooling. By capturing all the resources required, the
dependencies between them can be resolved automatically so that operators
@@ -29,9 +29,9 @@ do not need to remember and reason about them. Removing the burden
of building the tool allows operators to focus on their infrastructure
and not the tooling.
Furthermore, OpenTF is an open source tool. The community around OpenTF
Furthermore, OpenTofu is an open source tool. The community around OpenTofu
helps to extend its features, fix bugs and document new use cases.
OpenTF helps solve a problem that exists in every organization and provides
OpenTofu helps solve a problem that exists in every organization and provides
a standard that can be adopted to avoid reinventing the wheel between
and within organizations.
Its open source nature ensures it will be around in the long term.

14
website/docs/intro/vs/index.mdx
View File

@@ -1,19 +1,19 @@
---
description: An overview of how OpenTF compares to alternative software and tools.
description: An overview of how OpenTofu compares to alternative software and tools.
---
# OpenTF vs. Alternatives
# OpenTofu vs. Alternatives
OpenTF provides a flexible abstraction of resources and providers. This model
OpenTofu provides a flexible abstraction of resources and providers. This model
allows for representing everything from physical hardware, virtual machines, and
containers, to email and DNS providers. Because of this flexibility, OpenTF
containers, to email and DNS providers. Because of this flexibility, OpenTofu
can be used to solve many different problems. This means there are a number of
existing tools that overlap with the capabilities of OpenTF. We compare OpenTF
to a number of these tools, but it should be noted that OpenTF is not mutually
existing tools that overlap with the capabilities of OpenTofu. We compare OpenTofu
to a number of these tools, but it should be noted that OpenTofu is not mutually
exclusive with other systems. It can be used to manage a single application, or the
entire datacenter.
Learn how OpenTF compares to:
Learn how OpenTofu compares to:
- [Chef, Puppet, etc.](/docs/intro/vs/chef-puppet)
- [CloudFormation, Heat, etc.](/docs/intro/vs/cloudformation)

4
website/docs/language/attr-as-blocks.mdx
View File

@@ -9,7 +9,7 @@ description: >-
# Attributes as Blocks
:::note
This page is an appendix to the OpenTF documentation. Most users do not need to know the full details of this behavior.
This page is an appendix to the OpenTofu documentation. Most users do not need to know the full details of this behavior.
:::
## Summary
@@ -24,7 +24,7 @@ is set to an empty list (`<ATTR> = []`).
Most users do not need to know any further details of this "nested block or
empty list" behavior. However, read further if you need to:
- Use OpenTF's [JSON syntax](/docs/language/syntax/json) with this
- Use OpenTofu's [JSON syntax](/docs/language/syntax/json) with this
type of resource.
- Create a reusable module that wraps this type of resource.

26
website/docs/language/checks/index.mdx
View File

@@ -7,7 +7,7 @@ description: >-
The `check` block can validate your infrastructure outside the usual resource lifecycle. Check blocks address a gap between post-apply and functional validation of infrastructure.
Check blocks allow you to define [custom conditions](/docs/language/expressions/custom-conditions) that execute on every OpenTF plan or apply operation without affecting the overall status of an operation. Check blocks execute as the last step of a plan or apply after OpenTF has planned or provisioned your infrastructure.
Check blocks allow you to define [custom conditions](/docs/language/expressions/custom-conditions) that execute on every OpenTofu plan or apply operation without affecting the overall status of an operation. Check blocks execute as the last step of a plan or apply after OpenTofu has planned or provisioned your infrastructure.
## Syntax
@@ -32,9 +32,9 @@ check "health_check" {
You can use any data source from any provider as a scoped data source within a `check` block.
A `check` block can optionally contain a nested (a.k.a. scoped) data source. This `data` block behaves like an external [data source](/docs/language/data-sources), except you can not reference it outside its enclosing `check` block. Additionally, if a scoped data source's provider raises any errors, they are masked as warnings and do not prevent OpenTF from continuing operation execution.
A `check` block can optionally contain a nested (a.k.a. scoped) data source. This `data` block behaves like an external [data source](/docs/language/data-sources), except you can not reference it outside its enclosing `check` block. Additionally, if a scoped data source's provider raises any errors, they are masked as warnings and do not prevent OpenTofu from continuing operation execution.
You can use a scoped data source to validate the status of a piece of infrastructure outside of the usual OpenTF resource lifecycle. [In the above example](#syntax), if the `placeholderplaceholderplaceholder_io` data source fails to load, you receive a warning instead of a blocking error, which would occur if you declared this data source outside of a `check` block.
You can use a scoped data source to validate the status of a piece of infrastructure outside of the usual OpenTofu resource lifecycle. [In the above example](#syntax), if the `placeholderplaceholderplaceholder_io` data source fails to load, you receive a warning instead of a blocking error, which would occur if you declared this data source outside of a `check` block.
#### Meta-Arguments
@@ -44,11 +44,11 @@ Scoped data sources support the `depends_on` and `provider` [meta-arguments](/do
The `depends_on` meta-argument can be particularly powerful when used within scoped data sources.
The first time OpenTF creates the _initial_ plan for our [previous example](#syntax), the plan fails because OpenTF has not applied its configuration yet. Meaning this test fails because OpenTF must still create the resources to make this website exist. Therefore, the first time OpenTF runs this check, it always throws a potentially distracting error message.
The first time OpenTofu creates the _initial_ plan for our [previous example](#syntax), the plan fails because OpenTofu has not applied its configuration yet. Meaning this test fails because OpenTofu must still create the resources to make this website exist. Therefore, the first time OpenTofu runs this check, it always throws a potentially distracting error message.
You can fix this by adding [`depends_on`](/docs/language/meta-arguments/depends_on) to your scoped data source, ensuring it depends on an essential piece of your site's infrastructure, such as the load balancer. The check returns `known after apply` until that crucial piece of your website is ready. This strategy avoids producing unnecessary warnings during setup, and the check executes during subsequent plans and applies.
One problem with this strategy is that if the resource your scoped data source `depends_on` changes, the check block returns `known after apply` until OpenTF has updated that resource. Depending on your use case, this behavior could be acceptable or problematic.
One problem with this strategy is that if the resource your scoped data source `depends_on` changes, the check block returns `known after apply` until OpenTofu has updated that resource. Depending on your use case, this behavior could be acceptable or problematic.
We recommend implementing the `depends_on` meta-argument if your scoped data source depends on the existence of another resource without referencing it directly.
@@ -56,7 +56,7 @@ We recommend implementing the `depends_on` meta-argument if your scoped data sou
Check blocks validate your custom assertions using `assert` blocks. Each `check` block must have at least one, but potentially many, `assert` blocks. Each `assert` block has a [`condition` attribute](/docs/language/expressions/custom-conditions#condition-expressions) and an [`error_message` attribute](/docs/language/expressions/custom-conditions#error-messages).
Unlike other [custom conditions](/docs/language/expressions/custom-conditions), assertions do not affect OpenTF's execution of an operation. A failed assertion reports a warning without halting the ongoing operation. This contrasts with other custom conditions, such as a postcondition, where OpenTF produces an error immediately, halting the operation and blocking the application or planning of future resources.
Unlike other [custom conditions](/docs/language/expressions/custom-conditions), assertions do not affect OpenTofu's execution of an operation. A failed assertion reports a warning without halting the ongoing operation. This contrasts with other custom conditions, such as a postcondition, where OpenTofu produces an error immediately, halting the operation and blocking the application or planning of future resources.
Condition arguments within `assert` blocks can refer to scoped data sources within the enclosing `check` block and any variables, resources, data sources, or module outputs within the current module.
@@ -68,21 +68,21 @@ Check blocks do not currently support [meta-arguments](/docs/language/resources/
## Continuous validation in TACOS (TF Automation and Collaboration Software)
TACOS (TF Automation and Collaboration Software) can automatically validate whether checks in a workspace’s configuration continue to pass after OpenTF provisions new infrastructure.
TACOS (TF Automation and Collaboration Software) can automatically validate whether checks in a workspace’s configuration continue to pass after OpenTofu provisions new infrastructure.
## Choosing Checks or other Custom Conditions
Check blocks offer the most _flexible_ validation solution within OpenTF. You can reference outputs, variables, resources, and data sources within check assertions. You can also use checks to model every alternate [Custom Condition](/docs/language/expressions/custom-conditions). However, that does not mean you should replace all your custom conditions with check blocks.
Check blocks offer the most _flexible_ validation solution within OpenTofu. You can reference outputs, variables, resources, and data sources within check assertions. You can also use checks to model every alternate [Custom Condition](/docs/language/expressions/custom-conditions). However, that does not mean you should replace all your custom conditions with check blocks.
There are major behavioral differences between check block assertions and other custom conditions, the main one being that check blocks do _not_ affect OpenTF's execution of an operation. You can use this non-blocking behavior to decide the best type of validation for your use case.
There are major behavioral differences between check block assertions and other custom conditions, the main one being that check blocks do _not_ affect OpenTofu's execution of an operation. You can use this non-blocking behavior to decide the best type of validation for your use case.
### Outputs and variables
[Output postconditions](/docs/language/expressions/custom-conditions#outputs) and [variable validations](/docs/language/expressions/custom-conditions#input-variable-validation) both make assertions around inputs and outputs.
This is one of the cases where you might want OpenTF to block further execution.
This is one of the cases where you might want OpenTofu to block further execution.
For example, it is not helpful for OpenTF to warn that an input variable is invalid after it applies an entire configuration with that input variable. In this case, a check block would warn of the invalid input variable _without_ interrupting the operation. A validation block for the same input variable would alert you of the invalid variable and halt the plan or apply operation.
For example, it is not helpful for OpenTofu to warn that an input variable is invalid after it applies an entire configuration with that input variable. In this case, a check block would warn of the invalid input variable _without_ interrupting the operation. A validation block for the same input variable would alert you of the invalid variable and halt the plan or apply operation.
### Resource Preconditions and Postconditions
@@ -109,8 +109,8 @@ data "http" "placeholderplaceholderplaceholder_io" {
Both the `check` and `postcondition` block examples validate that the website returns a `200` status code during a plan or an apply operation. The difference between the two blocks is how each handles failure.
If a `postcondition` block fails, it _blocks_ OpenTF from executing the current operation. If a `check` block fails, it _does not_ block OpenTF from executing an operation.
If a `postcondition` block fails, it _blocks_ OpenTofu from executing the current operation. If a `check` block fails, it _does not_ block OpenTofu from executing an operation.
If the above example's postcondition fails, it is impossible to recover from. OpenTF blocks any future plan or apply operations if your postcondition is unsatisfied during the planning stage. This problem occurs because the postcondition does not directly depend on OpenTF configuration, but instead on the complex interactions between multiple resources.
If the above example's postcondition fails, it is impossible to recover from. OpenTofu blocks any future plan or apply operations if your postcondition is unsatisfied during the planning stage. This problem occurs because the postcondition does not directly depend on OpenTofu configuration, but instead on the complex interactions between multiple resources.
We recommend using check blocks to validate the status of infrastructure as a whole. We only recommend using postconditions when you want a guarantee on a single resource based on that resource's configuration.

32
website/docs/language/data-sources/index.mdx
View File

@@ -1,14 +1,14 @@
---
description: >-
Data sources allow OpenTF to use external data, function output, and data
Data sources allow OpenTofu to use external data, function output, and data
from other configurations. Learn data resource arguments, behavior, and
lifecycle.
---
# Data Sources
_Data sources_ allow OpenTF to use information defined outside of OpenTF,
defined by another separate OpenTF configuration, or modified by functions.
_Data sources_ allow OpenTofu to use information defined outside of OpenTofu,
defined by another separate OpenTofu configuration, or modified by functions.
Each [provider](/docs/language/providers) may offer data sources
alongside its set of [resource](/docs/language/resources)
@@ -31,9 +31,9 @@ data "aws_ami" "example" {
}
```
A `data` block requests that OpenTF read from a given data source ("aws_ami")
A `data` block requests that OpenTofu read from a given data source ("aws_ami")
and export the result under the given local name ("example"). The name is used
to refer to this resource from elsewhere in the same OpenTF module, but has
to refer to this resource from elsewhere in the same OpenTofu module, but has
no significance outside of the scope of a module.
The data source and name together serve as an identifier for a given
@@ -47,8 +47,8 @@ all arguments defined specifically for [the `aws_ami` data source](https://regis
When distinguishing from data resources, the primary kind of resource (as declared
by a `resource` block) is known as a _managed resource_. Both kinds of resources
take arguments and export attributes for use in configuration, but while
managed resources cause OpenTF to create, update, and delete infrastructure
objects, data resources cause OpenTF only to _read_ objects. For brevity,
managed resources cause OpenTofu to create, update, and delete infrastructure
objects, data resources cause OpenTofu only to _read_ objects. For brevity,
managed resources are often referred to just as "resources" when the meaning
is clear from context.
@@ -59,28 +59,28 @@ the kind of object (or objects) it reads and what query constraint arguments
are available.
Each data source in turn belongs to a [provider](/docs/language/providers),
which is a plugin for OpenTF that offers a collection of resource types and
which is a plugin for OpenTofu that offers a collection of resource types and
data sources that most often belong to a single cloud or on-premises
infrastructure platform.
Most of the items within the body of a `data` block are defined by and
specific to the selected data source, and these arguments can make full
use of [expressions](/docs/language/expressions) and other dynamic
OpenTF language features.
OpenTofu language features.
However, there are some "meta-arguments" that are defined by OpenTF itself
However, there are some "meta-arguments" that are defined by OpenTofu itself
and apply across all data sources. These arguments often have additional
restrictions on what language features can be used with them, and are described
in more detail in the following sections.
## Data Resource Behavior
OpenTF reads data resources during the planning phase when possible, but
OpenTofu reads data resources during the planning phase when possible, but
announces in the plan when it must defer reading resources until the apply
phase to preserve the order of operations. OpenTF defers reading data
phase to preserve the order of operations. OpenTofu defers reading data
resources in the following situations:
* At least one of the given arguments is a managed resource attribute or
other value that OpenTF cannot predict until the apply step.
other value that OpenTofu cannot predict until the apply step.
* The data resource depends directly on a managed resource that itself has
planned changes in the current plan.
* The data resource has
@@ -97,7 +97,7 @@ be used in situations where values must be fully known.
While many data sources correspond to an infrastructure object type that
is accessed via a remote network API, some specialized data sources operate
only within OpenTF itself, calculating some results and exposing them
only within OpenTofu itself, calculating some results and exposing them
for use elsewhere.
For example, local-only data sources exist for
@@ -106,7 +106,7 @@ For example, local-only data sources exist for
[rendering AWS IAM policies](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document).
The behavior of local-only data sources is the same as all other data
sources, but their result data exists only temporarily during an OpenTF
sources, but their result data exists only temporarily during an OpenTofu
operation, and is re-calculated each time a new plan is created.
## Data Resource Dependencies
@@ -241,7 +241,7 @@ for more information.
If the arguments of a data instance contain no references to computed values,
such as attributes of resources that have not yet been created, then the
data instance will be read and its state updated during OpenTF's "refresh"
data instance will be read and its state updated during OpenTofu's "refresh"
phase, which by default runs prior to creating a plan. This ensures that the
retrieved data is available for use during planning and the diff will show
the real values obtained.

8
website/docs/language/expressions/conditionals.mdx
View File

@@ -47,15 +47,15 @@ Refer to [Custom Condition Checks](/docs/language/expressions/custom-conditions#
## Result Types
The two result values may be of any type, but they must both
be of the _same_ type so that OpenTF can determine what type the whole
be of the _same_ type so that OpenTofu can determine what type the whole
conditional expression will return without knowing the condition value.
If the two result expressions don't produce the same type then OpenTF will
If the two result expressions don't produce the same type then OpenTofu will
attempt to find a type that they can both convert to, and make those
conversions automatically if so.
For example, the following expression is valid and will always return a string,
because in OpenTF all numbers can convert automatically to a string using
because in OpenTofu all numbers can convert automatically to a string using
decimal digits:
```hcl
@@ -63,7 +63,7 @@ var.example ? 12 : "hello"
```
Relying on this automatic conversion behavior can be confusing for those who
are not familiar with OpenTF's conversion rules though, so we recommend
are not familiar with OpenTofu's conversion rules though, so we recommend
being explicit using type conversion functions in any situation where there may
be some uncertainty about the expected result type.

56
website/docs/language/expressions/custom-conditions.mdx
View File

@@ -12,14 +12,14 @@ This page explains the following:
- Creating [validation conditions](#input-variable-validation) for input variables
- Creating [preconditions and postconditions](#preconditions-and-postconditions) for resources, data sources, and outputs
- Writing effective [condition expressions](#condition-expressions) and [error messages](#error-messages)
- When OpenTF [evaluates custom conditions](#conditions-checked-only-during-apply) during the plan and apply cycle
- When OpenTofu [evaluates custom conditions](#conditions-checked-only-during-apply) during the plan and apply cycle
## Selecting a Custom Condition for your use case
OpenTF's different custom conditions are best suited to various situations. Use the following broad guidelines to select the best custom condition for your use case:
1. [Check blocks with assertions](#checks-with-assertions) validate your infrastructure as a whole. Additionally, check blocks do not prevent or block the overall execution of OpenTF operations.
OpenTofu's different custom conditions are best suited to various situations. Use the following broad guidelines to select the best custom condition for your use case:
1. [Check blocks with assertions](#checks-with-assertions) validate your infrastructure as a whole. Additionally, check blocks do not prevent or block the overall execution of OpenTofu operations.
1. [Validation conditions](#input-variable-validation) or [output postconditions](#preconditions-and-postconditions) can ensure your configuration's inputs and outputs meet specific requirements.
1. Resource [preconditions and postconditions](#preconditions-and-postconditions) can validate that OpenTF produces your configuration with predictable results.
1. Resource [preconditions and postconditions](#preconditions-and-postconditions) can validate that OpenTofu produces your configuration with predictable results.
For more information on when to use certain custom conditions, see [Choosing Between Preconditions and Postconditions](#choosing-between-preconditions-and-postconditions) and [Choosing Checks or Other Custom Conditions](/docs/language/checks#choosing-checks-or-other-custom-conditions).
@@ -28,7 +28,7 @@ For more information on when to use certain custom conditions, see [Choosing Bet
Add one or more `validation` blocks within the `variable` block to specify custom conditions. Each validation requires a [`condition` argument](#condition-expressions), an expression that must use the value of the variable to return `true` if the value is valid, or `false` if it is invalid. The expression can refer only to the containing variable and must not produce errors.
If the condition evaluates to `false`, OpenTF produces an [error message](#error-messages) that includes the result of the `error_message` expression. If you declare multiple validations, OpenTF returns error messages for all failed conditions.
If the condition evaluates to `false`, OpenTofu produces an [error message](#error-messages) that includes the result of the `error_message` expression. If you declare multiple validations, OpenTofu returns error messages for all failed conditions.
The following example checks whether the AMI ID has valid syntax.
@@ -64,13 +64,13 @@ variable "image_id" {
Use `precondition` and `postcondition` blocks to create custom rules for resources, data sources, and outputs.
OpenTF checks a precondition _before_ evaluating the object it is associated with and checks a postcondition _after_ evaluating the object. OpenTF evaluates custom conditions as early as possible, but must defer conditions that depend on unknown values until the apply phase. Refer to [Conditions Checked Only During Apply](#conditions-checked-only-during-apply) for more details.
OpenTofu checks a precondition _before_ evaluating the object it is associated with and checks a postcondition _after_ evaluating the object. OpenTofu evaluates custom conditions as early as possible, but must defer conditions that depend on unknown values until the apply phase. Refer to [Conditions Checked Only During Apply](#conditions-checked-only-during-apply) for more details.
### Usage
Each precondition and postcondition requires a [`condition` argument](#condition-expressions). This is an expression that must return `true` if the conditition is fufilled or `false` if it is invalid. The expression can refer to any other objects in the same module, as long as the references do not create cyclic dependencies. Resource postconditions can also use the [`self` object](#self-object) to refer to attributes of each instance of the resource where they are configured.
If the condition evaluates to `false`, OpenTF will produce an [error message](#error-messages) that includes the result of the `error_message` expression. If you declare multiple preconditions or postconditions, OpenTF returns error messages for all failed conditions.
If the condition evaluates to `false`, OpenTofu will produce an [error message](#error-messages) that includes the result of the `error_message` expression. If you declare multiple preconditions or postconditions, OpenTofu returns error messages for all failed conditions.
The following example uses a postcondition to detect if the caller accidentally provided an AMI intended for the wrong system component.
@@ -92,18 +92,18 @@ data "aws_ami" "example" {
The `lifecycle` block inside a `resource` or `data` block can include both `precondition` and `postcondition` blocks.
- OpenTF evaluates `precondition` blocks after evaluating existing `count` and `for_each` arguments. This lets OpenTF evaluate the precondition separately for each instance and then make `each.key`, `count.index`, etc. available to those conditions. OpenTF also evaluates preconditions before evaluating the resource's configuration arguments. Preconditions can take precedence over argument evaluation errors.
- OpenTF evaluates `postcondition` blocks after planning and applying changes to a managed resource, or after reading from a data source. Postcondition failures prevent changes to other resources that depend on the failing resource.
- OpenTofu evaluates `precondition` blocks after evaluating existing `count` and `for_each` arguments. This lets OpenTofu evaluate the precondition separately for each instance and then make `each.key`, `count.index`, etc. available to those conditions. OpenTofu also evaluates preconditions before evaluating the resource's configuration arguments. Preconditions can take precedence over argument evaluation errors.
- OpenTofu evaluates `postcondition` blocks after planning and applying changes to a managed resource, or after reading from a data source. Postcondition failures prevent changes to other resources that depend on the failing resource.
In most cases, we do not recommend including both a `data` block and a `resource` block that both represent the same object in the same configuration. Doing so can prevent OpenTF from understanding that the `data` block result can be affected by changes in the `resource` block. However, when you need to check a result of a `resource` block that the resource itself does not directly export, you can use a `data` block to check that object safely as long as you place the check as a direct `postcondition` of the `data` block. This tells OpenTF that the `data` block is serving as a check of an object defined elsewhere, allowing OpenTF to perform actions in the correct order.
In most cases, we do not recommend including both a `data` block and a `resource` block that both represent the same object in the same configuration. Doing so can prevent OpenTofu from understanding that the `data` block result can be affected by changes in the `resource` block. However, when you need to check a result of a `resource` block that the resource itself does not directly export, you can use a `data` block to check that object safely as long as you place the check as a direct `postcondition` of the `data` block. This tells OpenTofu that the `data` block is serving as a check of an object defined elsewhere, allowing OpenTofu to perform actions in the correct order.
#### Outputs
An `output` block can include a `precondition` block.
Preconditions can serve a symmetrical purpose to input variable `validation` blocks. Whereas input variable validation checks assumptions the module makes about its inputs, preconditions check guarantees that the module makes about its outputs. You can use preconditions to prevent OpenTF from saving an invalid new output value in the state. You can also use them to preserve a valid output value from the previous apply, if applicable.
Preconditions can serve a symmetrical purpose to input variable `validation` blocks. Whereas input variable validation checks assumptions the module makes about its inputs, preconditions check guarantees that the module makes about its outputs. You can use preconditions to prevent OpenTofu from saving an invalid new output value in the state. You can also use them to preserve a valid output value from the previous apply, if applicable.
OpenTF evaluates output value preconditions before evaluating the `value` expression to finalize the result. Preconditions can take precedence over potential errors in the `value` expression.
OpenTofu evaluates output value preconditions before evaluating the `value` expression to finalize the result. Preconditions can take precedence over potential errors in the `value` expression.
### Examples
@@ -114,7 +114,7 @@ The following example shows use cases for preconditions and postconditions. The
- **The EC2 instance must be allocated a public DNS hostname.** In Amazon Web Services, EC2 instances are assigned public DNS hostnames only if they belong to a virtual network configured in a certain way. The postcondition would detect if the selected virtual network is not configured correctly, prompting the user to debug the network settings.
- **The EC2 instance will have an encrypted root volume.** The precondition ensures that the root volume is encrypted, even though the software running in this EC2 instance would probably still operate as expected on an unencrypted volume. This lets OpenTF produce an error immediately, before any other components rely on the new EC2 instance.
- **The EC2 instance will have an encrypted root volume.** The precondition ensures that the root volume is encrypted, even though the software running in this EC2 instance would probably still operate as expected on an unencrypted volume. This lets OpenTofu produce an error immediately, before any other components rely on the new EC2 instance.
```hcl
@@ -161,7 +161,7 @@ data "aws_ebs_volume" "example" {
# Whenever a data resource is verifying the result of a managed resource
# declared in the same configuration, you MUST write the checks as
# postconditions of the data resource. This ensures OpenTF will wait
# postconditions of the data resource. This ensures OpenTofu will wait
# to read the data resource until after any changes to the managed resource
# have completed.
lifecycle {
@@ -198,7 +198,7 @@ We recommend using postconditions for guarantees, so that future maintainers can
You should also consider the following questions when creating preconditions and postconditions.
- Which resource or output value would be most helpful to report in the error message? OpenTF will always report errors in the location where the condition was declared.
- Which resource or output value would be most helpful to report in the error message? OpenTofu will always report errors in the location where the condition was declared.
- Which approach is more convenient? If a particular resource has many dependencies that all make an assumption about that resource, it can be pragmatic to declare that once as a post-condition of the resource, rather than declaring it many times as preconditions on each of the dependencies.
- Is it helpful to declare the same or similar conditions as both preconditions and postconditions? This can be useful if the postcondition is in a different module than the precondition because it lets the modules verify one another as they evolve independently.
@@ -208,7 +208,7 @@ You should also consider the following questions when creating preconditions and
You can add one or more `assert` blocks within a `check` block to verify custom conditions. Each assertion requires a [`condition` argument](#condition-expressions), a boolean expression that should return `true` if the intended assumption or guarantee is fulfilled or `false` if it does not. Your `condition` expression can refer to any resource, data source, or variable available to the surrounding `check` block.
The following example uses a check block with an assertion to verify the OpenTF website is healthy.
The following example uses a check block with an assertion to verify the OpenTofu website is healthy.
```hcl
check "health_check" {
@@ -223,17 +223,17 @@ check "health_check" {
}
```
If the condition evaluates to `false`, OpenTF produces an [error message](#error-messages) that includes the result of the `error_message` expression. If you declare multiple assertions, OpenTF returns error messages for all failed conditions.
If the condition evaluates to `false`, OpenTofu produces an [error message](#error-messages) that includes the result of the `error_message` expression. If you declare multiple assertions, OpenTofu returns error messages for all failed conditions.
### Continuous Validation in a cloud backend
A cloud backend can automatically check whether the checks in a workspace’s configuration continue to pass after OpenTF provisions the infrastructure. For example, you can write a `check` to continuously monitor the validity of an API gateway certificate. Continuous validation alerts you when the condition fails, so you can update the certificate and avoid errors the next time you want to update your infrastructure.
A cloud backend can automatically check whether the checks in a workspace’s configuration continue to pass after OpenTofu provisions the infrastructure. For example, you can write a `check` to continuously monitor the validity of an API gateway certificate. Continuous validation alerts you when the condition fails, so you can update the certificate and avoid errors the next time you want to update your infrastructure.
## Condition Expressions
Check assertions, input variable validation, preconditions, and postconditions all require a `condition` argument. This is a boolean expression that should return `true` if the intended assumption or guarantee is fulfilled or `false` if it does not.
You can use any of OpenTF's built-in functions or language operators
You can use any of OpenTofu's built-in functions or language operators
in a condition as long as the expression is valid and returns a boolean result. The following language features are particularly useful when writing condition expressions.
### Logical Operators
@@ -364,7 +364,7 @@ resource "aws_internet_gateway" "example" {
## Error Messages
Input variable validations, preconditions, and postconditions all must include the `error_message` argument. This contains the text that OpenTF will include as part of error messages when it detects an unmet condition.
Input variable validations, preconditions, and postconditions all must include the `error_message` argument. This contains the text that OpenTofu will include as part of error messages when it detects an unmet condition.
```
Error: Resource postcondition failed
@@ -384,21 +384,21 @@ error messages are supported, and lines with leading whitespace will not be
word wrapped.
We recommend writing error messages as one or more full sentences in a
style similar to OpenTF's own error messages. OpenTF will show the
style similar to OpenTofu's own error messages. OpenTofu will show the
message alongside the name of the resource that detected the problem and any
external values included in the condition expression.
## Conditions Checked Only During Apply
OpenTF evaluates custom conditions as early as possible.
OpenTofu evaluates custom conditions as early as possible.
Input variable validations can only refer to the variable value, so OpenTF always evaluates them immediately. Check assertions, preconditions, and postconditions depend on OpenTF evaluating whether the value(s) associated with the condition are known before or after applying the configuration.
Input variable validations can only refer to the variable value, so OpenTofu always evaluates them immediately. Check assertions, preconditions, and postconditions depend on OpenTofu evaluating whether the value(s) associated with the condition are known before or after applying the configuration.
- **Known before apply:** OpenTF checks the condition during the planning phase. For example, OpenTF can know the value of an image ID during planning as long as it is not generated from another resource.
- **Known after apply:** OpenTF delays checking that condition until the apply phase. For example, AWS only assigns the root volume ID when it starts an EC2 instance, so OpenTF cannot know this value until apply.
- **Known before apply:** OpenTofu checks the condition during the planning phase. For example, OpenTofu can know the value of an image ID during planning as long as it is not generated from another resource.
- **Known after apply:** OpenTofu delays checking that condition until the apply phase. For example, AWS only assigns the root volume ID when it starts an EC2 instance, so OpenTofu cannot know this value until apply.
During the apply phase, a failed _precondition_
will prevent OpenTF from implementing planned actions for the associated resource. However, a failed _postcondition_ will halt processing after OpenTF has already implemented these actions. The failed postcondition prevents any further downstream actions that rely on the resource, but does not undo the actions OpenTF has already taken.
will prevent OpenTofu from implementing planned actions for the associated resource. However, a failed _postcondition_ will halt processing after OpenTofu has already implemented these actions. The failed postcondition prevents any further downstream actions that rely on the resource, but does not undo the actions OpenTofu has already taken.
OpenTF typically has less information during the initial creation of a
full configuration than when applying subsequent changes. Therefore, OpenTF may check conditions during apply for initial creation and then check them during planning for subsequent updates.
OpenTofu typically has less information during the initial creation of a
full configuration than when applying subsequent changes. Therefore, OpenTofu may check conditions during apply for initial creation and then check them during planning for subsequent updates.

6
website/docs/language/expressions/dynamic-blocks.mdx
View File

@@ -76,13 +76,13 @@ The iterator object (`setting` in the example above) has two attributes:
A `dynamic` block can only generate arguments that belong to the resource type,
data source, provider or provisioner being configured. It is _not_ possible
to generate meta-argument blocks such as `lifecycle` and `provisioner`
blocks, since OpenTF must process these before it is safe to evaluate
blocks, since OpenTofu must process these before it is safe to evaluate
expressions.
The `for_each` value must be a collection with one element per desired
nested block. If you need to declare resource instances based on a nested
data structure or combinations of elements from multiple data structures you
can use OpenTF expressions and functions to derive a suitable value.
can use OpenTofu expressions and functions to derive a suitable value.
For some common examples of such situations, see the
[`flatten`](/docs/language/functions/flatten)
and
@@ -110,7 +110,7 @@ variable "load_balancer_origin_groups" {
If you were defining a resource whose type expects a block for each origin
group and then nested blocks for each origin within a group, you could ask
OpenTF to generate that dynamically using the following nested `dynamic`
OpenTofu to generate that dynamically using the following nested `dynamic`
blocks:
```hcl

16
website/docs/language/expressions/for.mdx
View File

@@ -77,7 +77,7 @@ For example, the resulting value might be as follows:
```
A `for` expression alone can only produce either an object value or a tuple
value, but OpenTF's automatic type conversion rules mean that you can
value, but OpenTofu's automatic type conversion rules mean that you can
typically use the results in locations where lists, maps, and sets are expected.
## Filtering Elements
@@ -118,16 +118,16 @@ locals {
## Element Ordering
Because `for` expressions can convert from unordered types (maps, objects, sets)
to ordered types (lists, tuples), OpenTF must choose an implied ordering
to ordered types (lists, tuples), OpenTofu must choose an implied ordering
for the elements of an unordered collection.
For maps and objects, OpenTF sorts the elements by key or attribute name,
For maps and objects, OpenTofu sorts the elements by key or attribute name,
using lexical sorting.
For sets of strings, OpenTF sorts the elements by their value, using
For sets of strings, OpenTofu sorts the elements by their value, using
lexical sorting.
For sets of other types, OpenTF uses an arbitrary ordering that may change in future versions. We recommend converting the expression result into a set to make it clear elsewhere in the configuration that the result is unordered. You can use [the `toset` function](/docs/language/functions/toset)
For sets of other types, OpenTofu uses an arbitrary ordering that may change in future versions. We recommend converting the expression result into a set to make it clear elsewhere in the configuration that the result is unordered. You can use [the `toset` function](/docs/language/functions/toset)
to concisely convert a `for` expression result to be of a set type.
```hcl
@@ -138,10 +138,10 @@ toset([for e in var.set : e.example])
If the result type is an object (using `{` and `}` delimiters) then normally
the given key expression must be unique across all elements in the result,
or OpenTF will return an error.
or OpenTofu will return an error.
Sometimes the resulting keys are _not_ unique, and so to support that situation
OpenTF supports a special _grouping mode_ which changes the result to support
OpenTofu supports a special _grouping mode_ which changes the result to support
multiple elements per key.
To activate grouping mode, add the symbol `...` after the value expression.
@@ -189,7 +189,7 @@ map of lists of strings, such as the following:
}
```
Due to [the element ordering rules](#element-ordering), OpenTF will sort
Due to [the element ordering rules](#element-ordering), OpenTofu will sort
the users lexically by username as part of evaluating the `for` expression,
and so the usernames associated with each role will be lexically sorted
after grouping.

Some files were not shown because too many files have changed in this diff Show More