9.1 KiB
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: The remote backend was introduced in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, 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.
The remote backend is unique among all other Terraform backends because it can both store state snapshots and execute operations for Terraform Cloud's CLI-driven run workflow. It used to be called an "enhanced" backend.
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 (likenetworking
). -
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 Terraform cloud workspaces with names likenetworking-dev
andnetworking-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 usingterraform 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 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 withname
.
-> 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.