Directory Layouts per Environment

Workspace Design Tradeoffs ended on the objection every senior engineer raises: separate directories mean copying the same wiring three times. The layout below answers it by copying wiring only and never logic. A root module is any directory containing the configuration Terraform treats as the top of the graph: its own init, its own backend, its own state. The directory-per-environment model is simply that definition applied literally — three roots, three states, no cleverness:

infra/
├── modules/
│   ├── network/
│   └── service/
└── envs/
    ├── dev/
    │   ├── backend.tf
    │   ├── main.tf
    │   ├── variables.tf
    │   ├── outputs.tf
    │   └── dev.tfvars
    ├── staging/
    │   └── …same five files, staging.tfvars
    └── prod/
        └── …same five files, prod.tfvars

Each root is initialised and operated independently, and Terraform 1.5+ lets one working directory drive them all with -chdir:

terraform -chdir=envs/prod init
terraform -chdir=envs/prod plan  -var-file=prod.tfvars -out=tfplan
terraform -chdir=envs/prod apply tfplan

-chdir changes the directory every relative path resolves against, so prod.tfvars means envs/prod/prod.tfvars, and each root keeps its own .terraform/ working area, provider plugins, and module cache.

Separate state, separate backend, separate blast radius. The backend block differs per root — and since backend arguments must be literals anyway, there is no duplication to feel guilty about:

# envs/prod/backend.tf
terraform {
  required_version = "~> 1.9"
  backend "s3" {
    bucket         = "acme-tfstate-prod"
    key            = "services/payments/terraform.tfstate"
    region         = "eu-west-1"
    encrypt        = true
  }
}

Pointing production at acme-tfstate-prod and dev at acme-tfstate-dev is the difference between a staging developer holding state-plane credentials for everything and holding them for staging. The lock lives with the state, so the three roots apply concurrently without contending.

Variables are where the model pays off daily. Each root declares the same variable blocks — the contract is shared — while the values live in that root's .tfvars file and load automatically:

# envs/dev/dev.tfvars
account_id = "111122223333"
region     = "eu-west-1"
node_count = 1
domain     = "payments.dev.example.com"

# envs/prod/prod.tfvars
account_id = "444455556666"
region     = "eu-west-1"
node_count = 6
domain     = "payments.example.com"

No -var-file plumbing to remember, no terraform.tfvars shared by accident: open the directory and the environment's identity is visible in the file listing.

If you would rather keep account numbers out of the files entirely, use partial configuration and supply the literals at init:

# envs/prod/backend.tf
terraform {
  backend "s3" {}   # no arguments — filled in per environment
}

terraform -chdir=envs/prod init \
  -backend-config="bucket=acme-tfstate-prod" \
  -backend-config="key=services/payments/terraform.tfstate"

Literal backend files are greppable and reviewed alongside the rest of the environment; partial config keeps sensitive values out of a shared repository at the cost of an init command CI must get right on every run. Either is defensible — choosing deliberately is not optional.

Outputs follow the same discipline: one outputs.tf per root, publishing that environment's URL, certificate ARN, and queue names, so the contract stays identical while the values necessarily differ.

The cost of the model is wiring drift. Three copies of main.tf mean a new output added to dev but forgotten in prod is a silent divergence that only shows up when someone debugs production. Keep roots deliberately thin — backend, provider block, module calls, outputs — push all logic into modules/, and add cheap CI checks: terraform fmt -check -recursive, plus a diff of the roots themselves so a pull request that edits only envs/dev/main.tf raises a review comment. If the roots start growing past a screen, that is the signal logic leaked out of the modules.

Separate roots must not mean separate logic. The mechanism that keeps them honest is the module call: every environment instantiates the same module source and varies only the inputs.

# envs/prod/main.tf
module "network" {
  source = "../../modules/network"

  vpc_cidr       = "10.20.0.0/16"
  az_count       = 3
  enable_flow_log = true
}

module "service" {
  source = "../../modules/service"

  name        = "payments"
  node_count  = var.node_count
  subnet_ids  = module.network.private_subnet_ids
}

The relative source = "../../modules/network" resolves per root, so dev, staging, and prod all compile the same code from one location; only inputs differ. For published modules, the registry form pins a version per root:

module "vpc" {
  source  = "acme/vpc/aws"
  version = "~> 2.1"   # prod root — staging's root may say ~> 2.4
}

That per-root version argument is the quietly decisive feature: environments may adopt a module release at different times, which is exactly what a shared-configuration workspace setup cannot express. Module versions are recorded in .terraform/modules/modules.json after init, not in .terraform.lock.hcl — the lock file pins providers — so reviewing each root's version arguments is how you review what each environment actually runs.

Source addresses are a per-root decision too. In-repo logic uses relative paths, published modules use the registry with a version, and code shared across repositories but not published anywhere uses a Git source pinned by ref:

module "cluster" {
  source = "git::https://github.com/acme/tf-modules.git//eks?ref=v3.2.0"
}

The ?ref= pin does exactly what version does: without it every root floats to whatever main holds today, and the three environments diverge silently with each merge.

