---
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
}
```