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