Secret Management

Preview-Funktion

Secret Management ist derzeit eine Preview-Funktion. Es handelt sich um eine frühe Version dieser Funktionalität, die sich in zukünftigen Updates noch ändern kann, während wir die Nutzung weiter verbessern.

Codesphere bietet ein Secret-Management-System, das mit OpenBao integriert ist, einem Open-Source-Sicherheitstresor. Dadurch wird sichergestellt, dass sensible Daten wie API-Schlüssel, Datenbank-Zugangsdaten und Zertifikate mit branchenüblicher Verschlüsselung gespeichert und nur bei Bedarf in die Services eingespeist werden.

Überblick

Im Gegensatz zu Standard-Umgebungsvariablen werden Secrets in einem Vault gespeichert, der mit einer Codesphere-Instanz ausgeliefert wird. Das bringt mehrere Vorteile mit sich:

• Verschlüsselung im Ruhezustand: Alle Werte werden vor der Speicherung verschlüsselt.
• Granularer Zugriff: Nur Services, die ein Secret explizit referenzieren, können auf dessen Wert zugreifen.
• Automatische Bereinigung: Secrets sind an den Lebenszyklus des Workspace gebunden.

info

Derzeit haben nur Admins einer Codesphere-Installation direkten Zugriff auf den Vault.

Secrets referenzieren

Secrets werden im Landscape Config Editor verwaltet. Um ein Secret zu definieren, muss eine bestimmte Templating-Syntax verwendet werden, unabhängig davon, ob die UI oder die YAML-Konfiguration genutzt wird. Der Zugriff auf Secrets wird derzeit nur direkt in den Landscape-Services unterstützt, nicht in den gemeinsamen Prepare- oder Test-Schritten.

Template-Syntax: ${{ vault.secretKeyOfBao }}

UI-Konfiguration

So wird ein Secret über den visuellen Editor zu einem Service hinzugefügt:

1. Öffne den Landscape Config Editor im Workspace.
2. Wähle den zu konfigurierenden Service aus und öffne das Fly-in-Sheet Edit Service.
3. Navigiere zum Tab Values.
4. Füge einen neuen Eintrag mit der Templating-Syntax hinzu:
   • Key: Der Name der Umgebungsvariable, die der Service verwenden wird (z. B. SECRET_KEY).
   • Value: Das Template, das auf den Vault-Key verweist (${{ vault.secretFoo }}).

Konfiguration von Umgebungsvariablen mithilfe von Vault-Templates im Tab „Values“ eines Service.

YAML-Konfiguration

Für die direkte Konfiguration werden Secrets im Abschnitt env des ci.yml-Profils definiert. Codesphere parst diese Templates während des Sync-Prozesses und speist die entsprechenden OpenBao-Einträge in die Service-Umgebung ein.

schemaVersion: v0.2
prepare:
  steps: []
test:
  steps: []
run:
  secret-demo:
    steps:
      - command: echo $SECRET_KEY
    plan: 8
    replicas: 1
    network:
      ports:
        - port: 3000
          isPublic: false
      paths: []
    env:
      SECRET_KEY: ${{ vault.secretFoo }}
      PLAIN_ENV: foo

Erweiterte Umgebungs-Templates

Neben Vault-Secrets unterstützt Codesphere dynamische Templates, um auf System-IDs oder bestehende Workspace-Umgebungsvariablen zu verweisen. Diese sind besonders nützlich, um die Konfiguration portabel zu machen oder Variablen umzumappen.

Template	Beschreibung
${{ workspace.id }}	Löst sich zur ID des Workspace auf, der die Landscape enthält.
${{ workspace.devDomain }}	Löst sich zur Dev-Domain des Workspace auf, der die Landscape enthält.
${{ team.id }}	Löst sich zur ID des Teams auf, dem der Workspace gehört.
${{ workspace.env['KEY'] }}	Löst sich zu einer globalen Workspace-Umgebungsvariable auf.

