Backstage: Software Catalog und Templates

Lernziele

Nach dieser Lektion kannst du erklären, wie der Software Catalog von Backstage funktioniert, was eine catalog-info.yaml enthält und wie Software Templates neue Services scaffolden. Du kennst das Entity-Modell (Component, System, API, Resource), weißt, warum Backstage ein Framework und kein fertiges Produkt ist, und kannst die ehrliche Kostenrechnung für den Betrieb einer eigenen Instanz aufmachen.

Das Problem: Niemand weiß, was eigentlich läuft

Ab etwa 30 Teams stellt eine Organisation immer dieselben Fragen: Welche Services gibt es? Wem gehört der checkout-service? Wo ist seine Doku, wo seine Pipeline, wo seine Dashboards? Die Antworten verteilen sich auf Confluence-Seiten von 2021, ein halb gepflegtes CMDB und das Gedächtnis einzelner Kolleginnen. Onboarding dauert Wochen, und im Incident verliert man die erste halbe Stunde mit der Frage, wer überhaupt zuständig ist.

Backstage — von Spotify entwickelt und 2020 als Open Source an die CNCF gegeben — adressiert genau das: ein Developer Portal als einheitliche Oberfläche über alle Services, Teams und Tools. Das Herzstück ist nicht die UI, sondern das Datenmodell dahinter: der Software Catalog.

Der Software Catalog: Metadaten als Code

Der Catalog ist ein Inventar aller Software-Entitäten, gepflegt nach demselben Prinzip wie Infrastruktur: deklarativ, in Git, beim Code. Jeder Service bringt eine catalog-info.yaml in seinem Repository mit:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-service
  description: Bezahlprozess des Webshops
  annotations:
    github.com/project-slug: acme/checkout-service
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: webshop

Backstage liest diese Dateien regelmäßig ein (über sogenannte Locations oder Discovery-Mechanismen) und baut daraus einen Graphen. Die wichtigsten Entity-Kinds:

• Component — ein Stück Software: Service, Website, Library.
• API — eine Schnittstelle, die eine Component bereitstellt oder konsumiert (mit OpenAPI/gRPC-Definition als Anhang).
• System und Domain — Gruppierungen: das webshop-System bündelt mehrere Components, die Domain bündelt Systeme.
• Resource — Infrastruktur wie eine Datenbank oder ein S3-Bucket.
• Group und User — die Ownership-Seite, idealerweise aus dem IdP synchronisiert.

Der Wert entsteht aus den Relationen: ownedBy, partOf, providesApi, dependsOn. Damit beantwortet der Catalog Fragen wie „Welche Services hängen von dieser API ab?” — genau die Frage, die du vor einem Breaking Change stellen musst. Und weil owner ein Pflichtfeld ist, gibt es per Konstruktion keine herrenlosen Services mehr — solange der Catalog gepflegt wird, dazu unten mehr.

Annotations verknüpfen die Entität mit der Außenwelt: das GitHub-Repo, das Kubernetes-Label, das Grafana-Dashboard. Plugins lesen diese Annotations und blenden die Informationen direkt auf der Service-Seite ein — CI-Status, laufende Pods, offene Alerts. Das ist die eigentliche Portal-Idee: ein Ort statt acht Browser-Tabs.

Software Templates: der Scaffolder als Golden-Path-Maschine

Der zweite Pfeiler ist der Scaffolder. Ein Software Template ist selbst eine Catalog-Entität (kind: Template, apiVersion scaffolder.backstage.io/v1beta3) und beschreibt zwei Dinge: ein Formular (Parameter wie Service-Name, Team, Datenbank ja/nein) und eine Schrittfolge — Skeleton-Repo aus einer Vorlage rendern, GitHub-Repository anlegen, CI-Pipeline registrieren, catalog-info.yaml gleich mit erzeugen und im Catalog anmelden.

Für Entwickler heißt das: „Neuer Service” ist ein Formular und fünf Minuten Wartezeit statt drei Tage Copy-Paste aus dem letzten Projekt. Für die Plattform heißt es: Jeder neue Service startet mit den richtigen Defaults — Dockerfile, Observability-Setup, Security-Scanning. Das ist die technische Umsetzung der Golden Paths aus Lektion 5; wie du diese Templates als versionierte Produkte pflegst, ist Thema der nächsten Lektion.

Dritter Baustein im Standardumfang ist TechDocs: Doku als Markdown im Service-Repo (Docs-like-Code, gerendert mit MkDocs), angezeigt direkt auf der Catalog-Seite des Services. Damit liegt Doku dort, wo sie bei Code-Änderungen mitgepflegt wird — nicht in einem Wiki, das niemand aktualisiert.

Die ehrliche Seite: Backstage ist ein Framework

Der häufigste Irrtum: Backstage als Produkt zu behandeln, das man „installiert”. Tatsächlich baust du eine eigene App — TypeScript/React im Frontend, Node.js im Backend, PostgreSQL als Datenbank — und kompilierst Plugins hinein. Authentifizierung gegen deinen IdP, Berechtigungen, Catalog-Discovery, jede Drittsystem-Integration: alles Konfigurations- und teils Programmierarbeit.

Das hat Konsequenzen, die du im Interview benennen können solltest:

