Backstage as a self-service portal: giving your teams the LLM platform without giving them the cluster

· By José Manuel Román
Contents

This article opens the platform and self-service layer: the one that decides how you hand everything underneath to the teams that are going to use it. The three articles in this batch are Backstage (the portal), Kubeflow (the ML toolbox) and Knative (switching the GPU off when nobody is using it).

TL;DR

Backstage solves a real problem of a platform that has grown: nobody knows what is there, who maintains it, or how to ask for a new one without opening a ticket. Its answer is three pieces, a software catalogue that models every component and its relations, templates that create new resources through a form instead of through copy and paste, and TechDocs to keep documentation next to the code. On top of those three sits the concept that holds up everything else, the golden path: the supported route made also the easiest one, so that people take it because it is paved, not because they are forced onto it.

The price is high and it should be said plainly. Backstage is not a product you install, it is a Node and React application that you compile and maintain as your own code, at a declared cost of two to three full-time engineers, and with upgrades as its biggest pain point. As of August 2026 it is still a CNCF incubating project, not graduated, and it has no native entity type for models, datasets or inference endpoints: that gets modelled by hand, or you wait for a proposal that is still open. The decision is not about features, it is about scale: below a certain organisation size, a portal costs more than it saves.

The analogy: the industrial estate directory

A single unit needs no sign. You know what is inside because you built it. An estate with two hundred units, on the other hand, needs a directory at the entrance: which company sits on each plot, what it does, who is responsible, and an office where you can request a new plot with the utility connections already in place instead of negotiating each one separately.

An LLM platform starts out as a single unit. One cluster, one model, the team that built it. Six months later it is an industrial estate: fifteen models served, three RAG pipelines, LoRA adapters everywhere, and a question that comes back in every meeting, who maintains this? Backstage is the directory for that estate, with two additions an ordinary directory does not have: the office that hands over turnkey plots, and the archive of blueprints for each unit. The catalogue is the directory, the templates are the office, TechDocs is the archive.

The analogy also warns about the cost. The directory does not maintain itself. Somebody has to update it when a company moves, and a directory with half the plots mislabelled is worse than no directory at all, because people stop trusting it. In Backstage that failure has a name, catalog rot, and it is the leading cause of a portal being abandoned.

What Backstage is and what state it reaches 2026 in

Backstage was born inside Spotify and donated to the CNCF, which accepted it in September 2020 and moved it to incubating level in March 2022. That is where it still is: as of August 2026 it is incubating, not graduated, a detail that matters when someone sells it as a de facto standard. It is by far the most widely adopted developer portal (the official 2025 review declares more than 3,400 organisations using it, 31,000 GitHub stars and more than 250 plugins), but adoption is not governance maturity, and a large share of those plugins is maintained by the community, not by the core.

The architecture has kept changing pieces under the feet of whoever operates it. The New Backend System stabilised in 2024 and is now the standard. The New Frontend System became the default mode for new applications in version 1.49, of March 2026. The cadence is one minor release a month, and that rhythm is precisely the origin of the biggest operational problem, which we will see further down.

The three pieces

The software catalogue

The heart of Backstage is an entity catalogue. Every piece of the platform is described in a catalog-info.yaml file that lives next to its code, and Backstage discovers it by crawling the repository. The entity types are fixed: Component (something that runs or compiles), API (a contract that a component exposes), Resource (infrastructure that a component needs), System (a set of components that form a unit), Domain (a set of systems), plus Group and User for ownership.

The power is in the relations rather than in the entities, which Backstage computes and navigates: ownedBy connects each thing to its team, providesApi and consumesApi draw who depends on whom, partOf groups components into systems, dependsOn traces the dependency graph. With that, the meeting question (who maintains this, and what breaks if we touch it?) stops being answered from memory and starts being answered by query.

There is a design decision that conditions everything that follows: Backstage advises against creating new entity types. Plugins are compiled expecting the usual types, and an invented type leaves them blind. The supported route is to reuse an existing type and distinguish it with the spec.type field (for example a Resource with type: llm-model), adding whatever custom fields you need to the spec.

The templates

