Secrets-Management

Das Problem & die Regel

Ein Secret ist alles, was jemandem Zugang gibt: DB-Passwort, API-Token, TLS-Key, SSH-Key, OAuth-Client-Secret, das Restic-Repo-Passwort.

SOPS (Secrets OPerationS, von Mozilla) verschlüsselt die Werte einer .env/.yaml/.json, lässt die Schlüsselnamen lesbar – Git-Diffs bleiben also aussagekräftig. age ist die Verschlüsselung darunter (modern, ein kleines Binary, ein einzeiliger Public Key).

1 age-Schlüssel erzeugen

Ein Schlüsselpaar pro Ort, der entschlüsseln können soll: dein Laptop, jeder Server, die CI.

winget install FiloSottile.age
age-keygen -o "$env:APPDATA\sops\age\keys.txt"
# Ausgabe: "Public key: age1ql3z...".  Die private Haelfte steht IN der Datei.

• Die keys.txt (privat) verlässt den Rechner nie und wird nie committet. Zusatz-Kopie in den Passwortmanager – geht sie verloren, entschlüsselst du nichts mehr.
• Der Public Key (age1…) ist harmlos – er kommt gleich in .sops.yaml.
• Server: dieselbe Zeile als root, Datei nach /root/.config/sops/age/keys.txt (chmod 600). Bootstrap: einmal per SSH (Secure Shell) hinlegen oder in den Snapshot backen.

2 SOPS & .sops.yaml

winget install Mozilla.SOPS

creation_rules:
  # prod-Secrets: Laptop + Server + CI duerfen entschluesseln
  - path_regex: secrets/prod/.*\.(env|ya?ml|json)$
    age: >-
      age1ql3z...laptop,
      age1abc4...server,
      age1def7...ci

  # alles andere: nur Laptop
  - path_regex: .*
    age: age1ql3z...laptop

Die Regeln greifen von oben nach unten, erste passende gewinnt. Mehr Umgebungen → mehr path_regex-Blöcke (secrets/staging/… mit anderen Empfängern).

3 Ein Secret verschlüsseln

# neue Datei anlegen/bearbeiten: EDITOR oeffnet Klartext, beim Speichern wird verschluesselt
$env:EDITOR = 'code --wait'
sops secrets/prod/app.env

# oder eine bestehende .env in-place verschluesseln
sops -e -i secrets/prod/app.env

git add .sops.yaml secrets/prod/app.env
git commit -m "app-secrets (verschluesselt)"

DB_PASSWORD=ENC[AES256_GCM,data:9f2K...,iv:...,tag:...,type:str]
JWT_SECRET=ENC[AES256_GCM,data:pQ7...,iv:...,tag:...,type:str]
sops_age__list_0__map_recipient=age1abc4...server
sops_mac=ENC[AES256_GCM,data:...]
sops_version=3.9.4

4 Formate

sops exec-env secrets/prod/app.env -- ./mein-tool          # Vars nur im Prozess
sops exec-file secrets/prod/config.yaml 'app --config {}'  # Klartext in tmpfs, Pfad als {}
sops -d --extract '["database"]["password"]' secrets/prod/app.yaml   # nur ein Wert

5 Auf dem Server entschlüsseln

Der Server hat seinen eigenen age-Schlüssel (Schritt 1). Der Deploy holt das Repo und schreibt die Klartext-Datei dorthin, wo Compose sie erwartet.

#!/bin/sh
set -eu
export SOPS_AGE_KEY_FILE=/root/.config/sops/age/keys.txt
cd /opt/repo && git pull --ff-only

install -m 600 /dev/null /opt/stacks/app/app.env
sops -d /opt/repo/secrets/prod/app.env > /opt/stacks/app/app.env

cd /opt/stacks/app && docker compose up -d

systemd-Alternative: systemd-creds encrypt + LoadCredentialEncrypted= bindet an den Host-Schlüssel (TPM) – sehr dicht, aber nicht portabel und nicht in Git. Gut für „nur auf dieser einen Maschine“, schlecht für „reproduzierbar aus dem Repo“.

