sdlc.dev

Terraform path · At scale · Topic 12 of 14

Environments: workspaces or separate state

Not started

Most teams need the same infrastructure several times: dev, staging, prod, maybe one per customer or Region. Terraform offers two broad ways to do it. **CLI workspaces** keep several states for one configuration in one backend. **Separate root modules** (or separate backend configurations) give each environment its own state, backend location and credentials. Both work; they differ sharply in how well they keep environments apart.

Why it matters: Dev, staging and prod must not share state, credentials or a blast radius. How you separate them decides whether a mistake in dev can touch prod.

  1. 1Workspaces are named states

    CLI workspaces give one configuration several states in the same backend, selected with terraform workspace select.

  2. 2Not a security boundary

    HashiCorp's docs say workspaces are not appropriate when deployments need separate credentials and access controls.

  3. 3Separate roots per environment

    A directory (or backend config) per environment, each with its own state, backend key and credentials, is the common pattern for prod.

  4. 4Shared code through modules

    Environments differ in inputs, not in copied code: each root calls the same versioned modules with its own values.

1

How it works

The explanation, with examples you can run.

CLI workspaces

$ terraform workspace new stagingCreated and switched to workspace "staging"! You're now on a new, empty workspace. Workspaces isolate their state,so if you run "terraform plan" Terraform will not see any existing statefor this configuration. $ terraform workspace list  default* staging

(Terraform 1.5.7, local backend, where the new state went into terraform.tfstate.d/staging/.) The configuration can read terraform.workspace to vary names or sizes. Workspaces are convenient for short-lived copies, such as one per feature branch or a developer's sandbox.

Their weakness is that the only difference between environments is which state is selected. The same code, the same backend and, usually, the same credentials can reach every workspace, and one forgotten terraform workspace select applies dev's change to prod. The Terraform documentation says plainly that workspaces are not appropriate for system decomposition or for deployments that need separate credentials and access controls.

Separate state per environment

modules/  service/            # shared, versioned building blocks  network/envs/  dev/    main.tf           # module calls with dev inputs    backend.tf        # key = "checkout/dev/terraform.tfstate"  prod/    main.tf           # same modules, prod inputs    backend.tf        # key = "checkout/prod/terraform.tfstate", prod account

Each environment directory is a small root module that calls shared modules with its own values. Each has its own backend key, often its own bucket in its own AWS account, and CI uses a different role for each, so a dev pipeline physically cannot write prod state. Differences between environments are visible as different inputs in code review, not hidden behind terraform.workspace conditionals.

Variants of the same idea: one root with -backend-config and -var-file per environment (less duplication, but the CI job must pass the right pair), wrapper tools such as Terragrunt that generate the per-environment boilerplate, and HCP Terraform workspaces, which are full units with their own state, variables and permissions and so behave more like separate roots than like CLI workspaces. Terraform Stacks, newer in HCP Terraform, model several deployments of the same components explicitly.

Splitting by layer, too

Environments are one axis; layers are another. Keep long-lived, rarely changed infrastructure (accounts, networks, DNS) in different states from fast-moving application resources. Smaller states plan faster, lock less often, and limit what a single bad apply can damage. Pass values between them through outputs published to a parameter store, or narrow data sources, rather than one giant state.

2

Check yourself

3 questions. Get them all right to finish this topic.

  1. 1.With CLI workspaces, what separates dev and prod?
  2. 2.Which layout gives prod its own blast radius?
  3. 3.Where do HCP Terraform workspaces differ from CLI workspaces?

0 of 3 right so far. Get all three to finish this topic.

Go deeper