Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 5: Software Templates

Ziel: Du baust einen Golden Path, der per Klick ein neues Forgejo-Repo anlegt, es mit Code füllt und die neue Component im Katalog einträgt. · Dauer: ca. 120 min · Voraussetzung: Tag 4

Briefing

  • Ein Software Template ist eine Entity vom Kind Template. Sie besteht aus parameters (Formular), steps (Actions im Backend) und output (Links).
  • Der Scaffolder führt die Steps als Task aus. Jeder Lauf hat ein Log.
  • fetch:template rendert ein Skeleton mit Nunjucks (${{ values.name }}), publish:gitea legt das Repo an, catalog:register trägt es ein.
Wizard (Formular)  ──►  Task im Scaffolder-Backend
 name, owner,          fetch:template ─► publish:gitea ─► catalog:register
 repoUrl                 skeleton/        kranich/<name>    Component im Katalog

Drill 1: Gitea-Modul für den Scaffolder

Ausgangslage ist das Ende von Tag 4: Der Gitea-Provider aus Tag 3 findet alle kranich/*-Repos, die Gruppen team-sendung, team-web und plattform stammen aus kranich/org. Der Scaffolder kann aber nur zu GitHub publizieren:

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
bs scaffolder/v2/actions | jq -r '.[].id' | grep '^publish'

Erwartet:

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
publish:github
publish:github:pull-request

Das Modul für Gitea (und damit Forgejo) installierst du ins Backend:

~/backstage-lab/setup/portal.sh stop
cd ~/backstage-lab/portal
yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-gitea
grep scaffolder-backend-module-gitea packages/backend/package.json

Erwartet (gekürzt):

➤ YN0000: · Done with warnings in 12s 547ms
    "@backstage/plugin-scaffolder-backend-module-gitea": "^0.2.25",

Öffne packages/backend/src/index.ts und ergänze direkt unter der Zeile mit plugin-scaffolder-backend-module-github:

backend.add(import('@backstage/plugin-scaffolder-backend-module-gitea'));
grep -n 'scaffolder-backend' packages/backend/src/index.ts

Erwartet:

17:backend.add(import('@backstage/plugin-scaffolder-backend'));
18:backend.add(import('@backstage/plugin-scaffolder-backend-module-github'));
19:backend.add(import('@backstage/plugin-scaffolder-backend-module-gitea'));
21:  import('@backstage/plugin-scaffolder-backend-module-notifications'),

Das Modul liest die Zugangsdaten aus integrations.gitea in app-config.local.yaml. Dort steht seit Tag 0 der Bot backstage-bot, und der ist im Owners-Team der Org kranich. Die Action darf also Repos in der Org anlegen. Gestartet wird erst in Drill 3.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Template-Repo kranich/templates

Ein Template besteht aus template.yaml und einem Ordner skeleton/, der als Vorlage für das neue Repo dient. Zuerst die Template-Definition:

mkdir -p ~/backstage-lab/tag05/templates/node-service/skeleton/src
cd ~/backstage-lab/tag05/templates
cat > node-service/template.yaml <<'EOF'
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-service
  title: Node.js-Service
  description: Neuer Node.js-Service mit Repo in Forgejo und Katalog-Eintrag
  tags: [nodejs, kranich]
spec:
  owner: plattform
  type: service
  parameters:
    - title: Service
      required: [name, description, owner]
      properties:
        name:
          title: Name
          type: string
          description: Kleinbuchstaben, Ziffern, Bindestriche (z. B. lager-api)
          pattern: '^[a-z][a-z0-9-]{2,30}$'
          ui:autofocus: true
        description:
          title: Beschreibung
          type: string
          description: Ein Satz – erscheint in Forgejo und im Katalog
        owner:
          title: Owner
          type: string
          description: Team, das den Service betreut
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
              spec.type: team
    - title: Repository
      required: [repoUrl]
      properties:
        repoUrl:
          title: Ablageort
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts: ['127.0.0.1:3300']
            allowedOwners: [kranich]
  steps:
    - id: fetch
      name: Skeleton füllen
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
    - id: publish
      name: Repo in Forgejo anlegen
      action: publish:gitea
      input:
        repoUrl: ${{ parameters.repoUrl }}
        description: ${{ parameters.description }}
        defaultBranch: main
        repoVisibility: public
        gitCommitMessage: Erzeugt aus Template node-service
        gitAuthorName: Backstage Scaffolder
        gitAuthorEmail: [email protected]
    - id: register
      name: Im Katalog registrieren
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: catalog-info.yaml
  output:
    links:
      - title: Repository in Forgejo
        url: ${{ steps.publish.output.repoContentsUrl }}
      - title: Im Katalog öffnen
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}
EOF

Die wichtigsten Stellen:

Stelle Bedeutung
parameters zwei Listeneinträge = zwei Wizard-Schritte (JSON Schema)
OwnerPicker Auswahl aus dem Katalog, gefiltert auf Gruppen vom Typ team
RepoUrlPicker erkennt 127.0.0.1:3300 als Gitea-Host und liefert host?owner=…&repo=…
steps.publish.output Ausgaben einer Action: remoteUrl, repoContentsUrl, commitHash

publish:gitea verlangt repoUrl und description. defaultBranch (Standard main), repoVisibility (public/private, Standard public) und die Git-Angaben sind optional.

Jetzt das Skeleton. Alles in ${{ … }} ersetzt fetch:template beim Lauf durch die Werte aus values. Das Quoting 'EOF' verhindert, dass die Shell $ anfasst.

cat > node-service/skeleton/catalog-info.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name }}
  description: ${{ values.description | dump }}
  tags: [nodejs]
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner }}
EOF
cat > node-service/skeleton/package.json <<'EOF'
{
  "name": "${{ values.name }}",
  "version": "0.1.0",
  "description": ${{ values.description | dump }},
  "main": "src/index.js",
  "scripts": { "start": "node src/index.js" },
  "license": "UNLICENSED"
}
EOF
cat > node-service/skeleton/src/index.js <<'EOF'
// ${{ values.name }} – erzeugt aus dem Template node-service
const http = require('node:http');

const port = process.env.PORT || 8080;
http
  .createServer((req, res) => {
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify({ service: '${{ values.name }}', status: 'ok' }));
  })
  .listen(port, () => console.log('${{ values.name }} lauscht auf Port', port));
EOF

Die README des Skeletons enthält selbst einen Codeblock. Nimm sie aus dem Begleitcode, statt sie abzutippen:

cp ~/backstage-lab/code/tag05/templates/node-service/skeleton/README.md \
  node-service/skeleton/

Warum | dump? Der Nunjucks-Filter macht aus dem Text einen JSON-String mit Anführungszeichen. So bricht eine Beschreibung mit Doppelpunkt weder das YAML noch das JSON.

Zum Schluss eine Location-Datei im Wurzelverzeichnis. Neue Templates bekommen später nur noch eine Zeile unter targets:

cat > templates.yaml <<'EOF'
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: kranich-templates
  description: Alle Software Templates der Kranich Logistik
spec:
  targets:
    - ./node-service/template.yaml
EOF
~/backstage-lab/setup/mkrepo.sh kranich/templates ~/backstage-lab/tag05/templates

Erwartet:

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

Die Datei heißt absichtlich nicht catalog-info.yaml. Sonst würde der Gitea-Provider aus Tag 3 sie einlesen, und dort gelten die globalen Regeln ohne Template.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Template registrieren, Beispiel ausblenden

Seit Tag 3 erlaubt catalog.rules in app-config.local.yaml nur Component, System, API, Resource, Location und Domain. Templates kommen erst durch eine zusätzliche Regel durch. Ändere den Block catalog: in ~/backstage-lab/portal/app-config.local.yaml an drei Stellen:

  1. Unter rules: einen zweiten Eintrag ergänzen:
    # Tag 5: Templates nur aus dem Repo kranich/templates
    - allow: [Template]
      locations:
        - type: url
          pattern: http://127.0.0.1:3300/kranich/templates/**
  1. Unter locations: den Eintrag ../../examples/template/template.yaml samt seinen rules löschen. Damit verschwindet das Beispiel-Template aus create-app.
  2. Unter locations: am Ende ergänzen:
    # Tag 5: Software Templates aus kranich/templates
    - type: url
      target: http://127.0.0.1:3300/kranich/templates/src/branch/main/templates.yaml

Achtung: rules direkt an einer Location gelten nur für genau diese Datei (exakter Vergleich des Ziels), nicht für die Dateien unter targets. Ein allow: [Template] an templates.yaml würde node-service/template.yaml also nicht freischalten. Die Regel mit pattern unter catalog.rules deckt das ganze Repo ab.

~/backstage-lab/setup/portal.sh restart
sleep 30
bs 'catalog/entities?filter=kind=template' \
  | jq -r '.[] | "\(.metadata.name) \(.spec.owner)"'
bs catalog/entities/by-name/location/default/kranich-templates | jq -c .spec.targets

Erwartet:

✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
node-service plattform
["./node-service/template.yaml"]
  1. Klicke in der Sidebar auf Create.
  2. Erwartet: die Seite Templates mit genau einer Karte Node.js-Service wie in der Abbildung. Typ service steht oben, darunter Beschreibung, Tags und der Owner Team Plattform.
Create-Seite mit der Template-Karte Node.js-Service

Die Tabs oben gehören alle zum Scaffolder: Tasks listet alle Läufe, Actions zeigt die installierten Actions mit ihren Ein- und Ausgaben (dort steht jetzt publish:gitea). Template Editor kommt an Tag 6 dran.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der Wizard Schritt für Schritt

  1. Klicke auf der Karte auf CHOOSE. Die Adresse lautet /create/templates/default/node-service.
  2. Trage bei Name lager-api ein, bei Beschreibung Lagerbestände je Depot: API für Scanner und Disposition.
  3. Klicke in Owner und wähle Team Sendung. Die Liste zeigt nur Gruppen vom Typ team: Team Sendung, Team Plattform, Team Web und guests aus den Beispieldaten.
  4. Erwartet: Schritt Service wie in der Abbildung. Der Owner steht als vollständige Entity-Referenz group:default/team-sendung im Feld.
Wizard-Schritt Service mit Name, Beschreibung und Owner

Probier kurz Lager_API als Name: Next bleibt im Schritt und meldet 'Name' must match pattern "^[a-z][a-z0-9-]{2,30}$" – das pattern aus dem JSON Schema. Danach wieder lager-api eintragen.

  1. Klicke auf Next. Schritt Repository zeigt Host und Owner Available ausgegraut, denn beide Listen haben genau einen Wert.
  2. Trage bei Repository lager-api ein.
  3. Erwartet: der Schritt wie in der Abbildung.
Wizard-Schritt Repository mit dem Gitea-Host und der Org kranich

Warum erkennt der Picker Forgejo? Er schlägt den Host aus allowedHosts in den integrations nach. Der Typ ist gitea, also zeigt er die Gitea-Variante mit dem Owner-Feld. Bei GitHub sähe das Feld fast gleich aus, bei GitLab steht dort ein Gruppenpfad.

  1. Klicke auf Review. Erwartet: die Zusammenfassung wie in der Abbildung. Ablageort zeigt das Format, das publish:gitea erwartet: 127.0.0.1:3300?owner=kranich&repo=lager-api.
Review-Schritt mit allen Eingaben vor dem Start

Fortschritt speichern? Kostenlos registrieren

Drill 5: Der Task-Lauf und sein Log

  1. Klicke auf Create. Der Wizard springt auf /create/tasks/<task-id>.
  2. Die drei Steps laufen nacheinander und bekommen je einen grünen Haken. Darunter erscheinen die Links aus output.links, ganz unten das Log.
  3. Erwartet: die Task-Seite wie in der Abbildung.
Task-Seite mit drei erledigten Steps, Ausgabelinks und Log

Im Log siehst du, was publish:gitea tut: lokales Git-Repo im Arbeitsverzeichnis anlegen, alles committen, nach http://127.0.0.1:3300/kranich/lager-api.git pushen. catalog:register meldet die Datei-URL, die es registriert. Mit HIDE LOGS blendest du das Log aus, das Download-Symbol speichert es als Datei.

Derselbe Lauf per API:

bs 'scaffolder/v2/tasks?limit=1' | jq '.tasks[0] | {status, createdBy,
  template: .spec.templateInfo.entityRef, parameters: .spec.parameters}'

Erwartet:

{
  "status": "completed",
  "createdBy": "user:default/thomas.zachmann",
  "template": "template:default/node-service",
  "parameters": {
    "name": "lager-api",
    "description": "Lagerbestände je Depot: API für Scanner und Disposition",
    "owner": "group:default/team-sendung",
    "repoUrl": "127.0.0.1:3300?owner=kranich&repo=lager-api"
  }
}

Achtung: Schreib catalogInfoPath ohne führenden Schrägstrich. Mit /catalog-info.yaml löst Backstage den Pfad gegen die Repo-Wurzel auf und verliert bei Forgejo-URLs den Branch. Im Log steht dann Registering http://127.0.0.1:3300/kranich/lager-api/src/branch/catalog-info.yaml und danach ResponseError: Request failed with 400 Bad Request.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Ergebnis in Forgejo und im Katalog

Zuerst Forgejo:

R=$FORGEJO/api/v1/repos/kranich/lager-api
curl -sf -u "$ADMIN" "$R" | jq '{full_name, description, default_branch, private}'
curl -sf -u "$ADMIN" "$R/contents" | jq -r '.[].path'
curl -sf -u "$ADMIN" "$R/raw/catalog-info.yaml"

Erwartet:

{
  "full_name": "kranich/lager-api",
  "description": "Lagerbestände je Depot: API für Scanner und Disposition",
  "default_branch": "main",
  "private": false
}
README.md
catalog-info.yaml
package.json
src
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: lager-api
  description: "Lagerbestände je Depot: API für Scanner und Disposition"
  tags: [nodejs]
spec:
  type: service
  lifecycle: experimental
  owner: group:default/team-sendung

Der erzeugte Code läuft sofort:

cd ~/backstage-lab/tag05
git clone -q http://127.0.0.1:3300/kranich/lager-api.git && cd lager-api
git log --format='%an | %s'
node src/index.js & sleep 1; curl -s localhost:8080; echo; kill %1

Erwartet:

Backstage Scaffolder | Erzeugt aus Template node-service
lager-api lauscht auf Port 8080
{"service":"lager-api","status":"ok"}

Jetzt der Katalog:

  1. Klicke auf der Task-Seite auf IM KATALOG ÖFFNEN.
  2. Erwartet: die Entity-Seite von lager-api wie in der Abbildung, mit Component • service, Lifecycle experimental, Owner Team Sendung und der Beschreibung aus dem Wizard.
Entity-Seite der neuen Component lager-api
bs catalog/entities/by-name/component/default/lager-api \
  | jq -r '.spec.owner, .metadata.annotations["backstage.io/managed-by-location"]'

Erwartet:

group:default/team-sendung
url:http://127.0.0.1:3300/kranich/lager-api/src/branch/main/catalog-info.yaml

Der Gitea-Provider aus Tag 3 hätte das neue Repo nach spätestens einer Minute auch gefunden. catalog:register macht die Component sofort sichtbar. Weil beide auf dieselbe Datei zeigen, schreibt der Provider danach eine harmlose Warnung ins Log: Source gitea-provider:kranich detected conflicting entityRef location:default/generated-…. Wer Discovery nutzt, kann den Step register auch weglassen.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Fehlerfall – das Repo gibt es schon

Templates scheitern in der Praxis meist an Eingaben. Provoziere den Klassiker:

  1. Klicke auf Create, dann CHOOSE und fülle den Wizard genau wie in Drill 4 aus, also wieder mit lager-api.
  2. Klicke auf Review und Create.
  3. Erwartet: ein roter Balken, der Step Repo in Forgejo anlegen mit Ausrufezeichen, Im Katalog registrieren übersprungen wie in der Abbildung.
Fehlgeschlagener Task: publish meldet 409 Conflict

Das Log nennt die Ursache direkt aus der Forgejo-API. Ohne GUI holst du es dir aus den Events des letzten Tasks:

ID=$(bs 'scaffolder/v2/tasks?limit=1' | jq -r '.tasks[0].id')
bs "scaffolder/v2/tasks/$ID/events" | jq -r '.[]
  | select(.type=="completion" or (.body.message | test("^Error")))
  | .body.message[0:84]'

Erwartet:

Error: Unable to create repository, 409 Conflict, {"message":"The repository with th
Run completed with status: failed

Warum geht nichts kaputt? fetch:template arbeitet nur im temporären Arbeitsverzeichnis. publish:gitea bricht beim Anlegen ab, bevor es pusht, und alle späteren Steps überspringt der Scaffolder. Jetzt korrigieren:

  1. Klicke auf START OVER. Der Wizard öffnet sich mit allen bisherigen Eingaben (sie stehen als formData in der Adresse).
  2. Ändere Name auf lager-worker, klicke Next, ändere Repository auf lager-worker, dann Review und Create.
  3. Erwartet: alle drei Steps grün. Der letzte Task hat den Status completed.

Tipp: Die Prüfung, ob ein Name schon vergeben ist, gehört ins Formular, nicht in den Task. Tag 6 zeigt dafür eigene Feld-Validierungen und EntityNamePicker.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cat > ~/backstage-lab/tag05/kontrollpunkt.sh <<'EOF'
#!/usr/bin/env bash
# kontrollpunkt.sh – Kontrollpunkt Tag 5 (✔/✘). Exit-Code = Anzahl Fehler.
source "${LAB:-$HOME/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; }

t "Action publish:gitea installiert" \
  "bs scaffolder/v2/actions | jq -e '.[] | select(.id==\"publish:gitea\")'"
t "Template node-service registriert (Owner plattform)" \
  "bs catalog/entities/by-name/template/default/node-service \
     | jq -e '.spec.owner==\"plattform\"'"
t "Beispiel-Template ausgeblendet" \
  "! bs catalog/entities/by-name/template/default/example-nodejs-template"
t "Letzter Task completed" \
  "bs 'scaffolder/v2/tasks?limit=1' | jq -e '.tasks[0].status==\"completed\"'"
t "Repo kranich/lager-api mit catalog-info.yaml" \
  "curl -sf -u \$ADMIN \
     \$FORGEJO/api/v1/repos/kranich/lager-api/contents/catalog-info.yaml"
t "Component lager-api im Katalog (Owner team-sendung)" \
  "bs catalog/entities/by-name/component/default/lager-api \
     | jq -e '.spec.owner==\"group:default/team-sendung\"'"
exit "$fail"
EOF
bash ~/backstage-lab/tag05/kontrollpunkt.sh

Erwartet:

✔ Action publish:gitea installiert
✔ Template node-service registriert (Owner plattform)
✔ Beispiel-Template ausgeblendet
✔ Letzter Task completed
✔ Repo kranich/lager-api mit catalog-info.yaml
✔ Component lager-api im Katalog (Owner team-sendung)

Challenge

Erweitere node-service um einen Parameter port (Zahl, Standard 8080, erlaubt 1024 bis 65535). Der Wert soll in src/index.js und in der README landen. Lege damit den Service tour-api für team-web auf Port 8081 an.

Hinweis: Ein neues Feld braucht drei Stellen: properties im ersten Schritt, values im Step fetch und ${{ values.port }} im Skeleton.

Lösung

In template.yaml kommt unter properties des Schritts Service (nach owner) dazu:

        port:
          title: Port
          type: integer
          description: HTTP-Port des Service
          default: 8080
          minimum: 1024
          maximum: 65535

Und im Step fetch unter values:

          port: ${{ parameters.port }}

Die fertige Fassung liegt im Begleitcode. Übernehmen, Skeleton anpassen, pushen und das Template sofort neu einlesen lassen:

cd ~/backstage-lab/tag05
git clone -q http://lab-admin:[email protected]:3300/kranich/templates.git \
  templates-git && cd templates-git/node-service
cp ~/backstage-lab/code/tag05/challenge/node-service/template.yaml .
sed -i '' 's/process.env.PORT || 8080;/process.env.PORT || ${{ values.port }};/' \
  skeleton/src/index.js
sed -i '' 's/curl localhost:8080/curl localhost:${{ values.port }}/' skeleton/README.md
git -c user.name="Lab Admin" -c [email protected] \
  commit -qam "Parameter port" && git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
  -d '{"entityRef":"template:default/node-service"}' -w '%{http_code}\n'

Erwartet:

200

Im Wizard steht jetzt im Schritt Service das Feld Port mit 8080. Trage tour-api, eine Beschreibung, Team Web, Port 8081 und Repository tour-api ein und klicke auf Create. Danach:

curl -sf -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/tour-api/raw/src/index.js" \
  | grep 'const port'
bs catalog/entities/by-name/component/default/tour-api | jq -r .spec.owner

Erwartet:

const port = process.env.PORT || 8081;
group:default/team-web

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Templates gehören wie Code in ein Repo mit Review. Die Regel mit pattern in catalog.rules stellt sicher, dass nur dieses Repo Templates liefern darf.
  • Der Bot-Token aus integrations erzeugt Repos im Namen der Plattform. Wer Repos im Namen der Nutzer anlegen will, nutzt requestUserCredentials im RepoUrlPicker (braucht OAuth-Login bei der Git-Plattform, Tag 12).
  • Bei GitHub heißen die Actions publish:github (bzw. publish:github:pull-request für Änderungen an bestehenden Repos), bei GitLab publish:gitlab. Das Muster host?owner=…&repo=… ist überall gleich.
  • Nach dem Anlegen fehlt meist noch Infrastruktur: Branch-Schutz, CI-Variablen, Namespace im Cluster. Das erledigen weitere Actions oder ein nachgelagerter Pipeline-Lauf. Template und Plattform-Automatisierung sollten dasselbe Team pflegen.
  • Wer welche Templates sehen und ausführen darf, regeln Permissions (scaffolder.template.parameter.read, scaffolder.action.execute, Tag 12).