6 In CI

Ein einziges echtes GitHub-Secret – den age-Schlüssel der CI. Alles andere liegt verschlüsselt im Repo.

1. CI-age-Schlüssel erzeugen, Public Key in .sops.yaml aufnehmen, sops updatekeys secrets/prod/*.
2. Die private Haelfte als Repo-Secret SOPS_AGE_KEY (Settings › Secrets › Actions).

      - uses: actions/checkout@v4
      - run: curl -sSL https://github.com/getsops/sops/releases/latest/download/sops-linux-amd64 -o /usr/local/bin/sops && chmod +x /usr/local/bin/sops
      - env:
          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
        run: |
          sops -d secrets/prod/app.env > app.env
          # ... deployen (siehe CI/CD-Anleitung); app.env danach nicht als Artefakt hochladen!

Noch besser: die CI entschlüsselt gar nicht, sondern der Server macht es beim Pull (Abschnitt 5). Dann kennt die CI keine Secrets – Pull-Modell in der CI/CD-Anleitung.

7 In Compose / systemd

services:
  app:
    image: ghcr.io/nursude/cloud-host/app:latest
    env_file: [ ./app.env ]          # die von sops -d geschriebene Datei
    restart: unless-stopped

Alternativ Docker/Podman-Secrets statt Env-Vars (landen als Datei unter /run/secrets/<name>, tauchen nicht in docker inspect auf): docker compose mit secrets: und die App liest *_FILE-Varianten (POSTGRES_PASSWORD_FILE …).

8 Rotieren & Zugriff entziehen

Empfänger ändern (Gerät verloren, Person raus)

# .sops.yaml: den alten age1... entfernen, ggf. neuen dazu, dann:
sops updatekeys secrets/prod/app.env
git commit -am "sops: alten Schluessel entfernt"

Wert rotieren

• Neuen Wert erzeugen, im Dienst setzen (DB: ALTER USER, Token: neu ausstellen, alten widerrufen).
• sops secrets/prod/app.env → Wert ersetzen → committen → deployen.
• Regelmäßig für die wichtigsten (DB-Root, API-Tokens) – z. B. halbjährlich, oder sofort bei Verdacht.

9 Betrieb

• Backup der age-Identitäten ist Teil des Katastrophenplans – ohne sie ist jedes Secret im Repo verloren. Gehört in den Passwortmanager und außer Haus (verschlüsselter USB-Stick beim Vertrauensperson).
• Pre-commit-Hook: gitleaks oder ein einfacher Grep, der unverschlüsselte Secrets im Commit blockiert – SOPS hat auch einen .git/hooks-Helfer.
• Neue Person / neuer Server: deren Public Key in .sops.yaml, sops updatekeys secrets/**, committen – ab dann können sie entschlüsseln.

+ Alternativen

+ Kubernetes

• helm-secrets (Plugin): helm secrets install … -f secrets.yaml – die secrets.yaml ist SOPS-verschlüsselt im Chart-Repo. Passt zum Helm-Deploy aus der Bibliothek-Enterprise-Anleitung.
• External Secrets Operator: der Cluster zieht Secrets aus einem externen Store (Infisical, Vault, AWS SM) und legt sie als Secret an – nichts Sensibles im Manifest-Repo.
• Sealed Secrets (Bitnami): mit dem Cluster-Public-Key verschlüsseltes SealedSecret ins Repo. Nur dieser Cluster kann es öffnen.
• Nie ein rohes kind: Secret (nur base64!) ins Git.

+ Kosten

SOPS und age sind Open Source, kein laufender Dienst – 0 €. Infisical und Doppler haben brauchbare Free-Tiers (bis ~5 Nutzer / ein Projekt). Vault/OpenBao betreibst du selbst (ein kleiner Container). Der eine GitHub-Actions-Secret für den CI-age-Key ist gratis.