Zum Hauptinhalt springen

Common Workflows

Playbooks mit mehreren Befehlen für typische octo-cli-Nutzungsszenarien. Jeder Schritt hat seinen eigenen kopierbaren Codeblock – fügen Sie sie nacheinander ein. Die vollständige Dokumentation pro Befehl finden Sie im Abschnitt Command Reference in der Seitenleiste.

Initiales Setup​

  1. Endpunkte konfigurieren:

    octo-cli -c Config `
      -isu "https://localhost:5003/" `
      -asu "https://localhost:5001/" `
      -tid "meshtest"

  2. Anmelden:

    octo-cli -c LogIn -i

  3. Tenant erstellen:

    octo-cli -c Create -tid "myproject" -db "myproject_db"

  4. Sich selbst Zugriff auf den neuen Tenant gewähren:

    octo-cli -c ProvisionCurrentUser -ttid "myproject"

  5. Zum Kontext des neuen Tenants wechseln:

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

  6. Construction Kit importieren:

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

Siehe Tenant Lifecycle für ausführliche Hinweise zum Erstellen, Anhängen und Wiederherstellen von Tenants.

Kontexte verwalten​

Kontexte funktionieren wie kubectl-Kontexte – jeder bündelt seine eigenen Dienst-URIs, die Tenant-ID sowie das gespeicherte Access-/Refresh-Token. Über das Wechseln von Kontexten sprechen Sie verschiedene Umgebungen (dev / prod / customer-X) an, ohne alles neu konfigurieren zu müssen. Sie liegen in ~/.octo-cli/contexts.json.

BefehlBeschreibung
AddContextEinen benannten Kontext hinzufügen oder aktualisieren
UseContextDen aktiven Kontext wechseln
ListContextsAlle Kontexte auflisten oder Details eines Kontexts anzeigen
RemoveContextEinen Kontext entfernen

  1. Einen neuen Kontext hinzufügen (mit allen relevanten Dienst-URIs):

    octo-cli -c AddContext -n staging-1_meshtest `
      -isu https://connect.staging.octo-mesh.com/ `
      -asu https://assets.staging.octo-mesh.com/ `
      -bsu https://bots.staging.octo-mesh.com/ `
      -csu https://communication.staging.octo-mesh.com/ `
      -tid meshtest

    Der zuerst hinzugefügte Kontext wird automatisch aktiviert. Nachfolgende AddContext-Aufrufe aktualisieren, wenn der Name bereits existiert. Die vollständige Liste der Dienst-URI-Flags finden Sie auf der Referenzseite AddContext.

  2. Kontexte auflisten und Details einsehen:

    Tabellarische Liste aller Kontexte – der aktive ist mit * markiert:

    octo-cli -c ListContexts

    Detailansicht eines einzelnen Kontexts – zeigt alle Dienst-URIs und den Authentifizierungsstatus:

    octo-cli -c ListContexts -n staging-1_meshtest

    JSON-Ausgabe für Skripting (jq, ConvertFrom-Json usw.):

    octo-cli -c ListContexts -j

    Die Spalte Auth meldet einen der folgenden Werte: no token (run LogIn), authenticated (expires <timestamp>[, refresh available]) oder expired (expires <timestamp>). Access- und Refresh-Tokens werden niemals in die Ausgabe geschrieben, nur der Ablaufzeitstempel und ein hasRefreshToken-Flag (im JSON-Modus).

  3. Den aktiven Kontext wechseln – alle nachfolgenden Befehle sprechen den Tenant und die Dienste dieses Kontexts an:

    octo-cli -c UseContext -n staging-1_meshtest

  4. Einen Kontext entfernen, wenn er nicht mehr benötigt wird (wirkt sich nicht auf den entfernten Dienst aus):

    octo-cli -c RemoveContext -n old-context

    War der entfernte Kontext aktiv, wird automatisch ein anderer Kontext aktiv (oder keiner, falls es der letzte war).

Die Kontextauswahl ist die Voraussetzung für LogInClientCredentials (siehe Nicht-interaktive Authentifizierung weiter unten) – dieser Befehl akzeptiert kein -tid; er liest den Tenant aus dem aktiven Kontext.

Webanwendungs-Client hinzufügen​

  1. Client erstellen:

    octo-cli -c AddAuthorizationCodeClient `
      -id "my-webapp" `
      -n "My Web App" `
      -u "https://myapp.com/" `
      -ru "https://myapp.com/auth/callback"

  2. Erforderliche Scopes hinzufügen:

    octo-cli -c AddScopeToClient -id "my-webapp" -n "assetSystemAPI.full_access"
    octo-cli -c AddScopeToClient -id "my-webapp" -n "identityAPI.full_access"

