Zum Hauptinhalt springen

Tenant-Lebenszyklus

Dieser Leitfaden erklärt, was geschieht, wenn Tenants erstellt, angehängt oder wiederhergestellt werden, und welche Schritte Sie in jedem Szenario ausführen müssen.

Einen neuen Tenant erstellen​

Das Erstellen eines neuen Tenants ist die häufigste Operation. Es richtet eine frische, vollständig konfigurierte Umgebung ein.

Was automatisch geschieht​

  1. Das Asset Repository erstellt eine neue MongoDB-Datenbank und registriert den Tenant
  2. Ein PosCreateTenant-Event wird auf dem Distribution Event Hub veröffentlicht
  3. Alle Dienste empfangen das Event und führen ihr Tenant-Setup aus:
    • Importieren ihre Construction-Kit-Modelle
    • Führen Datenmigrationen aus
    • Erstellen MongoDB-Indizes
  4. Der Identity Service erstellt:
    • 10 Standardrollen (TenantManagement, UserManagement usw.)
    • TenantOwners-Gruppe mit allen Standardrollen
    • API-Scopes (octo_api, octo_api.read_only)
    • API-Ressource (octoAPI) und Identity-Ressourcen
    • Standard-Identity-Provider (Google, Microsoft — deaktiviert; nur System-Tenant). Untergeordnete Tenants erhalten stattdessen einen OctoTenant-Provider, der auf den übergeordneten Tenant verweist.

Schritte​

  1. Stellen Sie sicher, dass Sie sich im Kontext des System-Tenants befinden:

    octo-cli -c Config -tid "octosystem" -isu "https://localhost:5003/" -asu "https://localhost:5001/"
    octo-cli -c LogIn -i

  2. Erstellen Sie den Tenant:

    octo-cli -c Create -tid "my-project" -db "my_project_db"

  3. Gewähren Sie sich Zugriff auf den neuen Tenant (vom System-Tenant aus):

    octo-cli -c ProvisionCurrentUser -ttid "my-project"

  4. Wechseln Sie in den Kontext des neuen Tenants:

    octo-cli -c Config -tid "my-project" -isu "https://localhost:5003/"
    octo-cli -c LogIn -i

  5. Konfigurieren Sie Identity Provider (optional):

    octo-cli -c AddAzureEntryIdIdentityProvider -n "Corporate Azure AD" -t "<azure-tenant-id>" -cid "<client-id>" -cs "<client-secret>" -e true

  6. Erstellen Sie Gruppen und weisen Sie Rollen zu (optional):

    octo-cli -c CreateGroup -n "Operators" -rids "DashboardViewer,ReportingViewer"

  7. Importieren Sie Ihr Construction-Kit-Modell:

    octo-cli -c ImportCk -f "./my-model.yaml" -w
info

Schritt 3 (ProvisionCurrentUser) ist kritisch. Ohne ihn können Sie nicht auf den neuen Tenant zugreifen, weil Sie keinen allowed_tenants-Claim für ihn haben.

Tenant-Provisionierung inspizieren und wiederherstellen​

Die Provisionierung eines Tenants — während Create und beim automatischen Setup, das bei jedem Dienststart läuft — ist ein dauerhafter, selbstheilender Prozess: Sein Zustand wird in der Systemdatenbank persistiert, übersteht Dienstneustarts, und ein Hintergrund-Reconciler treibt jedes unvollständige Setup zum Abschluss. Zwei Operatorbefehle lassen Sie diesen Zustand inspizieren und, falls jemals nötig, anstoßen.

Den Lebenszyklus-Zustand inspizieren​

octo-cli -c GetTenantLifecycle -tid "my-project"

Gibt den Provisionierungszustand des Tenants als JSON zurück:

  • State — Creating (Setup läuft), Active (vollständig provisioniert und nutzbar), Deleting (Löschung läuft) oder Failed (Setup hat nach dem Retry-Budget aufgegeben und braucht einen Operator).
  • Phase, AttemptCount, LastError — wie weit das Setup fortgeschritten ist, wie viele Versuche es unternommen hat und der zuletzt beobachtete Fehler, während der Tenant noch nicht Active war.

Ein Tenant ohne Lebenszyklus-Datensatz (zum Beispiel einer, der vor diesem Feature erstellt wurde) meldet „No lifecycle record found" — behandeln Sie ihn als einen normalen, bereits aktiven Tenant.

Einen feststeckenden Tenant wiederherstellen​

