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.