Anwendungsfall: Variable Remapping

Das Template ${{ workspace.env[...] }} ermöglicht es, globale Variablen auf spezifische Service-Anforderungen abzubilden.

Erwartet ein Backend-Service beispielsweise eine Umgebungsvariable namens PG_USER, die Datenbank-Zugangsdaten sind jedoch global als BACKEND_PG_USER gespeichert, um Namenskonflikte mit anderen Datenbanken zu vermeiden, können diese wie folgt zugeordnet werden:

env:
  PG_USER: ${{ workspace.env['BACKEND_PG_USER'] }}

Synchronisation und Persistenz

Nach dem Definieren der Secret-Referenzen muss das Landscape Profile im Execution Manager synchronisiert werden.

Der Sync-Prozess

Enthält die ausgewählte ci.yml während einer Landscape-Synchronisation neue Secret-Referenzen, liegt es in der Verantwortung des Nutzers, die tatsächlichen Secret-Werte bereitzustellen. Der Ablauf umfasst folgende Schritte:

1. Nutzer-Aufforderung: Ein Modal erscheint, das zur Eingabe der in der Konfiguration definierten Secret-Einträge auffordert.
2. Eingabe: Der reale Wert des Secrets muss mindestens einmal eingegeben werden, um den Eintrag im Vault zu initialisieren.
3. Persistenz: Nach dem Absenden werden diese Werte in der OpenBao-Instanz gespeichert.
4. Injection: Die Synchronisation wird fortgesetzt, und die Landscape greift auf die Vault-Keys zu, um sie in die jeweiligen Services einzuspeisen.

Das Secret-Eingabe-Modal, das während des Landscape-Sync-Prozesses ausgelöst wird.

warnung

Landscape-Synchronisationen schlagen fehl, wenn ein im CI-Profil definierter Service nicht auf das referenzierte Secret zugreifen kann. Stelle sicher, dass alle Secrets beim ersten Deployment einer Landscape korrekt eingerichtet sind.

Secrets aktualisieren

Eine dedizierte Benutzeroberfläche (UI) für den Secrets-Vault ist derzeit nicht verfügbar, Secrets können jedoch während der Landscape-Synchronisation verwaltet werden. Beim Synchronisieren einer Landscape kann gewählt werden, ob mit bestehenden Secrets deployt werden soll oder ob diese vor dem Fortfahren aktualisiert werden sollen. Der Ablauf umfasst folgende Schritte:

1. Nutzer-Aufforderung: Ein Modal erscheint, das zur Auswahl auffordert, wie die Landscape deployt werden soll: mit bestehenden Secrets oder mit Änderung der Secrets vor dem Deployment.
2. Eingabe: Wähle change secrets before deploying. Gib den neuen, tatsächlichen Secret-Wert ein. Dieser überschreibt den Wert im Vault, sobald die Bestätigungsschaltfläche geklickt wird. Hinweis: Änderungen am Secret können während des Bearbeitungsvorgangs rückgängig gemacht werden, ebenso lässt sich der reale Wert einsehen.
3. Persistenz: Nach dem Absenden werden diese Werte in der OpenBao-Instanz gespeichert.
4. Injection: Die Synchronisation wird fortgesetzt, und die Landscape greift auf die Vault-Keys zu, um sie in die jeweiligen Services einzuspeisen.

Das Secret-Eingabe-Modal, das während des Landscape-Sync-Prozesses ausgelöst wird.

Shared Vaults

Standardmäßig erhält jeder Workspace eine eigene, isolierte Vault-Partition, und die darin referenzierten Secret-Werte müssen während des ersten Landscape-Sync initialisiert werden (siehe Der Sync-Prozess). Ein Shared Vault macht diesen manuellen Schritt für Secrets überflüssig, die team-übergreifend genutzt werden.

