github.com/pulumi/terraform@v1.4.0/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/configuration) that defines how Terraform executes operations and where Terraform stores persistent data, like [state](/language/state/purpose).
    11  
    12  The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform state associated with that configuration. Some backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. The configuration still has only one backend, but you can deploy multiple distinct instances of that configuration without configuring a new backend or changing authentication
    13  credentials.
    14  
    15  -> **Note**: The Terraform CLI workspaces are different from [workspaces in Terraform Cloud](/cloud-docs/workspaces). Refer to [Initializing and Migrating](/cli/cloud/migrating) for details about migrating a configuration with multiple workspaces to Terraform Cloud.
    16  
    17  ## Backends Supporting Multiple Workspaces
    18  
    19  You can use multiple workspaces with the following backends:
    20  
    21  - [AzureRM](/language/settings/backends/azurerm)
    22  - [Consul](/language/settings/backends/consul)
    23  - [COS](/language/settings/backends/cos)
    24  - [GCS](/language/settings/backends/gcs)
    25  - [Kubernetes](/language/settings/backends/kubernetes)
    26  - [Local](/language/settings/backends/local)
    27  - [OSS](/language/settings/backends/oss)
    28  - [Postgres](/language/settings/backends/pg)
    29  - [Remote](/language/settings/backends/remote)
    30  - [S3](/language/settings/backends/s3)
    31  
    32  
    33  ## Using Workspaces
    34  
    35  ~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/cli/workspaces#use-cases) in the Terraform CLI documentation for details and recommended alternatives.
    36  
    37  Terraform starts with a single, default workspace named `default` that you cannot delete. If you have not created a new workspace, you are using the default workspace in your Terraform working directory.
    38  
    39  When you run `terraform plan` in a new workspace, Terraform does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them.
    40  
    41  Refer to the [Terraform CLI workspaces](/cli/workspaces) documentation for full details about how to create and use workspaces.
    42  
    43  
    44  ## Current Workspace Interpolation
    45  
    46  Within your Terraform configuration, you may include the name of the current
    47  workspace using the `${terraform.workspace}` interpolation sequence. This can
    48  be used anywhere interpolations are allowed.
    49  
    50  Referencing the current workspace is useful for changing behavior based
    51  on the workspace. For example, for non-default workspaces, it may be useful
    52  to spin up smaller cluster sizes. For example:
    53  
    54  ```hcl
    55  resource "aws_instance" "example" {
    56    count = "${terraform.workspace == "default" ? 5 : 1}"
    57  
    58    # ... other arguments
    59  }
    60  ```
    61  
    62  Another popular use case is using the workspace name as part of naming or
    63  tagging behavior:
    64  
    65  ```hcl
    66  resource "aws_instance" "example" {
    67    tags = {
    68      Name = "web - ${terraform.workspace}"
    69    }
    70  
    71    # ... other arguments
    72  }
    73  ```