What is a Terraform Workspace? Multi-Environment Management Explained

You have one Terraform configuration. You need to deploy it to dev, staging, and production. Workspaces are one way to do this — but they're often misunderstood and misused.

What is a Workspace?

A Terraform workspace is an isolated state file. Same configuration code, different state.

By default, every Terraform project has one workspace named default. When you create a new workspace, Terraform creates a separate state file for it.

# List workspaces
terraform workspace list
# * default
 
# Create a new workspace
terraform workspace new staging
# Created and switched to workspace "staging"
 
# Switch between workspaces
terraform workspace select production
 
# Show current workspace
terraform workspace show

How Workspaces Work With State

Without workspaces — one state file:

terraform.tfstate

With workspaces — separate state per workspace:

terraform.tfstate.d/
  ├── staging/
  │   └── terraform.tfstate
  └── production/
      └── terraform.tfstate

For remote state (S3 backend), each workspace gets its own path:

s3://my-terraform-state/
  ├── env:/staging/terraform.tfstate
  └── env:/production/terraform.tfstate

Using Workspaces in Configuration

The current workspace name is available via terraform.workspace:

# main.tf
locals {
  environment = terraform.workspace
 
  instance_count = {
    default    = 1
    staging    = 2
    production = 5
  }
 
  instance_type = {
    default    = "t3.micro"
    staging    = "t3.small"
    production = "t3.large"
  }
}
 
resource "aws_instance" "app" {
  count         = local.instance_count[local.environment]
  instance_type = local.instance_type[local.environment]
  ami           = "ami-0abcdef1234567890"
 
  tags = {
    Name        = "app-${local.environment}"
    Environment = local.environment
  }
}

# Deploy to staging
terraform workspace select staging
terraform apply
 
# Deploy to production
terraform workspace select production
terraform apply

Workspace with S3 Backend

# backend.tf
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "app/terraform.tfstate"   # Each workspace adds env:/<name>/ prefix
    region         = "ap-south-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

State is stored at:

• app/terraform.tfstate (default workspace)
• env:/staging/app/terraform.tfstate (staging workspace)
• env:/production/app/terraform.tfstate (production workspace)

Workspace Commands

# Create workspace
terraform workspace new dev
 
# Switch workspace
terraform workspace select production
 
# List all workspaces (* = current)
terraform workspace list
# * production
#   staging
#   dev
 
# Delete workspace (must switch away first, state must be empty)
terraform workspace select default
terraform workspace delete dev
 
# Plan/apply in context of current workspace
terraform workspace select staging
terraform plan
terraform apply

When Workspaces Work Well

Workspaces are a good fit when:

• Same infrastructure pattern, different scale — same resources, just different sizes
• Short-lived environments — feature branch environments, ephemeral test environments
• Simple projects — 1–3 resources, limited environment-specific variation

Example: Feature branch environments in CI/CD:

# Create workspace for PR #123
terraform workspace new pr-123
terraform apply -var="instance_count=1" -var="env_suffix=pr-123"
 
# Cleanup after PR merge
terraform destroy
terraform workspace select default
terraform workspace delete pr-123

When Workspaces Are the Wrong Choice

Workspaces have important limitations that make them unsuitable for complex multi-environment setups:

1. Same code = same resource types everywhere

You can't have a database in production but not in dev using just workspaces (without messy count = workspace == "production" ? 1 : 0 logic).

2. No separation of permissions

Everyone with access to the Terraform state backend can accidentally terraform apply to production. There's no enforced access control between workspaces.

3. State visibility is confusing

Engineers forget to switch workspaces before running terraform plan. A typo in terraform workspace select production when you meant staging has caused real incidents.

The Alternative: Separate Directories per Environment

Many teams prefer this approach for production use:

infra/
├── modules/
│   ├── ec2/
│   ├── rds/
│   └── vpc/
├── environments/
│   ├── dev/
│   │   ├── main.tf        # Calls shared modules
│   │   ├── variables.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   │   ├── main.tf
│   │   └── terraform.tfvars
│   └── production/
│       ├── main.tf
│       └── terraform.tfvars

# environments/production/main.tf
module "app" {
  source         = "../../modules/ec2"
  instance_count = 5
  instance_type  = "t3.large"
  environment    = "production"
}

# Deploy to production
cd environments/production
terraform init
terraform apply

Advantages over workspaces:

• Clear directory — you always know which environment you're in
• Different backends per environment (different S3 buckets, different AWS accounts)
• Per-environment IAM permissions enforced at the directory level
• Different modules/resources per environment without workarounds

Decision Guide

Most experienced Terraform users use workspaces for ephemeral environments and separate directories for long-lived production infrastructure.

For Terraform hands-on labs covering workspaces, modules, and remote state, KodeKloud has courses from Terraform basics to multi-environment patterns.