OnCallReadyStart learning

Infrastructure as code Lesson 42.1 · Platform Engineering: Backstage & Crossplane · 11 min read

Platform engineering: what an internal developer platform is

In plain words

A restaurant kitchen works because the cooks do not each grow vegetables and fix the oven. A supply team brings the ingredients, the oven is maintained by someone else, and a recipe card says how the house dish is made. An internal developer platform is that supply team for software: product teams cook, the platform team makes sure the ingredients, tools and recipes are ready, and the recipe card is the golden path.

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 typeWhat it does
Stream-alignedOwns a flow of change for a business area (orders, payments). Most teams.
PlatformProvides internal services that stream-aligned teams use on their own.
EnablingSpecialists who help other teams learn a skill, then step back.
Complicated-subsystemOwns a part that needs deep expertise (a pricing engine, a video codec).
Interaction modeMeaning
CollaborationTwo teams work closely for a while to discover something new.
X-as-a-ServiceOne team consumes what another provides, with minimal talking.
FacilitatingOne 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.

Why it helps

Every company that grows past a few teams hits the same wall: each team re-learns how to get a database, a pipeline and monitoring, and gets it slightly wrong. Knowing the vocabulary (cognitive load, stream-aligned and platform teams, X-as-a-Service, golden paths, platform as a product) lets you discuss the problem in design reviews and interviews, and explains why the tools later in the chapter exist at all.

FAQ

What is cognitive load in this context?

The amount a team has to keep in its head to do its job: the business domain plus every tool, convention and system it must understand. Team Topologies treats it as the design constraint for teams, because a team that has to know too much ships slowly and makes more mistakes.

What are the four team types?

Stream-aligned teams own a flow of change for a business area; platform teams provide internal services others use on their own; enabling teams help others learn a skill and step back; complicated-subsystem teams own a part that needs deep expertise. Most teams in a company are stream-aligned.

What does X-as-a-Service mean?

One team consumes what another provides with minimal talking: a product team gets a database by filling in a form or writing a few lines of YAML, not by opening a ticket and waiting. It is the normal interaction mode for a platform team, with collaboration reserved for building something new.

What is the Thinnest Viable Platform?

The smallest platform that removes real load. Sometimes that is a wiki page with a good template rather than a new system. The warning behind the phrase is that a platform which tries to do everything becomes a second bureaucracy that teams work around.

How do you know a platform is working?

Measure adoption and outcomes: how many new services came from the template, how long it takes from "I need a database" to a working connection, how many tickets the platform team still gets, and whether the DORA metrics of teams on the golden path improve compared with teams off it.

In an interview Mid

What is an internal developer platform and why would a company build one?

An IDP is a self-service layer a platform team runs as a product for stream-aligned teams. It usually combines a portal such as Backstage, platform APIs that turn requests into infrastructure such as Crossplane Compositions, and golden paths: supported, optional, opinionated ways to do common things. Companies build one to reduce cognitive load, so teams ship faster and the company's decisions on security, backups and ownership are applied once instead of by every team.

Also asked: What are the team types in Team Topologies? · What makes a golden path different from a mandatory process? · Which metrics show whether a platform helps?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.