Kaltstart einer Installation

Worum es geht

Kaltstart heißt: eine Installation fährt hoch, und zwar so, dass danach die erste echte Anfrage beantwortet werden kann. Zwischen „Prozess gestartet“ und „bereit“ liegen mehrere Schritte, und sie haben eine feste Reihenfolge.

Diese Seite beschreibt den Ablauf über beide Module hinweg. Was die einzelnen Schalter bedeuten, steht unter Was läuft, bestimmt die Konfiguration.

Der Zeitstrahl

flowchart LR
    A["1 Schema<br/>Tabellen anlegen und anheben"] --> B["2 Kontext<br/>Objekte bauen, Angaben prüfen"]
    B --> C["3 Bootstrap<br/>Plattformrollen, erster Mandant,<br/>erster Administrator"]
    C --> D["4 Abgleich<br/>Realm-Rollen, Deklarationen, Gruppen"]
    D --> E["5 Zeitgeber<br/>starten, wenn eingeschaltet"]
    E --> F(["bereit für die erste Anfrage"])
    classDef stufe fill:#8e24aa,stroke:#8e24aa,color:#fff
    classDef ziel fill:#4d7c0f,stroke:#4d7c0f,color:#fff
    class A,B,C,D,E stufe
    class F ziel

Die Grenze zwischen 3 und 4 ist keine Feinheit: Bootstrap und Abgleich hängen an verschiedenen Ereignissen des Anwendungsstarts. Der Bootstrap läuft als Startlauf direkt nach dem Hochfahren, der Abgleich erst, wenn die Anwendung sich selbst als bereit meldet. Der Bootstrap ist also immer zuerst fertig, und das muss er auch sein: er schreibt die Rollen in den Katalog, die der Abgleich danach in Ruhe lässt.

Die fünf Stufen im Einzelnen

Ein Kaltstart von oben nach unten

1

CIAS→Datenbank
1 Schema. Die Tabellen entstehen oder werden angehoben, bevor Hibernate sie ansieht

Mit Starter ein eigener Migrationslauf je CIAS-Modul; ohne Starter über die Persistenz des Gastgebers. Einzelheiten unter Datenbanken und Schemata.
2

CIAS
2 Kontext. Spring baut die Objekte. Jede Angabe, ohne die CIAS raten müsste, wird jetzt geprüft

Wer das Mandanten-Tor beantwortet, die Betriebsart der Datenhaltung, die Liste der Module mit ihren Namen und Quellen, die Leserolle für GET /cias/fetch. Eine fehlende Angabe bricht hier ab, mit dem Namen der Einstellung in der Meldung.
3

CIAS→Datenbank
3 Bootstrap. Eine leere Installation bekommt ihre Plattformrollen, ihren ersten Mandanten und ihren ersten Administrator

Nur wenn codamai.cias.bootstrap.enabled auf true steht. Alles darin ist wiederholbar: Was schon da ist, bleibt unverändert.
4

CIAS→Keycloak
4 Abgleich. Erst die Realm-Rollen der Installation, dann die Deklarationen aller Module, dann die Gruppen

Nur wenn codamai.cias.authorization.startup.enabled auf true steht. Dieser Lauf wirft nie: Ist Keycloak weg oder ein Modul nicht erreichbar, wird das gemeldet und die Anwendung startet trotzdem.
5

CIAS
5 Zeitgeber. Die Hintergrundläufe beginnen, sofern sie eingeschaltet sind

Ergebnis: Die Anwendung nimmt Anfragen an. Der erste Kunde läuft durchs Mandanten-Tor.

Stufe 2: Was den Start abbricht

Der Kontextbau ist die Stelle, an der die meisten Fehler auffallen — absichtlich, denn hier ist ein Fehler noch eine Zeile in einer Datei und nicht ein Dienst ohne Rechte.

Was beim Kontextbau geprüft wird

