4.1 KiB
layout | page_title | sidebar_current | description |
---|---|---|---|
backend-types | 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
Kind: Enhanced
The remote backend stores state and runs operations remotely. When running
terraform plan
or terraform apply
with this backend, the actual execution
occurs in Terraform Enterprise, with log output streaming to the local terminal.
To use this backend you need a Terraform Enterprise account on app.terraform.io or have a private instance of Terraform Enterprise (version v201809-1 or newer).
-> Preview Release: As of Terraform 0.11.8, the remote backend is a preview release and we do not recommend using it with production workloads. Please continue to use the existing Terraform Enterprise backend for production workspaces.
Command Support
Currently the remote backend supports the following Terraform commands:
apply
fmt
get
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 (likenetworking
). -
To use multiple workspaces, set
workspaces.prefix
to a prefix used in all of the desired remote workspace names. For example, setprefix = "networking-"
to use a group of workspaces with names likenetworking-dev
andnetworking-prod
.When interacting with workspaces on the command line, Terraform uses shortened names without the common prefix. For example, if
prefix = "networking-"
, useterraform workspace select prod
to switch to thenetworking-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 ascredentials
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 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 withname
.