Terraform Workspace

You are a Terraform infrastructure engineer. The user wants to configure and manage Terraform workspaces for multi-environment deployments (dev, staging, prod).

What to check first

• Run terraform version to confirm Terraform is installed (v0.10.0+)
• Check terraform workspace list to see existing workspaces in your current backend
• Verify your backend configuration in main.tf or backend.tf — workspaces require a persistent backend (S3, Terraform Cloud, etc.)

Steps

1. Initialize your Terraform backend with terraform init if not already done — this sets up remote state storage
2. Create a new workspace with terraform workspace new dev (replace dev with environment name)
3. Switch to the workspace using terraform workspace select dev
4. Create a terraform.tfvars.dev file with environment-specific variables (instance count, instance type, etc.)
5. Reference the current workspace in your code using the terraform.workspace built-in variable
6. Use conditional logic in your resources to apply different configurations per workspace
7. Plan changes with terraform plan -var-file="terraform.tfvars.${terraform workspace show}" to preview environment-specific deployment
8. Apply with terraform apply — Terraform will automatically use the selected workspace's state file

Code

# backend.tf - Configure S3 backend with workspace support
terraform {
  required_version = ">= 1.0"
  
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# main.tf - Use workspaces for environment-specific config
locals {
  env_config = {
    dev = {
      instance_type = "t3.micro"
      instance_count = 1
      enable_monitoring = false
    }
    staging = {
      instance_type = "t3.small"
      instance_count = 2
      enable_monitoring = true
    }
    prod = {
      instance_type = "t3.medium"
      instance_count = 3
      enable_monitoring = true
    }
  }
  
  current_env = terraform.workspace
  config = local.env_config[local.current_env]
}

provider "aws" {
  region = "us-east-1"
  
  default_tags {
    tags = {
      Environment = local.current_env
      ManagedBy   = "Terraform"
    }
  }
}

resource "aws_instance" "app" {
  count         = local.config.instance_count
  ami           = data.aws_ami.ubuntu.id
  instance_type = local.config.instance_type
  
  tags = {
    Name = "${local.current_env}-app-${count.index

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change