Multi-Environment Layout: Workspaces vs Directory Isolation

The Big Idea

How do you manage development, staging, and production environments using Terraform? The official tooling provides a feature called Terraform Workspaces (terraform workspace select prod). While workspaces sound convenient, they have significant architectural limitations in production.

Workspaces share the exact same backend configuration and code. If an engineer forgets which workspace is currently active and runs terraform destroy, they can accidentally vaporize production. Furthermore, workspaces cannot use separate AWS accounts or credential boundaries easily.

The enterprise industry standard is Directory-Based Environment Isolation. You build reusable modules in a shared folder, and create dedicated directories for each environment (environments/dev, environments/prod). Each environment has its own isolated state file, its own distinct backend S3 key, and its own IAM permission boundary, providing zero-blast-radius safety.

Enterprise Directory-Based Environment Architecture

repo-root/
├── modules/                   # Reusable, versioned component modules
│   ├── vpc/
│   ├── ecs-cluster/
│   └── rds-postgres/
│
└── environments/              # Concrete environments with isolated state
    ├── dev/
    │   ├── backend.tf         # S3 key: "environments/dev/terraform.tfstate"
    │   ├── main.tf            # Instantiates modules with small dev sizes
    │   └── terraform.tfvars
    │
    ├── staging/
    │   ├── backend.tf         # S3 key: "environments/staging/terraform.tfstate"
    │   ├── main.tf
    │   └── terraform.tfvars
    │
    └── prod/
        ├── backend.tf         # S3 key: "environments/prod/terraform.tfstate"
        ├── main.tf            # Multi-AZ HA sizes, strict deletion protection
        └── terraform.tfvars