Master Terraform Workspaces: Isolate Environments and Reuse Configurations

What is a Terraform Workspace?

A workspace lets a single Terraform configuration manage multiple independent state environments. Each workspace has its own state file but shares the same code, enabling environment isolation, configuration reuse, easy switching, and parallel development.

Workspace and State Relationship

Each workspace stores its state separately.

Local state files reside in terraform.tfstate.d/<workspace_name>.

Remote state stores each workspace’s file under a distinct key (e.g., separate S3 objects).

Creating and Switching Workspaces

Terraform provides these commands: terraform workspace list – list all workspaces (e.g., default, dev). terraform workspace show – display the current workspace. terraform workspace select <workspace_name> – switch to a workspace. terraform workspace new <workspace_name> – create a new workspace. terraform workspace delete <workspace_name> – delete a workspace.

# List all workspaces
terraform workspace list

# Show current workspace
terraform workspace show

# Create a new workspace named "dev"
terraform workspace new dev

# Switch to "dev"
terraform workspace select dev

# Create a new workspace named "prod"
terraform workspace new prod

# Switch to "prod"
terraform workspace select prod

# Delete the "dev" workspace
terraform workspace delete dev

Important notes:

The default workspace is named default.

Never delete a workspace that is currently in use.

Workspace names cannot contain spaces or special characters.

Managing Environment‑Specific Configuration

Although the Terraform code is shared, you often need different variable values per environment.

Method 1: Separate Variable Files

Create a dev.tfvars and prod.tfvars file and pass the appropriate file when applying.

# dev.tfvars
instance_type = "t3.small"

# prod.tfvars
instance_type = "t3.medium"

# Apply to dev
terraform apply -var-file=dev.tfvars

# Apply to prod
terraform apply -var-file=prod.tfvars

Method 2: Built‑in terraform.workspace Variable

Use the built‑in variable terraform.workspace inside configurations to select values dynamically.

variable "instance_type" {
  type    = string
  default = "t2.micro"
}

resource "aws_instance" "example" {
  ami           = "ami-0c55b31ad2299a796"
  instance_type = terraform.workspace == "prod" ? "t3.medium" : var.instance_type

  tags = {
    Name        = "terraform-example-${terraform.workspace}"
    Environment = terraform.workspace
  }
}

This example sets instance_type to t3.medium in the prod workspace and uses the default otherwise; tags are also populated with the workspace name.

Method 3: Conditional Mapping

variable "instance_type_map" {
  type = map(string)
  default = {
    dev     = "t3.small"
    staging = "t3.medium"
    prod    = "t3.large"
  }
}

resource "aws_instance" "example" {
  ami           = "ami-0c55b31ad2299a796"
  instance_type = var.instance_type_map[terraform.workspace]

  tags = {
    Name        = "terraform-example-${terraform.workspace}"
    Environment = terraform.workspace
  }
}

Here a map variable links each workspace to its instance type, and the resource picks the correct value automatically.

Hands‑On Exercise

Create three workspaces: dev, staging, and prod.

Write Terraform configuration: Use terraform.workspace (or one of the methods above) to vary instance size, tags, etc., based on the workspace.

Switch and apply:

Switch to dev and run terraform apply to create development resources.

Switch to staging and apply.

Switch to prod and apply.

Validate: Check the cloud console to confirm each environment’s resources were created with the correct settings.

Conclusion

The article introduced Terraform workspaces as a powerful way to manage multiple environments, achieve isolation, and reuse configuration. We covered the concept, creation, switching commands, and three practical methods for handling environment‑specific variables, followed by a hands‑on exercise to solidify the knowledge.