The Missing Book in Platform Engineering: The Service Catalog

Most teams treat it as a directory. The ones who get value from it treat it as the constitution of their engineering organisation.

Every mature engineering organisation I have worked with eventually arrives at the same realisation. Their CI/CD pipelines work. Their observability stack is in place. Their cloud bill is monitored. And yet, when an incident hits at 2am, the same question gets asked in the same Slack channel: who owns this service?

This is the gap most platform engineering programmes underestimate. Not the tooling. Not the pipelines. The book that records what exists, who owns it, and what standards it must meet. The service catalog.

I call it the missing book because most teams treat it as optional. A wiki entry. A spreadsheet maintained by a senior engineer who keeps it accurate out of personal discipline. Until that engineer leaves, and a year later nobody can answer basic questions: which services are in production, what they depend on, who is on-call, whether they meet security standards.

Gartner now projects that by 2028, 85% of organisations with platform engineering teams will provide internal developer portals, up from 60% in 2025. That growth is not really about portals. It is about the catalog at the centre of them. The catalog is where ownership, standards, security signals, and increasingly AI agents converge into a single source of truth about what the engineering organisation actually has.

This is what most platform teams miss. The catalog is not a directory. It is the constitution.

Service Catalog for Engineering

What a service catalog actually is

Before going further, it is worth pinning down what a service catalog is, because the term has been overloaded for two decades.

The original definition came from ITIL — the Information Technology Infrastructure Library, born inside the UK Office of Government Commerce in the 1980s. The IT service catalog was formally introduced in 2007 as an ITSM best practice in ITIL v3, defined as a database or structured document listing all the IT services an organisation provides, with descriptions, owners, costs, and SLAs.

That definition was built for IT operations. The primary user was the business consumer asking IT for a laptop, a VPN account, a database. The catalog was the menu, and IT fulfilled the request. ServiceNow built an empire on this model.

It started breaking down when engineering teams went distributed, services became microservices, and ownership shifted from a central operations function to dozens of autonomous product teams. The old catalog answered “what can I request from IT?” The new question was: what services do we run, who owns them, and are they meeting our standards?

The platform engineering service catalog is the answer to that newer question. It inherits the ITIL primitives — entities, ownership, metadata, relationships — but pivots the audience. The user is the engineer building and operating software. The unit is the deployable service, defined declaratively in code. The catalog’s job is no longer to be a menu. It is to be the system of record that the engineering organisation runs on.

Where the platform engineering catalog came from

The platform engineering service catalog did not come from a vendor. It came from a problem Spotify hit when they grew past a few hundred engineers and could no longer answer simple questions about their own infrastructure.

The Spotify story is worth knowing because it explains what the catalog is for. As they grew, infrastructure became fragmented and engineers spent more time looking for information than writing code. Where is the API for that service? What version of the framework is everyone on? Who owns this thing that is failing? These are the questions platform engineers everywhere will recognise.

Spotify started simple, with a services catalog. Then they added TechDocs and Software Templates. By 2018 they had Backstage internally. They open-sourced it in March 2020 and donated it to the CNCF.

Backstage Software Catalog — the open-source reference implementation from Spotify. Source: backstage.io/demos

The point worth highlighting: the catalog came first. The portal came after. The portal is a delivery mechanism. The catalog is the substance. Every internal developer portal that has emerged since, commercial or open source, is a different opinion on how to render and govern the same underlying object.

This is where a lot of platform engineering programmes go wrong. They buy a portal before deciding what they want their catalog to be a record of.

Isn’t this just a CMDB?

A fair question follows. ITIL also gave the world the CMDB — Configuration Management Database — a central repository of configuration items, ownership, and relationships, sitting at the heart of every ServiceNow implementation. If both came out of ITIL, why is the platform engineering service catalog a different thing and not a rebrand?

They solve adjacent problems for different audiences. The CMDB was built for IT Service Management. Its user is the IT operations team running change management, incident management, and audit. Its unit is the configuration item — physical server, software license, anything tracked. Its value is impact analysis when something breaks or a regulator asks for evidence.

The platform engineering service catalog inherits the ITIL primitives but pivots the audience. Its user is the engineering team. Its unit is the deployable service, defined declaratively in code, owned by a named team. Its value is making engineering standards self-enforcing.

