Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 10: Plugins installieren

Ziel: Du bindest das Kubernetes-Plugin an einen lokalen kind-Cluster an, siehst die Pods der sendungs-api im 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 Repo backstage/community-plugins.
  • Frontend: app.packages: all lädt jedes Plugin aus packages/app/package.json automatisch (Feature-Discovery). Backend: eine Zeile backend.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.ts

Erwartet:

    "@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.yaml

Erwartet:

{
  "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 … plus backend.add(import(…)), danach portal.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-88

Erwartet:

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:

  1. Öffne sendungs-worker – die Annotation hat die Component seit Tag 2.
  2. Klicke auf den Tab Kubernetes und klappe die Warnung auf.
  3. Erwartet: „Could not find the Kubernetes Backend (HTTP 404)” wie in der Abbildung.
Kubernetes-Tab ohne konfiguriertes Backend mit HTTP 404

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 nodes

Erwartet (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 spricht kubectl mit 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.yaml

Erwartet:

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

Erwartet:

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:backstage

Erwartet:

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 caData geht im Lab auch skipTLSVerify: 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 main

Erwartet:

@@ -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 -4

Erwartet:

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:

  1. Öffne sendungs-api und klicke auf Kubernetes.
  2. Klappe Warning: There was a problem retrieving Kubernetes objects auf.
  3. Erwartet: je eine Zeile pro Objekttyp mit status code: 403 wie in der Abbildung.
Kubernetes-Tab mit 403-Fehlern für jeden Objekttyp

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.

  1. Lade den Tab Kubernetes von sendungs-api neu.
  2. Erwartet: die Cluster-Karte backstage-lab mit „1 pod” und „No pods with errors” wie in der Abbildung.
Kubernetes-Tab mit dem Cluster backstage-lab und einem gesunden Pod
  1. Klappe backstage-lab und darin das Deployment sendungs-api auf.
  2. Erwartet: die Pod-Tabelle wie in der Abbildung. CPU und Memory stehen auf unknown, weil kein metrics-server läuft.
Deployment sendungs-api mit Pod-Tabelle
  1. Klicke auf den Pod-Namen.
  2. 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.
Pod-Detail mit Container-Gesundheit

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_name

Erwartet:

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, allowedMethods setzen und credentials: dangerously-allow-unauthenticated nie 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.sh

Erwartet:

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

Deployment sendungs-api mit drei Pods

Tipp: Der kind-Cluster kostet RAM (nicht live getestet). Pausieren mit docker stop backstage-lab-control-plane, weiter mit docker 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: Mit authProvider: serviceAccount ohne Token nimmt das Backend das Pod-Token. Für fremde Cluster kurzlebige Tokens oder authProvider: oidc/aws/google statt unbefristeter Secrets.
  • Viele Cluster: clusterLocatorMethods vom Typ catalog (Cluster als Resource-Entities) oder gke; Cluster-URLs aus dem Katalog prüft das Backend gegen SSRF (private IPs nur über dangerouslyAllowClusterUrls).
  • Bei Namenskollisionen über Teams hinweg statt kubernetes-id die Annotation backstage.io/kubernetes-label-selector nutzen; mit metrics-server und ohne skipMetricsLookup erscheinen CPU und Memory.
  • Mit eigener Permission-Policy (Tag 12) die Rechte kubernetes.clusters.read, kubernetes.resources.read und kubernetes.proxy gezielt 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:bump gemeinsam anheben (Tag 14).