Betriebsanleitungen (Runbooks)

Im bestehenden database‑Container (PostGIS):

Kein Schema anlegen — persistence_autoUpdateDatabase=true baut es beim ersten Start selbst auf.

Im bestehenden Realm (in der Entwicklungsumgebung FROST-Test) einen Client frost-server-<slug> nach dem Vorbild des bestehenden Clients frost-server anlegen und dessen Secret (auth_keycloakConfigSecret) notieren.

Anschließend dem bestehenden globalen Adapter‑Benutzer die Client‑Rollen dieses neuen Clients zuweisen.

Den Block frost_server kopieren und fünf Werte ändern: Port, Service‑Root‑URL, Datenbank, Datenbankbenutzer/‑passwort und Keycloak‑Client. Das Image‑Tag bleibt überall identisch (siehe Image‑Tag).

auth_allowAnonymousRead ist die Stelle, an der die Anforderung „manche Kunden wollen ihre Daten hinter einer Authentifizierung“ tatsächlich zu einem Schalter wird — pro Instanz, und genau das ist der Gegenwert der Topologie ein FROST‑Server je Mandant.

Den Service hochfahren und die Initialisierung über die Admin‑Seite DatabaseStatus des FROST‑Servers anklicken. Dieser Schritt ist manuell und hat kein API‑Äquivalent.

An die Registry gehen genau zwei Werte:

Nichts anderes aus diesem Ablauf landet in der Mandantenzeile. Datenbankpasswort und Client‑Secret kennt der Adapter nie.

Danach wird der Mandant über die Verwaltungsoberfläche registriert; die Registrierung überträgt anschließend alle Observed Properties in den neuen, leeren FROST‑Server.

Alle FROST‑Instanzen laufen auf demselben festgeschriebenen Tag (FROST_SERVER_TAG, Standard 2.7.3), niemals auf latest. Zwei Instanzen auf unterschiedlichen Versionen unterscheiden sich im Verhalten der SensorThings‑API, und ein docker compose pull würde diesen Unterschied unbemerkt erzeugen. Eine Versionsanhebung ist eine Änderung an .env und betrifft dann alle Mandanten gleichzeitig.

Wurde der FROST‑Server zuerst abgebaut, lässt sich der Mandant über die API nie mehr löschen: die Löschprüfung fragt seinen FROST‑Server, ob dort noch Things hängen, und bekommt keine Antwort mehr — „nicht erreichbar“ gilt fail‑closed als „nicht freigegeben“.

Die Folge trifft nicht nur diesen Mandanten. Die tote Zeile lässt jede Löschung einer globalen ObservedProperty, eines TelemetryKey und einer UnitOfMeasurement dauerhaft und für alle scheitern, weil auch diese Prüfungen über alle Mandanten laufen und fail‑closed sind. Ein Force‑Flag gibt es bewusst nicht.

Der einzige Ausweg ist eine von Hand ausgeführte Anweisung gegen die Adapter‑Datenbank:

Ein Mandant wird nicht umbenannt, sondern gelöscht und neu angelegt — der Slug ist unveränderlich, weil er in der Rule‑Chain‑URL eines fremden Systems steht. Praktisch sind das die Schritte 1 und 2 oben, danach eine neue Registrierung gegen denselben frost_server_url, ohne Schritt 3.

Dabei bleiben die Observed‑Property‑Kopien des alten Slugs im FROST‑Server des Mandanten liegen; sie sind nachweislich inert, tauchen aber in der öffentlichen SensorThings‑Sammlung doppelt auf, und jedes weitere Umbenennen legt einen weiteren Satz an. Sie sind deshalb von Hand zu entfernen, solange noch klar ist, welcher Satz der aktuelle ist:

Unter PE trägt der API‑Key jede Anfrage und läuft nicht ab. Unter CE hält der Client ein JWT mit 150 Minuten Lebensdauer, während der Client‑Cache ihn für die Lebensdauer des Prozesses behält — ohne Gegenmaßnahme wäre nach 2,5 Stunden jeder ThingsBoard‑Zugriff dieses Mandanten kaputt, bis jemand den Adapter neu startet.

Die Gegenmaßnahme steht im Cache selbst (clients/tenant_clients.py): Er beantwortet zwei Fragen, und beide lauten „ist dieses Client‑Paar noch brauchbar?“ — hat sich die Zeile geändert (Fingerprint), und läuft die Sitzung ab (exp des Tokens, mit fünf Minuten Sicherheitsabstand). Trifft eines von beidem zu, wird das Paar neu gebaut. Unter PE ist exp schlicht 0, weil ein API‑Key gar kein Token hinterlegt; dort läuft nie etwas ab.

Nicht abgedeckt ist eine Sitzung, die ThingsBoard vorzeitig beendet — ein dort rotiertes Passwort oder eine von einem Administrator beendete Sitzung. Ein rotiertes Passwort muss ohnehin in die Mandantenzeile eingetragen werden, damit der Adapter es benutzen kann, und bewegt damit den Fingerprint; der zweite Fall ist selten und heilt spätestens mit exp. Bis dahin zeigt sich beides als fehlgeschlagene Anfrage und rotes Test connection.

Schritt 6 ist die einzige Prüfung, die Slug‑Routing, Mandantenauflösung, Client‑Auswahl, Sperrschlüssel und den Schreibvorgang gemeinsam ausübt. Ein 201 bei der Registrierung und ein sauberer Abgleichbericht sind seine Voraussetzung, kein Ersatz: die Rule Chain verwirft Fehler stillschweigend, weshalb „der Adapter ist gesund“ und „Telemetrie kommt an“ nie gleichgesetzt werden dürfen. Schlägt Schritt 6 fehl, ist das Debug‑Fenster der Rule Chain die richtige Stelle — eine falsche URL nach dem Neuimport ist die wahrscheinlichste Ursache.

Der Rückweg ist derselbe Wisch in die andere Richtung: vorheriges Image aufbauen, alte Chain importieren, einen leeren FROST‑Server hinnehmen.

Die Mandantenzeile wird getippt, nicht geseedet. Ein Übernahmeskript oder ein Auto‑Seed aus den alten Umgebungsvariablen wurde verworfen: er würde genau die Mandanten‑Kenntnis in bootstrap() zurückholen, die entfernt wurde, die alten Umgebungsvariablen über ihre Nützlichkeit hinaus in Config am Leben halten und ab dem Tag nach der Umstellung toten Code hinterlassen.

Der Slug ist der slugifizierte Name des ThingsBoard‑Mandanten, nicht dev. Er steht an drei Stellen, die übereinstimmen müssen — in den Rule‑Chain‑URLs, im Namensraum der Redis‑Sperren und in einer unveränderlichen Registry‑Zeile. dev benennt eine Umgebung, und der erste echte Mandant würde diesen Namen für immer tragen. Späteres Auseinanderlaufen, wenn jemand den Anzeigenamen in ThingsBoard ändert, ist harmlos: slug und name sind getrennte Felder.