Backstage: A Framework You Staff, Not a Product You Buy

Service sprawl is the problem leaders reach for Backstage to solve: dozens or hundreds of services, and nobody can say what runs where or who owns it. The trap is that the tool demos as a quick install, so the budget gets written against the install rather than the thing that keeps it alive. The honest framing is this: Backstage is a framework you staff, not a product you buy, and the real recurring line item is a standing platform team, not the bootstrap command. The decision that follows is whether to run Backstage yourself or adopt a hosted internal developer platform, and how to budget for either path.

If you are still weighing whether you need an internal developer platform at all, the broader category is covered in the internal developer platform guide. With the IDP decision already made, the narrower, sharper question is Backstage specifically: build or buy.

What Backstage Actually Is

Backstage is an open source framework for building developer portals. It originated at Spotify and was donated to the Cloud Native Computing Foundation, where it is a CNCF project. The word that matters in that sentence is “framework.” Backstage is not a finished portal you log into; it is a scaffold you assemble a portal from.

Out of the box it ships four capabilities, each of which is a thing your organization adopts rather than a feature you toggle on.

The Software Catalog is the centerpiece: a centralized system that tracks ownership and metadata for all the software in your ecosystem, from microservices and libraries to data pipelines and machine learning models. Software Templates, driven by the Scaffolder, let teams spin up new projects with your organization’s best practices baked in; this is the golden-paths mechanism. TechDocs is a docs-like-code solution where engineers write Markdown that lives next to the code it describes. The plugin ecosystem is a growing set of open source extensions that connect Backstage to the rest of your tooling. The framing to hold onto is that these are capabilities you operate, not a product that operates them for you.

Why Teams Pull It In

The appeal is real, and it maps directly onto the sprawl problem. Discoverability comes first: when every service, API, and pipeline is registered in one catalog with a named owner, the question “who owns this and where does it run” has an answer. Golden paths come second: templates turn the right way to start a new service into the default way, so standards spread by being easy rather than by being enforced. The single front door comes third: docs, ownership, and pipelines stop being scattered across wikis and dashboards and converge on one place a new engineer can be pointed at on day one.

These are genuine wins, and they are why Backstage became the reference point for the whole category. The mistake is not adopting Backstage; the mistake is mistaking the demo for the deliverable.

The Part Nobody Budgets For

The install genuinely is fast. The getting-started docs walk you through a single command that scaffolds a running application in minutes. That speed is exactly what sets the trap, because the same getting-started page also lists the footprint: a Unix-based operating system, an active Node LTS, and a baseline of at least 20 GB of disk and 6 GB of memory for the standalone app with demo data, increasing as you add plugins. The bootstrap is the cheap part. Everything underneath it is the standing surface a team owns for as long as the portal exists.

A useful way to hold this is a rough 10/90 frame: the install is maybe 10 percent of the work, and the ownership surface is the other 90 percent. That split is a rhetorical frame, not a measured benchmark; treat it as a way of thinking, not a statistic. What it points at is concrete.

Each branch on the right is a recurring obligation, not a setup step.

Surface	One-time install (~10%)	Ongoing ownership (~90%)
Bootstrap	The create-app command scaffolds a running app in minutes.	Done once.
Hosting and infra	Nothing extra to buy on day one.	Self-hosted by default: you run a frontend, a backend, and a database on a baseline that grows as plugins are added.
Auth, SSO and RBAC	Not wired by the scaffold.	Auth providers and the permission framework are configured and maintained by your team.
Catalog hygiene	Empty catalog at start.	Keeping ownership entries accurate is organizational discipline, not a feature that maintains itself.
Plugin upkeep	Default plugins installed.	Backstage ships a new main release every month. It does not follow semantic versioning, and each new minor version can contain breaking changes, so upgrades are a standing chore.
TechDocs pipeline	One demo doc renders.	A documentation build pipeline that someone owns and operates.
Portal on-call	Runs on your laptop.	In production the portal is itself a service with uptime, upgrades, and on-call.

The plugin row deserves emphasis because it is the one most often underestimated. The release cadence is monthly, and the project is explicit that minor versions can carry breaking changes. That is not a once-a-year migration you can plan around; it is a steady upkeep tax on a team that has to keep pace or fall behind.

The clearest statement of the thesis comes from the vendor selling the alternative. Spotify’s own managed offering markets itself with the line “Spend time using your portal instead of maintaining it.” That tagline only makes sense as a pitch if maintaining it is the real cost, and it is.

The Knowledge Layer

Two of the four capabilities are worth pulling out, because they are where Backstage earns its keep as a knowledge system rather than a glorified directory.

The Software Catalog is a single source of truth for who owns what: a centralized system that tracks ownership and metadata for all the software in your ecosystem. Each entity is described by a small descriptor file that lives next to the code, so ownership travels with the service rather than rotting in a separate registry. The value to a leader is not the file format; it is that the catalog answers ownership questions during an incident without a Slack archaeology session, provided the entries are kept honest.

TechDocs is documentation-as-code. Engineers write Markdown that ships in the same pull request as the code, the docs are discoverable directly from a service’s catalog page, and sites build from that Markdown with full-text search. The leadership point is the failure mode it removes: documentation stops rotting in a wiki disconnected from the code it describes, because it now moves at the same speed as the code. Both of these are capabilities you are buying into and then maintaining, not switches that stay flipped on their own.

