Secret Management

Codesphere bietet ein Secret-Management-System, das in OpenBao integriert ist, einen Open-Source-Security-Vault. Damit wird sichergestellt, dass sensible Daten wie API-Schlüssel, Datenbank-Zugangsdaten und Zertifikate mit branchenüblicher Verschlüsselung gespeichert und nur bei Bedarf in deine Dienste injiziert werden.

Überblick​

Anders als normale Umgebungsvariablen werden Secrets in einem Vault gespeichert, der mit einer Codesphere-Instanz ausgeliefert wird. Das bietet mehrere Vorteile:

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

Secrets referenzieren​

Secrets werden im Landscape Config Editor verwaltet. Um ein Secret zu definieren, musst du eine bestimmte Templating-Syntax verwenden – unabhängig davon, ob du die UI oder die YAML-Konfiguration nutzt. Derzeit wird der Zugriff auf Secrets nur direkt in den Landscape-Diensten unterstützt und nicht in den gemeinsamen prepare- oder test-Schritten.

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

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​

Über Vault-Secrets hinaus unterstützt Codesphere dynamische Templates, um systemweite IDs oder bestehende Workspace-Umgebungsvariablen zu referenzieren. Diese sind besonders nützlich, um deine Konfiguration portabel zu machen oder Variablen umzubenennen.

Anwendungsfall: Variablen umbenennen​

Mit dem Template ${{ workspace.env[...] }} kannst du globale Variablen auf spezifische Anforderungen eines Dienstes abbilden.

Wenn ein Backend-Dienst beispielsweise eine Umgebungsvariable namens PG_USER erwartet, deine Datenbank-Zugangsdaten aber global als BACKEND_PG_USER gespeichert sind, um Namenskollisionen mit anderen Datenbanken zu vermeiden, kannst du sie so abbilden:

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

Synchronisierung und Persistenz​

Nachdem du die Secret-Referenzen definiert hast, musst du das Landscape Profile im Execution Manager synchronisieren.

Der Sync-Prozess​

Wenn die ausgewählte ci.yml während einer Landscape-Synchronisierung neue Secret-Referenzen enthält, ist der Nutzer dafür verantwortlich, die tatsächlichen Secret-Werte bereitzustellen. Der Prozess läuft in diesen Schritten ab:

1. Nutzeraufforderung: Ein Modal erscheint und fordert dich auf, die in deiner Konfiguration definierten Secret-Einträge bereitzustellen.
2. Eingabe: Du musst den echten Wert des Secrets mindestens einmal eingeben, um den Eintrag im Vault zu initialisieren.
3. Persistenz: Nach dem Absenden werden diese Werte in der OpenBao-Instanz persistiert.
4. Injektion: Die Synchronisierung wird fortgesetzt, und die Landscape greift auf die Vault-Keys zu, um sie in die jeweiligen Dienste zu injizieren.

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

Secrets aktualisieren​

Auch wenn derzeit keine dedizierte Benutzeroberfläche (UI) für den Secrets-Vault verfügbar ist, können Secrets während der Landscape-Synchronisierung verwaltet werden. Beim Synchronisieren einer Landscape kannst du wählen, ob du mit bestehenden Secrets deployen oder sie vor dem Fortfahren aktualisieren möchtest. Der Prozess läuft in diesen Schritten ab:

1. Nutzeraufforderung: Ein Modal erscheint und fordert dich auf, auszuwählen, wie die Landscape deployt werden soll: mit bestehenden Secrets oder mit geänderten Secrets vor dem Deployment.
2. Eingabe: Wähle change secrets before deploying. Gib den neuen echten Secret-Wert an. Dieser überschreibt nach dem Klick auf die Bestätigungsschaltfläche den Wert im Vault. Hinweis: Du kannst jede Änderung am Secret rückgängig machen oder den echten Wert während des Bearbeitungsvorgangs einsehen.
3. Persistenz: Nach dem Absenden werden diese Werte in der OpenBao-Instanz persistiert.
4. Injektion: Die Synchronisierung wird fortgesetzt, und die Landscape greift auf die Vault-Keys zu, um sie in die jeweiligen Dienste zu injizieren.

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

Gemeinsame Vaults​

Standardmäßig erhält jeder Workspace seine eigene isolierte Vault-Partition, und die von ihr referenzierten Secret-Werte müssen während des ersten Landscape-Syncs initialisiert werden (siehe Der Sync-Prozess). Ein gemeinsamer Vault entfernt diesen manuellen Schritt für Secrets, die teamweit gemeinsam genutzt werden.

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

• Zugriff ohne Einrichtung: Workspaces, die einem gemeinsamen Vault zugewiesen sind, können dessen Secrets sofort referenzieren – ohne dass jemand während der Workspace-Erstellung oder des Landscape-Syncs Werte eingeben muss.
• Eine einzige Quelle der Wahrheit: Gemeinsame Zugangsdaten (z. B. geteilte Datenbank-Verbindungsdetails) werden einmal gespeichert und überall wiederverwendet, statt in jeden Workspace dupliziert zu werden.
• Zentrale Rotation: Das Aktualisieren eines Werts im gemeinsamen Vault wird beim nächsten Deployment auf jeden Workspace übertragen, der ihn verwendet.

