Backstage Catalog: CBA practice questions

The Software Catalog is the part of Backstage that keeps track of ownership and metadata for all the software in an organization. Its source of truth is metadata YAML stored in source control next to the code, conventionally a catalog-info.yaml file at the repository root, and when a change to that file is merged the catalog shows the new metadata after a short while.

Every entity has the same envelope: apiVersion, kind, metadata and spec. Backstage's own kinds use an apiVersion starting with backstage.io/, such as backstage.io/v1alpha1. metadata.name is required, must be 1 to 63 characters of letters, digits and the separators dash, underscore and dot, and is unique per kind within a namespace, compared without regard to case. The namespace defaults to default. Labels classify entities and the backstage.io/ prefix is reserved; annotations hold non-identifying string values, usually links to other systems; tags are short lowercase strings. The relations and status fields are produced by the catalog and are not written in descriptor files.

The kinds are Component, API, Resource, System, Domain, Group, User, Location and Template, and each has its own required spec fields. A Component needs type, lifecycle and owner, and can name a system, providesApis, consumesApis and dependsOn. An API needs type, lifecycle, owner and a definition, whose format follows the type, for example OpenAPI, AsyncAPI, GraphQL or gRPC. System and Domain need an owner, a Resource needs owner and type, a Group needs type and children (which may be empty), a User needs memberOf (which may be empty), and a Location lists target or targets to read. Spec fields such as owner and system become relations like ownedBy and partOf, and those relations are what consumers should read.

Common annotations connect an entity to tools. github.com/project-slug names the repository as owner/repository, backstage.io/techdocs-ref says where TechDocs source lives, and backstage.io/source-location points at the code when the descriptor is not stored there. The catalog itself adds backstage.io/managed-by-location and backstage.io/managed-by-origin-location, and sets backstage.io/orphan, which should never be added by hand.

Entities arrive in three ways: a user registers the full URL of a YAML file through the /create page, Software Templates register what they create automatically, or the app configuration lists static entries under catalog.locations. By default catalog.rules allows only the Component, API and Location kinds, so a Group in a newly registered file is rejected until the rules, globally or for that location, allow it. Setting the key replaces the default list.

Behind the scenes, entity providers ingest raw data with only a basic shape check, processors validate it and emit relations and errors, and a stitcher assembles the final entity. Processing never deletes anything. An entity that its parent location stops emitting becomes an orphan and is removed by default, unless orphanStrategy: keep is set. Processing errors appear on the entity in the UI.