The mechanics overlap. The cultures do not. CMDBs are notoriously hard to keep accurate — industry analysis suggests 80% of CMDB projects fail, often because the data goes stale within a quarter. The reason is structural. The CMDB sits in IT, but the data it tracks is generated in engineering. The feedback loop is broken by design.

The service catalog flips that. The data is generated in engineering, owned in engineering, consumed in engineering. CI/CD pipelines read from it. Incident routing reads from it. Security scans write to it. The catalog stays accurate because the engineering organisation cannot function without it being accurate.

A CMDB is a record of what IT has. A service catalog is a contract for what engineering ships. One is descriptive. The other is prescriptive.

How the major platforms treat the catalog differently

Once you start looking at how the leading implementations are designed, each one expresses a different theory of what the catalog is for.

Backstage treats the catalog as a framework. You define your entity model in YAML, write your own plugins, run your own infrastructure. The flexibility is real, and so is the cost. Backstage runs around $150K per 20 developers in hidden engineering time, versus $93K–$187K annually for commercial platforms for a 200-person team. The VP of Engineering at Spotify has noted that while internal adoption is high, it often stalls below 10% in other organisations. Backstage works best when you have a dedicated platform team that wants to build, not buy.

Datadog treats the catalog as a view onto telemetry. The Software Catalog visualises how services, queues, and data stores fit together, maps dependencies, and detects real-time traffic. The catalog is populated from observability data rather than authored declaratively. The trade-off is honest: you get a catalog that is always live, but you only see what is instrumented.

Datadog Software Catalog — telemetry-driven view of services with scorecards, on-call ownership, and dependency mapping. Source: Datadog

Cortex, Port, and OpsLevel treat the catalog as a governance surface. Cortex leans into engineering intelligence and scorecards. Port is a no-code platform built on four elements: Software Catalog, Self-Service Actions, Scorecards, and Workflow Automation. OpsLevel adds checks — automated validations that run against services and can gate CI/CD.

What ties this group together is the scorecard. The catalog is not just a record of what exists. It is a record of what is expected of each service. Cortex integrates with tools like Snyk so security findings land on the service timeline next to on-call incidents and SLO data. Once the catalog ingests these signals, it stops being a directory and becomes a governance instrument.

The vendor differences are real. The underlying pattern is the same: the catalog is where the platform team encodes what good looks like.

How to actually implement one

Buying or building the platform is the easy part. Getting accurate data in and keeping it accurate is the hard part. The strategy that works runs in three phases, in order. Skipping or reordering them is the most common reason catalog projects fail.

Phase 1 — Define the minimum rules before importing anything.

The first decision is what every service must declare to be considered a valid catalog entry. This is the entity schema, and it matters more than which platform you pick. Get it wrong and either nobody uses it, or everyone fills it in with garbage.

Start small. A workable minimum is six fields: service name, owning team, tier, upstream dependencies, on-call route, and runbook link. That is enough to answer the 2am question and to start routing incidents. Add fields when there is a system that consumes them, never before. A field with no downstream consumer becomes optional, then ignored, then stale. Encode the schema as code, version it, review changes to it like code.

Phase 2 — Make CI/CD the entry point, and sync the catalog back.

Once the schema is stable, make the catalog the only legal way for a service to reach production. New services do not get a namespace, a domain, a repo, or a pipeline until they have a catalog entry. The CI/CD pipeline becomes the enforcement layer.

In practice this is a pipeline stage that validates the service against the schema before the first deploy. Missing owner? Pipeline fails. No tier defined? Pipeline fails. Engineers will complain at first. Three months later, the complaints stop, because the catalog has become invisible scaffolding rather than a documentation task. Each deploy then enriches the catalog automatically — version, commit SHA, deployer, environment. The catalog stops being a static record and becomes a deploy-time event stream.

The part most implementations miss is the reverse loop. CI/CD writes to the catalog. The catalog must also write back to IaC and configuration management. When ownership changes in the catalog, Terraform owner tags update. CODEOWNERS files regenerate. PagerDuty rotations re-bind. Helm chart labels reflect the new tribe. The catalog becomes the upstream source for every place service ownership is encoded in the rest of the stack.

