» remote

Kind: Enhanced

Note: We recommend using Terraform v0.11.13 or newer with this backend. This backend requires either a Terraform Enterprise account on app.terraform.io or a private instance of Terraform Enterprise (version v201809-1 or newer).

The remote backend stores state and runs operations in Terraform Enterprise.

When used with a Pro or Premium tier Terraform Enterprise account, operations like terraform plan or terraform apply are executed in Terraform Enterprise's run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated Terraform Enterprise workspace.

When used with a free Terraform Enterprise account, operations are executed on the local machine and state is stored in Terraform Enterprise.

» Command Support

Currently the remote backend supports the following Terraform commands:

apply
console (supported in Terraform >= v0.11.12)
destroy (requires manually setting CONFIRM_DESTROY=1 on the workspace)
fmt
get
graph (supported in Terraform >= v0.11.12)
import (supported in Terraform >= v0.11.12)
init
output
plan
providers
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 workspace, set workspaces.name to the remote workspace's full name (like networking).
To use multiple workspaces, set workspaces.prefix to a prefix used in all of the desired remote workspace names. For example, set prefix = "networking-" to use a group of workspaces with names like networking-dev and networking-prod.

When interacting with workspaces on the command line, Terraform uses shortened names without the common prefix. For example, if prefix = "networking-", use terraform workspace select prod to switch to the networking-prod workspace.

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 terraform init and the corresponding remote workspaces are empty or absent, Terraform will create workspaces and/or update the remote state accordingly.

» Example Configuration

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

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

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

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

» Example Reference

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

  config = {
    organization = "company"

    workspaces {
      name = "workspace"
    }
  }
}

» Configuration variables

The following configuration options are supported:

hostname - (Optional) The remote backend hostname to connect to. Defaults to app.terraform.io.
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 setting it as 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 Terraform Enterprise, and the short names (minus the prefix) are used on the command line. If omitted, only the default workspace can be used. This option conflicts with name.