Tag 2: Das Datenmodell
Ziel: Die Sendungsverfolgung als Domain, System, Resource und Components modellieren und Fehler im Katalog sicher finden · Dauer: ca. 90 min · Voraussetzung: Tag 1
Briefing
- Vorausgesetzt (Ende Tag 1): Lab läuft,
sendungs-api(Component + API) undtracking-websind über ihre Forgejo-URLs registriert. - Jede Entity hat vier Teile:
apiVersion,kind,metadata,spec. - Verweise schreibt man als Entity-Referenz
kind:namespace/name; ausspec-Feldern macht der Katalog Relationen in beide Richtungen. - Heute entsteht das Repo
kranich/sendungsverfolgungmit Domain, System, Resource und einem Worker. - Zum Schluss baust du absichtlich kaputte Dateien und lernst, wo Backstage die Fehler zeigt.
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: Anatomie einer Entity
Hol dir die Component sendungs-api so, wie der Katalog
sie gespeichert hat:
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}'Erwartet:
{
"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" }
]
}
Warum? In der YAML-Datei steht nur owner: team-sendung.
Der Katalog ergänzt Namespace (default) und Kind (bei
owner ist das group) und speichert das
Ergebnis als vollständige Referenz
group:default/team-sendung. uid,
etag und relations vergibt der Katalog selbst
– die schreibst du nie in eine Datei.
Die Annotations zeigen, woher die Entity stammt:
bs catalog/entities/by-name/component/default/sendungs-api \
| jq '.metadata.annotations | keys'Erwartet:
[
"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"
]
Nur techdocs-ref stammt aus der Datei; die übrigen setzt
der Katalog beim Einlesen (daraus entstehen View Source
und der Stift-Button in der About-Karte).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Ein neues Repo mit vier Entities
Eine Datei darf mehrere Entities enthalten, getrennt durch
---. Leg das Repo kranich/sendungsverfolgung
an:
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 .Erwartet:
✔ kranich/sendungsverfolgung angelegt (http://127.0.0.1:3300/kranich/sendungsv…)
Bei dependsOn steht ein Kind-Präfix
(resource:), weil das Feld auf Components und Resources
zeigen kann; bei system und domain ist der
Kind eindeutig.
Jetzt registrieren wie an Tag 1:
- In der Seitenleiste Register Existing Component öffnen.
- Bei URL eintragen:
http://127.0.0.1:3300/kranich/sendungsverfolgung/src/branch/main/catalog-info.yaml - ANALYZE klicken.
Erwartet: eine rote Fehlermeldung statt der Vorschau wie in der Abbildung.
Warum? app-config.yaml aus create-app
erlaubt nur
catalog.rules: [Component, System, API, Resource, Location].
Domain fehlt – die Regel prüft jede Entity, und schon eine verbotene
lässt den ganzen Import scheitern.
Achtung: Per API (
bs catalog/locations -X POST …ohnedryRun) wird die Location trotzdem angelegt, es erscheint aber keine einzige Entity. Den Grund findest du dann nur im Backend-Log (Drill 8).
Fortschritt speichern? Kostenlos registrieren
Drill 3: Domain erlauben und importieren
Hänge einen catalog-Block an die lokale Konfiguration an
(Listen ersetzen beim Zusammenführen der Config die Liste aus
app-config.yaml komplett):
cat >> ~/backstage-lab/portal/app-config.local.yaml <<'EOF'
catalog:
rules:
- allow: [Component, System, API, Resource, Location, Domain]
EOF
~/backstage-lab/setup/portal.sh restartErwartet:
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
- Register Existing Component erneut öffnen, dieselbe URL eintragen, ANALYZE.
- Im Schritt Review die Liste prüfen.
- IMPORT klicken, dann VIEW COMPONENT.
Erwartet: Im Review stehen fünf Entities – deine vier plus die generierte Location (der Hash im Namen hängt von der URL ab), wie in der Abbildung.
Mehr zu catalog.rules und Locations gibt es an Tag
3.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Metadaten, die man sieht
Öffne Catalog, stelle den Filter Kind auf Component und klicke Sendungs-Worker.
Erwartet: rechts die Karten About, Links und Labels wie in der Abbildung.
| Feld | Wirkung in der GUI |
|---|---|
metadata.title |
Anzeigename statt name (Überschrift, Tabellen) |
metadata.tags |
graue Chips, Filter Tags im Katalog |
metadata.labels |
Karte Labels, Schlüssel/Wert zum Selektieren |
metadata.links |
Karte Links mit Icon (dashboard,
docs, github, …) |
metadata.annotations |
steuern Plugins – hier erscheint der Tab Kubernetes |
Warum? Tags sind freie Schlagwörter (nur a-z0-9+#, mit
- verbunden), Labels sind Schlüssel/Wert-Paare zum
Selektieren, Annotations sind die Schnittstelle zu Plugins. Der Tab
Kubernetes bleibt bis Tag 10 leer.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Bestehende Repos ins System hängen
sendungs-api und tracking-web bekommen
spec.system; sendungs-api hängt zusätzlich an
der Datenbank, tracking-web an sendungs-api.
Klonen, Datei komplett ersetzen, pushen:
cd ~/backstage-lab/tag02
GIT=http://lab-admin:[email protected]:3300 # Lab-Wert!
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 --onelineErwartet:
bdef724 In System sendungsverfolgung einhängen
a6a1fbc Initialer Stand
Der Katalog liest die Dateien regelmäßig neu (im Lab nach ca. zwei Minuten). Nicht warten – Refresh per API anstoßen; er liest die Quelle der Entity neu:
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)"'Erwartet (Reihenfolge kann abweichen):
Component sendungs-worker
API sendungs-api
Resource sendungs-db
Component tracking-web
Component sendungs-api
Fortschritt speichern? Kostenlos registrieren
Drill 6: System, Domain und Catalog Graph
- In der About-Karte des Workers auf Sendungsverfolgung (unter SYSTEM) klicken.
Erwartet: die System-Seite mit Has components (drei Einträge), Has resources und der Karte Relations wie in der Abbildung.
Die gelbe Warnung „relations to other entities, which can’t be found”
ist gewollt: Die Gruppe team-sendung entsteht erst an Tag
4.
- In der About-Karte unter DOMAIN auf Logistik klicken.
Erwartet: die Domain-Seite mit Has systems wie in der Abbildung.
- Unter Has systems auf Sendungsverfolgung klicken, dann unter Has resources auf sendungs-db; in dessen Karte Relations auf View graph klicken.
- FILTERS öffnen: MAX DEPTH auf
2; bei RELATIONS alles entfernen außer dependsOn, dependencyOf, partOf, hasPart; Simplified ausschalten.
Erwartet: Graph um sendungs-db – drei Components hängen
direkt oder über sendungs-api an der Datenbank, wie in der
Abbildung.
Warum? Simplified zeigt nur Kanten in eine Richtung;
ausgeschaltet siehst du auch, wer auf die Datenbank zeigt
(dependencyOf). Die Filter landen in der URL – praktisch,
um eine Ansicht zu teilen.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Relationen per API
Jede spec-Referenz wird zu einem Relationspaar
(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)"' | sortErwartet:
dependencyOf component:default/sendungs-api
dependencyOf component:default/sendungs-worker
ownedBy group:default/team-sendung
partOf system:default/sendungsverfolgung
Relationen sind filterbar – „wer hängt an der Datenbank?“:
bs 'catalog/entities?filter=relations.dependsOn=resource:default/sendungs-db' \
| jq -c 'map(.metadata.name)'Erwartet:
["sendungs-worker","sendungs-api"]
Tipp: Im Filter muss die Referenz vollständig sein (
resource:default/…); die Kurzform aus der YAML-Datei findet nichts.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Fehler provozieren und finden
Klone das neue Repo und leg drei kaputte Dateien an – Leerzeichen im Namen, fehlender Owner, unbekannter Kind:
cd ~/backstage-lab/tag02
GIT=http://lab-admin:[email protected]:3300 # Lab-Wert!
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 mainPrüfe jede Datei mit einem Dry-Run – derselbe Aufruf, den
ANALYZE im GUI macht. bs nutzt
curl -f und verschluckt Fehlertexte, deshalb hier direkt
mit curl:
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; doneErwartet (umbrochen):
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
Warum? Großbuchstaben sind in metadata.name erlaubt, das
Leerzeichen nicht. Ein unbekannter Kind scheitert schon an
catalog.rules, bevor ein Schema geprüft wird. Spielwiese
wieder löschen:
git rm -q kaputt-*.yaml
git -c user.name="Lab Admin" -c [email protected] commit -qm "Spielwiese weg"
git push -q origin mainGefährlicher ist ein Fehler in einer Datei, die schon registriert ist. Entferne den Owner des Workers:
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"}'Erwartet:
catalog-info.yaml | 1 -
1 file changed, 1 deletion(-)
Öffne Sendungs-Worker im GUI (Seite neu laden).
Erwartet: Owner steht weiterhin auf team-sendung,
darunter eine rote Fehlerkarte wie in der Abbildung.
Warum? Scheitert die Verarbeitung, behält der Katalog den letzten gültigen Stand und hängt den Fehler an. Niemand merkt es, der nicht auf die Seite schaut – deshalb gibt es zwei weitere Wege:
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'Erwartet (Log gekürzt):
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/…"
Die Log-Zeile stammt von
@backstage/plugin-catalog-backend-module-logs, das
create-app bereits in
packages/backend/src/index.ts einbindet. Reparieren:
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'Erwartet:
null
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cat > ~/backstage-lab/tag02/kontrollpunkt.sh <<'EOF'
#!/usr/bin/env bash
# kontrollpunkt.sh – prüft den Endstand von Tag 2 per 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.shErwartet:
✔ 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
Der Worker veröffentlicht Ereignisse „Sendung gescannt”. Modelliere
sie als API sendungs-ereignisse (Typ asyncapi,
Teil des Systems), die der Worker bereitstellt und
tracking-web konsumiert.
Hinweis: spec.definition darf auch
direkt als mehrzeiliger YAML-String (|) in der Entity
stehen.
Lösung
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)"' | sortErwartet:
apiConsumedBy component:default/tracking-web
apiProvidedBy component:default/sendungs-worker
ownedBy group:default/team-sendung
partOf system:default/sendungsverfolgung
Der Kontrollpunkt bleibt grün: Eine API zählt nicht zu den drei Components.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Das Modell vorher festlegen: welche Domains, welche
spec.type-Werte (service,website,library,database…), welche Lifecycles – sonst wuchern Schreibweisen. Eigene Validierung geht über einen Catalog-Processor als Backend-Modul. catalog.rulesbewusst setzen: Teams dürfen meist Component/API/Resource registrieren, Domains und Systems pflegt die Plattform in einem eigenen Repo.- Namespaces (
metadata.namespace) nur für echte Mandantentrennung nutzen; jede Referenz außerhalb vondefaultmuss dann voll qualifiziert sein. - Processing-Fehler aktiv überwachen: Log-Zeilen aus
catalog-backend-module-logsins zentrale Logging, Alarm aufcatalog warn; vertiefend an Tag 14. - Eigene Labels und Annotations mit Firmen-Präfix
(
kranich.de/…) versehen, damit sie nicht mitbackstage.io/…kollidieren.