Catalog und Entity-Modell

Das Portal basiert auf dem Backstage Software Catalog. Der Catalog ist das Rückgrat aller anderen Features: Kosten-, Security-, Compliance- und Netzwerkansichten sowie die Agenten starten alle bei einer Entity im Catalog und folgen ihren Beziehungen. Diese Seite erklärt, welche Entity-Arten es gibt, wie sie aus Azure und Entra ID gefüllt werden und was ein Workload-Team tun muss, damit sein workload mit dem richtigen Owner erscheint.

Entity-Arten

Art	API-Version	Bedeutung	Erstellt aus
Workload	xebia.com/v1	Eine Anwendung, ein Service oder eine Fähigkeit, die Cloud-Ressourcen nutzt. Die Einheit, bei der die meisten Ansichten beginnen.	subscriptions mit tags, optional angereichert aus Repository-Dateien
Domain	backstage.io/v1alpha1	Ein Fachbereich, der workloads gruppiert	Der tag domain auf subscriptions oder eine Repository-Datei
Organisation	xebia.com/v1	Ein Kunde oder eine interne Organisation, der eine oder mehrere Domänen gehören	Der tag organisation auf subscriptions. Domänen ohne diesen tag fallen auf eine einzelne Standardorganisation zurück.
Group	backstage.io/v1alpha1	Ein Team, als Security-Gruppe in Entra ID	Microsoft Graph
User	backstage.io/v1alpha1	Eine Person	Microsoft Graph
Fragment	xebia.com/v1	Eine Teilbeschreibung einer anderen Entity, um mehrere Quellen zusammenzuführen	Die Azure-Provider und Repository-Dateien
Customer	xebia.com/v1	Ein Kunde des Anbieters, mit einem Owner	Catalog-Dateien. Die Art wird nur in der eigenen Umgebung des Anbieters geladen

Ein workload hat diese Form:

apiVersion: xebia.com/v1
kind: Workload
metadata:
  name: my-workload
spec:
  owner: group:default/my-team   # required, a Group
  dependsOn:                     # optional, other workloads
    - other-workload
  domain: platform               # optional
  externalUris:                  # optional, see Network insights
    - https://api.example.com
    - https://api.example.com/orders

Nur owner ist Pflicht. Alle String-Felder brauchen eine Mindestlänge. Der Catalog lehnt Entities ab, die nicht validieren.

Beziehungen

Der Catalog-Prozessor erstellt diese Beziehungen aus der Workload-Spec.

Aus der Spec	Beziehung (und Gegenstück)
owner	ownedBy / ownerOf zwischen workload und Gruppe
dependsOn	dependsOn / dependencyOf zwischen workloads
domain	partOf / hasPart zwischen workload und Domäne

Die Ansichten verwenden eine fünfstufige Hierarchie: Organisation, Domäne, Team, workload, subscription. Eine Kosten-, Security- oder Compliance-Ansicht für eine Domäne oder ein Team ist die Aggregation ihrer workloads und deren subscriptions.

Subscription-Annotationen

Ein workload wird über Annotationen der Form azure.com/subscription-selector.<key> mit dem Wert <tenant-id>/<subscription-id> mit seinen Azure-subscriptions verknüpft. Der Schlüssel benennt einen Slot, zum Beispiel einen pro Umgebung. Alle Azure-Plugins lesen diese Annotationen, um zu wissen, welche subscriptions sie abfragen. Ein workload mit mehr als einer subscription (zum Beispiel Nicht-Produktion und Produktion) zeigt jede subscription einzeln und die Summe pro workload.

Wie Entities in den Catalog kommen

flowchart LR
    arg["Azure Resource Graph<br/>subscription tags and<br/>Application Gateway listeners"] --> frag["Fragment entities"]
    ado["Azure DevOps<br/>catalog-info.yaml files"] --> frag
    frag --> merge["Merged Entities module<br/>groups by kind, namespace, name"]
    merge --> wl["Workload, Domain,<br/>Organisation entities"]
    wl --> proc["Entity model module<br/>validates, adds relations"]
    graph["Microsoft Graph<br/>users and groups"] --> cat["Catalog"]
    proc --> cat

Der Backstage Catalog akzeptiert eine Entity einmal pro Art, Namespace und Name. Eine zweite Quelle mit demselben Namen würde als Konflikt abgelehnt. Das Portal lässt deshalb jede Quelle ein Fragment der Entity beschreiben, und ein Merged Entities-Modul führt die Fragmente zu einer Entity zusammen, bevor der Catalog sie verarbeitet.

Schritt	Was passiert
1	Das Azure-Resource-Graph-Modul liest subscriptions und leitet aus den tags Fragmente für workload, Domäne und Organisation ab. Ein zweiter Provider liest die Host-Namen der Application-Gateway-Listener und leitet daraus Fragmente ab. Beide laufen nach einem Zeitplan, der in der Konfiguration festgelegt wird. Die gemeinsame Produktionskonfiguration setzt für den Application-Gateway-Provider eine Stunde.
2	Der Azure-DevOps-Catalog-Provider liest catalog-info.yaml-Dateien aus Repositories (in der Referenzkonfiguration alle 30 Minuten) und kann Fragmente oder Entities hinzufügen.
3	Der Merged-Entity-Provider fragt den Catalog nach allen Fragmenten, gruppiert sie nach Zielart, Namespace und Name und führt sie zu einer Entity zusammen. Fragmente aus einer YAML-Datei haben Vorrang vor anderen Fragmenten. Innerhalb jeder Gruppe gilt die Reihenfolge nach Fragmentname, sodass das Ergebnis stabil ist.
4	Das Entity-Modell-Modul validiert den Workload und erstellt die Beziehungen.

