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 ausparameters(Formular),steps(Actions im Backend) undoutput(Links). - Der Scaffolder führt die Steps als Task aus. Jeder Lauf hat ein Log.
fetch:templaterendert ein Skeleton mit Nunjucks (${{ values.name }}),publish:gitealegt das Repo an,catalog:registerträ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.jsonErwartet (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.tsErwartet:
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 }}
EOFDie 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));
EOFDie 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/templatesErwartet:
✔ 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:
- 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/**- Unter
locations:den Eintrag../../examples/template/template.yamlsamt seinenruleslöschen. Damit verschwindet das Beispiel-Template auscreate-app. - 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.yamlAchtung:
rulesdirekt an einer Location gelten nur für genau diese Datei (exakter Vergleich des Ziels), nicht für die Dateien untertargets. Einallow: [Template]antemplates.yamlwürdenode-service/template.yamlalso nicht freischalten. Die Regel mitpatternuntercatalog.rulesdeckt 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.targetsErwartet:
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
node-service plattform
["./node-service/template.yaml"]
- Klicke in der Sidebar auf Create.
- Erwartet: die Seite Templates mit genau einer Karte
Node.js-Service wie in der Abbildung. Typ
servicesteht oben, darunter Beschreibung, Tags und der Owner Team Plattform.
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
- Klicke auf der Karte auf CHOOSE. Die Adresse lautet
/create/templates/default/node-service. - Trage bei Name
lager-apiein, bei BeschreibungLagerbestände je Depot: API für Scanner und Disposition. - Klicke in Owner und wähle Team
Sendung. Die Liste zeigt nur Gruppen vom Typ
team: Team Sendung, Team Plattform, Team Web undguestsaus den Beispieldaten. - Erwartet: Schritt Service wie in der Abbildung. Der
Owner steht als vollständige Entity-Referenz
group:default/team-sendungim Feld.
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.
- Klicke auf Next. Schritt Repository zeigt Host und Owner Available ausgegraut, denn beide Listen haben genau einen Wert.
- Trage bei Repository
lager-apiein. - Erwartet: der Schritt wie in der Abbildung.
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.
- Klicke auf Review. Erwartet: die Zusammenfassung
wie in der Abbildung. Ablageort zeigt das Format, das
publish:giteaerwartet:127.0.0.1:3300?owner=kranich&repo=lager-api.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Der Task-Lauf und sein Log
- Klicke auf Create. Der Wizard springt auf
/create/tasks/<task-id>. - Die drei Steps laufen nacheinander und bekommen je einen grünen
Haken. Darunter erscheinen die Links aus
output.links, ganz unten das Log. - Erwartet: die Task-Seite wie in der Abbildung.
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
catalogInfoPathohne führenden Schrägstrich. Mit/catalog-info.yamllöst Backstage den Pfad gegen die Repo-Wurzel auf und verliert bei Forgejo-URLs den Branch. Im Log steht dannRegistering http://127.0.0.1:3300/kranich/lager-api/src/branch/catalog-info.yamlund danachResponseError: 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 %1Erwartet:
Backstage Scaffolder | Erzeugt aus Template node-service
lager-api lauscht auf Port 8080
{"service":"lager-api","status":"ok"}
Jetzt der Katalog:
- Klicke auf der Task-Seite auf IM KATALOG ÖFFNEN.
- Erwartet: die Entity-Seite von
lager-apiwie in der Abbildung, mitComponent • service, Lifecycleexperimental, Owner Team Sendung und der Beschreibung aus dem Wizard.
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:
- Klicke auf Create, dann CHOOSE und
fülle den Wizard genau wie in Drill 4 aus, also wieder mit
lager-api. - Klicke auf Review und Create.
- Erwartet: ein roter Balken, der Step Repo in Forgejo anlegen mit Ausrufezeichen, Im Katalog registrieren übersprungen wie in der Abbildung.
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:
- Klicke auf START OVER. Der Wizard öffnet sich mit
allen bisherigen Eingaben (sie stehen als
formDatain der Adresse). - Ändere Name auf
lager-worker, klicke Next, ändere Repository auflager-worker, dann Review und Create. - 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.shErwartet:
✔ 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: 65535Und 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.ownerErwartet:
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
patternincatalog.rulesstellt sicher, dass nur dieses Repo Templates liefern darf. - Der Bot-Token aus
integrationserzeugt Repos im Namen der Plattform. Wer Repos im Namen der Nutzer anlegen will, nutztrequestUserCredentialsimRepoUrlPicker(braucht OAuth-Login bei der Git-Plattform, Tag 12). - Bei GitHub heißen die Actions
publish:github(bzw.publish:github:pull-requestfür Änderungen an bestehenden Repos), bei GitLabpublish:gitlab. Das Musterhost?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).