Skip to content
Hands-on IT IT Drills

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.sh all ✔, 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 container bs-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 or POST catalog/locations – Task 4 checks that.
  • You run templates as thomas.zachmann (Team Plattform, Day 12) or via bs scaffolder/v2/tasks. Since Day 12, the guest is no longer allowed to start templates.
  • The script pruefung.sh awards 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 -2

Expected:

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(" ")'
done

Expected:

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 -3

Expected:

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)"' \
  | sort

Expected:

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 EntityPicker that 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 annotation backstage.io/techdocs-ref.
  • The owner is always team-fuhrpark, without a selection field.
  • Repo via publish:gitea, then catalog: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.

Wizard fuhrpark-service: system via EntityPicker, checkbox with TechDocs

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' ' '; echo

Expected:

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.

Catalog: the three components of Team Fuhrpark

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 -u

Expected (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.

  1. 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).
  2. Backup (+5): Back up the catalog database with pg_dump in custom format to ~/backstage-lab/pruefung/catalog.dump after fahrzeug-ortung is in the catalog (Day 13, Challenge). Without a running container bs-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 -1

Expected:

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.sh

Expected 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.yaml to org.yaml in kranich/org and push. The group needs children: [], the users have memberOf: [team-fuhrpark].
  • A2–A4 (Day 2, Drill 2; Day 3, Drill 4): create the folder flottenmanagement/ with catalog-info.yaml (six entities) and openapi.yaml as a repo via mkrepo.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/flottenmanagement

The 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 cloned kranich/templates, append the line - ./fuhrpark-service/template.yaml to templates.yaml, push, refresh location:default/kranich-templates. Compared with node-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: true

The 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.zachmann in the wizard or via the API with werte.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, under home-page-widget:home/toolkit → config.tools, add an entry, then portal.sh restart. Not in app-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 to getUserInfo, add dedicated handling for catalog.entity.delete. You know the imports isResourcePermission, catalogConditions and createCatalogConditionalDecision from 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)"'
done

Expected:

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.dump

The 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 -2

Expected:

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.

  1. Why can’t you simply define team-fuhrpark in kranich/flottenmanagement, even though the Gitea provider reads that repo?
  2. The system belongs to the domain, but the domain’s page doesn’t show it. Where do you look first?
  3. Why does discovery report a conflict for fahrzeug-ortung, but not for flottenmanagement?
  4. What value does the EntityPicker return, and why does it still work in spec.system?
  5. The checkbox mit TechDocs is off. Which steps run, and what is in the log?
  6. Search finds fahrzeug-ortung as a component, but no docs. Name two reasons.
  7. Why does the toolkit suddenly have only one link after adding an entry under app.extensions only in app-config.local.yaml?
  8. Why does a policy rule for catalog.entity.delete have no effect on the lab token lab-cli?

Answer key

  1. The global catalog.rules allow User and Group only at the location of kranich/org (Day 4). Otherwise any repo could create groups and grab ownership by the back door.
  2. In the system’s entity: spec.domain is misspelled, or the domain has a processing error. The relation partOf only points to an existing entity (Day 2, Day 14).
  3. catalog:register has already created a location for fahrzeug-ortung. The provider creates the same location again and is rejected (Day 3, Day 5).
  4. A full reference such as system:default/flottenmanagement. spec.system also accepts references with kind and namespace (Day 6).
  5. All except the one with if: – the log reports Skipping step techdocs because its if condition was false, and catalog-info.yaml has no annotation (Day 6).
  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).
  7. Lists in app-config*.yaml are replaced, not merged. The list from the local file pushes out the entire list from app-config.yaml (Day 9).
  8. lab-cli is a service principal. For it, the framework decides without the policy; it can only be restricted with accessRestrictions (Day 12).