Appendix B: Final Exam
Goal: Prove that you can take a new business domain through the entire portal on your own: catalog, organization, golden path, TechDocs, search, home page and operations. · Duration: 120 min hands-on + 20 min questions · Prerequisite: Day 14
Rules
- Training ground as after Day 14:
check.shall ✔, Gitea provider (Day 3),kranich/org(Day 4),kranich/templates(Day 5), venv for TechDocs (Day 7), home page (Day 9), policy (Day 12), Postgres in the containerbs-postgres(Day 13). - Allowed: Appendix A, backstage.io/docs, your companion code from
Days 0 to 14. Not allowed: looking into
code/anhang-b/loesung/. - The working folder is
~/backstage-lab/pruefung. Do not register anything via Register Existing Component orPOST catalog/locations– Task 4 checks that. - You run templates as
thomas.zachmann(Team Plattform, Day 12) or viabs scaffolder/v2/tasks. Since Day 12, the guest is no longer allowed to start templates. - The script
pruefung.shawards the points. It changes nothing. Passed: at least 70 of 100 points and full points on Task 1. Task 10 brings bonus points but does not count toward the total.
source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/check.sh | grep ✘ || echo "Gelände ok"
docker start bs-postgres >/dev/null && ~/backstage-lab/setup/portal.sh start
mkdir -p ~/backstage-lab/pruefung && cd ~/backstage-lab/pruefung
bash ~/backstage-lab/code/anhang-b/pruefung.sh | tail -2Expected:
Gelände ok
✔ läuft bereits: http://localhost:3000
Summe: 0 von 100 (Aufgabe 1: 0 von 10, Bonus: 0 von 10)
✘ NICHT BESTANDEN
Scenario
Kranich Logistik brings its vehicle fleet in-house. A new team takes it over and gets its own domain in the portal:
Domain fuhrpark ── System flottenmanagement Owner: team-fuhrpark
├─ Component fahrzeug-api ──provides──► API fahrzeug-api
│ └─dependsOn──► Resource fahrzeug-db (OpenAPI)
├─ Component fahrtenbuch-web ──consumes──┘
└─ Component fahrzeug-ortung (via template, with TechDocs)
| Name | Kind | Repo |
|---|---|---|
team-fuhrpark, dana.engel,
emil.fischer |
Group, User | kranich/org |
fuhrpark, flottenmanagement |
Domain, System | kranich/flottenmanagement |
fahrzeug-db, fahrzeug-api,
fahrtenbuch-web |
Resource, API, Component | kranich/flottenmanagement |
fuhrpark-service |
Template | kranich/templates |
fahrzeug-ortung |
Component | kranich/fahrzeug-ortung |
The names are mandatory; the script looks for exactly these. You
choose descriptions, titles and texts yourself. The names
lager-* have been taken since Days 5 and 6, which is why
the new domain is not called “Lager” (warehouse).
Tasks
Each task names the goal, not the path. The check command below it shows you whether you are done. The days in parentheses tell you where to find the tool. The outputs come from a test run with the sample solution.
| Task | Points | Time |
|---|---|---|
| 1 Team Fuhrpark (mandatory) | 10 | 10 min |
| 2 Domain, System, Resource | 15 | 15 min |
| 3 Components and API | 15 | 15 min |
| 4 Discovery instead of registration | 10 | 5 min |
| 5 Template fuhrpark-service | 15 | 25 min |
| 6 Create fahrzeug-ortung | 10 | 10 min |
| 7 TechDocs with two pages | 10 | 10 min |
| 8 Search | 5 | 5 min |
| 9 Home page | 10 | 10 min |
| 10 Extra: policy and backup | +10 | 15 min |
| Total | 100 | 120 min |
Task 1: Team Fuhrpark (10 points, mandatory)
In kranich/org, add the group team-fuhrpark
(type team) under it, with the members
dana.engel and emil.fischer (Day 4).
org.yaml is already registered as a location – no restart
needed.
bs catalog/entities/by-name/group/default/team-fuhrpark | jq -r '.relations[]
| select(.type == "hasMember" or .type == "childOf") | "\(.type) \(.targetRef)"'Expected:
childOf group:default/it
hasMember user:default/dana.engel
hasMember user:default/emil.fischer
Task 2: Domain, System, Resource (15 points)
New repo kranich/flottenmanagement with a
catalog-info.yaml: domain fuhrpark, inside it
the system flottenmanagement, plus the resource
fahrzeug-db of type database in the system.
The owner is team-fuhrpark everywhere (Day 2).
for r in domain/default/fuhrpark system/default/flottenmanagement \
resource/default/fahrzeug-db; do
bs catalog/entities/by-name/$r | jq -r '[.kind, .metadata.name,
(.relations[] | select(.type == "partOf" or .type == "ownedBy")
| .targetRef)] | join(" ")'
doneExpected:
Domain fuhrpark group:default/team-fuhrpark
System flottenmanagement group:default/team-fuhrpark domain:default/fuhrpark
Resource fahrzeug-db group:default/team-fuhrpark system:default/flottenmanagement
Task 3: Components and API (15 points)
In the same repo: component fahrzeug-api (type
service) provides the API fahrzeug-api and
depends on fahrzeug-db. Component
fahrtenbuch-web (type website) consumes the
API. The API is of type openapi; its definition lives as
openapi.yaml in the repo and is included via
$text (Day 1, Day 2, Day 8).
bs catalog/entities/by-name/component/default/fahrzeug-api | jq -r '.relations[]
| select(.type | test("providesApi|dependsOn")) | "\(.type) \(.targetRef)"'
bs catalog/entities/by-name/api/default/fahrzeug-api \
| jq -r '.spec.definition' | head -3Expected:
dependsOn resource:default/fahrzeug-db
providesApi api:default/fahrzeug-api
openapi: 3.0.3
info:
title: Fahrzeug-API
Task 4: Discovery instead of registration (10 points)
All entities from Tasks 2 and 3 get into the catalog via the Gitea provider, not via a registered location. None of them has a processing error (Day 3, Day 14).
bs catalog/locations | jq '[.[] | select(.data.target
| test("flottenmanagement"))] | length'
F='relations.ownedBy=group:default/team-fuhrpark'
bs "catalog/entities?filter=$F&fields=kind,metadata.name,status" \
| jq -r '.[] | "\(.kind) \(.metadata.name) \(.status.items // [] | length)"' \
| sortExpected:
0
API fahrzeug-api 0
Component fahrtenbuch-web 0
Component fahrzeug-api 0
Domain fuhrpark 0
Resource fahrzeug-db 0
System flottenmanagement 0
The last number is the number of processing errors. After Tasks 5 and
6, Template fuhrpark-service and
Component fahrzeug-ortung are added.
Task 5: Template fuhrpark-service (15 points)
New template fuhrpark-service in
kranich/templates, derived from node-service
(Day 5, Day 6):
- A System field as an
EntityPickerthat offers only systems. - A checkbox mit TechDocs (with TechDocs; default:
on). If it is checked, the repo gets
mkdocs.yml, two doc pages and the annotationbackstage.io/techdocs-ref. - The owner is always
team-fuhrpark, without a selection field. - Repo via
publish:gitea, thencatalog:register.
bs catalog/entities/by-name/template/default/fuhrpark-service | jq -c '
[.spec.parameters[].properties | to_entries[]
| {(.key): (.value["ui:field"] // .value.type)}] | add'Expected (wrapped):
{"name":"EntityNamePicker","description":"string","system":"EntityPicker",
"techdocs":"boolean","repoUrl":"RepoUrlPicker"}
In the wizard under Create, the first step then
looks like the figure. If there is only one matching system, the
EntityPicker selects it by itself and locks the field.
Task 6: Create fahrzeug-ortung (10 points)
Use the template to create the component fahrzeug-ortung
in the system flottenmanagement, with TechDocs, repo
kranich/fahrzeug-ortung (Day 5, Day 6).
bs catalog/entities/by-name/component/default/fahrzeug-ortung | jq -r '
.relations[] | select(.type == "partOf" or .type == "ownedBy") | .targetRef'
curl -sf -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/fahrzeug-ortung/contents" \
| jq -r '.[].path' | tr '\n' ' '; echoExpected:
group:default/team-fuhrpark
system:default/flottenmanagement
README.md catalog-info.yaml docs mkdocs.yml package.json src
Afterwards, in the catalog filtered to kind Component and owner Team Fuhrpark, there are three components, as in the figure.
Task 7: TechDocs with two pages (10 points)
The docs of fahrzeug-ortung are built and have at least
two pages in the navigation (Day 7). To do that, open the
TechDocs tab once.
D=techdocs/static/docs/default/component/fahrzeug-ortung
bs $D/search/search_index.json \
| jq -r '.docs[] | select(.location | contains("#") | not) | .title'Expected:
Start
Betrieb
The titles come from the navigation in mkdocs.yml.
Task 8: Search (5 points)
Searching for fahrzeug-ortung finds the component and
its docs (Day 8). The collator runs every minute.
bs 'search/query?term=fahrzeug-ortung' \
| jq -r '.results[] | "\(.type) \(.document.location)"' | sort -uExpected (the entries with # are headings within the
pages):
software-catalog /catalog/default/component/fahrzeug-ortung
techdocs /docs/default/component/fahrzeug-ortung/
techdocs /docs/default/component/fahrzeug-ortung/#fahrzeug-ortung
techdocs /docs/default/component/fahrzeug-ortung/betrieb/
techdocs /docs/default/component/fahrzeug-ortung/betrieb/#bereitschaft
techdocs /docs/default/component/fahrzeug-ortung/betrieb/#betrieb
techdocs /docs/default/component/fahrzeug-ortung/betrieb/#start
Task 9: Home page (10 points)
The toolkit on the home page gets a link
Flottenmanagement to the system page
/catalog/default/system/flottenmanagement. The other links
stay (Day 9).
cd ~/backstage-lab/portal
yarn backstage-cli config:print --frontend --format json 2>/dev/null \
| jq -r '.app.extensions[] | objects | .["home-page-widget:home/toolkit"]
// empty | .config.tools[].label'Expected:
Flottenmanagement
Forgejo
Neues Projekt
TechDocs
Backstage-Doku
Task 10: Extra – policy and backup (+10 bonus)
Both parts are optional.
- Policy (+5): Only Team Fuhrpark may delete entities
with owner
team-fuhrpark. Team Plattform keeps the right to delete everything else (Day 12 with the Challenge). - Backup (+5): Back up the catalog database with
pg_dumpin custom format to~/backstage-lab/pruefung/catalog.dumpafterfahrzeug-ortungis in the catalog (Day 13, Challenge). Without a running containerbs-postgres, the script skips this part.
docker exec -i bs-postgres pg_restore -f - -a -t final_entities \
< ~/backstage-lab/pruefung/catalog.dump \
| grep -o 'component:default/fahrzeug-ortung' | head -1Expected:
component:default/fahrzeug-ortung
The script checks the policy only statically (source code and
index.ts): a user token of a Fuhrpark member is only
available through the browser login (Day 12). The counter-check is in
the sample solution.
Exam script
The script is at
~/backstage-lab/code/anhang-b/pruefung.sh. It only queries:
catalog, scaffolder, TechDocs and search via bs, Forgejo
via curl, the home page via config:print, the
backup via pg_restore. The core:
pt() { # pt <task> <points> <text> <bash expression>
if eval "$4" >/dev/null 2>&1; then
echo "✔ A$1 $3 (+$2)"; pts[$1]=$((pts[$1] + $2))
else
echo "✘ A$1 $3 (0 von $2)"
fi
}
e() { bs "catalog/entities/by-name/$1"; } # e kind/namespace/name
has() { e "$1" | jq -e "$2"; } # has <ref> <jq filter>
rel() { has "$1" "any(.relations[]; .type == \"$2\" and .targetRef == \"$3\")"; }Each check is one line. It evaluates relations instead of
spec fields – so owner: team-fuhrpark counts
just like owner: group:default/team-fuhrpark:
pt 2 5 "System flottenmanagement in Domain fuhrpark" \
"rel system/default/flottenmanagement partOf domain:default/fuhrpark &&
rel system/default/flottenmanagement ownedBy $T"
pt 5 4 "EntityPicker für System" "has $TPL '$EP'"Task 4 relies on the fact that catalog/locations returns
only locations registered via the API. What the Gitea provider creates
does not appear there. You choose the container for the backup with
PG=…; the default is bs-postgres.
bash ~/backstage-lab/code/anhang-b/pruefung.shExpected with a complete solution (shortened):
== Teil 1: Katalog
✔ A1 Group team-fuhrpark (team) unter it (+4)
✔ A1 mindestens zwei User in team-fuhrpark (+4)
✔ A1 Team stammt aus kranich/org (+2)
...
✔ A4 Repo kranich/flottenmanagement per Discovery, nicht registriert (+5)
✔ A4 alle Entities von team-fuhrpark ohne Processing-Fehler (+5)
== Teil 2: Golden Path
...
✔ A8 Suche findet die TechDocs (+2)
== Teil 3: Plattform
✔ A9 Toolkit verlinkt das System flottenmanagement (+6)
✔ A9 Toolkit behält dabei den Forgejo-Link (+4)
== Zusatz (optional, Bonus)
✔ A10 Policy: Löschen von Fuhrpark-Entities nur für team-fuhrpark (+5)
✔ A10 Backup pruefung/catalog.dump enthält fahrzeug-ortung (+5)
Summe: 100 von 100 (Aufgabe 1: 10 von 10, Bonus: 10 von 10)
✔ BESTANDEN
Against a training ground without a solution (shortened):
== Teil 1: Katalog
✘ A1 Group team-fuhrpark (team) unter it (0 von 4)
✘ A1 mindestens zwei User in team-fuhrpark (0 von 4)
...
✘ A9 Toolkit behält dabei den Forgejo-Link (0 von 4)
== Zusatz (optional, Bonus)
✘ A10 Policy: Löschen von Fuhrpark-Entities nur für team-fuhrpark (0 von 5)
✘ A10 Backup pruefung/catalog.dump enthält fahrzeug-ortung (0 von 5)
Summe: 0 von 100 (Aufgabe 1: 0 von 10, Bonus: 0 von 10)
✘ NICHT BESTANDEN
The exit code is 0 on passing, otherwise 1 – handy for a pipeline.
Sample solution
Read this only after the exam. All files are in
~/backstage-lab/code/anhang-b/loesung/.
- A1 (Day 4, Drill 2): append
org/team-fuhrpark.yamltoorg.yamlinkranich/organd push. The group needschildren: [], the users havememberOf: [team-fuhrpark]. - A2–A4 (Day 2, Drill 2; Day 3, Drill 4): create the
folder
flottenmanagement/withcatalog-info.yaml(six entities) andopenapi.yamlas a repo viamkrepo.sh. Don’t register it: the provider finds the repo within a minute at most.
cd ~/backstage-lab/pruefung
L=~/backstage-lab/code/anhang-b/loesung
~/backstage-lab/setup/mkrepo.sh kranich/flottenmanagement $L/flottenmanagementThe crucial part of catalog-info.yaml:
kind: Component
metadata:
name: fahrzeug-api
spec:
type: service
lifecycle: experimental
owner: team-fuhrpark
system: flottenmanagement
providesApis: [fahrzeug-api]
dependsOn: [resource:fahrzeug-db]- A5 (Day 6, Drill 3 and Challenge): put the folder
fuhrpark-service/into the clonedkranich/templates, append the line- ./fuhrpark-service/template.yamltotemplates.yaml, push, refreshlocation:default/kranich-templates. Compared withnode-service, the form changes like this:
system:
title: System
type: string
description: Nur Systems der Domain Fuhrpark
ui:field: EntityPicker
ui:options:
catalogFilter:
kind: System
spec.domain: fuhrpark
defaultKind: System
allowArbitraryValues: false
techdocs:
title: mit TechDocs
type: boolean
default: trueThe owner is fixed in the values of the step
fetch (owner: group:default/team-fuhrpark);
the step techdocs, with
if: ${{ parameters.techdocs }}, fetches the folder
techdocs/ with mkdocs.yml (navigation Start
and Betrieb), docs/index.md and
docs/betrieb.md. The template doesn’t need the ticket step
from Day 6.
- A6 (Day 6, Drill 7): as
thomas.zachmannin the wizard or via the API withwerte.json:
ID=$(bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' \
-d @$L/werte.json | jq -r .id)
bs scaffolder/v2/tasks/$ID | jq -r .status- A7 (Day 7, Drill 5): open the
TechDocs tab or run
bs techdocs/sync/default/component/fahrzeug-ortung -N. - A8 (Day 8, Drill 5): nothing to do except wait. The TechDocs collator only finds docs that are already built – that’s why A7 comes first.
- A9 (Day 9, Drill 3): in
app-config.yaml, underhome-page-widget:home/toolkit→config.tools, add an entry, thenportal.sh restart. Not inapp-config.local.yaml: that list would replace the whole list.
- url: /catalog/default/system/flottenmanagement
label: Flottenmanagement
icon: kind:system- A10, policy (Day 12, Drill 6 and Challenge): in
packages/backend/src/modules/permissionPolicy.ts, after the call togetUserInfo, add dedicated handling forcatalog.entity.delete. You know the importsisResourcePermission,catalogConditionsandcreateCatalogConditionalDecisionfrom the Day 12 Challenge. Complete file:loesung/permissionPolicy.ts.
const FUHRPARK = 'group:default/team-fuhrpark';
// … in handle(), after getUserInfo():
if (
isResourcePermission(request.permission, 'catalog-entity') &&
request.permission.name === 'catalog.entity.delete'
) {
const gehoertFuhrpark = catalogConditions.isEntityOwner({
claims: [FUHRPARK],
});
if (ownershipEntityRefs.includes(FUHRPARK)) {
return createCatalogConditionalDecision(request.permission, gehoertFuhrpark);
}
if (ownershipEntityRefs.includes(PLATTFORM)) {
return createCatalogConditionalDecision(request.permission, {
not: gehoertFuhrpark,
});
}
return { result: AuthorizeResult.DENY };
}The catalog itself checks the condition against the relation
ownedBy. Counter-check without a Forgejo login: temporarily
attach the guest to Dana (userEntityRef from Day 4) and ask
the permission backend directly, with the guest’s token:
cd ~/backstage-lab/portal && cp app-config.local.yaml app-config.local.yaml.vorher
yq -i '.auth.providers.guest.userEntityRef = "user:default/dana.engel"' \
app-config.local.yaml
~/backstage-lab/setup/portal.sh restart >/dev/null
tok=$(curl -s "$BACKSTAGE/api/auth/guest/refresh" \
-H 'X-Requested-With: XMLHttpRequest' | jq -r .backstageIdentity.token)
for e in component:default/fahrzeug-api component:default/sendungs-api; do
jq -n --arg r "$e" '{items: [{id: "1", resourceRef: $r, permission: {
type: "resource", name: "catalog.entity.delete",
attributes: {action: "delete"}, resourceType: "catalog-entity"}}]}' \
| curl -s -X POST "$BACKSTAGE/api/permission/authorize" \
-H "Authorization: Bearer $tok" -H 'Content-Type: application/json' -d @- \
| jq -r --arg r "$e" '"\($r) \(.items[0].result)"'
doneExpected:
component:default/fahrzeug-api ALLOW
component:default/sendungs-api DENY
With user:default/thomas.zachmann instead of Dana, it’s
the other way round (DENY, then ALLOW).
Afterwards, run
mv app-config.local.yaml.vorher app-config.local.yaml and
portal.sh restart. In the GUI, the same shows up after
signing in as Dana via Forgejo (Day 12, Drill 1) at the menu item
Unregister entity (not tested live).
- A10, backup (Day 13, Challenge):
docker exec bs-postgres pg_dump -U backstage -Fc backstage_plugin_catalog \
> ~/backstage-lab/pruefung/catalog.dumpThe script loesung/loesung.sh replays everything except
the policy (35 seconds in the test run, followed by
portal.sh restart for the home page and two minutes for the
search index):
bash ~/backstage-lab/code/anhang-b/loesung/loesung.sh
~/backstage-lab/setup/portal.sh restart && sleep 120
bash ~/backstage-lab/code/anhang-b/pruefung.sh | tail -2Expected:
Summe: 100 von 100 (Aufgabe 1: 10 von 10, Bonus: 5 von 10)
✔ BESTANDEN
With loesung/permissionPolicy.ts in
packages/backend/src/modules/ (followed by
yarn tsc and portal.sh restart), the
second-to-last line reads Bonus: 10 von 10.
Knowledge questions
Answer each question in one or two sentences, without notes. At least 6 of 8 should be right.
- Why can’t you simply define
team-fuhrparkinkranich/flottenmanagement, even though the Gitea provider reads that repo? - The system belongs to the domain, but the domain’s page doesn’t show it. Where do you look first?
- Why does discovery report a conflict for
fahrzeug-ortung, but not forflottenmanagement? - What value does the
EntityPickerreturn, and why does it still work inspec.system? - The checkbox mit TechDocs is off. Which steps run, and what is in the log?
- Search finds
fahrzeug-ortungas a component, but no docs. Name two reasons. - Why does the toolkit suddenly have only one link after adding an
entry under
app.extensionsonly inapp-config.local.yaml? - Why does a policy rule for
catalog.entity.deletehave no effect on the lab tokenlab-cli?
Answer key
- The global
catalog.rulesallow User and Group only at the location ofkranich/org(Day 4). Otherwise any repo could create groups and grab ownership by the back door. - In the system’s entity:
spec.domainis misspelled, or the domain has a processing error. The relationpartOfonly points to an existing entity (Day 2, Day 14). catalog:registerhas already created a location forfahrzeug-ortung. The provider creates the same location again and is rejected (Day 3, Day 5).- A full reference such as
system:default/flottenmanagement.spec.systemalso accepts references with kind and namespace (Day 6). - All except the one with
if:– the log reportsSkipping step techdocs because its if condition was false, andcatalog-info.yamlhas no annotation (Day 6). - The docs have never been built (tab never opened, no
techdocs/sync), or the TechDocs collator hasn’t run since the build (Day 8). - Lists in
app-config*.yamlare replaced, not merged. The list from the local file pushes out the entire list fromapp-config.yaml(Day 9). lab-cliis a service principal. For it, the framework decides without the policy; it can only be restricted withaccessRestrictions(Day 12).