Decide what belongs where with one rule: if two environments need it identically it belongs in a module; if it differs, it becomes an input.

If copying the glue between roots still offends you, Terragrunt removes it while keeping the directory model:

# envs/prod/network/terragrunt.hcl
include "root" { path = find_in_parent_folders() }

inputs = merge(
  read_terragrunt_config(find_in_parent_folders("common.hcl")).inputs,
  { node_count = 6 }
)

The root terragrunt.hcl generates the backend and provider blocks from a single template and holds shared inputs in common.hcl, so each unit directory shrinks to an include plus overrides — and terragrunt run-all plan walks the tree. Cross-unit wiring uses dependency blocks instead of hand-written terraform_remote_state blocks, one per unit:

# envs/prod/service/terragrunt.hcl
dependency "network" {
  config_path = "../network"
}

inputs = {
  subnet_ids = dependency.network.outputs.private_subnet_ids
}

Terragrunt resolves the ordering itself on run-all apply, and reading another unit's outputs rather than its raw state keeps the coupling narrow — the same contract rule that governs modules, applied between roots. The trade is real: Terragrunt adds a wrapper layer that every new engineer must learn, so adopt it when the roots genuinely multiply, not preemptively.

A cheap CI check catches the drift this model still allows: diff envs/dev/main.tf against envs/prod/main.tf on every pull request and comment when they differ in more than their variable references. Three copies of wiring drift quietly; that comment makes the drift visible while it is one line old.

The final piece is telling CI which of these directories a change actually affects — covered next.

The layout only pays for itself once the pipeline can answer "which roots did this commit touch?" without running three full plans every time. Two answers combine: a path filter that maps changed files to directories, and a matrix that runs Terraform only inside the selected ones.

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      envs: ${{ steps.changes.outputs.changes }}
    steps:
      - uses: actions/checkout@v4
      - id: changes
        uses: dorny/paths-filter@v3
        with:
          filters: |
            dev:     ['envs/dev/**', 'modules/**']
            staging: ['envs/staging/**', 'modules/**']
            prod:    ['envs/prod/**', 'modules/**']

  plan:
    needs: detect
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env: [dev, staging, prod]
    if: ${{ contains(needs.detect.outputs.envs, matrix.env) }}
    steps:
      - uses: actions/checkout@v4
      - run: terraform -chdir=envs/${{ matrix.env }} init -input=false
      - run: terraform -chdir=envs/${{ matrix.env }} plan -input=false
              -var-file=${{ matrix.env }}.tfvars -out=tfplan
      - run: terraform -chdir=envs/${{ matrix.env }} show -json tfplan > tfplan.json
      - uses: actions/upload-artifact@v4
        with:
          name: plan-${{ matrix.env }}
          path: tfplan*

Read the filter rules carefully, because they encode the blast radius of every path: a change under envs/prod/** plans only production, while a change under modules/** plans all three — shared code can reach any root, so it must be exercised everywhere. Merge a pull request that only renames a dev tag and production's job never runs, never touches state, and never risks a lock.

No filter action? The same mapping comes from Git directly — note the three-dot range, which diffs against the merge base rather than the previous commit:

BASE="origin/${{ github.base_ref || 'main' }}"
CHANGED=$(git diff --name-only --diff-filter=ACMR "$BASE"...HEAD)

for env in dev staging prod; do
  printf '%s\n' "$CHANGED" | grep -q "^envs/$env/\|^modules/" && echo "$env" >> affected.txt
done

The apply side reuses the same matrix, gated on the branch:

  apply:
    needs: [plan]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: ${{ matrix.env }}   # production entry carries required reviewers
    steps:
      - run: terraform -chdir=envs/${{ matrix.env }} apply -input=false -auto-approve tfplan

Three operational details decide whether this stays reliable:

• Cache per directory. .terraform/ already lives inside each root thanks to -chdir, but the actions cache key must include the root path and .terraform.lock.hcl (envs-${{ matrix.env }}-${{ hashFiles(format('envs/{0}/.terraform.lock.hcl', matrix.env)) }}), otherwise one environment's provider cache is restored into another's.
• Validate the directory before init. A matrix entry for a deleted environment fails with a confusing Configuration does not exist error; test -d envs/$ENV first.
• Branch mapping stays simple. Pull requests run plan and post the diff; pushes to main run apply, still scoped by the same filter. Do not add a third mapping from branch names to environments — the directory is already the environment's name.

Values that cannot sit in a committed .tfvars — database passwords, API tokens — arrive as TF_VAR_ environment variables injected per matrix entry, so the secret is attached to the environment rather than to a file. The directory names the tier and CI supplies that tier's secrets; nothing in the repository has to know which environment it is serving.

Because each root owns its state, plan jobs for different roots run concurrently without contending — each holds a different lock object — while two runs against the same root queue normally, which is exactly the behaviour you want: parallel where isolation is real, serial where it is not. Only the roots a commit touched participate at all, so unrelated work never pays for Terraform's runtime.

That scoped, per-directory behaviour is precisely what a promotion pipeline needs as input, and Promoting Changes Across Environments turns it into plan-on-PR, apply-on-merge.