OnCallReadyStart learning

Infrastructure as code Lesson 42.16 · Platform Engineering: Backstage & Crossplane · 17 min read

Backstage and the software catalog

In plain words

The software catalog is the company's phone book for software. Every service, API, database and team has an entry saying what it is, who owns it and what it depends on. Teams write their own entry in a small file next to their code, and the phone book reads it regularly, so when something breaks at night anyone can look up who to call.

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:

KindWhat it modelsRequired spec fields
Componenta piece of software: a service, website, librarytype, lifecycle, owner
APIan interface a component provides (OpenAPI, AsyncAPI, gRPC, GraphQL)type, lifecycle, owner, definition
Resourceinfrastructure a component needs: a database, a bucket, a queuetype, owner
Systema collection of components, APIs and resources that form one productowner
Domaina business area grouping systemsowner
Groupa team or departmenttype, children
Usera personmemberOf
Locationpoints at more catalog files to read(target or targets)
Templatea 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:

FieldRelation (and its reverse)
ownerownedBy / ownerOf
system, subcomponentOf, domainpartOf / hasPart
providesApisprovidesApi / apiProvidedBy
consumesApisconsumesApi / apiConsumedBy
dependsOndependsOn / 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:

AnnotationUsed by
backstage.io/kubernetes-idthe Kubernetes plugin: workloads labelled with the same value
backstage.io/kubernetes-namespace, backstage.io/kubernetes-label-selectornarrow or replace that lookup
backstage.io/techdocs-refTechDocs: where the docs source is (dir:. = next to this file)
gitlab.com/project-slug / github.com/project-slugthe GitLab / GitHub plugins: group/repo
backstage.io/source-locationwhere the source lives (set automatically from the location)
backstage.io/managed-by-locationthe 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.

RequestDoes
GET /api/catalog/entities/by-name/:kind/:namespace/:nameone 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-ordersa 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-entityvalidate one entity: {"entity": {...}, "location": "url:..."} - 200 with no body when valid, 400 with errors when not
POST /api/catalog/refreshprocess an entity now: {"entityRef":"component:default/orders"}
DELETE /api/catalog/locations/:idunregister 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.

Why it helps

Ownership is the first thing an incident needs and the first thing that goes stale in a growing company. The catalog makes it a file in each repository, checked by the same validation every time. Knowing the entity kinds, references, relations, annotations and the exact validation errors lets you onboard services correctly, fix the ones the catalog refuses, and script against the catalog's API.

On the blog

Commands in this lesson

curl

FAQ

Why does owner work without a kind but dependsOn does not?

Each spec field has a default kind for short references: owner defaults to Group, system to System, providesApis to API. dependsOn can point at a component or a resource, so it has no default kind and must be written in full, as resource:name or component:name.

Why can metadata.name not contain spaces?

It is an identifier: letters, digits and dash, underscore or dot, at most 63 characters, starting and ending with a letter or digit. The human-friendly name belongs in metadata.title, which the UI shows instead wherever it can.

How does the catalog read catalog-info.yaml?

You register a location, the URL of the file. The processing loop reads it again and again on its own schedule, validates every entity, adds relations and stores the result. If a new entity fails, it never appears; if an older version exists, it stays with the error attached.

How do I test a file before registering it?

POST it as a location with ?dryRun=true to see what would be created and every error, or send a single entity to /api/catalog/validate-entity, which answers 200 with no body when it is valid and 400 with the errors when it is not.

What are annotations used for?

They connect an entity to the outside world for plugins: backstage.io/kubernetes-id for the Kubernetes tab, backstage.io/techdocs-ref for docs, gitlab.com/project-slug or github.com/project-slug for the repository. The catalog also adds its own, such as the location an entity came from.

In an interview Mid

What is the Backstage software catalog and how do services get into it?

It holds entities - Component, API, Resource, System, Domain, Group, User - described by each team in a catalog-info.yaml in its own repository. You register the file's URL as a location; the catalog processes it on a loop, validates it against policies and the kind schemas, and derives relations such as ownedBy, partOf, providesApi and dependsOn. Plugins find external data through annotations. I test new files with a dry-run location or validate-entity before registering.

Also asked: What are the required fields of a Component? · What is a Location entity? · How would you keep ownership in the catalog accurate?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.