Skip to main content

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​

StageSlugPurposeIsolation domain
sandboxsbxExperimentation; looser access, no production data, excluded from compliance evaluationnonprod
devdevDaily development and automated testing; every merge to main deploys herenonprod
stagingstgProduction mirror for QA and release verification; high-availability layout like prodnonprod
prodprdCustomer workloads; changes only through reviewed pull requests and the prod GitHub Environmentprod

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:

ItemAWS Enterprise BaselineAzure Enterprise BaselineGCP Enterprise Baseline
Isolation unitAccount plat-prod (141414141414) and its siblingsSubscription acme-plat-prod and its siblingsProject acme-plat-prod and its siblings
Landing-zone unitsstacks/plat-account, seven unitsstacks/plat-subscription, eight unitsstacks/plat-project, four units
Resource namesacme-usw2-prd-vpc, acme-usw2-dev-eksacme-eus2-prd-aks, acme-eus2-dev-aksacme-usw1-prd-gke, acme-usw1-dev-gke
Landing-zone valuesSSM parameters /acme/usw2/<stage>/<service>/<key>Contract vault kv-acme-eus2-<stage>-platParameter 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:

Valuedevprod
public_domaindev.company.comprod.company.com
eks_node_min_size / max2 / 33 / 4
argocd_hafalsetrue
argocd_auto_synctruefalse
log_retention_days30365
docdb_instance_count13
docdb_deletion_protectionfalsetrue
redis_num_cache_clusters / redis_multi_az1 / false2 / true

On the Azure edition:

Valuedevprod
aks_sku_tierFreeStandard
aks_system_min23
nap_cpu_limit32128
front_door_skuStandard_AzureFrontDoorPremium_AzureFrontDoor
mongo_compute_tier / mongo_high_availabilityM10 / falseM30 / true
redis_sku_name / redis_high_availabilityBalanced_B0 / falseBalanced_B1 / true
delete_locksfalsetrue
argocd_ha / argocd_auto_syncfalse / truetrue / false
enable_availability_testfalsetrue

On the GCP edition:

Valuedevprod
gke_zones23
nap_cpu_limit / nap_memory_limit32 / 128128 / 512
gke_deletion_protectionfalsetrue
armor_previewtruefalse
firestore_pitrfalsetrue
firestore_backup_retention_days035
valkey_node_type / valkey_replicasSHARED_CORE_NANO / 0STANDARD_SMALL / 1
argocd_ha / argocd_auto_syncfalse / truetrue / 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.

StageTriggerApprovalRollback
devMerge to mainNonegit revert, merge, auto-apply
stagingSame mergePull request reviewgit revert, merge, auto-apply
prodSame mergeRequired reviewers of the prod Environmentgit 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 prod Environment 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.