Cloud Backend Settings

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 tofu 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 OpenTofu configuration when running plans and applies.

After adding or changing a cloud block, you must run tofu init.

The cloud Block

The cloud block is a nested block within the top-level terraform settings block. It specifies which cloud backend workspaces to use for the current working directory.

terraform {
  cloud {
    organization = "my-org"
    hostname = "app.example.org"

    workspaces {
      project = "networking-development"
      tags = ["networking", "source:cli"]
    }
  }
}

The cloud block also has some special restrictions:

• A configuration can only provide one cloud block.
• A cloud block cannot be used with state backends. A configuration can use one or the other, but not both.
• A cloud block cannot refer to named values (like input variables, locals, or data source attributes).

The cloud block only affects 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.

Arguments

The cloud block supports the following configuration arguments:

• hostname - (Required) The hostname of the cloud backend.

• organization - (Required) The name of the organization containing the workspace(s) the current configuration should use.

• workspaces - (Required) A nested block that specifies which remote cloud backend workspaces to use for the current configuration. The workspaces block must contain exactly one of the following arguments, each denoting a strategy for how workspaces should be mapped:

  • tags - (Optional) A set of 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 tofu workspace commands 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. 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. 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 tofu login or manually configuring credentials in the CLI config file.

Environment Variables

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. :::

Use the following environment variables to configure the cloud block:

• 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. 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. 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. 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 selected TF_WORKSPACE must have a set of tags that match the tags in the cloud block. This variable also selects the workspace in your local environment. Refer to TF_WORKSPACE for details.

Excluding Files from Upload with .terraformignore

When executing a remote plan or apply in a CLI-driven run, a copy of your configuration directory is uploaded to the cloud backend. You can define paths to exclude from upload by adding a .terraformignore file at the root of your configuration directory. If this file is not present, the upload will exclude the following by default:

• .git/ directories
• .terraform/ directories (exclusive of .terraform/modules)

The rules in .terraformignore file resemble the rules allowed in a .gitignore file:

• Comments (starting with #) or blank lines are ignored.
• End a pattern with a forward slash / to specify a directory.
• Negate a pattern by starting it with an exclamation point !.

:::note Unlike .gitignore, only the .terraformignore at the root of the configuration directory is considered. :::