Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Fehlersuche und Upgrades

Ziel: Du findest typische Backstage-Fehler systematisch über Log, API und DevTools, reparierst sie und hebst das Portal kontrolliert auf eine neue Version. · Dauer: ca. 120 min · Voraussetzung: Tag 13

Briefing

  • Fehler zeigen sich selten dort, wo sie entstehen: Ein abgelaufenes Token wird zur roten Karte an einer Location, ein CORS-Fehler zur falschen Meldung beim Login.
  • Vorgehen: Symptom einer Ebene zuordnen, dann das passende Werkzeug nehmen.
  • Viele Werkzeuge kennst du schon (Tag 2, 3, 5, 10). Heute kommen Log-Level, backstage-cli config:*, DevTools und Unprocessed Entities dazu.
  • Ausgangslage: Ende von Tag 13. Du arbeitest wieder im Entwicklungsmodus mit portal.sh (Ports 3000/7007, PostgreSQL in bs-postgres, vorher docker start bs-postgres) und meldest dich wie gewohnt an.
 Symptom                          Ebene              Werkzeug
 Seite leer, Login scheitert ───► Frontend↔Backend   Browser-Konsole, curl -H Origin
 Portal startet nicht ──────────► Konfiguration      config:check, portal.sh logs
 Entity alt, rote Karte ────────► Katalog            status.items, Inspect, Log
 Entity fehlt ganz ─────────────► Katalog            Unprocessed, Log
 401/403/„not allowed" ─────────► Integration        Dry-Run, Token gegen Forgejo
 Task rot ──────────────────────► Scaffolder         Task-Log, tasks/<id>/events

Drill 1: Lagebild in einer Minute

Bevor du einen Fehler jagst, prüfst du, ob die Grundlage stimmt: läuft alles, und welche Warnungen sind normales Grundrauschen?

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
curl -s $BACKSTAGE/.backstage/health/v1/readiness | jq -c .
curl -s $BACKSTAGE/.backstage/health/v1/liveness | jq -c .
~/backstage-lab/setup/portal.sh logs 2000 | sed 's/\x1b\[[0-9;]*m//g' \
  | awk '$3=="warn" || $3=="error" {print $2, $3}' | sort | uniq -c | sort -rn

Erwartet (gekürzt, die Zahlen weichen ab):

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{"status":"ok"}
{"status":"ok"}
   7 catalog warn
   2 search warn
   1 signals warn

Spalte 2 der Log-Zeile ist das Plugin, Spalte 3 der Level. Was steckt dahinter?

~/backstage-lab/setup/portal.sh logs 2000 | sed 's/\x1b\[[0-9;]*m//g' \
  | grep -E ' (warn|error) ' | cut -c26-110 | sort -u

Erwartet (gekürzt):

catalog warn Event subscribe request failed with status 404, events backend not f…
catalog warn Repo http://127.0.0.1:3300/kranich/katalog does not contain a catalo…
catalog warn Repo http://127.0.0.1:3300/kranich/org does not contain a catalog-in…
catalog warn Repo http://127.0.0.1:3300/kranich/templates does not contain a cata…
search warn Index for techdocs was not created: indexer received 0 documents docu…
signals warn Event subscribe request failed with status 404, events backend not f…

Das ist das Grundrauschen deines Labs: kein Events-Backend, drei Repos ohne catalog-info.yaml (gewollt, Tag 3 bis 5) und ein noch leerer TechDocs-Index. Merke dir diese Liste – alles, was neu dazukommt, ist verdächtig. Für Fehlerberichte liefert die CLI die Versionen:

cd ~/backstage-lab/portal
yarn backstage-cli info | head -6

Erwartet:

OS:   Darwin 24.6.0 - darwin/arm64
node: v24.21.0
yarn: 4.13.0
cli:  0.36.6 (installed)
info module: 0.1.4
backstage:   1.55.0

Den Rest des Werkzeugkastens kennst du schon:

Symptom Werkzeug eingeführt
Entity zeigt alten Stand, rote Karte status.items, Fehlerkarte Tag 2, Tag 3
Woher kommt diese Entity? Inspect entity → Ancestry Tag 3
Entity abgelehnt (allowed kind) Backend-Log Tag 3, Tag 4
Verwaist oder doppelt Orphan-Filter, conflicting entityRef Tag 3
Task schlägt fehl Task-Seite mit Log Tag 5
Plugin-Tab meldet 403/404 Backend-Konfiguration, RBAC Tag 10

