TerraformPilot

Guides

Terraform Workspaces - Complete Guide to Managing Environments

How to use Terraform workspaces to manage dev, staging, and production environments with one configuration. Commands, patterns, and when to avoid workspaces.

LLuca Berton1 min read

Quick Answer

#

Terraform workspaces let you manage multiple state files (dev, staging, prod) from the same configuration. Each workspace has isolated state. Use terraform workspace new dev to create, terraform workspace select prod to switch.

Workspace Commands

# 
# List workspaces (* = current)
terraform workspace list
 
# Create a new workspace
terraform workspace new dev
terraform workspace new staging
terraform workspace new prod
 
# Switch workspace
terraform workspace select prod
 
# Show current workspace
terraform workspace show
 
# Delete a workspace (must switch away first)
terraform workspace select default
terraform workspace delete dev

Using Workspaces in Configuration

# 
# Access current workspace name
locals {
  environment = terraform.workspace
  is_prod     = terraform.workspace == "prod"
}
 
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = local.is_prod ? "t3.large" : "t3.micro"
 
  tags = {
    Name        = "web-${local.environment}"
    Environment = local.environment
  }
}
 
resource "aws_s3_bucket" "data" {
  bucket = "myapp-${local.environment}-data"
}

Variable Maps per Workspace

# 
variable "instance_count" {
  type = map(number)
  default = {
    dev     = 1
    staging = 2
    prod    = 3
  }
}
 
variable "instance_type" {
  type = map(string)
  default = {
    dev     = "t3.micro"
    staging = "t3.small"
    prod    = "t3.large"
  }
}
 
resource "aws_instance" "web" {
  count         = lookup(var.instance_count, terraform.workspace, 1)
  instance_type = lookup(var.instance_type, terraform.workspace, "t3.micro")
  ami           = data.aws_ami.ubuntu.id
}

How Workspaces Store State

# 
# Local backend — separate directories
terraform.tfstate.d/
├── dev/
│   └── terraform.tfstate
├── staging/
│   └── terraform.tfstate
└── prod/
    └── terraform.tfstate
 
# S3 backend — separate keys
s3://my-state-bucket/
├── env:/dev/terraform.tfstate
├── env:/staging/terraform.tfstate
└── env:/prod/terraform.tfstate

When to Use Workspaces

#

✅ Good Use Cases

#
  • Same infrastructure, different sizes (dev=small, prod=large)
  • Feature branch testing
  • Personal development environments
  • Small teams with simple infrastructure

❌ When NOT to Use Workspaces

#
  • Different infrastructure per environment — use separate directories
  • Different providers per environment — workspaces share config
  • Large teams — workspaces are easy to confuse; separate repos are safer
  • Different access controls — all workspaces share the same backend permissions

Workspaces vs Separate Directories

#
FeatureWorkspacesSeparate Directories
Config duplicationNone — sharedSome — separate main.tf per env
State isolation✅ Separate state per workspace✅ Separate state per directory
Different infrastructure❌ Same config✅ Can differ completely
Different providers❌ Same providers✅ Different providers per env
VisibilityEasy to forget which workspaceExplicit directory = clear
CI/CDNeeds workspace select stepJust cd into directory

Alternative: Directory-Based Environments

# 
environments/
├── dev/
│   ├── main.tf
│   ├── terraform.tfvars
│   └── backend.tf
├── staging/
│   ├── main.tf
│   ├── terraform.tfvars
│   └── backend.tf
└── prod/
    ├── main.tf
    ├── terraform.tfvars
    └── backend.tf
modules/
├── networking/
├── compute/
└── database/
#

Conclusion

#

Workspaces work best for simple multi-environment setups where infrastructure is identical except for sizing. For anything more complex — different infra per environment, different access controls, large teams — use separate directories with shared modules instead.

#workspaces#environments#state

Share this article

Related articles