[InnoLab, PLAIN] Aufbrechen und Restrukturieren des Core

Projektübersicht und Ziele

Ziele des Epics:

Der Core-Microservice ist aktuell ein Bottleneck für die Weiterentwicklung und Erweiterbarkeit von F13. Neue Endpoints anzulegen erfordert Code-Änderungen am Core, was vielfältige Probleme nach sich zieht. Zudem vereint das Core-Repository gerade unterschiedliche Aufgaben (Routing+Authentisierung, Feedback-DB, Integrations-Tests, Demo-Deployment), die sich gut voneinander trennen lassen.

Durch diese Vielfalt an Aufgaben ergibt sich auch eine große Zahl an Zielen und möglichen Verbesserungen. Auf die technischen Details wird dabei unter "Technische Anforderungen" eingegangen.

Primäre Ziele:

  • Routing + Authentisierung: Das Routing und die Absicherung nach außen wird von einer konfigurierbaren Komponente übernommen. Die Einbindung eines dezidierten API-Gateways stellt dafür eine vielversprechende Lösung dar. Es gibt in diesem Bereich open-source Lösungen, die hierfür infrage kommen (bspw Apache APISIX). Weiterleitungen zu neuen Endpoints in anderen Microservices erfordern damit nur noch eine Konfigurationsänderung. Dopplungen von pydantic-Modellen, Endpoint-Definitionen und Tests entfallen.
  • Entflechtung der Microservices: Die Konfiguration erlaubt flexibles und eigenständiges Konfigurieren von Microservices, die enge Bindung an einen Core-Microservice entfällt

Sekundäre Ziele:

  • Nutzung weiterer Features des API-Gateway, bspw. für Logging und Monitoring
  • Aufbau einer dezidierten Struktur für Integrations-Tests. Diese gewinnt an Flexibilität/Geschwindigkeit, weil sie beliebige Kombinationen von Services testen kann, statt zwangsläufig alle starten zu müssen.
  • Demo-Deployments (aktuelles docker compose up im Core) können vom Core getrennt angelegt und verwaltet werden.
  • Funktionalität die gerade aus historischen Gründen im Core liegt (bspw. Feedback-Datenbank) wird in eine eigene Komponente ausgelagert.

Stretch Goals/Research:

  • Semi-automatische Konfiguration des API-Gateways mittels automatischem Discovery
  • Konfiguration von Berechtigungen (wer darf welche Funktionalität nutzen) mittels GUI zugänglich machen

Business- und/oder User-Value:

  • Für Endnutzer:innen: indirekt:
    • schnellere Bereitstellung von Features
    • größere Auswahl durch leichte Einbindung zusätzlicher Services
  • Für Administrierende:
    • flexiblere Konfigurationsmöglichkeiten ohne Rebuild des Core-Images
    • mittelfristig leichtere Einbindung zusätzlicher/externer Komponenten
    • einfachere Konfiguration reduziert Gefahr von sicherheitskritischen Konfigurationsfehlern
  • Für Entwickler:innen:
    • Stark vereinfachte Entwicklungsabläufe (Vermeidung von Dopplungen, Reduktion von Abhängigkeiten)
    • schnellere und zielgerichtetere Tests
    • gesteigerte Modularität reduziert Abstimmungsbedarfe und verfeinfacht unabhängige (auch externe) Neu- und Weiterentwicklungen

Gemeinsam mit einem erweiterbaren Aufbau des Frontends ist eine Umstrukturierung des Core maßgeblich, um neue Funktionalitäten unkompliziert integrieren zu können. Davon profitiert sowohl das OS-Projekt direkt als auch externe Contributors, die F13 als Basis für eigene Entwicklungen nutzen wollen.

Transferpotenzial

Übertragbar auf:

  • Andere Behörden/Verwaltungen
  • Andere Fachverfahren
  • Andere F13-Instanzen
  • Externe Projekte

Konkrete Anwendungsbeispiele:

  • F13 soll um eine Chat-Historie erweitert werden:
    • Aktuell: Um die Funktionalität mit dem Frontend zu testen, muss zunächst der Code im Core angepasst werden, um dort händisch für jeden Endpoint eine Weiterleitung zu erstellen. Für Testung und Release muss eine genaue Abstimmung stattfinden, damit zur richtigen Zeit der richtige Code im richtigen Branch liegt.
    • Neu: Es muss nur die Konfigurations-Datei des API-Gateways mit den zusätzlichen Pfaden ergänzt werden.
  • Community-Mitglied A möchte einen neuen Microservice entwickeln und verproben.
    • Aktuell: Erstellung eines Forks des Core-Repository, um die Weiterleitungen einzurichten. Dieser muss durch wiederholtes mergen akutell gehalten werden. Container müssen selbst gebaut werden.
    • Neu: Es können bestehende Container-Images verwendet werden, nur die angepasste Konfiguration muss an die richtige Stelle gemountet werden.
  • Integrationstests von zwei oder mehr Services: Durch die erhöhte Modularität können spezifische Services miteinander getestet und auch nur diese gestartet werden. Ein Filtern der Tests nach beteiligten Services erhöht die Effizienz der Test-Pipeline, wenn nur in bestimmten Bereichen Änderungen vorgenommen wurden. (Dieser Punkt lässt sich auch mit dem aktuellen Stand umsetzen, vereinfacht sich aber, wenn die Tests in einem dezidierten Repository liegen)

