github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/language/settings/backends/remote.html.md (about) 1 --- 2 layout: "language" 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 -> **Note:** We recommend using Terraform v0.11.13 or newer with this 14 backend. 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 18 The remote backend stores Terraform state and may be used to run operations in Terraform Cloud. 19 20 When using full remote operations, operations like `terraform plan` or `terraform apply` can be executed in Terraform 21 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. 22 23 Terraform 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 27 Currently 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 50 The remote backend can work with either a single remote Terraform Cloud workspace, 51 or with multiple similarly-named remote workspaces (like `networking-dev` 52 and `networking-prod`). The `workspaces` block of the backend configuration 53 determines 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 66 When interacting with workspaces on the command line, Terraform uses 67 shortened names without the common prefix. For example, if 68 `prefix = "networking-"`, use `terraform workspace select prod` to switch to 69 the Terraform CLI workspace `prod` within the current configuration. Remote 70 Terraform operations such as `plan` and `apply` executed against that Terraform 71 CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`. 72 73 Additionally, the [`${terraform.workspace}`](/docs/language/state/workspaces.html#current-workspace-interpolation) 74 interpolation sequence should be removed from Terraform configurations that run 75 remote operations against Terraform Cloud workspaces. The reason for this is that 76 each Terraform Cloud workspace currently only uses the single `default` Terraform 77 CLI workspace internally. In other words, if your Terraform configuration 78 used `${terraform.workspace}` to return `dev` or `prod`, remote runs in Terraform Cloud 79 would always evaluate it as `default` regardless of 80 which workspace you had set with the `terraform workspace select` command. That 81 would most likely not be what you wanted. (It is ok to use `${terraform.workspace}` 82 in local operations.) 83 84 The backend configuration requires either `name` or `prefix`. Omitting both or 85 setting both results in a configuration error. 86 87 If previous state is present when you run `terraform init` and the corresponding 88 remote workspaces are empty or absent, Terraform will create workspaces and/or 89 update the remote state accordingly. However, if your workspace needs variables 90 set or requires a specific version of Terraform for remote operations, we 91 recommend that you create your remote workspaces on Terraform Cloud before 92 running 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: 104 terraform { 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: 116 terraform { 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 132 terraform { 133 required_version = "~> 0.12.0" 134 135 backend "remote" {} 136 } 137 ``` 138 139 Backend configuration file: 140 141 ```hcl 142 # config.remote.tfbackend 143 workspaces { name = "workspace" } 144 hostname = "app.terraform.io" 145 organization = "company" 146 ``` 147 148 Running `terraform init` with the backend file: 149 150 ```sh 151 terraform init -backend-config=config.remote.tfbackend 152 ``` 153 154 ### Data Source Configuration 155 156 ```hcl 157 data "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 172 The 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` 195 data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only 196 intended for use when configuring an instance of the remote backend. 197 198 ## Command Line Arguments 199 200 For configurations that include a `backend "remote"` block, commands that 201 make local modifications to Terraform state and then push them back up to 202 the 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 222 When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), 223 an archive of your configuration directory is uploaded to Terraform Cloud. You can define 224 paths 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 229 The `.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 237 Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration 238 directory is considered.