The Platform Reference Architecture

A reference architecture is a shared blueprint — so you never design an internal developer platform from a blank page. This lesson walks the model the community converged on: the five planes every platform is built from (developer control, integration & delivery, resource, observability, and security), the capabilities they add up to, how a single developer request flows through all of them, and why the blueprint hands you the slots while you choose the tools.

What a reference architecture buys you

☺ Like you’re 10: It’s the picture on the box — it names the parts and shows how they fit, so you don’t have to invent a whole platform from scratch.

Here’s a quiet truth: almost every internal developer platform (IDP) ends up needing the same handful of parts. Somewhere to ask for things. Machinery that builds and delivers them. Real infrastructure they run on. A way to watch it all. And guardrails to keep it safe. A reference architecture is the community’s distilled answer to “what are those parts, and how do they fit together?” — written down once so you don’t rediscover it the hard way.

The CNCF’s Platforms Working Group (in TAG App Delivery) published the Platforms White Paper, which defines a platform for cloud-native computing as an integrated collection of capabilities, defined and presented according to the needs of the platform’s users. The paper itself is organised around capabilities; the popular way of drawing those capabilities — the five planes used throughout this lesson — comes from the community reference architectures built on top of it, so don’t be surprised to meet the same model elsewhere with the observability plane labelled the “monitoring and logging plane.” Either way, you don’t copy the blueprint brick-for-brick; you use it as a checklist of slots. That does two things a pile of tools never will: it stops you forgetting a whole area (the classic “nobody actually owns secrets”), and it stops you re-deciding problems the community already solved.

This is the moment the whole course clicks into a shape. In Foundations you learned why platforms exist; in Platform as a Product you learned the mindset. The reference architecture is the map that the five exam domains hang on — every domain lesson is really a deep dive into one plane of this blueprint.

The five platform planes

☺ Like you’re 10: Picture the platform as a building with five areas of work — three you ride from top to bottom, and two that run up the sides touching every floor.

The reference architecture slices the platform into planes — coherent groups of capabilities, each owned by a different specialist. Three of them form a vertical flow, from a developer’s wish at the top down to running infrastructure at the bottom. The other two are cross-cutting: they run alongside all three, because you can’t bolt “watching” or “security” onto one floor and skip the rest. Here they are — and notice how each plane is one member of the Guild:

Developer Control Plane — the surface developers touch 🦋

☺ Like you’re 10: This is the front counter — the buttons, forms, and files a developer uses to ask for what they want.

This is the plane your developers see. It’s the primary configuration layer and the main point of interaction — where a developer expresses intent without needing to know how it’s granted. It has several faces: a portal/GUI (Backstage’s Software Catalog and Software Templates), a CLI for scripting and speed, the GitOps interface (a config repo the developer opens PRs against), and workload specifications like Score, where a developer describes “a container plus a database plus a route” once, in a platform-agnostic file. Crucially, this plane holds no real infrastructure — it just captures what the developer wants and hands it down. Get this plane right and Dot the Duck never learns a cluster’s name.

Integration & Delivery Plane — the machinery 🦫

This is the engine room. It takes the intent captured above and makes it real: CI pipelines build, test, scan, and sign images; the image registry stores them; GitOps engines (Argo CD, Flux) continuously reconcile manifests; and infrastructure orchestrators like Crossplane turn a declared “I need a Postgres” into a real database. Secrets delivery lives here too — the External Secrets Operator or Vault agent injecting credentials at deploy time. If the control plane is what you want, this plane is how it happens. The exam’s joint-largest domain — GitOps & Continuous Delivery, worth 25% — lives almost entirely inside this one plane; we split it across two lessons, GitOps and CI/CD & Progressive Delivery.

Resource Plane — where it actually runs ☁️

☺ Like you’re 10: This is the ground the whole road is built on — the real computers, disks, networks, and databases where your app truly lives.

Everything above is machinery about running software; this is where software actually runs. The Resource Plane is Nimbus: the Kubernetes clusters and their nodes (compute), the storage layer (CSI drivers, StorageClass, persistent volumes), the network (CNI, ingress, the service-mesh data plane), and the backing services — databases, caches, message queues, object storage. The delivery plane provisions into this plane; the control plane never touches it directly. How you shape it — multi-tenancy, right-sizing, autoscaling — is the whole of the Architecture & Infrastructure domain.