The second piece is the Scaffolder, the template engine. A template is an entity of type Template with three parts: the parameters requested through a form, the steps that get executed, and the actions that do the real work (create a repository, write the catalog-info.yaml, register the component, trigger the GitOps pipeline). The developer goes to /create, picks a template, fills in the form, and in a single operation has the resource created, catalogued and deploying.

This is what turns a directory into an office. Without templates, Backstage only lists what already exists. With templates, it is the door through which new things are created, and that door is where the golden path materialises.

TechDocs

The third piece is TechDocs, documentation as code. Documents are written in Markdown next to the code, generated with MkDocs in the CI pipeline, and served inside the portal itself, linked from each component’s page. The advantage is in the incentives: documentation that lives far from the code rots; documentation that lives next to it and gets reviewed in the same pull request has some chance of staying true.

The golden path, which is what all of this is about

Spotify coined the term golden path for the recommended and supported way to build something. It has two halves: the blessed tooling, visible in the portal, and a step-by-step tutorial in the documentation. The idea, in the formulation that platform reports keep repeating, is that nobody forces you to use the paved road; people take it because it is paved.

The data supports the golden path being the deciding variable. The 2026 State of Platform Engineering report, covering 518 professionals, puts voluntary adoption above 80 % where there is a well-designed golden path and below 20 % where there is not, and estimates that around 70 % of platform initiatives fail to reach significant adoption without one. It is a figure that reorders priorities: a portal without golden paths is a pretty catalogue nobody uses.

In Backstage, a golden path is implemented as a Scaffolder template. For an LLM platform, a typical golden path would be “serve a new model”: the form asks for the model, the GPU size, the owning team and the SLO; the template creates the repository with the InferenceService, writes the catalog-info.yaml, registers it under the right system, and opens the pull request against the GitOps repository you already have with Flux. What used to be half a day of copying a colleague’s YAML and guessing the values becomes a two-minute form with the correct defaults.

Authentication and permissions

For a sovereign platform the identity piece matters as much as the catalogue. Backstage ships connectors out of the box for GitHub, GitLab, Google, Microsoft, Okta, generic OIDC and SAML, among others. For on-premise the relevant one is Keycloak, which fits in like any other OIDC provider, with one nuance worth keeping in mind: the Keycloak connector is maintained by the community, not by the core, so its maintenance and its tightness fall on a third-party plugin. Once you have set up Keycloak as we saw in the article on authenticating MCP, the portal hooks into the same identity issuer.

The permissions framework appears today as stable in the documentation and supports RBAC, ABAC and custom logic. The small print: by default the endpoints are not protected, and the permission policy is written by the integrator. The most widely used RBAC solution with a graphical interface comes with the Red Hat distribution, not with the core. In other words, serious access control means work on top of what comes in the box.

The real cost, no frills

This is where an honest article parts ways with the brochure. Backstage is not an installable product, it is a framework that you compile and maintain as your own code. That has measurable consequences.

The most quoted analysis, from the managed Backstage vendor Roadie, puts the effort at around three full-time engineers in the first year and two from the second onwards, with a time to production of six to twelve months in self-managed mode. The figure comes from a vendor with a commercial interest in you buying its managed version, so it should be taken as an order of magnitude and not as a neutral data point, but the direction is confirmed by independent sources: ongoing maintenance takes up around a fifth of engineering time, and upgrades are the biggest pain point, cited by more than half of those who adopt it. With one minor release a month and architectural pieces shifting under your feet, keeping up to date is a permanent job.

The other cost is about adoption, not engineering. A widely repeated critical analysis points out that many organisations settle at around 10 % internal usage, against the 99 % voluntary usage Spotify achieved at home, and attributes it to three recurring failures: the catalog rot we already mentioned, the lack of a product owner treating the portal as a product, and the illusion that Backstage can be adopted over what already exists when in practice it only standardises new things well. The sentence that sums up the disenchantment is that Backstage is a free portal in the same way you would have a free car if somebody tipped all the parts of a Chevrolet onto your desk.

Applied to an LLM platform: what is there and what is not

Here an expectation needs correcting. In 2026 Backstage has no native entities for models, datasets or inference endpoints. There are three things and none of them is what you would hope for:

An open proposal (RFC 33060, from February 2026) to model model servers as entities of type API with type: ai-model-server. It is under discussion, not implemented.

An official module that introduces an AiResource type, which sounds like what we are after but is for something else: governing the skills and rules of coding assistants, not registering inference models.

And one real pattern, the MLOps templates that AWS documents on top of SageMaker, where Backstage acts as the Scaffolder that creates environments and pipelines, not as the model registry. It is a cloud case, not on-premise, and it uses Backstage for its template half, not for its model catalogue.

The practical conclusion for your own stack is twofold. First, what Backstage brings to an LLM platform today is above all the template half: the “create a new inference service” golden path wired into your GitOps. Second, if you want to catalogue models, today that is done by hand with custom spec.type values, treating the model as a Resource and its endpoint as an API, until the proposal matures. Registering the model’s bytes remains the job of the OCI registry, not of the catalogue.

The infrastructure plugins that are worth it in this stack do exist and are reasonably alive: the Kubernetes one (core), the Flux one for seeing GitOps state from the portal, the Grafana one for embedding dashboards in a component’s page, and the ArgoCD one for anyone using Argo instead of Flux.

Alternatives: when not to set up Backstage

The honest decision is not which portal, but whether a portal. The SaaS-type alternatives (Port, Cortex, OpsLevel, Humanitec) win on time to first value, measured in days instead of months, and on not having to maintain the framework, in exchange for a per-user fee that scales badly and for giving up pure on-premise. Roadie offers managed Backstage, which removes the framework maintenance while keeping its extensibility, in exchange for a per-developer fee and for taking your catalogue outside.

For a sovereign platform, where on-premise and data ownership are requirements, pure SaaS is usually ruled out by design, which leaves the real choice between self-managed Backstage and no portal at all. And there the criterion is size. Below a handful of teams, a well-maintained README and a tidy GitOps repository do the same job as the catalogue, without the cost of two engineers. The portal starts paying off when the cognitive load of knowing what is there and how to ask for it exceeds the cost of maintaining the tool that answers it.

Operational traps and honest scepticism

The catalogue rots if it is not automated. A catalog-info.yaml written by hand and never updated is lying within a few weeks. The only defence is generating and validating those files in the pipeline, not trusting people to maintain them.

Without a product owner, the portal dies. Backstage is not infrastructure you install and forget, it is an internal product with users you have to understand. Without somebody treating adoption as an objective, it ends up as a catalogue nobody looks at.

Upgrades are a recurring tax. One release a month and architectural pieces mid-migration mean the portal is never finished. That maintenance has to be budgeted from the start, not discovered in the second quarter.

Backstage deploys nothing. It is a portal, not an engine. Behind each template there has to be your GitOps, your operators and your cluster doing the real work. If that base is not solid, the portal just puts a pretty façade over chaos.

The data model for AI does not exist yet. Anyone setting up Backstage expecting a ready-to-use model catalogue is going to find themselves modelling by hand. It is doable, but it is work, and you should know that beforehand.

For an inference factory

Backstage fits at the high maturity level of a platform, not at the start. In the five maturity levels it is a tool of the level where the platform already serves several teams and the bottleneck has stopped being technical and become one of coordination. Three concrete decisions follow from all of the above.

The first is not setting it up too early. If the platform is used by two teams who know each other, the portal is cost without return. The trigger is cognitive load, not the calendar.

The second is starting with the templates, not with the catalogue. The value you notice from day one is the golden path that turns half a day of copying YAML into a two-minute form. The complete catalogue, with all its relations, is a bigger job that can come later.

The third is budgeting maintenance as a function, not as a project. Two part-time engineers indefinitely, an owner watching adoption, and automatic generation of the catalogue entries. Without that, the portal degrades until somebody asks why nobody uses it, and the answer is that it stopped being true.

The portal is the face your platform shows to whoever uses it. It is worth it when there is enough platform behind it that showing it tidily saves more than maintaining the shop window costs. Before that, it is the shop window of a shop that has no stock yet. The other two articles in this batch go into that stock: the ML toolbox with Kubeflow and the savings of switching the GPU off with Knative.

See also

Sources