Backstage: Catalog zum Laufen bringen

“Backstage installieren dauert einen Nachmittag.” Das stimmt. “Backstage adoptieren dauert Monate.” Das stimmt auch — und das wird bei der Entscheidung oft unterschätzt.

Der technische Teil — Backstage-Instanz deployen, Entity-Provider konfigurieren, Plugins aktivieren — ist lösbar. Der menschliche Teil — Teams dazu bringen, catalog-info.yaml in ihre Repos zu committen und aktuell zu halten — ist die eigentliche Arbeit.

Was im Catalog eigentlich steht

Der Catalog modelliert mehr als eine Liste von Services. Backstage kennt mehrere Entity-Kinds: Component (ein Service, eine Library, eine Website), API (die Schnittstelle, die eine Component bereitstellt oder konsumiert), System (eine Gruppe zusammengehöriger Components), Resource (Datenbanken, Queues) sowie Group und User für Ownership. Eine brauchbare catalog-info.yaml sieht so aus:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-service
  annotations:
    github.com/project-slug: org/checkout-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: group:default/team-checkout
  system: shop
  providesApis:
    - checkout-api
  dependsOn:
    - resource:default/checkout-db

Erst die Relationen machen den Catalog wertvoll: Wer dependsOn und providesApis pflegt, bekommt einen navigierbaren Abhängigkeitsgraphen — die Frage “wen breche ich, wenn ich diese API ändere?” wird klickbar. Ein Eintrag, der nur Name, Owner und Repo-Link enthält, ist dagegen eine CMDB mit hübscherem Frontend. Dafür committet niemand freiwillig YAML.

Wichtig dabei: Group- und User-Entities nicht von Hand pflegen, sondern aus dem Identity-Provider synchronisieren — Backstage bringt Provider für LDAP, Microsoft Entra und andere mit. Ownership, die auf manuell gepflegte Gruppen zeigt, ist nach drei Reorgs wertlos.

Discovery statt Bittstellerei

Der größte Hebel gegen den leeren Catalog ist automatische Discovery. Der GitHub-Entity-Provider scannt die Organisation periodisch und registriert alle Repos, die eine catalog-info.yaml enthalten — oder generiert für Repos ohne Datei einen minimalen Eintrag. Teams müssen nicht wissen, dass Backstage existiert; ihr Service erscheint trotzdem. Der Eintrag ist dünn, aber er ist da, und das Platform-Team kann beim Anreichern helfen statt beim Anlegen betteln.

Das Gegenstück zur Discovery ist Hygiene. Catalog-Daten driften: Teams werden umbenannt, Services abgeschaltet, Repos archiviert. Ohne Gegenmaßnahmen ist der Catalog nach einem Jahr eine Mischung aus Wahrheit und Fossilien — und sobald Entwickler einmal auf einen veralteten Eintrag hereingefallen sind, trauen sie keinem mehr. Was hilft: Orphaned-Entity-Erkennung aktivieren (Entities, deren Quelldatei verschwunden ist), archivierte Repos automatisch aus der Discovery ausschließen, und Ownership-Änderungen über die IdP-Synchronisation statt über Pull Requests abbilden.

Adoption ist ein Incentive-Problem

Teams committen catalog-info.yaml, wenn sie etwas davon haben. Drei Dinge erzeugen erfahrungsgemäß echten Sog:

TechDocs ist der stärkste Hebel. Dokumentation lebt als Markdown im Repo, wird beim Build gerendert und ist im Portal genauso auffindbar wie der Code. Das löst ein Problem, das jedes Team kennt — verstreute Confluence-Seiten, von denen die Hälfte veraltet ist.

Scaffolder-Templates sind der zweite. Ein “Neuen Service anlegen”-Template, das Repo, CI-Pipeline, Deployment-Manifeste und den Catalog-Eintrag in einem Schritt erzeugt, sorgt dafür, dass neue Services von Geburt an im Catalog stehen — Adoption per Default statt per Nachpflege.

Scorecards sind der dritte: pro Service sichtbar machen, was fehlt — kein Runbook, kein definierter On-Call, keine SLOs. Das funktioniert allerdings nur, wenn die Kriterien mit den Teams abgestimmt sind. Ein rotes Dashboard, das vom Platform-Team verordnet wurde, erzeugt Abwehr statt Verbesserung.

Die Einführungsstrategie, die funktioniert: mit ein, zwei Teams starten, die ein konkretes Problem haben, das Backstage löst. Erst wenn die sagen “das hilft uns wirklich”, ausweiten — mit dem Erfolgsbeispiel im Rücken. Der umgekehrte Weg, ein Big-Bang-Rollout mit Management-Mandat und leerem Portal, produziert zuverlässig die Reaktion “schon wieder ein Tool”.

Woran misst man, ob es funktioniert? Nicht an der Zahl der Catalog-Einträge — die treibt Discovery automatisch hoch. Aussagekräftiger sind wiederkehrende Nutzung (wie viele Entwickler öffnen das Portal pro Woche, ohne dazu aufgefordert zu werden), der Anteil von Entities mit gepflegten Relationen und TechDocs, und ob bei Incidents tatsächlich jemand im Catalog nach dem Owner sucht statt in Slack zu fragen.

Ehrlich gesagt werden die Betriebskosten oft unterschätzt: Backstage ist ein Framework, kein Produkt. Plugin-Updates, eigene Integrationen und die React/Node-Codebasis brauchen dauerhaft Engineering-Kapazität — realistisch ein bis zwei Personen, nicht “nebenbei”. Wer das nicht investieren kann oder will, sollte sich kommerzielle Alternativen ansehen; der Vergleich Humanitec vs. Port geht darauf ein.

Für Organisationen mit vielen Services und Teams bleibt ein gepflegter Catalog trotzdem einer der nützlichsten Beiträge, den ein Platform-Team leisten kann — vorausgesetzt, man behandelt ihn als Produkt mit Nutzern, nicht als Inventarliste. Mehr Grundlagen dazu im Backstage-Lernpfad und im Architektur-Artikel System Design: Internal Developer Platform.