Skip to main content

Workspaces

Each OpenTofu configuration has an associated backend that defines how OpenTofu executes operations and where OpenTofu stores persistent data, like state.

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:

Using Workspaces​

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 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:

Code Block
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:

Code Block
resource "aws_instance" "example" {
  tags = {
    Name = "web - ${terraform.workspace}"
  }

  # ... other arguments
}