Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 11: Ein eigenes Plugin

Ziel: Du baust mit yarn new ein Backend- und ein Frontend-Plugin bereitschaft, das auf jeder Component-Seite zeigt, wer im Owner-Team heute Bereitschaft hat. · Dauer: ca. 120 min · Voraussetzung: Tag 10

Briefing

  • Ein Plugin besteht meist aus zwei Paketen: das Backend-Plugin liefert eine REST-API unter /api/<pluginId>, das Frontend-Plugin liefert Extensions für die App.
  • yarn new erzeugt beide Pakete unter plugins/ und trägt sie gleich in Backend und App ein.
  • Das Frontend fragt das Backend über fetchApi – mit dem Token des angemeldeten Users. Ohne Token antwortet jedes Plugin-Backend mit 401.
  • Die Bereitschaftsliste steht in der Konfiguration, nicht im Code.
Entity-Seite sendungs-api (spec.owner: team-sendung)
  └─ entity-card:bereitschaft/heute ──fetchApi──► GET /api/bereitschaft/heute
                                                     ?team=team-sendung
                                    ◄── {"person":"user:default/ben.kraus", …}
     app-config.local.yaml: bereitschaft.teams.team-sendung: [anna.berger, …]

Drill 1: Ein Backend-Plugin erzeugen

Ausgangslage ist das Ende von Tag 10. Für dieses Kapitel genügen sendungs-api, tracking-web und die Organisation aus Tag 4 im Katalog; Kubernetes muss nicht laufen. Der Generator ruft am Ende selbst yarn install und yarn lint --fix auf.

source ~/backstage-lab/setup/env.sh
cd ~/backstage-lab/portal
yarn new

Wähle im Menü mit den Pfeiltasten backend-plugin und gib als ID bereitschaft ein. Erwartet (gekürzt; die Fragezeilen können je nach Version abweichen):

? What do you want to create? backend-plugin - A new backend plugin
? Enter the ID of the plugin [required] bereitschaft
  templating    plugins/bereitschaft-backend ✔
  backend       adding @internal/backstage-plugin-bereitschaft-backend ✔
  executing     yarn install ✔
  executing     yarn lint --fix ✔

Tipp: Ohne Rückfragen, z. B. in Skripten: yarn new --select backend-plugin --option pluginId=bereitschaft. Beide Flags stehen in yarn new --help.

Der Paketname folgt dem Muster @internal/backstage-plugin-<id>-backend. Der Generator hat ihn schon im Backend eingetragen:

git diff packages/backend/src/index.ts | grep '^+b'
find plugins/bereitschaft-backend/src -type f | sort

Erwartet:

+backend.add(import('@internal/backstage-plugin-bereitschaft-backend'));
plugins/bereitschaft-backend/src/index.ts
plugins/bereitschaft-backend/src/plugin.test.ts
plugins/bereitschaft-backend/src/plugin.ts
plugins/bereitschaft-backend/src/router.test.ts
plugins/bereitschaft-backend/src/router.ts
plugins/bereitschaft-backend/src/services/TodoListService.ts
plugins/bereitschaft-backend/src/setupTests.ts

Die Vorlage ist eine kleine Todo-API (/todos). Du ersetzt sie in Drill 2 durch die Bereitschaft.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Router und Konfiguration

Der Router kennt nur eine Route. wer() wählt reihum, jeden Tag ist die nächste Person dran. Fehler wirfst du als InputError (400) oder NotFoundError (404) aus @backstage/errors – das Backend macht daraus eine JSON-Fehlerantwort.

cd ~/backstage-lab/portal/plugins/bereitschaft-backend
rm -r src/services
cat > src/router.ts <<'EOF'
import { InputError, NotFoundError } from '@backstage/errors';
import express from 'express';
import Router from 'express-promise-router';

/** Team-Name → Liste der User-Namen (aus bereitschaft.teams) */
export type Teams = Record<string, string[]>;

/** Reihum: jeden Tag ist die nächste Person dran. */
export function wer(personen: string[], datum: Date): string {
  const tag = Math.floor(datum.getTime() / 86_400_000);
  return personen[tag % personen.length];
}

