What is it?

One Terraform codebase — multiple environments — each with its own separate state file.

project/
├── main.tf                            ← single file, shared by all workspaces
└── terraform.tfstate.d/
    ├── dev/terraform.tfstate
    ├── test/terraform.tfstate
    └── prod/terraform.tfstate

Important — What Workspaces Are NOT

Workspaces do NOT create separate folders or separate code per environment.

Every workspace runs the exact same main.tf. The only thing isolated is the state file.

So if you change code and apply in test — that same changed code runs in dev and prod too when you apply there next.

Workspaces are not meant for different code per environment.

What Workspaces Are Actually For

Only useful when your infra is identical across environments and the only difference is size, count, or naming.

# same code, behaves differently based on workspace name
instance_type = terraform.workspace == "prod" ? "t3.large" : "t3.micro"
count         = terraform.workspace == "prod" ? 3 : 1
bucket        = "myapp-${terraform.workspace}-uploads"

tags = {
  Environment = terraform.workspace
}

Switch workspace → apply → get a scaled-down copy of prod for dev. That's the entire use case.

Why It Falls Apart in Real Companies

Real company environments are genuinely different: