terraform/website/docs/language/settings/backends/remote.html.md

layout	page_title	sidebar_current	description
language	Backend Type: remote	docs-backends-types-enhanced-remote	Terraform can store the state and run operations remotely, making it easier to version and work with in a team.

remote

-> Note: With the release of Terraform v1.1.0, we recommend using the Terraform Cloud's built-in cloud integration instead of this backend. The cloud option includes an improved user experience and more features.

-> Note: This backend is unique among all other Terraform backends in that it has the ability to execute operations for Terraform Cloud's CLI-driven run workflow, rather than only store state snapshots. (The documentation used to refer to this as "enhanced" backend behavior, but it's simpler to describe it as a quirk of the remote backend.)

-> Note: The remote backend requires Terraform v0.11.13 or newer, and requires either a Terraform Cloud account on app.terraform.io or a Terraform Enterprise instance (version v201809-1 or newer).

When using full remote operations, operations like terraform plan or terraform apply can be executed in Terraform Cloud's run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated Terraform Cloud workspace.

Terraform Cloud can also be used with local operations, in which case only state is stored in the Terraform Cloud backend.

Command Support

Currently the remote backend supports the following Terraform commands:

• apply
• console (supported in Terraform >= v0.11.12)
• destroy
• fmt
• get
• graph (supported in Terraform >= v0.11.12)
• import (supported in Terraform >= v0.11.12)
• 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 Terraform Cloud 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 Terraform Cloud workspace, set workspaces.name to the remote workspace's full name (like networking).

• 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 Terraform cloud workspaces with names like networking-dev and networking-prod. This is helpful when mapping multiple Terraform CLI workspaces used in a single Terraform configuration to multiple Terraform Cloud workspaces.

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 Terraform CLI workspace prod within the current configuration. Remote Terraform operations such as plan and apply executed against that Terraform CLI workspace will be executed in the Terraform Cloud workspace networking-prod.

Additionally, the terraform.workspace expression shouldn't be used in Terraform configurations that use Terraform 1.0.x or earlier and run remote operations against Terraform Cloud workspaces. The reason for this is that prior to Terraform 1.1.0, Terraform Cloud workspaces only used the single default Terraform CLI workspace internally. In other words, if your Terraform configuration used ${terraform.workspace} to return dev or prod, remote runs in Terraform Cloud would always evaluate it as default regardless of which workspace you had set with the terraform workspace select command. That would most likely not be what you wanted. (It is ok to use terraform.workspace in local operations, and with remote operations in workspaces configured to use Terraform 1.1.0 or later.)

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. However, if your workspace needs variables set or requires a specific version of Terraform for remote operations, we recommend that you create your remote workspaces on Terraform Cloud before running any remote operations against them.

Example Configurations

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

Basic 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-"
    }
  }
}

Using CLI Input

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

  backend "remote" {}
}

Backend configuration file:

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

Running terraform init with the backend file:

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

Data Source Configuration

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 using terraform 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 Terraform Cloud, and the short names (minus the prefix) are used on the command line for Terraform 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 Terraform Cloud 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 Terraform 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 Terraform versions agree, making an operation proceed even when there is a mismatch.

  Normally state-modification operations require using a local version of Terraform CLI which is compatible with the Terraform 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 Terraform Cloud workspace that is no longer able to complete remote operations, so we recommend against using this option.

Excluding Files from Upload with .terraformignore

-> Version note: .terraformignore support was added in Terraform 0.12.11.

When executing a remote plan or apply in a CLI-driven run, an archive of your configuration directory is uploaded to Terraform Cloud. 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.