User Stories

Story 1

User Story: Als Entwickli möchte ich die Routing-Funktionalität des Core-Microservice durch ein dezidiertes API-Gateway ersetzen, um eine flexible und leicht zu handhabende Konfiguration für Routen zur Verfügung zu stellen.

Update: Der aktuelle Stand für diese Story findet sich auf dem Branch epic-60-aufbrechen-und-restrukturieren-des-core des Core-Repositories.

Akzeptanzkriterien:

  • Mögliche API-Gateways gesichtet und nach folgenden Kriterien bewertet:
    • open-source (notwendig)
    • Unterstützung von openid-connect für Verbindung mit Keycloak (notwendig)
    • Unterstützung gestaffelter Zugriffsrechte, die über Keycloak festgelegt werden können (notwendig)
    • Verfügbare Konfigurationsmöglichkeiten
    • Längerfristige Stabilität/Verfügbarkeit (Etabliertheit, Governance-Struktur)
    • Verfügbarkeit weiterer Funktionalitäten: Logging, Metriken, Rate-Limiting, ...
  • API-Gateway vor den Core-Microservice geschaltet und alle Routen damit gemanaged
  • Authentifizierung von Zugriffen durch Integration mit Keycloak
  • Sicherheit der Authentifizierung geprüft
  • Zugang zu spezifischen Funktionalitäten (Chat, Transkription, ...) kann durch Einstellungen in Keycloak geregelt werden
  • Anpassung der docker-compose.yml Dateien für Testing erfolgt
  • Dokumentation zur Konfiguration des API-Gateways angefertigt

Nicht Teil der Story:

  • Der Core-Microservice kann zunächst unverändert bleiben, es wird nur eine Komponente vorgeschaltet. Routen, bei denen Logik im Core liegt werden zunächst an diesen weitergeleitet.
  • Von "außen" bleibt die Funktionalität zunächst gleich, Tests und andere Microservices sollten wenn möglich unverändert beibehalten werden können.

Story 2

User Story: Als Entwickli möchte ich die Feedback-Datenbank in einen eigenen Microservice auslagern, um den Core zu verschlanken/entfernen und die Feedback-Funktionalität wie andere Services modular nutzbar zu machen.

Akzeptanzkriterien:

Story 3

User Story: Als Entwickli möchte ich Integrations-Tests in ein eigenes Repository verlagern, um diese vom Core unabhängig und damit flexibler und einfacher handhabbar zu machen.

Update: Die Arbeit an dieser Story findet im (aktuell noch privaten) Integration Tests-Repository statt.

Akzeptanzkriterien:

  • Ein Konzept für die Integrations-Tests wurde erstellt, Anforderungen sind:
    • Auszuführende Tests können anhand der beteiligten Microservices ausgewählt werden
    • Es werden im Test nur Microservices gestartet, die tatsächlich genutzt werden
    • Version der zu testenden Microservices kann unkompliziert konfiguriert werden
    • Einfaches Testen von bevorstehenden Releases
  • Bestehende Tests wurden refactored und in ein neues Repository verschoben
  • Test-Strategie validiert und dokumentiert
  • Regelmäßige Tests für relevante Szenarien in die CI-Pipeline integriert

Story 4

User Story: Als Entwickli möchte ich das Demo-Deployment (docker compose up) aus dem Core-Microservice in ein separates Repository verlagern, um dieses unabhängig von Änderungen im Core handhaben zu können (bspw. was Versionen der enthaltenen Microservices betrifft).

Update: Voraussichtlich ist dies die Funktionalität, die im core-Repository verbleibt, selbst wenn es keinen Core-Microservice mehr gibt.

