Why Every Platform Engineer Should Know About Backstage
A platform is only as good as the window developers see it through. Ours is Backstage: one catalog, one search, one place where every service, its docs, its running state, and its infrastructure spec all live.
An internal platform can be excellent and still feel like chaos to the people using it, because the value is spread across a dozen tools nobody can find. The catalog is in one place, the docs in another, the dashboards in a third, and ownership is a guess. Backstage is the fix I reach for. It is an open framework, built at Spotify and now a CNCF project, for putting a single developer portal over all of it.
The problem a portal solves
Ask a developer at a growing company a few simple questions. Who owns this service? Where are its docs? What APIs does it expose, and what is it running right now? At any real scale, answering that means opening five tools and asking two people. The information exists; it is just scattered, and scattered information may as well not exist.
Backstage collapses that into one portal. Underneath it is a software catalog: a typed, searchable model of everything you own, with ownership and relationships built in. Everything else, the docs, the templates, the cluster view, hangs off that catalog. It is open source, it has graduated to a CNCF incubating project, and the plugin ecosystem around it is the real superpower.
The four features that do the work
Four features carry most of the weight, and they map cleanly onto those questions: what exists and who owns it, how you make more of it, where the docs are, and what is actually running. Click through them.
The pieces that turn a pile of tools into one portal. Click one to see it, and how I use it.
A central registry of everything you own, tracked by a catalog-info.yaml in each repo. Entities are typed: Component, API, Resource, System and Domain, plus Group and User for ownership, all linked by their relationships and dependencies.
- Every microservice, shared library, and data pipeline is a catalog entity, with its owner, lifecycle, and dependencies.
- I register the Crossplane compositions themselves as entities, so a developer can open the application or database composition and read its spec from the portal.
- OpenAPI specs are API entities, linked to the components that expose and consume them.
How I run it as our single pane
On our platform, Backstage is the single pane of glass, and I lean on it hard. Everything a developer needs to understand a piece of software lives on its catalog page:
- Every microservice, shared library, and data pipeline, with its owner, lifecycle, and dependency graph.
- The docs: how a service is deployed, its cURLs and runbooks, its OpenAPI spec, its ML-model cards, and its access metadata, all docs-like-code so they ship with the repo.
- The Crossplane compositions, registered as catalog entities, so a developer can open the application or database composition and read its spec without leaving the portal.
- The live Kubernetes state of a service, wired through the Kubernetes plugin, sitting right next to its definition.
- Our observability and infrastructure tooling, pulled in through Backstage's rich plugin catalog, so the dashboards live where the service does.
- Software templates that scaffold a brand-new microservice, with its starter config and paved-road defaults, in a couple of clicks.
Why every platform engineer should know it
Here is my actual argument. Platform engineering spends most of its effort on the machinery, the compositions, the pipelines, the guardrails, and almost none on the window people look through to use it. That is backwards. A paved road nobody can see gets ignored, and the tools you built get worked around.
Backstage is the UI layer of the whole discipline: the place where all that machinery becomes legible to the people it is for. It will not build your platform for you, but it will make the platform you built usable, discoverable, and owned, with an open plugin model that meets your infrastructure wherever it already is. If you do platform engineering and you have not looked hard at Backstage, that is the gap I would close first.