Environments and promotion
An environment is a stage of the software lifecycle with its own account, subscription or project, its own network and its own sizing; promotion is how one reviewed change moves through those stages in order. Every edition of the BuiltForProd Baseline has four stages, sandbox, dev, staging and prod, each an isolation unit in the plat group, and every stage is generated from the same definitions with a small block of per-stage values.
Why it matters in production
Environments that were built by hand drift apart, and then staging proves nothing about prod. Environments that share an account, subscription or project share a blast radius, and then a mistake in dev can touch customer data. Separate isolation units give each stage a hard identity and billing boundary; identical definitions give each stage the same shape; explicit per-stage values make the differences reviewable; and a fixed promotion order with approvals at the right point makes every production change deliberate.
How each edition implements it
One isolation unit per stage
| Stage | Slug | Purpose | Isolation domain |
|---|---|---|---|
| sandbox | sbx | Experimentation; looser access, no production data, excluded from compliance evaluation | nonprod |
| dev | dev | Daily development and automated testing; every merge to main deploys here | nonprod |
| staging | stg | Production mirror for QA and release verification; high-availability layout like prod | nonprod |
| prod | prd | Customer workloads; changes only through reviewed pull requests and the prod GitHub Environment | prod |
The slugs and the two isolation domains are the same in every edition. What carries each stage, how its resources are named and where the landing zone publishes its values differ:
| Item | AWS Enterprise Baseline | Azure Enterprise Baseline | GCP Enterprise Baseline |
|---|---|---|---|
| Isolation unit | Account plat-prod (141414141414) and its siblings | Subscription acme-plat-prod and its siblings | Project acme-plat-prod and its siblings |
| Landing-zone units | stacks/plat-account, seven units | stacks/plat-subscription, eight units | stacks/plat-project, four units |
| Resource names | acme-usw2-prd-vpc, acme-usw2-dev-eks | acme-eus2-prd-aks, acme-eus2-dev-aks | acme-usw1-prd-gke, acme-usw1-dev-gke |
| Landing-zone values | SSM parameters /acme/usw2/<stage>/<service>/<key> | Contract vault kv-acme-eus2-<stage>-plat | Parameter Manager parameters in acme-plat-<stage> |
Each stage also gets its own network from the address plan; see landing zones and the landing-zone contract.
The same shape, different values
The blueprint repositories of every edition describe each stage with one stack file that instantiates a template and sets only what differs. The web platform's dev and prod files are identical apart from their values. On the AWS edition:
| Value | dev | prod |
|---|---|---|
public_domain | dev.company.com | prod.company.com |
eks_node_min_size / max | 2 / 3 | 3 / 4 |
argocd_ha | false | true |
argocd_auto_sync | true | false |
log_retention_days | 30 | 365 |
docdb_instance_count | 1 | 3 |
docdb_deletion_protection | false | true |
redis_num_cache_clusters / redis_multi_az | 1 / false | 2 / true |
On the Azure edition:
| Value | dev | prod |
|---|---|---|
aks_sku_tier | Free | Standard |
aks_system_min | 2 | 3 |
nap_cpu_limit | 32 | 128 |
front_door_sku | Standard_AzureFrontDoor | Premium_AzureFrontDoor |
mongo_compute_tier / mongo_high_availability | M10 / false | M30 / true |
redis_sku_name / redis_high_availability | Balanced_B0 / false | Balanced_B1 / true |
delete_locks | false | true |
argocd_ha / argocd_auto_sync | false / true | true / false |
enable_availability_test | false | true |
On the GCP edition:
| Value | dev | prod |
|---|---|---|
gke_zones | 2 | 3 |
nap_cpu_limit / nap_memory_limit | 32 / 128 | 128 / 512 |
gke_deletion_protection | false | true |
armor_preview | true | false |
firestore_pitr | false | true |
firestore_backup_retention_days | 0 | 35 |
valkey_node_type / valkey_replicas | SHARED_CORE_NANO / 0 | STANDARD_SMALL / 1 |
argocd_ha / argocd_auto_sync | false / true | true / false |
In every edition staging mirrors prod's high-availability layout (zone-redundant or multi-AZ data stores, ArgoCD in HA mode, three system nodes) so that failover is exercised before it matters in prod; dev stays single-instance for cost. Each value is tagged # @optional: with its consequence and price, such as about $60 per month per extra DocumentDB instance on AWS, M30 at about $270 per month on Azure, or about $49 per month per GKE system node on GCP. The mechanism is described under Terragrunt units and stacks.
Promotion
Infrastructure repositories. The model is the same in every edition. One merge to main plans and applies every stage. The blueprint workflows run a matrix of dev, staging and prod whose jobs start in parallel (fail-fast: false), each under the GitHub Environment of the same name; the prod job waits for that Environment's required reviewers. The landing zone's apply is one job gated by the prod Environment. Applies queue per branch and are never cancelled.
| Stage | Trigger | Approval | Rollback |
|---|---|---|---|
| dev | Merge to main | None | git revert, merge, auto-apply |
| staging | Same merge | Pull request review | git revert, merge, auto-apply |
| prod | Same merge | Required reviewers of the prod Environment | git revert plus manual validation |
Application code. Images are built once and promoted by immutable tag (main-<sha> per build, vX.Y.Z added at release). The web application reaches dev on merge (auto-merged deploy pull request, ArgoCD auto-sync), staging on a GitHub Release (auto-merged, auto-sync), and prod through promote-prod.yml with the release tag: prod Environment approval, a deploy pull request a person merges, then a manual ArgoCD sync. The ETL pipeline reaches dev on merge and staging on release, then waits for prod approval inside the release workflow before deploying the same tag to prod. Rollback is promoting or re-running the previous tag; nothing is rebuilt. See immutable artifacts and GitOps.
Access narrows toward prod
In every edition engineers change the lower stages and read prod; only Platform Leads and DevOps Leads can change prod. On AWS that is PowerUser in sandbox, dev and staging and ReadOnly in prod. On Azure it is Contributor on the lower stages (developers on sandbox and dev, their leads also on staging) and read-only on prod through ACME_AllEngineers, with Owner for the leads eligible through PIM when it is on. On GCP it is an editor bundle on the lower stages and a viewer bundle on prod, with Owner for the leads only through Privileged Access Manager. Secrets follow the same line: every engineer group can decrypt the sandbox and dev secrets, only the lead groups can decrypt staging and prod. In every Baseline, code ownership assigns environments/plat/prod/ to the platform leads and the security team; an approval from either team satisfies the rule. See least privilege.
Worked example: staging backups
On the GCP edition, staging keeps no scheduled Firestore backups: its stack file sets firestore_backup_retention_days = 0, while prod keeps 35 days. The team wants a week of backups in staging to rehearse a restore. An engineer sets firestore_backup_retention_days = 7 in environments/staging/us-west1/terragrunt.stack.hcl of the web app infrastructure and opens a pull request.
The plan workflow shows one change in the staging matrix job and none in dev or prod, because their stack files carry their own values. A reviewer approves; on merge, the dev and prod apply jobs are no-ops, and the staging job adds the backup schedule. Had the change been for prod, the prod job of the same merge would have waited for the prod Environment's required reviewers first.
Common mistakes
- Testing in prod because dev "is not the same". Dev is generated from the same definitions; the differences are the values in its stack file, and they are the only differences.
- Setting a per-stage value in the template or the definition. A template default applies to every stage; per-stage choices belong in the stage file, tagged.
- Promoting by rebuilding. Staging and prod run the tag that was built for dev; a rebuild is a different artifact.
- Granting prod write access to speed up a release. Prod changes go through the
prodEnvironment and a person's merge; that is the control, not an obstacle. - Adding a stage without placing it in an isolation domain. A new stage belongs in exactly one domain in
network.hcl, in every edition; see hub-and-spoke networking.