Service catalogs: ownership, dependencies and reliable metadata
Build a service catalog that helps during incidents. Define ownership records, distinguish declared dependencies from runtime evidence and detect stale metadata.
TL;DR: A service catalog connects a stable service identity to accountable people and operational evidence. Keep ownership maintained through normal change workflows, and verify that catalog links resolve when someone actually needs help.
A useful record answers an operational question
An incident responder searching for invoice-worker needs the current owning team, its escalation route and the service's operating instructions. A repository URL alone cannot answer who accepts responsibility at night. Equally, an individual engineer's name becomes stale after a transfer or leave period.
Use a stable service identifier and team ownership. Preserve previous names as searchable aliases when a service is renamed. Decide how a component differs from a repository: a monorepo can contain several deployable services, and one service may involve more than one repository. The catalog's unit should match the operational responsibility people can actually exercise.
Backstage describes components and their relationships in its catalog descriptor format. Its ownership field communicates responsibility; it does not, by itself, grant cloud permissions or prove that the team has accepted on-call duties.
Follow one record from Git to an incident
This illustrative descriptor identifies a service and its owning group. The group and system references must resolve to entities your catalog knows.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: invoice-worker
description: Produces invoice documents from approved billing events.
spec:
type: service
lifecycle: production
owner: group:default/billing-operations
system: billing
Add operational links through the catalog's supported metadata conventions. Keep credentials out of the descriptor. A dashboard link can be public within the company while the dashboard itself still enforces authorization.
The correction loop matters. A beautifully populated catalog that cannot incorporate mistakes found during incidents becomes another stale inventory.
Suppose a hypothetical company has 80 production service records. Twelve point to archived team channels, and five have no documented backup escalation. Reporting “100% catalog coverage” conceals the immediate operational problem. Measure whether a responder can reach an accountable team for the services that matter, then fix the missing routes before importing hundreds more records.
Store facts with an authority and a freshness rule
| Catalog fact | Suitable authority | How to detect staleness |
|---|---|---|
| Owning team | Accepted ownership change in source or organizational system | Group deleted, handoff unacknowledged |
| Deployed revision | Deployment controller or release records | Observation timestamp too old |
| Declared dependency | Service configuration or reviewed descriptor | Reference no longer resolves |
| Observed dependency | Tracing or network telemetry | Observation window excludes quiet paths |
| Runbook | Maintained operational repository | Link broken or exercise finds incorrect steps |
Declared dependencies express intended relationships. Observed calls describe traffic seen during a particular window. Neither is a complete substitute for the other. A nightly export may be critical even when daytime traces show no calls to its storage dependency.
Preserve that distinction in the interface. A responder should see “declared database dependency” or “observed in the last hour,” with the evidence's age, rather than a single apparently authoritative graph built from incompatible inputs. Also distinguish “no observations” from “no dependency.”
Make ownership changes an acceptance process
When teams reorganize, update more than a YAML string. The receiving team needs access, operating knowledge and capacity to take the responsibility. Google's SRE engagement model discusses responsibility through engagement and readiness. Apply the same reasoning to a catalog handoff: the record should reflect an agreement that has happened.
For the invoice worker, a concrete acceptance exercise is to locate its last release, diagnose a deliberately failed staging job and find the procedure for replaying an event safely. Keep the previous escalation route available during a bounded transition. Record the date when the receiving team becomes primary and the unresolved work that remains with the original team.
A catalog can flag incomplete handoffs, but it cannot settle them automatically. Use cross-team ownership negotiation when teams disagree about the boundary.
Check whether the record helps someone unfamiliar with the service
An interview answer should explain how metadata gets corrected and what operational decision it supports. Naming Backstage plugins without a maintenance model leaves the main failure mode unresolved.
Self-check: a service has a valid owner reference and a green ingestion status. Can the platform report that it has operational ownership?
Only after defining what that claim means. Schema validation proves the record is structurally acceptable. Verify that the team acknowledges responsibility, that escalation works and that a responder can access the necessary evidence. If those checks fail, display the gap and assign a correction instead of treating successful ingestion as readiness.