Version: Weekly Build

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 Nutzererfahrung weiter verbessern.

Codesphere bietet ein Secret-Management-System, das in OpenBao integriert ist, einen Open-Source-Sicherheitstresor. Dies stellt sicher, dass sensible Daten wie API-Schlüssel, Datenbank-Anmeldedaten und Zertifikate mit branchenüblicher Verschlüsselung gespeichert und erst bei Bedarf in deine Services eingebunden werden.

Übersicht

Im Gegensatz zu Standard-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 vor der Speicherung verschlüsselt.
Granularer Zugriff: Nur Services, die explizit auf ein Secret verweisen, können auf dessen Wert zugreifen.
Automatisches Aufräumen: 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, musst du eine bestimmte Template-Syntax verwenden, unabhängig davon, ob du die UI oder die YAML-Konfiguration verwendest. Derzeit wird der Zugriff auf Secrets nur direkt in den Landscape-Services unterstützt, nicht in den gemeinsamen Prepare- oder Test-Schritten.

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

UI-Konfiguration
YAML-Konfiguration

So fügst du einem Service über den visuellen Editor ein Secret hinzu:

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

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

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

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

Erweiterte Umgebungs-Templates

Über Vault-Secrets hinaus unterstützt Codesphere dynamische Templates, um auf System-IDs oder bestehende Workspace-Umgebungsvariablen zu verweisen. Diese sind besonders nützlich, um deine 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.
${{ resourceGroup.id }}	Löst sich zur ID der Resource Group auf, der der Workspace gehört.
${{ workspace.env['KEY'] }}	Löst sich zu einer globalen Workspace-Umgebungsvariable auf.

${{ team.id }} funktioniert weiterhin als Alias für ${{ resourceGroup.id }}.

Anwendungsfall: Variablen umbenennen

Mit dem Template ${{ workspace.env[...] }} kannst du globale Variablen auf spezifische Service-Anforderungen mappen.

Wenn ein Backend-Service beispielsweise eine Umgebungsvariable namens PG_USER erwartet, deine Datenbank-Anmeldedaten jedoch global als BACKEND_PG_USER gespeichert sind, um Namenskonflikte mit anderen Datenbanken zu vermeiden, kannst du sie wie folgt mappen:

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-Vorgang

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 Vorgang läuft in folgenden Schritten ab:

Nutzer-Eingabeaufforderung: Ein Modal erscheint und fordert dich auf, die in deiner Konfiguration definierten Secret-Einträge bereitzustellen.
Eingabe: Du musst den tatsächlichen Wert des Secrets mindestens einmal eingeben, um den Eintrag im Vault zu initialisieren.
Persistenz: Nach dem Absenden werden diese Werte in der OpenBao-Instanz gespeichert.
Einbindung: Die Synchronisierung läuft weiter, und die Landscape greift auf die Vault-Schlüssel zu, um sie in die jeweiligen Services einzubinden.

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

warnung

Landscape-Synchronisierungen schlagen fehl, wenn ein im CI-Profil definierter Service nicht auf den von ihm referenzierten Secret-Eintrag zugreifen kann. Stelle sicher, dass alle Secrets beim ersten Deployment einer Landscape korrekt eingerichtet sind.

Secrets aktualisieren

Obwohl derzeit noch keine eigene 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 diese vor dem Fortfahren aktualisieren möchtest. Der Vorgang läuft in folgenden Schritten ab:

Nutzer-Eingabeaufforderung: Ein Modal erscheint und fordert dich auf, auszuwählen, wie die Landscape deployt werden soll: mit bestehenden Secrets oder mit Änderung der Secrets vor dem Deployment.
Eingabe: Wähle Secrets vor dem Deployment ändern. Gib den neuen tatsächlichen Secret-Wert ein. Dieser überschreibt den Wert im Vault, nachdem du auf die Bestätigungsschaltfläche geklickt hast. Hinweis: Du kannst jede Änderung am Secret rückgängig machen oder den tatsächlichen Wert während der Bearbeitung einsehen.
Persistenz: Nach dem Absenden werden diese Werte in der OpenBao-Instanz gespeichert.
Einbindung: Die Synchronisierung läuft weiter, und die Landscape greift auf die Vault-Schlüssel zu, um sie in die jeweiligen Services einzubinden.

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

Shared Vaults

Standardmäßig erhält jeder Workspace eine eigene, isolierte Vault-Partition, und die von ihm referenzierten Secret-Werte müssen während der ersten Landscape-Synchronisierung initialisiert werden (siehe Der Sync-Vorgang). Ein Shared Vault erspart diesen manuellen Schritt für Secrets, die über eine Resource Group hinweg gemeinsam genutzt werden.

