The remote backend stores state and runs operations remotely. In order
use this backend you need a Terraform Enterprise account or have Private
Terraform Enterprise running on-premises.
The remote backend stores state and runs operations remotely. When running
`terraform plan` with this backend, the actual execution occurs in Terraform
Enterprise, with log output streaming to the local terminal.
### Commands
To use this backend you need a Terraform Enterprise account on
[app.terraform.io](https://app.terraform.io) or a private instance of Terraform
Enterprise.
## Command Support
Currently the remote backend supports the following Terraform commands:
1. fmt
2. get
3. init
4. output
5. plan
6. providers
7. show
8. taint
9. untaint
10. validate
11. version
11. workspace
### Workspaces
To work with remote workspaces we need either a name or a prefix. You will
get a configuration error when neither or both options are configured.
#### Name
When a name is provided, that name is used to make a one-to-one mapping
between your local “default” workspace and a named remote workspace. This
option assumes you are not using workspaces when working with TF, so it
will act as a backend that does not support names states.
#### Prefix
When a prefix is provided it will be used to filter and map workspaces that
can be used with a single configuration. This allows you to dynamically
filter and map all remote workspaces with a matching prefix.
The prefix is added when making calls to the remote backend and stripped
again when receiving the responses. This way any locally used workspace
names will remain the same short names (e.g. “tst”, “acc”) while the remote
names will be mapped by adding the prefix.
It is assumed that you are only using named workspaces when working with
Terraform and so the “default” workspace is ignored in this case. If there
is a state file for the “default” config, this will give an error during
`terraform init`. If the default workspace is selected when running the
`init` command, the `init` process will succeed but will end with a message
that tells you how to select an existing workspace or create a new one.
- `fmt`
- `get`
- `init`
- `output`
- `plan`
- `providers`
- `show`
- `taint`
- `untaint`
- `validate`
- `version`
- `workspace`
Importantly, it does not support the `apply` command.
## 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-prod`).
- 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.
In prefix mode, the special `default` workspace is disabled. Before running
`terraform init`, ensure that there is no state stored for the local
`default` workspace and that a non-default workspace is currently selected;
otherwise, the initialization will fail.
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
```hcl
# 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 {
name = "workspace"
prefix = "my-app-"
}
}
@ -84,7 +104,7 @@ data "terraform_remote_state" "foo" {
organization = "company"
workspaces {
name = "workspace"
name = "my-app-prod"
}
}
}
@ -99,16 +119,16 @@ The following configuration options are supported:
* `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 which can be set as `credentials` in the
We recommend omitting the token from the configuration, and instead setting it
Nick Fagerlund
8 years ago
committed by
Martin Atkins