Why Backstage Is a Framework and Not a Product
In one line
Backstage is the developer portal Spotify used internally, released as open source in 2020 and donated to the CNCF (promoted to incubating in 2022). And it is not a product you install and use right away, but a framework for building your own portal. If you adopt it without understanding this difference, you will fail.
Why this was needed
If you ask an organization of any real size the following questions, there is usually no answer.
- How many services does our company have?
- Who owns this service? Whom do we wake up at 3 a.m.?
- Who is using this API? What breaks if we remove it now?
- What should a new developer read to make a first deployment?
The reason there is no answer is not that the information is missing, but that it is scattered. The owner is in the wiki, deployment is in the CI dashboard, dependencies are in someone's head, and the documentation is in a Confluence from three years ago. Each piece is up to date, but put together they form no picture at all.
Backstage's answer is this. Build a software catalog, and have that catalog filled automatically from code repositories. If ownership information lives next to the code (catalog-info.yaml), it moves with the code when the code moves, it goes through review, and the chance that it stays stale drops sharply.
How it works
The three pillars
There are three things you need to know when you first look at Backstage.
- Software Catalog — a list of everything we own and the relations between them. It is the heart of Backstage.
- Software Templates (the scaffolder) — a mechanism that creates new services along the golden path.
- TechDocs — a feature that renders Markdown documents living next to the code and shows them in the portal.
A plugin ecosystem is attached to this. It pulls information from tools such as Kubernetes, CI, on-call, cost, and security scanners into the entity page. This is the core value of the portal — not merging the tools into one, but gathering and showing information centered on the entity (the service).
Frontend plugins and backend plugins
Backstage is split into two apps.
| Frontend | Backend | |
|---|---|---|
| What it is | A React application | A Node.js service |
| What plugins do | Provide pages, tabs, cards, and icons | API endpoints, data collection, authentication to external systems |
| Example | The "Kubernetes" tab on an entity page | A service that queries a cluster and fetches workloads |
| Why the split | Credentials must not sit in the browser | Tokens and Secrets stay on the server only |
This separation matters for security. If a frontend plugin called the Kubernetes API directly, the user's browser would need cluster credentials. So a backend plugin makes the call on its behalf, and the frontend calls only the backend's endpoints.
Why it is not a product
To use Backstage, you create an app source tree that you own with npx @backstage/create-app. From then on, it is your code. To add a plugin, you change the code, build it, and deploy it. Upgrades are your job too.
The pros and cons of this choice are clear.
- The good — you can change anything to fit your organization. You can build and attach internal-only plugins, and define the information structure in your organization's own language.
- The bad — you need someone to maintain it. A team that can work with TypeScript/React must be attached permanently, and the upgrade burden keeps coming.
That is why, on the CBA exam, if a question like "Does installing Backstage give you a portal you can use right away?" appears, the answer is no. The adoption decision is not a technology choice but a staffing decision. If there is no team to treat this framework like a product, in six months you get one more neglected portal that nobody upgrades.
What it looks like in the field
Even the author's 7-node homelab shows why a catalog is needed. One cluster runs Cilium (CNI), MetalLB (L4 LB), Cilium Gateway API (L7), csi-driver-nfs (storage), GPU Operator (4 GPUs), KubeVirt+CDI (virtualization), CloudNativePG (DB), kube-prometheus-stack (observability), Gitea (10.0.0.200), Argo CD (10.0.0.201), Harbor (10.0.0.202), and Grafana (10.0.0.203). Each one has a backstory — Gateway API needed CRD v1.6.1, and KubeVirt had a defect in the containerDisk path and needed a DataVolume workaround.
Even in a homelab run by a single person, if you do not remember this list and its backstories, you get lost half a year later. Needless to say, the same is true for an organization. Keeping "what exists, why it was configured that way, and who knows" out of people's heads — that is the reason a catalog exists.
And this cluster's recurring lesson, "the state Ready and actually working are different claims," applies to portal design as well. It is easy to put up many green badges on an entity page. The hard part is whether those badges are connected to the real user experience. A portal is a tool for gathering information, and gathering it does not make that information true.
What to check in the next quiz
This module ends with a quiz. In the next module you learn the entity kinds and relations of the catalog, and write a real set of catalog-info.yaml files in /root/cba-catalog/. Backstage itself is not in the lab environment, so you work with writing entity files and expressing their ownership information as cluster labels.