Fortschritt speichern? Kostenlos registrieren

Drill 2: Log-Level gezielt erhöhen

Der Root-Logger aus @backstage/backend-defaults liest LOG_LEVEL aus der Umgebung (error, warn, info, debug). Für einen Lauf:

LOG_LEVEL=debug ~/backstage-lab/setup/portal.sh restart
sleep 45
~/backstage-lab/setup/portal.sh logs 5000 | sed 's/\x1b\[[0-9;]*m//g' \
  | awk '$3=="debug" {print $2}' | sort | uniq -c | sort -rn | head -4

Erwartet (Zahlen weichen ab):

  86 catalog
   6 backstage
   5 search
   4 scaffolder

Schon nach 45 Sekunden kommen fast hundert Zeilen zusammen, die meisten vom Katalog. Gezielter geht es mit backend.logger.overrides: Ein Override gilt nur für Log-Einträge, deren Felder zu matchers passen (Wert oder Regex in /…/). Zuerst ohne Debug neu starten, dann den Override setzen:

~/backstage-lab/setup/portal.sh restart
cd ~/backstage-lab/portal
yq -i '.backend.logger.overrides =
  [{"matchers": {"plugin": "catalog"}, "level": "debug"}]' app-config.local.yaml
sleep 30
~/backstage-lab/setup/portal.sh logs 300 | sed 's/\x1b\[[0-9;]*m//g' \
  | grep ' debug ' | tail -3 | cut -c26-100

Erwartet:

catalog debug Processing location:default/kranich-extern
catalog debug Processing user:default/chris.dietz
catalog debug Processing user:default/thomas.zachmann

Warum ohne Neustart? Der Logger abonniert Konfigurationsänderungen und übernimmt Overrides im laufenden Betrieb – auch in Produktion ein Weg, Debug für ein Plugin kurz einzuschalten. yq ändert die Datei gezielt, ohne einen zweiten backend:-Block zu erzeugen. Wieder ausschalten:

yq -i 'del(.backend.logger)' app-config.local.yaml

Sicherheit: Der Logger ersetzt alle Werte aus der Konfiguration, die als Secret markiert sind (Tokens, Passwörter), durch ***. Werte, die nicht aus der Konfiguration stammen, schützt das nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Konfiguration prüfen, bevor du neu startest

backstage-cli lädt dieselben Dateien wie das Backend und prüft sie gegen die Schemas aller installierten Pakete:

cd ~/backstage-lab/portal
yarn backstage-cli config:check && echo "✔ config ok"
yarn backstage-cli config:print 2>/dev/null | yq '.integrations.gitea'

Erwartet:

Loaded config from app-config.yaml, app-config.local.yaml
✔ config ok
- host: 127.0.0.1:3300
  baseUrl: http://127.0.0.1:3300
  username: <secret>
  password: <secret>

config:print maskiert alles, was ein Schema mit visibility: secret markiert. Mit --with-secrets siehst du Klartext – nie in ein Ticket kopieren. Woher weiß die CLI, was geheim ist? Aus dem zusammengeführten Schema:

mkdir -p ~/backstage-lab/tag14
S=~/backstage-lab/tag14/schema.json
yarn backstage-cli config:schema --merge --format json > $S
jq '.properties.integrations.properties.gitea.items.properties.password' $S

Erwartet (gekürzt):

{
  "type": "string",
  "description": "Gitea password used to authenticate requests. This can be ...",
  "visibility": "secret"
}

Tipp: Leite config:schema immer in eine Datei um. Direkt in eine Pipe geschrieben, bricht die Ausgabe nach 64 KiB ab, und jq meldet Unfinished JSON.

Eine fehlende Umgebungsvariable ist der stillste Fehler von allen:

env -u FORGEJO_TOKEN yarn backstage-cli config:print 2>/dev/null \
  | yq '.integrations.gitea'
env -u FORGEJO_TOKEN yarn backstage-cli config:check && echo "✔ trotzdem ok"

