Tag 10: Plugins installieren
Ziel: Du bindest das Kubernetes-Plugin an einen lokalen kind-Cluster an, siehst die Pods der
sendungs-apiim Portal und richtest einen Proxy-Endpunkt zur Forgejo-API ein. · Dauer: ca. 120 min · Voraussetzung: Tag 9
Briefing
- Ein Plugin besteht meist aus mehreren npm-Paketen:
Frontend (
@backstage/plugin-kubernetes), Backend (…-kubernetes-backend), optional Module (…-backend-module-…) und Bibliotheken (-react,-common,-node). - Fundort: das Plugin-Verzeichnis unter
backstage.io/plugins, dazu npm und das Repobackstage/community-plugins. - Frontend:
app.packages: alllädt jedes Plugin auspackages/app/package.jsonautomatisch (Feature-Discovery). Backend: eine Zeilebackend.add(import(…)). - Danach braucht fast jedes Plugin noch Konfiguration und oft eine Annotation an der Entity.
Browser Backend :7007 kind-Cluster backstage-lab
┌────────────┐ POST ┌─────────────────────────┐ GET ┌───────────────────────────┐
│ Tab │ ────► │ /api/kubernetes/ │ ───► │ Pods, Deployments, … mit │
│ Kubernetes │ │ services/<id> │ │ Label backstage.io/ │
└────────────┘ │ Token des ServiceAccount│ │ kubernetes-id=sendungs-api│
└─────────────────────────┘ └───────────────────────────┘
Drill 1: Was ist schon installiert?
Ausgangslage ist das Ende von Tag 9: Portal läuft, Katalog mit
sendungs-api, sendungs-worker (Repo
kranich/sendungsverfolgung) und der Organisation aus Tag 4.
Bevor du etwas installierst, prüfe, was die create-app-Vorlage schon
mitbringt:
source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
cd ~/backstage-lab/portal
grep -h '"@backstage/plugin-kubernetes' packages/app/package.json \
packages/backend/package.json
grep -n kubernetes packages/backend/src/index.tsErwartet:
"@backstage/plugin-kubernetes": "^0.12.23",
"@backstage/plugin-kubernetes-backend": "^0.21.11",
59:// kubernetes plugin
60:backend.add(import('@backstage/plugin-kubernetes-backend'));
Beide Hälften sind also schon da – ein yarn add ist für
dieses Plugin nicht nötig. Warum findet das Frontend das Plugin ohne
Eintrag in App.tsx?
jq '.backstage | {role, pluginId, features}' \
node_modules/@backstage/plugin-kubernetes/package.json
grep -n 'packages:' app-config.yamlErwartet:
{
"role": "frontend-plugin",
"pluginId": "kubernetes",
"features": {
"./alpha": "@backstage/FrontendPlugin"
}
}
6: packages: all
Warum? app.packages: all durchsucht die Abhängigkeiten
von packages/app nach Paketen mit
role: frontend-plugin und einem Feature-Export und lädt
sie. Das Kubernetes-Plugin bringt so die Entity-Extension
entity-content:kubernetes/kubernetes mit – den Tab
Kubernetes, der nur bei Entities mit Annotation
backstage.io/kubernetes-id erscheint.
Tipp: Ein Plugin, das noch fehlt, installierst du genauso wie an Tag 5:
yarn --cwd packages/app add @backstage/plugin-…(Frontend) bzw.yarn --cwd packages/backend add …plusbackend.add(import(…)), danachportal.sh restart.
Das Backend dagegen ist nur halb aktiv:
~/backstage-lab/setup/portal.sh logs 300 | sed 's/\x1b\[[0-9;]*m//g' \
| grep 'kubernetes warn' | cut -c1-88Erwartet:
2026-10-13T07:17:34.973Z kubernetes warn Failed to initialize kubernetes backend: valid
Ohne Block kubernetes: (in app-config.yaml
steht er leer) registriert das Plugin keine Routen. Sieh dir das
Fehlerbild im Portal an:
- Öffne
sendungs-worker– die Annotation hat die Component seit Tag 2. - Klicke auf den Tab Kubernetes und klappe die Warnung auf.
- Erwartet: „Could not find the Kubernetes Backend (HTTP 404)” wie in der Abbildung.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Der kind-Cluster backstage-lab
Du brauchst kind und kubectl (Homebrew:
brew install kind kubectl). Der Cluster bekommt eine eigene
kubeconfig-Datei – deine ~/.kube/config und ihr aktueller
Kontext bleiben unangetastet.
mkdir -p ~/backstage-lab/tag10 && cd ~/backstage-lab/tag10
export KUBECONFIG=~/backstage-lab/tag10/kubeconfig
kind create cluster --name backstage-lab --image kindest/node:v1.37.0 \
--kubeconfig "$KUBECONFIG"
kubectl wait --for=condition=Ready node --all --timeout=90s
kubectl get nodesErwartet (gekürzt):
Creating cluster "backstage-lab" ...
✓ Ensuring node image (kindest/node:v1.37.0)
✓ Starting control-plane
Set kubectl context to "kind-backstage-lab"
node/backstage-lab-control-plane condition met
NAME STATUS ROLES AGE VERSION
backstage-lab-control-plane Ready control-plane 20s v1.37.0
„Set kubectl context” bezieht sich nur auf die Datei in
$KUBECONFIG. Fehlt das Image
kindest/node:v1.37.0 lokal, lädt kind es beim ersten Mal
(gut 1 GB).
Achtung: Jedes neue Terminal braucht wieder
export KUBECONFIG=~/backstage-lab/tag10/kubeconfig, sonst sprichtkubectlmit deinem Standard-Cluster.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die sendungs-api im Cluster
Das Deployment ist ein kleiner nginx im Namespace
kranich. Entscheidend ist das Label
backstage.io/kubernetes-id an Deployment, Pod-Template und
Service:
cp -R ~/backstage-lab/code/tag10/k8s ~/backstage-lab/tag10/
grep -n -B1 'kubernetes-id' k8s/sendungs-api.yamlErwartet:
13- app: sendungs-api
14: backstage.io/kubernetes-id: sendungs-api
--
23- app: sendungs-api
24: backstage.io/kubernetes-id: sendungs-api
--
40- labels:
41: backstage.io/kubernetes-id: sendungs-api
kubectl apply -f k8s/sendungs-api.yaml
kubectl -n kranich rollout status deploy/sendungs-api --timeout=120s
kubectl get pods -n kranich -L backstage.io/kubernetes-idErwartet:
namespace/kranich created
deployment.apps/sendungs-api created
service/sendungs-api created
deployment "sendungs-api" successfully rolled out
NAME READY STATUS RESTARTS AGE KUBERNETES-ID
sendungs-api-dc8cbccbf-dqrl4 1/1 Running 0 9s sendungs-api
Der Node zieht nginx:1.24-alpine selbst aus Docker Hub.
Warum ein Label? Das Plugin sucht standardmäßig per Label-Selector
backstage.io/kubernetes-id=<Annotation> in allen
Namespaces – der Name des Deployments spielt keine Rolle.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein ServiceAccount für Backstage
Backstage meldet sich mit dem Token eines eigenen ServiceAccounts am Cluster an. Erst einmal ohne Rechte – das Fehlerbild kommt in Drill 6.
cat > k8s/backstage-sa.yaml <<'EOF'
# backstage-sa.yaml – technischer Zugang für Backstage (noch ohne Rechte)
apiVersion: v1
kind: Namespace
metadata:
name: backstage
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: backstage
namespace: backstage
---
apiVersion: v1
kind: Secret
metadata:
name: backstage-token
namespace: backstage
annotations:
kubernetes.io/service-account.name: backstage
type: kubernetes.io/service-account-token
EOF
kubectl apply -f k8s/backstage-sa.yaml
kubectl auth can-i list pods --as=system:serviceaccount:backstage:backstageErwartet:
namespace/backstage created
serviceaccount/backstage created
secret/backstage-token created
no
Das Secret vom Typ service-account-token füllt der
Cluster selbst mit einem unbefristeten Token – bequem fürs Lab, in
Produktion siehe Enterprise-Notiz.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Den Cluster konfigurieren
Drei Werte holst du aus kubeconfig und Secret: API-URL, CA-Zertifikat, Token.
K8S_URL=$(kubectl config view --raw --minify \
-o jsonpath='{.clusters[0].cluster.server}')
K8S_CA=$(kubectl config view --raw --minify \
-o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
K8S_TOKEN=$(kubectl -n backstage get secret backstage-token \
-o jsonpath='{.data.token}' | base64 -d)
echo "$K8S_URL ${#K8S_CA} ${#K8S_TOKEN}"Erwartet (der Port ist bei jedem Cluster anders):
https://127.0.0.1:50509 1476 905
Hänge den Block an app-config.local.yaml an. Das
EOF steht diesmal ohne Anführungszeichen,
damit die Shell die drei Variablen einsetzt – Token und CA landen so in
der nicht eingecheckten local-Datei:
cat >> ~/backstage-lab/portal/app-config.local.yaml <<EOF
kubernetes:
serviceLocatorMethod:
type: multiTenant
clusterLocatorMethods:
- type: config
clusters:
- name: backstage-lab
url: $K8S_URL
authProvider: serviceAccount
serviceAccountToken: $K8S_TOKEN
caData: $K8S_CA
skipMetricsLookup: true
EOF
grep -c '^kubernetes:' ~/backstage-lab/portal/app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
bs kubernetes/clusters | jq -c '.items[]'Erwartet:
1
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{"name":"backstage-lab","authProvider":"serviceAccount"}
Warum? multiTenant fragt jeden konfigurierten Cluster
nach jeder Entity. skipMetricsLookup: true spart die
Abfrage beim metrics-server, den kind nicht hat.
Tipp: Statt
caDatageht im Lab auchskipTLSVerify: true– dann prüft das Backend das Zertifikat des API-Servers gar nicht. Nur für Spielwiesen.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Annotation und das Fehlerbild 403
Die sendungs-api hat noch keine Annotation. Ergänze sie
nur in der Component (die Datei enthält auch API-Entities) und
pushe:
cd ~/backstage-lab/tag10
git clone -q http://lab-admin:[email protected]:3300/kranich/sendungs-api.git
cd sendungs-api
yq -i '(select(.kind == "Component")
| .metadata.annotations["backstage.io/kubernetes-id"]) = "sendungs-api"' \
catalog-info.yaml
git diff
git -c user.name="Lab Admin" -c [email protected] \
commit -qam "Kubernetes-ID für das Kubernetes-Plugin"
git push -q origin mainErwartet:
@@ -6,6 +6,7 @@ metadata:
tags: [nodejs, rest]
annotations:
backstage.io/techdocs-ref: dir:.
+ backstage.io/kubernetes-id: sendungs-api
spec:
type: service
Nach ein bis zwei Minuten (Gitea-Provider) hat die Entity die Annotation. Frage das Plugin direkt – genau diesen Aufruf macht auch der Tab:
sleep 70
k8s() { bs kubernetes/services/$1 -X POST -H 'Content-Type: application/json' \
-d "{\"entity\":{\"kind\":\"Component\",\"metadata\":{\"name\":\"$1\"}}}"; }
k8s sendungs-api | jq -r '.items[].errors[] | "\(.statusCode) \(.resourcePath)"' \
| head -4Erwartet:
403 /api/v1/pods
403 /api/v1/services
403 /api/v1/configmaps
403 /api/v1/limitranges
Verbindung und TLS stimmen, aber der ServiceAccount darf nichts lesen. Im Portal:
- Öffne
sendungs-apiund klicke auf Kubernetes. - Klappe Warning: There was a problem retrieving Kubernetes objects auf.
- Erwartet: je eine Zeile pro Objekttyp mit
status code: 403wie in der Abbildung.
Die Liste zeigt, welche Ressourcen das Plugin abfragt – genau die braucht die Rolle.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Leserechte vergeben
Eine ClusterRole mit get, list und
watch auf diese Typen, gebunden an den ServiceAccount:
cat > ~/backstage-lab/tag10/k8s/backstage-rbac.yaml <<'EOF'
# backstage-rbac.yaml – Leserechte (get/list/watch) für den ServiceAccount backstage
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: backstage-read-only
rules:
- apiGroups: [""]
resources: [pods, pods/log, services, configmaps, limitranges, resourcequotas]
verbs: [get, list, watch]
- apiGroups: [apps]
resources: [deployments, replicasets, statefulsets, daemonsets]
verbs: [get, list, watch]
- apiGroups: [autoscaling]
resources: [horizontalpodautoscalers]
verbs: [get, list, watch]
- apiGroups: [networking.k8s.io]
resources: [ingresses]
verbs: [get, list, watch]
- apiGroups: [batch]
resources: [jobs, cronjobs]
verbs: [get, list, watch]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: backstage-read-only
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: backstage-read-only
subjects:
- kind: ServiceAccount
name: backstage
namespace: backstage
EOF
kubectl apply -f ~/backstage-lab/tag10/k8s/backstage-rbac.yaml
SA=system:serviceaccount:backstage:backstage
kubectl auth can-i list pods --as=$SA; kubectl auth can-i delete pods --as=$SA
k8s sendungs-api | jq -r '.items[] | "errors: \(.errors | length)",
(.resources[] | select(.resources | length > 0)
| "\(.type): \([.resources[].metadata.name] | join(", "))")'Erwartet:
clusterrole.rbac.authorization.k8s.io/backstage-read-only created
clusterrolebinding.rbac.authorization.k8s.io/backstage-read-only created
yes
no
errors: 0
pods: sendungs-api-dc8cbccbf-dqrl4
services: sendungs-api
deployments: sendungs-api
replicasets: sendungs-api-dc8cbccbf
pods/log ist dabei, damit der Button
LOGS im Pod-Detail funktioniert. Kein Neustart nötig –
das Backend fragt bei jedem Aufruf live.
- Lade den Tab Kubernetes von
sendungs-apineu. - Erwartet: die Cluster-Karte backstage-lab mit „1 pod” und „No pods with errors” wie in der Abbildung.
- Klappe backstage-lab und darin das Deployment sendungs-api auf.
- Erwartet: die Pod-Tabelle wie in der Abbildung. CPU und Memory
stehen auf
unknown, weil kein metrics-server läuft.
- Klicke auf den Pod-Namen.
- Erwartet: ein Seitenpanel mit Container
web, Image und Container health wie in der Abbildung. Das rote Kreuz bei Readiness Probe Set ist ein echter Hinweis – das Demo-Deployment hat keine Probe.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Zweites Plugin – Proxy zur Forgejo-API
@backstage/plugin-proxy-backend ist ebenfalls schon in
index.ts. Ein Proxy-Endpunkt reicht Aufrufe unter
/api/proxy/<route> an ein Ziel weiter und setzt dabei
Header – so bleibt das Forgejo-Token im Backend, der Browser sieht es
nie.
cat >> ~/backstage-lab/portal/app-config.local.yaml <<'EOF'
proxy:
endpoints:
/forgejo:
target: http://127.0.0.1:3300/api/v1
headers:
Authorization: token ${FORGEJO_TOKEN}
allowedMethods: [GET]
EOF
grep -c '^proxy:' ~/backstage-lab/portal/app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
bs proxy/forgejo/user | jq -r .login
bs proxy/forgejo/orgs/kranich/repos | jq -r '.[].full_name'
bs 'proxy/forgejo/repos/kranich/sendungs-api/commits?limit=2' \
| jq -r '.[] | "\(.sha[0:7]) \(.commit.message | split("\n")[0])"'Erwartet (Repo-Liste je nach Stand deiner Org länger):
1
backstage-bot
kranich/sendungs-api
kranich/tracking-web
kranich/org
kranich/sendungsverfolgung
a2130d1 Kubernetes-ID für das Kubernetes-Plugin
7458306 Initialer Stand
Jetzt die Gegenproben – ohne Backstage-Token und mit einer schreibenden Methode:
curl -s "$BACKSTAGE/api/proxy/forgejo/user" | jq -r .error.message
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE \
-H "Authorization: Bearer $BACKSTAGE_TOKEN" \
"$BACKSTAGE/api/proxy/forgejo/repos/kranich/org"
curl -sf -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/org" | jq -r .full_nameErwartet:
Missing credentials
404
kranich/org
Warum? Standard ist credentials: require – nur
angemeldete Benutzer oder Dienste dürfen durch den Proxy.
allowedMethods: [GET] lässt das DELETE gar
nicht erst durch, das Repo bleibt. Ohne diese Zeile hätte jeder
Portal-Benutzer die Schreibrechte des Bots.
Sicherheit: Ein Proxy-Endpunkt verleiht die Rechte seines Tokens an alle Benutzer des Portals. Token mit minimalen Scopes,
allowedMethodssetzen undcredentials: dangerously-allow-unauthenticatednie für interne APIs.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Die Datei liegt auch unter
~/backstage-lab/code/tag10/kontrolle.sh.
#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 10 (✔/✘). Exit-Code = Anzahl Fehler.
source ~/backstage-lab/setup/env.sh
export KUBECONFIG=~/backstage-lab/tag10/kubeconfig
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
else echo "✘ $1"; fail=$((fail+1)); fi; }
k8s() { bs kubernetes/services/sendungs-api -X POST \
-H 'Content-Type: application/json' \
-d '{"entity":{"kind":"Component","metadata":{"name":"sendungs-api"}}}'; }
t "kind-Cluster backstage-lab läuft" "kubectl get nodes"
t "ServiceAccount darf Pods lesen" \
"kubectl auth can-i list pods --as=system:serviceaccount:backstage:backstage \
| grep -qx yes"
t "Backstage kennt den Cluster backstage-lab" \
"bs kubernetes/clusters | jq -e '.items[] | select(.name==\"backstage-lab\")'"
t "Annotation kubernetes-id an sendungs-api" \
"bs catalog/entities/by-name/component/default/sendungs-api \
| jq -e '.metadata.annotations[\"backstage.io/kubernetes-id\"]'"
t "Backend liefert Pods ohne Fehler" \
"k8s | jq -e '.items[0].errors == [] and
([.items[0].resources[] | select(.type==\"pods\") | .resources[]] | length > 0)'"
t "Proxy /forgejo liefert Repos der Org kranich" \
"bs proxy/forgejo/orgs/kranich/repos | jq -e 'length > 0'"
exit "$fail"bash ~/backstage-lab/code/tag10/kontrolle.shErwartet:
✔ kind-Cluster backstage-lab läuft
✔ ServiceAccount darf Pods lesen
✔ Backstage kennt den Cluster backstage-lab
✔ Annotation kubernetes-id an sendungs-api
✔ Backend liefert Pods ohne Fehler
✔ Proxy /forgejo liefert Repos der Org kranich
Mit der Rolle aus Drill 4 allein (ohne Drill 7) schlagen Punkt 2 und 5 fehl.
Challenge
Skaliere die sendungs-api auf drei Replicas. Beweise per
Backstage-API, dass das Plugin drei laufende Pods sieht, und prüfe den
Tab im Portal.
Hinweis: Das Backend fragt den Cluster bei jedem
Aufruf live – ein kubectl scale genügt, die Abfrage aus
Drill 6 zeigt den neuen Stand.
Lösung
export KUBECONFIG=~/backstage-lab/tag10/kubeconfig
kubectl -n kranich scale deployment sendungs-api --replicas=3
kubectl -n kranich rollout status deployment sendungs-api --timeout=90s
bs kubernetes/services/sendungs-api -X POST -H 'Content-Type: application/json' \
-d '{"entity":{"kind":"Component","metadata":{"name":"sendungs-api"}}}' \
| jq -r '.items[0].resources[] | select(.type=="pods") | .resources[]
| "\(.metadata.name) \(.status.phase)"'Erwartet:
deployment.apps/sendungs-api scaled
deployment "sendungs-api" successfully rolled out
sendungs-api-dc8cbccbf-6jnf7 Running
sendungs-api-dc8cbccbf-dqrl4 Running
sendungs-api-dc8cbccbf-gtl85 Running
Im Tab Kubernetes zeigt das Deployment jetzt „3 pods” wie in der Abbildung.
Tipp: Der kind-Cluster kostet RAM (nicht live getestet). Pausieren mit
docker stop backstage-lab-control-plane, weiter mitdocker start …; die API-Adresse bleibt gleich. Löschst du ihn (kind delete cluster --name backstage-lab), musst du Drill 2 bis 5 und 7 wiederholen – URL, CA und Token ändern sich.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Läuft Backstage selbst im Cluster, entfällt
serviceAccountToken: MitauthProvider: serviceAccountohne Token nimmt das Backend das Pod-Token. Für fremde Cluster kurzlebige Tokens oderauthProvider: oidc/aws/googlestatt unbefristeter Secrets. - Viele Cluster:
clusterLocatorMethodsvom Typcatalog(Cluster als Resource-Entities) odergke; Cluster-URLs aus dem Katalog prüft das Backend gegen SSRF (private IPs nur überdangerouslyAllowClusterUrls). - Bei Namenskollisionen über Teams hinweg statt
kubernetes-iddie Annotationbackstage.io/kubernetes-label-selectornutzen; mit metrics-server und ohneskipMetricsLookuperscheinen CPU und Memory. - Mit eigener Permission-Policy (Tag 12) die Rechte
kubernetes.clusters.read,kubernetes.resources.readundkubernetes.proxygezielt vergeben – Letzteres erlaubt Aufrufe an die Kubernetes-API über/api/kubernetes/proxy. - Plugins vor der Aufnahme prüfen: Maintainer, Release-Takt, Support
für das neue Frontend-System, Lizenz; Versionen mit
yarn backstage-cli versions:bumpgemeinsam anheben (Tag 14).