Backstage and the software catalog
Backstage is the developer portal Spotify built for itself and open-sourced in 2020; it is a CNCF incubating project. It is not a product you install and use as is: it is a framework for building your company's portal. You create an app (npx @backstage/create-app), choose plugins, configure it in app-config.yaml, and run it like any other service - a React frontend and a Node.js backend, by default on port 3000 (frontend, in development) and 7007 (backend, which also serves the built frontend in production).
The heart of every Backstage install is the software catalog: one place that answers "what do we run, who owns it, what does it depend on, where are its docs". Everything else (templates, docs, the Kubernetes view, CI status) hangs off catalog entities.
In the lab, Backstage runs at http://backstage.lab:7007. Console > Backstage is its web UI; in the terminal you use its REST API with curl, which is what scripts, CI jobs and on-call engineers do.
Entities and catalog-info.yaml
The catalog is a set of entities, each described in YAML that looks a lot like a Kubernetes object - on purpose. Teams keep them in their own repositories, usually in a file called catalog-info.yaml at the root:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: orders
description: Takes and tracks customer orders
annotations:
gitlab.com/project-slug: platform/orders
backstage.io/kubernetes-id: orders
backstage.io/techdocs-ref: dir:.
tags:
- java
spec:
type: service
lifecycle: production
owner: team-orders
system: shop
providesApis:
- orders-api
dependsOn:
- resource:default/orders-db
The built-in kinds:
| Kind | What it models | Required spec fields |
|---|---|---|
| Component | a piece of software: a service, website, library | type, lifecycle, owner |
| API | an interface a component provides (OpenAPI, AsyncAPI, gRPC, GraphQL) | type, lifecycle, owner, definition |
| Resource | infrastructure a component needs: a database, a bucket, a queue | type, owner |
| System | a collection of components, APIs and resources that form one product | owner |
| Domain | a business area grouping systems | owner |
| Group | a team or department | type, children |
| User | a person | memberOf |
| Location | points at more catalog files to read | (target or targets) |
| Template | a Software Template (next lesson) | type, steps |
type and lifecycle are free strings, but a company agrees on a short list (service, website, library; experimental, production, deprecated) so the catalog can be filtered.
Names, namespaces and references
Every entity is identified by kind, namespace and name. The namespace defaults to default; most companies never use another. A reference writes that as kind:namespace/name, and the catalog stores it in lowercase: component:default/orders.
Inside spec, references can be shortened, and each field has a default kind: owner: team-orders means group:default/team-orders, system: shop means system:default/shop, providesApis: [orders-api] means api:default/orders-api. Two fields have no default kind: dependsOn and dependencyOf can point at a component or a resource, so you must write the kind (resource:default/orders-db or resource:orders-db).
metadata.name must be at most 63 characters of letters, digits and -_., starting and ending with a letter or digit. No spaces: the human-friendly name goes in metadata.title.
Relations
From those spec fields the catalog builds relations, always in both directions:
| Field | Relation (and its reverse) |
|---|---|
owner | ownedBy / ownerOf |
system, subcomponentOf, domain | partOf / hasPart |
providesApis | providesApi / apiProvidedBy |
consumesApis | consumesApi / apiConsumedBy |
dependsOn | dependsOn / dependencyOf |
memberOf (User), members (Group) | memberOf / hasMember |
parent, children (Group) | childOf / parentOf |
$ curl -s -H "Authorization: Bearer $TOKEN" http://backstage.lab:7007/api/catalog/entities/by-name/component/default/orders | jq .relations
[
{
"type": "dependsOn",
"targetRef": "resource:default/orders-db"
},
{
"type": "ownedBy",
"targetRef": "group:default/team-orders"
},
{
"type": "partOf",
"targetRef": "system:default/shop"
},
{
"type": "providesApi",
"targetRef": "api:default/orders-api"
}
]
A relation to an entity that does not exist is not an error: the catalog shows a dangling link. That is why ownership needs care: if team-orders is not a Group in the catalog, nobody can find the owner of orders.
Annotations: how plugins find things
Annotations connect an entity to the outside world. Plugins read them:
| Annotation | Used by |
|---|---|
backstage.io/kubernetes-id | the Kubernetes plugin: workloads labelled with the same value |
backstage.io/kubernetes-namespace, backstage.io/kubernetes-label-selector | narrow or replace that lookup |
backstage.io/techdocs-ref | TechDocs: where the docs source is (dir:. = next to this file) |
gitlab.com/project-slug / github.com/project-slug | the GitLab / GitHub plugins: group/repo |
backstage.io/source-location | where the source lives (set automatically from the location) |
backstage.io/managed-by-location | the catalog file this entity came from (set by the catalog) |
Locations and processing
The catalog does not watch git. You register a location - the URL of a catalog-info.yaml - and the catalog's processing loop reads it, again and again, on its own schedule (every couple of minutes by default). Each location becomes a Location entity named generated-<sha1 of the type and URL>; the entities in the file become children of it.
Processing one entity runs, in order: an envelope check, the policies (schema, default namespace, no unknown root fields, field formats), kind validation (the required fields above), then the processors that add relations. Any failure stops that entity. If it is new, it never appears; if an older version exists, that version stays, with the error attached to it.
$ curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"type":"url","target":"https://git.lab/platform/orders/-/blob/main/catalog-info.yaml"}' \
"http://backstage.lab:7007/api/catalog/locations?dryRun=true" | jq -r '.entities[].metadata.name'
generated-f6211a33547344583b309aeee3eb66ff73c25f87
orders-api
orders
?dryRun=true processes the file and returns what would be created, without registering anything - the safest first step. Drop it to register for real. (The catalog works through the entities as a stack: the Location first, then the file's entities last-first, so orders-api, the second document, comes before orders. The first entity that fails stops the dry run, and the error is that entity's alone - fix it and run it again to see the next one.) Registering a URL that is already registered is a 409 Conflict: Location url:https://... already exists.
The validation errors
Learn to read these; you will see them in every portal you run. A name with a space:
InputError: Policy check failed for component:default/payments api; caused by Error: "metadata.name" is not valid; expected a string that is sequences of [a-zA-Z0-9] separated by any of [-_.], at most 63 characters in total but found "Payments API". To learn more about catalog file format, visit: https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md
A Component without an owner:
Processor BuiltinKindsEntityProcessor threw an error while validating the entity component:default/payments-api; caused by TypeError: /spec must have required property 'owner' - missingProperty: owner
A dependsOn without a kind:
Processor BuiltinKindsEntityProcessor threw an error while postprocessing; caused by Error: Entity reference "orders-db" had missing or empty kind (e.g. did not start with "component:" or similar)
A URL the catalog cannot read (wrong branch, wrong path, file not pushed yet):
Unable to read url, https://git.lab/platform/orders/-/blob/main/catalog-info.yaml could not be read as https://git.lab/api/v4/projects/platform%2Forders/repository/files/catalog-info.yaml/raw?ref=main, 404 Not Found
The REST API
The catalog backend serves /api/catalog. Every request needs a token: in the lab a static token configured for external access (backend.auth.externalAccess in app-config.yaml), stored in ~/oncall-lab/labs/platform/backstage-token. Without it the backend answers 401 with AuthenticationError: Missing credentials; with a wrong one, Illegal token.
| Request | Does |
|---|---|
GET /api/catalog/entities/by-name/:kind/:namespace/:name | one entity (404: No entity named 'x' found, with kind 'component' in namespace 'default') |
GET /api/catalog/entities/by-query?filter=kind=component,spec.owner=team-orders | a filtered list (filter= sets combine with OR) |
POST /api/catalog/locations[?dryRun=true] | register (or test) a catalog file: {"type":"url","target":"..."} |
POST /api/catalog/validate-entity | validate one entity: {"entity": {...}, "location": "url:..."} - 200 with no body when valid, 400 with errors when not |
POST /api/catalog/refresh | process an entity now: {"entityRef":"component:default/orders"} |
DELETE /api/catalog/locations/:id | unregister a location (its entities become orphans) |
Errors always come back in the same shape: {"error":{"name":...,"message":...},"request":{"method":...,"url":...},"response":{"statusCode":...}}.
(simulator) The lab's Backstage has no frontend build of its own (Console > Backstage plays that part), reads catalog files only from git.lab, and processes locations within a few seconds of a change instead of on its normal schedule.
In an interview: the software catalog holds entities (Component, API, Resource, System, Domain, Group, User) that teams describe in a catalog-info.yaml in their repo and register as a location; the catalog derives relations (ownedBy, dependsOn, providesApi...) and plugins find external data through annotations. An entity that fails a policy or kind validation never appears - test with ?dryRun=true or validate-entity.