Infrastructure as Code

Alle administrativen Funktionen des Weldall-Servers lassen sich über die Benutzeroberfläche verwalten. Die wichtigsten Bausteine – Scopes, Ressourcen, Machine Clients, administrativ verwaltete Skills und Zuweisungen – können zusätzlich in YAML-Dateien beschrieben werden. So wird aus der Konfiguration Infrastructure as Code (IaC).

Warum IaC?

In einem versionierten Git-Repository bleibt jede Änderung nachvollziehbar. Pull Requests bieten Raum für Diskussionen und Freigaben, und Kommentare im YAML dokumentieren direkt, warum eine bestimmte Berechtigung existiert.

Atomare Änderungen

Weldall fasst die YAML-Dateien in einem Workspace zusammen und wendet den gewünschten Zustand atomar an: Entweder werden alle geplanten Änderungen durchgeführt oder keine.

Auch bei der Nutzung von IaC können Personen mit den entsprechenden Rechten weiterhin die Benutzeroberfläche verwenden, um Änderungen vorzunehmen oder neue Scopes, Ressourcen und andere Elemente anzulegen. Manuelle Änderungen an verwalteten Elementen erscheinen im nächsten Plan als Drift und werden beim Anwenden auf den in der YAML-Konfiguration beschriebenen Zustand zurückgesetzt. Wird ein verwaltetes Element manuell gelöscht, plant Weldall seine Wiederherstellung. Das betrifft nur Elemente, die über IaC angelegt oder importiert wurden. Alle anderen Elemente bleiben unberührt.

Workspace anlegen

1. Machine Client vorbereiten

Für IaC-Befehle wird die Weldall CLI verwendet. Sie authentifiziert sich mit einem zuvor in Weldall angelegten Machine Client, dem der Scope weldall:iac zugewiesen wurde. Die CLI liest Client-ID und Schlüssel aus Umgebungsvariablen:

export WELDALL_M2M_CLIENT_ID=platform-ci
export WELDALL_M2M_KID=ci-2026
export WELDALL_M2M_PRIVATE_JWK='<privater P-256-JWK als JSON>'
export WELDALL_M2M_PUBLIC_JWK='<öffentlicher P-256-JWK als JSON>'

Diese Variablen bestimmen auch, was die Hilfe zeigt: Die IaC-Befehle erscheinen nur dann in weldall --help, wenn sie gesetzt sind – eine reine Browser-Anmeldung macht sie nicht nutzbar.

Privaten Schlüssel schützen

Der private Schlüssel gehört weder in die YAML-Konfiguration noch ins Git-Repository.

258. Workspace initialisieren

     mkdir platform-access && cd platform-access
     weldall init --name platform-access --issuer https://weldall.example.com

     Der Befehl erzeugt weldall.yml, weldall.lock.yml und das Verzeichnis weldall/. Manifest und Lockdatei werden gemeinsam versioniert.

Workspace in Fragmente aufteilen

Ein Workspace kann zum Beispiel so aufgebaut sein:

• Ordnerplatform-access/ - weldall.yml Root-Manifest - weldall.lock.yml Versionierter Serverzustand und Objektzuordnungen - weldall/ - access.yml Scopes und Zuweisungen - runtime.yml Ressourcen und Machine Clients - imports/ Optional, wird von weldall import verwendet - emailAssignment-alice.yml Erzeugtes Importfragment

  • …

Das von init erzeugte Root-Manifest enthält die Metadaten des Workspaces und bindet alle YAML-Dateien unter weldall/ ein:

weldall.yml

apiVersion: weldall.dev/v1
workspace:
  name: platform-access
  issuer: https://weldall.example.com
include:
  - weldall/**/*.yml

Die eingebundenen Dateien sind Fragmente. Sie wiederholen weder apiVersion noch workspace, sondern enthalten nur eine oder mehrere Objektgruppen wie scopes, resources oder emailAssignments. Die CLI führt alle Fragmente zu einer vollständigen Konfiguration zusammen. Wie die Dateien aufgeteilt werden, kann das Team selbst entscheiden – zum Beispiel nach Anwendung, Zuständigkeit oder Umgebung.

Zugriffe deklarieren

weldall/access.yml

scopes:
  expenses_read:
    key: expenses:read
    description: Ausgaben lesen

emailAssignments:
  alice:
    email: alice@example.com
    scopes:
      - expenses:read