export function createRouter(options: { teams: Teams }): express.Router {
  const router = Router();

  router.get('/heute', async (req, res) => {
    const team = req.query.team;
    if (typeof team !== 'string' || team === '') {
      throw new InputError('Parameter team fehlt');
    }
    const personen = options.teams[team];
    if (!personen?.length) {
      throw new NotFoundError(`Keine Bereitschaft für ${team}`);
    }
    const datum = new Date();
    res.json({
      team,
      datum: datum.toISOString().slice(0, 10),
      person: `user:default/${wer(personen, datum)}`,
    });
  });

  return router;
}
EOF

Das Plugin holt sich per Dependency Injection die Konfiguration, einen Logger und den httpRouter, der alles unter /api/bereitschaft einhängt:

cat > src/plugin.ts <<'EOF'
import {
  coreServices,
  createBackendPlugin,
} from '@backstage/backend-plugin-api';
import { createRouter, Teams } from './router';

/**
 * bereitschaftPlugin backend plugin
 *
 * @public
 */
export const bereitschaftPlugin = createBackendPlugin({
  pluginId: 'bereitschaft',
  register(env) {
    env.registerInit({
      deps: {
        config: coreServices.rootConfig,
        logger: coreServices.logger,
        httpRouter: coreServices.httpRouter,
      },
      async init({ config, logger, httpRouter }) {
        const teams = config.getOptional<Teams>('bereitschaft.teams') ?? {};
        logger.info(`Bereitschaft für ${Object.keys(teams).length} Teams`);
        httpRouter.use(createRouter({ teams }));
      },
    });
  },
});
EOF

Der Schlüssel bereitschaft ist frei gewählt. Hänge ihn als eigenen Top-Level-Block an die local-Datei an (die User stammen aus kranich/org, Tag 4):

cat ~/backstage-lab/code/tag11/bereitschaft.yaml \
  >> ~/backstage-lab/portal/app-config.local.yaml
tail -4 ~/backstage-lab/portal/app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
grep -a 'Bereitschaft für' ~/backstage-lab/portal.log | sed 's/\x1b\[[0-9;]*m//g'

Erwartet:

bereitschaft:
  teams:
    team-sendung: [anna.berger, ben.kraus]
    team-web: [chris.dietz, thomas.zachmann]
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
2026-10-13T07:31:08.373Z bereitschaft info Bereitschaft für 2 Teams

Die Testdateien der Vorlage passen nicht mehr zum Code. Du ersetzt sie in Drill 7; yarn start stört das nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Aufruf per API – und warum 401

curl -s "$BACKSTAGE/api/bereitschaft/heute?team=team-sendung" \
  | jq -c '.error | {name, message}'
bs 'bereitschaft/heute?team=team-sendung' | jq
bs 'bereitschaft/heute?team=team-xyz' -w '%{http_code}\n'

Erwartet (die Person wechselt täglich; bs nutzt curl -f und gibt beim 404 nur den Statuscode aus):

{"name":"AuthenticationError","message":"Missing credentials"}
{
  "team": "team-sendung",
  "datum": "2026-10-13",
  "person": "user:default/ben.kraus"
}
404

Warum? Im neuen Backend-System gilt für jede Route die Standard-Policy des httpRouter: Nur Anfragen mit gültigem Token kommen durch – entweder ein User-Token aus dem Login oder ein Service-Token. bs schickt den statischen Lab-Token aus backend.auth.externalAccess, das Backend sieht den Service-Principal lab-cli. Ein falscher Token liefert Illegal token, ebenfalls 401.

Sicherheit: Öffnen lässt sich eine Route nur bewusst im Plugin, z. B. httpRouter.addAuthPolicy({ path: '/health', allow: 'unauthenticated' }). Wer zusätzlich nur User zulassen will, prüft im Handler await httpAuth.credentials(req, { allow: ['user'] }) – so macht es die Todo-Vorlage.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ein Frontend-Plugin erzeugen

cd ~/backstage-lab/portal
yarn new

Wähle frontend-plugin und wieder die ID bereitschaft. Erwartet (gekürzt):

