- OpenTofu Settings
- Backends
- remote
Backend Type: remote
We recommend using the cloud
built-in integration instead of this backend. The cloud
option includes an improved user experience and more features.
The remote backend is unique among all other OpenTofu backends because it can both store state snapshots and execute CLI-driven run workflow operations for TF Automation and Collaboration Software (TACOS) backends. It used to be called an "enhanced" backend.
If your TACOS provider enables full remote operations, you can execute commands such as tofu plan
or tofu apply
within the TACOS runtime environment, with log output streaming directly to your local terminal. Remote plans and applies use variable values from the associated remote workspace.
You can also use TACOS with local operations, where only state is stored in the TACOS remote backend.
Command Support
Features implementation might vary between different TACOS.
The remote backend supports the following OpenTofu commands:
apply
console
destroy
fmt
get
graph
import
init
output
plan
providers
show
state
(supports all sub-commands: list, mv, pull, push, rm, show)taint
untaint
validate
version
workspace
Workspaces
The remote backend can work with either a single remote workspace, or with multiple similarly-named remote workspaces (like networking-dev
and networking-prod
). The workspaces
block of the backend configuration
determines which mode it uses:
-
To use a single remote workspace, set
workspaces.name
to the remote workspace's full name (likenetworking-prod
). -
To use multiple remote workspaces, set
workspaces.prefix
to a prefix used in all of the desired remote workspace names. For example, setprefix = "networking-"
to use remote workspaces with names likenetworking-dev
andnetworking-prod
. This is helpful when mapping multiple OpenTofu CLI workspaces used in a single OpenTofu configuration to multiple remote workspaces.
The backend configuration requires either name
or prefix
. Omitting both or
setting both results in a configuration error.
If previous state is present when you run tofu init
and the corresponding
remote workspaces are empty or absent, OpenTofu will create workspaces and
update the remote state accordingly. However, if your workspace requires variables or a specific version of OpenTofu for remote operations, we
recommend that you create your remote workspaces on TACOS before
running any remote operations against them.
Workspace Names
OpenTofu uses shortened names without the common prefix to interact with workspaces on the command line. For example, if prefix = "networking-"
, use tofu workspace select prod
to switch to the OpenTofu CLI workspace prod
within the current configuration. However, remote OpenTofu operations such as plan
and apply
for that OpenTofu CLI workspace will take place in the remote workspace networking-prod
.
Because of this, the terraform.workspace
interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called networking-prod
created with prefix = "networking-"
the expression produces the following:
- For local operations,
terraform.workspace
=prod
- For remote operations,
terraform.workspace
=networking-prod
Example Configurations
We recommend omitting the token from the configuration, and instead using
tofu login
or manually configuring
credentials
in the CLI config file.
Basic Configuration
Using CLI Input
Backend configuration file:
Running tofu init
with the backend file:
Data Source Configuration
Configuration Variables
We recommend using environment variables to supply credentials and other sensitive data. If you use -backend-config
or hardcode these values directly in your configuration, OpenTofu will include these values in both the .terraform
subdirectory and in plan files. Refer to Credentials and Sensitive Data for details.
The following configuration options are supported:
-
hostname
- (Required) The remote backend hostname to connect to. -
organization
- (Required) The name of the organization containing the targeted workspace(s). -
token
- (Optional) The token used to authenticate with the remote backend. We recommend omitting the token from the configuration, and instead usingtofu login
or manually configuringcredentials
in the CLI config file. -
workspaces
- (Required) A block specifying which remote workspace(s) to use. Theworkspaces
block supports the following keys:name
- (Optional) The full name of one remote workspace. When configured, only the default workspace can be used. This option conflicts withprefix
.prefix
- (Optional) A prefix used in the names of one or more remote workspaces, all of which can be used with this configuration. The full workspace names are used in TACOS, and the short names (minus the prefix) are used on the command line for OpenTofu CLI workspaces. If omitted, only the default workspace can be used. This option conflicts withname
.
You must use the name
key when configuring a terraform_remote_state
data source that retrieves state from another remote workspace. The prefix
key is only
intended for use when configuring an instance of the remote backend.
Command Line Arguments
For configurations that include a backend "remote"
block, commands that
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 OpenTofu versions agree, making an operation proceed even when there is a mismatch.Normally state-modification operations require using a local version of OpenTofu CLI which is compatible with the OpenTofu version selected for the remote workspace as part of its settings. This is to avoid the local operation creating a new state snapshot which the workspace's remote execution environment would then be unable to decode.
Overriding this check can result in a remote workspace that is no longer able to complete remote operations, so we recommend against using this option.
Excluding Files from Upload with .terraformignore
When executing a remote plan
or apply
in a CLI-driven run,
an archive of your configuration directory is uploaded to TACOS. You can define
paths to ignore from upload via a .terraformignore
file at the root of your configuration directory. If this file is not present, the archive will exclude the following by default:
.git/
directories.terraform/
directories (exclusive of.terraform/modules
)
The .terraformignore
file can include rules as one would include 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 that unlike .gitignore
, only the .terraformignore
at the root of the configuration
directory is considered.