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