Landing-zone contract

The landing-zone contract is the set of values a Baseline publishes for each stage so that the blueprints can build on it without reading its state or looking anything up: network and subnet IDs, DNS zones, the registry, identities and shared templates. Every edition of the BuiltForProd Baseline publishes one per workload stage, in the cloud's own configuration store, from one unit in the stage's stack.

Why it matters in production

A blueprint needs the landing zone's IDs: the subnet its cluster runs in, the zone its records go into, the registry its images come from. It must not create what the landing zone owns, and it should not read the landing zone's state, because reading state couples two repositories to each other's internals and needs read access to everything in that state. A published contract is a narrow, named interface: the landing zone decides what it exposes, the blueprint reads only that, and either side can change its internals without breaking the other. Nothing in a blueprint names a subnet ID, so the same blueprint code deploys to every stage and every customer.

How each edition implements it

The shape is the same in every edition. A unit in each workload stage's stack writes the values the blueprints need; the blueprint modules read them by name at plan time; and the code pipelines write back the one kind of value the infrastructure must learn from them, the deployed ETL trigger image tag. Nothing in the contract is a secret: the values are IDs, names and templates.

Aspect	AWS Enterprise Baseline	Azure Enterprise Baseline	GCP Enterprise Baseline
Publishing unit	ssm-publish	kv-publish	pm-publish
Store	SSM Parameter Store in the workload account	Contract vault kv-acme-eus2-<stage>-plat	Parameter Manager in acme-plat-<stage>
Naming	/acme/usw2/<stage>/<service>/<key>	<area>--<name>	<service>--<key>
Count	VPC, Transit Gateway attachment and account ID	30 secrets: 25 base, 5 platform services	24 parameters: 19 base, 5 platform services
Blueprint readers	aws_ssm_parameter data sources	azurerm_key_vault_secret data sources	Parameter Manager data sources in one shared contract.tf

AWS Enterprise Baseline

The ssm-publish unit of each workload account writes /acme/usw2/<stage>/vpc/id, vpc/cidr, vpc/private_subnet_ids and vpc/public_subnet_ids, /tgw/attachment_id and /account/id. The blueprint modules read them with SSM Parameter Store data sources at plan time. The ETL Lambda's deployed tag is the SSM parameter /acme/usw2/<stage>/etl-trigger/image_tag, which the pipeline writes.

Azure Enterprise Baseline

The kv-publish unit in each plat subscription writes 30 secrets into the stage's contract vault, kv-acme-eus2-<stage>-plat, named <area>--<name>:

• 25 base values. The spoke VNet (ID, CIDR, name, resource group), its eight subnets and its route table (vnet--subnet--aks, vnet--subnet--endpoints and so on); the hub (network--firewall-private-ip, none in the spoke_nat egress mode; network--hub-vnet-id; network--dns-resolver-ip); the stage's public zone, the private zone and the Private Link zones; the subscription and tenant IDs; the principal IDs of the code pipelines' identities and the IDs of the custom roles the blueprints grant them; and the WAF template waf--policy-template.
• 5 platform-services values, behind the Terragrunt feature platform_services: the stage application workspace, the security action group, the secrets syncer's principal ID, and the registry's login server and ID.

The blueprint modules read the secrets with azurerm_key_vault_secret data sources, one per name their unit lists in contract_secrets. The blueprint infrastructure pipelines hold Key Vault Secrets Officer on the vault, because they also record their own values there, such as the Web App Blueprint's front-end endpoints. The code pipelines get one secret each, never the whole vault: the ETL code writes etl-trigger--image-tag, and the web app code reads frontend--storage-account. The Key Vault explainer covers the vault's controls.

GCP Enterprise Baseline

The pm-publish unit in each plat project writes 24 Parameter Manager parameters named <service>--<key>, each with a single version v1 that is updated in place:

• 19 base values. The domain VPC, the host project and the stage's subnets (vpc--subnet--nodes, vpc--subnet--data, vpc--subnet--proxy, vpc--subnet--psc, the secondary range names, the CIDR and the GKE control-plane range); the public and private DNS zones with their projects; the project ID and number; and the Cloud Armor rule template waf--policy-template.
• 5 platform-services values, behind the unit's platform_services feature flag: platform--artifact-registry, platform--notification-channel, platform--alerts-topic, platform--kms-sops-key and platform--secrets-syncer-sa.

Every blueprint module that needs a landing-zone value carries the same contract.tf, one data source per parameter its unit lists in contract_parameters. The Web App Blueprint's guard scripts/check-contract.py fails a pull request that reads a parameter the landing zone does not publish, or reads one its unit does not list. The blueprints record their own values beside the contract, such as frontend--image-tag and etl-trigger--image-tag.

Worked example: a cluster finds its subnet

On the Azure edition, the Web App Blueprint's aks unit lists vnet--subnet--aks among its contract_secrets. When the dev plan runs, the module's contract.tf reads that secret from kv-acme-eus2-dev-plat and passes the subnet ID to the cluster. The prod plan reads the same name from kv-acme-eus2-prd-plat and gets the prod subnet. Nothing in the blueprint names a subnet ID, a VNet or a subscription; the same code deploys every stage, and a change to the address plan in the Baseline reaches the cluster through the contract.

Common mistakes

• Reading the Baseline's state from a blueprint. It couples the repositories and needs access to everything in that state; read the contract instead.
• Writing a contract value by hand. The publishing unit owns every base value and the next Baseline apply overwrites a hand edit; a change belongs in the unit's inputs, through a pull request.
• Deleting a value a blueprint still reads. The blueprint's next plan fails on the missing parameter or secret; on GCP, the guard catches a parameter the landing zone does not publish before the plan runs.
• Putting a secret in the contract. The contract holds IDs and names that every blueprint pipeline can read; secrets belong in the Secrets Blueprint and the application's own vault or secret store.