Workspaces

Each OpenTF configuration has an associated backend that defines how OpenTF executes operations and where OpenTF 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 OpenTF 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
• Consul
• COS
• GCS
• Kubernetes
• Local
• OSS
• Postgres
• Remote
• S3

Using Workspaces​

~> Important: Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to Use Cases in the OpenTF CLI documentation for details and recommended alternatives.

OpenTF 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 OpenTF working directory.

When you run opentf plan in a new workspace, OpenTF does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them.

Refer to the OpenTF CLI workspaces documentation for full details about how to create and use workspaces.

Current Workspace Interpolation​

Within your OpenTF 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:

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:

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

  # ... other arguments
}