What Zalando’s Sunrise Proves

Zalando runs one of the most cited Backstage deployments, a developer platform called Sunrise, and it is the clearest worked proof of the thesis. Since 2021, Zalando has built Sunrise on top of Backstage with extensions built internally. The platform is operated by a dedicated team named Builder Portal that has, in their words, “been operating and evolving the platform since its inception.” That sentence is the thesis made flesh: the success condition is a funded, standing team, not a clever install.

The scale numbers double as evidence for the catalog-hygiene point. Zalando reports “over 40k registered entities (between applications, teams, and users) which we sync daily with the respective source of truth services.” The catalog is not kept true by hope; it is kept true by a daily synchronization pipeline against systems of record. On top of the base framework, the team integrated 27 other tools and services through 30 front-end plugins, and contributed some work back to open source, including their Zally API Linter plugin.

Here is the part a leader has to read carefully. Sunrise is heavily customized at Zalando’s scale, and most of what makes it impressive is exactly what a normal organization cannot copy cheaply.

The patterns on the left are portable to a team of any size. The investments on the right are a function of headcount and scale. Copying the customization depth without the staffing behind it is the most expensive mistake an admiring leader can make.

Build vs Buy

The buy side is a genuine market, and the most telling fact about it is that Spotify, the origin of Backstage, sells the managed answer. Spotify Portal for Backstage markets itself as the fastest way to get started, with “No coding required” and an onboarding wizard for no-code setup, and the maintenance-cost tagline already quoted. Alongside it sit hosted internal developer platforms such as Port, Cortex, and OpsLevel that compete on the same promise: you do not run the platform yourself.

The hosted category as a whole trades the same way. You give up deep customization and accept a subscription and some vendor lock-in; in return the vendor absorbs hosting, upgrades, and the upkeep treadmill, and you start in days rather than staffing a team. DIY Backstage gives you full control and the entire open plugin ecosystem; the price is the standing platform team and the monthly non-semver upgrade cadence the table above describes.

For a small-to-medium organization with no standing platform team, the default recommendation is a hosted IDP, not DIY Backstage. DIY wins only in a specific shape, and that shape is the Zalando shape.

The branch to DIY Backstage only resolves when all four conditions hold: an existing funded platform team, budget for a standing team in the Builder Portal mold, customization needs a hosted vendor cannot meet, and scale measured in many teams and thousands of entities. Any single “no” routes back to a hosted IDP. The framework is not “open source is free, so build it.” It is “you already pay for a platform org, so owning the framework buys you control you will actually use.”

Common Pitfalls

The pitfalls in this decision are predictable, and all of them follow from mistaking the install for the program.

The first is budgeting for the install and not the team. The standing platform team is the line item; Zalando’s permanent Builder Portal team is the proof, and the absence of one is the most common reason DIY adoptions quietly stall. The second is treating the catalog as set-and-forget. A stale catalog destroys trust faster than no catalog, because people stop believing the ownership data; Zalando syncs 40k entities daily precisely to keep that from happening. The third is copying Zalando’s 30-plugin customization depth without Zalando’s headcount, which produces an unmaintainable portal and a frustrated team. The fourth is underestimating the monthly, non-semver release cadence, where minor versions can carry breaking changes, and budgeting upgrades as an annual event. The fifth is assuming open source means free: the license is free, and the standing team is the cost.

When This Holds and When to Override

For most small-to-medium organizations without a funded platform team, a hosted internal developer platform is the right default. It removes the very cost that sinks DIY adoptions: the standing team that owns hosting, auth, catalog hygiene, the upgrade treadmill, and on-call. DIY Backstage is the right answer in one specific case: you already run a funded platform org, you can staff a permanent team in the Builder Portal mold, you need customization a hosted vendor cannot match, and your scale is measured in many teams and thousands of entities. Outside that shape, the install is the easy 10 percent and the team you did not budget for is the 90 percent that decides whether the program survives.

The single next step is to cost the team before the tool. If you cannot name who owns the portal on-call rotation a year from now, you are not yet ready to run Backstage yourself.

References

• What is Backstage? - Official overview defining Backstage as a framework for building developer portals and its four out-of-the-box capabilities.
• Backstage Software Catalog - The ownership and metadata source of truth, including the descriptor model for entities.
• Backstage TechDocs - Docs-like-code: Markdown alongside the code, catalog-integrated discovery, and full-text search.
• Backstage Software Templates - The Scaffolder and golden-paths mechanism for standardizing new projects.
• Backstage Release and Versioning Policy - The monthly cadence and the statement that minor versions can contain breaking changes.
• Backstage Getting Started - The create-app command and the baseline disk and memory footprint that grows with plugins.
• CNCF: Backstage project - Project status and maturity as a CNCF project donated by Spotify.
• Sunrise: Zalando’s Developer Platform Based on Backstage - The worked case study: 40k entities synced daily, the Builder Portal team, and 27 tools across 30 plugins.
• Sunrise: Zalando’s Internal Developer Platform (talk) - Companion conference talk and recording on the same platform.
• Spotify Portal for Backstage - The commercial managed Backstage offering, source of the “spend time using your portal instead of maintaining it” tagline.
• Port - A hosted, commercial internal developer platform on the buy side of the decision.
• Cortex - A commercial internal developer platform competing on managed, no-maintenance operation.
• OpsLevel - A commercial internal developer platform in the hosted IDP category.