groupAssignments:
  finance:
    provider: company-directory
    groupId: finance-team
    scopes:
      - expenses:read

scope.expenses_read, emailAssignment.alice und groupAssignment.finance sind Namen, die IaC nur innerhalb dieses Workspaces verwendet. Der Teil hinter dem Punkt stammt jeweils aus dem Map-Key im YAML. Diese IaC-internen Namen ändern nichts am eigentlichen Objekt in Weldall: Dort wird ein Scope zum Beispiel weiterhin durch expenses:read und eine Person durch alice@example.com identifiziert.

Der Group Provider muss bereits existieren oder im selben Workspace deklariert werden. Deaktivierte Entwürfe dürfen referenziert werden, gewähren aber keine Rechte. Ob die angegebene Gruppen-ID tatsächlich existiert, prüft die CLI nicht.

Ressourcen und Machine Clients verwenden dasselbe Format:

weldall/runtime.yml

resources:
  expenses:
    key: expenses
    name: Expenses API
    resourceIdentifier: https://expenses.example.com/api
    authorizationServer: https://expenses.example.com
    downstreamClientId: expenses-api
    enabled: true
    skillDiscoveryEnabled: false
    requestPrefixes:
      - https://expenses.example.com/api
    scopes:
      - expenses:read

machines:
  reporter:
    clientId: expense-reporter
    name: Expense reporter
    enabled: true
    publicKeys:
      ci-2026:
        kty: EC
        crv: P-256
        x: IOqiZZjB6aPt6WuPSZw_sJxwdEueJ3AFo-AkI-c_sx0
        y: 8oDde4-gGqCC4jGY_vwNBbaAw8l4Xti8cv6NRtoinjk
    resources:
      - expenses
    scopes:
      - expenses:read

Ins Manifest gehören nur öffentliche Machine-Schlüssel.

Managed Connectors können ebenfalls in YAML beschrieben werden. Das Manifest enthält nur öffentliche Policy; OAuth-Client-Secrets werden in der Admin-Oberfläche eingetragen und von der CLI nie akzeptiert. envelopeProvider ist nach der Erstellung unveränderlich. Google-Connectors listen exakte Google-OAuth-Scopes. Atlassian-Cloud-Connectors müssen ressourcenbezogene Grants, mindestens einen erlaubten Jira- oder Confluence-Product-Scope und mindestens eine erlaubte Site-cloudId verwenden.

connectors:
  google:
    key: google
    name: Google Workspace
    type: google
    enabled: false
    envelopeProvider: LOCAL_ENV
    requiredScopes: []
    provider:
      clientId: google-client-id.apps.googleusercontent.com
      allowedScopes:
        - https://www.googleapis.com/auth/calendar.readonly
      defaultScopes:
        - https://www.googleapis.com/auth/calendar.readonly
  company_jira:
    key: company-jira
    name: Company Jira
    type: atlassian
    enabled: false
    envelopeProvider: OPENBAO
    requiredScopes:
      - jira:use
    provider:
      clientId: atlassian-client-id
      grantType: resource
      products:
        - jira
      allowedCloudIds:
        - 8594f221-9797-5f78-1fa4-485e198d7cd0
      allowedScopes:
        - read:jira-work
        - read:jira-user
      defaultScopes:
        - read:jira-work

Connector-Manifeste lassen sich wie jedes andere Objekt planen und anwenden. Manuelle Änderungen an der verwalteten Connector-Policy erscheinen als Drift, während Provider-Secrets außerhalb des Manifests bleiben.

Das Logo auf der CLI-Willkommensseite lässt sich als Singleton-Einstellung verwalten. Eine leere URL entfernt das Unternehmenslogo:

cli:
  logoUrl: https://example.com/brand-logo.svg

Administrativ verwaltete Skills enthalten das Markdown direkt und geben alle konfigurierbaren Felder explizit an:

skills:
  review_expenses:
    slug: expenses.review
    title: Ausgaben prüfen
    content: |
      # Ausgaben prüfen

      Prüfe jede Ausgabe anhand der Richtlinie.
    requiredScopes:
      - expenses:read
    visibility: HIDDEN_IF_UNALLOWED
    meta:
      tags:
        - finanzen
        - prüfung
      owner: Finanzbetrieb
      appearance:
        icon: file-text
        gradientFrom: "#555BD6"
        gradientTo: "#7773E5"
        darkGradientFrom: "#2A2660"
        darkGradientTo: "#403A86"
    lastUpdatedAt: "2026-08-20"