Ein Shared Vault ist eine dedizierte Partition innerhalb des Cluster-Vaults, die auf Team-Ebene statt auf Workspace-Ebene existiert. Einmal erstellt, kann er von beliebig vielen Workspaces innerhalb desselben Teams genutzt werden. Die wichtigsten Vorteile sind:

• Zugriff ohne Einrichtung: Workspaces, denen ein Shared Vault zugewiesen ist, können dessen Secrets sofort referenzieren — ohne dass jemand bei der Workspace-Erstellung oder dem Landscape-Sync Werte eingeben muss.
• Single Source of Truth: Gemeinsame Zugangsdaten (zum Beispiel gemeinsame Datenbankverbindungsdetails) werden einmal gespeichert und überall wiederverwendet, statt in jedem Workspace dupliziert zu werden.
• Zentrale Rotation: Eine Aktualisierung eines Werts im Shared Vault wird beim nächsten Deployment an jeden Workspace weitergegeben, der ihn nutzt.

info

Shared Vaults sind auf ein Team beschränkt. Das Auflisten erfordert Lese-Zugriff auf das Team, während das Erstellen, Löschen oder Ändern Schreib-Zugriff auf das Team erfordert.

Wie ein Workspace Shared Secrets auflöst

Die Templating-Syntax zum Referenzieren eines Secrets ändert sich nicht — es wird weiterhin ${{ vault.secretKey }} in der Service-Konfiguration verwendet (siehe Secrets referenzieren). Was sich ändert, ist, gegen welchen Vault die Referenz aufgelöst wird:

• Ist einem Workspace ein Shared Vault zugewiesen, werden alle ${{ vault.* }}-Referenzen in dessen Landscape gegen diese gemeinsame Partition aufgelöst.
• Ist kein Shared Vault zugewiesen, werden Referenzen gegen die eigene Partition des Workspace aufgelöst (Standardverhalten).

Das bedeutet, dass ein Workspace, der auf einen Shared Vault verweist, eine Landscape deployen kann, die gemeinsame Secrets nutzt, ohne dass zuvor eine Initialisierung pro Workspace erforderlich ist.

warnung

Ein Workspace liest Secrets entweder aus seinem eigenen Vault oder aus dem zugewiesenen Shared Vault — beide werden nicht zusammengeführt. Wird ein Workspace auf einen Shared Vault umgestellt, muss sichergestellt werden, dass jeder von dessen Landscape referenzierte ${{ vault.* }}-Key in diesem Shared Vault existiert, da sonst der nächste Sync fehlschlägt.

Einem Workspace einen Shared Vault zuweisen

Shared Vaults werden pro Workspace über das Dropdown Secrets Vault ausgewählt. Das Dropdown listet jeden im Team verfügbaren Shared Vault sowie die Standardoption Workspace (default) auf, die den Workspace auf seiner eigenen isolierten Partition belässt.

Bei der Workspace-Erstellung

Beim Erstellen eines Workspace die Advanced Options im zweiten Schritt des Dialogs aufklappen und einen Vault aus dem Dropdown Secrets Vault auswählen. Bleibt die Option auf Workspace (default), bleibt der Workspace isoliert.

Auswahl eines Shared Vault unter Advanced Options im Dialog „Create Workspace“.

Bei einem bestehenden Workspace

Der Vault eines bestehenden Workspace kann im Tab General der Workspace-Einstellungen geändert werden. Die Änderung wird beim nächsten Landscape-Sync wirksam.

Ändern des Secrets Vault eines bestehenden Workspace im Tab „General“ der Einstellungen.

info

Die Auswahl Secrets Vault wird nur angezeigt, wenn Secret Management für die jeweilige Installation aktiviert ist.

Secrets über die Public API verwalten

Die Codesphere Public API stellt einen vollständigen Satz an Vault-Endpunkten bereit, mit denen Workspace-Secrets programmatisch verwaltet und automatisch generiert werden können — beispielsweise in einer CI/CD-Pipeline oder einer internen Developer-Plattform. Authentifizierung und allgemeine API-Nutzung werden in der Public-API-Dokumentation beschrieben.

