Service Catalog

A service catalog records software and its ownership. In the software-and-ownership sense used here, Backstage describes components such as services, websites, libraries and data pipelines through metadata that people and tools can discover.

The catalog’s metadata function is distinct from provisioning, deployment and operation. A portal can combine the catalog with workflows that perform those actions; the record alone is not the execution engine.

What it answers, and what it does not

Metadata the catalog records	Additional execution or evidence needed
Software and resource inventory	A workflow to create another instance
Accountable owner and support links	Confirmed on-call and escalation arrangements
Declared relationships and dependencies	Runtime health from monitoring and current dependency evidence
Documentation, dashboards and repository locations	An authorization decision enforced by the relevant service

The left column is genuinely valuable, and it is worth stating why rather than assuming it. The documented use cases are “helping teams manage and maintain the software they own” and making all the software “and who owns it, discoverable — no more orphan software hiding in the dark corners of your software ecosystem.”

A current owner and escalation route can reduce delays in incident response, patching and handover. The owner need not be the first responder. Confirm both the responsibility and the contact path; a catalog entry cannot replace that agreement. Whether a catalog is the cheapest improvement depends on the estate and existing tools.

As an estate grows, a shared index can make ownership and dependencies easier to discover than relying on personal knowledge. The useful scale depends on complexity and how the records are maintained, not a fixed service-count threshold.

The entity model is a useful vocabulary on its own

Backstage’s system model supplies a common vocabulary for discussing software and infrastructure. It can also guide a catalog built with another tool.

Components describe software; APIs describe interfaces that components provide or consume; resources describe infrastructure such as databases, queues and object stores. Users represent people and groups represent teams or other organizational units. Relationships between these records help users understand dependencies and resource ownership.

Two design decisions in that model repay attention because they turn a list into something you can reason with.

The model treats APIs as first-class entities with machine-readable contracts. It discusses public, restricted and private visibility, while noting that some concepts are not implemented in Backstage. Verify the installed schema and use a documented extension where needed. Visibility describes intended consumers, not access enforcement, and private APIs still need coordinated changes with their internal consumers.

Systems group cooperating entities behind exposed APIs. Domains group related systems by business purpose, terminology and models, connecting the catalog to the idea of a bounded context. Encapsulation allows implementation changes that preserve the consumer contract; merely grouping records does not guarantee compatibility or isolation.

The type field is locally defined. Agree its meanings and validation rules so teams do not use the same label for incompatible categories.

Keeping catalog records trustworthy

Backstage supports repository YAML, registration through its interface, creation through templates and external sources. Entity providers ingest records; processors can validate or enrich them; the backend stores the processed result. Define an authoritative source for each field rather than assuming every value must originate in Git.

Derive fields from maintained systems where that improves reliability, and assign responsibility for facts that need human confirmation. Track ingestion time, failures and conflicting inputs. A source update may not yet be reflected in the displayed record, and automated collection can faithfully reproduce an incorrect source value.

Check ownership, escalation and support expectations with the responsible team. Treat source freshness and the truth of those claims as separate questions, and make unconfirmed records visible rather than presenting every harvested field as verified.

Evaluate accuracy, coverage and freshness together, weighted by the consequences of a wrong or missing answer. Partial, clearly labeled coverage can be useful, but omitted assets still matter for patching and retirement. Expose the uncollected and uncertain parts of the estate, and let users report incorrect records. One bad field does not determine every use of the catalog.

Where it sits in a platform

A catalog is commonly exposed through a portal alongside documentation, telemetry and provisioning workflows. The CNCF paper distinguishes the portal and API capabilities; that separates their responsibilities without requiring separate products or preventing actions from starting on a catalog page.

Self-service provisioning needs a discoverable route to the capability. A catalog can provide that route, but a documented API, CLI or focused service page may be sufficient. A software inventory and a menu of available services are related views, not necessarily the same data model or a mandatory prerequisite for each other.

Backstage Software Templates separately describe a form’s inputs and execution steps. In ITSM, a service catalog can instead describe requestable offerings and their fulfillment contracts. An illustrative database item would name eligible requesters, allowed sizes, required cost or access approvals, a fulfillment owner, expected completion conditions, and status and support routes. ServiceNow’s catalog-item documentation describes approval and fulfillment workflows. A software inventory can link the resulting database to an owner without itself performing those steps. This entry’s inventory model and that request model can share a portal while serving different questions. What Happens After the Click explains the rest of an internal platform, and developer portal explains its interface.

References

• Backstage: Software Catalog
• System Model
• CNCF TAG App Delivery: Platforms White Paper
• CNCF Platform Engineering Maturity Model
• Backstage: External integrations
• Backstage: Software Templates
• ServiceNow — Service Catalog items