Angabe	Wenn sie fehlt oder nicht stimmt
`codamai.cias.tenancy.lookup`	Start bricht ab. Ohne sie gäbe es niemanden, der das Mandanten-Tor beantwortet
`codamai.persistence.tenant.mode`	Start bricht ab, wo es CDMS-Persistenz gibt
`codamai.cdms.cias.reader-roles` in CDMS	Start bricht ab. Eine leere Angabe ist erlaubt und heißt „niemand“
ein Modul in der Deklarationsliste ohne Namen oder mit doppeltem Namen	Start bricht ab. Der Name sagt, wem eine Rolle gehört
ein Modul mit `bean` und `url`, oder mit keinem von beidem	Start bricht ab. Genau eine Angabe sagt, wo die Deklaration liegt
eine `bean`, die es in dieser Anwendung nicht gibt	Start bricht ab, mit dem Namen der Bean in der Meldung
ein Modul mit `url`, aber ohne `reader-token`	Start bricht ab. Der Endpunkt verlangt eine Leserolle
ein Migrationsort ohne Skripte	Start bricht ab. Ein Tippfehler im Ort würde sonst still nichts migrieren
Keycloak ist gerade nicht erreichbar	Kein Startfehler. Das fällt erst in Stufe 4 auf und wird dort gemeldet

Stufe 3: Was der Bootstrap tut

Eine frische Installation hat einen leeren Rollenkatalog. Aus diesem Katalog lässt sich nichts befüllen: Eine Rolle anzulegen darf nur ein Plattform-Administrator, und wer die Plattform verwaltet, sagt der Katalog. Dieser Kreis wird an genau einer Stelle aufgebrochen, beim ersten Start.

Der Bootstrap, Schritt für Schritt

1

CIAS
gibt sich für die Dauer des Laufs einen Aufruferkontext mit den Plattformrollen dieser Installation und räumt ihn danach wieder weg

Derselbe Weg, den sonst ein geprüftes Token nimmt. Er ist auf diese eine Methode beschränkt, läuft einmal und schreibt auf, was er getan hat.
2

CIAS
trägt jede konfigurierte Rolle in den Katalog ein, die noch nicht drin ist

Auf Realm-Ebene und ohne Eigentümermodul. Deshalb legt später kein Abgleich sie still: Der Abgleich vergleicht je Modul, und was keinem Modul gehört, lässt das Schweigen eines Moduls in Ruhe. Typisch stehen hier nur die zwei Rollen, die über allen Modulen liegen.
3

CIAS
legt den ersten Mandanten an, falls einer konfiguriert ist und es ihn noch nicht gibt

Über denselben Weg wie jedes spätere Anlegen, samt Einrichtung der Datenbank. Siehe Ein neuer Mandant, Ende zu Ende.
4

CIAS→Keycloak
sucht das Konto zur konfigurierten Administrator-Adresse
5

CIAS
Es gibt kein solches Konto → Start bricht ab

CIAS hält keine Zugangsdaten und kann deshalb kein Konto anlegen. Eine genannte Adresse ohne Konto ist eine Aussage, die nicht aufgeht — sie wird nicht übersprungen.
6

CIAS→Keycloak
vergibt die Plattformrollen an dieses Konto

Ergebnis: Die Installation hat einen Katalog, gegebenenfalls einen Mandanten und einen Menschen, der sich anmelden und weiterarbeiten kann.

Stufe 4: Was der Abgleich tut

Der Startabgleich

1

CIAS→Keycloak
legt die Realm-Rollen an, die die Installation in ihrer Konfiguration nennt

Diese kommen nie aus einer Deklaration. Realm-Ebene ist das, was über allen Modulen liegt, und ein Modul kann die Folgen einer solchen Rolle nicht überblicken.
2

CIAS→CDMS
liest die Deklaration jedes konfigurierten Moduls, als Bean oder über GET /cias/fetch
3

CIAS→Keycloak
schreibt Benutzerprofil, Client-Rollen und Claim-Mapper, danach den Katalog

Einzelheiten unter Der Abgleich mit Keycloak.
4

CIAS→Keycloak
gleicht die Gruppen ab: fehlende Kopien anlegen, Rollen und Mitglieder auf den Stand bringen

Ergebnis: Siehe Abgleich mit Keycloak.

Beide Läufe hängen an einem Schalter (codamai.cias.authorization.startup.enabled) und an dem des Moduls. Keiner von beiden bricht den Start ab. Der Grund ist dieselbe Abwägung an beiden Stellen: Eine Rolle, die noch nicht angelegt ist, fällt später auf und lässt sich nachholen; eine Plattform, die nicht hochkommt, weil Keycloak gerade neu startet, ist ein größerer Schaden. Eine Rolle anzulegen vergibt sie außerdem an niemanden — deshalb darf dieser Lauf unbeaufsichtigt laufen.