In dem seltenen Fall, dass ein Tenant in Creating verbleibt oder als Failed endet — zum Beispiel wenn der Identity- Dienst während eines Bursts von Tenant-Aktivität kurz nicht verfügbar war — öffnen Sie sein Setup erneut, damit der Reconciler es abschließt:

octo-cli -c ReRunTenantSetup -tid "my-project"

Dies setzt den Tenant auf Creating zurück, löscht das Versuchsbudget und lässt den Hintergrund-Reconciler die Provisionierung abschließen. Beobachten Sie mit GetTenantLifecycle, wie er zu Active zurückkehrt.

tipp

Normalerweise benötigen Sie dies nie — das Setup schließt von selbst ab und heilt sich nach Neustarts selbst. ReRunTenantSetup ist ein Sicherheitsventil für den seltenen Fall, dass ein Tenant halb-provisioniert verbleibt.

Eine vorhandene Datenbank anhängen​

Attach registriert eine vorhandene MongoDB-Datenbank als Tenant. Dies wird verwendet, wenn:

  • Eine Datenbank zuvor abgehängt wurde
  • Eine Datenbank außerhalb von OctoMesh erstellt wurde
  • Eine Datenbank von einer OctoMesh-Instanz zu einer anderen verschoben wird

Was automatisch geschieht​

  1. Das Asset Repository registriert die vorhandene Datenbank als Tenant
  2. Anders als Create löst Attach keine vollständige Initialisierung aus — die Datenbank wird als bereits eingerichtet angenommen

Schritte​

  1. Aus dem Kontext des System-Tenants:

    octo-cli -c Config -tid "octosystem" -isu "https://localhost:5003/"
    octo-cli -c LogIn -i

  2. Hängen Sie die Datenbank an:

    octo-cli -c Attach -tid "restored-tenant" -db "existing_database_name"

  3. Leeren Sie den Tenant-Cache (zwingt alle Dienste zur erneuten Initialisierung):

    octo-cli -c ClearCache -tid "restored-tenant"

  4. Gewähren Sie sich Zugriff (falls noch nicht vorhanden):

    octo-cli -c ProvisionCurrentUser -ttid "restored-tenant"
warnung

Wenn Sie eine Datenbank aus einer anderen OctoMesh-Installation anhängen, müssen Sie möglicherweise das System-CK-Modell aktualisieren:

octo-cli -c UpdateSystemCkModel -tid "restored-tenant"

Aus einem Backup wiederherstellen​

Die Wiederherstellung stellt die Daten eines Tenants aus einer Backup-Datei wieder her. Das Backup umfasst alle MongoDB-Daten (CK-Modelle, Runtime-Entitäten, Identity-Daten).

Wichtige Überlegungen​

  • Die Wiederherstellungsoperation überschreibt die Zieldatenbank
  • Sie müssen den Tenant zuerst erstellen oder anhängen
  • Nach der Wiederherstellung müssen Sie den Cache leeren, damit die Dienste die wiederhergestellten Daten übernehmen
  • Wenn das Backup von einer anderen OctoMesh-Version stammt, können beim ersten Zugriff CK-Modell-Migrationen ausgeführt werden
  • Identity-Daten (Benutzer, Rollen, Gruppen, Provider) sind im Backup enthalten

Schritte​

  1. Aus dem Kontext des System-Tenants:

    octo-cli -c Config -tid "octosystem" -isu "https://localhost:5003/"
    octo-cli -c LogIn -i

  2. Erstellen Sie den Tenant zuerst (richtet die Infrastruktur ein):

    octo-cli -c Create -tid "restored-tenant" -db "restored_tenant_db"

  3. Gewähren Sie sich vor der Wiederherstellung Zugriff (Identity-Daten werden überschrieben):

    octo-cli -c ProvisionCurrentUser -ttid "restored-tenant"

  4. Aus dem Backup wiederherstellen (überschreibt die in Schritt 2 erstellte Datenbank):

    octo-cli -c Restore -tid "restored-tenant" -db "restored_tenant_db" -f "./backup.tar.gz" -w

  5. Tenant-Cache leeren (kritisch — Dienste müssen die wiederhergestellten Daten neu laden):

    octo-cli -c ClearCache -tid "restored-tenant"

  6. Sich selbst neu provisionieren (die Wiederherstellung hat möglicherweise Ihre Zuordnung überschrieben):

    octo-cli -c ProvisionCurrentUser -ttid "restored-tenant"
vorsicht

