Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: Organisation und Ownership

Ziel: Du bildest die Kranich-Organisation mit Groups und Users im Katalog ab, löst alle Owner auf und lässt den Gast als echte User-Entity auftreten. · Dauer: ca. 90 min · Voraussetzung: Tag 3

Briefing

  • Group und User sind Entities wie alle anderen. Sie liegen bei Kranich im Repo kranich/org in einer Datei org.yaml.
  • Die Hierarchie entsteht aus spec.parent (Gruppe) und spec.memberOf (User). Die Gegenrichtung (parentOf, hasMember) ergänzt der Katalog selbst.
  • spec.owner: team-sendung wird zur Relation ownedBy → group:default/team-sendung. Fehlt die Gruppe, bleibt die Relation ins Leere – die gelbe Warnung seit Tag 1.
  • Owned im Katalog zeigt, was die angemeldete Identität oder eine ihrer Gruppen besitzt.
kranich (organization)
└── it (department)
    ├── team-sendung (team) ◄─ memberOf ─ anna.berger, ben.kraus
    ├── team-web     (team) ◄─ memberOf ─ chris.dietz, thomas.zachmann
    └── plattform    (team) ◄─ memberOf ─ thomas.zachmann

Drill 1: Bestandsaufnahme

Ausgangslage ist das Ende von Tag 3: Das Portal läuft, sendungs-api, tracking-web, das System sendungsverfolgung und die externen Resources sind im Katalog, und app-config.local.yaml enthält einen Block catalog.locations.

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
mkdir -p ~/backstage-lab/tag04 && cd ~/backstage-lab/tag04
  1. Öffne http://localhost:3000, klicke auf Enter und dann auf sendungs-api.
  2. Erwartet: die gelbe Warnung wie in der Abbildung, Owner zeigt nur den nackten Namen team-sendung.
Entity-Seite mit Warnung über die fehlende Gruppe team-sendung

Welche Owner fehlen insgesamt? Das Skript holt alle Werte der Relation ownedBy als Facette und fragt sie gesammelt per by-refs ab – fehlende Entities kommen als null zurück.

cat > ~/backstage-lab/tag04/owner-check.sh <<'EOF'
#!/usr/bin/env bash
# owner-check.sh – listet Owner-Referenzen, zu denen es keine Entity gibt.
source ~/backstage-lab/setup/env.sh
refs=$(bs 'catalog/entity-facets?facet=relations.ownedBy' \
  | jq -c '[.facets[][] | .value]')
bs catalog/entities/by-refs -X POST -H 'Content-Type: application/json' \
  -d "{\"entityRefs\":$refs,\"fields\":[\"kind\"]}" \
  | jq -r --argjson r "$refs" '[range(0; $r | length) as $i
      | select(.items[$i] == null) | "✘ fehlt: \($r[$i])"]
      | if length == 0 then "✔ alle \($r | length) Owner vorhanden" else .[] end'
EOF
bash ~/backstage-lab/tag04/owner-check.sh

Erwartet:

✘ fehlt: group:default/team-sendung
✘ fehlt: group:default/team-web

group:default/guests und user:default/guest fehlen nicht – sie stammen aus examples/org.yaml der create-app-Vorlage.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Repo kranich/org

Die fertige org.yaml liegt im Begleitcode. Fünf Groups, vier Users:

cp -R ~/backstage-lab/code/tag04/org ~/backstage-lab/tag04/
grep -E '^  name:' ~/backstage-lab/tag04/org/org.yaml

Erwartet:

  name: kranich
  name: it
  name: team-sendung
  name: team-web
  name: plattform
  name: anna.berger
  name: ben.kraus
  name: chris.dietz
  name: thomas.zachmann

Ein Auszug mit den drei Bausteinen – Wurzel, Team, User:

kind: Group
metadata:
  name: kranich
  title: Kranich Logistik GmbH
spec:
  type: organization
  profile:
    displayName: Kranich Logistik GmbH
    email: [email protected]
  children: []
---
kind: Group
metadata:
  name: team-sendung
  title: Team Sendung
  description: Sendungsverfolgung – API, Worker, Datenbank
spec:
  type: team
  parent: it
  profile:
    displayName: Team Sendung
    email: [email protected]
  children: []
---
kind: User
metadata:
  name: thomas.zachmann
spec:
  profile:
    displayName: Thomas Zachmann
    email: [email protected]
  memberOf: [plattform, team-web]

Warum children: []? Das Feld ist bei Groups Pflicht. Du pflegst die Hierarchie nur von unten (parent), die Kinder trägt der Katalog als Relation parentOf nach. spec.type ist frei wählbar – organization, department und team sind Konvention.

