Why a platform still needs a service catalog

Is the service catalog still a thing?

A lot of teams stood up a developer portal a few years ago, filled it with hand-written YAML, and watched it go stale within a year. Now there's a newer doubt on top of that one: if an AI agent can read the code, write the Terraform and open the pull request, why does anyone need a catalog at all? Can't you just ask?

I think the service catalog matters more now than it did five years ago, but for a different reason. It used to be a nicer way for people to find things. Now it's the API that everyone, people and agents alike, uses to change things. That's why Airframe sits at the centre of Hangar, and why I built it before almost anything else.

Two ways of building software, at the same time

Here's how I see where platform engineering is heading. We're going to be supporting the human software lifecycle for a long time yet: people writing code, reviewing it, merging it, getting paged at 3am. That isn't going away, and a platform that forgets it will lose the developers it's meant to serve. At the same time, AI is arriving at every level at once. It writes code beside us, reviews pull requests, diagnoses a failed rollout, and increasingly runs as a workload of its own that needs a database and a secret like any other service.

So the platform has to serve both, through the same front door. I think of it as an IDP that can speak AI, in a manner of speaking. That's why Hangar includes Autopilot, and it's why the service catalog has become the most important piece of the design: it's where we decide what the platform actually offers, in a form that both a person and a machine can read.

"Service catalog" means two things

Part of the confusion is that we use one phrase for two different ideas. The first is an inventory: everything that's running, who owns it, where its docs are, and what it depends on. That's what most people picture when they hear "Backstage". The second is a menu: the things you're allowed to ask the platform for, what you'll get back, and how you'll know it worked.

Both matter. An agent about to change a service needs to know who owns it, and it needs to know what it can ask for. So does a new hire in their first week. But the inventory is the one that goes stale, because somebody has to keep it up to date by hand, and nobody's job is to do that. The trick I've come to believe in is to generate the inventory from the menu. In Hangar, Backstage's entities and its scaffolder templates are both generated from Airframe's live XRDs and the resources they create. Nobody types them in, so they can't drift from what's actually there.

The catalog is the API

Once you see the menu as the thing that matters, a service catalog stops being a portal feature and becomes the platform's API. In Hangar, that's literal. Airframe has fifteen APIs, from app stacks and environments to PostgreSQL, Redis, RabbitMQ and a secret store, and there's exactly one way to use them: a git commit. Backstage can't write to a cluster at all; its templates open pull requests. Glidepath's pipelines commit. And when Autopilot's runtime is built, an agent will go through the same door too, with narrower authority and every action on the record.

That's the part I care about most. If people, pipelines and agents each had their own way in, I'd have three platforms to keep honest: three places to enforce policy, three audit trails, three sets of names for the same database. With one API, a new kind of caller, including ones we haven't thought of yet, gets all of that for free.

A list isn't enough. It needs a contract

Here's where I'd push back on a lot of catalogs I've seen, including early versions of my own. A name and a form is a wish list. What turns it into an API is the contract: what you can ask for, what you get back, how you'll know it's working, and who's allowed to change it.

I learned this the hard way. When I first measured how ready Airframe was for an agent, 22 of the 25 live environment entries had a hand-typed name for something the platform had created, like a Secret or a Service. Every one of those was a guess that happened to be right. A person can live with that. An agent will copy the guess, confidently, into the next app. So components now declare their outputs by name, a closed list of reasons for their health, and the checks that say what "working" means. Five do so far, and the live environment files are still catching up: 33 of 45 entries hard-code a name today, which is exactly why the scorecard counts them. The contract is generated from those sources into one bundle, CI fails if it drifts, and there's an llms.txt at the root of the repo so an agent knows where to start.

The payoff is that an agent can plan. Autopilot has a small planner that takes one sentence, which I call the parachute sentence, "provision a new Python application named parachute, with a dev and test environment and a canary step", and turns it into an ordered set of changes that's checked against the real XRD schemas and a real helm template before anything is committed. That only works because the catalog says exactly what's allowed. Without it, the agent would be guessing, and so would everyone reviewing its pull request.

Agents don't make the catalog obsolete. They make a vague one dangerous.

Is this where the industry is going?