? What do you want to create? frontend-plugin - A new frontend plugin
? Enter the ID of the plugin [required] bereitschaft
  templating    plugins/bereitschaft ✔
  app           adding import ✔
  executing     yarn install ✔
  executing     yarn lint --fix ✔

„adding import” ist ein Überbleibsel aus dem alten Frontend-System: App.tsx bleibt unverändert. Der Generator trägt das Paket nur als Abhängigkeit der App ein:

git diff packages/app/package.json | grep bereitschaft
grep -n 'packages: all' app-config.yaml

Erwartet:

+    "@internal/backstage-plugin-bereitschaft": "workspace:^",
6:  packages: all

Das reicht: app.packages: all lässt die CLI alle Frontend-Plugins aus den Abhängigkeiten von packages/app automatisch einbinden (Feature-Discovery). Die Vorlage bringt eine Seite mit, ein PageBlueprint auf Pfad /bereitschaft.

~/backstage-lab/setup/portal.sh restart
  1. Öffne http://localhost:3000/bereitschaft.
  2. Erwartet: die Seite „Welcome to bereitschaft!” wie in der Abbildung. Die zwei Einträge sind Beispieldaten – die Seite fragt /todos, das gibt es seit Drill 2 nicht mehr.
Die vom Generator erzeugte Plugin-Seite mit Beispieldaten

Tipp: Explizit statt automatisch: app.packages akzeptiert statt all auch include:/exclude: mit Paketnamen. Mit exclude: ['@internal/backstage-plugin-bereitschaft'] taucht das Plugin erst auf, wenn du es in App.tsx importierst und unter features einträgst.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die Entity-Karte

Die Karte braucht zwei weitere Pakete: plugin-catalog-react (Blueprint, useEntity, EntityRefLink) und catalog-model (parseEntityRef).

cd ~/backstage-lab/portal/plugins/bereitschaft
yarn add @backstage/plugin-catalog-react @backstage/catalog-model
jq -r '.dependencies | keys[]' package.json

Erwartet:

@backstage/catalog-model
@backstage/core-components
@backstage/frontend-plugin-api
@backstage/plugin-catalog-react
@backstage/theme
@backstage/ui
react-use

Beide Pakete hat die App schon installiert, yarn add lädt nichts nach; die Ranges (^3.2.3, ^1.10.1) passen zu Backstage 1.55.

Die Seite der Vorlage fliegt raus, das Plugin bekommt stattdessen ein EntityCardBlueprint. Der Filter { kind: 'component' } sorgt dafür, dass die Karte nur auf Component-Seiten erscheint.

rm -r src/components/TodoPage src/components/TodoList src/routes.ts
cat > src/plugin.tsx <<'EOF'
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
import { EntityCardBlueprint } from '@backstage/plugin-catalog-react/alpha';

export const bereitschaftCard = EntityCardBlueprint.make({
  name: 'heute',
  params: {
    filter: { kind: 'component' },
    loader: () =>
      import('./components/BereitschaftCard').then(m => <m.BereitschaftCard />),
  },
});

export const bereitschaftPlugin = createFrontendPlugin({
  pluginId: 'bereitschaft',
  extensions: [bereitschaftCard],
});
EOF

Die Komponente liest spec.owner der aktuellen Entity. parseEntityRef macht aus team-sendung und group:default/team-sendung (OwnerPicker, Tag 5) denselben Namen. plugin://bereitschaft/… löst fetchApi über die discoveryApi zur Backend-URL auf und hängt den Token des Users an.

mkdir -p src/components/BereitschaftCard
cat > src/components/BereitschaftCard/BereitschaftCard.tsx <<'EOF'
import { InfoCard, Progress, WarningPanel } from '@backstage/core-components';
import { fetchApiRef, useApi } from '@backstage/frontend-plugin-api';
import { parseEntityRef } from '@backstage/catalog-model';
import { EntityRefLink, useEntity } from '@backstage/plugin-catalog-react';
import { Text } from '@backstage/ui';
import useAsync from 'react-use/esm/useAsync';

type Bereitschaft = { team: string; datum: string; person: string };