Erwartet:

- host: 127.0.0.1:3300
  baseUrl: http://127.0.0.1:3300
  username: <secret>
✔ trotzdem ok

Ist ${FORGEJO_TOKEN} leer oder falsch geschrieben, fällt password einfach weg. Backstage liest öffentliche Repos dann anonym weiter, private nicht mehr. Jetzt ein YAML-Fehler, wie ihn eine verrutschte Einrückung erzeugt:

sed -i '' 's/^  database:/   database:/' app-config.local.yaml
yarn backstage-cli config:check; echo "exit=$?"

Erwartet (die Zeilennummer weicht ab):

YAMLParseError: All mapping items must start at the same column at line 18, column 1:

          subject: lab-cli
   database:
^

exit=1

Hättest du stattdessen portal.sh restart aufgerufen, stünde derselbe Fehler im Log: yarn start beendet sich, portal.sh bemerkt das nach wenigen Sekunden und meldet ✘ Start fehlgeschlagen – siehe: tail -50 …/portal.log. Dann portal.sh logs 30. Reparieren:

sed -i '' 's/^   database:/  database:/' app-config.local.yaml
yarn backstage-cli config:check && echo "✔ config ok"

Erwartet:

Loaded config from app-config.yaml, app-config.local.yaml
✔ config ok

Warum? Merke dir die Reihenfolge ändern → config:check → portal.sh restart. Tippfehler in Schlüsselnamen findet config:check nur mit --strict (Challenge).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Integrationen – 401 und fehlender Host

Das Bot-Token läuft ab oder wird in Forgejo widerrufen. Du simulierst das mit einem falschen Wert:

sed -i '' 's/password: ${FORGEJO_TOKEN}/password: abgelaufen-0000/' \
  app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
sleep 40
bs 'catalog/entities?fields=kind,metadata.name,status' \
  | jq -r '.[] | .status.items[]?.message' | grep -o '[0-9]\{3\} [A-Z][a-z]*' \
  | sort | uniq -c
~/backstage-lab/setup/portal.sh logs 600 | sed 's/\x1b\[[0-9;]*m//g' \
  | grep 'gitea-provider.*failed' | cut -c26-124

Erwartet:

  12 401 Unauthorized
catalog error gitea-provider:kranich refresh failed, Error: Failed to list Gitea p…

Die Components zeigen weiter ihren letzten guten Stand. Die Fehler hängen an den Locations, die die Dateien lesen. Im Browser http://localhost:3000/catalog/default/location/kranich-extern öffnen.

Erwartet: zwei rote Karten mit 401 Unauthorized wie in der Abbildung.

Location kranich-extern mit 401-Fehlern beim Lesen aus Forgejo

Ist es das Token oder Forgejo? Frag Forgejo direkt mit beiden Werten:

for t in abgelaufen-0000 "$FORGEJO_TOKEN"; do
  curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: token $t" \
    $FORGEJO/api/v1/user
done

Erwartet:

401
200

Fix: Token zurück, neu starten, warten, bis keine Entity mehr Fehler trägt.

sed -i '' 's/password: abgelaufen-0000/password: ${FORGEJO_TOKEN}/' \
  app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
until [ "$(bs 'catalog/entities?fields=status' \
  | jq '[.[] | select(.status.items)] | length')" = 0 ]; do sleep 5; done
echo "✔ keine Fehler mehr"

Erwartet:

✔ keine Fehler mehr

Zweites Fehlerbild: jemand registriert eine URL mit localhost statt 127.0.0.1. Für Backstage ist das ein anderer Host – ohne Integration. Der Dry-Run zeigt es (direkt mit curl, weil bs Fehlertexte verschluckt):

for h in localhost:3300 127.0.0.1:3300; do
  curl -s -X POST "$BACKSTAGE/api/catalog/locations?dryRun=true" \
    -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
    -H 'Content-Type: application/json' -d "{\"type\": \"url\",
    \"target\": \"http://$h/kranich/zustell-app/src/branch/main/catalog-info.yaml\"}" \
    | jq -r '.error.message // "✔ \(.entities | length) Entities"' | cut -c1-120
done

Erwartet:

