Environment Separation: Workspaces vs. Directories

The Great Debate

Every team eventually faces the same question: how do you manage dev, stage, and prod without duplicating all your Terraform code?

There are two primary approaches, and choosing the wrong one for your context creates real operational risk.

Approach 1: Terraform Workspaces

Workspaces let you use the exact same .tf files in one directory while maintaining separate state files for each environment, switched via a CLI command that selects which workspace subsequent commands apply against. Inside the code, a local value can branch on the active workspace's name to size resources differently per environment — a larger instance type in prod, a smaller one everywhere else.

• Pros: Fast to set up. No code duplication. Good for ephemeral environments (feature branches, PR previews).
• Cons: All workspaces share the same backend configuration — the same S3 bucket, the same AWS account. The active workspace is invisible in the code itself; you must run terraform workspace show to know where you are. It is dangerously easy to run terraform apply in the wrong workspace.

Approach 2: Directory Structure (Recommended for Production)

Separate folders, each with their own backend configuration, call shared modules:

infrastructure/
├── modules/
│   ├── networking/
│   └── web-server/
└── envs/
    ├── dev/
    │   ├── main.tf      # Calls modules with dev-sized inputs
    │   └── backend.tf   # Points to dev S3 bucket
    └── prod/
        ├── main.tf      # Calls modules with prod-sized inputs
        └── backend.tf   # Points to prod S3 bucket (different account)

• Pros: Explicit. You must cd envs/prod to affect production — the filesystem is your safety mechanism. Each environment can use a completely different AWS account and S3 bucket for state. Blast radius is contained.
• Cons: More boilerplate. Changes to module interfaces must be propagated to each environment directory.

Verdict: Use Directory Structure for any environment that holds real data or serves real users. Use Workspaces for short-lived, throwaway environments like PR previews or developer sandboxes.