Observability & Security — the cross-cutting planes 🐘🐢

☺ Like you’re 10: These two aren’t a floor of their own — they’re the watchtower and the guardrails that run alongside every floor.

The last two planes are drawn beside the stack, not inside it, and that placement is the whole point. The Observability Plane collects metrics, logs, and traces from all three vertical planes and turns them into dashboards and alerts — you watch the portal, the pipelines, and the running pods with the same telescope. The Security Plane applies identity, RBAC, policy, secrets, and supply-chain checks across every plane — an admission controller gating what the delivery plane may run, RBAC deciding what the control plane may request, image signatures verified before anything reaches the resource plane. If you ever find yourself “adding observability later” or “bolting on security to just the prod cluster,” the blueprint is quietly telling you you’ve mis-drawn it. These map to the Observability and Security & Policy domains.

Platform capabilities — what the planes add up to

☺ Like you’re 10: A capability is one useful thing the platform can do for you — “give me a database,” “ship my app,” “show me my logs.” Planes are where capabilities live; capabilities are what developers actually feel.

Planes are only half the picture — the whitepaper itself frames platforms in terms of capabilities. That distinction matters. Planes are the architecture; capabilities are the product. Dot doesn’t experience “the Integration & Delivery Plane”; she experiences “I pushed and it shipped safely.” A mature platform offers most of a familiar menu of capability categories as self-service, each landing in one or more planes:

• Application & development — scaffolding a new service, dev/inner-loop tooling, a browsable service catalog.
• Orchestration & environment management — clusters, namespaces, and on-demand environments (dev, staging, preview).
• Delivery — CI/CD pipelines, GitOps, and progressive rollouts (canary, blue/green).
• Provisioning & data services — request a database, bucket, or queue by declaration, not a ticket.
• Observability — metrics, logs, traces, dashboards, and alerts, wired in by default.
• Identity, access & policy (IAM) — RBAC, admission policy, secrets, and supply-chain checks.
• Cost / FinOps — showback, right-sizing hints, and budget guardrails.

Read that table top to bottom and you’ve just read the syllabus of the whole exam. Every domain is one capability area, resting in one plane of the blueprint.

How one request flows through the planes

☺ Like you’re 10: Follow a single wish — “I want a new service with a database” — as it slides down through the floors and comes back to Dot, running.

The planes come alive when you trace one request through them. Watch Dot ship a brand-new checkout service without filing a single ticket:

1. Control plane. Dot opens the portal and picks the “golden-path Java service” template — or, equivalently, writes a small score.yaml and opens a pull request. Either way, she has just declared intent.
2. Delivery plane. CI builds, tests, scans, and signs the image, then pushes it to the registry and bumps the tag in Git. The GitOps engine (Argo CD or Flux) notices the change and reconciles; Crossplane sees the declared postgres resource and provisions a real database.
3. Resource plane. Pods schedule onto the cluster, the database comes up, and networking wires the route. The wish is now real.
4. Security plane (all along). Admission control refused any unsigned or non-compliant image; RBAC confirmed Dot’s team may do this; secrets were injected, never committed.
5. Observability plane (from the first pod). Metrics, logs, and traces start flowing; an SLO dashboard and alerts light up automatically.

Dot experienced one step — “new service, please” — and never touched a cluster, a pipeline, or a secret. That end-to-end path, gated by security and watched by observability, is the golden path the whole course is building.

Here’s the intent Dot declared — a Score file. Notice it names things from several planes at once (a workload for the resource plane, a database to be provisioned by the delivery plane, a route for networking) yet says nothing about how any of it is satisfied. That “what, not how” is the entire trick:

apiVersion: score.dev/v1b1
metadata:
  name: checkout                 # one workload, described once, platform-agnostic
containers:
  checkout:
    image: "."                   # "." = the real, signed tag is supplied at deploy time
    variables:
      DB_HOST: "${resources.db.host}"   # wired from the provisioned database
    resources:
      requests: { cpu: "100m", memory: "128Mi" }
service:
  ports:
    www:
      port: 80
      targetPort: 8080
resources:
  db:
    type: postgres               # the platform decides HOW (Crossplane? an operator? RDS?)
  web:
    type: route                  # the platform decides HOW (ingress? gateway? mesh?)
    params:
      host: checkout.acme.internal
      path: /
      port: 80                   # the service port declared above

