Skip to content
Hands-on IT IT Drills

Day 2: The Data Model

Goal: Model shipment tracking as a Domain, System, Resource and Components, and reliably find errors in the catalog · Duration: approx. 90 min · Prerequisite: Day 1

Briefing

  • Prerequisite (end of Day 1): the lab is running, sendungs-api (Component + API) and tracking-web are registered via their Forgejo URLs.
  • Every entity has four parts: apiVersion, kind, metadata, spec.
  • References are written as an entity reference kind:namespace/name; from spec fields the catalog creates relations in both directions.
  • Today you create the repo kranich/sendungsverfolgung (shipment tracking) with a Domain, System, Resource and a worker.
  • Finally you deliberately build broken files and learn where Backstage shows the errors.
Domain logistik
 └─ System sendungsverfolgung
     ├─ Component sendungs-api ─────providesApi──▶ API sendungs-api
     ├─ Component tracking-web ─────consumesApi──▶ API sendungs-api
     ├─ Component sendungs-worker ──dependsOn────▶ Resource sendungs-db
     └─ Resource sendungs-db   (sendungs-api ─dependsOn─▶ sendungs-db)

Drill 1: Anatomy of an Entity

Fetch the component sendungs-api the way the catalog has stored it:

source ~/backstage-lab/setup/env.sh
bs catalog/entities/by-name/component/default/sendungs-api \
  | jq '{apiVersion, kind, metadata: (.metadata | {namespace, name, uid}),
         spec, relations}'

Expected:

{
  "apiVersion": "backstage.io/v1alpha1",
  "kind": "Component",
  "metadata": {
    "namespace": "default",
    "name": "sendungs-api",
    "uid": "eedef0a5-18f1-4577-a9a5-d63cd3a8a001"
  },
  "spec": {
    "type": "service",
    "lifecycle": "production",
    "owner": "team-sendung",
    "providesApis": [ "sendungs-api" ]
  },
  "relations": [
    { "type": "ownedBy", "targetRef": "group:default/team-sendung" },
    { "type": "providesApi", "targetRef": "api:default/sendungs-api" }
  ]
}

Why? The YAML file only says owner: team-sendung. The catalog fills in the namespace (default) and kind (for owner that is group) and stores the result as the full reference group:default/team-sendung. uid, etag and relations are assigned by the catalog itself – you never write them into a file.

The annotations show where the entity comes from:

bs catalog/entities/by-name/component/default/sendungs-api \
  | jq '.metadata.annotations | keys'

Expected:

[
  "backstage.io/edit-url",
  "backstage.io/managed-by-location",
  "backstage.io/managed-by-origin-location",
  "backstage.io/source-location",
  "backstage.io/techdocs-ref",
  "backstage.io/view-url"
]

Only techdocs-ref comes from the file; the catalog sets the others while ingesting (they produce View Source and the pencil button in the About card).

Save your progress? Sign up for free

Drill 2: A New Repo with Four Entities

A file may contain multiple entities, separated by ---. Create the repo kranich/sendungsverfolgung:

mkdir -p ~/backstage-lab/tag02/sendungsverfolgung
cd ~/backstage-lab/tag02/sendungsverfolgung
cat > catalog-info.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: logistik
  title: Logistik
  description: Alles rund um Transport und Zustellung
spec:
  owner: team-sendung
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: sendungsverfolgung
  title: Sendungsverfolgung
  description: Kunden sehen, wo ihr Paket gerade ist
spec:
  owner: team-sendung
  domain: logistik
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: sendungs-db
  description: PostgreSQL mit allen Sendungsereignissen
spec:
  type: database
  owner: team-sendung
  system: sendungsverfolgung
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sendungs-worker
  title: Sendungs-Worker
  description: Liest Scanner-Ereignisse und schreibt sie in die Datenbank
  tags: [nodejs, queue]
  labels:
    kranich.de/kritikalitaet: hoch
  annotations:
    backstage.io/kubernetes-id: sendungs-worker
  links:
    - url: https://grafana.kranich.example/d/sendungs-worker
      title: Dashboard
      icon: dashboard
    - url: https://wiki.kranich.example/runbooks/sendungs-worker
      title: Runbook
      icon: docs
