github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/website/docs/language/state/workspaces.mdx (about)

     1  ---
     2  page_title: 'State: Workspaces'
     3  description: >-
     4    Workspaces allow the use of multiple states with a single configuration
     5    directory.
     6  ---
     7  
     8  # Workspaces
     9  
    10  Each Terraform configuration has an associated [backend](/language/settings/backends)
    11  that defines how operations are executed and where persistent data such as
    12  [the Terraform state](/language/state/purpose) are
    13  stored.
    14  
    15  The persistent data stored in the backend belongs to a _workspace_. Initially
    16  the backend has only one workspace, called "default", and thus there is only
    17  one Terraform state associated with that configuration.
    18  
    19  Certain backends support _multiple_ named workspaces, allowing multiple states
    20  to be associated with a single configuration. The configuration still
    21  has only one backend, but multiple distinct instances of that configuration
    22  to be deployed without configuring a new backend or changing authentication
    23  credentials.
    24  
    25  Multiple workspaces are currently supported by the following backends:
    26  
    27  * [AzureRM](/language/settings/backends/azurerm)
    28  * [Consul](/language/settings/backends/consul)
    29  * [COS](/language/settings/backends/cos)
    30  * [etcdv3](/language/settings/backends/etcdv3)
    31  * [GCS](/language/settings/backends/gcs)
    32  * [Kubernetes](/language/settings/backends/kubernetes)
    33  * [Local](/language/settings/backends/local)
    34  * [Manta](/language/settings/backends/manta)
    35  * [OSS](/language/settings/backends/oss)
    36  * [Postgres](/language/settings/backends/pg)
    37  * [Remote](/language/settings/backends/remote)
    38  * [S3](/language/settings/backends/s3)
    39  * [Swift](/language/settings/backends/swift)
    40  
    41  In the 0.9 line of Terraform releases, this concept was known as "environment".
    42  It was renamed in 0.10 based on feedback about confusion caused by the
    43  overloading of the word "environment" both within Terraform itself and within
    44  organizations that use Terraform.
    45  
    46  -> **Note**: The Terraform CLI workspace concept described in this document is
    47  different from but related to the Terraform Cloud
    48  [workspace](/cloud-docs/workspaces) concept.
    49  If you use multiple Terraform CLI workspaces in a single Terraform configuration
    50  and are migrating that configuration to Terraform Cloud, refer to [Initializing and Migrating](/cli/cloud/migrating).
    51  
    52  ## Using Workspaces
    53  
    54  Terraform starts with a single workspace named "default". This
    55  workspace is special both because it is the default and also because
    56  it cannot ever be deleted. If you've never explicitly used workspaces, then
    57  you've only ever worked on the "default" workspace.
    58  
    59  Workspaces are managed with the `terraform workspace` set of commands. To
    60  create a new workspace and switch to it, you can use `terraform workspace new`;
    61  to switch workspaces you can use `terraform workspace select`; etc.
    62  
    63  For example, creating a new workspace:
    64  
    65  ```text
    66  $ terraform workspace new bar
    67  Created and switched to workspace "bar"!
    68  
    69  You're now on a new, empty workspace. Workspaces isolate their state,
    70  so if you run "terraform plan" Terraform will not see any existing state
    71  for this configuration.
    72  ```
    73  
    74  As the command says, if you run `terraform plan`, Terraform will not see
    75  any existing resources that existed on the default (or any other) workspace.
    76  **These resources still physically exist,** but are managed in another
    77  Terraform workspace.
    78  
    79  ## Current Workspace Interpolation
    80  
    81  Within your Terraform configuration, you may include the name of the current
    82  workspace using the `${terraform.workspace}` interpolation sequence. This can
    83  be used anywhere interpolations are allowed.
    84  
    85  Referencing the current workspace is useful for changing behavior based
    86  on the workspace. For example, for non-default workspaces, it may be useful
    87  to spin up smaller cluster sizes. For example:
    88  
    89  ```hcl
    90  resource "aws_instance" "example" {
    91    count = "${terraform.workspace == "default" ? 5 : 1}"
    92  
    93    # ... other arguments
    94  }
    95  ```
    96  
    97  Another popular use case is using the workspace name as part of naming or
    98  tagging behavior:
    99  
   100  ```hcl
   101  resource "aws_instance" "example" {
   102    tags = {
   103      Name = "web - ${terraform.workspace}"
   104    }
   105  
   106    # ... other arguments
   107  }
   108  ```
   109  
   110  ## When to use Multiple Workspaces
   111  
   112  Named workspaces allow conveniently switching between multiple instances of
   113  a _single_ configuration within its _single_ backend. They are convenient in
   114  a number of situations, but cannot solve all problems.
   115  
   116  A common use for multiple workspaces is to create a parallel, distinct copy of
   117  a set of infrastructure in order to test a set of changes before modifying the
   118  main production infrastructure. For example, a developer working on a complex
   119  set of infrastructure changes might create a new temporary workspace in order
   120  to freely experiment with changes without affecting the default workspace.
   121  
   122  Non-default workspaces are often related to feature branches in version control.
   123  The default workspace might correspond to the "main" or "trunk" branch,
   124  which describes the intended state of production infrastructure. When a
   125  feature branch is created to develop a change, the developer of that feature
   126  might create a corresponding workspace and deploy into it a temporary "copy"
   127  of the main infrastructure so that changes can be tested without affecting
   128  the production infrastructure. Once the change is merged and deployed to the
   129  default workspace, the test infrastructure can be destroyed and the temporary
   130  workspace deleted.
   131  
   132  When Terraform is used to manage larger systems, teams should use multiple
   133  separate Terraform configurations that correspond with suitable architectural
   134  boundaries within the system so that different components can be managed
   135  separately and, if appropriate, by distinct teams. Workspaces _alone_
   136  are not a suitable tool for system decomposition, because each subsystem should
   137  have its own separate configuration and backend, and will thus have its own
   138  distinct set of workspaces.
   139  
   140  In particular, organizations commonly want to create a strong separation
   141  between multiple deployments of the same infrastructure serving different
   142  development stages (e.g. staging vs. production) or different internal teams.
   143  In this case, the backend used for each deployment often belongs to that
   144  deployment, with different credentials and access controls. Named workspaces
   145  are _not_ a suitable isolation mechanism for this scenario.
   146  
   147  Instead, use one or more [re-usable modules](/language/modules/develop) to
   148  represent the common elements, and then represent each instance as a separate
   149  configuration that instantiates those common elements in the context of a
   150  different backend. In that case, the root module of each configuration will
   151  consist only of a backend configuration and a small number of `module` blocks
   152  whose arguments describe any small differences between the deployments.
   153  
   154  Where multiple configurations are representing distinct system components
   155  rather than multiple deployments, data can be passed from one component to
   156  another using paired resources types and data sources. For example:
   157  
   158  * Where a shared [Consul](https://www.consul.io/) cluster is available, use
   159    [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to
   160    publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys)
   161    to retrieve those values in other configurations.
   162  
   163  * In systems that support user-defined labels or tags, use a tagging convention
   164    to make resources automatically discoverable. For example, use
   165    [the `aws_vpc` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc)
   166    to assign suitable tags and then
   167    [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc)
   168    to query by those tags in other configurations.
   169  
   170  * For server addresses, use a provider-specific resource to create a DNS
   171    record with a predictable name and then either use that name directly or
   172    use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve
   173    the published addresses in other configurations.
   174  
   175  * If a Terraform state for one configuration is stored in a remote backend
   176    that is accessible to other configurations then
   177    [`terraform_remote_state`](/language/state/remote-state-data)
   178    can be used to directly consume its root module outputs from those other
   179    configurations. This creates a tighter coupling between configurations,
   180    but avoids the need for the "producer" configuration to explicitly
   181    publish its results in a separate system.
   182  
   183  ## Workspace Internals
   184  
   185  Workspaces are technically equivalent to renaming your state file. They
   186  aren't any more complex than that. Terraform wraps this simple notion with
   187  a set of protections and support for remote state.
   188  
   189  For local state, Terraform stores the workspace states in a directory called
   190  `terraform.tfstate.d`. This directory should be treated similarly to
   191  local-only `terraform.tfstate`; some teams commit these files to version
   192  control, although using a remote backend instead is recommended when there are
   193  multiple collaborators.
   194  
   195  For [remote state](/language/state/remote), the workspaces are stored
   196  directly in the configured [backend](/language/settings/backends). For example, if you
   197  use [Consul](/language/settings/backends/consul), the workspaces are stored
   198  by appending the workspace name to the state path. To ensure that
   199  workspace names are stored correctly and safely in all backends, the name
   200  must be valid to use in a URL path segment without escaping.
   201  
   202  The important thing about workspace internals is that workspaces are
   203  meant to be a shared resource. They aren't a private, local-only notion
   204  (unless you're using purely local state and not committing it).
   205  
   206  The "current workspace" name is stored locally in the ignored
   207  `.terraform` directory. This allows multiple team members to work on
   208  different workspaces concurrently. Workspace names are also attached to associated remote workspaces in Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [remote backend](/language/settings/backends/remote#workspaces) and [CLI Integration (recommended)](/cli/cloud/settings#arguments) documentation.