meta.appearance.icon akzeptiert kanonische Namen in Kebab-Case aus dem Lucide-Icon-Katalog. Gradient-Overrides werden nur verwendet, wenn beide Farben eines hellen oder dunklen Paars sechsstellige Hex-Farben sind; andernfalls verwendet Weldall den deterministischen Slug-basierten Fallback.

Der Slug ist die Identität des Skills; eine Änderung ersetzt den Skill. Ein über IaC verwalteter Skill bleibt in der Admin-Oberfläche bearbeitbar. Solche Änderungen gelten als Drift und werden beim nächsten Apply auf den YAML-Zustand zurückgesetzt. Administrativ verwaltete Skills dürfen einen von einer Ressource veröffentlichten Skill mit derselben kanonischen ID überschreiben. Entdeckte Skills und Kataloge können weder importiert noch verwaltet werden.

Öffentliche Konfiguration, Secrets nur in der UI

IaC unterstützt außerdem diese öffentlichen Deklarationen; Pflichtfelder und Defaults stehen im Manifest-Schema:

Sektion	Identität	Credential hinterlegen
sharedConnections	Stabiler key; nur Scope-basierte Service-Accounts	Admin → Connections
groupProviders	Stabiler key; Adapter management-api-v1	Admin → Group Providers
loginProviders	Stabile Provider-id (UUID); erhält die Callback-URL	Admin → Login Providers

Mit enabled: false anlegen und anwenden, Credential in der UI hinterlegen, danach ausdrücklich aktivieren und erneut anwenden. Secrets gehören nie in YAML/State; Provisionierung/Rotation aktiviert nichts, Deaktivieren erhält das Credential. Connector und Verbindung müssen aktiv sein. Deaktivierte Group-/Login-Provider gewähren keine Gruppenrechte/starten keine Logins.

Geteilte Verbindungen benötigen einen vorhandenen Connector, einen bestehenden Benutzer als Credential-Verantwortlichen und eine nichtleere Liste von Nicht-System-Nutzungsscopes (Scopes dürfen im selben Workspace deklariert werden). Alle Connector-/Nutzungsscopes gelten auch für Administratoren und Credential-Manager. Persönliches OAuth kann nicht importiert werden.

Pläne prüfen Credential-Präsenz und bekannte Voraussetzungen, nicht die Upstream-Gültigkeit; Planung/Import entschlüsseln keine Secrets und kontaktieren OpenBao nicht. Aktivierung/Credential-Operationen behalten Provider-Prüfungen und Fail-closed-Verhalten. Der Login-Issuer ist unveränderlich; credential-gebundene Client-IDs oder Directory-URLs benötigen ausdrückliche Reprovisionierung in der UI statt stiller Wiederverwendung.

Identity-Administration und Bestätigung

weldall:iac erlaubt öffentliche Login-/Group-Policy-Änderungen, kein Lesen/Provisionieren von Secrets. Login-Aktivierung und Authority-Änderungen aktiver Provider benötigen die Bestätigung dieses konkreten Plans:

weldall plan --json
# Aktionen mit requiresAuthorityConfirmation prüfen und digest dieses Plans übernehmen:
weldall up --yes --acknowledge-authority <digest>

--yes allein genügt nicht; geänderte Pläne benötigen eine neue Freigabe, auch für API-Aufrufe. IaC kann weder den letzten aktiven Login-Provider deaktivieren/löschen noch die Installation zurücksetzen; der bestätigte UI-Recovery-Weg bleibt separat.

Import und Wiederherstellung

weldall import connector company-jira --as connector.company_jira
weldall import sharedConnection atlassian-bot --as sharedConnection.bot
weldall import groupProvider company-directory --as groupProvider.directory
weldall import loginProvider <bestehende-provider-uuid> --as loginProvider.sso

Import schreibt öffentliche Konfiguration/Bindungen und erhält Identität, Callback, Aktivierung, Credential-Verantwortlichen und Ciphertext; der nächste Plan ist ein No-op. State-Move/Unmanage erhalten ebenfalls Credentials. Öffentliche UI-Änderungen sind Drift, Secret-Rotation nicht; sie kann aber einen gespeicherten Plan ungültig machen.

