Skip to main content

Infrastructure as code

Infrastructure as code (IaC) means the organization structure, the networks, the security services, identity and the pipelines of every edition of the BuiltForProd Baseline are described in files, reviewed as pull requests, and created by a pipeline that runs the same code every time. Nothing is clicked together in a console: if it is not in a repository, it does not exist, and if it appears in the cloud without a commit, it is drift.

Why it matters in production​

A production environment built by hand cannot be rebuilt, reviewed or reasoned about. The questions that matter after an incident (what changed, who changed it, can we recreate it in another region) have no answer when the infrastructure lives in a console history. IaC gives every change an author, a review, a plan that shows the effect before it happens, and a history that can be reverted.

It also makes environments alike. Development, staging and production are generated from the same definitions with different values, so "it works in staging" means something. And it makes the platform transferable: a customer receives repositories, not a running environment nobody can reproduce.

How each edition implements it​

Every edition ships seven repositories with the same roles: the Baseline (the landing zone every other repository depends on), the web app infrastructure, the web app code, the GitOps repository, the ETL infrastructure, the ETL code and the secrets repository. All infrastructure is written in OpenTofu modules orchestrated by Terragrunt, planned on every pull request and applied on merge.

The mechanics that make this hold, per edition:

PracticeAWS Enterprise BaselineAzure Enterprise BaselineGCP Enterprise Baseline
One definition per unit, generated per account or stageunits/, stacks/, environments/units/, stacks/, environments/units/, stacks/, environments/
No hard-coded CIDRs; every address comes from one address plancheck-no-hardcoded-cidrs.py, check-vpc-maps.pycheck-no-hardcoded-cidrs.py, check-vnet-maps.pycheck-no-hardcoded-cidrs.py, check-network-maps.py
No cloud IDs typed in codeOrganizations outputsorg_subscriptions.hcl, written by the organizations unitorg_projects.hcl, written by the organizations unit
Every dependency has complete mock outputscheck-mock-outputs.pycheck-mock-outputs.pycheck-mock-outputs.py
Every unit supplies its module's required inputscheck-required-inputs.pycheck-required-inputs.pycheck-required-inputs.py
Versions pinned in one placeroot.hcl, check-module-versions.pyroot.hcl, check-module-versions.pyroot.hcl, check-module-versions.py
State, one entry per unitS3 bucket acme-use1-root-tfstateStorage account stacmeeus2roottfstate, container tfstateCloud Storage bucket acme-usw1-root-tfstate
Changes reach the cloud only through the pipelineplan.yml on pull requests, apply.yml on merge to mainplan.yml on pull requests, apply.yml on merge to mainplan.yml on pull requests, apply.yml on merge to main

The guard scripts live in scripts/ of each Baseline repository and run in pre-commit and again in CI before any plan. State is split per unit in every edition, so a bad write is recoverable from a previous version and the blast radius of any run stays small.

Deployment-specific values are tagged, not buried​

The repositories are templates: they are forked and customized per customer. In every repository of every edition, everything that must be set for a deployment carries a # TODO: comment, and everything that may be changed carries a # @optional: comment with its consequence and, where it costs money, its price.

Finding every choice and every required value
git grep "TODO: " # things you MUST set for your deployment
git grep "@optional: " # things you MAY change; the platform works without them

A TODO: never marks something optional, and something optional is never a TODO:. The deployment guides tell operators to search for TODO: to find what they must set.

AWS Enterprise Baseline​

The landing zone acme-aws-platform-baseline is the hub the other six repositories depend on: acme-aws-blueprint-webapp-infra and acme-aws-blueprint-etl-infra build workloads on top of it, and the code, GitOps and secrets repositories complete the set.

State lives in one encrypted, versioned S3 bucket in the management account, acme-use1-root-tfstate, with native locking. Every address comes from the VPC map through IPAM, and check-vpc-maps.py rejects an invalid or overlapping map. Account IDs come from the Organizations unit's outputs. Secrets are SOPS-encrypted, and write-only arguments keep the DocumentDB password out of state. The AWS Enterprise Baseline overview holds the detail.

