Airframe in ten minutes

Airframe is a way to run cloud infrastructure for many product teams where nobody builds things by hand in a console and nobody holds standing administrator access. A team describes what it wants in files, rules written as code check every change, and pipelines do the work. This page follows one product through its whole life, from the day a team asks for it to the day it is removed.

The examples come from a demo organization, a fictional online retailer, and its orders product. Words in bold are the ones the glossary explains.

1. A team wants a new product

In many companies, a team that needs a new service fills in a form or opens a ticket, then waits while someone creates cloud projects, a code repository, network rules and dashboards by hand. Each of those steps is a chance for a mistake, and nobody can easily see later why things were set up the way they were.

On Airframe, nobody does those steps by hand. The team asks by changing a file, and the platform does the rest.

2. It writes one file in the catalog

The catalog is a git repository of small YAML files that describe the organization: how its work is divided into journeys, domains and contexts, which teams and people exist, and which products they own.

To create the orders product, the team adds one file, products/shop.store.ordering.orders.yaml. It says which team owns the product, which stack it runs (Java, Node or Python), how critical it is, how quickly it must recover from a failure, and its monthly budget in US dollars. That file is the whole request.

3. Rules check it, and owners approve it

The new file arrives as a merge request, like every change on Airframe. The catalog’s pipeline checks it against the catalog’s schema and its consistency rules, for example that the owning team really belongs to the product’s context.

People then approve what the change is for. The catalog itself says who owns what: a new product is approved by its team or by the leads of its context or domain. A service called the gate reads those ownership rules and approves the merge request only once the right people have approved it. The author’s own approval never counts.

4. Pipelines build everything

After the merge, the catalog’s pipeline starts a chain of reconcilers: automated jobs that read the catalog and make the real world match it. Between them, they create:

• two Google Cloud projects for the product, one for production and one for everything else, each with its own pipeline identities;
• a code repository, generated from the golden path template for the chosen stack;
• dashboards for the product’s service, its reliability targets and its cost;
• a hostname behind single sign-on, once the product’s first pipeline has deployed it.

The dashboards live in one Grafana Cloud stack, where the product’s logs, metrics and traces also arrive; observability follows that path.

A note on the merged merge request follows the chain as it runs, so the team can watch its product being built. One step stays separate on purpose: a new product only runs once its projects are linked to billing, which is its own merge request in the landing-zone repository.

5. The team changes its product through merge requests

From then on, the team works in its own repository, which holds the application, its infrastructure as Terraform code, and its pipeline. Every change is a merge request, and every merge request goes through the same steps:

• jobs the team cannot remove check the change, including the policy pack: tested rules that refuse, for example, a storage bucket open to the internet;
• the product’s owners approve it, and then the gate approves it too;
• the executor, a trusted pipeline the gate starts on the platform’s trusted runner, plans the change with the product’s own identities: it works out exactly what the change would do to the cloud and what it would cost each month;
• the executor also deploys a preview of the change, a short-lived copy of the product at its own hostname, so reviewers can try it before the merge;
• a check keeps the merge closed while that cost is above the product’s budget.

Once merged, the pipeline on the main branch applies the change. Nobody runs a command against the cloud from a laptop. The merge also publishes the product’s page in the architecture catalog, a map of every product, its events and its owners.

6. Nobody holds standing write access

People’s everyday accounts can look at production infrastructure but not change it; the one narrow exception is adding a new version of one of their product’s secrets. Pipelines get short-lived identities through workload identity federation: a job proves which repository it belongs to, which environment it deploys to and whether its branch is protected, and only the right job gets the right identity.

When a person really needs to change something by hand, they request a Privileged Access Manager grant: time-boxed, written down, and for administrative roles approved by another member of the platform team. Nobody can create a service account key, the long-lived password of a machine account, for any project of the demo organization.

7. A coding agent works under the same checks

Airframe was designed with a coding agent as a contributor from the start. Skills from the platform-skills repository teach a coding agent the platform’s patterns, and airframe validate runs most of the merge request’s validation on a laptop, so a coding agent can fix its mistakes before it opens a merge request.

The coding agent’s merge request then runs exactly the same checks as a person’s. The approval that lets it merge must come from a named person in the catalog who did not write the change.

8. When the product is retired, the same file says so

Ending a product is also a change to its catalog file. Setting its status to retiring takes its services off the shared edge, so they no longer answer at their hostnames, and scales them to zero, but keeps its data. After the retirement date written in the entry, removed deletes its projects and its repository. Each change of status needs two approvers besides the author.

The name is never reused: a removed product leaves a tombstone in the catalog, so a new product cannot take its name in the same domain. The demo organization’s orders product is retiring today.

Where to go next

• The glossary defines every term on this page in a sentence or two.
• The Concepts section goes one level deeper on each idea: the catalog, reconcilers, identities and access, the gate and the executor, policy as code, releases, previews, observability and the architecture catalog.
• How it works follows a product’s life and a change’s path step by step, with the platform’s own timings.
• The nine “why” pages explain what sets Airframe apart, each with the mechanism that makes it true: start with self-service by merge request and zero standing privilege.