spec:
  type: service
  lifecycle: experimental
  owner: team-sendung
  system: sendungsverfolgung
  dependsOn:
    - resource:sendungs-db
EOF
~/backstage-lab/setup/mkrepo.sh kranich/sendungsverfolgung .

Expected:

✔ kranich/sendungsverfolgung angelegt (http://127.0.0.1:3300/kranich/sendungsv…)

dependsOn has a kind prefix (resource:) because the field can point to Components and Resources; for system and domain the kind is unambiguous.

Now register it as on Day 1:

  1. Open Register Existing Component in the sidebar.
  2. Under URL enter: http://127.0.0.1:3300/kranich/sendungsverfolgung/src/branch/main/catalog-info.yaml
  3. Click ANALYZE.

Expected: a red error message instead of the preview, as in the figure.

The import fails because of the Domain

Why? The app-config.yaml from create-app only allows catalog.rules: [Component, System, API, Resource, Location]. Domain is missing – the rule checks every entity, and a single forbidden one makes the whole import fail.

Warning: Via the API (bs catalog/locations -X POST … without dryRun) the location is created anyway, but not a single entity appears. You will then find the reason only in the backend log (Drill 8).

Save your progress? Sign up for free

Drill 3: Allowing and Importing Domains

Append a catalog block to the local configuration (when the config is merged, lists completely replace the list from app-config.yaml):

cat >> ~/backstage-lab/portal/app-config.local.yaml <<'EOF'
catalog:
  rules:
    - allow: [Component, System, API, Resource, Location, Domain]
EOF
~/backstage-lab/setup/portal.sh restart

Expected:

✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
  1. Open Register Existing Component again, enter the same URL, ANALYZE.
  2. In the Review step, check the list.
  3. Click IMPORT, then VIEW COMPONENT.

Expected: Review lists five entities – your four plus the generated location (the hash in the name depends on the URL), as in the figure.

Review step with five entities from one file

More about catalog.rules and locations on Day 3.

Save your progress? Sign up for free

Drill 4: Metadata You Can See

Open Catalog, set the Kind filter to Component and click Sendungs-Worker.

Expected: on the right, the About, Links and Labels cards as in the figure.

About, Links and Labels cards of the worker
Field Effect in the GUI
metadata.title Display name instead of name (heading, tables)
metadata.tags gray chips, Tags filter in the catalog
metadata.labels Labels card, key/value for selecting
metadata.links Links card with icon (dashboard, docs, github, …)
metadata.annotations control plugins – here the Kubernetes tab appears

Why? Tags are free-form keywords (only a-z0-9+#, joined with -), labels are key/value pairs for selecting, annotations are the interface to plugins. The Kubernetes tab stays empty until Day 10.

Save your progress? Sign up for free

Drill 5: Hooking Existing Repos into the System

sendungs-api and tracking-web get spec.system; sendungs-api additionally depends on the database, tracking-web on sendungs-api. Clone, replace the file completely, push:

cd ~/backstage-lab/tag02
GIT=http://lab-admin:[email protected]:3300        # lab value!
git clone -q $GIT/kranich/sendungs-api.git
git clone -q $GIT/kranich/tracking-web.git
cat > sendungs-api/catalog-info.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sendungs-api
  title: Sendungs-API
  description: REST-API für den Sendungsstatus
  tags: [nodejs, rest]
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-sendung
  system: sendungsverfolgung
  providesApis: [sendungs-api]
  dependsOn: [resource:sendungs-db]
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: sendungs-api
  description: Öffentliche Schnittstelle der Sendungsverfolgung
spec:
  type: openapi
  lifecycle: production
  owner: team-sendung
  system: sendungsverfolgung
  definition:
    $text: ./openapi.yaml
EOF
cat > tracking-web/catalog-info.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: tracking-web
  title: Tracking-Web
  description: Web-Oberfläche zur Sendungsverfolgung
  tags: [web]
spec:
  type: website
  lifecycle: production
  owner: team-web
  system: sendungsverfolgung
  consumesApis: [sendungs-api]
  dependsOn: [component:sendungs-api]
EOF
for r in sendungs-api tracking-web; do
  git -C $r -c user.name="Lab Admin" -c [email protected] \
    commit -qam "In System sendungsverfolgung einhängen"
  git -C $r push -q origin main
done
git -C sendungs-api log --oneline

Expected:

bdef724 In System sendungsverfolgung einhängen
a6a1fbc Initialer Stand

The catalog rereads the files regularly (in the lab after about two minutes). Don’t wait – trigger a refresh via the API; it rereads the entity’s source:

for e in component:default/sendungs-api component:default/tracking-web; do
  bs catalog/refresh -X POST -H 'Content-Type: application/json' \
    -d "{\"entityRef\":\"$e\"}"
done
sleep 5
bs 'catalog/entities?filter=spec.system=sendungsverfolgung&fields=kind,metadata.name' \
  | jq -r '.[] | "\(.kind) \(.metadata.name)"'

Expected (order may differ):

Component sendungs-worker
API sendungs-api
Resource sendungs-db
Component tracking-web
Component sendungs-api

Save your progress? Sign up for free

Drill 6: System, Domain and Catalog Graph

  1. In the worker’s About card, click Sendungsverfolgung (under SYSTEM).

Expected: the system page with Has components (three entries), Has resources and the Relations card as in the figure.

System page with components, resource and relations diagram

The yellow warning “relations to other entities, which can’t be found” is intended: the group team-sendung is only created on Day 4.

  1. In the About card under DOMAIN, click Logistik.

Expected: the domain page with Has systems as in the figure.

Domain page with the system Sendungsverfolgung
  1. Under Has systems click Sendungsverfolgung, then under Has resources click sendungs-db; in its Relations card click View graph.
  2. Open FILTERS: MAX DEPTH to 2; under RELATIONS remove everything except dependsOn, dependencyOf, partOf, hasPart; turn Simplified off.

Expected: a graph around sendungs-db – three components depend on the database directly or via sendungs-api, as in the figure.

Catalog Graph around sendungs-db with filtered relations

Why? Simplified shows edges in one direction only; with it turned off you also see who points to the database (dependencyOf). The filters end up in the URL – handy for sharing a view.

Save your progress? Sign up for free

Drill 7: Relations via the API

Every spec reference becomes a pair of relations (partOf/hasPart, dependsOn/dependencyOf, providesApi/apiProvidedBy, consumesApi/apiConsumedBy, ownedBy/ownerOf):

bs catalog/entities/by-name/resource/default/sendungs-db \
  | jq -r '.relations[] | "\(.type)\t\(.targetRef)"' | sort

Expected:

dependencyOf    component:default/sendungs-api
dependencyOf    component:default/sendungs-worker
ownedBy         group:default/team-sendung
partOf          system:default/sendungsverfolgung

Relations can be filtered – “who depends on the database?”:

bs 'catalog/entities?filter=relations.dependsOn=resource:default/sendungs-db' \
  | jq -c 'map(.metadata.name)'

Expected:

["sendungs-worker","sendungs-api"]

Tip: In the filter the reference must be complete (resource:default/…); the short form from the YAML file finds nothing.

Save your progress? Sign up for free

Drill 8: Provoking and Finding Errors

Clone the new repo and create three broken files – a space in the name, a missing owner, an unknown kind:

cd ~/backstage-lab/tag02
GIT=http://lab-admin:[email protected]:3300        # lab value!
git clone -q $GIT/kranich/sendungsverfolgung.git sv
cd sv
cat > kaputt-name.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: Sendungs Archiv
spec:
  type: service
  lifecycle: experimental
  owner: team-sendung
EOF
cat > kaputt-owner.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sendungs-archiv
spec:
  type: service
  lifecycle: experimental
EOF
cat > kaputt-kind.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Komponente
metadata:
  name: sendungs-archiv
spec:
  type: service
  lifecycle: experimental
  owner: team-sendung
EOF
git add -A
git -c user.name="Lab Admin" -c [email protected] commit -qm "Spielwiese"
git push -q origin main

Check each file with a dry run – the same call that ANALYZE makes in the GUI. bs uses curl -f and swallows error texts, so here you use curl directly:

pruefe() {
  local u="$FORGEJO/kranich/sendungsverfolgung/src/branch/main/$1"
  curl -s -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
    -H 'Content-Type: application/json' -X POST \
    "$BACKSTAGE/api/catalog/locations?dryRun=true" \
    -d "{\"type\":\"url\",\"target\":\"$u\"}" \
    | jq -r '.error.message // "ok"' | cut -c1-170
}
for f in kaputt-name.yaml kaputt-owner.yaml kaputt-kind.yaml; do pruefe $f; done

Expected (wrapped):

InputError: Policy check failed for component:default/sendungs archiv; 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 …
InputError: Processor BuiltinKindsEntityProcessor threw an error while validating
  the entity component:default/sendungs-archiv; caused by TypeError: /spec must
  have required property 'owner' - missingProperty: owner
NotAllowedError: Entity komponente:default/sendungs-archiv at url:http://127.0.0…
  is not of an allowed kind for that location

Why? Uppercase letters are allowed in metadata.name, the space is not. An unknown kind already fails at catalog.rules, before any schema is checked. Delete the playground again:

git rm -q kaputt-*.yaml
git -c user.name="Lab Admin" -c [email protected] commit -qm "Spielwiese weg"
git push -q origin main

An error in a file that is already registered is more dangerous. Remove the worker’s owner:

sed -i '' '/name: sendungs-worker/,$ {/owner: team-sendung/d;}' catalog-info.yaml
git diff --stat
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Owner entfernt (Absicht)"
git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
  -d '{"entityRef":"component:default/sendungs-worker"}'

Expected:

 catalog-info.yaml | 1 -
 1 file changed, 1 deletion(-)

Open Sendungs-Worker in the GUI (reload the page).

Expected: the owner is still team-sendung, with a red error card below it, as in the figure.

Error card on the entity page after a broken push

Why? If processing fails, the catalog keeps the last valid state and attaches the error. Nobody notices unless they look at the page – which is why there are two more ways:

bs catalog/entities/by-name/component/default/sendungs-worker \
  | jq -r '.status.items[] | "\(.level): \(.error.cause.message)"'
~/backstage-lab/setup/portal.sh logs 300 | grep 'catalog.*warn.*validating'

Expected (log shortened):

error: /spec must have required property 'owner' - missingProperty: owner
2026-10-13T06:42:16.485Z catalog warn Processor BuiltinKindsEntityProcessor threw
  an error while validating the entity component:default/sendungs-worker; …
  entity="component:default/sendungs-worker" location="url:http://127.0.0.1:3300/…"

The log line comes from @backstage/plugin-catalog-backend-module-logs, which create-app already wires into packages/backend/src/index.ts. Repair it:

git revert --no-edit HEAD
git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
  -d '{"entityRef":"component:default/sendungs-worker"}'
sleep 5
bs catalog/entities/by-name/component/default/sendungs-worker | jq '.status'

Expected:

null

Save your progress? Sign up for free

Checkpoint

cat > ~/backstage-lab/tag02/kontrollpunkt.sh <<'EOF'
#!/usr/bin/env bash
# kontrollpunkt.sh – checks the final state of Day 2 via the Backstage API (✔/✘)
source ~/backstage-lab/setup/env.sh
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
       else echo "✘ $1"; fail=$((fail+1)); fi; }
sys='system:default/sendungsverfolgung'
t "Domain logistik vorhanden" "bs catalog/entities/by-name/domain/default/logistik"
t "System liegt in Domain logistik" \
  "bs catalog/entities/by-name/system/default/sendungsverfolgung \
     | jq -e '.spec.domain == \"logistik\"'"
t "System hat 3 Components" \
  "bs 'catalog/entities?filter=kind=component,relations.partOf=$sys' \
     | jq -e 'length == 3'"
t "Resource sendungs-db (type database)" \
  "bs catalog/entities/by-name/resource/default/sendungs-db \
     | jq -e '.spec.type == \"database\"'"
t "Zwei Components hängen von sendungs-db ab" \
  "bs 'catalog/entities?filter=relations.dependsOn=resource:default/sendungs-db' \
     | jq -e 'length == 2'"
t "Keine Processing-Fehler im System" \
  "bs 'catalog/entities?filter=spec.system=sendungsverfolgung' \
     | jq -e '[.[] | select(.status.items)] | length == 0'"
exit "$fail"
EOF
bash ~/backstage-lab/tag02/kontrollpunkt.sh

Expected:

✔ Domain logistik vorhanden
✔ System liegt in Domain logistik
✔ System hat 3 Components
✔ Resource sendungs-db (type database)
✔ Zwei Components hängen von sendungs-db ab
✔ Keine Processing-Fehler im System

Challenge

The worker publishes “Sendung gescannt” (“shipment scanned”) events. Model them as the API sendungs-ereignisse (type asyncapi, part of the system), which the worker provides and tracking-web consumes.

Hint: spec.definition may also be written directly in the entity as a multi-line YAML string (|).

Solution

cd ~/backstage-lab/tag02/sv
cat >> catalog-info.yaml <<'EOF'
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: sendungs-ereignisse
  description: Ereignisse "Sendung gescannt" für Live-Updates
spec:
  type: asyncapi
  lifecycle: experimental
  owner: team-sendung
  system: sendungsverfolgung
  definition: |
    asyncapi: 3.0.0
    info:
      title: Sendungs-Ereignisse
      version: 1.0.0
    channels:
      sendungGescannt:
        address: sendungen.gescannt
EOF
sed -i '' 's/^    - resource:sendungs-db$/    - resource:sendungs-db\
  providesApis: [sendungs-ereignisse]/' catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "API sendungs-ereignisse"
git push -q origin main
cd ../tracking-web
sed -i '' 's/\[sendungs-api\]$/[sendungs-api, sendungs-ereignisse]/' \
  catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Ereignisse konsumieren"
git push -q origin main
for e in component:default/sendungs-worker component:default/tracking-web; do
  bs catalog/refresh -X POST -H 'Content-Type: application/json' \
    -d "{\"entityRef\":\"$e\"}"
done
sleep 10
bs catalog/entities/by-name/api/default/sendungs-ereignisse \
  | jq -r '.relations[] | "\(.type)\t\(.targetRef)"' | sort

Expected:

apiConsumedBy   component:default/tracking-web
apiProvidedBy   component:default/sendungs-worker
ownedBy         group:default/team-sendung
partOf          system:default/sendungsverfolgung

The checkpoint stays green: an API does not count toward the three components.

Save your progress? Sign up for free

Enterprise Note

  • Define the model up front: which domains, which spec.type values (service, website, library, database …), which lifecycles – otherwise spellings proliferate. Custom validation is done with a catalog processor as a backend module.
  • Set catalog.rules deliberately: teams are usually allowed to register Component/API/Resource, while the platform maintains Domains and Systems in a repo of its own.
  • Use namespaces (metadata.namespace) only for real tenant separation; every reference outside default must then be fully qualified.
  • Actively monitor processing errors: send log lines from catalog-backend-module-logs to central logging, alert on catalog warn; more on this on Day 14.
  • Give your own labels and annotations a company prefix (kranich.de/…) so they don’t collide with backstage.io/….