Error: Unable to read url, Reading from 'http://localhost:3300/kranich/zustell-app/s…
✔ 2 Entities

Die vollständige Meldung endet mit „You may need to configure an integration for the target host, or add it to the configured list of allowed hosts at ‘backend.reading.allow’“. Der Host in integrations.gitea[].host muss exakt zur URL passen, inklusive Port.

Fortschritt speichern? Kostenlos registrieren

Drill 5: DevTools und unverarbeitete Entities

Eine Entity, die nie erfolgreich verarbeitet wurde, hat keinen „letzten guten Stand” – sie fehlt einfach, status.items gibt es nicht. Solche Fälle zeigt das Modul catalog-backend-module-unprocessed, die Oberfläche dazu liefern DevTools:

~/backstage-lab/setup/portal.sh stop
cd ~/backstage-lab/portal
yarn --cwd packages/backend add @backstage/plugin-devtools-backend \
  @backstage/plugin-catalog-backend-module-unprocessed
yarn --cwd packages/app add @backstage/plugin-devtools \
  @backstage/plugin-catalog-unprocessed-entities
sed -i '' "/plugin-catalog-backend-module-gitea/a\\
backend.add(import('@backstage/plugin-catalog-backend-module-unprocessed'));\\
backend.add(import('@backstage/plugin-devtools-backend'));
" packages/backend/src/index.ts
yq -i '.devTools.scheduledTasks.plugins = ["catalog", "search"]' \
  app-config.local.yaml
