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/orgin einer Dateiorg.yaml. - Die Hierarchie entsteht aus
spec.parent(Gruppe) undspec.memberOf(User). Die Gegenrichtung (parentOf,hasMember) ergänzt der Katalog selbst. spec.owner: team-sendungwird zur RelationownedBy → 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- Öffne
http://localhost:3000, klicke auf Enter und dann aufsendungs-api. - Erwartet: die gelbe Warnung wie in der Abbildung,
Owner zeigt nur den nackten Namen
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.shErwartet:
✘ 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.yamlErwartet:
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/orgErwartet:
✔ 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.messageErwartet (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.yamlsteht, lösche ihn. Beide Dateien definierengroup: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)"' | sortErwartet:
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
- Lade die Entity-Seite von
sendungs-apineu. - Erwartet: keine Warnung mehr, Owner zeigt jetzt den
displayName„Team Sendung” als Link – wie in der Abbildung.
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
- Klicke auf der Entity-Seite von
sendungs-apiauf Team Sendung. - 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.
- 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.
- Klicke in der Profilkarte auf IT. Die Abteilung hat weder Mitglieder noch eigene Entities – Ownership ist leer.
- Schalte in Ownership den Schalter Include indirect ownership ein.
- Erwartet: die Summe aller drei Teams wie in der Abbildung.
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-orgund lassen sich inapp.extensionskonfigurieren, z. B.entity-card:org/ownershipmitconfig.initialRelationAggregation: aggregated(Tag 9).
Fortschritt speichern? Kostenlos registrieren
Drill 6: Die User-Seite
- Klicke in der Sidebar auf Catalog, stelle
Kind auf
Userund öffnethomas.zachmann. - Erwartet: die User-Seite wie in der Abbildung – Profilkarte mit E-Mail und den Gruppen Team Plattform und Team Web, darunter 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
- Klicke auf Catalog und links unter PERSONAL auf Owned.
- 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.identityErwartet (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.
- Öffne Settings, klicke im Profil auf ⋮ und Sign Out, dann wieder Enter.
- Erwartet: Unter Profile steht
user:default/thomas.zachmann, die Karte Backstage Identity zeigt die Identität wie in der Abbildung.
- Klicke auf Catalog und Owned.
Erwartet: „Owned Components (1)” mit
tracking-webwie in der Abbildung.
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:
- Öffne die Gruppe Kranich Logistik GmbH (über Parent Group von IT) und klicke in Relations auf View graph.
- Setze MAX DEPTH auf
3, wähle unter KINDS nurGroupundUserund unter DirectionTop to bottom. - Erwartet: der Organigramm-Graph wie in der Abbildung. Thomas Zachmann hängt an zwei Teams.
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.shErwartet:
✔ 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.yamlfü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
userEntityRefist 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.