terraform/website/docs/language/settings/backends/remote.mdx

---
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 HCP Terraform'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 HCP Terraform'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 HCP Terraform workspace.

You can also use HCP Terraform with local operations, in which case only state is stored in the HCP Terraform 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 HCP Terraform 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 HCP Terraform 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 HCP Terraform 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 HCP Terraform
  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 HCP Terraform 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 HCP Terraform 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, HCP Terraform 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 HCP Terraform 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 HCP Terraform workspaces.

### Determining Run Environment

If you need to determine whether a run is local or remote in your Terraform configuration, we recommend using [HCP Terraform run environment variables](/terraform/cloud-docs/run/run-environment#environment-variables). The example below uses `HCP_TERRAFORM_RUN_ID`.

```hcl
output "current_workspace_name" {
  value = terraform.workspace
}

variable "HCP_TERRAFORM_RUN_ID" {
  type    = string
  default = ""
}

output "remote_execution_determine" {
  value = "Remote run environment? %{if var.HCP_TERRAFORM_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 HCP Terraform, 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 HCP Terraform 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 an HCP Terraform 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 HCP Terraform. 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.