Service Catalog: The Map Your Organization Actually Needs
A service catalog records ownership, dependencies, and interfaces for every service, making it possible to answer who owns what and what breaks if it fails.
Definition
A service catalog is a structured inventory of services, their owners, interfaces, dependencies, and operational metadata, kept close to the code that describes each service and exposed through a searchable interface or API.
Context and scope
Catalogs matter once an organization has more services than any engineer can name; without one, incident response starts with a Slack archaeology exercise.
Common misconceptions
- A catalog is a spreadsheet — static inventories are stale within a quarter
- Only microservices belong in a catalog — databases, queues, and shared libraries need owners too
- The catalog must be complete before it is useful — coverage grows as teams register new and changed services
Anti-patterns
- Maintaining the catalog by hand in a system separate from the code
- Recording dependencies nobody validates, so the graph becomes fiction
- Building a catalog with no search or ownership query, making it useless during incidents
Related concepts
Authoritative source
https://backstage.io/docs/features/software-catalog/software-catalog-overview
An inventory that has to stay current
A service catalog is only useful if it reflects reality today. That constraint shapes the design: entries should live next to the code, be updated by the same pull request that changes the service, and be validated automatically. A catalog maintained by a quarterly survey is a historical document.
What to record
Record the service name, its owner, its interfaces, its dependencies, its data classification, and its runbook. Keep the schema small enough that teams will fill it in. In practice, ownership, interface, and dependency fields deliver most of the value: they answer who to page, how to call the service, and what might break when it fails.
Keeping it truthful
A catalogue decays through missing updates and hopeful entries. Automated validation helps: reject descriptors without an owner, resolve links, and compare declared dependencies against observed traffic. Where a dependency is only declared and never observed, mark it as unverified rather than presenting it as fact.
During an incident
The catalog’s real test is a page at three in the morning. An on-call engineer should be able to search a service, see its owner and escalation path, list its upstream consumers, and open the runbook in under a minute. For example, a catalog that answers “which services call payments” before the incident commander asks turns a fifteen-minute discovery phase into a glance.
Compared to a wiki
A wiki is easy to start and impossible to trust: pages drift, links rot, and no query can answer who depends on what. A catalog enforces structure and can be validated. The cost is upfront schema design; the benefit is machine-readable answers exactly when time is scarce.