Alle Vault-Endpunkte folgen diesem Basispfad:

/vault/teams/{teamId}/workspaces/{workspaceId}

Secrets speichern

POST /vault/teams/{teamId}/workspaces/{workspaceId}

Schreibt ein oder mehrere Secret-Key-Value-Paare in den Vault für einen bestimmten Workspace. Gibt eine Zuordnung jedes Keys zu seiner Revisionskennung zurück, die eine Versionsnummer und einen Zeitstempel kombiniert.

Request-Body:

{
  "DATABASE_PASSWORD": "supersecretpassword",
  "API_KEY": "123456789"
}

Response:

{
  "DATABASE_PASSWORD": "1__2026-03-05T10:14:48.490756937Z",
  "API_KEY": "1__2026-03-05T10:14:48.490756937Z"
}

Secret-Keys auflisten

GET /vault/teams/{teamId}/workspaces/{workspaceId}/keys

Gibt die Liste der für einen Workspace gespeicherten Secret-Keys zurück. Werte werden über diesen Endpunkt niemals offengelegt.

Response:

["DATABASE_PASSWORD", "API_KEY"]

Secrets löschen

DELETE /vault/teams/{teamId}/workspaces/{workspaceId}

Entfernt die angegebenen Secrets dauerhaft aus dem Vault.

Request-Body:

["DATABASE_PASSWORD", "API_KEY"]

Secrets automatisch generieren

POST /vault/teams/{teamId}/workspaces/{workspaceId}/generate

Generiert kryptografisch zufällige Secret-Werte und speichert sie direkt im Vault — ein Klartextwert muss die Pipeline zu keinem Zeitpunkt verlassen. Die Form jedes generierten Werts wird über eine Passwortrichtlinie gesteuert.

Felder der Passwortrichtlinie:

Feld	Typ	Beschreibung
length	number	Gesamtlänge des generierten Secrets.
rules	array	Eine oder mehrere während der Generierung angewendete Zeichensatzregeln.
rules[].charset	string	Die Menge der zu verwendenden Zeichen.
rules[].minChars	number	Mindestanzahl an Zeichen aus diesem Zeichensatz.

Request-Body:

{
  "DATABASE_PASSWORD": {
    "length": 16,
    "rules": [
      {
        "charset": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
        "minChars": 16
      }
    ]
  },
  "API_KEY": {
    "length": 32,
    "rules": [
      {
        "charset": "0123456789abcdef",
        "minChars": 32
      }
    ]
  }
}

Response — die generierten Werte und ihre Revisionskennungen:

{
  "DATABASE_PASSWORD": {
    "value": "aB3kR7mX...",
    "revision": "1__2026-03-05T10:14:48.490756937Z"
  },
  "API_KEY": {
    "value": "1a2b3c4d...",
    "revision": "1__2026-03-05T10:14:48.490756937Z"
  }
}

Anwendungsfall: Zero-Knowledge-Bootstrapping

Der Generate-Endpunkt eignet sich ideal für die initiale Workspace-Bereitstellung — starke, eindeutige Secrets können für jede neue Umgebung erstellt werden, ohne die Rohwerte selbst handhaben zu müssen. Referenziere die Vault-Keys in der ci.yml mit ${{ vault.secretKey }}, und die Secrets werden zum Deployment-Zeitpunkt eingespeist.

Shared-Vault-Endpunkte

Die Public API stellt außerdem Endpunkte zur Verwaltung von Shared Vaults bereit — team-weite Vaults, die über mehrere Workspaces hinweg genutzt werden können. Damit lassen sich ein Shared Vault und dessen Secrets programmatisch bereitstellen, zum Beispiel beim Bootstrapping einer neuen Team-Umgebung.

Shared-Vault-Endpunkte sind auf das Team und nicht auf einen einzelnen Workspace beschränkt und folgen diesem Basispfad:

/vault/teams/{teamId}/shared

