environment-management

Environment Management

"It worked in staging" loses all meaning the moment staging is a different system than prod — different topology, different config format, a manually patched box nobody touched since it was built. Staging's entire job is to be a trustworthy predictor of what will happen in prod. Every divergence between them is a bug in that predictor, whether or not anyone notices it before the next incident.

The only differences that should exist between environments are the ones you'd defend out loud: scale, non-critical data, cost. Everything else — topology, versions, how config is structured — should be identical.

Environments should differ by the values you feed the same code, never by forking the code itself.

1. Make the difference a values file, not a branch

The moment staging and prod are separate directories or separate branches, they will diverge — someone fixes a bug in one and forgets the other, or adds a resource to prod under deadline pressure and never backports it. One codebase, one set of modules, environment-specific .tfvars or equivalent values files is the only structure that makes divergence visible in a diff instead of invisible until it breaks something.

See terraform-modules for the module-interface side of this and infrastructure-as-code for the state-isolation side — each environment still needs its own state file even though it shares code.

Done when: the diff between any two environments is fully expressed in their values files, with zero resource-definition files that exist in one environment's directory and not another's.

2. Give every pull request its own throwaway environment

A shared staging environment queues every team behind whoever's currently testing something in it, and a broken staging blocks everyone at once. Ephemeral, per-PR preview environments — spun up on open, torn down on merge or close — remove the queue and catch integration bugs before merge instead of after, when they're entangled with everyone else's changes.