github.com/paybyphone/terraform@v0.9.5-0.20170613192930-9706042ddd51/website/docs/state/workspaces.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "State: Workspaces"
     4  sidebar_current: "docs-state-workspaces"
     5  description: |-
     6    Workspaces allow the use of multiple states with a single configuration directory.
     7  ---
     8  
     9  # Workspaces
    10  
    11  A _workspace_ is a named container for Terraform state. With multiple
    12  workspaces, a single directory of Terraform configuration can be used to
    13  manage multiple distinct sets of infrastructure resources.
    14  
    15  Terraform state determines what resources it manages based on what
    16  exists in the state. This is how `terraform plan` determines what isn't
    17  created, what needs to be updated, etc. The full details of state can be
    18  found on [the _purpose_ page](/docs/state/purpose.html).
    19  
    20  Multiple workspaces are currently supported by the following backends:
    21  
    22   * [Consul](/docs/backends/types/consul.html)
    23   * [S3](/docs/backends/types/s3.html)
    24  
    25  In the 0.9 line of Terraform releases, this concept was known as "environment".
    26  It was renamed in 0.10 based on feedback about confusion caused by the
    27  overloading of the word "environment" both within Terraform itself and within
    28  organizations that use Terraform.
    29  
    30  ## Using Workspaces
    31  
    32  Terraform starts with a single workspace named "default". This
    33  workspace is special both because it is the default and also because
    34  it cannot ever be deleted. If you've never explicitly used workspaces, then
    35  you've only ever worked on the "default" workspace.
    36  
    37  Workspaces are managed with the `terraform workspace` set of commands. To
    38  create a new workspace and switch to it, you can use `terraform workspace new`;
    39  to switch environments you can use `terraform workspace select`; etc.
    40  
    41  For example, creating a new workspace:
    42  
    43  ```text
    44  $ terraform workspace new bar
    45  Created and switched to workspace "bar"!
    46  
    47  You're now on a new, empty workspace. Workspaces isolate their state,
    48  so if you run "terraform plan" Terraform will not see any existing state
    49  for this configuration.
    50  ```
    51  
    52  As the command says, if you run `terraform plan`, Terraform will not see
    53  any existing resources that existed on the default (or any other) workspace.
    54  **These resources still physically exist,** but are managed in another
    55  Terraform workspace.
    56  
    57  ## Current Workspace Interpolation
    58  
    59  Within your Terraform configuration, you may include the name of the current
    60  workspace using the `${terraform.workspace}` interpolation sequence. This can
    61  be used anywhere interpolations are allowed.
    62  
    63  Referencing the current workspace is useful for changing behavior based
    64  on the workspace. For example, for non-default workspaces, it may be useful
    65  to spin up smaller cluster sizes. For example:
    66  
    67  ```hcl
    68  resource "aws_instance" "example" {
    69    count = "${terraform.workspace == "default" ? 5 : 1}"
    70  
    71    # ... other arguments
    72  }
    73  ```
    74  
    75  Another popular use case is using the workspace name as part of naming or
    76  tagging behavior:
    77  
    78  ```hcl
    79  resource "aws_instance" "example" {
    80    tags {
    81      Name = "web - ${terraform.workspace}"
    82    }
    83  
    84    # ... other arguments
    85  }
    86  ```
    87  
    88  ## Best Practices
    89  
    90  Workspaces can be used to manage small differences between development,
    91  staging, and production, but they **should not** be treated as the only
    92  isolation mechanism. As Terraform configurations get larger, it's much more
    93  manageable and safer to split one large configuration into many
    94  smaller ones linked together with the `terraform_remote_state` data source.
    95  This allows teams to delegate ownership and reduce the potential impact of
    96  changes. For *each* smaller configuration, you can use workspaces to model
    97  the differences between development, staging, and production. However, if you
    98  have one large Terraform configuration, it is riskier and not recommended to
    99  use workspaces to handle those differences.
   100  
   101  [The `terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html)
   102  accepts a `workspace` name to target. Therefore, you can link
   103  together multiple independently managed Terraform configurations with the same
   104  environment easily, with each configuration itself having multiple workspaces.
   105  
   106  While workspaces are available to all,
   107  [Terraform Enterprise](https://www.hashicorp.com/products/terraform/)
   108  provides an interface and API for managing sets of configurations linked
   109  with `terraform_remote_state` and viewing them all as a single environment.
   110  
   111  Workspaces alone are useful for isolating a set of resources to test
   112  changes during development. For example, it is common to associate a
   113  branch in a VCS with a temporary workspace so new features can be developed
   114  without affecting the default workspace.
   115  
   116  Future Terraform versions and workspace enhancements will enable
   117  Terraform to track VCS branches with a workspace to help verify only certain
   118  branches can make changes to a Terraform workspace.
   119  
   120  ## Workspace Internals
   121  
   122  Workspaces are technically equivalent to renaming your state file. They
   123  aren't any more complex than that. Terraform wraps this simple notion with
   124  a set of protections and support for remote state.
   125  
   126  For local state, Terraform stores the workspace states in a directory called
   127  `terraform.tfstate.d`. This directory should be be treated similarly to
   128  local-only `terraform.tfstate`); some teams commit these files to version
   129  control, although using a remote backend instead is recommended when there are
   130  multiple collaborators.
   131  
   132  For [remote state](/docs/state/remote.html), the workspaces are stored
   133  directly in the configured [backend](/docs/backends). For example, if you
   134  use [Consul](/docs/backends/types/consul.html), the workspaces are stored
   135  by appending the environment name to the state path. To ensure that
   136  workspace names are stored correctly and safely in all backends, the name
   137  must be valid to use in a URL path segment without escaping.
   138  
   139  The important thing about workspace internals is that workspaces are
   140  meant to be a shared resource. They aren't a private, local-only notion
   141  (unless you're using purely local state and not committing it).
   142  
   143  The "current workspace" name is stored only locally in the ignored
   144  `.terraform` directory. This allows multiple team members to work on
   145  different workspaces concurrently.