Ein Shared Vault ist eine dedizierte Partition innerhalb des Cluster-Vaults, die auf Resource-Group-Ebene statt auf Workspace-Ebene existiert. Einmal erstellt, kann er von einer beliebigen Anzahl von Workspaces innerhalb derselben Resource Group genutzt werden. Die wichtigsten Vorteile sind:

Zugriff ohne Einrichtungsaufwand: Workspaces, die einem Shared Vault zugewiesen sind, können dessen Secrets sofort referenzieren — ohne dass jemand während der Workspace-Erstellung oder Landscape-Synchronisierung Werte eingeben muss.
Single Source of Truth: Gemeinsame Anmeldedaten (z. B. gemeinsame Datenbankverbindungsdaten) werden einmal gespeichert und überall wiederverwendet, anstatt in jedem Workspace dupliziert zu werden.
Zentralisierte Rotation: Die Aktualisierung eines Werts im Shared Vault wirkt sich beim nächsten Deployment auf jeden Workspace aus, der ihn verwendet.

info

Shared Vaults sind auf eine Resource Group beschränkt. Zum Auflisten ist Lese-Zugriff auf die Resource Group erforderlich, zum Erstellen, Löschen oder Ändern ist Schreib-Zugriff auf die Resource Group erforderlich.

Wie ein Workspace Shared Secrets auflöst

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

Wenn einem Workspace ein Shared Vault zugewiesen ist, werden alle ${{ vault.* }}-Referenzen in seiner Landscape gegen diese gemeinsame Partition aufgelöst.
Wenn kein Shared Vault zugewiesen ist, 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. Wenn du einen Workspace auf einen Shared Vault umstellst, stelle sicher, dass jeder von seiner Landscape referenzierte ${{ vault.* }}-Schlüssel in diesem Shared Vault existiert, andernfalls schlägt die nächste Synchronisierung fehl.

Einem Workspace einen Shared Vault zuweisen

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

Bei der Workspace-Erstellung
Bei einem bestehenden Workspace

Erweitere beim Erstellen eines Workspace im zweiten Schritt des Dialogs die Advanced Options und wähle im Dropdown Secrets Vault einen Vault aus. Belässt du die Einstellung auf Workspace (default), bleibt der Workspace isoliert.

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

info

Der Auswahlbereich Secrets Vault wird nur angezeigt, wenn Secret Management für deine Installation aktiviert ist.

Secrets über die Public API verwalten

Die Codesphere Public API stellt einen vollständigen Satz von Vault-Endpunkten bereit, mit denen du Workspace-Secrets programmgesteuert verwalten und automatisch generieren kannst — zum Beispiel in einer CI/CD-Pipeline oder einer internen Entwicklerplattform. Authentifizierung und allgemeine API-Nutzung sind in der Public-API-Dokumentation beschrieben.

Alle Vault-Endpunkte folgen diesem Basispfad:

/vault/resource-groups/{resourceGroupId}/workspaces/{workspaceId}

Secrets speichern

POST /vault/resource-groups/{resourceGroupId}/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 seiner Revisionskennung zurück, die eine Versionsnummer mit einem 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/resource-groups/{resourceGroupId}/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/resource-groups/{resourceGroupId}/workspaces/{workspaceId}

Entfernt die angegebenen Secrets dauerhaft aus dem Vault.

Request-Body:

["DATABASE_PASSWORD", "API_KEY"]

Secrets automatisch generieren

POST /vault/resource-groups/{resourceGroupId}/workspaces/{workspaceId}/generate

Generiert kryptografisch zufällige Secret-Werte und speichert sie direkt im Vault — kein Klartext-Wert muss jemals deine Pipeline verlassen. Die Form jedes generierten Werts wird durch eine Passwortrichtlinie gesteuert.

Felder der Passwortrichtlinie:

