Why catalogs matter at scale
200 services → no one knows owner, SLO, or blast radius of dependencies.
Service catalog — metadata registry: who owns what, how to call it, tier, compliance.
Backstage (common OSS)
Spotify-origin developer portal:
- Software catalog — entities (Component, API, Resource)
- Scaffolder — golden-path templates for new services
- TechDocs — docs-as-code in repo
- Plugins for K8s, Argo, PagerDuty
Minimum viable catalog entry
| Field | Purpose |
|---|---|
| Owner team | On-call routing |
| Tier (0–3) | Incident priority |
| Dependencies | Blast radius graph |
| OpenAPI / proto | Contract discovery |
| SLO | Error budget context |
| Repo / runbook | Operability |
API discovery
Developers find how to call Payments without Slack archaeology. Link OpenAPI from catalog; integrate with Communication contract-first workflow.
Golden paths
Platform team encodes blessed stack: K8s + mesh + observability bootstrap + CI template. Reduces snowflake services.
vs service registry
| Registry (Consul) | Catalog (Backstage) | |
|---|---|---|
| Purpose | Runtime routing | Human/developer metadata |
| Data | IP, port, health | Owner, docs, tier |
Both needed at scale.
Staff signal
Propose catalog when interviewer describes "we have 80 microservices and nobody knows who to page."
Further Reading
Hands-On Tasks (Optional)
Architecture drills and whiteboard exercises. Assumes Communication & Data Transfer and Distributed Systems fundamentals.
- Define a service catalog entry15m
For Payments API: owner team, tier, SLO, dependencies, on-call, repo, OpenAPI link, compliance tags. What breaks without catalog at 100 services?