Skip to content
Hands-on IT IT Drills

Day 10: Installing plugins

Goal: You connect the Kubernetes plugin to a local kind cluster, see the pods of sendungs-api in the portal and set up a proxy endpoint to the Forgejo API. · Duration: approx. 120 min · Prerequisite: Day 9

Briefing

  • A plugin usually consists of several npm packages: frontend (@backstage/plugin-kubernetes), backend (…-kubernetes-backend), optional modules (…-backend-module-…) and libraries (-react, -common, -node).
  • Where to find them: the plugin directory at backstage.io/plugins, plus npm and the repo backstage/community-plugins.
  • Frontend: app.packages: all loads every plugin from packages/app/package.json automatically (feature discovery). Backend: one line backend.add(import(…)).
  • After that, almost every plugin still needs configuration and often an annotation on the entity.
 Browser              Backend :7007                    kind cluster backstage-lab
 ┌────────────┐ POST  ┌─────────────────────────┐ GET  ┌───────────────────────────┐
 │ Tab        │ ────► │ /api/kubernetes/        │ ───► │ Pods, Deployments, … with │
 │ Kubernetes │       │ services/<id>           │      │ label backstage.io/       │
 └────────────┘       │ ServiceAccount token    │      │ kubernetes-id=sendungs-api│
                      └─────────────────────────┘      └───────────────────────────┘

Drill 1: What is already installed?

You start where Day 9 ended: the portal is running, with a catalog containing sendungs-api, sendungs-worker (repo kranich/sendungsverfolgung) and the organization from Day 4. Before you install anything, check what the create-app template already ships:

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

Expected:

    "@backstage/plugin-kubernetes": "^0.12.23",
    "@backstage/plugin-kubernetes-backend": "^0.21.11",
59:// kubernetes plugin
60:backend.add(import('@backstage/plugin-kubernetes-backend'));

So both halves are already there – this plugin does not need a yarn add. Why does the frontend find the plugin without an entry in App.tsx?

jq '.backstage | {role, pluginId, features}' \
  node_modules/@backstage/plugin-kubernetes/package.json
grep -n 'packages:' app-config.yaml

Expected:

{
  "role": "frontend-plugin",
  "pluginId": "kubernetes",
  "features": {
    "./alpha": "@backstage/FrontendPlugin"
  }
}
6:  packages: all

Why? app.packages: all searches the dependencies of packages/app for packages with role: frontend-plugin and a feature export, and loads them. That is how the Kubernetes plugin brings along the entity extension entity-content:kubernetes/kubernetes – the Kubernetes tab, which only appears for entities with the annotation backstage.io/kubernetes-id.

Tip: You install a plugin that is still missing the same way as on Day 5: yarn --cwd packages/app add @backstage/plugin-… (frontend) or yarn --cwd packages/backend add … plus backend.add(import(…)), then portal.sh restart.

The backend, on the other hand, is only half active:

~/backstage-lab/setup/portal.sh logs 300 | sed 's/\x1b\[[0-9;]*m//g' \
  | grep 'kubernetes warn' | cut -c1-88

Expected:

2026-10-13T07:17:34.973Z kubernetes warn Failed to initialize kubernetes backend: valid

Without a kubernetes: block (it is empty in app-config.yaml), the plugin registers no routes. Look at the failure in the portal:

  1. Open sendungs-worker – the component has had the annotation since Day 2.
  2. Click the Kubernetes tab and expand the warning.
  3. Expected: “Could not find the Kubernetes Backend (HTTP 404)”, as in the figure.
Kubernetes tab without a configured backend, with HTTP 404

Save your progress? Sign up for free

Drill 2: The kind cluster backstage-lab

You need kind and kubectl (Homebrew: brew install kind kubectl). The cluster gets its own kubeconfig file – your ~/.kube/config and its current context stay untouched.

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

Expected (shortened):

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” refers only to the file in $KUBECONFIG. If the image kindest/node:v1.37.0 is not available locally, kind downloads it the first time (a good 1 GB).

Warning: Every new terminal needs export KUBECONFIG=~/backstage-lab/tag10/kubeconfig again, otherwise kubectl talks to your default cluster.

Save your progress? Sign up for free

Drill 3: The sendungs-api in the cluster

The deployment is a small nginx in the namespace kranich. The key part is the label backstage.io/kubernetes-id on the Deployment, pod template and Service:

cp -R ~/backstage-lab/code/tag10/k8s ~/backstage-lab/tag10/
grep -n -B1 'kubernetes-id' k8s/sendungs-api.yaml

Expected:

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

Expected:

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

The node pulls nginx:1.24-alpine from Docker Hub itself. Why a label? By default the plugin searches with the label selector backstage.io/kubernetes-id=<annotation> across all namespaces – the name of the Deployment does not matter.

Save your progress? Sign up for free

Drill 4: A ServiceAccount for Backstage

Backstage authenticates to the cluster with the token of its own ServiceAccount. For now without permissions – you will see the failure in Drill 6.

cat > k8s/backstage-sa.yaml <<'EOF'
# backstage-sa.yaml – technical access for Backstage (no permissions yet)
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

Expected:

namespace/backstage created
serviceaccount/backstage created
secret/backstage-token created
no

The cluster itself fills the Secret of type service-account-token with a non-expiring token – convenient for the lab; for production see the Enterprise Note.

Save your progress? Sign up for free

Drill 5: Configuring the cluster

You take three values from the kubeconfig and the Secret: API URL, CA certificate, 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}"

Expected (the port differs for every cluster):

https://127.0.0.1:50509 1476 905

Append the block to app-config.local.yaml. This time the EOF has no quotes, so the shell substitutes the three variables – token and CA thus end up in the local file, which is not checked in:

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[]'

Expected:

