Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 8: Secrets mit SOPS und age

Ziel: Die Secrets im Fleet-Repo verschlüsseln, Flux beim Anwenden entschlüsseln lassen, einen Schlüssel wechseln und erleben, was ohne Entschlüsselung passiert. · Dauer: ca. 75 min · Voraussetzung: Tag 7

Briefing

  • Seit Tag 0 stehen API-Key und Datenbank-Passwort im Klartext in Git. Jeder mit Leserechten auf das Repo kennt sie, für immer, denn Git vergisst nichts.
  • SOPS (Secrets OPerationS) verschlüsselt die Werte in einer YAML-Datei und lässt die Schlüssel lesbar. Ein Diff zeigt also noch, welches Feld sich geändert hat, nur nicht, wie.
  • age ist ein einfaches Verschlüsselungswerkzeug mit Schlüsselpaaren. Der öffentliche Schlüssel (age1…) darf ins Repo, mit ihm verschlüsselt jeder. Der private Schlüssel (AGE-SECRET-KEY-…) kommt nur in den Cluster, mit ihm entschlüsselt Flux.
  • Die Kustomization bekommt einen Block decryption. Der kustomize-controller entschlüsselt dann beim Anwenden, und im Cluster steht wieder Klartext.
 Laptop/VM:  sops --encrypt (öffentlicher Schlüssel)  ──►  Git: ENC[AES256_GCM,…]
 Cluster:    Secret sops-age (privater Schlüssel)
             kustomize-controller entschlüsselt  ──►  Secret notes-api: lab-api-key-…

Drill 1: Werkzeuge und Schlüssel

curl -fsSL -o ~/.local/bin/sops \
  https://github.com/getsops/sops/releases/download/v3.13.3/sops-v3.13.3.linux.amd64
chmod +x ~/.local/bin/sops
cd ~/flux-lab
curl -fsSLO https://github.com/FiloSottile/age/releases/download/v1.3.2/age-v1.3.2-linux-amd64.tar.gz
tar xzf age-v1.3.2-linux-amd64.tar.gz
mv age/age age/age-keygen ~/.local/bin/
rm -r age age-v1.3.2-linux-amd64.tar.gz
age --version

Erwartet:

v1.3.2

Das Schlüsselpaar:

age-keygen -o age.agekey
chmod 600 age.agekey

Erwartet (dein Schlüssel weicht ab):

Public key: age138s6889pax7c4q4tsj9lf0mu5cwela32v34x4apt2setmqm3lpfqk2ajzf

age.agekey liegt in ~/flux-lab, nicht im Fleet-Repo. Der private Teil kommt als Secret in den Cluster:

kubectl -n flux-system create secret generic sops-age --from-file=age.agekey=age.agekey

Erwartet:

secret/sops-age created

Dieses Secret legst du von Hand an, nicht aus Git. Es ist das eine Geheimnis, aus dem sich alle anderen ergeben. Wie es bei einem neuen Cluster hineinkommt, regelt eure Notfallplanung. Eine Sicherung von age.agekey an einem sicheren Ort gehört dazu.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Regeln für SOPS

Eine Datei .sops.yaml im Wurzelordner des Repos sagt SOPS, womit es verschlüsseln soll. Dann musst du den Schlüssel nicht bei jedem Aufruf angeben:

cd ~/flux-lab/fleet
cat > .sops.yaml <<EOF
creation_rules:
  - path_regex: .*\.yaml
    encrypted_regex: ^(data|stringData)\$
    age: $(age-keygen -y ../age.agekey)
EOF
cat .sops.yaml

Erwartet:

creation_rules:
  - path_regex: .*\.yaml
    encrypted_regex: ^(data|stringData)$
    age: age138s6889pax7c4q4tsj9lf0mu5cwela32v34x4apt2setmqm3lpfqk2ajzf
  • age-keygen -y liest den öffentlichen Schlüssel aus der Schlüsseldatei.
  • encrypted_regex begrenzt die Verschlüsselung auf data und stringData. kind, metadata und alles andere bleiben lesbar. Kubernetes und Flux brauchen sie, um das Objekt zuzuordnen.
  • Das <<EOF ohne Anführungszeichen ist hier Absicht: Die Shell soll $(age-keygen -y …) einsetzen. Das \$ schützt das Dollarzeichen am Ende der Regex.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Zuerst entschlüsseln können