grep -hE 'devtools|unprocessed' packages/*/package.json

Erwartet (gekürzt):

➤ YN0000: · Done with warnings in 12s 39ms
➤ YN0000: · Done with warnings in 5s 357ms
    "@backstage/plugin-catalog-unprocessed-entities": "^0.2.35",
    "@backstage/plugin-devtools": "^0.1.43",
    "@backstage/plugin-catalog-backend-module-unprocessed": "^0.6.16",
    "@backstage/plugin-devtools-backend": "^0.5.21",

Die Frontend-Pakete brauchen keinen Code: app.packages: all findet sie, und plugin-catalog-unprocessed-entities hängt sich als Reiter in page:devtools. Der Schlüssel devTools.scheduledTasks.plugins stammt aus dem config.schema.json von @backstage/plugin-devtools.

Achtung: DevTools prüft Permissions (devtools.info, devtools.config, devtools.scheduler.read, catalog.entities.unprocessed.read …). Lehnt deine Policy aus Tag 12 unbekannte Permissions ab, gib sie für plattform frei.

Jetzt ein Repo, dessen catalog-info.yaml keinen Owner hat:

~/backstage-lab/setup/portal.sh start
cat ~/backstage-lab/code/tag14/lieferschein/catalog-info.yaml | tail -4
~/backstage-lab/setup/mkrepo.sh kranich/lieferschein \
  ~/backstage-lab/code/tag14/lieferschein
sleep 75
bs catalog/entities/by-name/component/default/lieferschein-service \
  || echo "nicht im Katalog"
bs catalog/entities/unprocessed/pending | jq -r '.entities[]
  | "\(.unprocessed_entity.metadata.name)  \(.errors[0].cause.message)"'

Erwartet:

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
spec:
  type: service
  lifecycle: experimental
  system: sendungsverfolgung
✔ kranich/lieferschein angelegt (http://127.0.0.1:3300/kranich/lieferschein)
nicht im Katalog
lieferschein-service  /spec must have required property 'owner' - missingProperty: …

Der Gitea-Provider hat das Repo gefunden, die Location ist da, die Component scheitert an der Validierung. Im Browser:

  1. In der Sidebar auf DevTools klicken.
  2. Reiter Unprocessed Entities, dann Pending.

Erwartet: eine Zeile mit Kind Component, Owner unknown und leerer ENTITYREF.

Unprocessed Entities in den DevTools mit der Component ohne Owner
  1. In der Spalte RAW auf das Dokument-Symbol klicken.

Erwartet: Rohdaten und Fehlerliste wie in der Abbildung.

Rohdaten der unverarbeiteten Entity mit der Fehlermeldung

Warum Pending und nicht Failed? Pending heißt „noch nie im Katalog angekommen”, Failed heißt „war schon da, letzter Lauf ohne Ergebnis”. Schau in beide Reiter. Reparieren:

mkdir -p ~/backstage-lab/tag14 && cd ~/backstage-lab/tag14
git clone -q http://lab-admin:[email protected]:3300/kranich/lieferschein.git
cd lieferschein
yq -i '.spec.owner = "team-sendung"' catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Owner ergänzt" && git push -q
s=$SECONDS; until bs catalog/entities/by-name/component/default/lieferschein-service \
  >/dev/null; do sleep 5; done; echo "nach $((SECONDS - s)) s im Katalog"
bs catalog/entities/unprocessed/pending | jq '.entities | length'

Erwartet:

nach 26 s im Katalog
0

Die übrigen Reiter: Info zeigt Node- und Backstage-Version plus alle @backstage/*-Pakete, Config die Konfiguration mit <secret> statt Werten (bs devtools/config | jq .config.integrations liefert dasselbe). Scheduled Tasks listet die Hintergrundjobs der Plugins aus devTools.scheduledTasks.plugins.

Erwartet: die Tasks des Katalogs mit Trigger- und Cancel-Symbol.

Scheduled Tasks des Katalogs mit dem Gitea-Provider

Mit dem Pfeil-Symbol stößt du den Gitea-Provider sofort an, statt eine Minute zu warten. Vorsicht: Auch im 401-Fall aus Drill 4 stand er hier auf Idle – der Provider fängt seine Fehler selbst ab. Der Status ersetzt also nicht den Blick ins Log.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Frontend, Backend und belegte Ports

Das Frontend auf :3000 ruft das Backend auf :7007 auf – eine andere Origin. Das Backend erlaubt das nur für backend.cors.origin. Ein Tippfehler dort:

cd ~/backstage-lab/portal
yq -i '.backend.cors.origin = "http://localhost:3001"' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s -D - -o /dev/null -H "Origin: $APP" "$BACKSTAGE/api/catalog/entities" \
  | grep -i '^access-control-allow-origin' || echo "kein Access-Control-Allow-Origin"

Erwartet:

kein Access-Control-Allow-Origin

Im Browser http://localhost:3000 öffnen und anmelden.

Erwartet: Mit dem Gast-Login erscheint eine irreführende Meldung wie in der Abbildung. Bei OIDC-Login (Tag 12) scheitert der Login ebenfalls, nur mit anderem Text.

Login scheitert wegen CORS mit irreführender Fehlermeldung

Die Wahrheit steht in der Browser-Konsole (F12 → Console):

Access to fetch at 'http://localhost:7007/api/auth/guest/refresh' from origin
'http://localhost:3000' has been blocked by CORS policy: Response to preflight
request doesn't pass access control check: No 'Access-Control-Allow-Origin' header
is present on the requested resource.

Fix: den Override löschen, dann gilt wieder http://localhost:3000 aus app-config.yaml.

yq -i 'del(.backend.cors)' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s -D - -o /dev/null -H "Origin: $APP" "$BACKSTAGE/api/catalog/entities" \
  | grep -i '^access-control-allow-origin'

Erwartet:

Access-Control-Allow-Origin: http://localhost:3000

Tipp: app.baseUrl, backend.baseUrl und backend.cors.origin gehören zusammen. Wer das Portal hinter einem anderen Hostnamen betreibt, ändert alle drei.

Zweites Startproblem: Port 7007 ist schon belegt, etwa von einem vergessenen yarn start in einem anderen Terminal. Du simulierst das:

~/backstage-lab/setup/portal.sh stop
node -e "require('http').createServer((q, s) => s.end('belegt')).listen(7007)" &
~/backstage-lab/setup/portal.sh start
curl -s $BACKSTAGE/.backstage/health/v1/readiness; echo
~/backstage-lab/setup/portal.sh logs 300 | sed 's/\x1b\[[0-9;]*m//g' \
  | grep EADDRINUSE | cut -c26-110
lsof -nP -iTCP:7007 -sTCP:LISTEN

Erwartet (gekürzt, PID und User weichen ab):

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
belegt
backstage error Unhandled rejection listen EADDRINUSE: address already in use :::…
COMMAND   PID  USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
node    22395  du     12u  IPv6  0xd12e…     0t0  TCP *:7007 (LISTEN)

portal.sh meldet ✔, weil der fremde Prozess auf die Readiness-URL antwortet – mit belegt statt JSON. Das Backend selbst ist nie gestartet. lsof nennt den Schuldigen:

kill %1
~/backstage-lab/setup/portal.sh restart
curl -s $BACKSTAGE/.backstage/health/v1/readiness | jq -c .

Erwartet:

{"status":"ok"}

Fortschritt speichern? Kostenlos registrieren

Drill 7: Template-Fehler im Task-Log

Der RepoUrlPicker lässt im Wizard nur 127.0.0.1:3300 zu (allowedHosts, Tag 5). Über die API prüft das niemand:

id=$(bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' -d '{
  "templateRef": "template:default/node-service",
  "values": {"name": "retouren-api", "description": "Retouren erfassen",
    "owner": "group:default/team-sendung",
    "repoUrl": "localhost:3300?owner=kranich&repo=retouren-api"}}' | jq -r .id)
sleep 8
bs scaffolder/v2/tasks/$id | jq -r .status
bs scaffolder/v2/tasks/$id/events | jq -r '.[] | select(.type=="log")
  | .body.message' | grep -E '^(Beginning|Finished|Skipping|InputError)' \
  | cut -c1-100

Erwartet:

failed
Beginning step Skeleton füllen
Finished step Skeleton füllen
Beginning step Repo in Forgejo anlegen
InputError: No matching integration configuration for host localhost:3300, please c…
Skipping step register because a previous step failed

Im Browser http://localhost:3000/create/tasks öffnen und den obersten Task wählen.

Erwartet: der erste Schritt grün, der zweite rot, der dritte übersprungen; oben die Fehlermeldung, darunter das Log.

Fehlgeschlagener Task mit fehlender Integration für localhost

Lies das Task-Log von oben: Der erste Fehler zählt, alles danach sind Folgen. Die Meldung ist dieselbe Ursache wie in Drill 4, diesmal in der Action publish:gitea. Fehlt dagegen das Passwort der Integration (leeres ${FORGEJO_TOKEN}, Drill 3), meldet die Action laut Quellcode wörtlich Credentials for the gitea ${host} required. – mit dem Platzhalter im Text.

Tipp: Template-Fehler findest du am schnellsten vor dem Lauf: Dry-Run im Template Editor oder per API (Tag 6). Fehlende Actions meldet bs scaffolder/v2/actions | jq -r '.[].id'.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Upgrade auf den nächsten Patch

Backstage erscheint monatlich als Release (z. B. 1.55.0) mit Patches dazwischen. Welches Release du nutzt, steht in backstage.json. Zuerst einen sauberen Stand sichern:

cd ~/backstage-lab/portal
git add -A && git commit -qm "Stand vor Upgrade"; git status --short | wc -l
cat backstage.json
curl -s https://versions.backstage.io/v1/tags/main/manifest.json | jq -r .releaseVersion

Erwartet (das neueste Release weicht je nach Datum ab):

       0
{
  "version": "1.55.0"
}
1.55.3

versions:bump setzt alle @backstage/*-Abhängigkeiten auf die Versionen des Release-Manifests. --skip-install lässt yarn install weg – so siehst du zuerst nur die Änderungen:

yarn backstage-cli versions:bump --release 1.55.3 --skip-install 2>&1 \
  | sed 's/\x1b\[[0-9;]*m//g' | grep -vE '^(Checking|bumping)'
git diff --stat

Erwartet (gekürzt):

Using default pattern glob @backstage/*
Some packages are outdated, updating

Upgraded from release 1.55.0 to 1.55.3, please review these template changes:

  https://backstage.github.io/upgrade-helper/?from=1.55.0&to=1.55.3

Skipping yarn install
...
Version bump complete!

 backstage.json            | 2 +-
 packages/app/package.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

Zwei Quellen sagen dir, was sich geändert hat:

  • Upgrade Helper (Link aus der Ausgabe): Diff der create-app-Vorlage zwischen zwei Versionen – Änderungen an index.ts, App.tsx oder app-config.yaml, die du von Hand nachziehst.
  • Changesets/CHANGELOG jedes Pakets, ein Eintrag pro Änderung:
git diff packages/app/package.json | grep '^[-+] '
sed -n '/^## 1.18.2/,/^## 1.18.1/p' \
  node_modules/@backstage/plugin-techdocs/CHANGELOG.md | head -5

Erwartet:

-    "@backstage/plugin-techdocs": "^1.18.1",
+    "@backstage/plugin-techdocs": "^1.18.2",
## 1.18.2

### Patch Changes

- f712f71: Fixed TechDocs addons silently not rendering in apps using the new …

Bei Minor-Releases (1.55 → 1.56) lies zusätzlich die Release Notes unter https://backstage.io/docs/releases/v1.56.0/ – dort stehen Breaking Changes und Migrationen. Der vollständige Ablauf eines echten Upgrades:

yarn install                                  # lädt die neuen Pakete
yarn tsc                                      # Typen über alle Pakete prüfen
yarn --cwd packages/app lint
CI=true yarn test
yarn backstage-cli config:check
~/backstage-lab/setup/portal.sh restart
bash ~/backstage-lab/code/tag14/kontrolle.sh  # Kontrollpunkt unten

Erwartet (gekürzt; beim Patch-Sprung hatte yarn.lock die neuen Versionen dank ^-Ranges schon, deshalb ist nichts zu laden):

➤ YN0000: · Done with warnings in 2s 281ms
Tests:       1 passed, 1 total
Loaded config from app-config.yaml, app-config.local.yaml
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
✔ DevTools meldet dieselbe Version wie backstage.json

yarn tsc und Lint geben ohne Fehler nichts aus. Das Lab bleibt auf 1.55.0, damit alle Ausgaben im Buch passen – Änderungen zurücknehmen:

git checkout -- . && yarn install >/dev/null && cat backstage.json
~/backstage-lab/setup/portal.sh restart

Erwartet:

{
  "version": "1.55.0"
}
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)

Warum diese Reihenfolge? tsc findet geänderte APIs, bevor das Portal startet; config:check findet umbenannte Konfigurationsschlüssel; erst dann kostet ein Neustart Zeit. Ein Commit pro Upgrade macht den Rückweg zu einem git revert.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Die Datei liegt unter ~/backstage-lab/code/tag14/kontrolle.sh.

#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 14 (✔/✘). Exit-Code = Anzahl Fehler.
source "${LAB:-$HOME/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; }

t "config:check ohne Fehler" "cd '$PORTAL' && yarn backstage-cli config:check"
t "Backend bereit (readiness)" \
  "curl -sf $BACKSTAGE/.backstage/health/v1/readiness | jq -e '.status==\"ok\"'"
t "keine Entity mit Processing-Fehler" \
  "bs 'catalog/entities?fields=kind,metadata.name,status' \
     | jq -e '[.[] | select(.status.items)] | length == 0'"
t "keine unverarbeiteten Entities (pending/failed)" \
  "[ \$(bs catalog/entities/unprocessed/pending | jq '.entities|length') = 0 ] &&
   [ \$(bs catalog/entities/unprocessed/failed | jq '.entities|length') = 0 ]"
t "lieferschein-service im Katalog" \
  "bs catalog/entities/by-name/component/default/lieferschein-service"
t "DevTools meldet dieselbe Version wie backstage.json" \
  "[ \"\$(bs devtools/info | jq -r .backstageVersion)\" = \
     \"\$(jq -r .version '$PORTAL/backstage.json')\" ]"
t "Gitea-Provider läuft ohne 401" \
  "! '$LAB/setup/portal.sh' logs 400 | grep -q 'gitea-provider.*401'"
exit "$fail"
bash ~/backstage-lab/code/tag14/kontrolle.sh

Erwartet:

✔ config:check ohne Fehler
✔ Backend bereit (readiness)
✔ keine Entity mit Processing-Fehler
✔ keine unverarbeiteten Entities (pending/failed)
✔ lieferschein-service im Katalog
✔ DevTools meldet dieselbe Version wie backstage.json
✔ Gitea-Provider läuft ohne 401

Challenge

Ein Kollege schickt dir seine app-config.kaputt.yaml. Finde alle vier Fehler, ohne das Portal zu starten.

Hinweis: Drei Fehler findet backstage-cli (config:check, --strict, config:print), den vierten ein Vergleich der Hosts in integrations und catalog.locations.

Lösung

Mit --config lädt die CLI genau die genannten Dateien, app-config.local.yaml bleibt außen vor:

cd ~/backstage-lab/portal
K=~/backstage-lab/code/tag14/challenge/app-config.kaputt.yaml
yarn backstage-cli config:check --config app-config.yaml --config $K

Erwartet:

YAMLParseError: Nested mappings are not allowed in compact mappings at line 33, colum…

      target: http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml
              ^

Fehler 1: rules: darunter ist eine Stelle zu weit eingerückt (die Meldung zeigt auf die Zeile davor). Korrigieren und strikt prüfen:

KK=~/backstage-lab/tag14/k.yaml
cp $K $KK && sed -i '' 's/^       rules:/      rules:/' $KK
yarn backstage-cli config:check --strict --config app-config.yaml \
  --config $KK 2>&1 | grep additionalProperty
yarn backstage-cli config:print --config app-config.yaml --config $KK \
  2>/dev/null | yq -o json '{"keys": (.integrations.gitea[0] | keys),
  "hosts": [.integrations.gitea[].host], "targets": [.catalog.locations[].target]}'

Erwartet:

  Config must NOT have additional properties { additionalProperty=second } at /cata…
{
  "keys": [
    "host",
    "baseUrl",
    "username"
  ],
  "hosts": [
    "localhost:3300"
  ],
  "targets": [
    "http://127.0.0.1:3300/kranich/katalog/src/branch/main/locations.yaml",
    "http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml"
  ]
}

Fehler 2: processingInterval: { second: 20 } statt seconds – ohne --strict ignoriert. Fehler 3: password fehlt, weil ${FORGEJO_TOKN} falsch geschrieben ist. Fehler 4: Integration für localhost:3300, Locations auf 127.0.0.1:3300 – jede Location scheiterte mit „Reading from … is not allowed” (Drill 4). Die reparierte Fassung liegt daneben:

diff $K ~/backstage-lab/code/tag14/challenge/app-config.repariert.yaml \
  | grep '^[<>] [^#]'
yarn backstage-cli config:check --strict --config app-config.yaml \
  --config ~/backstage-lab/code/tag14/challenge/app-config.repariert.yaml \
  && echo "✔ strikt ok"

Erwartet:

<     - host: localhost:3300
<       baseUrl: http://localhost:3300
>     - host: 127.0.0.1:3300
>       baseUrl: http://127.0.0.1:3300
<       password: ${FORGEJO_TOKN}
>       password: ${FORGEJO_TOKEN}
<        rules:
>       rules:
<   processingInterval: { second: 20 }
>   processingInterval: { seconds: 20 }
Loaded config from app-config.yaml, app-config.repariert.yaml
✔ strikt ok

Achtung: config:check --strict gegen deine echte app-config.local.yaml meldet additionalProperty=providers an /catalog: Der Gitea-Provider bringt kein Schema für catalog.providers.gitea mit. Das ist ein Fehlalarm – lies --strict deshalb immer Zeile für Zeile.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Logs zentral sammeln: Mit NODE_ENV=production schreibt das Backend JSON-Zeilen (Tag 13); Alarme auf level=error und auf catalog warn aus catalog-backend-module-logs, nicht auf das Grundrauschen.
  • config:check --strict (mit bekannten Ausnahmen) und yarn tsc als CI-Gate für jede Änderung an app-config*.yaml und jedes Upgrade.
  • DevTools und Unprocessed Entities nur für das Plattform-Team freigeben: Config zeigt die gesamte Struktur, Unprocessed erlaubt Löschen (catalog.entities.unprocessed.delete).
  • Upgrades monatlich im Takt der Releases, je ein Branch mit versions:bump, Upgrade Helper und CHANGELOG-Review; große Sprünge über mehrere Minor-Versionen vermeiden.
  • Tokens der Integrationen mit Ablaufdatum überwachen und rotieren, bevor sie ablaufen – sonst sieht man es erst an den roten Location-Karten.