Wenn sich der ursprüngliche Datenbankname des Backups vom Ziel unterscheidet, geben Sie den alten Namen an:

octo-cli -c Restore -tid "restored-tenant" -db "new_database_name" -f "./backup.tar.gz" -oldDb "original_database_name" -w

Aus einer anderen OctoMesh-Instanz wiederherstellen​

Bei der Wiederherstellung aus einem Backup, das auf einer anderen OctoMesh-Installation erstellt wurde:

# After the standard restore steps above:

# Update system CK model to current version
octo-cli -c UpdateSystemCkModel -tid "restored-tenant"

# Clear cache again
octo-cli -c ClearCache -tid "restored-tenant"

# Verify identity providers are correct (may need reconfiguration)
octo-cli -c Config -tid "restored-tenant" -isu "https://localhost:5003/"
octo-cli -c LogIn -i
octo-cli -c GetIdentityProviders

Ein Backup erstellen​

# From the system tenant context with Bot Services configured
octo-cli -c Config -tid "octosystem" -isu "https://localhost:5003/" -bsu "https://localhost:5009/"
octo-cli -c LogIn -i

# Dump the tenant
octo-cli -c Dump -tid "my-project" -f "./my-project-backup.tar.gz"

Das Backup wird als Hintergrundjob erstellt. Die CLI wartet auf den Abschluss und lädt die Datei herunter.

Einen Tenant löschen​

gefahr

Das Löschen eines Tenants entfernt die MongoDB-Datenbank und alle ihre Daten dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden. Wenn Stream Data auf der Instanz aktiviert ist, werden auch die CrateDB-Tabellen der Archive des Tenants verworfen — nach dem Best-Effort-Prinzip: Wenn CrateDB nicht erreichbar ist, gelingt das Löschen dennoch, ein Fehler wird protokolliert, der die Tabellen nennt, die manuell verworfen werden müssen. Nur die eigenen Archivtabellen des Tenants werden berührt, niemals andere Tabellen im selben CrateDB-Schema. Detach behält sowohl die Datenbank als auch die Tabellen; ein Restore über einen vorhandenen Tenant ersetzt nur die Datenbank und behält die Archivtabellen ebenfalls.

octo-cli -c Delete -tid "my-project"
warnung

Ein Tenant kann nur gelöscht werden, während keine seiner optionalen Fähigkeiten aktiviert ist. Wenn Stream Data, Communication, Reporting oder AI Services auf dem Tenant noch aktiviert ist, wird das Löschen mit HTTP 409 abgelehnt, und die Fehlermeldung nennt die noch aktivierten Fähigkeiten.

Deaktivieren Sie sie zuerst. Die Deaktivierungsbefehle nehmen kein -tid-Argument entgegen — sie wirken auf den Tenant des aktiven octo-cli-Kontexts, wechseln Sie also in den Kontext des Tenants, den Sie löschen möchten (UseContext) oder übergeben Sie --context:

octo-cli --context <child-context> -c DisableStreamData
octo-cli --context <child-context> -c DisableCommunication
octo-cli --context <child-context> -c DisableReporting
octo-cli --context <child-context> -c DisableAi

Alle vier Fähigkeiten können alternativ in Refinery Studio unter General > Settings > Tenant Features dieses Tenants deaktiviert werden. Das Panel liest denselben aktivierten Zustand, den diese Vorbedingung auswertet (den aggregierten GET {tenantId}/v1/features/status des Asset Repository), sodass eine Fähigkeit, die das Panel als deaktiviert anzeigt, das Löschen niemals blockiert. Eine Fähigkeit, deren Dienst nicht Teil der Installation ist (seine URL im _configuration-Discovery-Dokument ist leer), wird als Not installed ohne Umschaltbuttons angezeigt; wenn ihr aktiviertes Flag dennoch gesetzt ist, zeigt das Panel eine Warnung an — Löschen und Detach verweigern weiterhin, bis das Flag mit den obigen octo-cli-Befehlen deaktiviert wird.

DisableStreamData hat eine eigene Vorbedingung: Es wird mit HTTP 409 abgelehnt, solange irgendein Archiv des Tenants noch aktiviert ist — der Fehler nennt sie. Deaktivieren Sie sie zuerst mit DisableArchive (Daten bleiben erhalten) oder entfernen Sie sie mit DeleteArchive (Rollups vor ihrem Quellarchiv) oder in Refinery Studio unter Repository > Archives. Der Befehl schaltet nur das Tenant-Flag aus: Das System.StreamData-Modell, die Archivdefinitionen und die gespeicherten Streamdaten verbleiben im Tenant (siehe Stream Data Archives und die Studio-Archivseite).

