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 im Zuge der weiteren Verbesserung noch ändern kann.

Codesphere bietet ein Secret-Management-System, das mit OpenBao integriert ist, einem Open-Source-Security-Vault. Dadurch wird sichergestellt, dass vertrauliche Daten wie API-Keys, Datenbankzugangsdaten und Zertifikate nach Industriestandard verschlüsselt gespeichert und nur bei Bedarf in die Services eingespielt werden.

Überblick

Im Gegensatz zu üblichen 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 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 unabhängig davon, ob die UI oder die YAML-Konfiguration verwendet wird, eine bestimmte Template-Syntax genutzt werden.

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 mithilfe der Template-Syntax einen neuen Eintrag hinzu:
   • Key: Der Name der Umgebungsvariable, die der Service verwendet (z. B. SECRET_KEY).
   • Value: Das Template, das den Vault-Key referenziert (${{ vault.secretFoo }}).

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

YAML-Konfiguration

Für die direkte Konfiguration werden Secrets im env-Abschnitt des ci.yml-Profils definiert. Codesphere parst diese Templates während des Sync-Vorgangs und spielt 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 zur Referenzierung von System-IDs oder vorhandenen Umgebungsvariablen des Workspace. Diese sind besonders nützlich, um die Konfiguration portabel zu gestalten oder Variablen neu zuzuordnen.

Template	Beschreibung
${{ workspace.id }}	Wird zur ID des Workspace aufgelöst, der die Landscape enthält.
${{ team.id }}	Wird zur ID des Teams aufgelöst, dem der Workspace gehört.
${{ workspace.env['KEY'] }}	Wird zu einer globalen Umgebungsvariable des Workspace aufgelöst.

Anwendungsfall: Variablen-Remapping

Mit dem Template ${{ workspace.env[...] }} können globale Variablen auf spezifische Service-Anforderungen abgebildet werden.

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

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

Synchronisierung und Persistenz

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

Der Sync-Vorgang

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

1. Benutzerabfrage: Es erscheint ein Modal, das zur Eingabe der in der Konfiguration definierten Secret-Einträge auffordert.
2. Eingabe: Der Secret-Key und der dazugehörige tatsächliche Wert müssen 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. Einspielung: Der Sync wird fortgesetzt, und die Landscape greift auf die Vault-Keys zu, um sie in die jeweiligen Services einzuspielen.

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

info

Vor jeder Landscape-Synchronisierung können bestehende Secrets auch manuell überschrieben werden.

warnung

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

Sicherheit und Zugriffskontrolle

Codesphere erzwingt eine strikte Isolation beim Zugriff auf Secrets:

• Referenzbasierter Zugriff: Ein Service kann ein Secret nur abrufen, wenn es explizit in dessen Konfiguration definiert ist.
• Landscape-Isolation: Secrets werden auf Landscape-Ebene verwaltet, wodurch sichergestellt ist, dass unterschiedliche Deployment-Umgebungen voneinander 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 identifiziert, die mit diesem Workspace und dessen Services in Verbindung stehen.
• Führt das System eine permanente Bereinigung aller zugehörigen Keys durch.
• Bleiben nach dem Entfernen des Workspace keine vertraulichen Daten mehr verfügbar.