1--- 2layout: "language" 3page_title: "Backend Type: remote" 4sidebar_current: "docs-backends-types-enhanced-remote" 5description: |- 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-> **Note:** We recommend using Terraform v0.11.13 or newer with this 14backend. This backend requires either a Terraform Cloud account on 15[app.terraform.io](https://app.terraform.io) or a Terraform Enterprise instance 16(version v201809-1 or newer). 17 18The remote backend stores Terraform state and may be used to run operations in Terraform Cloud. 19 20When using full remote operations, operations like `terraform plan` or `terraform apply` can be executed in Terraform 21Cloud's run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated Terraform Cloud workspace. 22 23Terraform Cloud can also be used with local operations, in which case only state is stored in the Terraform Cloud backend. 24 25## Command Support 26 27Currently the remote backend supports the following Terraform commands: 28 29- `apply` 30- `console` (supported in Terraform >= v0.11.12) 31- `destroy` 32- `fmt` 33- `get` 34- `graph` (supported in Terraform >= v0.11.12) 35- `import` (supported in Terraform >= v0.11.12) 36- `init` 37- `output` 38- `plan` 39- `providers` 40- `show` 41- `state` (supports all sub-commands: list, mv, pull, push, rm, show) 42- `taint` 43- `untaint` 44- `validate` 45- `version` 46- `workspace` 47 48## Workspaces 49 50The remote backend can work with either a single remote Terraform Cloud workspace, 51or with multiple similarly-named remote workspaces (like `networking-dev` 52and `networking-prod`). The `workspaces` block of the backend configuration 53determines which mode it uses: 54 55- To use a single remote Terraform Cloud workspace, set `workspaces.name` to the 56 remote workspace's full name (like `networking`). 57 58- To use multiple remote 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 Terraform cloud workspaces with 61 names like `networking-dev` and `networking-prod`. This is helpful when 62 mapping multiple Terraform CLI [workspaces](/docs/language/state/workspaces.html) 63 used in a single Terraform configuration to multiple Terraform Cloud 64 workspaces. 65 66When interacting with workspaces on the command line, Terraform uses 67shortened names without the common prefix. For example, if 68`prefix = "networking-"`, use `terraform workspace select prod` to switch to 69the Terraform CLI workspace `prod` within the current configuration. Remote 70Terraform operations such as `plan` and `apply` executed against that Terraform 71CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`. 72 73Additionally, the [`${terraform.workspace}`](/docs/language/state/workspaces.html#current-workspace-interpolation) 74interpolation sequence should be removed from Terraform configurations that run 75remote operations against Terraform Cloud workspaces. The reason for this is that 76each Terraform Cloud workspace currently only uses the single `default` Terraform 77CLI workspace internally. In other words, if your Terraform configuration 78used `${terraform.workspace}` to return `dev` or `prod`, remote runs in Terraform Cloud 79would always evaluate it as `default` regardless of 80which workspace you had set with the `terraform workspace select` command. That 81would most likely not be what you wanted. (It is ok to use `${terraform.workspace}` 82in local operations.) 83 84The backend configuration requires either `name` or `prefix`. Omitting both or 85setting both results in a configuration error. 86 87If previous state is present when you run `terraform init` and the corresponding 88remote workspaces are empty or absent, Terraform will create workspaces and/or 89update the remote state accordingly. However, if your workspace needs variables 90set or requires a specific version of Terraform for remote operations, we 91recommend that you create your remote workspaces on Terraform Cloud before 92running any remote operations against them. 93 94## Example Configurations 95 96-> **Note:** We recommend omitting the token from the configuration, and instead using 97 [`terraform login`](/docs/cli/commands/login.html) or manually configuring 98 `credentials` in the [CLI config file](/docs/cli/config/config-file.html#credentials). 99 100### Basic Configuration 101 102```hcl 103# Using a single workspace: 104terraform { 105 backend "remote" { 106 hostname = "app.terraform.io" 107 organization = "company" 108 109 workspaces { 110 name = "my-app-prod" 111 } 112 } 113} 114 115# Using multiple workspaces: 116terraform { 117 backend "remote" { 118 hostname = "app.terraform.io" 119 organization = "company" 120 121 workspaces { 122 prefix = "my-app-" 123 } 124 } 125} 126``` 127 128### Using CLI Input 129 130```hcl 131# main.tf 132terraform { 133 required_version = "~> 0.12.0" 134 135 backend "remote" {} 136} 137``` 138 139Backend configuration file: 140 141```hcl 142# backend.hcl 143workspaces { name = "workspace" } 144hostname = "app.terraform.io" 145organization = "company" 146``` 147 148Running `terraform init` with the backend file: 149 150```sh 151terraform init -backend-config=backend.hcl 152``` 153 154### Data Source Configuration 155 156```hcl 157data "terraform_remote_state" "foo" { 158 backend = "remote" 159 160 config = { 161 organization = "company" 162 163 workspaces = { 164 name = "workspace" 165 } 166 } 167} 168``` 169 170## Configuration variables 171 172The following configuration options are supported: 173 174* `hostname` - (Optional) The remote backend hostname to connect to. Defaults 175 to app.terraform.io. 176* `organization` - (Required) The name of the organization containing the 177 targeted workspace(s). 178* `token` - (Optional) The token used to authenticate with the remote backend. 179 We recommend omitting the token from the configuration, and instead using 180 [`terraform login`](/docs/cli/commands/login.html) or manually configuring 181 `credentials` in the 182 [CLI config file](/docs/cli/config/config-file.html#credentials). 183* `workspaces` - (Required) A block specifying which remote workspace(s) to use. 184 The `workspaces` block supports the following keys: 185 186 * `name` - (Optional) The full name of one remote workspace. When configured, 187 only the default workspace can be used. This option conflicts with `prefix`. 188 * `prefix` - (Optional) A prefix used in the names of one or more remote 189 workspaces, all of which can be used with this configuration. The full 190 workspace names are used in Terraform Cloud, and the short names 191 (minus the prefix) are used on the command line for Terraform CLI workspaces. 192 If omitted, only the default workspace can be used. This option conflicts with `name`. 193 194-> **Note:** You must use the `name` key when configuring a `terraform_remote_state` 195data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only 196intended for use when configuring an instance of the remote backend. 197 198## Command Line Arguments 199 200For configurations that include a `backend "remote"` block, commands that 201make local modifications to Terraform state and then push them back up to 202the remote workspace accept the following option to modify that behavior: 203 204* `-ignore-remote-version` - Override checking that the local and remote 205 Terraform versions agree, making an operation proceed even when there is 206 a mismatch. 207 208 Normally state-modification operations require using a local version of 209 Terraform CLI which is compatible with the Terraform version selected 210 for the remote workspace as part of its settings. This is to avoid the 211 local operation creating a new state snapshot which the workspace's 212 remote execution environment would then be unable to decode. 213 214 Overriding this check can result in a Terraform Cloud workspace that is 215 no longer able to complete remote operations, so we recommend against 216 using this option. 217 218## Excluding Files from Upload with .terraformignore 219 220-> **Version note:** `.terraformignore` support was added in Terraform 0.12.11. 221 222When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), 223an archive of your configuration directory is uploaded to Terraform Cloud. You can define 224paths 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: 225 226* .git/ directories 227* .terraform/ directories (exclusive of .terraform/modules) 228 229The `.terraformignore` file can include rules as one would include in a 230[.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) 231 232 233* Comments (starting with `#`) or blank lines are ignored 234* End a pattern with a forward slash / to specify a directory 235* Negate a pattern by starting it with an exclamation point `!` 236 237Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration 238directory is considered. 239