Zum Hauptinhalt springen

Apply-IdentityOverlay

Apply-IdentityOverlay (ausgeliefert in octo-tools/modules/Apply-IdentityOverlay.psm1) wendet deklarativ eine YAML-Overlay-Datei auf die blueprint-verwalteten Identity-Clients des Tenants im aktiven octo-cli-Kontext an. Es verteilt octo-cli -c ApplyClientOverlay über jeden in der Datei aufgeführten Client, dedupliziert serverseitig gegen bestehende URIs und markiert neue Einträge mit Source = "overlay:<name>", sodass sie ein erneutes Anwenden des Blueprints überstehen.

Für den konzeptionellen Hintergrund – wann Overlays zu verwenden sind, die Taxonomie des Source-Tags, Family vs. Overlay sowie wie der Lebenszyklus mit dem Anwenden des Blueprints zusammenspielt – siehe Clients and API Scopes → URI Sources and Lifecycle.

Voraussetzungen​

  • PowerShell 7+.
  • Modul powershell-yaml: Install-Module -Name powershell-yaml -Scope CurrentUser.
  • octo-cli im PATH.
  • Ein aktiver octo-cli-Kontext mit gültigen Auth-Tokens (führen Sie zuvor Invoke-OctoCliLoginLocal oder ein Äquivalent aus).

Parameter​

ParameterErforderlichStandardZweck
-OverlayFilenein$Global:ROOTPATH/octo-tools/overlays/identity-local-dev.yamlPfad zum Overlay-YAML. Übergeben Sie einen absoluten Pfad oder eine andere Datei, um ein Overlay anzuwenden, das nicht der Standard ist.
-OverlayNameneinaus dem Feld overlayName der DateiÜberschreibt den Overlay-Namen (wird zum Suffix des overlay:<name>-Source-Tags). Nützlich, wenn ein einmaliges Overlay aus der gemeinsam genutzten Datei unter einem anderen Marker angewendet werden soll.
-DryRunneinausParst + validiert die Overlay-Datei, gibt die octo-cli-Aufrufe aus, die ausgeführt würden, ruft aber nichts auf. Plausibilitätsprüfung vor dem Anwenden.
-OctoClineinocto-cliPfad / Name der ausführbaren octo-cli-Datei. Standardmäßig aus dem PATH aufgelöst.

Beispiele​

Das Standard-local-dev-Overlay anwenden​

Apply-IdentityOverlay

Liest octo-tools/overlays/identity-local-dev.yaml (relativ zu $Global:ROOTPATH) und wendet die local-dev-URI-Menge auf jeden Client in der Datei an. Führen Sie dies einmal nach einer frischen Tenant-Wiederherstellung aus, damit OIDC-Roundtrips gegen die lokal laufenden Dienste gelingen.

Dry-Run​

Apply-IdentityOverlay -DryRun

Gibt die exakten octo-cli-Aufrufe aus, die das Cmdlet ausführen würde, einen pro Client, ohne etwas aufzurufen. Führen Sie dies nach dem Bearbeiten der Overlay-Datei aus, um zu überprüfen, dass die Struktur korrekt geparst wird und die URI-Listen korrekt als CSV vorliegen.

Persönliches Overlay unter eigenem Namen markiert​

Apply-IdentityOverlay -OverlayFile ~/dev/gerald-laptop.yaml -OverlayName gerald-laptop

Wendet eine persönliche Overlay-Datei von außerhalb des Repositorys an, markiert unter ihrem eigenen Overlay-Namen. Der --clean-Filter in DumpTenant entfernt diese Einträge anhand des Overlay-Namens (overlay:gerald-laptop), ohne die gemeinsam genutzten local-dev-Einträge (overlay:local-dev) zu berühren.

Einen vom Standard abweichenden Overlay-Namen für die gemeinsam genutzte Datei erzwingen​

Apply-IdentityOverlay -OverlayName local-dev-experimental

Wendet die kanonische local-dev-Datei an, markiert aber jeden Eintrag stattdessen als overlay:local-dev-experimental. Nützlich, wenn Sie mit Overlay-Änderungen experimentieren, die Sie nicht mit dem produktiven local-dev-Zustand vermischen möchten.

Verhalten und Idempotenz​

  • Ein fehlgeschlagener Client bricht den Batch nicht ab. Wenn octo-cli für einen Client einen Exit-Code ungleich null zurückgibt, protokolliert das Cmdlet eine Warnung und fährt mit den verbleibenden Clients fort. Das abschließende $LASTEXITCODE wird auf 1 gesetzt, wenn ein Client fehlgeschlagen ist.
  • Erneute Ausführungen sind No-Op. Der Server dedupliziert eingehende URIs gegen den bestehenden Listeninhalt (jeder Quelle) und überspringt, wenn nichts Neues hinzugefügt wird – kein DB-Schreibvorgang, keine Cache-Invalidierung. Sicher, in jedem Start-Octo-Aufruf enthalten zu sein.
  • URIs, die nur aus Leerzeichen bestehen, werden herausgefiltert. Sowohl die Prüfung der URI-Anzahl pro Client im Cmdlet als auch die meaningfulCount-Prüfung des Servers trimmen Einträge; eine redirectUris:-Liste aus [" ", ""] wird als leer behandelt, und das Cmdlet überspringt den Client (andernfalls würde es serverseitig auf einen 400 laufen).
  • Serverseitige Validierung: Der Overlay-Name muss ^[A-Za-z0-9._-]+$ entsprechen; das Cmdlet prüft dies clientseitig vor dem ersten octo-cli-Aufruf.

Ausgabe​

Pro Client, eines von:

[octo-data-refinery-studio] applying overlay...
[overlay 'local-dev' on 'octo-data-refinery-studio'] applied: RedirectUris=2 added / 0 skipped, PostLogoutRedirectUris=1 added / 0 skipped, AllowedCorsOrigins=1 added / 0 skipped

Bei einer erneuten Ausführung gibt derselbe Client 0 added / N skipped-Zahlen aus und signalisiert damit den No-Op-Pfad.

Start-Octo-Integration​

Apply-IdentityOverlay läuft heute eigenständig. Der automatische Aufruf aus Start-Octo nach der Identity-Prüfung /healthz/ready (mit einer -SkipOverlay-Opt-out-Option an Start-Octo) ist eine Folgeänderung. Führen Sie das Cmdlet bis dahin manuell aus, nachdem Start-Octo anzeigt, dass Identity läuft.

Siehe auch​