Dot wrote what she needs; the delivery plane decides how to grant it and the resource plane runs it. Swap Crossplane for a cloud operator, or one cluster for another, and this file doesn’t change. That portability is the reference architecture doing its job. One caveat worth internalising: the resource types (postgres, route) and the params each one accepts are defined by your platform’s provisioners, not by the Score spec — that indirection is exactly the point, and it’s also why two platforms can read the same file and grant it differently.

Interfaces: a platform is a set of APIs

☺ Like you’re 10: The same wish can be granted three ways — click a button, type a command, or write it in a file. Underneath all three is one API.

Here’s the deepest idea in the whole blueprint: every capability is exposed through an interface, and good platforms expose the same capability through several of them. A portal (GUI) is best for discovery and for humans browsing what exists. A CLI is best for speed and scripting. An API — very often the Kubernetes API plus GitOps — is best for automation and for other systems. They’re three doors into the same room, so nobody is forced through a door that doesn’t suit them.

And because Kubernetes is itself an API server, “the platform is a set of APIs” is not a slogan — it’s literally true. A Custom Resource is an API. A Score file is an API request. A Backstage template is a GUI that emits API calls. The portal you build is a friendly face over the same endpoints your CLI and your CI pipeline hit. Here is one capability — “create a service on the golden path” — offered through all three interfaces:

# One capability, three interfaces — same golden path, same guardrails.

# 1) Portal (GUI): Dot clicks "Create Service" in Backstage and fills a short form.
#    The scaffolder opens a new repo and a pull request for her.

# 2) CLI: the identical golden path, scripted for speed. "platform" stands in for
#    your own in-house CLI -- the name and flags are whatever your team ships.
platform new service checkout --template golden-java --db postgres

# 3) API / GitOps: commit the intent; the delivery plane reconciles it.
git add checkout/score.yaml
git commit -m "add checkout service"
git push
# Argo CD syncs the manifests -> Crossplane provisions the database
# -> pods schedule on the cluster. Same result, whichever door you use.

The portal itself is described declaratively too. In Backstage, a catalog-info.yaml registers a component and — in one small file — points at every plane: its owner (security/IAM), its CD app (delivery), its dashboards (observability), and the resources it depends on (resource plane). One catalog entry becomes the single pane of glass over all five planes — with one caveat: only the backstage.io/* keys are core Backstage. Annotations like argocd/* and grafana/* are read by the plugins of the same name, so check the exact key against the plugin you actually install:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout
  description: Checkout service for the storefront
  annotations:
    argocd/app-name: checkout                            # delivery plane
    grafana/dashboard-selector: "tags @> 'checkout'"     # observability plane
    backstage.io/techdocs-ref: dir:.                     # docs, in the portal
  tags: [golden-path, java]
spec:
  type: service
  lifecycle: production
  owner: team-payments                          # security / IAM: who owns & can access
  system: storefront
  dependsOn:
    - resource:default/checkout-db              # resource plane

Build, buy, or assemble?

☺ Like you’re 10: You don’t forge a platform from raw metal, and you can’t buy one in a box. You assemble it — snapping proven pieces into the blueprint’s slots and adding a little glue.

The reference architecture quietly settles the oldest platform argument — build vs buy — with a third answer: assemble. You almost never build a GitOps engine, a metrics database, or a policy engine from scratch; those slots are already filled by mature, battle-tested CNCF projects. And you rarely buy one monolithic platform, because your slots and constraints are specific to your org. Instead you assemble: the blueprint names the slots, you pick the best-fit project for each, and you build only the thin glue — the golden-path templates, the Crossplane compositions, the portal — that makes the pieces feel like one product. That glue, not the tools, is where your platform’s value actually lives.

Which project fits which slot is exactly the map on the Tool Landscape page — think of it as the shopping list that pairs with this blueprint. Every project on the CNPE tool list (Argo, Crossplane, Flux, Kyverno, OPA, Prometheus, OpenTelemetry, Istio, and the rest) slots cleanly into one of the five planes you just met.

You now have the map the rest of the course fills in. Next, Professor Owl and Sol descend into the first plane on the exam — the Resource Plane and its architecture: multi-tenancy, networking, storage, and right-sizing the ground everything runs on.