Secret Management

Preview Feature

Secret Management ist derzeit eine Preview-Funktion. Es wird hier eine frühe Version dieser Funktionalität gezeigt, die sich in zukünftigen Updates noch ändern kann, während die Erfahrung weiter verbessert wird.

Codesphere bietet ein Secret-Management-System, das mit OpenBao, einem Open-Source-Sicherheitstresor, integriert ist. 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. Dies 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.
• Automatische Bereinigung: Secrets sind an den Lifecycle 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

Um mit dem visuellen Editor ein Secret zu einem Service hinzuzufügen:

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. Wechsle zum Tab Values.
4. Füge einen neuen Eintrag mit der Template-Syntax hinzu:
   • Key: Der Name der Umgebungsvariable, die vom Service verwendet 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“ des 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-Vorgangs 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 Environment-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 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 beispielsweise ein Backend-Service eine Umgebungsvariable namens PG_USER, die Datenbank-Zugangsdaten sind jedoch global als BACKEND_PG_USER gespeichert, um Namenskollisionen mit anderen Datenbanken zu vermeiden, kann die Zuordnung wie folgt erfolgen:

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

Sync und Persistenz

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

Der Sync-Vorgang

Wenn die ausgewählte ci.yml-Datei während einer Landscape-Synchronisierung neue Secret-Referenzen enthält, ist der Nutzer selbst dafür verantwortlich, die tatsächlichen Secret-Werte bereitzustellen. Der Ablauf umfasst folgende Schritte:

1. Aufforderung: Ein Modal erscheint und fordert dazu auf, die in der Konfiguration definierten Secret-Einträge bereitzustellen.
2. Eingabe: Der Secret-Key und der zugehö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. Injektion: Der Sync 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-Vorgangs ausgelöst 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 Secret-Eintrag zugreifen kann, auf den er verweist. Stelle sicher, dass alle Secrets beim ersten Deployment einer Landscape korrekt eingerichtet sind.

Sicherheit und Zugriffskontrolle

Codesphere erzwingt eine strikte Isolation für den 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 unterschiedliche Deployment-Umgebungen getrennt bleiben.

Lifecycle und Bereinigung

Um eine saubere Sicherheitslage zu gewährleisten, verwaltet Codesphere den Lifecycle der Secrets automatisch. Beim Löschen eines Workspace:

• Werden alle zugehörigen Secret-Einträge im Vault identifiziert, die zu diesem Workspace und dessen Services gehören.
• Führt das System eine permanente Bereinigung aller zugehörigen Keys durch.
• Bleiben keine sensiblen Daten mehr verfügbar, nachdem der Workspace entfernt wurde.