Azure Enterprise Baseline​

The seven repositories are acme-azure-platform-baseline and acme-azure-blueprint-webapp-infra, -webapp-code, -webapp-gitops, -etl-infra, -etl-code and -secrets. The modules are thin wrappers around native azurerm, azuread and azapi resources, one resource category per module; no module comes from a registry.

State lives in one storage account in acme-core-root, stacmeeus2roottfstate, reached with Microsoft Entra authentication only and locked with blob leases. Every unit writes its own blob in the tfstate container, named after its path in the tree.

Every address is written once, in vnet_map.yaml; check-no-hardcoded-cidrs.py and check-vnet-maps.py reject a range anywhere else and an invalid or overlapping map.

Subscription IDs are never typed. The organizations unit writes org_subscriptions.hcl after every apply, a committed file with the tenant, management-group and subscription IDs and no secret, and root.hcl targets each unit at its subscription by name through it.

CI signs in with a federated identity, so no client secret exists, and runs on the self-hosted Container Apps runners once the repository variable RUNNER_LABELS is set. The Azure Enterprise Baseline overview holds the detail.

GCP Enterprise Baseline​

The seven repositories are acme-gcp-platform-baseline and acme-gcp-blueprint-webapp-infra, -webapp-code, -webapp-gitops, -etl-infra, -etl-code and -secrets. The modules are thin, one resource category each, and none comes from a registry.

State lives in the Cloud Storage bucket acme-usw1-root-tfstate in the seed project, with native locking and versioning. Every unit writes its own object prefix, derived from its path in the tree.

Every address is written once, in network_map.yaml; check-no-hardcoded-cidrs.py and check-network-maps.py reject a range anywhere else and an invalid map.

Project IDs and numbers come from org_projects.hcl, which the organizations unit writes after every apply (scripts/write-org-projects.py) and which is committed. Before it exists, root.hcl falls back to the deterministic project IDs. Nothing in root.hcl calls gcloud or needs credentials, so terragrunt stack generate, render and validate work offline.

CI authenticates through Workload Identity Federation and impersonates each project's deployer service account from the provider configuration that root.hcl generates. The GCP Enterprise Baseline overview holds the detail.

Worked example: adding a region​

On the GCP edition, adding a region is a folder change, not a code change. network_map.yaml already reserves "region 1": us-east1, slug use1, 10.16.0.0/12. An engineer adds environments/<folder>/<project>/us-east1/ folders, each with a region.hcl and a terragrunt.stack.hcl listing the region's units.

The ipam unit lists the live regions from the folders, and the preconditions of its terraform_data.drift resource fail the plan when a region folder has no map entry or a different slug. The gcp.resourceLocations organization policy follows on its own, because the organizations unit computes its allowed locations from the same folders. No unit definition is edited.

The AWS and Azure editions work the same way: their address plans reserve space for a second region, and their ipam units fail the plan when the folders and the map disagree.

Common mistakes​

  • Treating the console as a shortcut. A console change is not in the code, so the next apply reverts it or the drift job reports it. Make the change in a pull request.
  • Applying from a laptop. Changes reach the cloud through pull request, plan, merge and the apply workflow. A local apply bypasses review, the environment gate and the serialized queue.
  • Typing an IP range or an account, subscription or project ID. The guards reject CIDR literals; IDs come from the Organizations outputs on AWS, org_subscriptions.hcl on Azure and org_projects.hcl on GCP.
  • Editing generated files. Anything under .terragrunt-stack/ is regenerated, and org_subscriptions.hcl and org_projects.hcl are rewritten by the organizations unit; change the definition, the stack file or the unit's inputs.
  • Changing a default without updating its tag or its price comment. The tags are how the next reader finds what was decided.