I think so, mostly. The ideas Hangar leans on aren't mine alone. Treating the platform as a product, offering APIs instead of tickets, building on a Kubernetes-style control plane that people can extend, and giving agents a small, typed set of tools rather than a shell are all where the thoughtful platform teams I follow are heading. Crossplane's move towards intelligent control planes, and the way MCP has become the ordinary way for an agent to discover tools, both point the same way: the platform as a well-described API that people and machines share.

Where I'd be more careful is the portal-first version of this. Buying a portal and hoping a catalog grows inside it is how a lot of teams ended up with a very pretty, very stale inventory. The API has to come first, and the portal is one of its readers.

And I'll be honest about where Hangar falls short. The scorecard grades the API: its schemas, its contracts, how safely it can be written to. It doesn't yet measure the thing that matters most, which is whether developers are better off. How long does a new service take to reach production? Which APIs do teams actually use? "Platform as a product" is the first of my principles, and a product without usage numbers is mostly an opinion. That's the next thing I want to add.

Build or buy, now that AI writes code

AI has made writing code much cheaper, but the build-or-buy answer has changed less than you'd expect. I build with AI tools beside me every day now, and a lot of Hangar's typing wasn't mine. But it hasn't made owning code any cheaper. Someone still upgrades it, gets paged for it and explains it to the next person. When you can generate a whole reconciler in an afternoon, the temptation is to build everything yourself because it feels free.

It's a trap! Here's how I split it instead:

Even adopting has a cost. I run my own fork of the GitHub provider because the release I was on read a rate-limit error as "this file was deleted" and recreated it. I wrote about that in Building Airframe. Open source didn't mean free; it meant I could fix it. AI collaborators make that kind of fix much faster, which is a real reason to choose open engines you can read over closed ones you can't. They don't change what's worth owning.

How I'd build one, if you handed me the job

Say I joined a platform team tomorrow and was asked to build the company's service catalog. I wouldn't start with Crossplane, or Backstage, or a schema. I'd start with the people who are going to use it.

Discovery comes first. Developers are the customer, and they already know what hurts. I'd spend the first few weeks interviewing them, fifteen or twenty across different teams and seniorities, shadowing a couple of real onboardings end to end, and taking an honest inventory of what's already running. Nobody asks for an XRD. They say "it took three weeks to get a database" or "I copy the last repo and hope". Each of those is a job the platform could do for them, and the job is what you design around.

Then I'd turn what I heard into nouns. A good API is a noun a developer already uses: a database, an application, a secret store. If you have to explain the name, it isn't one yet. I'd draft three to five of them, no more, and take the draft schemas back to the people who asked. "Would this have saved you the three weeks?" is the cheapest design review you'll ever run. Just as important is writing down what we won't build yet, so nobody's waiting on it.

Then one slice, for one team. Take the most painful journey and make it self-service end to end with a pilot team, with git as the only way in from day one. One API that one team loves beats fifteen that nobody asked for. Airframe has fifteen because Hangar is my lab and I'm its only customer; at a company I'd grow into that number, not start there.

Then make it readable. Before anything else can build on the API, give it outputs, honest conditions and generated portal pages, and let CI catch drift. This is the step most teams skip, and it's the one agents depend on.

Then open it to agents. Same API, narrower authority. Expose the contract as tools, keep every write a pull request, and audit everything. I put this after readability on purpose. An agent working against a vague API just makes mistakes faster.

And measure the whole time. Take a baseline during discovery, then track time to first deploy and how much each API is actually used. Retire what nobody calls. And keep going back to discovery, because the first catalog you ship is really a draft of the second one.

Why Airframe

Airframe is my version of all this, built in a home lab rather than a company, so the interviews were mostly with myself and the apps I wanted to run. It's the part of Hangar that defines what a compliant service is, once, for everyone who asks. Glidepath builds and ships what it describes, Tower and Backstage show it, and Autopilot will let agents use it within limits I can explain.

If I had to keep just one piece of Hangar, it would be this one. Portals come and go, pipelines get rewritten, and the tools agents use will look different next year. What the platform promises, written down precisely enough that a person and a machine read it the same way, is the part that lasts.

James

← All architecture essays