Terraform workspaces (workspaces) are an easy yet powerful building block to create Terraform projects of any scale. In this article, I will guide you through all the details in the context of workflows. At the end of this guide, you take your Terraform projects to the next level.

What are Terraform workspaces

Think of workspaces as a layer of isolation for Terraform state files. Every workspace has its state file. All modifications applied in a particular workspace will never affect resources managed by another workspace. Workspaces are the key to manage multiple independent environments using a single Terraform project.

You can use workspaces no matter if you are using local or remote state backends.

Use the workspace variable in Terraform files

When using workspaces in Terraform, you can use the current workflow’s name in your configuration files. Just use the terraform.workspace variable.

A fairly common use case is to create scoped names for resources. Consider using Terraform to provision an Azure Resource Group. Azure enforces a unique name constraint on Resource Groups in the context of your Azure subscription. (You can have only one Resource Group with the name cool-product). By adding the name of the current workspace (e.g. dev, staging, or prod), you prevent yourself from violating the unique name constraint.

resource "azurerm_resource_group" "rg" {
    name = "cool-product-${terraform.workspace}"
    location = "westeurope"
}

How to create a new Terraform workspace

Every Terraform project comes with a workspace out of the box. When you call terraform init, Terraform implicitly creates a new workspace. The name of this workspace is always default. However, you can quickly create a custom workspace using the terraform workspace new command:

# create three new workspace
terraform workspace new dev
terraform workspace new staging
terraform workspace new prod

Create a workspace from an existing state file

You can bring in workspaces also for existing Terraform projects. If you already have a state file, use the state option to copy the existing state into the new workspace.

# create a new workspace and pass existing state file
terraform workspace new -state=terraform.tfstate dev

Display the current workspace

If you want to know which workspace you are currently interacting with, execute terraform workspace show. Terraform will quickly print the name of the current workspace.

# get the name of the current workspace
terraform workspace show
prod

List all available workspaces

Perhaps you joined a new team or a project. Looking at the list of available workspaces may help to get an overview. Using the list sub-command is easy:

# list all workspaces
terraform workspace list

default
dev
staging
prod

How to switch a Terraform workspace

Switching to a different namespace is super easy in Terraform. Just execute the terraform workspace select command, followed by the name of the desired workspace.

# switch to the dev workspace
terraform workspace select dev

terraform workspace show
dev

Remove a Terraform workspace

Sometimes, you want to remove a specific workspace. The sub-command delete is responsible for that. Delete the staging environment and check the list of remaining workspaces. There is only one exception; you can not delete the default namespace.

# delete the staging workspace
terraform workspace delete staging

terraform workspace list

default
dev
prod

Conclusion

Workspaces allow you to create multiple, predictable infrastructures using the sample Terraform project. Because the state is managed independently, things remain easy. Typically, I use the workspace variable ${terraform.workspace} to provide individual values per environment.