Secrets

Composia verwaltet verschlüsselte Secret-Dateien im Sollzustand-Repository mit Age-Verschlüsselung. Ver- und Entschlüsselung finden auf dem Controller statt. Agenten erhalten niemals Zugriff auf den privaten Age-Schlüssel.

Konfiguration

Secrets erfordern ein Age-Schlüsselpaar. In der Controller-Konfiguration einrichten:

controller:
  secrets:
    provider: age
    identity_file: "/app/configs/age-identity.key"

Generiere ein Schlüsselpaar:

age-keygen -o age-identity.key

Optional: Extrahiere den öffentlichen Schlüssel als Empfänger:

age-keygen -y age-identity.key > age-recipients.txt

Wie Secrets gespeichert werden

Secret-Dateien im Repository haben konventionsgemäß die Erweiterung .enc. Sie werden als Age-verschlüsselter Geheimtext gespeichert:

my-app/
├── docker-compose.yaml
├── composia-meta.yaml
└── .secret.env.enc        (mit Age verschlüsselt)

Der Controller verschlüsselt Klartext beim Schreiben und entschlüsselt beim Lesen. Das Repository enthält nur Geheimtext. Secrets erscheinen niemals als Klartext im Repo, in Aufgabenprotokollen oder bei der Übertragung an Agenten.

Wie Secrets zu Agenten gelangen

Während des Render-Schritts einer Deploy- oder Update-Aufgabe:

1. Liest der Controller verschlüsselte Dateien aus dem Dienstverzeichnis im Repo.
2. Entschlüsselt jede Datei mit dem privaten Age-Schlüssel.
3. Injiziert den entschlüsselten Inhalt als .composia-secret.env in das Dienstpaket.

Das Paket wird über die Agent-Report-Verbindung an den Agenten gestreamt. Der Agent schreibt das Paket auf die Festplatte und fährt mit docker compose up fort. Die entschlüsselte Secret-Umgebung steht den Compose-Diensten zur Verfügung, ohne dass der Agent jemals den privaten Schlüssel sieht.

CLI-Nutzung

Schreibe eine verschlüsselte Secret-Datei:

composia secret update my-app .secret.env.enc --file ./local-plain.env

Lese und entschlüssele eine Secret-Datei:

composia secret get my-app .secret.env.enc

Bearbeite ein Secret direkt (öffnet deinen Editor):

composia secret edit my-app .secret.env.enc

Alle Secret-Schreiboperationen beinhalten eine Basis-Revisionsprüfung, um Konflikte mit gleichzeitigen Änderungen zu verhindern.

Dateipfad-Regeln

Secret-Dateipfade müssen:

• Relativ zum Dienstverzeichnis sein (nicht absolut).
• Keine Pfadtraversierungssequenzen wie ../ enthalten.
• Auf eine Datei innerhalb des Dienstverzeichnisses verweisen.

Der Controller lokalisiert den Dienst, löst den Dateipfad relativ zum Dienstverzeichnis auf und operiert auf der Repo-Datei.

Fehlerbedingungen

• Secrets nicht konfiguriert: GetSecret und UpdateSecret geben FailedPrecondition zurück, wenn controller.secrets nicht gesetzt ist.
• Datei nicht gefunden: GetSecret gibt eine leere Inhaltsantwort statt eines Fehlers zurück, wenn die Datei nicht existiert. Dies ermöglicht Clients, zwischen fehlenden Dateien und Entschlüsselungsfehlern zu unterscheiden.
• Basis-Revisionskonflikt: UpdateSecret verwendet CAS (Compare-and-Swap) gegen den Repo-HEAD. Wenn sich das Repo seit dem letzten Lesen geändert hat, schlägt das Schreiben mit einem Revisionskonflikt fehl.