Terraform Environments and Workspaces

Option 1: one directory per environment (recommended for most teams)

modules/
  app/
envs/
  dev/      main.tf   backend.tf   terraform.tfvars
  staging/  main.tf   backend.tf   terraform.tfvars
  prod/     main.tf   backend.tf   terraform.tfvars

Each environment has its own state and backend key, calls the same modules, and can be locked down separately. Mistakes stay contained.

Option 2: workspaces

terraform workspace new staging creates a separate state for the same directory, and terraform.workspace tells your code which one is active.

locals {
  settings = {
    default = { size = "small", replicas = 1 }
    prod    = { size = "large", replicas = 3 }
  }
  current = lookup(local.settings, terraform.workspace, local.settings["default"])
}

output "workspace" {
  value = "${terraform.workspace}: ${local.current.replicas} x ${local.current.size}"
}

workspace = "default: 1 x small"

Workspaces share one backend and one set of credentials, so they are convenient for short-lived copies (a feature branch environment) but risky for keeping production apart.

Promotion

Apply changes to dev first, then staging, then prod, with the same module version, usually through a CI/CD pipeline with a manual approval before production.