octo-cli --context <child-context> -c DisableArchive -id <archiveRtId>
octo-cli --context <child-context> -c DisableStreamData

DisableCommunication hat eine eigene Vorbedingung: Es wird mit HTTP 409 abgelehnt, solange irgendein Deployment Site oder Workload (Adapter oder Application) des Tenants noch deployt ist — der Fehler nennt sie mit ihrem Deployment-Zustand. Undeployen Sie sie zuerst mit UndeployWorkload (ein Aufruf pro Workload) und dann UndeployPool (beide wirken auf den Kontext-Tenant, wie die Deaktivierungsbefehle) oder in Refinery Studio unter Communication > Adapters / Applications / Deployment Sites. Pipelines und Pipeline-Trigger benötigen keine Aktion — das Deaktivieren von Communication kümmert sich um sie.

octo-cli --context <child-context> -c UndeployWorkload -id <workloadRtId> -y
octo-cli --context <child-context> -c UndeployDeploymentSite -id <deploymentSiteRtId> -y
octo-cli --context <child-context> -c DisableCommunication

DisableReporting und DisableAi haben keine eigene Vorbedingung: Beide entfernen nur das aktivierte Flag. Berichtsdefinitionen und gespeicherte Berichte (Reporting) sowie die AI-Konfiguration und Sitzungsdaten (AI Services) verbleiben im Tenant und sind nach EnableReporting / EnableAi wieder nutzbar (EnableAi erfordert, dass Communication auf dem Tenant aktiviert ist).

Wenn die Daten des Tenants noch benötigt werden, erstellen Sie mit Dump ein Backup, bevor Sie die Fähigkeiten deaktivieren (siehe Ein Backup erstellen) — Dump ist von dieser Vorbedingung nicht betroffen.

info

Ein Delete, dem sofort ein neues Create desselben Tenant-IDs folgt (zum Beispiel beim Ersetzen eines Demo-Tenants), ist sicher: Während die vorherige Löschung ihren Datenbank-Drop noch abschließt, gibt das Create ein wiederholbares „deletion still in progress, retry later" (HTTP 409) statt eines verwirrenden Fehlers zurück — wiederholen Sie es einfach, und es gelingt, sobald der Drop abgeschlossen ist.

Einen Tenant abhängen​

Detach hebt die Registrierung eines Tenants bei OctoMesh auf, behält aber seine MongoDB-Datenbank. Verwenden Sie es, um eine Datenbank zu einer anderen OctoMesh-Instanz zu verschieben oder einen Tenant außer Betrieb zu nehmen, ohne seine Daten zu verlieren. Die Datenbank kann später mit Attach erneut registriert werden.

octo-cli -c Detach -tid "my-project"
  • Der Tenant muss ein untergeordneter Tenant des Tenants in Ihrem aktuellen Kontext sein (wie bei Delete); andernfalls wird das Detach mit HTTP 404 abgelehnt.
  • Dieselbe Vorbedingung wie bei Delete gilt: Stream Data, Communication, Reporting und AI Services müssen zuerst auf dem Tenant deaktiviert werden, andernfalls wird das Detach mit HTTP 409 abgelehnt, wobei die noch aktivierten Fähigkeiten genannt werden. Die Deaktivierungsbefehle finden Sie in der Warnung in Einen Tenant löschen.

Einen Tenant bereinigen​

Das Bereinigen setzt einen Tenant auf die Werkseinstellungen zurück, indem alle CK-Modelle (außer System) und alle Runtime-Entitäten entfernt werden, während die Datenbank erhalten bleibt:

octo-cli -c Clean -tid "my-project"

Zusammenfassung der Operationen​

OperationErstellt DBInitialisiert KonfigErhält DatenWann verwenden
CreateJaJa–Einen frischen Tenant einrichten
AttachNeinNeinJaEine vorhandene Datenbank neu registrieren
RestoreNein (benötigt zuerst Create)ÜberschriebenBackup-DatenAus einem Backup wiederherstellen
CleanNeinTeilweiser ResetNeinAuf Werkseinstellungen zurücksetzen
DeleteVerwirft DB (+ CrateDB-Archivtabellen)–NeinEinen Tenant dauerhaft entfernen
DetachNein (behält DB)–JaEinen Tenant deregistrieren und dabei seine Datenbank behalten