Zum Inhalt springen
Trainingslager IT-Trainingslager

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) und tracking-web sind über ihre Forgejo-URLs registriert.
  • Jede Entity hat vier Teile: apiVersion, kind, metadata, spec.
  • Verweise schreibt man als Entity-Referenz kind:namespace/name; aus spec-Feldern macht der Katalog Relationen in beide Richtungen.
  • Heute entsteht das Repo kranich/sendungsverfolgung mit 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:

  1. In der Seitenleiste Register Existing Component öffnen.
  2. Bei URL eintragen: http://127.0.0.1:3300/kranich/sendungsverfolgung/src/branch/main/catalog-info.yaml
  3. ANALYZE klicken.

Erwartet: eine rote Fehlermeldung statt der Vorschau wie in der Abbildung.

Der Import scheitert an der Domain

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 … ohne dryRun) 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 restart

Erwartet:

✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
  1. Register Existing Component erneut öffnen, dieselbe URL eintragen, ANALYZE.
  2. Im Schritt Review die Liste prüfen.
  3. 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.

Review-Schritt mit fünf Entities aus einer Datei

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.

About-, Links- und Labels-Karte des Workers
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 --oneline

Erwartet:

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

  1. 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.

System-Seite mit Components, Resource und Relations-Diagramm

Die gelbe Warnung „relations to other entities, which can’t be found” ist gewollt: Die Gruppe team-sendung entsteht erst an Tag 4.

  1. In der About-Karte unter DOMAIN auf Logistik klicken.

Erwartet: die Domain-Seite mit Has systems wie in der Abbildung.

Domain-Seite mit dem System Sendungsverfolgung
  1. Unter Has systems auf Sendungsverfolgung klicken, dann unter Has resources auf sendungs-db; in dessen Karte Relations auf View graph klicken.
  2. 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.

Catalog Graph um sendungs-db mit gefilterten Relationen

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)"' | sort

Erwartet:

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 main

Prü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; done

Erwartet (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 main

Gefä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.

Fehlerkarte auf der Entity-Seite nach kaputtem Push

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.sh

Erwartet:

✔ 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)"' | sort

Erwartet:

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.rules bewusst 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 von default muss dann voll qualifiziert sein.
  • Processing-Fehler aktiv überwachen: Log-Zeilen aus catalog-backend-module-logs ins zentrale Logging, Alarm auf catalog warn; vertiefend an Tag 14.
  • Eigene Labels und Annotations mit Firmen-Präfix (kranich.de/…) versehen, damit sie nicht mit backstage.io/… kollidieren.