Die Ausprägungen

Wie ein Kaltstart aussieht

Bootstrap anBootstrap ausErster Administrator fehlt in KeycloakEingebettetGetrennt

Wann: codamai.cias.bootstrap.enabled: true, üblicherweise genau einmal auf einer frischen Installation.

Stufe 3 läuft und füllt den Katalog, gegebenenfalls den ersten Mandanten und die Rolle des ersten Administrators. Bei einer Installation, die schon läuft, findet der Lauf alles vor und ändert nichts.

Ergebnis: Nach dem Start gibt es einen Katalog und jemanden, der ihn verwalten darf.

Wann: Der Schalter fehlt oder steht auf false. Das ist der Normalfall im laufenden Betrieb.

Stufe 3 entfällt vollständig. Nichts wird geschrieben, und keine der Verbindungen, die der Bootstrap bräuchte, wird überhaupt aufgebaut — ein Start ohne Bootstrap fragt Keycloak an dieser Stelle gar nicht erst.

Ergebnis: Der Start geht direkt von Stufe 2 zu Stufe 4.

Wann: Eine Administrator-Adresse ist konfiguriert, aber es gibt kein Konto dazu.

1

CIAS→Keycloak
sucht das Konto zur Adresse
2

CIAS
findet keines und bricht den Start ab

Ebenso, wenn die Installation gar keine Plattformrolle nennt: Dann gibt es nichts zu vergeben, und eine der beiden Aussagen ist nicht gemeint.

Ergebnis: Erst das Konto in Keycloak anlegen, dann neu starten. Die Reihenfolge ist nicht verhandelbar — CIAS hält keine Zugangsdaten.

Wann: CDMS und CIAS laufen im selben Prozess.

Ein Kaltstart für beides. Die Deklaration von CDMS ist eine Bean im selben Prozess, der Abgleich braucht kein Netz und kein Token. Die CIAS-Tabellen liegen in der System-Datenbank des Gastgebers. Den Bootstrap gibt es nur, wenn der Gastgeber den Starter mitbringt.

Ergebnis: Ist der Prozess oben, ist alles oben.

Wann: CIAS ist ein eigener Dienst.

Zwei Kaltstarts, die nichts voneinander wissen. Jeder Dienst migriert sein eigenes Schema und baut seinen eigenen Kontext. Erst in Stufe 4 berühren sie sich: CIAS ruft GET /cias/fetch beim CDMS-Dienst auf. Ist der noch nicht oben, gilt sein Modul als nicht lesbar — an seinen Rollen ändert sich dann nichts, auch keine Stilllegung.

Ergebnis: Die Reihenfolge der beiden Dienste ist frei. Was beim ersten Anlauf nicht gelesen wurde, holt der nächste Abgleich nach.

Was danach im Hintergrund läuft

Zwei Zeitgeber gehören zum Betrieb, und beide sind standardmäßig aus. Einen Hintergrundlauf zu starten ist eine Entscheidung der Anwendung, nicht des Jars.

Zeitgeber	Schalter	Was er tut
Rollensynchronisation	`codamai.cias.authorization.synchronization.enabled`	lässt abgelaufene befristete Rollen wirklich ablaufen, voreingestellter Abstand 5 Minuten
Mandanten-Abgleich	`codamai.cias.tenancy.reconciliation.enabled`	findet liegengebliebene Einrichtungen und setzt sie auf `FAILED`, voreingestellter Abstand 15 Minuten

Der eigenständige CIAS-Dienst schaltet beide ein. Eine Anwendung, die CIAS ohne Starter einbettet, hat sie nicht — dort gibt es keinen Zeitgeber, und beides muss angestoßen werden.

Fallen

Weiter

Module melden Rollen und Attribute an: was in Stufe 4 gelesen wird
Ein neuer Mandant, Ende zu Ende: was in Stufe 3 beim ersten Mandanten passiert
Datenbanken und Schemata: was in Stufe 1 passiert
Was läuft, bestimmt die Konfiguration und CIAS eingebettet
Der Abgleich mit Keycloak und Abgleich der Gruppen
Die Realm-Rollen der Plattform