export const BereitschaftCard = () => {
  const { entity } = useEntity();
  const { fetch } = useApi(fetchApiRef);
  const owner = String(entity.spec?.owner ?? '');
  const team = parseEntityRef(owner, { defaultKind: 'group' }).name;

  const { value, loading, error } = useAsync(async () => {
    const res = await fetch(`plugin://bereitschaft/heute?team=${team}`);
    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
    return (await res.json()) as Bereitschaft;
  }, [fetch, team]);

  return (
    <InfoCard title="Bereitschaft">
      {loading && <Progress />}
      {error && <WarningPanel title={`Kein Plan für ${team}`} />}
      {value && (
        <Text as="p">
          Heute ({value.datum}) für {team}:{' '}
          <EntityRefLink entityRef={value.person} />
        </Text>
      )}
    </InfoCard>
  );
};
EOF
echo "export { BereitschaftCard } from './BereitschaftCard';" \
  > src/components/BereitschaftCard/index.ts
~/backstage-lab/setup/portal.sh restart
  1. Öffne im Katalog sendungs-api und scrolle im Tab Overview nach unten.
  2. Erwartet: unter den API-Karten die Karte Bereitschaft mit „Heute (…) für team-sendung:” und dem verlinkten Namen. EntityRefLink zeigt den displayName der User-Entity, also „Ben Kraus” statt ben.kraus.
  3. Öffne die API sendungs-api. Erwartet: keine Bereitschaftskarte – der Filter wirkt.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Die Karte konfigurieren

Die Extension-ID setzt sich aus Art, Plugin-ID und Name zusammen: entity-card:bereitschaft/heute. Wie jede Extension (Tag 9) lässt sie sich in app-config.yaml konfigurieren. EntityCardBlueprint kennt die Optionen filter und type; type: info schiebt die Karte in die rechte Spalte. Hänge in app-config.yaml als letzten Eintrag unter app.extensions an (Einrückung wie die übrigen Einträge, Vorlage in code/tag11/app-extensions.yaml):

    # Tag 11: Bereitschaftskarte in die rechte Spalte
    - entity-card:bereitschaft/heute:
        config:
          type: info
~/backstage-lab/setup/portal.sh restart
  1. Lade die Entity-Seite von sendungs-api neu.
  2. Erwartet: die Karte steht jetzt oben rechts über About, wie in der Abbildung.
Entity-Seite von sendungs-api mit der Bereitschaftskarte über der About-Karte
Die Bereitschaftskarte im Detail
  1. Öffne in der Sidebar App-Struktur und wähle den Tab Detailed.
  2. Erwartet: unter page:catalog/entity → entity-content:catalog/overview → cards steht entity-card:bereitschaft/heute als erste Karte, wie in der Abbildung.
Die neue Extension im Extension-Baum unter entity-content:catalog/overview

Warum in app-config.yaml und nicht im Code? So entscheidet der Plattform-Betrieb, wo die Karte sitzt oder ob sie für bestimmte Entities aus ist – ohne neuen Build.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tests, Typen, Lint

Die generierten Tests prüfen noch die Todo-API. Für das Backend ersetzt du sie durch einen Unit-Test des Routers (ohne Backend, mit supertest) und einen Plugin-Test mit startTestBackend, der auch die Auth-Policy prüft:

cd ~/backstage-lab/portal
cat > plugins/bereitschaft-backend/src/router.test.ts <<'EOF'
import { mockErrorHandler } from '@backstage/backend-test-utils';
import express from 'express';
import request from 'supertest';
import { createRouter, wer } from './router';

const teams = { 'team-sendung': ['anna.berger', 'ben.kraus'] };

describe('createRouter', () => {
  const app = express().use(createRouter({ teams })).use(mockErrorHandler());

  it('liefert die Bereitschaft eines Teams', async () => {
    const res = await request(app).get('/heute?team=team-sendung');
    expect(res.status).toBe(200);
    expect(res.body.person).toMatch(
      /^user:default\/(anna\.berger|ben\.kraus)$/,
    );
  });

  it('antwortet 400 ohne team und 404 für unbekannte Teams', async () => {
    expect((await request(app).get('/heute')).status).toBe(400);
    expect((await request(app).get('/heute?team=team-xyz')).status).toBe(404);
  });
});