Die Reihenfolge ist wichtig: Erst lernt Flux entschlüsseln, dann verschlüsselst du. Andersherum passiert etwas Hässliches:

Ausprobiert: Im Lab waren die Secrets zuerst verschlüsselt und gepusht, ohne decryption in der Kustomization. Flux hat die Dateien klaglos angewendet, mit den verschlüsselten Texten als Werten. Im Cluster stand danach als Datenbank-Passwort wörtlich ENC[AES256_GCM,data:HilOj0xX…. Die laufenden Pods merken davon nichts, aber beim nächsten Neustart findet notes-api weder den richtigen API-Key noch das richtige Passwort.

Alle Kustomizations, die notes-Secrets anwenden, bekommen den Block decryption. Er gehört direkt unter sourceRef:

for f in clusters/lab/notes.yaml clusters/lab/notes-db.yaml clusters/lab/notes-dev.yaml; do
  sed -i 's/^    name: flux-system$/    name: flux-system\n  decryption:\n    provider: sops\n    secretRef:\n      name: sops-age/' $f
done
grep -c 'provider: sops' clusters/lab/notes.yaml clusters/lab/notes-db.yaml \
  clusters/lab/notes-dev.yaml

Erwartet:

clusters/lab/notes.yaml:1
clusters/lab/notes-db.yaml:1
clusters/lab/notes-dev.yaml:2

notes-dev.yaml enthält zwei Kustomizations, also zwei Blöcke.

git add -A
git commit -m "SOPS: Regeln und Entschlüsselung"
git push
flux reconcile kustomization flux-system --with-source
flux get kustomizations | grep notes

Erwartet: vier notes-Kustomizations, alle READY True. Noch ist nichts verschlüsselt, und die Entschlüsselung hat nichts zu tun.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Verschlüsseln

sops --encrypt --in-place apps/notes/base/secret.yaml
sops --encrypt --in-place apps/notes-db/base/secret.yaml
cat apps/notes/base/secret.yaml

Erwartet (gekürzt):

apiVersion: v1
kind: Secret
metadata:
    name: notes-api
    namespace: notes
stringData:
    apiKey: ENC[AES256_GCM,data:xNJQjyyvzrzay/6CAvgo,iv:GV9V//ZCxt9JaYqAc/lLl440RtwdJ2wmxmdIeOfTDng=,tag:SS8jf/kXdr0vDUoh5T4UKQ==,type:str]
sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
            ...
            -----END AGE ENCRYPTED FILE-----
          recipient: age138s6889pax7c4q4tsj9lf0mu5cwela32v34x4apt2setmqm3lpfqk2ajzf
    encrypted_regex: ^(data|stringData)$
    lastmodified: "2026-11-12T16:38:33Z"
    mac: ENC[AES256_GCM,data:SJrw…,type:str]
    version: 3.13.3
  • Unter sops stehen die Metadaten: für wen verschlüsselt wurde (recipient) und eine Prüfsumme (mac). Wer an einem verschlüsselten Wert herumbastelt, fällt beim Entschlüsseln auf.
  • SOPS rückt die Datei mit vier Leerzeichen ein. Für YAML ist das egal.
git commit -am "Secrets verschlüsselt"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-db
flux reconcile kustomization notes
kubectl -n notes get secret notes-db -o jsonpath='{.data.password}' | base64 -d; echo

Erwartet (gekürzt):

✔ applied revision main@sha1:a16d459c9ce778c29560d74ff23aa4c9ff6b2c77
...
lab-db-pass-123

Im Cluster steht Klartext, in Git nur noch ENC[…]. Lesen kannst du die Datei weiterhin, wenn du den privaten Schlüssel hast:

export SOPS_AGE_KEY_FILE=~/flux-lab/age.agekey
sops --decrypt apps/notes/base/secret.yaml | grep apiKey

Erwartet:

    apiKey: lab-api-key-123

Fortschritt speichern? Kostenlos registrieren

Drill 5: Den Schlüssel tauschen

Der alte API-Key steht in der Git-Historie, verschlüsseln ändert daran nichts. Wer das Repo je geklont hat, kennt ihn. Also bekommt notes-api einen neuen. sops set ändert einen Wert, ohne dass du die Datei entschlüsselt auf die Platte schreibst:

sops set apps/notes/base/secret.yaml '["stringData"]["apiKey"]' '"lab-api-key-456"'
git commit -am "notes: neuer API-Key"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes
curl -s -o /dev/null -w '%{http_code}\n' -H "X-API-Key: lab-api-key-456" \
  -d '{"text":"t"}' localhost:30080/notes

Erwartet (gekürzt):

...
401

401 Unauthorized. Das Secret im Cluster ist neu, aber die laufenden Pods haben ihre Umgebungsvariablen beim Start gelesen. Kubernetes startet Pods nicht neu, nur weil sich ein Secret geändert hat.

kubectl -n notes rollout restart deploy/notes
kubectl -n notes rollout status deploy/notes
curl -s -o /dev/null -w '%{http_code}\n' -H "X-API-Key: lab-api-key-456" \
  -d '{"text":"Neuer Schlüssel"}' localhost:30080/notes

Erwartet (gekürzt):

deployment "notes" successfully rolled out
201

rollout restart setzt eine Annotation mit der Uhrzeit am Pod-Template. Die steht nicht in Git, also entfernt Flux sie beim nächsten Abgleich wieder, und das löst einen zweiten, harmlosen Rollout aus. Wie es eleganter geht, steht in der Enterprise-Notiz.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Den age-Schlüssel wechseln

Auch der age-Schlüssel selbst soll nicht ewig leben. Der Wechsel geht in drei Schritten: Neuen Schlüssel erzeugen, Dateien umschlüsseln, alten Schlüssel aus dem Cluster nehmen.

cd ~/flux-lab
age-keygen -o age-2027.agekey
chmod 600 age-2027.agekey
cd fleet
sed -i "s/    age: .*/    age: $(age-keygen -y ../age-2027.agekey)/" .sops.yaml
sops updatekeys -y apps/notes/base/secret.yaml
sops updatekeys -y apps/notes-db/base/secret.yaml

Erwartet (gekürzt):

Public key: age18xtp80985favcrpj3zvtm2rnp80yag3w8aphfsejaq52343tmg9sj4937c
--- age138s6889pax7c4q4tsj9lf0mu5cwela32v34x4apt2setmqm3lpfqk2ajzf
… File /home/ubuntu/flux-lab/fleet/apps/notes/base/secret.yaml synced with new keys
--- age138s6889pax7c4q4tsj9lf0mu5cwela32v34x4apt2setmqm3lpfqk2ajzf
… File /home/ubuntu/flux-lab/fleet/apps/notes-db/base/secret.yaml synced with new keys

updatekeys entschlüsselt mit dem alten Schlüssel (aus SOPS_AGE_KEY_FILE) und verschlüsselt für die Empfänger aus .sops.yaml neu. Die Zeilen mit --- zeigen, welcher Empfänger wegfällt.

Bevor du pushst, braucht der Cluster beide Schlüssel. Sonst könnte Flux die neuen Dateien nicht lesen. kubectl replace tauscht das Secret aus:

kubectl -n flux-system create secret generic sops-age \
  --from-file=age.agekey=../age.agekey \
  --from-file=age-2027.agekey=../age-2027.agekey \
  --dry-run=client -o yaml | kubectl replace -f -
git commit -am "SOPS: neuer age-Schlüssel"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-db
flux reconcile kustomization notes

Erwartet (gekürzt):

secret/sops-age replaced
...
✔ applied revision main@sha1:edb2dff5631d0b3c52139d5cd9e08026511f7713

Jetzt kann der alte Schlüssel raus:

kubectl -n flux-system create secret generic sops-age \
  --from-file=age-2027.agekey=../age-2027.agekey \
  --dry-run=client -o yaml | kubectl replace -f -
flux reconcile kustomization notes
export SOPS_AGE_KEY_FILE=~/flux-lab/age-2027.agekey

Erwartet (gekürzt):

secret/sops-age replaced
...
✔ applied revision main@sha1:edb2dff5631d0b3c52139d5cd9e08026511f7713

Zur Probe: Mit dem alten Schlüssel lässt sich nichts mehr öffnen.

SOPS_AGE_KEY_FILE=~/flux-lab/age.agekey sops --decrypt apps/notes/base/secret.yaml

Erwartet (gekürzt):

Failed to get the data key required to decrypt the SOPS file.

Group 0: FAILED
...

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

grep -c 'ENC\[' apps/notes/base/secret.yaml apps/notes-db/base/secret.yaml

Erwartet:

apps/notes/base/secret.yaml:2
apps/notes-db/base/secret.yaml:2

Pro Datei zwei Treffer: der Wert und die Prüfsumme mac.

kubectl -n flux-system get secret sops-age -o jsonpath='{.data}' | grep -o '"[a-z0-9.-]*":'

Erwartet:

"age-2027.agekey":
flux get kustomizations | grep -c True

Erwartet: 10, alle Kustomizations sind bereit.

Die verschlüsselten Dateien im Begleitcode weichen von deinen ab, denn sie sind mit einem anderen Schlüssel verschlüsselt. Der Vergleich lässt sie deshalb aus:

diff -r -x 'secret*.yaml' -x '.sops.yaml' ~/flux-lab/fleet/apps \
  ~/flux-lab/code/loesung/tag08/apps

Erwartet: keine Ausgabe.

Challenge

notes-helm hat noch einen API-Key im Klartext, direkt im HelmRelease unter values. Bring ihn in ein verschlüsseltes Secret und lass den HelmRelease ihn per valuesFrom lesen. Neuer Wert: lab-helm-key-123.

Hinweis: valuesFrom kann auch ein Secret lesen, standardmäßig den Schlüssel values.yaml. Und die Kustomization notes-helm muss entschlüsseln können.

Lösung

Erst die Kustomization:

sed -i 's/^    name: flux-system$/    name: flux-system\n  decryption:\n    provider: sops\n    secretRef:\n      name: sops-age/' \
  clusters/lab/notes-helm.yaml

Dann das Secret, verschlüsselt:

cat > apps/notes-helm/secret-values.yaml <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: notes-secret-values
  namespace: notes-helm
stringData:
  values.yaml: |
    apiKey: lab-helm-key-123
EOF
sops --encrypt --in-place apps/notes-helm/secret-values.yaml
sed -i 's/  - release.yaml/  - release.yaml\n  - secret-values.yaml/' apps/notes-helm/kustomization.yaml

Im HelmRelease fliegt die Zeile apiKey aus values heraus, und valuesFrom bekommt einen zweiten Eintrag:

  values:
    nodePort: 30090
  valuesFrom:
    - kind: ConfigMap
      name: notes-values
    - kind: Secret
      name: notes-secret-values
git add -A
git commit -m "notes-helm: API-Key verschlüsselt"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helm
kubectl -n notes-helm get secret notes-api -o jsonpath='{.data.apiKey}' | base64 -d; echo

Erwartet (gekürzt):

...
lab-helm-key-123

Ein Secret, das kein Kustomize-Generator erzeugt, hat keinen Hash im Namen. Eine nameReference wie in Tag 6 brauchst du hier nicht.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Cloud-KMS statt age: SOPS kann statt mit age mit AWS KMS, Azure Key Vault, GCP KMS oder HashiCorp Vault verschlüsseln. Dann liegt kein privater Schlüssel im Cluster, der kustomize-controller fragt per Workload Identity den KMS. Wer Zugriff hat, regelt die Cloud-IAM.
  • Neustarts nach Secret-Änderungen: Entweder ein Werkzeug wie Stakater Reloader, das Deployments bei geänderten Secrets neu startet. Oder Kustomizes secretGenerator mit Hash im Namen: Ein neuer Wert ergibt einen neuen Namen, und das Deployment rollt von selbst neu aus. Flux entschlüsselt auch SOPS-Dateien, die ein Generator liest.
  • Alternativen: Wer Secrets nicht in Git haben will, holt sie mit dem External Secrets Operator aus einem Tresor wie OpenBao (siehe „OpenBao-Secrets zum Anfassen“). In Git steht dann nur ein Verweis.