Skip to main content

remote

-> Note: 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 OpenTF backends because it can both store state snapshots and execute operations for TACOS (TF Automation and Collaboration Software) CLI-driven run workflow. It used to be called an "enhanced" backend.

When using full remote operations, operations like opentf plan or opentf apply can be executed in TACOS (TF Automation and Collaboration Software) run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated remote workspace.

You can also use TACOS (TF Automation and Collaboration Software) with local operations, in which case only state is stored in the remote backend.

Command Support​

The remote backend supports the following OpenTF 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 (like networking-prod).

  • To use multiple remote workspaces, set workspaces.prefix to a prefix used in all of the desired remote workspace names. For example, set prefix = "networking-" to use remote workspaces with names like networking-dev and networking-prod. This is helpful when mapping multiple OpenTF CLI workspaces used in a single OpenTF 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 opentf init and the corresponding remote workspaces are empty or absent, OpenTF will create workspaces and update the remote state accordingly. However, if your workspace requires variables or a specific version of OpenTF for remote operations, we recommend that you create your remote workspaces on TACOS (TF Automation and Collaboration Software) before running any remote operations against them.

Workspace Names​

OpenTF uses shortened names without the common prefix to interact with workspaces on the command line. For example, if prefix = "networking-", use opentf workspace select prod to switch to the OpenTF CLI workspace prod within the current configuration. However, remote OpenTF operations such as plan and apply for that OpenTF CLI workspace will take place in the remote workspace networking-prod.

Because of this, the terraform.workspace interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called networking-prod created with prefix = "networking-" the expression produces the following:

  • For local operations, terraform.workspace = prod
  • For remote operations, terraform.workspace= networking-prod

Determining Run Environment​

If you need to determine whether a run is local or remote in your OpenTF configuration, we recommend using run environment variables. The example below uses TFC_RUN_ID.

output "current_workspace_name" {
  value = terraform.workspace
}

variable "TFC_RUN_ID" {
  type    = string
  default = ""
}

output "remote_execution_determine" {
  value = "Remote run environment? %{if var.TFC_RUN_ID != ""}Yes%{else}No this is local%{endif}!"
}

Example Configurations​

-> Note: We recommend omitting the token from the configuration, and instead using opentf login or manually configuring credentials in the CLI config file.

Basic Configuration​

# Using a single workspace:
terraform {
  backend "remote" {
    hostname = "app.example.io"
    organization = "company"

    workspaces {
      name = "my-app-prod"
    }
  }
}

# Using multiple workspaces:
terraform {
  backend "remote" {
    hostname = "app.example.io"
    organization = "company"

    workspaces {
      prefix = "my-app-"
    }
  }
}

Using CLI Input​

# main.tf
terraform {
  required_version = "~> 0.12.0"

  backend "remote" {}
}

Backend configuration file:

# config.remote.tfbackend
workspaces { name = "workspace" }
hostname     = "app.example.io"
organization = "company"

Running opentf init with the backend file:

opentf init -backend-config=config.remote.tfbackend

Data Source Configuration​

data "terraform_remote_state" "foo" {
  backend = "remote"

  config = {
    organization = "company"

    workspaces = {
      name = "workspace"
    }
  }
}

Configuration Variables​

!> Warning: We recommend using environment variables to supply credentials and other sensitive data. If you use -backend-config or hardcode these values directly in your configuration, OpenTF will include these values in both the .terraform subdirectory and in plan files. Refer to Credentials and Sensitive Data 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 using opentf login or manually configuring credentials in the CLI config file.

  • workspaces - (Required) A block specifying which remote workspace(s) to use. The workspaces 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 with prefix.
    • 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 (TF Automation and Collaboration Software), and the short names (minus the prefix) are used on the command line for OpenTF CLI workspaces. If omitted, only the default workspace can be used. This option conflicts with name.

-> Note: 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 OpenTF state and then push them back up to the remote workspace accept the following option to modify that behavior:

  • -ignore-remote-version - Override checking that the local and remote OpenTF versions agree, making an operation proceed even when there is a mismatch.

    Normally state-modification operations require using a local version of OpenTF CLI which is compatible with the OpenTF 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 (TF Automation and Collaboration Software). You can define paths to ignore from upload via a .terraformignore file at the root of your configuration directory. If this file is not present, the archive will exclude the following by default:

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