Ein Fragment hat denselben Rahmen wie die Ziel-Entity, aber nur apiVersion, kind und metadata.name sind Pflicht, sodass eine Quelle nur die Felder liefern kann, die sie kennt:

apiVersion: xebia.com/v1
kind: Fragment
metadata:
  name: my-unique-fragment-name
spec:
  apiVersion: xebia.com/v1
  kind: Workload
  metadata:
    name: my-target-entity-name
  spec:
    # only the fields this source knows

Fragmente können einen Workload, eine Domain oder eine Organisation als Ziel haben.

Tags, die den Catalog steuern

Der Azure-Provider liest diese tags auf subscriptions. Die Standardnamen lassen sich in der Provider-Konfiguration ändern (Konfiguration).

Tag (Standard)	Wirkung
workload	Markiert eine subscription als Teil eines workloads und benennt ihn
owner	Die Owner-Gruppe des workloads
domain	Die Domäne des workloads (optional)
organisation	Die Organisation, zu der die Domäne gehört (optional)
name	Ein lesbarer Titel für die Entity (optional)
description	Eine Beschreibung (optional)
external-uris	Kommagetrennte Liste absoluter HTTP- oder HTTPS-URIs, die zum workload gehören und zum Abgleich der Application-Gateway-WAF-Logs dienen (optional)

Hinweise zu external-uris:

• Leerzeichen um Einträge werden ignoriert, ungültige Einträge werden verworfen.
• Die URIs aller subscriptions desselben workloads werden zusammengeführt und als spec.externalUris am workload gespeichert.
• Beispiel: https://api.example.com, https://api.example.com/orders.

Spokes der Plattform

Ein spoke, den die Plattform deployt, trägt bereits die tags workload und owner (siehe die Pflicht-tags in der Spoke-JSON-Referenz und unter Namensgebung und tags). Zusätzlich setzt das Spoke-Deployment einen versteckten tag mit JSON-Metadaten:

{
  "workloadShortName": "<workload>",
  "productTeamGroupNames": ["<team group name>"]
}

Der Provider liest workloadShortName als workload und den ersten nicht leeren Eintrag von productTeamGroupNames als Owner. Weil das Spoke-Deployment ihn füllt, braucht ein spoke kein zusätzliches manuelles Tagging, um im Catalog zu erscheinen. Ungültiges JSON wird mit einer Warnung ignoriert.

Welche Quelle gewinnt, wenn sowohl der versteckte tag als auch die einfachen tags vorhanden sind, steuert die Option spokeMetadataOverridable (Standard false: Die versteckten Metadaten gewinnen, die einfachen tags sind der Fallback. true kehrt das um). Behalte den Standard für spokes der Plattform.

Benutzer und Gruppen

Benutzer und Gruppen werden aus Microsoft Graph eingelesen (in der Referenzkonfiguration: aktivierte Benutzer und Security-aktivierte Gruppen, einmal pro Stunde). Das Portal meldet Benutzer an, indem es die E-Mail-Adresse der Anmeldung einer User-Entity zuordnet, siehe Authentifizierung und Zugriff.

Owner-Werte in tags können einfache Gruppennamen oder Entity-Referenzen sein. Ist das Feature-Flag features.microsoftGraphGroupNameNormalization aktiviert, wendet das Portal eine Namenskonvention auf Entra-ID-Gruppennamen an:

Eingabe	Ergebnis
Einfacher Owner-tag, zum Beispiel SG-AZ-LZ_<org>_engineers	Mit der Konvention auf eine Gruppe in einem aus dem Namen abgeleiteten Namespace abgebildet (zum Beispiel group:sg-az-lz-<org>/engineers)
Entity-Referenz, zum Beispiel group:default/Some_Group	Struktur bleibt erhalten, Catalog-übliche Normalisierung wird auf die Teile angewendet
Flag aus	Einfacher tag wird auf group:default/<normalised name> abgebildet

Namenskonvention für Gruppen

Bei aktiviertem Flag wird eine Gruppe nur eingelesen, wenn ihr Name (nach der Normalisierung) auf _engineers, _users, _admins oder _standard_changes endet. Gruppen mit anderen Namen werden vom Transformer verworfen und können keinen workload besitzen. Diese Konvention ist spezifisch für die Gruppenbenennung des Anbieters. Prüfe sie, bevor du das Flag für einen anderen Kunden aktivierst.

Was ein Workload-Team tut

1. Stelle sicher, dass die subscription des workloads die tags workload und owner trägt. Bei spokes der Plattform geschieht das beim Deployment.
2. Füge den tag domain hinzu, wenn der workload zu einer Domäne gehört, und external-uris, wenn der workload hinter einem Application Gateway mit WAF liegt.
3. Füge optional eine catalog-info.yaml in ein Repository ein, um Beschreibungen, Abhängigkeiten oder Dokumentation zu ergänzen. Sie wird beim nächsten Scan übernommen.
4. Warte den nächsten Lauf der Provider ab (in der Referenzkonfiguration bis zu eine Stunde für tags, bis zu dreißig Minuten für Repository-Dateien), bevor du nach der Änderung suchst.

Hat ein workload keinen Owner oder einen Owner, der als Gruppe nicht existiert, können die Insight-Ansichten seine Kosten nicht zuordnen und zeigen sie als UNKNOWN, und niemand kann seine sensiblen Details sehen (Authentifizierung und Zugriff).

Verwandt

• Insights
• Konfiguration
• Namensgebung und tags