The Multi-Environment Problem

The idea in one sentence

Every real infrastructure setup needs at least dev, staging, and prod as separate, isolated environments, and reusing the same Terraform logic across all of them without letting their configurations quietly drift apart is a problem Terraform does not solve for you automatically.

More environments than you think

A toy Terraform example usually manages one environment. A real one never does. At minimum you need:

• dev — cheap, disposable, safe to break.
• staging — a realistic rehearsal of prod, used to catch problems before they ship.
• prod — the one that serves real traffic and real customers.

Most teams end up with more subdivisions than that: a separate copy per AWS region, a separate copy per customer for larger B2B deployments, or a short-lived preview environment spun up per feature branch and torn down when the pull request merges. Each of these usually differs from the others in concrete ways — a smaller EC2 instance type in dev, fewer read replicas in staging, autoscaling turned off in dev to save money — and, critically, prod is often placed in an entirely separate AWS account or region from the rest, specifically so that a mistake in dev cannot reach anything that matters. That last point is called blast-radius isolation: limiting how far a bad apply or a leaked credential can actually travel.

The naive fix: copy-paste a directory per environment

The first instinct almost everyone reaches for is to build one environment, get it working, then copy the whole directory for each additional environment:

# Three near-identical copies, created once by hand
tree environments
environments
├── dev
│   └── main.tf
├── staging
│   └── main.tf
└── prod
    └── main.tf

On day one, all three files are identical except for a handful of hardcoded values — an instance size here, a bucket name there. It works, and it feels fast: no shared modules to design, no abstractions to get right, just three folders of ordinary .tf code.

# Day one: dev/main.tf, staging/main.tf, and prod/main.tf are all this rule, verbatim
resource "aws_security_group_rule" "allow_app_port" {
  type              = "ingress"
  from_port         = 8080
  to_port           = 8080
  protocol          = "tcp"
  cidr_blocks       = ["10.0.0.0/16"]
  security_group_id = aws_security_group.app.id
}

Six months later, a security review flags that rule in prod as too permissive, and someone tightens it directly in prod/main.tf:

# Six months later: prod/main.tf was patched during a security review.
# staging/main.tf and dev/main.tf still say 10.0.0.0/16 — nobody remembered to port the fix.
resource "aws_security_group_rule" "allow_app_port" {
  type              = "ingress"
  from_port         = 8080
  to_port           = 8080
  protocol          = "tcp"
  cidr_blocks       = ["10.0.5.0/24"]
  security_group_id = aws_security_group.app.id
}

Nobody did anything malicious or even careless here — fixing the rule where the security review happened to be looking was the reasonable thing to do in the moment. But the three directories are now three subtly different, undocumented configurations, and nothing in the repository says so. A diff between dev/ and prod/ six months later turns up a dozen small discrepancies, and nobody can say from memory which ones are intentional and which are just forgotten copy-paste debt.

The tension this module explores

The underlying problem is that copy-pasting an entire environment directory optimizes for isolation — each environment truly cannot affect another, since they are separate files entirely — at the total expense of reuse. Every bug fix, every tag added for cost tracking, every module version bump has to be manually repeated in every copy, and manual repetition is exactly the kind of process step that silently stops happening.

The rest of this module is about resolving that tension: how do you reuse the same underlying logic across every environment (so there is one place to fix a bug, not three or five) while still keeping each environment’s state, credentials, and blast radius fully isolated from the others? Terraform on its own offers two partial answers — workspaces and the directory-per-environment pattern — and each one, as the next two lessons show, solves one half of the problem while leaving the other half exposed.

flowchart LR
  origin["Working config, copied once"] -->|copy-paste| dev["dev/ (copy)"]
  origin -->|copy-paste| staging["staging/ (copy)"]
  origin -->|copy-paste| prod["prod/ (copy)"]
  prod -->|"security rule tightened here only"| prodDrift["prod/ (drifted)"]
  staging -->|"instance size bumped here only"| stagingDrift["staging/ (drifted)"]
  dev -->|"never touched again"| devDrift["dev/ (stale)"]

Three copy-pasted environment directories quietly diverge as ad hoc fixes land in only one of them

🏗️ The one-line takeaway

Every real setup needs multiple isolated environments (at minimum dev, staging, and prod, often more), but the naive fix of copy-pasting a whole directory per environment optimizes for isolation at the cost of DRY reuse — every fix or tweak must be manually re-applied to every copy, and because that repetition is manual, the copies silently drift into different, undocumented configurations over time. The rest of this module is about balancing reuse against isolation instead of sacrificing one for the other.

What specifically goes wrong with copy-pasting an entire environment directory for every environment

Terraform refuses to apply configuration that exists in more than one directory A fix or tweak made in one copy is not automatically applied to the others, so the copies silently drift into different, undocumented configurations over time Copy-pasting directories is not allowed by the AWS provider It makes the initial setup slower than writing a shared module

What are the two competing goals that any multi-environment approach has to balance

Cost and performance Reusing the same underlying logic across environments (DRY) while keeping each environment state, credentials, and blast radius fully isolated from the others Choosing HCL versus a general-purpose programming language Local state versus remote state

Why does the copy-paste-per-environment problem tend to get worse over time rather than staying static

Terraform state files grow in size automatically every day AWS periodically changes resource defaults on its own Each ad hoc edit made to only one copy compounds on the last, and nothing forces the copies back into sync, so undocumented divergence accumulates the longer the setup lives Newer Terraform versions are not backward compatible with older configurations

What does blast-radius isolation refer to in a multi-environment setup

How fast terraform apply completes Limiting how far a mistake, bad apply, or leaked credential in one environment can actually reach, often by placing environments in separate AWS accounts or regions The size of the Terraform state file The number of resources a single module can create

Submit

Mark as complete