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