landing-zone

The landing-zone repository builds the part of Google Cloud that every product stands on: the organization’s folders and policies, the shared networks, the factories that create each product’s projects and identities, and the audit trail. It is also where the platform’s written design lives: the specification, the contracts every repository implements, the decision records and an illustrated handbook. If you want to know why something on Airframe is the way it is, the answer is usually in this repository’s docs folder.

What it is for

A landing zone is the prepared ground of a cloud organization: the structure, rules and shared services that must exist before any team can safely deploy anything. On Airframe, all of it is Terraform code in this repository, applied by pipelines, so the foundation is reviewed and recorded like everything else.

What is in it

The roots, each a directory of Terraform code with its own state and identity:

organisation: the organization-wide policies, such as no service account keys and no public database addresses, and the deny policy that protects the demo organization’s folder.
folders: a folder per journey, domain and context, from the catalog.
project-factory: one factory per domain, which creates each product’s two projects, its plan and apply identities, its places for Terraform state, its budget once it is billed, and its Ready output; and one for the platform’s own projects.
groups: the Google groups of teams, leads and each product’s users, with their members from the catalog.
network and perimeters: the two shared networks, production and non-production, the shared edge that gives every product its hostname behind single sign-on, DNS, and the VPC Service Controls perimeters, which run in dry-run mode today.
wif and pam: the identity provider that gives pipeline jobs their short-lived identities, and the Privileged Access Manager grants for people.
audit and state: the audit log export and the buckets that hold every root’s Terraform state.

The documents, in docs/:

architecture.md, the specification: what is built and why, with the alternatives considered;
contracts.md: the names and shapes every repository must use, from catalog fields to hostnames;
adaptations.md, bootstrap.md and bootstrap-log.md: where this implementation departs from the original design, the few things created by hand at the start, and the record of every hand step since;
adr/, rehearsals/ and reviews/: decisions, rehearsals of rebuilding and retiring, and reviews of the implementation with what answered each finding;
guides/: the handbook, one illustrated guide per view of the platform, starting with the overview.

How it connects

It reads the catalog. The folders, groups and project factories make what the catalog describes, and the chain after a catalog merge starts this repository’s pipeline first.
Everything else reads it. A project factory’s Ready output tells a product’s own roots, control-plane’s GitLab roots and operations’ roots what exists. The network’s publication tells the factories which projects are attached.
Products publish to it. A product’s routes are published to a shared bucket, and the network root composes the shared edge from them, so a product never holds the edge’s credentials.

Who changes it, and how

Changes are merge requests approved by the platform team. On main, the pipeline plans each root, runs the policy pack on the plan, and applies it under that root’s own identity. The network and perimeter roots plan after the factories have applied, so a new product’s projects reach the network in the same pipeline.

Three roots are not applied by the pipeline: organisation, audit and wif. A pipeline that could rewrite the identity model would be the most powerful one on the platform, so these are applied from a maintainer’s laptop under a time-boxed grant that another member of the platform group approves. The pipeline still plans them every day with a read-only identity, so any change made under a grant shows up as drift.

Every day the scheduled pipeline also plans every root for drift, and asks Google’s Policy Analyzer who holds which role at the organization, failing if anyone holds one they should not.

Where it lives

In the landing-zone repository: