Workspaces: Multiple States in One Backend

A Terraform workspace is a feature that allows multiple states in a single backend configuration. The workspace is named (e.g. dev, staging, prod) and the state is stored at a path that includes the workspace name. The lesson teaches when workspaces are appropriate and when they are not.

The workspace command

The workspace command:

# List workspaces
terraform workspace list

# Create a workspace
terraform workspace new dev

# Select a workspace
terraform workspace select dev

# Show the current workspace
terraform workspace show

# Delete a workspace
terraform workspace delete dev

The workspace is a separate state in the same backend. The state path includes the workspace name:

s3://mycompany-terraform-state/env:/dev/terraform.tfstate
s3://mycompany-terraform-state/env:/staging/terraform.tfstate
s3://mycompany-terraform-state/env:/prod/terraform.tfstate

The workspace is a separate state with the same backend.

When workspaces are appropriate

Workspaces are appropriate for:

• Short-lived environments. A dev environment that is rebuilt every day.
• Similar environments. A staging environment that is similar to production.
• Single-team operations. A team that maintains multiple parallel environments with the same configuration.
• Module development. A module being developed in isolation.

The case for workspaces is: a single configuration that manages multiple similar environments.

When workspaces are not appropriate

Workspaces are not appropriate for:

• Production isolation. Production must have its own backend, its own credentials, and its own state.
• Multi-cloud. Different providers should be in different configurations.
• Multi-region. Different regions should be in different configurations with provider aliases.
• Multi-team. Different teams should be in different configurations.

The case against workspaces is: a single state with multiple environments is a single blast radius.

The misconception

A common misconception is that workspaces are an isolation control. They are not.

Three workspaces in one backend:
  - dev (workspace)
  - staging (workspace)
  - prod (workspace)

  All three use the same credentials.
  All three share the same backend.
  All three share the same lock table.

  A misconfigured apply in dev can affect prod.

The workspaces are separate states, but they are not isolated. The credentials, the backend, and the lock are shared.

The fix is to use separate backends for separate environments:

Three environments with separate backends:
  - dev (production-backend)
  - staging (staging-backend)
  - prod (production-backend)

  Each has its own credentials.
  Each has its own backend.
  Each has its own lock table.

  A misconfigured apply in dev cannot affect prod.

The production pattern

A production Terraform estate uses workspaces for the short-lived, similar environments:

# Dev: workspace, ephemeral
terraform workspace new dev
terraform apply

# Staging: workspace, similar to prod
terraform workspace new staging
terraform apply

# Production: separate backend, isolated
cd ../production
terraform apply

The workspaces manage the dev and staging environments. The production environment is in a separate working directory with its own backend.

The CLI behaviour

The workspace affects the state path:

# Workspace dev
terraform state list
# aws_instance.web

# Switch to staging
terraform workspace select staging
terraform state list
# aws_instance.web

The output is the same — the state is named the same — but the state is in a different path. The resources are separate.

The CI/CD pattern

A CI/CD pipeline uses the workspace to select the environment:

- run: terraform workspace select ${{ github.event.inputs.environment }}
- run: terraform apply

The pipeline selects the workspace, then applies. The workspace is the input to the apply.

What comes next

The next lesson is state boundaries — the design of state splits for production Terraform estates.

Verification