Gruppenbasierten Zugriff einrichten​

  1. Eine Gruppe mit Rollen erstellen:

    octo-cli -c CreateGroup `
      -n "Operators" `
      -d "Operations team" `
      -rids "DashboardViewer,ReportingViewer"

  2. Benutzer zur Gruppe hinzufügen:

    octo-cli -c AddUserToGroup -id "<group-rtid>" -uid "<user-id>"

  3. Optional die automatische Zuweisung nach E-Mail-Domäne einrichten:

    octo-cli -c CreateEmailDomainGroupRule `
      -edp "company.com" `
      -tgid "<group-rtid>" `
      -d "Auto-assign company employees"

Einem Machine-to-Machine-Client eine Rolle geben​

Ermöglicht es einem client_credentials-Client, rollengeschützte Endpunkte aufzurufen – sein Access-Token trägt dann die aufgelösten role-Claims (direkt + über Gruppen vererbt), in derselben Form wie ein Benutzer-Token.

  1. Dem Client eine Rolle direkt zuweisen:

    octo-cli -c AddClientToRole -id "ci-deploy" -r "DataAnalyst"

  2. Oder – empfohlen – den Client zu einer rollentragenden Gruppe hinzufügen (über die Runtime-ID des Clients, aus GetClient):

    octo-cli -c AddClientToGroup -id "<group-rtid>" -cid "<client-rtid>"

  3. Die vollständige Menge der direkt zugewiesenen Rollen ersetzen (über die Rollen-ID):

    octo-cli -c UpdateClientRoles -id "ci-deploy" -rids "<role-id-1>,<role-id-2>"

Das nächste client_credentials-Token des Clients enthält die aufgelösten Rollen automatisch.

Tenant-übergreifenden Zugriff einrichten​

Im Child-Tenant: Fügen Sie einen OctoTenant-Provider hinzu, der auf den Parent zeigt, und erstellen Sie dann Benutzerzuordnungen.

  1. Zum Kontext des Child-Tenants wechseln:

    octo-cli -c Config -tid "child-tenant" -isu "https://id.example.com/"
    octo-cli -c LogIn -i

  2. OctoTenant-Identity-Provider hinzufügen:

    octo-cli -c AddOctoTenantIdentityProvider `
      -n "Parent Auth" `
      -ptid "octosystem" `
      -e true

  3. Benutzerzuordnungen erstellen:

    octo-cli -c CreateExternalTenantUserMapping `
      -stid "octosystem" `
      -suid "<user-id>" `
      -sun "alice" `
      -rids "Development,DashboardViewer"

Siehe Cross-Tenant Authentication für Details.

Nicht-interaktive Authentifizierung​

Richten Sie die client_credentials-Authentifizierung für jeden unbeaufsichtigten Aufrufer ein – eine CI-Pipeline, einen Cron-Job, einen systemd-Dienst, einen Container-Entrypoint, ein Remote-Administrationsskript usw. Führen Sie die Setup-Schritte einmal von einer Workstation aus; die Laufzeitschritte werden bei jeder Ausführung des Skripts oder Jobs ausgeführt.

Einmaliges Setup (Workstation)​

  1. Als Benutzer authentifizieren, der berechtigt ist, Clients im Ziel-Tenant zu erstellen:

    octo-cli -c UseContext -n prod
    octo-cli -c LogIn -i

  2. Einen client_credentials-Client in diesem Tenant erstellen:

    octo-cli -c AddClientCredentialsClient `
      -id "my-script-client" `
      -n "Headless script client" `
      -s "<generated-secret>"

  3. Die Client-ID + das Secret in einem Secrets-Manager speichern – Azure-DevOps-Variablengruppe, GitHub-Actions-Secret, Vault, AWS Secrets Manager, eine private, nur vom ausführenden Benutzer lesbare Datei usw.

Bei jeder Skript-/Job-Ausführung​

  1. Den Kontext festlegen, damit der Tenant korrekt ist:

    octo-cli -c UseContext -n prod

  2. Anmeldedaten aus dem Speicherort exportieren:

    $env:OCTO_CLI_CLIENT_ID    = "<from secret store>"
    $env:OCTO_CLI_CLIENT_SECRET = "<from secret store>"

  3. Anmelden – die Tokens werden automatisch erneuert, solange die Umgebungsvariablen im Gültigkeitsbereich bleiben, sodass ein langlaufendes Skript LogInClientCredentials zwischen den Befehlen nicht erneut aufrufen muss:

    octo-cli -c LogInClientCredentials

  4. Beliebige nachfolgende Befehle ausführen:

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

Wenn das Skript mehrere Tenants anspricht, erstellen Sie pro Tenant einen client_credentials-Client und wechseln Sie vor jeder Anmeldung den Kontext. Dieselben Umgebungsvariablennamen funktionieren über alle Kontexte hinweg; der aktive Kontext bestimmt, gegen welchen Tenant sich die Anmeldedaten authentifizieren.

Sicherung und Wiederherstellung​

Sicherung​

octo-cli -c Dump -tid "production" -f "./backup.tar.gz"

