# terraform / workspaces / environments
One Codebase, Multiple Stages: Workspaces
In real-world software delivery, you deploy identical infrastructure topologies across multiple environments: Development, Staging, QA, and Production. Terraform Workspaces allow you to manage distinct state files from a single set of configuration files.
The Multi-Environment Challenge
If you create a web application stack, you don't want to copy your .tf files into three separate folders (dev/, stage/, prod/) and manually keep them in sync every time you add a new resource. Workspaces keep one code directory and switch the active backend state underneath.
| Workspace | Instance Type | Min Nodes | Database Size |
|---|---|---|---|
development | t3.micro | 1 | db.t3.micro (Single-AZ) |
staging | t3.small | 2 | db.t3.small (Single-AZ) |
production | m5.large | 4 | db.r5.large (Multi-AZ) |
Every Project Starts in "default"
If you have never run a workspace command, you are already using the default workspace. Creating new workspaces adds separate branches of state without changing your code.
Workspace Management CLI Commands
# 1. List all available workspaces $ terraform workspace list * default # 2. Create and switch to a new 'dev' workspace $ terraform workspace new dev Created and switched to workspace "dev"! # 3. Create 'prod' workspace $ terraform workspace new prod # 4. Switch between existing workspaces $ terraform workspace select dev Switched to workspace "dev". # 5. Check which workspace is currently active $ terraform workspace show dev
Always Verify Active Workspace in Terminal
Because the folder looks identical on your disk, running terraform destroy in the wrong active workspace could accidentally destroy Production. Always run terraform workspace show or customize your shell prompt to display the active workspace.
Interpolating terraform.workspace in HCL
locals { instance_types = { default = "t3.micro" dev = "t3.micro" stage = "t3.small" prod = "m5.large" } } resource "aws_instance" "app" { ami = "ami-0123456789abcdef0" instance_type = lookup(local.instance_types, terraform.workspace, "t3.micro") tags = { Name = "app-server-${terraform.workspace}" Environment = terraform.workspace } }
terraform.workspace Keyword
The terraform.workspace variable is built directly into Terraform's core engine. It always evaluates to the string name of the currently selected workspace.
How Remote State Isolates Workspaces
When using the AWS S3 backend, Terraform automatically prefixes the state object key with env:/<workspace_name>/. Your environments never overwrite each other's state data.
s3://shan-tfstate-ap-south-1/ ├── prod/app/terraform.tfstate # default workspace ├── env:/dev/prod/app/terraform.tfstate # dev workspace └── env:/stage/prod/app/terraform.tfstate # stage workspace
Workspaces vs Directory-Based Layout
| Factor | Terraform Workspaces | Directory-Based (e.g. environments/prod) |
|---|---|---|
| Code Structure | Single shared folder for all environments | Separate folder per environment referencing modules |
| Multi-Account Cloud | Difficult (all share same provider config) | Easy (each folder has unique AWS Account IDs & IAM roles) |
| Blast Radius | High risk if engineer selects wrong workspace | Low risk (separate directories, separate permissions) |
| Configuration Drift | Zero code drift (all share exact same HCL) | Requires discipline to keep module versions aligned |
| Best Use Case | Fast ephemeral PR preview environments, dev/QA | Production multi-account enterprise architecture |
The Enterprise Verdict
Use Workspaces For
- Temporary pull request preview environments (e.g.
pr-142). - Identical developer test sandboxes in the same AWS account.
- Fast iteration when infrastructure differences are purely instance sizing.
Use Folder Separation For
- Separate AWS Accounts (e.g. Dev Account vs Prod Account).
- Strict compliance where Prod state must be locked behind distinct IAM roles.
- Environments requiring structurally different architecture (e.g. Multi-Region in Prod).