Wie ein Workspace gemeinsame Secrets auflöst​

Die Templating-Syntax zum Referenzieren eines Secrets ändert sich nicht – du verwendest weiterhin ${{ vault.secretKey }} in deiner Dienstkonfiguration (siehe Secrets referenzieren). Was sich ändert, ist, gegen welchen Vault die Referenz aufgelöst wird:

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

Das bedeutet, ein Workspace, der auf einen gemeinsamen Vault verweist, kann eine Landscape deployen, die gemeinsame Secrets nutzt, ohne dass vorab eine Initialisierung pro Workspace nötig ist.

Einem Workspace einen gemeinsamen Vault zuweisen​

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

Secrets über die Public API verwalten​

Die Codesphere Public API stellt einen vollständigen Satz an Vault-Endpunkten bereit, mit dem du Workspace-Secrets programmatisch verwalten und automatisch generieren kannst – zum Beispiel in einer CI/CD-pipeline oder einer internen Entwicklerplattform. Authentifizierung und allgemeine API-Nutzung werden in der Public-API-Dokumentation behandelt.

Alle Vault-Endpunkte folgen diesem Basispfad:

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

Secrets speichern​

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

Schreibt ein oder mehrere Secret-Schlüssel-Wert-Paare in den Vault für einen bestimmten Workspace. Gibt eine Zuordnung jedes Schlüssels zu seinem Revisions-Bezeichner zurück, der 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-Schlüssel auflisten​

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

Gibt die Liste der für einen Workspace gespeicherten Secret-Schlüssel 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 – kein Klartextwert muss jemals deine pipeline verlassen. Die Form jedes generierten Werts wird durch eine Passwort-Policy gesteuert.

Felder der Passwort-Policy:​

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 Revisions-Bezeichner:

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

Endpunkte für gemeinsame Vaults​

Die Public API stellt außerdem Endpunkte zur Verwaltung von gemeinsamen Vaults bereit – Vaults auf Team-Ebene, die über Workspaces hinweg wiederverwendet werden können. Damit kannst du einen gemeinsamen Vault und seine Secrets programmatisch bereitstellen, zum Beispiel beim Aufsetzen einer neuen Team-Umgebung.

Endpunkte für gemeinsame Vaults sind auf das Team statt auf einen einzelnen Workspace beschränkt und folgen diesem Basispfad:

/vault/teams/{teamId}/shared

Die Semantik der Secret-Werte – Revisions-Bezeichner, Schreib-/Auflist-/Löschverhalten – ist identisch mit den oben beschriebenen Workspace-Endpunkten. Das Auflisten erfordert read-Zugriff auf das Team; das Erstellen, Löschen und Ändern erfordern write-Zugriff auf das Team.

Gemeinsame Vaults auflisten​

GET /vault/teams/{teamId}/shared

Gibt die Namen aller gemeinsamen Vaults zurück, die zum Team gehören.

Response:

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

Einen gemeinsamen Vault erstellen​

POST /vault/teams/{teamId}/shared

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

Request-Body:

{
  "name": "production-secrets"
}

Einen gemeinsamen Vault löschen​

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

Löscht einen gemeinsamen Vault und alle darin gespeicherten Secrets dauerhaft. Jeder Workspace, der diesem Vault noch zugewiesen ist, kann seine Secrets beim nächsten Sync nicht auflösen.

Secrets in einem gemeinsamen Vault speichern​

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

Schreibt ein oder mehrere Secret-Schlüssel-Wert-Paare in den benannten gemeinsamen Vault. Gibt eine Zuordnung jedes Schlüssels zu seinem Revisions-Bezeichner 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-Schlüssel in einem gemeinsamen Vault auflisten​

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

Gibt die Liste der im benannten gemeinsamen Vault gespeicherten Secret-Schlüssel zurück. Werte werden über diesen Endpunkt niemals offengelegt.

Response:

["DATABASE_PASSWORD", "API_KEY"]

Secrets aus einem gemeinsamen Vault löschen​

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

Entfernt ein oder mehrere benannte Secrets aus dem gemeinsamen Vault. Das Löschen aller Schlüssel entfernt nicht den Vault selbst – verwende dafür den Endpunkt Einen gemeinsamen Vault löschen.

Request-Body:

["DATABASE_PASSWORD", "API_KEY"]

Sicherheit und Zugriffskontrolle​

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

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

Lebenszyklus und Bereinigung​

Um eine saubere Sicherheitslage aufrechtzuerhalten, verwaltet Codesphere den Lebenszyklus deiner Secrets automatisch. Wenn ein Workspace gelöscht wird:

• Alle zugehörigen Secret-Einträge im Vault, die diesen Workspace und seine Dienste betreffen, werden identifiziert.
• Das System führt eine dauerhafte Bereinigung aller zugehörigen Schlüssel durch.
• Nach dem Entfernen des Workspace bleiben keine sensiblen Daten verfügbar.

Gemeinsame Vaults folgen einem anderen Lebenszyklus: Da sie dem Team gehören und über Workspaces hinweg geteilt werden, werden sie nicht entfernt, wenn ein einzelner Workspace gelöscht wird. Ein gemeinsamer Vault und seine Secrets bestehen fort, bis er explizit gelöscht wird – entweder über die Public API oder durch einen Installations-Admin.