| --- |
| page_title: 'Backend Type: remote' |
| description: >- |
| Terraform can store the state and run operations remotely, making it easier to |
| version and work with in a team. |
| --- |
| |
| # remote |
| |
| -> **Note:** We introduced the remote backend in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, **we recommend using the Terraform Cloud's built-in [`cloud` integration](/terraform/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features. |
| |
| The remote backend is unique among all other Terraform backends because it can both store state snapshots and execute operations for Terraform Cloud's [CLI-driven run workflow](/terraform/cloud-docs/run/cli). It used to be called an "enhanced" backend. |
| |
| When using full remote operations, operations like `terraform plan` or `terraform apply` can be 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. |
| |
| You can also use Terraform Cloud with local operations, in which case only state is stored in the Terraform Cloud backend. |
| |
| ## Command Support |
| |
| The remote backend supports the following Terraform commands: |
| |
| - `apply` |
| - `console` (supported in Terraform >= v0.11.12) |
| - `destroy` |
| - `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 Terraform Cloud 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 remote Terraform Cloud workspace, set `workspaces.name` to the |
| remote workspace's full name (like `networking-prod`). |
| |
| - To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in |
| all of the desired remote workspace names. For example, set |
| `prefix = "networking-"` to use Terraform cloud workspaces with |
| names like `networking-dev` and `networking-prod`. This is helpful when |
| mapping multiple Terraform CLI [workspaces](/terraform/language/state/workspaces) |
| used in a single Terraform configuration to multiple Terraform Cloud |
| workspaces. |
| |
| |
| 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 |
| update the remote state accordingly. However, if your workspace requires variables or a specific version of Terraform for remote operations, we |
| recommend that you create your remote workspaces on Terraform Cloud before |
| running any remote operations against them. |
| |
| ### Workspace Names |
| |
| Terraform uses shortened names without the common prefix to interact with workspaces on the command line. For example, if `prefix = "networking-"`, use `terraform workspace select prod` to switch to the Terraform CLI workspace `prod` within the current configuration. However, remote Terraform operations such as `plan` and `apply` for that Terraform CLI workspace will take place in the Terraform Cloud workspace `networking-prod`. |
| |
| Because of this, the [`terraform.workspace`](/terraform/language/state/workspaces#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following: |
| |
| - For local operations, `terraform.workspace` = `prod` |
| - For remote operations, `terraform.workspace`= `networking-prod` |
| |
| Prior to Terraform version 1.1.0, Terraform Cloud workspaces used only the single `default` Terraform CLI workspace internally. So if a Terraform configuration used `terraform.workspace` to return `dev` or `prod`, remote runs in Terraform Cloud would always evaluate it as `default`, regardless of |
| which workspace you set with the `terraform workspace select` command. Therefore, we do not recommend using `terraform.workspace` in Terraform configurations that use Terraform 1.0.x or earlier and run remote operations against Terraform Cloud workspaces. |
| |
| ### Determining Run Environment |
| |
| If you need to determine whether a run is local or remote in your Terraform configuration, we recommend using [Terraform Cloud run environment variables](/terraform/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`. |
| |
| ``` |
| output "current_workspace_name" { |
| value = terraform.workspace |
| } |
| |
| variable "TFC_RUN_ID" { |
| type = string |
| default = "" |
| } |
| |
| output "remote_execution_determine" { |
| value = "Remote run environment? %{if var.TFC_RUN_ID != ""}Yes%{else}No this is local%{endif}!" |
| } |
| ``` |
| |
| |
| ## Example Configurations |
| |
| -> **Note:** We recommend omitting the token from the configuration, and instead using |
| [`terraform login`](/terraform/cli/commands/login) or manually configuring |
| `credentials` in the [CLI config file](/terraform/cli/config/config-file#credentials). |
| |
| ### Basic 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-" |
| } |
| } |
| } |
| ``` |
| |
| ### Using CLI Input |
| |
| ```hcl |
| # main.tf |
| terraform { |
| required_version = "~> 0.12.0" |
| |
| backend "remote" {} |
| } |
| ``` |
| |
| Backend configuration file: |
| |
| ```hcl |
| # config.remote.tfbackend |
| workspaces { name = "workspace" } |
| hostname = "app.terraform.io" |
| organization = "company" |
| ``` |
| |
| Running `terraform init` with the backend file: |
| |
| ```sh |
| terraform init -backend-config=config.remote.tfbackend |
| ``` |
| |
| ### Data Source Configuration |
| |
| ```hcl |
| data "terraform_remote_state" "foo" { |
| backend = "remote" |
| |
| config = { |
| organization = "company" |
| |
| workspaces = { |
| name = "workspace" |
| } |
| } |
| } |
| ``` |
| |
| ## Configuration Variables |
| |
| !> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details. |
| |
| 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 using |
| [`terraform login`](/terraform/cli/commands/login) or manually configuring |
| `credentials` in the |
| [CLI config file](/terraform/cli/config/config-file#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 for Terraform CLI workspaces. |
| If omitted, only the default workspace can be used. This option conflicts with `name`. |
| |
| -> **Note:** You must use the `name` key when configuring a `terraform_remote_state` |
| data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only |
| intended for use when configuring an instance of the remote backend. |
| |
| ## Command Line Arguments |
| |
| For configurations that include a `backend "remote"` block, commands that |
| make local modifications to Terraform state and then push them back up to |
| the remote workspace accept the following option to modify that behavior: |
| |
| - `-ignore-remote-version` - Override checking that the local and remote |
| Terraform versions agree, making an operation proceed even when there is |
| a mismatch. |
| |
| Normally state-modification operations require using a local version of |
| Terraform CLI which is compatible with the Terraform version selected |
| for the remote workspace as part of its settings. This is to avoid the |
| local operation creating a new state snapshot which the workspace's |
| remote execution environment would then be unable to decode. |
| |
| Overriding this check can result in a Terraform Cloud workspace that is |
| no longer able to complete remote operations, so we recommend against |
| using this option. |
| |
| ## Excluding Files from Upload with .terraformignore |
| |
| -> **Version note:** `.terraformignore` support was added in Terraform 0.12.11. |
| |
| When executing a remote `plan` or `apply` in a [CLI-driven run](/terraform/cloud-docs/run/cli), |
| an archive of your configuration directory is uploaded to Terraform Cloud. You can define |
| 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: |
| |
| - `.git/` directories |
| - `.terraform/` directories (exclusive of `.terraform/modules`) |
| |
| The `.terraformignore` file can include rules as one would include in a |
| [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) |
| |
| - Comments (starting with `#`) or blank lines are ignored |
| - End a pattern with a forward slash `/` to specify a directory |
| - Negate a pattern by starting it with an exclamation point `!` |
| |
| Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration |
| directory is considered. |