APISIX-Routen verwalten
Die UDSP stellt für APISIX eine administrative Weboberfläche bereit. Berechtigte Administratoren können dort Upstreams und zusätzliche Routen konfigurieren, ohne unmittelbar das Plattformrepository zu verändern.
Ein bereits bereitgestellter Dienst ist über einen eindeutigen Pfad des UDSP-Gateways erreichbar. Die Route verweist auf das richtige interne Ziel, lässt nur die vorgesehenen HTTP-Methoden zu und wurde mit erlaubten sowie abgelehnten Zugriffen geprüft.
Zugang festlegen
Zielgruppe, externer Pfad, Methoden und benötigter Schutz sind geklärt.
Dashboard öffnen
Die APISIX-Oberfläche wird mit dem freigegebenen Admin-Key verbunden.
Upstream anlegen
Interner Host, Port, Protokoll und Erreichbarkeit des Dienstes werden konfiguriert.
Route anlegen
URI, Host, Methoden, Upstream und freigegebene Plugins werden zusammengeführt.
Zugriff prüfen
Erlaubte und nicht erlaubte Aufrufe werden getestet und dokumentiert.
UI oder Plattformbereitstellung?
Die Plattforminstallation erzeugt bereits Standardrouten für Stellio, FROST, GeoServer, den Geoportal-Konfigurationsdienst und weitere technische Zugänge. Diese Routen besitzen abgestimmte Scopes, Datenraumprüfungen und Telemetrie-Plugins. Ändern oder löschen Sie sie nicht über die Oberfläche.
Zusätzliche Routen werden im laufenden Betrieb grundsätzlich über das APISIX Dashboard verwaltet. APISIX speichert die Konfiguration in etcd. Änderungen über die Oberfläche bleiben daher nach einem Neustart der APISIX-Pods erhalten und müssen nicht zusätzlich durch ein Ansible-Playbook ausgeführt werden.
Eine zusätzliche Route über das Dashboard ist sinnvoll, wenn:
- der Zieldienst bereits in der UDSP erreichbar ist,
- der Zugang nur für einen konkreten Mandanten oder Anwendungsfall benötigt wird,
- ein eigener, noch nicht belegter Pfad vereinbart wurde und
- Schutzbedarf und verantwortliche Stelle feststehen.
Das Dashboard ist der normale Administrationsweg für zusätzliche Routen in einer bestehenden UDSP. Ansible stellt dagegen die von der Plattform benötigten Standardrouten bei einer Neuinstallation reproduzierbar bereit. Eine über die UI angelegte Route muss nur dann in die Plattformbereitstellung übernommen werden, wenn sie künftig zum verbindlichen Standard jeder UDSP-Installation gehören soll.
1. APISIX Dashboard öffnen
Die aktuelle UDSP-Konfiguration veröffentlicht die eingebettete APISIX-Oberfläche unter:
https://api-admin.<DOMAIN>/ui/
Öffnen Sie dort die Einstellungen und hinterlegen Sie den freigegebenen APISIX API Key. Der Schlüssel wird in der technischen Mandantenkonfiguration unter apisix.api_credentials bereitgestellt.
Viewer-Key
Dient zur Kontrolle vorhandener APISIX-Ressourcen, erlaubt aber keine administrativen Änderungen.
Admin-Key
Erlaubt das Anlegen, Ändern und Löschen von Upstreams, Routen und Plugins.
Das Dashboard verwendet aktuell einen APISIX API Key und keine persönliche Keycloak-Anmeldung. Behandeln Sie den Admin-Key daher wie ein Plattform-Secret: nicht in Screenshots, Tickets, Node-RED-Flows oder Git-Repositories übernehmen und nur an den vorgesehenen Administrationskreis ausgeben.
2. Upstream anlegen
Ein Upstream beschreibt das interne Ziel, an das APISIX passende Anfragen weiterleitet. Öffnen Sie im Dashboard Upstreams und legen Sie einen neuen Eintrag an.
Name
Eindeutiger Name mit Bezug zu Mandant und Anwendung, beispielsweise stadt-messwerte-api.
Host und Port
Aus dem APISIX-Namespace erreichbarer Kubernetes-Service beziehungsweise freigegebener interner Endpunkt.
Schema
HTTP oder HTTPS entsprechend dem tatsächlichen internen Dienst; nicht anhand der externen URL ableiten.
Timeout und Health Check
Bewusste Grenzwerte und – sofern vorhanden – ein geeigneter technischer Health-Endpunkt.
Verwenden Sie für einen einzelnen Ziel-Pod keine wechselnde Pod-IP. Tragen Sie den stabilen Kubernetes-Service ein. Prüfen Sie vor dem Speichern gemeinsam mit dem Plattformbetrieb, ob APISIX diesen Dienst und Port über die geltenden NetworkPolicies erreichen kann.
3. Route anlegen
Öffnen Sie Routes, wählen Sie Create und konfigurieren Sie mindestens:
| Feld | Entscheidung |
|---|---|
| Name | eindeutige Bezeichnung mit Mandant und Zweck |
| Host | normalerweise api.<DOMAIN> für das zentrale UDSP-Gateway |
| URI | eigener Pfad, beispielsweise /gateway/messwerte/* |
| Methods | nur tatsächlich benötigte Methoden wie GET oder POST |
| Upstream | der zuvor geprüfte interne Zieldienst |
| Status | erst nach vollständiger Konfiguration aktivieren |
Vermeiden Sie breite Muster wie /*, weil sie bestehende Zugänge überschneiden können. Trennen Sie lesende und schreibende Zugriffe in unterschiedliche Routen, wenn dafür unterschiedliche Schutzregeln gelten.
4. Schutz und Plugins festlegen
Eine erreichbare Route ist noch keine sicher freigegebene Route. Entscheiden Sie ausdrücklich, ob der Zugang öffentlich sein darf oder ein gültiges Keycloak-Token benötigt.
- Aktivieren Sie eine Route ohne Authentifizierung nur nach dokumentierter fachlicher und datenschutzrechtlicher Freigabe.
- Verwenden Sie für geschützte Zugänge das abgestimmte OpenID-Connect-Profil der UDSP.
- Ordnen Sie lesenden, schreibenden und löschenden Zugriffen die vorgesehenen Scopes zu.
- Übernehmen Sie eine Datenraumprüfung nur aus einem freigegebenen UDSP-Muster; eine bloße Prüfung auf ein vorhandenes Token reicht für mandantenbezogene Daten nicht aus.
- Aktivieren Sie die vereinbarten Metrik- und Logging-Plugins, ohne sensible Request- oder Response-Inhalte unkontrolliert zu protokollieren.
Die Werte für OIDC-Client, Client-Secret, Discovery-URL und Datenraumprüfung sind plattformspezifisch. Wenn dafür kein freigegebenes Profil vorliegt, speichern Sie keine ungeschützte Ersatzroute, sondern stimmen die Erweiterung mit dem Plattformbetrieb ab.
5. Route abnehmen
Prüfen Sie die Route unmittelbar nach dem Speichern mit einer kleinen Testmatrix:
| Prüfung | Erwartetes Ergebnis |
|---|---|
| vorgesehene Methode und gültiger Zugang | Anfrage erreicht den Upstream |
| nicht freigegebene HTTP-Methode | Anfrage wird am Gateway abgelehnt |
| fehlender oder ungültiger Token | geschützte Route lehnt die Anfrage ab |
| unzulässiger Datenraum | mandantenbezogene Route lehnt die Anfrage ab |
| nicht vorhandener Zielpfad | kontrollierter Fehler ohne Offenlegung interner Details |
Dokumentieren Sie anschließend Route-ID, externen Pfad, Upstream, erlaubte Methoden, Schutzprofil, verantwortliche Stelle und Prüfergebnis. Deaktivieren Sie nicht mehr benötigte Routen zunächst und löschen Sie sie erst, wenn keine Anwendung mehr davon abhängt.
Persistenz und Nachvollziehbarkeit
Dashboard-Änderungen werden direkt in etcd gespeichert und sind damit persistent. Ein normaler Neustart oder erneuter Rollout der APISIX-Pods entfernt sie nicht. Die Oberfläche ist deshalb der geeignete Weg, um zusätzliche Routen im laufenden Betrieb zu verwalten.
Die UI-Konfiguration wird jedoch nicht automatisch versioniert und lässt sich nicht allein aus dem Core-Platform-Repository in einer neuen Umgebung wiederherstellen. Dokumentieren Sie deshalb mindestens Route-ID, Upstream, Schutzprofil, verantwortliche Stelle und Prüfergebnis. Nur plattformweit verbindliche Standardrouten gehören zusätzlich in die Ansible-Bereitstellung.
Damit weiterarbeiten
APISIX in der Plattform
Rolle, Standardrouten, Schlüssel und technische Abhängigkeiten des Gateways.
Referenz öffnenAPI-Zugriff und Sicherheit
Tokenbezug und zentraler Zugriffspfad der geschützten Fach-APIs.
Referenz öffnen