Isolate dev / staging / prod state in a single backend.

Terraform Workspaces — Multi-Environment State

Terraform workspaces allow multiple state files to coexist in the same backend configuration. Each workspace maps to an environment (dev/staging/prod), enabling the same HCL to deploy isolated instances without directory duplication.

Interactive Pipeline Flow

SetupConfigDeploy

📥 Init — shared backend

terraform init configures the remote backend (Azure Blob Storage). All workspaces share the same storage account but get separate state blobs.

Architecture Diagrams

Promotion pipeline: deploy through dev → staging → prod with workspace selection at each stage.

Loading diagram...

Key Design Decisions

⚠️Workspace Limitations

Workspaces share the same backend config (storage account, container, key). They cannot have different backend locations. For strong prod/dev isolation, use separate Terraform configurations + backends.

🔀terraform.workspace Variable

Reference the current workspace as terraform.workspace in HCL. Use it for conditional logic: instance_type = terraform.workspace == 'prod' ? 'Standard_D4s_v5' : 'Standard_B2s'.

🏷️Workspace vs Directory Pattern

Workspaces suit identical environments with different sizes (dev/staging/prod). The directory pattern (separate roots per env) suits environments with different resource structures. Know the trade-offs.

🔒State File Naming

In Azure Blob Storage backend, workspace state files are stored as env:/<workspace>/terraform.tfstate. The default workspace uses the key value from the backend config directly.

🚫Avoid workspace new in CI

Create workspaces once (dev/staging/prod) as part of bootstrap. In CI pipelines, use workspace select only — never workspace new. Prevents duplicate environment accidents.

🔄Per-workspace Variables

Keep a vars/ directory: vars/dev.tfvars, vars/prod.tfvars. In CI, pass -var-file=vars/${WORKSPACE}.tfvars. Never hardcode environment values in main.tf.

Discussion