Why platform teams exist
Picture the company after a few years of "you build it, you run it". Forty product teams each own their services end to end. That was the point: no ticket to an ops team, no waiting. But look at what every one of those teams now has to know to ship one new service: a Dockerfile that passes the security scan, a Helm chart, the Kubernetes namespace conventions, the network policies, how to ask for a database, how to get its password into the pod without putting it in git, which dashboards and alerts are mandatory, how to register the service for on-call. Each team learns it separately, gets half of it wrong, and copies the mistakes into the next service.
That load has a name: cognitive load, the amount a team has to keep in its head to do its job. The book Team Topologies (Matthew Skelton and Manuel Pais, IT Revolution, 2019) made it the design constraint for how a company organises its teams: a team that has to understand too much ships slowly and makes mistakes. Platform engineering is the answer the industry converged on: a dedicated team builds an internal developer platform (IDP) that takes most of that load off the product teams.
What you need to know already: the Kubernetes chapters (objects, RBAC, CRDs and controllers, Helm), the AWS chapters (an account, IAM credentials, S3 and RDS), and the delivery chapters (git.lab, merge requests, GitOps). This chapter builds on all of them: the platform is made of the things you already run.
The four team types
Team Topologies describes four kinds of teams and three ways they interact. You will meet these words in every platform discussion:
| Team type | What it does |
|---|---|
| Stream-aligned | Owns a flow of change for a business area (orders, payments). Most teams. |
| Platform | Provides internal services that stream-aligned teams use on their own. |
| Enabling | Specialists who help other teams learn a skill, then step back. |
| Complicated-subsystem | Owns a part that needs deep expertise (a pricing engine, a video codec). |
| Interaction mode | Meaning |
|---|---|
| Collaboration | Two teams work closely for a while to discover something new. |
| X-as-a-Service | One team consumes what another provides, with minimal talking. |
| Facilitating | One team helps another get better, without doing the work for it. |
The platform team's normal mode is X-as-a-Service: a product team gets a database by filling in a form or writing ten lines of YAML, not by opening a ticket and waiting for a person. The book's warning is the Thinnest Viable Platform: build the smallest platform that removes real load. Sometimes that is a wiki page with a good template. A platform that tries to do everything becomes a second bureaucracy.
What an internal developer platform is made of
The CNCF's Platforms White Paper (TAG App Delivery, 2023) defines a platform as an integrated collection of capabilities, presented according to the needs of its users, and lists the attributes that make one worth having: it is run as a product (the product teams are its customers), it is self-service, it reduces cognitive load, it is secure by default, and its parts are optional and composable rather than all-or-nothing.
In practice almost every IDP has three layers. This chapter builds one of each:
developers ──▶ PORTAL Backstage: the catalog of everything, templates,
docs next to the code, a view of what runs
│
▼
PLATFORM APIs Crossplane: "give me a database" as a Kubernetes
object, with the company's defaults baked in
│
▼
INFRASTRUCTURE the cloud account (AWS), the cluster, git.lab,
the delivery pipeline you already run
The portal is where people find things and start things. The platform APIs are where requests become real resources, built the same way every time. The infrastructure underneath does not change: the platform is a layer of opinions and automation on top of it, not a replacement.
Golden paths
A golden path is the supported, opinionated, well-paved way to do a common thing: create a new service, get a database, publish an API. Spotify, where the term comes from (and where Backstage was built before it was open-sourced in 2020), describes it as the path the platform team actively maintains and supports. Two properties matter:
- It is optional. Teams may leave the path, but then they own what they build. A golden path that is mandatory becomes a gate, and gates breed tickets.
- It encodes the boring decisions. Encryption on, backups on, tags for cost, the on-call rotation registered, the service in the catalog. A developer who takes the path gets them without knowing they exist.
A typical golden path for "new Java service" ends with: a repository created from a template, the service registered in the catalog with its owner, a CI pipeline, a database requested through a platform API, dashboards and alerts generated, and docs published - in minutes, not weeks.
Self-service through APIs, not tickets
The old way to get a database was a ticket. Someone on an infrastructure team read it, clicked through a console or ran Terraform, and replied days later with a hostname and a password in a chat message. The platform way is an API: the request is a declarative object that a controller turns into real resources.
apiVersion: platform.lab/v1alpha1
kind: Database
metadata:
name: orders
namespace: team-orders
spec:
size: small
The developer asks for a small database. The platform team has decided, once, what "small" means (instance class, storage, engine version, backups, encryption, deletion protection) and where it runs. That decision lives in a Composition (Crossplane), reviewed in git like any other code. The request lives in the team's namespace, so Kubernetes RBAC already says who may ask.
Platform as a product
The hardest part of platform engineering is not technical. A platform team that builds what it finds interesting, and then mandates it, fails. One that treats product teams as customers succeeds. In practice:
- Talk to your users. Shadow a team creating a new service. Count the steps and the waiting. That list is your backlog.
- Measure adoption, not existence. How many new services came from the template this quarter? How long from "I need a database" to a working connection string?
- Measure outcomes. The DORA metrics you met in the delivery chapters (deployment frequency, lead time for changes, change failure rate, time to restore) should move for the teams on the golden path.
- Keep an escape hatch. Teams with a real need to leave the path must be able to, and you learn from why they did.
In an interview: an internal developer platform is a self-service layer that a platform team runs as a product for stream-aligned teams, to reduce their cognitive load. It usually combines a portal (Backstage), platform APIs that turn requests into infrastructure (Crossplane, Terraform modules behind an API), and golden paths: supported, optional, opinionated ways to do the common things.
What this chapter builds
You will install Crossplane v2 on the lab cluster and use it to build platform APIs: first raw managed resources (an S3 bucket, an RDS database in the lab's AWS account, Kubernetes objects through provider-kubernetes), then your own APIs with CompositeResourceDefinitions and Compositions. You will debug them the way you will on call: conditions, events, crossplane resource trace. You will learn what can destroy data (a renamed resource in a Composition) and how to make that impossible.
Then you will put Backstage in front of it: the software catalog (catalog-info.yaml, owners, relations), Software Templates that create a repository and register it, TechDocs and the Kubernetes view. The incidents at the end are the three classics of a young platform: credentials that expire, a Composition change that would replace a database, and a template that registers a broken entity.
Versions in this chapter (checked against the projects' releases and source in October 2026): Crossplane v2.4.2, the crossplane CLI v2.5.0, function-patch-and-transform v0.11.1, provider-kubernetes v1.4.1, the AWS providers (provider-upjet-aws) v2.9.0, Backstage 1.56. Check again before you rely on a detail: both projects ship often.