github.com/hugorut/terraform@v1.1.3/website/docs/language/settings/backends/remote.mdx (about)

     1  ---
     2  page_title: 'Backend Type: remote'
     3  description: >-
     4    Terraform can store the state and run operations remotely, making it easier to
     5    version and work with in a team.
     6  ---
     7  
     8  # remote
     9  
    10  -> **Note:** The remote backend was introduced 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](/language/settings/terraform-cloud)** instead of this backend. The `cloud` option includes an improved user experience and more features.
    11  
    12  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](/cloud-docs/run/cli). It used to be called an "enhanced" backend.
    13  
    14  When using full remote operations, operations like `terraform plan` or `terraform apply` can be executed in Terraform
    15  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.
    16  
    17  Terraform Cloud can also be used with local operations, in which case only state is stored in the Terraform Cloud backend.
    18  
    19  ## Command Support
    20  
    21  Currently the remote backend supports the following Terraform commands:
    22  
    23  - `apply`
    24  - `console` (supported in Terraform >= v0.11.12)
    25  - `destroy`
    26  - `fmt`
    27  - `get`
    28  - `graph` (supported in Terraform >= v0.11.12)
    29  - `import` (supported in Terraform >= v0.11.12)
    30  - `init`
    31  - `output`
    32  - `plan`
    33  - `providers`
    34  - `show`
    35  - `state` (supports all sub-commands: list, mv, pull, push, rm, show)
    36  - `taint`
    37  - `untaint`
    38  - `validate`
    39  - `version`
    40  - `workspace`
    41  
    42  ## Workspaces
    43  
    44  The remote backend can work with either a single remote Terraform Cloud workspace,
    45  or with multiple similarly-named remote workspaces (like `networking-dev`
    46  and `networking-prod`). The `workspaces` block of the backend configuration
    47  determines which mode it uses:
    48  
    49  - To use a single remote Terraform Cloud workspace, set `workspaces.name` to the
    50    remote workspace's full name (like `networking`).
    51  
    52  - To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in
    53    all of the desired remote workspace names. For example, set
    54    `prefix = "networking-"` to use Terraform cloud workspaces with
    55    names like `networking-dev` and `networking-prod`. This is helpful when
    56    mapping multiple Terraform CLI [workspaces](/language/state/workspaces)
    57    used in a single Terraform configuration to multiple Terraform Cloud
    58    workspaces.
    59  
    60  When interacting with workspaces on the command line, Terraform uses
    61  shortened names without the common prefix. For example, if
    62  `prefix = "networking-"`, use `terraform workspace select prod` to switch to
    63  the Terraform CLI workspace `prod` within the current configuration. Remote
    64  Terraform operations such as `plan` and `apply` executed against that Terraform
    65  CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`.
    66  
    67  Additionally, the [`terraform.workspace`](/language/state/workspaces#current-workspace-interpolation)
    68  expression shouldn't be used in Terraform configurations that use Terraform 1.0.x or earlier and run
    69  remote operations against Terraform Cloud workspaces. The reason for this is that
    70  prior to Terraform 1.1.0, Terraform Cloud workspaces only used the single `default` Terraform
    71  CLI workspace internally. In other words, if your Terraform configuration
    72  used `${terraform.workspace}` to return `dev` or `prod`, remote runs in Terraform Cloud
    73  would always evaluate it as `default` regardless of
    74  which workspace you had set with the `terraform workspace select` command. That
    75  would most likely not be what you wanted. (It is ok to use `terraform.workspace`
    76  in local operations, and with remote operations in workspaces configured to use Terraform 1.1.0 or later.)
    77  
    78  The backend configuration requires either `name` or `prefix`. Omitting both or
    79  setting both results in a configuration error.
    80  
    81  If previous state is present when you run `terraform init` and the corresponding
    82  remote workspaces are empty or absent, Terraform will create workspaces and/or
    83  update the remote state accordingly. However, if your workspace needs variables
    84  set or requires a specific version of Terraform for remote operations, we
    85  recommend that you create your remote workspaces on Terraform Cloud before
    86  running any remote operations against them.
    87  
    88  ## Example Configurations
    89  
    90  ->  **Note:** We recommend omitting the token from the configuration, and instead using
    91  [`terraform login`](/cli/commands/login) or manually configuring
    92  `credentials` in the [CLI config file](/cli/config/config-file#credentials).
    93  
    94  ### Basic Configuration
    95  
    96  ```hcl
    97  # Using a single workspace:
    98  terraform {
    99    backend "remote" {
   100      hostname = "app.terraform.io"
   101      organization = "company"
   102  
   103      workspaces {
   104        name = "my-app-prod"
   105      }
   106    }
   107  }
   108  
   109  # Using multiple workspaces:
   110  terraform {
   111    backend "remote" {
   112      hostname = "app.terraform.io"
   113      organization = "company"
   114  
   115      workspaces {
   116        prefix = "my-app-"
   117      }
   118    }
   119  }
   120  ```
   121  
   122  ### Using CLI Input
   123  
   124  ```hcl
   125  # main.tf
   126  terraform {
   127    required_version = "~> 0.12.0"
   128  
   129    backend "remote" {}
   130  }
   131  ```
   132  
   133  Backend configuration file:
   134  
   135  ```hcl
   136  # config.remote.tfbackend
   137  workspaces { name = "workspace" }
   138  hostname     = "app.terraform.io"
   139  organization = "company"
   140  ```
   141  
   142  Running `terraform init` with the backend file:
   143  
   144  ```sh
   145  terraform init -backend-config=config.remote.tfbackend
   146  ```
   147  
   148  ### Data Source Configuration
   149  
   150  ```hcl
   151  data "terraform_remote_state" "foo" {
   152    backend = "remote"
   153  
   154    config = {
   155      organization = "company"
   156  
   157      workspaces = {
   158        name = "workspace"
   159      }
   160    }
   161  }
   162  ```
   163  
   164  ## Configuration variables
   165  
   166  The following configuration options are supported:
   167  
   168  - `hostname` - (Optional) The remote backend hostname to connect to. Defaults
   169    to app.terraform.io.
   170  - `organization` - (Required) The name of the organization containing the
   171    targeted workspace(s).
   172  - `token` - (Optional) The token used to authenticate with the remote backend.
   173    We recommend omitting the token from the configuration, and instead using
   174    [`terraform login`](/cli/commands/login) or manually configuring
   175    `credentials` in the
   176    [CLI config file](/cli/config/config-file#credentials).
   177  - `workspaces` - (Required) A block specifying which remote workspace(s) to use.
   178    The `workspaces` block supports the following keys:
   179  
   180    - `name` - (Optional) The full name of one remote workspace. When configured,
   181      only the default workspace can be used. This option conflicts with `prefix`.
   182    - `prefix` - (Optional) A prefix used in the names of one or more remote
   183      workspaces, all of which can be used with this configuration. The full
   184      workspace names are used in Terraform Cloud, and the short names
   185      (minus the prefix) are used on the command line for Terraform CLI workspaces.
   186      If omitted, only the default workspace can be used. This option conflicts with `name`.
   187  
   188  ->  **Note:** You must use the `name` key when configuring a `terraform_remote_state`
   189  data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only
   190  intended for use when configuring an instance of the remote backend.
   191  
   192  ## Command Line Arguments
   193  
   194  For configurations that include a `backend "remote"` block, commands that
   195  make local modifications to Terraform state and then push them back up to
   196  the remote workspace accept the following option to modify that behavior:
   197  
   198  - `-ignore-remote-version` - Override checking that the local and remote
   199    Terraform versions agree, making an operation proceed even when there is
   200    a mismatch.
   201  
   202    Normally state-modification operations require using a local version of
   203    Terraform CLI which is compatible with the Terraform version selected
   204    for the remote workspace as part of its settings. This is to avoid the
   205    local operation creating a new state snapshot which the workspace's
   206    remote execution environment would then be unable to decode.
   207  
   208    Overriding this check can result in a Terraform Cloud workspace that is
   209    no longer able to complete remote operations, so we recommend against
   210    using this option.
   211  
   212  ## Excluding Files from Upload with .terraformignore
   213  
   214  -> **Version note:** `.terraformignore` support was added in Terraform 0.12.11.
   215  
   216  When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli),
   217  an archive of your configuration directory is uploaded to Terraform Cloud. You can define
   218  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:
   219  
   220  - `.git/` directories
   221  - `.terraform/` directories (exclusive of `.terraform/modules`)
   222  
   223  The `.terraformignore` file can include rules as one would include in a
   224  [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
   225  
   226  - Comments (starting with `#`) or blank lines are ignored
   227  - End a pattern with a forward slash `/` to specify a directory
   228  - Negate a pattern by starting it with an exclamation point `!`
   229  
   230  Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration
   231  directory is considered.