1
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{"name":"backstage-lab","authProvider":"serviceAccount"}

Why? multiTenant asks every configured cluster about every entity. skipMetricsLookup: true skips the query to the metrics-server, which kind doesn’t have.

Tip: Instead of caData, skipTLSVerify: true also works in the lab – then the backend does not verify the API server’s certificate at all. Only for sandboxes.

Save your progress? Sign up for free

Drill 6: Annotation and the 403 failure

sendungs-api has no annotation yet. Add it only to the component (the file also contains API entities) and push:

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

Expected:

@@ -6,6 +6,7 @@ metadata:
   tags: [nodejs, rest]
   annotations:
     backstage.io/techdocs-ref: dir:.
+    backstage.io/kubernetes-id: sendungs-api
 spec:
   type: service

After one or two minutes (Gitea provider), the entity has the annotation. Ask the plugin directly – the tab makes exactly this call too:

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

Expected:

403 /api/v1/pods
403 /api/v1/services
403 /api/v1/configmaps
403 /api/v1/limitranges

Connection and TLS are fine, but the ServiceAccount is not allowed to read anything. In the portal:

  1. Open sendungs-api and click Kubernetes.
  2. Expand Warning: There was a problem retrieving Kubernetes objects.
  3. Expected: one line per object type with status code: 403, as in the figure.
Kubernetes tab with 403 errors for each object type

The list shows which resources the plugin queries – exactly those are what the role needs.

Save your progress? Sign up for free

Drill 7: Granting read permissions

A ClusterRole with get, list and watch on these types, bound to the ServiceAccount:

cat > ~/backstage-lab/tag10/k8s/backstage-rbac.yaml <<'EOF'
# backstage-rbac.yaml – read permissions (get/list/watch) for the 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(", "))")'

Expected:

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 is included so that the LOGS button in the pod detail works. No restart needed – the backend queries live on every call.

  1. Reload the Kubernetes tab of sendungs-api.
  2. Expected: the cluster card backstage-lab with “1 pod” and “No pods with errors”, as in the figure.
Kubernetes tab with the cluster backstage-lab and one healthy pod
  1. Expand backstage-lab and, inside it, the Deployment sendungs-api.
  2. Expected: the pod table, as in the figure. CPU and memory show unknown because no metrics-server is running.
Deployment sendungs-api with pod table
  1. Click the pod name.
  2. Expected: a side panel with container web, image and Container health, as in the figure. The red cross at Readiness Probe Set is a real finding – the demo deployment has no probe.
Pod detail with container health

Save your progress? Sign up for free

Drill 8: Second plugin – proxy to the Forgejo API

@backstage/plugin-proxy-backend is also already in index.ts. A proxy endpoint forwards calls under /api/proxy/<route> to a target and sets headers on the way – so the Forgejo token stays in the backend and the browser never sees it.

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])"'

Expected (the repo list may be longer, depending on the state of your org):

1
backstage-bot
kranich/sendungs-api
kranich/tracking-web
kranich/org
kranich/sendungsverfolgung
a2130d1 Kubernetes-ID für das Kubernetes-Plugin
7458306 Initialer Stand

Now the counter-checks – without a Backstage token and with a write method:

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

Expected:

Missing credentials
404
kranich/org

Why? The default is credentials: require – only signed-in users or services may pass through the proxy. allowedMethods: [GET] doesn’t let the DELETE through at all, and the repo stays. Without this line, every portal user would have the bot’s write permissions.

Security: A proxy endpoint lends the permissions of its token to all users of the portal. Use tokens with minimal scopes, set allowedMethods, and never use credentials: dangerously-allow-unauthenticated for internal APIs.

Save your progress? Sign up for free

Checkpoint

The file is also available at ~/backstage-lab/code/tag10/kontrolle.sh.

#!/usr/bin/env bash
# kontrolle.sh – checkpoint Day 10 (✔/✘). Exit code = number of failures.
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

Expected:

✔ 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

With the role from Drill 4 alone (without Drill 7), checks 2 and 5 fail.

Challenge

Scale sendungs-api to three replicas. Prove via the Backstage API that the plugin sees three running pods, and check the tab in the portal.

Hint: The backend queries the cluster live on every call – a kubectl scale is enough; the query from Drill 6 shows the new state.

Solution

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

Expected:

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

In the Kubernetes tab, the Deployment now shows “3 pods”, as in the figure.

Deployment sendungs-api with three pods

Tip: The kind cluster costs RAM (not tested live). Pause it with docker stop backstage-lab-control-plane, resume with docker start …; the API address stays the same. If you delete it (kind delete cluster --name backstage-lab), you have to repeat Drills 2 to 5 and 7 – URL, CA and token change.

Save your progress? Sign up for free

Enterprise Note

  • If Backstage itself runs in the cluster, serviceAccountToken is not needed: with authProvider: serviceAccount and no token, the backend uses the pod token. For other clusters, use short-lived tokens or authProvider: oidc/aws/google instead of non-expiring Secrets.
  • Many clusters: clusterLocatorMethods of type catalog (clusters as Resource entities) or gke; the backend checks cluster URLs from the catalog against SSRF (private IPs only via dangerouslyAllowClusterUrls).
  • For name collisions across teams, use the annotation backstage.io/kubernetes-label-selector instead of kubernetes-id; with a metrics-server and without skipMetricsLookup, CPU and memory appear.
  • With your own permission policy (Day 12), grant the permissions kubernetes.clusters.read, kubernetes.resources.read and kubernetes.proxy selectively – the latter allows calls to the Kubernetes API via /api/kubernetes/proxy.
  • Vet plugins before adopting them: maintainers, release cadence, support for the new frontend system, license; bump versions together with yarn backstage-cli versions:bump (Day 14).