This bidirectional sync is what makes the system survive team restructuring. Without it, ownership lives in five places and the catalog is just the sixth. With it, the catalog is the only place ownership is authored, and everything else is generated. When a re-org happens, you change one entry and the entire engineering stack reconfigures itself overnight. This is the difference between a catalog that decays after every reorg and one that absorbs them.

Phase 3 — Backfill the old services using IaC and configuration management.

This is where most implementations stall. New services flow in through CI/CD cleanly. The hundreds of pre-existing services running before the catalog existed do not. Backfilling them is slow, political, and boring.

The shortcut is to stop treating backfill as a manual exercise and start treating it as a derivation problem. The data already exists. Terraform state declares infrastructure ownership. Helm charts declare runtime configuration. CODEOWNERS files declare ownership. PagerDuty knows who is on call. Snyk and Wiz know what is deployed. Every one of these systems holds part of the truth.

The backfill strategy is to write derivation rules — scripts, pipelines, platform jobs — that read these existing sources and propose catalog entries. The platform team reviews, the owning team confirms or corrects, the entry lands. Slow at first, faster as patterns repeat. Once an entry is in the catalog, the bidirectional sync from Phase 2 takes over and the IaC inherits the catalog as upstream.

Backfilling from configuration management does one more thing worth knowing. It tells you which services have no clear owner anywhere — not in Terraform, not in CODEOWNERS, not in PagerDuty. Those services are the actual risk. The backfill does not just populate the catalog. It surfaces the orphans.

What FairPrice did with the catalog

At FairPrice Group, we treat the service catalog as the place where engineering discipline becomes visible. The Singapore retailer runs over 570 locations serving more than 1 million customer interactions daily, and without a clear catalog, ownership questions multiply faster than the team can answer them.

What I learned from running this in practice is that the value only shows up after three things are in place. Clarity: every service has a named owner, a tier, dependencies, runbooks, and an on-call route, and the catalog refuses incomplete entries. Discipline: scorecards grade each service against shared standards for production readiness, security posture, SLOs, and documentation — a feedback loop for the owning team, not a report card for managers. Self-regulation: once the catalog is the source of truth, every other system pulls from it. CI/CD pipelines check it before deploying. Incident management routes alerts using catalog ownership. Cost reports attribute spend to catalog teams. The catalog becomes the spine of how the engineering organisation regulates itself.

The hardest lesson did not come from setting the catalog up. It came from team reorganisations. When a squad gets restructured, a service moves to a new tribe, or someone leaves and the on-call rota is silently inherited, the catalog is the last place anyone thinks to update. The moment it stops reflecting the latest ownership, the entire engineering discipline starts to corrupt from underneath.

The failure mode is not that an incident routes to the wrong team once and gets redirected. It is what happens downstream over the following weeks. The new owning team does not see security findings because the dashboard is filtered by the old owner. Scorecards grade the service against the wrong team’s standards. Cost reports attribute spend to a tribe that no longer runs the workload. Access reviews approve the wrong people. Each looks like a small operational issue. They are not. They are the same lie, propagating through every system that trusts the catalog.

We learned to treat ownership changes as a first-class engineering event. Re-orgs do not complete until the catalog reflects them. The cost of getting this wrong is not a few misrouted pages. It is months of compounding governance drift that no observability tool will surface, because every tool is faithfully showing you a consistent picture built on stale truth.

What changes in the AI era

The service catalog is about to do something it has never had to do before. It is about to govern non-human actors.

Until now, every entity in the catalog has been built and maintained by a human team. Services have human owners. The catalog assumed a one-to-one relationship between an entity and a team.

That assumption is breaking. AI agents are entering production at a rate the catalog was not designed for. They consume services, expose tools, call other agents, and increasingly own workflows that used to belong to humans. The hyperscalers have already moved. AWS released Agent Registry through Bedrock AgentCore in April 2026 as a centralised catalog for AI agents, tools, MCP servers, and skills. Microsoft Agent 365 is generally available as a unified registry for organisational agents, with sync to AWS Bedrock and Google Cloud.

