| --- | |
| description: >- | |
| Workspaces allow the use of multiple states with a single configuration | |
| directory. | |
| --- | |
| # Workspaces | |
| Each OpenTofu configuration has an associated [backend](../../language/settings/backends/configuration.mdx) that defines how OpenTofu executes operations and where OpenTofu stores persistent data, like [state](../../language/state/purpose.mdx). | |
| The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one OpenTofu 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 | |
| credentials. | |
| ## Backends Supporting Multiple Workspaces | |
| You can use multiple workspaces with the following backends: | |
| - [AzureRM](../../language/settings/backends/azurerm.mdx) | |
| - [Consul](../../language/settings/backends/consul.mdx) | |
| - [COS](../../language/settings/backends/cos.mdx) | |
| - [GCS](../../language/settings/backends/gcs.mdx) | |
| - [Kubernetes](../../language/settings/backends/kubernetes.mdx) | |
| - [Local](../../language/settings/backends/local.mdx) | |
| - [OSS](../../language/settings/backends/oss.mdx) | |
| - [Postgres](../../language/settings/backends/pg.mdx) | |
| - [Remote](../../language/settings/backends/remote.mdx) | |
| - [S3](../../language/settings/backends/s3.mdx) | |
| ## Using Workspaces | |
| :::warning Important | |
| Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](../../cli/workspaces/index.mdx#use-cases) in the OpenTofu CLI documentation for details and recommended alternatives. | |
| ::: | |
| OpenTofu 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 OpenTofu working directory. | |
| When you run `tofu plan` in a new workspace, OpenTofu does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them. | |
| Refer to the [OpenTofu CLI workspaces](../../cli/workspaces/index.mdx) documentation for full details about how to create and use workspaces. | |
| ## Current Workspace Interpolation | |
| Within your OpenTofu configuration, you may include the name of the current | |
| workspace using the `${terraform.workspace}` interpolation sequence. This can | |
| be used anywhere interpolations are allowed. | |
| Referencing the current workspace is useful for changing behavior based | |
| on the workspace. For example, for non-default workspaces, it may be useful | |
| to spin up smaller cluster sizes. For example: | |
| ```hcl | |
| resource "aws_instance" "example" { | |
| count = "${terraform.workspace == "default" ? 5 : 1}" | |
| # ... other arguments | |
| } | |
| ``` | |
| Another popular use case is using the workspace name as part of naming or | |
| tagging behavior: | |
| ```hcl | |
| resource "aws_instance" "example" { | |
| tags = { | |
| Name = "web - ${terraform.workspace}" | |
| } | |
| # ... other arguments | |
| } | |
| ``` |