~/backstage-lab/setup/mkrepo.sh kranich/org ~/backstage-lab/tag04/org

Erwartet:

✔ kranich/org angelegt (http://127.0.0.1:3300/kranich/org)

Fortschritt speichern? Kostenlos registrieren

Drill 3: Registrieren trotz catalog.rules

Der naheliegende Weg ist ein Probelauf per API:

URL=$FORGEJO/kranich/org/src/branch/main/org.yaml
curl -s -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  -H 'Content-Type: application/json' -X POST \
  "$BACKSTAGE/api/catalog/locations?dryRun=true" \
  -d "{\"type\":\"url\",\"target\":\"$URL\"}" | jq -r .error.message

Erwartet (umbrochen, gekürzt):

NotAllowedError: Entity group:default/kranich at url:http://127.0.0.1:3300/kranich/
org/src/branch/main/org.yaml, originated at url:…, is not of an allowed kind for
that location

Warum? Die globalen catalog.rules (Tag 3) erlauben User und Group nicht. Das ist gewollt: Sonst könnte jeder per Register Existing Component Gruppen anlegen und sich so Ownership erschleichen. Die Ausnahme gilt nur für eine Location in der Konfiguration. Füge in app-config.local.yaml unter catalog.locations als letzten Listeneintrag hinzu (Einrückung wie die übrigen Einträge):

    # Tag 4: Organisation aus kranich/org
    - type: url
      target: http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml
      rules:
        - allow: [User, Group]

Achtung: Falls dort noch der Eintrag für tag03/entwurf.yaml steht, lösche ihn. Beide Dateien definieren group:default/team-sendung. Der Katalog behält dann die zuerst gesehene Version und schreibt ins Log: Detected conflicting entityRef group:default/team-sendung already referenced by file:…/tag03/entwurf.yaml and now also url:…/kranich/org/….

~/backstage-lab/setup/portal.sh restart
sleep 20
bs 'catalog/entities?filter=kind=group,kind=user&fields=kind,metadata.name' \
  | jq -r '.[] | "\(.kind) \(.metadata.name)"' | sort

Erwartet:

Group guests
Group it
Group kranich
Group plattform
Group team-sendung
Group team-web
User anna.berger
User ben.kraus
User chris.dietz
User guest
User thomas.zachmann

Fortschritt speichern? Kostenlos registrieren

Drill 4: Die Warnung verschwindet

  1. Lade die Entity-Seite von sendungs-api neu.
  2. Erwartet: keine Warnung mehr, Owner zeigt jetzt den displayName „Team Sendung” als Link – wie in der Abbildung.
Dieselbe Seite ohne Warnung mit aufgelöstem Owner Team Sendung
bash ~/backstage-lab/tag04/owner-check.sh
bs catalog/entities/by-name/group/default/it \
  | jq -r '.spec.children, (.relations[] | "\(.type) -> \(.targetRef)")'

Erwartet:

✔ alle 5 Owner vorhanden
[]
childOf -> group:default/kranich
parentOf -> group:default/plattform
parentOf -> group:default/team-sendung
parentOf -> group:default/team-web

spec.children bleibt leer, die Relationen parentOf stammen aus den parent-Feldern der drei Teams. Abfragen und Oberfläche arbeiten immer mit Relationen, nie mit spec.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die Gruppen-Seite

  1. Klicke auf der Entity-Seite von sendungs-api auf Team Sendung.
  2. Erwartet: die Gruppen-Seite wie in der Abbildung. Rechts die Profilkarte mit Entity Ref, Email, Parent Group (IT) und Child Groups (N/A), links der Mini-Graph Relations mit Mitgliedern und allem, was das Team besitzt.
Gruppen-Seite von Team Sendung mit Relations-Graph und Profilkarte
  1. Scrolle nach unten. Die Karte Team Sendung members (2 of 2) listet Anna Berger und Ben Kraus mit E-Mail, die Karte Ownership zählt die besessenen Entities nach Typ.
  2. Klicke in der Profilkarte auf IT. Die Abteilung hat weder Mitglieder noch eigene Entities – Ownership ist leer.
  3. Schalte in Ownership den Schalter Include indirect ownership ein.
  4. Erwartet: die Summe aller drei Teams wie in der Abbildung.
Ownership-Karte der Abteilung IT mit indirekter Ownership

Warum? „Indirekt” folgt den parentOf-Relationen nach unten. So sieht eine Abteilungsleitung auf einen Blick, wofür ihre Teams zuständig sind.

Tipp: Die Karten kommen aus dem Plugin @backstage/plugin-org und lassen sich in app.extensions konfigurieren, z. B. entity-card:org/ownership mit config.initialRelationAggregation: aggregated (Tag 9).

Fortschritt speichern? Kostenlos registrieren

Drill 6: Die User-Seite

  1. Klicke in der Sidebar auf Catalog, stelle Kind auf User und öffne thomas.zachmann.
  2. Erwartet: die User-Seite wie in der Abbildung – Profilkarte mit E-Mail und den Gruppen Team Plattform und Team Web, darunter Ownership.
User-Seite von Thomas Zachmann mit Gruppen und Ownership

Der User selbst besitzt nichts. Die Karte Ownership zeigt trotzdem tracking-web und kartendienst: Für User ist Include indirect ownership von Anfang an an und zählt alles, was seinen Gruppen gehört.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Owned und die Gast-Identität

  1. Klicke auf Catalog und links unter PERSONAL auf Owned.
  2. Erwartet: Owned zeigt 0, die Tabelle bleibt bei „All Components”.

Warum? Der Gast ist user:development/guest – Namespace development, nicht default. Der Guest-Provider sucht diese Entity im Katalog, findet sie nicht und stellt ein Token mit ent: [user:development/guest] aus. Diese Liste (ownershipEntityRefs) bestimmt Owned, und dieser Ref besitzt nichts.

Im installierten Code (plugin-auth-backend-module-guest-provider, Datei config.schema.json) stehen zwei Schlüssel: userEntityRef (Standard user:development/guest) und ownershipEntityRefs. Findet der Provider den User im Katalog, löst er die Gruppen selbst auf. Hänge an app-config.local.yaml an:

cat >> ~/backstage-lab/portal/app-config.local.yaml <<'EOF'
auth:
  providers:
    guest:
      userEntityRef: user:default/thomas.zachmann
EOF
grep -c '^auth:' ~/backstage-lab/portal/app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s -H 'X-Requested-With: XMLHttpRequest' "$BACKSTAGE/api/auth/guest/refresh" \
  | jq .backstageIdentity.identity

Erwartet (die 1 heißt: kein doppelter Top-Level-Key auth):

1
{
  "type": "user",
  "userEntityRef": "user:default/thomas.zachmann",
  "ownershipEntityRefs": [
    "user:default/thomas.zachmann",
    "group:default/plattform",
    "group:default/team-web"
  ]
}

auth.providers.guest: {} aus app-config.yaml und dein Block werden zusammengeführt.

  1. Öffne Settings, klicke im Profil auf ⋮ und Sign Out, dann wieder Enter.
  2. Erwartet: Unter Profile steht user:default/thomas.zachmann, die Karte Backstage Identity zeigt die Identität wie in der Abbildung.
Backstage Identity mit User und zwei Gruppen als Ownership Entities
  1. Klicke auf Catalog und Owned. Erwartet: „Owned Components (1)” mit tracking-web wie in der Abbildung.
Owned-Filter zeigt tracking-web von Team Web

Starred steht wieder auf 0: Sterne gehören zur Identität, die Favoriten von user:development/guest aus Tag 1 sieht der neue User nicht.

Sicherheit: Der Guest-Provider prüft nichts – jeder, der das Portal erreicht, ist jetzt Thomas Zachmann. Im Lab ist das bequem, in Produktion ersetzt ein echter Sign-in mit Resolver diesen Trick (Tag 12).

Fortschritt speichern? Kostenlos registrieren

Drill 8: Ownership per API und Org-Graph

Alles, was ein Team besitzt, liefert ein Filter auf die Relation. Er funktioniert auch, wenn die Gruppe fehlt – er vergleicht nur Zeichenketten.

bs 'catalog/entities?filter=relations.ownedBy=group:default/team-web' \
  | jq -r '.[] | "\(.kind) \(.metadata.name)"'
bs 'catalog/entity-facets?facet=relations.ownedBy' | jq -c '.facets[][]'

Erwartet:

Component tracking-web
Resource kartendienst
{"value":"group:default/guests","count":3}
{"value":"group:default/team-sendung","count":7}
{"value":"group:default/team-web","count":2}
{"value":"user:default/guest","count":1}

filter=spec.owner=team-web liefert hier dasselbe, scheitert aber bei Schreibweisen wie group:team-web oder group:default/team-web. Die Relation ist immer vollständig qualifiziert – nimm in Skripten die Relation.

Die Organisation als Graph:

  1. Öffne die Gruppe Kranich Logistik GmbH (über Parent Group von IT) und klicke in Relations auf View graph.
  2. Setze MAX DEPTH auf 3, wähle unter KINDS nur Group und User und unter Direction Top to bottom.
  3. Erwartet: der Organigramm-Graph wie in der Abbildung. Thomas Zachmann hängt an zwei Teams.
Catalog Graph der Organisation von Kranich bis zu den Usern

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cat > ~/backstage-lab/tag04/kontrolle.sh <<'EOF'
#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 4 (✔/✘). 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 "Gruppen kranich, it, team-sendung, team-web, plattform" \
  "for g in kranich it team-sendung team-web plattform; do
     e group/default/\$g || exit 1; done"
t "team-sendung hängt unter it" \
  "e group/default/team-sendung | jq -e '.relations[] |
     select(.type==\"childOf\" and .targetRef==\"group:default/it\")'"
t "User thomas.zachmann mit E-Mail" \
  "e user/default/thomas.zachmann | jq -e '.spec.profile.email | test(\"@\")'"
t "team-sendung besitzt die Component sendungs-api" \
  "bs 'catalog/entities?filter=relations.ownedBy=group:default/team-sendung' |
     jq -e '.[] | select(.metadata.name==\"sendungs-api\" and .kind==\"Component\")'"
t "Keine fehlenden Owner" \
  "bash ~/backstage-lab/tag04/owner-check.sh | grep -q '^✔'"
t "Gast tritt als user:default/thomas.zachmann auf" \
  "curl -sf -H 'X-Requested-With: XMLHttpRequest' \$BACKSTAGE/api/auth/guest/refresh |
     jq -e '.backstageIdentity.identity.userEntityRef ==
       \"user:default/thomas.zachmann\"'"
exit "$fail"
EOF
bash ~/backstage-lab/tag04/kontrolle.sh

Erwartet:

✔ Gruppen kranich, it, team-sendung, team-web, plattform
✔ team-sendung hängt unter it
✔ User thomas.zachmann mit E-Mail
✔ team-sendung besitzt die Component sendungs-api
✔ Keine fehlenden Owner
✔ Gast tritt als user:default/thomas.zachmann auf

Challenge

Gründe unter it das Team team-kunde mit Chris Dietz als Mitglied und übergib ihm tracking-web. Alles per git push und Refresh, ohne Neustart.

Hinweis: Eine Gruppe kann ihre Mitglieder auch selbst über spec.members angeben, und ein Refresh einer Entity liest die ganze Datei neu, in der sie steht.

Lösung

cd ~/backstage-lab/tag04
git clone -q http://lab-admin:[email protected]:3300/kranich/org.git org-repo
cat ~/backstage-lab/code/tag04/challenge/team-kunde.yaml >> org-repo/org.yaml
git -C org-repo -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Neues Team Kunde" && git -C org-repo push -q origin main
git clone -q http://lab-admin:[email protected]:3300/kranich/tracking-web.git
sed -i '' 's/owner: team-web/owner: team-kunde/' tracking-web/catalog-info.yaml
git -C tracking-web -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Owner team-kunde" && git -C tracking-web push -q origin main
for r in group:default/kranich component:default/tracking-web; do
  bs catalog/refresh -X POST -H 'Content-Type: application/json' \
    -d "{\"entityRef\":\"$r\"}" -w '%{http_code}\n'
done
sleep 6
bs catalog/entities/by-name/group/default/team-kunde \
  | jq -r '.relations[] | "\(.type) -> \(.targetRef)"'

Erwartet:

200
200
childOf -> group:default/it
hasMember -> user:default/chris.dietz
ownerOf -> component:default/tracking-web

Die angehängte Gruppe (challenge/team-kunde.yaml) beginnt mit --- und trägt members: [chris.dietz]. Chris ist nun in Team Web und Team Kunde. Owned zeigt für Thomas Zachmann keine Component mehr – tracking-web gehört nicht mehr Team Web.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Niemand pflegt org.yaml für 5000 Mitarbeitende von Hand. Entity-Provider lesen Users und Groups aus LDAP (catalog-backend-module-ldap), Microsoft Entra ID (catalog-backend-module-msgraph), GitHub- oder GitLab-Orgs.
  • Die Org-Daten gehören in Locations aus der Konfiguration mit allow: [User, Group]. Global erlaubte Groups machen Ownership fälschbar.
  • Owner sind Teams, nicht Personen: Menschen wechseln, Teams bleiben. Ein Owner-Check wie in Drill 1 gehört als Gate in die CI der Katalog-Repos.
  • Der Guest-Provider mit userEntityRef ist nur ein Lab-Werkzeug. In Produktion löst ein Sign-in-Resolver den echten Login auf eine User-Entity auf, z. B. per E-Mail (Tag 12).
  • Ownership ist die Grundlage für Berechtigungen: Regeln wie „nur Owner dürfen löschen” setzen gepflegte Gruppen und Mitgliedschaften voraus.