github.com/kcburge/terraform@v0.11.12-beta1/website/docs/backends/types/remote.html.md (about)

     1  ---
     2  layout: "backend-types"
     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  The remote backend stores state and runs operations remotely. When running
    14  `terraform plan` or `terraform apply` with this backend, the actual execution
    15  occurs in Terraform Enterprise, with log output streaming to the local terminal.
    16  
    17  To use this backend you need a Terraform Enterprise account on
    18  [app.terraform.io](https://app.terraform.io) or have a private instance of
    19  Terraform Enterprise (version v201809-1 or newer).
    20  
    21  -> **Preview Release**: As of Terraform 0.11.8, the remote backend is a preview
    22     release and we do not recommend using it with production workloads. Please
    23     continue to use the existing [Terraform
    24     Enterprise](terraform-enterprise.html) backend for production workspaces.
    25  
    26  ## Command Support
    27  
    28  Currently the remote backend supports the following Terraform commands:
    29  
    30  - `apply`
    31  - `console`
    32  - `destroy` (requires manually setting `CONFIRM_DESTROY=1` on the workspace)
    33  - `fmt`
    34  - `get`
    35  - `graph`
    36  - `import`
    37  - `init`
    38  - `output`
    39  - `plan`
    40  - `providers`
    41  - `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 workspace, or with
    51  multiple similarly-named remote workspaces (like `networking-dev` and
    52  `networking-prod`). The `workspaces` block of the backend configuration
    53  determines which mode it uses:
    54  
    55  - To use a single workspace, set `workspaces.name` to the remote workspace's
    56    full name (like `networking`).
    57  
    58  - To use multiple 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 a group of workspaces with names like
    61    `networking-dev` and `networking-prod`.
    62  
    63    When interacting with workspaces on the command line, Terraform uses
    64    shortened names without the common prefix. For example, if
    65    `prefix = "networking-"`, use `terraform workspace select prod` to switch to
    66    the `networking-prod` workspace.
    67  
    68  The backend configuration requires either `name` or `prefix`. Omitting both or
    69  setting both results in a configuration error.
    70  
    71  If previous state is present when you run `terraform init` and the corresponding
    72  remote workspaces are empty or absent, Terraform will create workspaces and/or
    73  update the remote state accordingly.
    74  
    75  ## Example Configuration
    76  
    77  ```hcl
    78  # Using a single workspace:
    79  terraform {
    80    backend "remote" {
    81      hostname = "app.terraform.io"
    82      organization = "company"
    83  
    84      workspaces {
    85        name = "my-app-prod"
    86      }
    87    }
    88  }
    89  
    90  # Using multiple workspaces:
    91  terraform {
    92    backend "remote" {
    93      hostname = "app.terraform.io"
    94      organization = "company"
    95  
    96      workspaces {
    97        prefix = "my-app-"
    98      }
    99    }
   100  }
   101  ```
   102  
   103  ## Example Reference
   104  
   105  ```hcl
   106  data "terraform_remote_state" "foo" {
   107    backend = "remote"
   108  
   109    config {
   110      organization = "company"
   111  
   112      workspaces {
   113        name = "workspace"
   114      }
   115    }
   116  }
   117  ```
   118  
   119  ## Configuration variables
   120  
   121  The following configuration options are supported:
   122  
   123  * `hostname` - (Optional) The remote backend hostname to connect to. Defaults
   124    to app.terraform.io.
   125  * `organization` - (Required) The name of the organization containing the
   126    targeted workspace(s).
   127  * `token` - (Optional) The token used to authenticate with the remote backend.
   128    We recommend omitting the token from the configuration, and instead setting it
   129    as `credentials` in the
   130    [CLI config file](/docs/commands/cli-config.html#credentials).
   131  * `workspaces` - (Required) A block specifying which remote workspace(s) to use.
   132    The `workspaces` block supports the following keys:
   133  
   134    * `name` - (Optional) The full name of one remote workspace. When configured,
   135      only the default workspace can be used. This option conflicts with `prefix`.
   136    * `prefix` - (Optional) A prefix used in the names of one or more remote
   137      workspaces, all of which can be used with this configuration. The full
   138      workspace names are used in Terraform Enterprise, and the short names
   139      (minus the prefix) are used on the command line. If omitted, only the
   140      default workspace can be used. This option conflicts with `name`.