Feld	Typ	Beschreibung
`length`	`number`	Gesamtlänge des generierten Secrets.
`rules`	`array`	Eine oder mehrere Zeichensatzregeln, die bei der Generierung angewendet werden.
`rules[].charset`	`string`	Die Menge der Zeichen, aus denen geschöpft wird.
`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 — du kannst für jede neue Umgebung starke, eindeutige Secrets erstellen, ohne die Rohwerte selbst zu handhaben. Referenziere die Vault-Schlüssel in deiner ci.yml mit ${{ vault.secretKey }}, und die Secrets werden zum Deployment-Zeitpunkt eingebunden.

Shared-Vault-Endpunkte

Die Public API stellt außerdem Endpunkte zur Verwaltung von Shared Vaults bereit — Vaults auf Resource-Group-Ebene, die über mehrere Workspaces hinweg wiederverwendet werden können. Damit kannst du einen Shared Vault und dessen Secrets programmgesteuert bereitstellen, zum Beispiel beim Bootstrapping einer neuen Resource-Group-Umgebung.

Shared-Vault-Endpunkte sind auf die Resource Group statt auf einen einzelnen Workspace beschränkt und folgen diesem Basispfad:

/vault/resource-groups/{resourceGroupId}/shared

Die Semantik der Secret-Werte — Revisionskennungen, Verhalten beim Schreiben/Auflisten/Löschen — ist identisch mit den oben beschriebenen Workspace-Endpunkten. Zum Auflisten ist Lese-Zugriff auf die Resource Group erforderlich; zum Erstellen, Löschen und Ändern ist Schreib-Zugriff auf die Resource Group erforderlich.

Shared Vaults auflisten

GET /vault/resource-groups/{resourceGroupId}/shared

Gibt die Namen aller Shared Vaults zurück, die zur Resource Group gehören.

Response:

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

Einen Shared Vault erstellen

POST /vault/resource-groups/{resourceGroupId}/shared

Erstellt einen neuen, leeren Shared Vault für die Resource Group. Secrets werden separat über den unten stehenden Speicher-Endpunkt hinzugefügt.

Request-Body:

{
  "name": "production-secrets"
}

Einen Shared Vault löschen

DELETE /vault/resource-groups/{resourceGroupId}/shared/{vaultName}

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

Secrets in einem Shared Vault speichern

POST /vault/resource-groups/{resourceGroupId}/shared/{vaultName}/secrets

Schreibt ein oder mehrere Secret-Schlüssel-Wert-Paare in den genannten Shared Vault. Gibt eine Zuordnung jedes Schlüssels 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-Schlüssel in einem Shared Vault auflisten

GET /vault/resource-groups/{resourceGroupId}/shared/{vaultName}/keys

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

Response:

["DATABASE_PASSWORD", "API_KEY"]

Secrets aus einem Shared Vault löschen

DELETE /vault/resource-groups/{resourceGroupId}/shared/{vaultName}/secrets

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

Request-Body:

["DATABASE_PASSWORD", "API_KEY"]

Sicherheit und Zugriffskontrolle

Codesphere erzwingt eine strikte Isolierung beim Zugriff auf Secrets:

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

Lebenszyklus und Aufräumen

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

Werden alle zugehörigen Secret-Einträge im Vault identifiziert, die mit diesem Workspace und seinen Services in Verbindung stehen.
Führt das System ein dauerhaftes Aufräumen aller zugehörigen Schlüssel durch.
Bleiben keine sensiblen Daten mehr verfügbar, nachdem der Workspace entfernt wurde.

Shared Vaults folgen einem anderen Lebenszyklus: Da sie der Resource Group gehören und über Workspaces hinweg gemeinsam genutzt 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 Installations-Admin.

Übersicht​

Secrets referenzieren​

Erweiterte Umgebungs-Templates​

Anwendungsfall: Variablen umbenennen​

Synchronisierung und Persistenz​

Der Sync-Vorgang​

Secrets aktualisieren​

Shared Vaults​

Wie ein Workspace Shared Secrets auflöst​

Einem Workspace einen Shared Vault zuweisen​

Secrets über die Public API verwalten​

Secrets speichern​

Request-Body:​

Response:​

Secret-Schlüssel auflisten​

Response:​

Secrets löschen​

Request-Body:​

Secrets automatisch generieren​

Felder der Passwortrichtlinie:​

Request-Body:​

Shared-Vault-Endpunkte​

Shared Vaults auflisten​

Response:​

Einen Shared Vault erstellen​

Request-Body:​

Einen Shared Vault löschen​

Secrets in einem Shared Vault speichern​

Request-Body:​

Response:​

Secret-Schlüssel in einem Shared Vault auflisten​

Response:​

Secrets aus einem Shared Vault löschen​

Request-Body:​

Sicherheit und Zugriffskontrolle​

Lebenszyklus und Aufräumen​

Übersicht

Secrets referenzieren

Erweiterte Umgebungs-Templates

Anwendungsfall: Variablen umbenennen

Synchronisierung und Persistenz

Der Sync-Vorgang

Secrets aktualisieren

Shared Vaults

Wie ein Workspace Shared Secrets auflöst

Einem Workspace einen Shared Vault zuweisen

Secrets über die Public API verwalten

Secrets speichern

Request-Body:

Response:

Secret-Schlüssel auflisten

Response:

Secrets löschen

Request-Body:

Secrets automatisch generieren

Felder der Passwortrichtlinie:

Request-Body:

Shared-Vault-Endpunkte

Shared Vaults auflisten

Response:

Einen Shared Vault erstellen

Request-Body:

Einen Shared Vault löschen

Secrets in einem Shared Vault speichern

Request-Body:

Response:

Secret-Schlüssel in einem Shared Vault auflisten

Response:

Secrets aus einem Shared Vault löschen

Request-Body:

Sicherheit und Zugriffskontrolle

Lebenszyklus und Aufräumen