171 lines
4.8 KiB
Markdown
171 lines
4.8 KiB
Markdown
---
|
|
layout: "backend-types"
|
|
page_title: "Backend Type: remote"
|
|
sidebar_current: "docs-backends-types-enhanced-remote"
|
|
description: |-
|
|
Terraform can store the state and run operations remotely, making it easier to version and work with in a team.
|
|
---
|
|
|
|
# remote
|
|
|
|
**Kind: Enhanced**
|
|
|
|
-> **Note:** We recommend using Terraform v0.11.13 or newer with this
|
|
backend. This backend requires either a Terraform Cloud account on
|
|
[app.terraform.io](https://app.terraform.io) or a Terraform Enterprise instance
|
|
(version v201809-1 or newer).
|
|
|
|
The remote backend stores state and runs operations in Terraform Cloud.
|
|
|
|
When used with a Pro or Premium tier Terraform Cloud account, operations
|
|
like `terraform plan` or `terraform apply` are 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.
|
|
|
|
When used with a free Terraform Cloud account, operations are executed on
|
|
the local machine and state is stored in Terraform Cloud.
|
|
|
|
## 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`
|
|
- `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 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
|
|
|
|
```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 {
|
|
prefix = "my-app-"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Example Reference
|
|
|
|
```hcl
|
|
data "terraform_remote_state" "foo" {
|
|
backend = "remote"
|
|
|
|
config = {
|
|
organization = "company"
|
|
|
|
workspaces {
|
|
name = "workspace"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Example configuration using CLI input
|
|
|
|
```hcl
|
|
# main.tf
|
|
terraform {
|
|
required_version = "~> 0.12.0"
|
|
|
|
backend "remote" {}
|
|
}
|
|
```
|
|
|
|
Backend configuration file:
|
|
|
|
```hcl
|
|
# backend.hcl
|
|
workspaces { name = "workspace" }
|
|
hostname = "app.terraform.io"
|
|
organization = "company"
|
|
```
|
|
|
|
Running `terraform init` with the backend file:
|
|
|
|
```sh
|
|
terraform init -backend-config=backend.hcl
|
|
```
|
|
|
|
## 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](/docs/commands/cli-config.html#credentials).
|
|
* `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. If omitted, only the
|
|
default workspace can be used. This option conflicts with `name`.
|