terraform/website/docs/language/settings/backends/remote.html.md

---
layout: "language"
page_title: "Backend Type: remote"
sidebar_current: "docs-backends-types-enhanced-remote"
description: |-
  Terraform can store the state and run operations remotely, making it easier to version and work with in a team.
---

# remote

-> **Note:** With the release of Terraform v1.1.0, we recommend using the Terraform Cloud's built-in
[`cloud` integration](/docs/language/settings/terraform-cloud.html) instead of this backend.
The `cloud` option includes an improved user experience and more features.

-> **Note:** This backend is unique among all other Terraform backends in that it has the ability to
execute operations for Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html), rather
than only store state snapshots. (The documentation used to refer to this as "enhanced" backend
behavior, but it's simpler to describe it as a quirk of the `remote` backend.)

-> **Note:** The remote backend requires Terraform v0.11.13 or newer, and requires either a
Terraform Cloud account on [app.terraform.io](https://app.terraform.io) or a Terraform Enterprise
instance (version v201809-1 or newer).


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.

Terraform Cloud can also be used with local operations, in which case only state is stored in the Terraform Cloud backend.

## Command Support

Currently 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`).

- 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](/docs/language/state/workspaces.html)
  used in a single Terraform configuration to multiple Terraform Cloud
  workspaces.

When interacting with workspaces on the command line, Terraform uses
shortened names without the common prefix. For example, if
`prefix = "networking-"`, use `terraform workspace select prod` to switch to
the Terraform CLI workspace `prod` within the current configuration. Remote
Terraform operations such as `plan` and `apply` executed against that Terraform
CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`.

Additionally, the [`terraform.workspace`](/docs/language/state/workspaces.html#referencing-the-current-workspace-name)
expression shouldn't be used in Terraform configurations that use Terraform 1.0.x or earlier and run
remote operations against Terraform Cloud workspaces. The reason for this is that
prior to Terraform 1.1.0, Terraform Cloud workspaces only used the single `default` Terraform
CLI workspace internally. In other words, if your 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 had set with the `terraform workspace select` command. That
would most likely not be what you wanted. (It is ok to use `terraform.workspace`
in local operations, and with remote operations in workspaces configured to use Terraform 1.1.0 or later.)

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/or
update the remote state accordingly. However, if your workspace needs variables
set or requires 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.

## Example Configurations

->  **Note:** We recommend omitting the token from the configuration, and instead using
  [`terraform login`](/docs/cli/commands/login.html) or manually configuring
  `credentials` in the [CLI config file](/docs/cli/config/config-file.html#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

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`](/docs/cli/commands/login.html) or manually configuring
  `credentials` in the
  [CLI config file](/docs/cli/config/config-file.html#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](/docs/cloud/run/cli.html),
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.