• Du brauchst dauerhafte Kapazität. Eine realistische Größenordnung ist mindestens ein bis zwei Engineers, die das Portal als Produkt betreiben und weiterentwickeln — sonst veraltet die Instanz und stirbt den Adoption-Tod.
• TypeScript-Kompetenz im Platform-Team ist Voraussetzung, was in infrastrukturlastigen Teams oft fehlt.
• Der Catalog ist nur so gut wie seine Pflege. Ein halb leerer Catalog ist schlimmer als keiner, weil er Vertrauen kostet.

Die Alternativen gehören in jede Build-vs-Buy-Diskussion (Lektion 11): kommerzielle Portale wie Port oder Cortex (schneller startklar, weniger anpassbar, Vendor-Abhängigkeit), Managed-Backstage-Angebote wie Roadie, oder bewusst kein Portal — ein gepflegtes Git-Repo mit Service-Inventar trägt kleine Organisationen erstaunlich weit.

Praxis: Backstage lokal erkunden

Backstage lässt sich lokal mit Node.js ausprobieren (Node und Yarn vorausgesetzt):

npx @backstage/create-app@latest
# Name vergeben, z. B. "my-portal", dann:
cd my-portal
yarn start

Die App startet mit Demo-Daten unter http://localhost:3000. Arbeite drei Aufgaben durch:

1. Catalog lesen: Öffne eine Beispiel-Component und finde heraus, aus welcher YAML-Datei sie stammt (Tab „Inspect entity” zeigt die Rohdaten).
2. Eigene Entität registrieren: Lege in einem eigenen Repo eine catalog-info.yaml wie oben an und registriere sie über „Register existing component”. Beobachte, welche Relationen entstehen, wenn owner auf eine nicht existierende Group zeigt.
3. Template ansehen: Öffne unter „Create” ein Beispiel-Template und lies seine YAML-Definition — Parameter-Block und Steps-Block erkennst du sofort wieder.

Danach hast du das Entity-Modell einmal angefasst statt nur Screenshots gesehen — ein Unterschied, den Interviewer hören.

Typische Stolperfallen

Catalog-Befüllung als Einmalaktion: Wer den Catalog initial per Skript befüllt, aber keine Discovery und keine Ownership-Pflicht etabliert, hat nach sechs Monaten ein Museum. Der Catalog muss in den Workflow: neue Services entstehen nur über Templates, die die Registrierung gleich miterledigen.

Backstage einführen, bevor es ein Problem löst: Mit fünf Teams ist ein Portal Overhead ohne Nutzen. Die Faustregel: Erst wenn „Wem gehört Service X?” regelmäßig Zeit kostet, lohnt das Investment.

Plugin-Sammelwut: Jedes Plugin ist Code, den du beim nächsten Backstage-Upgrade mitziehen musst. Ein Portal mit 30 Plugins und drei Monaten Upgrade-Rückstand ist ein bekanntes Schmerzbild.

Portal als Pflicht statt als Produkt: Wenn Entwickler das Portal nur öffnen, weil ein Prozess es erzwingt, ist die Adoption-Metrik wertlos. Miss, ob Leute freiwillig wiederkommen.

Interview-Vorbereitung

Auf „Erkläre Backstage” antwortest du problem-first: Problem (Service-Sprawl, unklare Ownership, fragmentierte Tool-Landschaft) → Lösung (Developer Portal mit Software Catalog als deklarativem Inventar, Scaffolder für Golden Paths, TechDocs für Doku) → Mechanik (catalog-info.yaml im Repo, Entity-Graph mit Ownership-Relationen, Plugins über Annotations) → Grenze (Framework statt Produkt, braucht dediziertes Team und gelebte Catalog-Pflege).

Wahrscheinliche Follow-ups:

• „Wie kommt ein Service in den Catalog?” — catalog-info.yaml im Repo, eingelesen per Discovery oder Registrierung; idealerweise erzeugt das Scaffolder-Template sie automatisch.
• „Was unterscheidet Component, System und Domain?” — Component ist die Software-Einheit, System gruppiert Components zu einem fachlichen Ganzen, Domain gruppiert Systeme — der Graph dazwischen beantwortet Abhängigkeits- und Ownership-Fragen.
• „Warum scheitern Backstage-Einführungen?” — unterschätzter Betriebsaufwand, leerer oder veralteter Catalog, kein Product Ownership fürs Portal.
• „Backstage oder ein kommerzielles Portal?” — Backstage bei Anpassungsbedarf und vorhandener Frontend-Kompetenz; Buy, wenn Time-to-Value zählt und das Team klein ist. Entscheidungskriterien nennen, nicht Tool-Namen.

Zusammenfassung

Backstage macht aus verstreutem Tribal Knowledge ein deklaratives System: Der Software Catalog modelliert Services, APIs, Systeme und Ownership als YAML in Git, Software Templates gießen Golden Paths in ausführbare Formulare, TechDocs hält Doku beim Code. Der Preis ist real: Backstage ist ein Framework, das ein eigenes Team als internes Produkt betreiben muss, und ein ungepflegter Catalog zerstört das Vertrauen schneller, als es aufgebaut wurde.

In der nächsten Lektion geht es um die Frage, die nach dem ersten Template sofort auftaucht: Wie versionierst du Golden Paths — und was passiert mit den 80 Services, die aus Template-Version 1 gescaffoldet wurden, wenn Version 2 erscheint?