The signal is not that hyperscalers are building agent registries. The signal is that they are building them as catalogs — same primitives, same governance surface, same ownership model. The agent catalog and the service catalog are converging because the problems are the same.

The future state I am preparing for is a single catalog where services and agents coexist as first-class entities, governed by the same platform team with shared scorecards. A service has SLOs and security scans. An agent has eval pass rates, MCP server permissions, and skill provenance. Both have owners, tiers, dependencies, lineage.

This is also where DevSecOps consolidates. Security signals live in Snyk, code quality in SonarQube, SBOMs in Wiz and Artifactory, agent skills in separate registries. The catalog becomes where all of these land per entity. JFrog’s AI Catalog is positioned as the system of record for the enterprise AI supply chain. Wiz generates SBOMs agentlessly in SPDX and CycloneDX formats, portable into any catalog. Every signal that matters about a deployable thing converges on the catalog.

The harder problem ahead is that the catalog itself will need to be agent-operable. Catalog updates, ownership reassignments, scorecard remediations — these are the repetitive governance tasks agents will handle better than human platform teams. The platform team’s job shifts from maintaining the catalog by hand to defining the rules that agents follow when they maintain it.

Unified Service Catalog

What this means for platform engineering leaders

The platform engineering teams that will matter in three years are the ones that treat the service catalog as their most important product. Not the CI/CD pipeline. Not the Kubernetes platform. The catalog.

The reasoning is simple. The catalog is the only artefact in the engineering stack that has to be true. If the pipeline is slow, you optimise it. If the cluster is misconfigured, you fix it. If the catalog is wrong, every other system that depends on it is wrong too — ownership routing, incident response, security gating, cost attribution, agent governance. The catalog is upstream of everything.

Three positions are worth taking.

Treat the catalog as a product, with a roadmap and an owner. Most teams treat it as a side effect of buying a portal. That is how it goes stale. The catalog needs the same product discipline as any customer-facing system.

Pick the implementation that fits the maturity of your organisation, not the one with the best demo. Backstage offers flexibility at the cost of years of platform investment. Commercial platforms get you to value faster but lock you into someone else’s entity model. There is no universally correct answer, only the right one for where your organisation actually is.

Plan now for the agent catalog convergence. Teams that wait until agents are already proliferating will be doing a forensic exercise instead of a governance one. The right time to design the unified entity model is before either category sprawls.

The missing book is not missing because nobody knows it should exist. It is missing because most teams have not yet decided what it is a record of. Decide that, and everything else in platform engineering gets easier.

References

1. Spotify — Backstage Software Catalog and Developer Platform background
2. Spotify for Backstage — Backstage 101
3. Cortex — Spotify Backstage: Features, Benefits & Challenges in 2025
4. Datadog — DASH 2025: Guide to Datadog’s newest announcements
5. Datadog — Simplify microservice governance with the Datadog Software Catalog
6. Taloflow — Cortex vs Port for Platform Engineering in 2025
7. Encore Cloud — Platform Engineering Tools Compared: Backstage, Port, Cortex, OpsLevel, Humanitec, Encore
8. Platform Engineering Playbook — Internal Developer Portal Showdown 2025
9. Cortex — Cortex recognized as a Representative Vendor in the 2025 Gartner Market Guide for IDPs
10. Cortex — Easily map Snyk vulnerabilities to Cortex services
11. Port — Announcing Port Scorecards
12. Bitscale — FairPrice Group Company Profile
13. AWS Machine Learning Blog — The future of managing agents at scale: AWS Agent Registry now in preview
14. Microsoft Security Blog — Microsoft Agent 365, now generally available, expands capabilities and integrations
15. JFrog — JFrog AI Catalog: Enterprise AI Governance & Security
16. getDX — What is Spotify Backstage and how does it work in 2025
17. Wiz — Streamline SBOM Generation with Wiz’s Agentless SBOM
18. Wiz — Guide To Standard SBOM Formats
19. Port — What is a Configuration Management Database (CMDB)?
20. SquaredUp — Is service catalog the modern CMDB?
21. Jitendra Zaa — CMDB Complete Guide: From Beginner to Advanced
22. TechTarget — What is an IT service catalog? Definition
23. ServiceNow — What is an IT service catalog?
24. Ivanti — IT Service Catalog glossary