Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Erster Rundgang

Ziel: Du findest dich im Portal zurecht, registrierst die ersten Forgejo-Repos im Software Catalog und liest dieselben Daten per API. · Dauer: ca. 90 min · Voraussetzung: Tag 0

Briefing

  • Der Software Catalog ist das Herz von Backstage: Jede Entity (Component, API, Group …) stammt aus einer YAML-Datei, meist catalog-info.yaml im Repo.
  • Eine Location zeigt auf so eine Datei. Backstage liest sie, verarbeitet die Entities und frischt sie periodisch auf.
  • Alles, was die Oberfläche zeigt, liefert die Katalog-API unter /api/catalog.
Forgejo-Repo                  Backstage-Backend                    Frontend
catalog-info.yaml ─► Location ─► Processing ─► Entities ─► /api/catalog ─► Katalogseite
        ▲                           │ alle ~2 min oder per Refresh
        └───────────────────────────┘

Drill 1: Gast-Login, Sidebar und Filter

Ausgangslage ist das Ende von Tag 0: Forgejo läuft, die Org kranich ist befüllt, app-config.local.yaml ist angelegt und das Portal gestartet.

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
~/backstage-lab/setup/check.sh | tail -3

Erwartet:

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
✔ Backend bereit (http://localhost:7007)
✔ Frontend erreichbar (http://localhost:3000)
✔ Katalog-API mit Lab-Token
  1. Öffne http://localhost:3000 und klicke beim Guest-Provider auf Enter.
  2. Klicke unten in der Sidebar auf Settings. Unter Profile steht user:development/guest – das ist deine Identität bis Tag 12.
  3. Fahre die Sidebar von oben nach unten ab.
Eintrag Pfad Wofür
Home /home Startseite mit Widgets (ab Tag 9 auf /)
Catalog / Software Catalog – hier die Startseite
Create /create Software Templates (Tag 5)
APIs /api-docs alle API-Entities
Catalog Graph /catalog-graph Beziehungen als Graph
Docs /docs TechDocs (Tag 7)
Register Existing Component /catalog-import Location registrieren
Visualizer /visualizer Extension-Baum (ab Tag 9 „App-Struktur“)

Der Katalog liegt auf /, weil app-config.yaml die Extension page:catalog mit path: / konfiguriert. http://localhost:3000/catalog allein liefert deshalb 404, Entity-Seiten liegen trotzdem unter /catalog/<namespace>/<kind>/<name>.

Jetzt die Filter links auf der Katalogseite:

  1. Klicke auf Catalog. Erwartet: die Katalogseite wie in der Abbildung, mit Kind Component und genau einer Beispiel-Component example-website.
  2. Stelle Kind auf API – es erscheint example-grpc-api. Probiere Template, Group und User, dann zurück auf Component.
  3. Wähle unter Lifecycle den Wert experimental, unter Owner den Wert guests. Beobachte die Adresszeile.
Katalogseite mit Filterleiste und der Beispiel-Component

Erwartet: „All Components (1)” und in der Adresszeile (dekodiert, umbrochen):

/?filters[kind]=component&filters[owners]=group:default/guests
  &filters[lifecycles]=experimental&filters[user]=all&limit=20

Warum? Jeder Filter landet in der URL – gefilterte Ansichten lassen sich als Link weitergeben. Die Beispieldaten stammen aus examples/ (statische catalog.locations in app-config.yaml, Tag 3).

Fortschritt speichern? Kostenlos registrieren

Drill 2: Register Existing Component

Die Datei catalog-info.yaml in kranich/sendungs-api beschreibt eine Component und eine API. Im GUI registrierst du sie mit der Forgejo-URL der Datei (…/src/branch/main/… ist das Forgejo-Gegenstück zu GitHubs …/blob/main/…).

  1. Klicke in der Sidebar auf Register Existing Component.
  2. Trage bei URL ein: http://127.0.0.1:3300/kranich/sendungs-api/src/branch/main/catalog-info.yaml
Schritt Select URL mit der Forgejo-URL der catalog-info.yaml
  1. Klicke auf ANALYZE. Erwartet: Schritt Review listet die Location und drei Entities – API sendungs-api, Component sendungs-api und eine Location generated-….
Review-Schritt mit den drei gefundenen Entities
  1. Klicke auf IMPORT. Erwartet: Schritt Finish mit VIEW COMPONENT und REGISTER ANOTHER.
Finish-Schritt nach dem Import

Warum funktioniert das ohne Plugin? Backstage liest die Datei über die integrations.gitea-Einträge aus app-config.local.yaml mit dem Token von backstage-bot. Der Hinweis „GitHub only” rechts betrifft nur die Repository-Variante (ganzes Repo durchsuchen und bei Bedarf einen Pull Request anlegen) – für Forgejo gibst du immer die vollständige Datei-URL an.

Achtung: VIEW COMPONENT springt zur ersten Entity der Datei – hier zur API sendungs-api, nicht zur Component. Achte oben auf API • openapi.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die Entity-Seite

  1. Klicke in der Sidebar auf Catalog und dann in der Tabelle auf sendungs-api.
  2. Erwartet: die Entity-Seite wie in der Abbildung – Kopf mit Component • service, Lifecycle und Owner, darunter die Tabs Overview, TechDocs und APIs.
Entity-Seite der Component sendungs-api mit Warnung und About-Karte

Die Teile der Seite:

  • About-Karte: Beschreibung, Owner, System, Tags, Kind, Type, Lifecycle aus der YAML-Datei. VIEW SOURCE öffnet das Repo in Forgejo, der Kreispfeil plant einen Refresh (Drill 8), der Stift (Edit Metadata) öffnet catalog-info.yaml im Forgejo-Editor.
  • Provided APIs: die Relation providesApis: [sendungs-api] als Tabelle.
  • Relations (weiter unten): dieselben Beziehungen als Mini-Graph.
  • Tab APIs: Provided und Consumed APIs auf einer eigenen Seite. Tab TechDocs bauen wir an Tag 7 auf.

Die gelbe Warnung „This entity has relations to other entities, which can’t be found in the catalog. Entities not found are: group:default/team-sendung” ist gewollt: owner: team-sendung verweist auf eine Group, die es noch nicht gibt. Die Gruppen legst du an Tag 4 an – dann verschwindet die Warnung.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Die API-Seite mit OpenAPI

  1. Klicke in der Karte Provided APIs auf sendungs-api (Puzzle-Symbol).
  2. Klicke auf den Tab Documentation und im Menü auf Definition.
  3. Erwartet: die OpenAPI-Ansicht wie in der Abbildung, mit dem Endpunkt GET /sendungen/{id}. Der Untertab Raw zeigt die rohe YAML.
Definition der API sendungs-api als OpenAPI-Ansicht

Warum steht die Spezifikation im Katalog? In catalog-info.yaml steht definition: { $text: ./openapi.yaml } – der Katalog lädt die Datei relativ zur Location nach und speichert sie in spec.definition. Die Ansicht Overview zeigt dieselbe Definition plus Consumers und Providers. Alle APIs auf einen Blick liefert APIs in der Sidebar.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Zweite Component per API registrieren

Was IMPORT im GUI tut, ist ein einziger API-Aufruf. tracking-web registrierst du so mit dem Lab-Token (bs aus env.sh):

URL=$FORGEJO/kranich/tracking-web/src/branch/main/catalog-info.yaml
bs catalog/locations -X POST -H 'Content-Type: application/json' \
  -d "{\"type\":\"url\",\"target\":\"$URL\"}" \
  | jq '{location: .location.entityRef, entities}'

Erwartet (Hash abweichend):

{
  "location": "location:default/generated-db94e7dc525bf019d6d06a7c893a31005721c2c9",
  "entities": []
}

entities ist leer, weil die Verarbeitung asynchron läuft. Ein paar Sekunden später:

bs 'catalog/entities?filter=kind=component' | jq -r '.[].metadata.name' | sort
bs catalog/locations | jq -r '.[].data.target'

Erwartet:

example-website
sendungs-api
tracking-web
http://127.0.0.1:3300/kranich/sendungs-api/src/branch/main/catalog-info.yaml
http://127.0.0.1:3300/kranich/tracking-web/src/branch/main/catalog-info.yaml

Tipp: Mit ?dryRun=true an catalog/locations prüft Backstage die Datei, ohne etwas anzulegen – praktisch in CI-Pipelines.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Catalog Graph und Favoriten

tracking-web deklariert consumesApis: [sendungs-api]. Den Zusammenhang zeigt der Catalog Graph:

  1. Öffne die Entity-Seite der Component sendungs-api und klicke in der Karte Relations auf View graph.
  2. Die Graph-Seite öffnet sich mit MAX DEPTH 1 – nur die API ist zu sehen. Setze MAX DEPTH auf 2.
  3. Erwartet: drei Knoten wie in der Abbildung. Die Root-Entity ist rot hervorgehoben.
Catalog Graph mit tracking-web, der API und der Component sendungs-api

Ein Klick auf einen Knoten macht ihn zur neuen Wurzel, Shift-Klick öffnet seine Entity-Seite. Jetzt der Favorit:

  1. Gehe zurück zur Component sendungs-api und klicke oben rechts auf den Stern (Add to favorites).
  2. Klicke auf Catalog und links unter PERSONAL auf Starred.
  3. Erwartet: „Starred Components (1)” wie in der Abbildung.
Katalog mit aktivem Starred-Filter

Warum? Sterne sind persönliche Einstellungen der Identität user:development/guest. Das Backend-Plugin user-settings speichert sie in data/user-settings.sqlite – sie überleben also Browserwechsel und Neustarts. Owned bleibt bei 0, weil der Gast keine Gruppe besitzt – das ändert Tag 4.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Dieselben Daten per API

Filter in der URL entsprechen der Katalog-API. Innerhalb eines filter gilt UND (Komma), mehrere filter-Parameter verknüpft die API mit ODER.

F='fields=metadata.name,spec.owner'
bs "catalog/entities?filter=kind=component,spec.lifecycle=production&$F" | jq -c '.[]'
bs 'catalog/entities?filter=kind=api&filter=spec.type=website' \
  | jq -r '.[] | "\(.kind) \(.metadata.name)"'

Erwartet:

{"metadata":{"name":"sendungs-api"},"spec":{"owner":"team-sendung"}}
{"metadata":{"name":"tracking-web"},"spec":{"owner":"team-web"}}
API example-grpc-api
API sendungs-api
Component tracking-web
Component example-website

Eine einzelne Entity holst du über die Entity-Referenz kind/namespace/name:

bs catalog/entities/by-name/component/default/sendungs-api | jq '{
  description: .metadata.description,
  relations: [.relations[] | "\(.type) -> \(.targetRef)"] }'

Erwartet:

{
  "description": "REST-API für den Sendungsstatus",
  "relations": [
    "ownedBy -> group:default/team-sendung",
    "providesApi -> api:default/sendungs-api"
  ]
}

Die Zähler der Filterleiste liefern die Facetten:

bs 'catalog/entity-facets?facet=kind' | jq -c '.facets.kind[] | [.value, .count]'

Erwartet:

["API",2]
["Component",3]
["Group",1]
["Location",5]
["System",1]
["Template",1]
["User",1]

Fünf Locations: drei aus app-config.yaml, zwei von dir registriert. Mit facet=spec.owner oder facet=metadata.tags bekommst du die Werte der übrigen Filter.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Refresh im GUI und per API

Backstage liest jede Location ungefähr alle zwei Minuten neu. Schneller geht es mit einem Refresh. Zuerst eine Änderung in Forgejo:

mkdir -p ~/backstage-lab/tag01 && cd ~/backstage-lab/tag01
git clone -q http://lab-admin:[email protected]:3300/kranich/sendungs-api.git
cd sendungs-api
sed -i '' \
  's/REST-API für den Sendungsstatus/REST-API für Sendungsstatus und Zustellprognose/' \
  catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Beschreibung erweitert" && git push -q origin main
bs catalog/entities/by-name/component/default/sendungs-api | jq -r .metadata.description

Erwartet – der Katalog kennt noch den alten Stand:

REST-API für den Sendungsstatus
  1. Öffne die Component sendungs-api.
  2. Klicke in der About-Karte auf den Kreispfeil (Schedule entity refresh). Erwartet: die Meldung „Refresh scheduled”.
  3. Lade die Seite nach ein paar Sekunden neu. Erwartet: DESCRIPTION zeigt „REST-API für Sendungsstatus und Zustellprognose”.

Dasselbe per API, diesmal mit einem neuen Tag für tracking-web:

cd ~/backstage-lab/tag01
git clone -q http://lab-admin:[email protected]:3300/kranich/tracking-web.git
cd tracking-web
sed -i '' 's/tags: \[web\]/tags: [web, kunde]/' catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Tag kunde" && git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
  -d '{"entityRef":"component:default/tracking-web"}' -w '%{http_code}\n'
sleep 3
bs catalog/entities/by-name/component/default/tracking-web | jq -c .metadata.tags

Erwartet:

200
["web","kunde"]

Warum? Refresh setzt die Entity in der Verarbeitungsschlange nach vorn. Backstage liest dabei die Quelldatei neu. Das Repo selbst ist die Wahrheit – Änderungen im GUI gibt es im Katalog nicht.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cat > ~/backstage-lab/tag01/kontrolle.sh <<'EOF'
#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 1 (✔/✘). Exit-Code = Anzahl Fehler.
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; }
e() { bs "catalog/entities/by-name/$1"; }