Akzeptanzkriterien:

  • Ein neues Repository wurde angelegt, in dem zu Test- und Demonstrationszwecken mit einem einfachen Kommando F13 mit den wichtigsten Komponenten (und Mock- oder ggf Cloud-Backend) gestartet werden kann.
  • Die Version der gestarteten Microservices ist einfach konfigurierbar
  • Durch festgesetzte Versionen ist das Standard-Demo-Deployment stabil und unabhängig von aktuellen Entwicklungen, die noch nicht Teil eines Release sind (eine "unstable"-Variante mit dem aktuellsten Stand ist zusätzlich ebenfalls möglich, siehe voriges Kriterium).
  • Längerfristiges Zielbild: Man startet F13 und es läuft. Dazu müssen ggf Secrets per User-Eingabe (oder mittels Defaults) mit einem pre-run-Skript befüllt werden. Services die nicht vorhandene Tokens (bspw für den Download von Modellen) benötigen sollten mit einem entsprechenden Hinweis zunächst nicht gestartet werden.

Story 5

User Story: Als Community-Manager:in möchte ich die erfolgten Änderungen mit externen Contributors besprechen und testen, um sicherzustellen, dass diese gut nutzbar ist und sich gut in andere Entwicklungsabläufe integrieren lässt.

Akzeptanzkriterien:

  • Die Entwicklungs-Community wurde über die neue Struktur informiert
  • Feedback, Anregungen und Änderungswünsche wurden eingeholt
  • Wenn möglich: Die neue Struktur wurde anhand einer externen Contribution getestet

Abgrenzung (Out of Scope)

  • Keine inhaltliche Arbeit an Microservices
  • Zunächst keine Einarbeitung neuer Features, die durch die neue Struktur ermöglicht werden (Logging, Metriken, ...)

Technische Anforderungen

API-Design und Schnittstellen

Definition der Endpunkte: Es werden keine neuen Endpunkte eingeführt.

Authentifizierung und Autorisierung: Die Autorisierung muss dem entsprechen, was aktuell im Core möglich ist. Darüber hinausgehende Authentifizierung (bspw. um den Zugriff auf die Landing-Page zu sichern) kann bei Bedarf unkompliziert umgesetzt werden.

Datenflüsse

Das API-Gateway tritt an die Stelle des Core-Microservice und übernimmt dessen Routing-Funktionalität. Daten für die Feedback-Datenbank fließen von der API-Gateway direkt zum neuen Feedback-Datenbank-Microservice.

Microservice-Architektur

  • Betroffene Microservices identifiziert: Core
  • Neuer Microservice notwendig: Ja: Feedback-Datenbank Microservice (Funktionalität bereits implementiert), API-Gateway (externe Komponente)
  • Bestehende Services werden erweitert: Nein
  • Breaking Changes: Ja

Technische Infrastruktur

Support-Services

Datenbanken: Für eine statische, dateibasierte Konfiguration des API-Gateway wird keine Datenbank benötigt. Bei dynamischer Konfiguration wird möglicherweise ein key-value store benötigt (im Stil von etcd, Details hängen vom API-Gateway ab). Zunächst würden wir eine dateibasierte Konfiguration testen.

Weitere Support-Services:

Keine.

Externe Ressourcen

Die Funktionalität wird in einem Container bereitgestellt, der nach seiner Erstellung keine externen Ressourcen benötigt.

Abgrenzung und Schnittstellen

Funktionale Abgrenzung

Siehe Abgrenzung in den User-Stories.

Integration mit anderen Systemen

Das API-Gateway nimmt die Rolle des Core ein. Dadurch steht es im Austausch mit allen anderen Komponenten. Ziel ist jedoch, dass die Endpoints und das Verhalten unverändert bleiben, diese Komponenten sollten die Änderung also nicht wahrnehmen.

Das API-Gateway ersetzt die Routing- und Authentifizierungsfunktionalität des Core. Das kann schrittweise geschehen, indem zu Anfang alle Routen über den Core geleitet werden. Nach und nach können dann Routen direkt an die Microservices geroutet werden, bis der Core-Microservice (nach Auslagerung der Feedback-Datenbank) keine Aufgaben mehr erfüllt. Falls nötig könnte er die Funktion eines Kompatibilitäts-Layers erfüllen, der an bestimmten Anfragen Anpassungen vornimmt um sie weiterzuleiten.

Refactoring

Es handelt sich um ein Refactoring, Details s. vorherige Abschnitte

Checkliste

Datenschutz & Compliance

Durch die hier beschriebenen Änderungen findet keine Änderung in der Art der Datenverarbeitung statt.

Datenverarbeitungstypen:

  • Personenbezogene Daten: Ja / Nein
    • Falls Ja: Art der Daten: ______________________
  • Biometrische Daten: Ja / Nein
    • Falls Ja: Rechtsgrundlage: ______________________
  • Sonstiges Relevantes: Ja / Nein

Freigabe

  • Anforderungsboard
  • Architekturboard
  • Projekt zugeteilt
  • Sprint-Planung, falls vorhanden: Zugeordnet zu Sprint ______
Edited by Valentin Pratz