Gelöschte Objekte deaktiviert wiederherstellen, Credentials erneut hinterlegen, dann ausdrücklich aktivieren: IaC kann gelöschte Secrets nicht zurückholen. Unverwaltete/fremde Abhängigkeiten blockieren Connector-/Group-Provider-Löschung. Lokales Löschen widerruft keine Upstream-Tokens.

Rollout und Kompatibilität

Datenbank sichern, Migrationen bis 0021_iac_secret_primitives anwenden und den passenden Server mit neu generiertem Prisma-Client ausrollen, danach Clients aktualisieren. Credentials/Verschlüsselungsformate bleiben erhalten. Alte Server-Binaries gegen das migrierte Schema sind nicht unterstützt; Rollback benötigt ein kompatibles Backup.

Neue Sektionen/Importe benötigen das Discovery-Feature iac-ui-secrets-v1; bisherige Workflows unterstützen ältere Server weiter. Fehlende Sektionen unterscheiden sich von leeren Maps: zum Löschen des letzten verwalteten Objekts z. B. groupProviders: {} beibehalten. Unvollständige inkompatible Snapshots scheitern vor Änderungen, statt unbekannte Objekte zu löschen.

Nur wer vor dem Upgrade eine Anmeldung begonnen, aber noch nicht abgeschlossen hat, muss erneut auf „Anmelden“ klicken; bestehende Sitzungen bleiben gültig. Callbacks sind an Erstellungszeitpunkt und Version gebunden, damit das Neuanlegen einer UUID keinen alten Vorgang reaktiviert.

Die wichtigsten CLI-Befehle

Befehl	Zweck
weldall init --name … --issuer …	Legt einen neuen Workspace mit Root-Manifest, Lockdatei und Fragmentverzeichnis an.
weldall validate	Liest und prüft das Root-Manifest sowie alle Fragmente lokal, ohne den Server zu kontaktieren.
weldall plan	Vergleicht die YAML-Konfiguration mit dem aktuellen Serverzustand, ohne etwas zu ändern.
weldall up	Zeigt einen aktuellen Plan, fragt nach Bestätigung und wendet ihn anschließend an.
weldall up --yes	Wendet den Plan ohne Rückfrage an, zum Beispiel in der CI.
weldall import <kind> <identity> --as <iac-name>	Übernimmt ein vorhandenes Objekt und gibt ihm einen Namen für diesen IaC-Workspace.
weldall unmanage <iac-name> --yes	Beendet die Verwaltung eines Objekts, ohne das Objekt selbst zu löschen.
weldall state mv <old> <new>	Ändert den Namen, unter dem IaC das Objekt verwaltet; das Weldall-Objekt bleibt unverändert.
weldall state pull	Stellt die Zuordnungen in der Lockdatei aus dem Serverzustand wieder her.

weldall plan --json gibt den Plan als maschinenlesbares JSON aus. Mit weldall plan --detailed-exit-code signalisiert Exit-Code 2, dass Änderungen anstehen.

Vorhandenes Objekt importieren

Ein passendes manuelles Objekt wird nie automatisch übernommen. Der Import ist immer explizit:

weldall import emailAssignment alice@example.com --as emailAssignment.alice
weldall import scope expenses:read --as scope.expenses_read
weldall import skill expenses.review --as skill.review_expenses

Der Import erhält das Objekt, schreibt seine aktuelle Konfiguration nach weldall/imports/ und aktualisiert die Lockdatei.

Wird eine verwaltete Deklaration entfernt, löscht das nächste Apply das Objekt. Soll das Objekt erhalten bleiben, wird zuerst die Deklaration entfernt und anschließend die Verwaltung beendet:

weldall unmanage scope.expenses_read --yes

Der nur innerhalb von IaC verwendete Name lässt sich ändern, ohne das eigentliche Weldall-Objekt umzubenennen oder neu anzulegen. Zum Beispiel benennt dieser Befehl scope.expenses_read innerhalb von IaC in scope.expenses_view um; der Scope expenses:read in Weldall bleibt derselbe:

weldall state mv scope.expenses_read scope.expenses_view

Die Lockdatei kann außerdem aus dem Serverzustand wiederhergestellt werden:

weldall state pull

Alle Felder beschreibt das JSON-Schema des Manifests.