github.com/kcburge/terraform@v0.11.12-beta1/website/docs/backends/types/remote.html.md (about) 1 --- 2 layout: "backend-types" 3 page_title: "Backend Type: remote" 4 sidebar_current: "docs-backends-types-enhanced-remote" 5 description: |- 6 Terraform can store the state and run operations remotely, making it easier to version and work with in a team. 7 --- 8 9 # remote 10 11 **Kind: Enhanced** 12 13 The remote backend stores state and runs operations remotely. When running 14 `terraform plan` or `terraform apply` with this backend, the actual execution 15 occurs in Terraform Enterprise, with log output streaming to the local terminal. 16 17 To use this backend you need a Terraform Enterprise account on 18 [app.terraform.io](https://app.terraform.io) or have a private instance of 19 Terraform Enterprise (version v201809-1 or newer). 20 21 -> **Preview Release**: As of Terraform 0.11.8, the remote backend is a preview 22 release and we do not recommend using it with production workloads. Please 23 continue to use the existing [Terraform 24 Enterprise](terraform-enterprise.html) backend for production workspaces. 25 26 ## Command Support 27 28 Currently the remote backend supports the following Terraform commands: 29 30 - `apply` 31 - `console` 32 - `destroy` (requires manually setting `CONFIRM_DESTROY=1` on the workspace) 33 - `fmt` 34 - `get` 35 - `graph` 36 - `import` 37 - `init` 38 - `output` 39 - `plan` 40 - `providers` 41 - `show` 42 - `taint` 43 - `untaint` 44 - `validate` 45 - `version` 46 - `workspace` 47 48 ## Workspaces 49 50 The remote backend can work with either a single remote workspace, or with 51 multiple similarly-named remote workspaces (like `networking-dev` and 52 `networking-prod`). The `workspaces` block of the backend configuration 53 determines which mode it uses: 54 55 - To use a single workspace, set `workspaces.name` to the remote workspace's 56 full name (like `networking`). 57 58 - To use multiple workspaces, set `workspaces.prefix` to a prefix used in 59 all of the desired remote workspace names. For example, set 60 `prefix = "networking-"` to use a group of workspaces with names like 61 `networking-dev` and `networking-prod`. 62 63 When interacting with workspaces on the command line, Terraform uses 64 shortened names without the common prefix. For example, if 65 `prefix = "networking-"`, use `terraform workspace select prod` to switch to 66 the `networking-prod` workspace. 67 68 The backend configuration requires either `name` or `prefix`. Omitting both or 69 setting both results in a configuration error. 70 71 If previous state is present when you run `terraform init` and the corresponding 72 remote workspaces are empty or absent, Terraform will create workspaces and/or 73 update the remote state accordingly. 74 75 ## Example Configuration 76 77 ```hcl 78 # Using a single workspace: 79 terraform { 80 backend "remote" { 81 hostname = "app.terraform.io" 82 organization = "company" 83 84 workspaces { 85 name = "my-app-prod" 86 } 87 } 88 } 89 90 # Using multiple workspaces: 91 terraform { 92 backend "remote" { 93 hostname = "app.terraform.io" 94 organization = "company" 95 96 workspaces { 97 prefix = "my-app-" 98 } 99 } 100 } 101 ``` 102 103 ## Example Reference 104 105 ```hcl 106 data "terraform_remote_state" "foo" { 107 backend = "remote" 108 109 config { 110 organization = "company" 111 112 workspaces { 113 name = "workspace" 114 } 115 } 116 } 117 ``` 118 119 ## Configuration variables 120 121 The following configuration options are supported: 122 123 * `hostname` - (Optional) The remote backend hostname to connect to. Defaults 124 to app.terraform.io. 125 * `organization` - (Required) The name of the organization containing the 126 targeted workspace(s). 127 * `token` - (Optional) The token used to authenticate with the remote backend. 128 We recommend omitting the token from the configuration, and instead setting it 129 as `credentials` in the 130 [CLI config file](/docs/commands/cli-config.html#credentials). 131 * `workspaces` - (Required) A block specifying which remote workspace(s) to use. 132 The `workspaces` block supports the following keys: 133 134 * `name` - (Optional) The full name of one remote workspace. When configured, 135 only the default workspace can be used. This option conflicts with `prefix`. 136 * `prefix` - (Optional) A prefix used in the names of one or more remote 137 workspaces, all of which can be used with this configuration. The full 138 workspace names are used in Terraform Enterprise, and the short names 139 (minus the prefix) are used on the command line. If omitted, only the 140 default workspace can be used. This option conflicts with `name`.