describe('wer', () => {
  it('wechselt jeden Tag', () => {
    const p = ['a', 'b'];
    const montag = wer(p, new Date('2026-10-12T08:00:00Z'));
    expect(wer(p, new Date('2026-10-13T08:00:00Z'))).not.toBe(montag);
  });
});
EOF
cat > plugins/bereitschaft-backend/src/plugin.test.ts <<'EOF'
import {
  mockCredentials,
  mockServices,
  startTestBackend,
} from '@backstage/backend-test-utils';
import request from 'supertest';
import { bereitschaftPlugin } from './plugin';

describe('bereitschaftPlugin', () => {
  it('liest die Teams aus der Config und verlangt Auth', async () => {
    const { server } = await startTestBackend({
      features: [
        bereitschaftPlugin,
        mockServices.rootConfig.factory({
          data: { bereitschaft: { teams: { 'team-web': ['chris.dietz'] } } },
        }),
      ],
    });
    const url = '/api/bereitschaft/heute?team=team-web';

    const res = await request(server).get(url).expect(200);
    expect(res.body.person).toBe('user:default/chris.dietz');

    await request(server)
      .get(url)
      .set('Authorization', mockCredentials.none.header())
      .expect(401);
  });
});
EOF

startTestBackend behandelt Anfragen ohne Header als angemeldeten Mock-User; mockCredentials.none simuliert den anonymen curl aus Drill 3. Für das Frontend liegt der Test der Karte im Begleitcode. Er rendert die Karte mit einer Fake-Entity und einer fetch-Attrappe und prüft die aufgerufene URL:

cp ~/backstage-lab/code/tag11/frontend/src/components/BereitschaftCard/*.test.tsx \
  plugins/bereitschaft/src/components/BereitschaftCard/
grep -n 'apis:\|mountedRoutes\|toHaveBeenCalledWith' -A1 \
  plugins/bereitschaft/src/components/BereitschaftCard/BereitschaftCard.test.tsx

Erwartet:

27:        apis: [[fetchApiRef, { fetch }]],
28:        mountedRoutes: { '/catalog/:namespace/:kind/:name': entityRouteRef },
29-      },
--
33:    expect(fetch).toHaveBeenCalledWith(
34-      'plugin://bereitschaft/heute?team=team-sendung',

mountedRoutes braucht EntityRefLink, sonst bricht der Test mit No path for routeRef{type=absolute,id=catalog:entity} ab. Jetzt alles prüfen:

CI=true yarn test plugins/bereitschaft
yarn tsc && echo "✔ tsc"
yarn --cwd plugins/bereitschaft lint && yarn --cwd plugins/bereitschaft-backend lint

Erwartet (gekürzt, Pfade abgeschnitten):

PASS @internal/backstage-plugin-bereitschaft-backend …/router.test.ts
PASS @internal/backstage-plugin-bereitschaft-backend …/plugin.test.ts
PASS @internal/backstage-plugin-bereitschaft …/plugin.test.ts
PASS @internal/backstage-plugin-bereitschaft …/BereitschaftCard.test.tsx
Test Suites: 4 passed, 4 total
Tests:       6 passed, 6 total
✔ tsc

CI=true schaltet den Watch-Modus ab, das Muster plugins/bereitschaft trifft beide Pakete. Lint ohne Ausgabe heißt: keine Befunde. Das Root-Skript yarn lint prüft nur Änderungen seit origin/master – im Lab ohne Remote nimm die Paket-Skripte oder yarn lint:all.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

mkdir -p ~/backstage-lab/tag11
cp ~/backstage-lab/code/tag11/kontrolle.sh ~/backstage-lab/tag11/
bash ~/backstage-lab/tag11/kontrolle.sh

Das Skript prüft die Dateien im Portal (Eintrag im Backend, Abhängigkeit der App, Filter, Extension-Konfiguration) und die API mit und ohne Token. Ein Auszug:

t "Ohne Token: 401" \
  "[ \$(curl -s -o /dev/null -w '%{http_code}' \
     \$BACKSTAGE/api/bereitschaft/heute?team=team-sendung) = 401 ]"
t "Mit Lab-Token: Person aus team-sendung" \
  "bs 'bereitschaft/heute?team=team-sendung' |
     jq -e '.person | test(\"anna.berger|ben.kraus\")'"

Erwartet:

✔ Backend-Plugin in packages/backend/src/index.ts
✔ Frontend-Plugin als Abhängigkeit von packages/app
✔ Karte nutzt EntityCardBlueprint mit Filter kind=component
✔ Karte in app-config.yaml als info konfiguriert
✔ Ohne Token: 401
✔ Mit Lab-Token: Person aus team-sendung
✔ Unbekanntes Team: 404

Challenge

Die Karte soll zusätzlich die Telefonnummer der Person zeigen. Die Nummern stehen in der Konfiguration unter bereitschaft.telefon, je User-Name eine.

Hinweis: Das Frontend kann bereitschaft.* nicht lesen (Config ist dort nur mit @visibility frontend sichtbar) – liefere die Nummer im Backend mit.

Lösung

Die geänderten Dateien liegen in code/tag11/challenge/. Die Kernzeilen:

// router.ts – neue, optionale Option und ein Feld mehr in der Antwort
export function createRouter(options: {
  teams: Teams;
  telefon?: Record<string, string>;
}): express.Router {
  // …
    const name = wer(personen, datum);
    res.json({
      team,
      datum: datum.toISOString().slice(0, 10),
      person: `user:default/${name}`,
      telefon: options.telefon?.[name],
    });
// plugin.ts
        const telefon =
          config.getOptional<Record<string, string>>('bereitschaft.telefon') ??
          {};
        httpRouter.use(createRouter({ teams, telefon }));
// BereitschaftCard.tsx – Typ um telefon?: string ergänzen, dann:
      {value?.telefon && <Text as="p">Telefon: {value.telefon}</Text>}

telefon ist optional, damit router.test.ts unverändert kompiliert. Der Konfig-Block ist zwei Leerzeichen eingerückt und gehört unter bereitschaft: – er funktioniert per >> nur, wenn dieser Block am Ende der Datei steht.

cd ~/backstage-lab/portal
C=~/backstage-lab/code/tag11/challenge
cp $C/router.ts $C/plugin.ts plugins/bereitschaft-backend/src/
cp $C/BereitschaftCard.tsx plugins/bereitschaft/src/components/BereitschaftCard/
cat $C/telefon.yaml >> app-config.local.yaml
yarn tsc && CI=true yarn test plugins/bereitschaft 2>&1 | grep '^Tests:'
~/backstage-lab/setup/portal.sh restart
bs 'bereitschaft/heute?team=team-web' | jq

Erwartet:

Tests:       6 passed, 6 total
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{
  "team": "team-web",
  "datum": "2026-10-13",
  "person": "user:default/thomas.zachmann",
  "telefon": "+49 40 5550-202"
}

Auf der Entity-Seite von tracking-web zeigt die Karte jetzt die Nummer, wie in der Abbildung.

Bereitschaftskarte von tracking-web mit Telefonnummer

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Eigene Plugins gehören in ein eigenes Repo oder einen Monorepo-Ordner mit CI: yarn tsc, yarn test, yarn lint und yarn build als Gate vor jedem Merge.
  • Wiederverwendbare Plugins veröffentlichst du in eine interne npm-Registry (--scope, publishConfig); @internal/… ist nur für den Monorepo gedacht.
  • Bereitschaftsdaten kommen in der Praxis aus PagerDuty oder Opsgenie. Dafür gibt es Community-Plugins – vor dem Selberbauen im Plugin-Verzeichnis nachsehen.
  • Eine eigene Config braucht ein Schema (config.d.ts im Plugin), sonst fehlt die Validierung beim Start, und Secrets darin müssen mit @visibility secret markiert sein.
  • Jede neue Route ist Angriffsfläche: Auth-Policy nie pauschal öffnen, Eingaben validieren (die Vorlage nutzt zod), schreibende Routen an Permissions koppeln (Tag 12).