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