Die Semantik der Secret-Werte — Revisionskennungen, Schreib-/List-/Löschverhalten — ist identisch zu den oben beschriebenen Workspace-Endpunkten. Das Auflisten erfordert Lese-Zugriff auf das Team; Erstellen, Löschen und Ändern erfordern Schreib-Zugriff auf das Team.

Shared Vaults auflisten

GET /vault/teams/{teamId}/shared

Gibt die Namen aller zum Team gehörenden Shared Vaults zurück.

Response:

["production-secrets", "staging-secrets"]

Einen Shared Vault erstellen

POST /vault/teams/{teamId}/shared

Erstellt einen neuen, leeren Shared Vault für das Team. Secrets werden separat über den unten stehenden Store-Endpunkt hinzugefügt.

Request-Body:

{
  "name": "production-secrets"
}

Einen Shared Vault löschen

DELETE /vault/teams/{teamId}/shared/{vaultName}

Löscht einen Shared Vault und alle darin gespeicherten Secrets dauerhaft. Jeder Workspace, der diesem Vault noch zugewiesen ist, wird beim nächsten Sync keine Secrets mehr auflösen können.

Secrets in einem Shared Vault speichern

POST /vault/teams/{teamId}/shared/{vaultName}/secrets

Schreibt ein oder mehrere Secret-Key-Value-Paare in den angegebenen Shared Vault. Gibt eine Zuordnung jedes Keys zu seiner Revisionskennung zurück (eine Versionsnummer kombiniert mit einem Zeitstempel).

Request-Body:

{
  "DATABASE_PASSWORD": "supersecretpassword",
  "API_KEY": "123456789"
}

Response:

{
  "DATABASE_PASSWORD": "1__2026-03-05T10:14:48.490756937Z",
  "API_KEY": "1__2026-03-05T10:14:48.490756937Z"
}

Secret-Keys in einem Shared Vault auflisten

GET /vault/teams/{teamId}/shared/{vaultName}/keys

Gibt die Liste der im angegebenen Shared Vault gespeicherten Secret-Keys zurück. Werte werden über diesen Endpunkt niemals offengelegt.

Response:

["DATABASE_PASSWORD", "API_KEY"]

Secrets aus einem Shared Vault löschen

DELETE /vault/teams/{teamId}/shared/{vaultName}/secrets

Entfernt ein oder mehrere benannte Secrets aus dem Shared Vault. Das Löschen aller Keys entfernt nicht den Vault selbst — dafür den Endpunkt Einen Shared Vault löschen verwenden.

Request-Body:

["DATABASE_PASSWORD", "API_KEY"]

Sicherheit und Zugriffskontrolle

Codesphere setzt eine strikte Isolation für den Secret-Zugriff durch:

• Referenzbasierter Zugriff: Ein Service kann ein Secret nur abrufen, wenn es in seiner Konfiguration explizit definiert ist.
• Landscape-Isolation: Secrets werden auf Landscape-Ebene verwaltet, wodurch unterschiedliche Deployment-Umgebungen getrennt bleiben.

Lebenszyklus und Bereinigung

Um eine saubere Sicherheitslage zu gewährleisten, verwaltet Codesphere den Lebenszyklus der Secrets automatisch. Wird ein Workspace gelöscht:

• Werden alle zugehörigen Secret-Einträge im Vault, die mit diesem Workspace und dessen Services in Verbindung stehen, identifiziert.
• Führt das System eine dauerhafte Bereinigung aller zugehörigen Keys durch.
• Bleiben nach dem Entfernen des Workspace keine sensiblen Daten mehr verfügbar.

Shared Vaults folgen einem anderen Lebenszyklus: Da sie dem Team gehören und über Workspaces hinweg geteilt werden, werden sie beim Löschen eines einzelnen Workspace nicht entfernt. Ein Shared Vault und seine Secrets bleiben bestehen, bis er explizit gelöscht wird — entweder über die Public API oder durch einen Installationsadmin.