t "Component sendungs-api im Katalog" "e component/default/sendungs-api"
t "API sendungs-api im Katalog" "e api/default/sendungs-api"
t "Component tracking-web im Katalog" "e component/default/tracking-web"
t "tracking-web konsumiert die API" \
  "e component/default/tracking-web | jq -e '.relations[] |
     select(.type==\"consumesApi\" and .targetRef==\"api:default/sendungs-api\")'"
t "Neue Beschreibung angekommen (Refresh)" \
  "e component/default/sendungs-api | jq -e '.metadata.description | test(\"Zustell\")'"
t "Zwei Forgejo-Locations registriert" \
  "[ \$(bs catalog/locations | jq '[.[].data.target | select(test(\"/kranich/\"))]
     | length') -ge 2 ]"
exit "$fail"
EOF
bash ~/backstage-lab/tag01/kontrolle.sh

Erwartet:

✔ Component sendungs-api im Katalog
✔ API sendungs-api im Katalog
✔ Component tracking-web im Katalog
✔ tracking-web konsumiert die API
✔ Neue Beschreibung angekommen (Refresh)
✔ Zwei Forgejo-Locations registriert

Challenge

Lege aus ~/backstage-lab/code/tag01/zustell-worker das Repo kranich/zustell-worker an, registriere es per Register Existing Component im GUI und finde danach per API alle Components mit Lifecycle experimental.

Hinweis: mkrepo.sh aus setup/ legt das Repo an, der Filter kombiniert kind und spec.lifecycle mit Komma.

Lösung

~/backstage-lab/setup/mkrepo.sh kranich/zustell-worker \
  ~/backstage-lab/code/tag01/zustell-worker

Erwartet:

✔ kranich/zustell-worker angelegt (http://127.0.0.1:3300/kranich/zustell-worker)

Im GUI: Register Existing Component → URL http://127.0.0.1:3300/kranich/zustell-worker/src/branch/main/catalog-info.yaml → ANALYZE → IMPORT. Der Review-Schritt zeigt „Entities: 2” (Component und Location). Dann:

F='fields=metadata.name,spec.owner'
bs "catalog/entities?filter=kind=component,spec.lifecycle=experimental&$F" | jq -c '.[]'

Erwartet:

{"metadata":{"name":"zustell-worker"},"spec":{"owner":"team-sendung"}}
{"metadata":{"name":"example-website"},"spec":{"owner":"guests"}}

Im GUI liefert Lifecycle experimental dieselben zwei Zeilen. Im Catalog Graph der API hängt zustell-worker nun als zweiter Consumer.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • „Register Existing Component” ist für Einzelfälle gedacht. In Produktion entdecken Entity-Provider alle Repos einer Org automatisch (Gitea-Provider an Tag 3, bei GitHub/GitLab die jeweiligen Discovery-Module).
  • Wer im GUI registrieren darf, regeln Berechtigungen (catalog.location.create, Tag 12). Sonst kann jeder beliebige URLs einlesen lassen.
  • Die Integration braucht nur Lesezugriff. Für den Katalog reicht ein Token mit read:repository. Schreibrechte braucht erst der Scaffolder.
  • Datei-URLs anderer Plattformen: GitHub …/<org>/<repo>/blob/main/catalog-info.yaml, GitLab …/<gruppe>/<repo>/-/blob/main/catalog-info.yaml. Die Repository-Variante mit automatischem Pull Request bietet der Wizard nur für GitHub an.
  • Der Refresh-Takt (catalog.processingInterval) und API-Rate-Limits der Git-Plattform hängen zusammen. Bei Tausenden Repos lieber Webhooks/Events nutzen statt kurzer Intervalle.