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) andtracking-webare registered via their Forgejo URLs. - Every entity has four parts:
apiVersion,kind,metadata,spec. - References are written as an entity reference
kind:namespace/name; fromspecfields 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:
- Open Register Existing Component in the sidebar.
- Under URL enter:
http://127.0.0.1:3300/kranich/sendungsverfolgung/src/branch/main/catalog-info.yaml - Click ANALYZE.
Expected: a red error message instead of the preview, as in the figure.
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 …withoutdryRun) 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 restartExpected:
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
- Open Register Existing Component again, enter the same URL, ANALYZE.
- In the Review step, check the list.
- 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.
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.
| 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 --onelineExpected:
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
- 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.
The yellow warning “relations to other entities, which can’t be
found” is intended: the group team-sendung is only created
on Day 4.
- In the About card under DOMAIN, click Logistik.
Expected: the domain page with Has systems as in the figure.
- Under Has systems click Sendungsverfolgung, then under Has resources click sendungs-db; in its Relations card click View graph.
- 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.
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)"' | sortExpected:
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 mainCheck 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; doneExpected (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 mainAn 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.
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.shExpected:
✔ 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)"' | sortExpected:
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.typevalues (service,website,library,database…), which lifecycles – otherwise spellings proliferate. Custom validation is done with a catalog processor as a backend module. - Set
catalog.rulesdeliberately: 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 outsidedefaultmust then be fully qualified. - Actively monitor processing errors: send log lines from
catalog-backend-module-logsto central logging, alert oncatalog warn; more on this on Day 14. - Give your own labels and annotations a company prefix
(
kranich.de/…) so they don’t collide withbackstage.io/….