Wiederherstellung in einen neuen Tenant​

  1. Den Ziel-Tenant erstellen:

    octo-cli -c Create -tid "staging" -db "staging_db"

  2. Sich selbst Zugriff gewähren:

    octo-cli -c ProvisionCurrentUser -ttid "staging"

  3. Aus der Sicherung wiederherstellen:

    octo-cli -c Restore `
      -tid "staging" `
      -db "staging_db" `
      -f "./backup-20241213.tar.gz" `
      -w

  4. Tenant-Cache leeren:

    octo-cli -c ClearCache -tid "staging"

  5. Sich selbst erneut provisionieren (das Zurücksetzen des Caches kann die vorherige Zuweisung ungültig gemacht haben):

    octo-cli -c ProvisionCurrentUser -ttid "staging"

Siehe Tenant Lifecycle für ausführliche Hinweise zu Sicherung und Wiederherstellung.

Eine Pipeline bereitstellen und ausführen​

  1. Communication für den Tenant aktivieren:

    octo-cli -c EnableCommunication

  2. Prüfen, dass der Adapter verbunden ist:

    octo-cli -c GetAdapters

  3. Eine Pipeline-Definition bereitstellen – der zentrale Communication Operator übernimmt diese und rollt den Adapter automatisch über Helm aus:

    octo-cli -c DeployPipeline `
      -aid "<adapter-rtId>" `
      -pid "<pipeline-rtId>" `
      -f "./my-pipeline.yaml"

  4. Die Pipeline ausführen:

    octo-cli -c ExecutePipeline -id "<pipeline-rtId>"

  5. Ausführungsergebnis prüfen:

    octo-cli -c GetLatestPipelineExecution -id "<pipeline-rtId>"

  6. Debug-Punkte einsehen (falls Debugging aktiviert ist):

    octo-cli -c GetPipelineDebugPoints -id "<pipeline-rtId>" -eid "<execution-guid>"

Siehe DataFlows & Pipelines für Details zu Pipeline-Definitionen.

Local-Dev-Callbacks zu einem Blueprint-verwalteten Client hinzufügen​

Blueprint-verwaltete Clients (octo-data-refinery-studio, octo-cli, die Swagger-UIs) tragen die URIs, die das Blueprint ausgeliefert hat – typischerweise auf die bereitgestellte Umgebung zeigend. Um Local-Dev-URIs (http://localhost:4200/auth-callback, …) hinzuzufügen, ohne sie beim nächsten Blueprint-Apply zu verlieren, verwenden Sie den Overlay-Endpunkt. Die Einträge werden mit Source = "overlay:<name>" gekennzeichnet und überstehen jedes erneute Anwenden.

  1. Bei der lokalen Umgebung anmelden (setzt den aktiven Kontext):

    Invoke-OctoCliLoginLocal -tenantId "meshtest"

  2. Das kanonische Local-Dev-Overlay anwenden (das PowerShell-Cmdlet fächert die Aufrufe pro Client auf):

    Apply-IdentityOverlay

    Für nur einen Client rufen Sie octo-cli direkt auf:

    octo-cli -c ApplyClientOverlay `
      -id "octo-data-refinery-studio" `
      -n  "local-dev" `
      -r  "http://localhost:4200/auth-callback,http://localhost:4200/silent-renew" `
      -plr "http://localhost:4200/" `
      -co "http://localhost:4200"

  3. Verifizieren – der nächste Aufruf ist ein No-Op (jede URI trifft den Dedup-Zweig):

    Apply-IdentityOverlay -DryRun  # prints the invocations
    Apply-IdentityOverlay          # re-runs idempotently, all SkippedDuplicate

  4. Sauberer Export – wenn Sie den Tenant dumpen, um ihn mit einem anderen Entwickler zu teilen oder als Seed-Material zu committen, entfernen Sie zuerst die Overlay-Einträge, damit sie nicht durchsickern. Drei separate Befehle (der Dump ist ein reines mongodump-Archiv; die Filterung muss vor dem Dump erfolgen und nicht innerhalb):

    octo-cli -c CleanClientOverlays -y                                    # strip every overlay:* entry
    octo-cli -c DumpTenant -tid "meshtest" -f ./meshtest-clean.tar.gz      # dump the now-clean tenant
    Apply-IdentityOverlay                                                  # optional: restore local-dev overlays (idempotent)

    Um nur einen bestimmten Overlay-Namen zu entfernen (z. B. persönliche Overlays entfernen und dabei das gemeinsame local-dev-Set behalten), übergeben Sie -n <name>:

    octo-cli -c CleanClientOverlays -n gerald-laptop -y

Siehe Clients and API Scopes → URI Sources and Lifecycle für den konzeptionellen Hintergrund (Quellen-Taxonomie, Family vs. Overlay, Lifecycle über Blueprint-Re-Applies hinweg) und Apply-IdentityOverlay für den vollständigen Parametersatz des Cmdlets.