Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 10: Secrets mit SOPS

Ziel: Im Fleet-Repo steht kein Passwort mehr im Klartext. SOPS verschlüsselt die Secrets mit age, und der repo-server von Argo CD entschlüsselt sie beim Rendern. · Dauer: ca. 50 min · Voraussetzung: Tag 9

Briefing

  • Seit Tag 2 stehen der API-Key und seit Tag 4 das Datenbank-Passwort im Klartext im Repo. Wer das Repo lesen kann, kennt beide.
  • age ist ein kleines Verschlüsselungsprogramm. Ein Schlüsselpaar besteht aus einem öffentlichen Schlüssel (age1…) zum Verschlüsseln und einer privaten Datei zum Entschlüsseln.
  • SOPS verschlüsselt in einer YAML-Datei nur die Werte, nicht die Schlüssel. Die Datei bleibt lesbar, ein Diff zeigt, welches Feld sich geändert hat.
  • KSOPS ist ein Kustomize-Plugin. Es ruft SOPS beim kustomize build auf. Damit der repo-server es nutzen kann, braucht er das Programm, den privaten Schlüssel und zwei zusätzliche Optionen für Kustomize.
  • Der private Schlüssel kommt nie ins Repo. Er liegt auf deiner VM und als Secret im Namespace argocd.
 Fleet-Repo                       repo-server                          Cluster
 db-secret.enc.yaml  ──►  kustomize build ─► ksops ─► sops  ──►  Secret notes-db
 (password: ENC[…])                                 ▲              (Klartext in etcd)
                                    Secret sops-age ┘ privater Schlüssel

Drill 1: Klartext im Repo

cd ~/argo-lab/argocd-fleet
git grep -n "lab-" -- apps

Erwartet:

apps/notes/base/db-secret.yaml:8:  password: lab-db-pw-123
apps/notes/base/secret.yaml:6:  apiKey: lab-api-key-123

Auch wenn du beide Dateien jetzt verschlüsselst: In der Git-Historie bleiben die alten Stände lesbar. Im Betrieb heißt das, die Passwörter nach dem Verschlüsseln zu ändern.

Fortschritt speichern? Kostenlos registrieren

Drill 2: SOPS und age

Beide Programme kommen wie argocd nach ~/.local/bin:

curl -sLo ~/.local/bin/sops \
  https://github.com/getsops/sops/releases/download/v3.13.3/sops-v3.13.3.linux.amd64
chmod +x ~/.local/bin/sops
AGE_URL=https://github.com/FiloSottile/age/releases/download/v1.3.2
curl -sL $AGE_URL/age-v1.3.2-linux-amd64.tar.gz \
  | tar xz -C ~/.local/bin --strip-components=1 age/age age/age-keygen
sops --version --disable-version-check
age --version

Erwartet:

sops 3.13.3
v1.3.2

Ohne --disable-version-check fragt sops --version im Netz nach einer neueren Version und hängt eine lange Warnung an.

Jetzt das Schlüsselpaar:

age-keygen -o ~/argo-lab/age.key
ls -l ~/argo-lab/age.key

Erwartet:

Public key: age1cmppn2qlaapjw63t45skvazp5vsex5u7vf0l720lr5txfh9aq3dqattlrl
-rw------- 1 ubuntu ubuntu 184 Nov 14 20:28 /home/ubuntu/argo-lab/age.key

Dein öffentlicher Schlüssel ist ein anderer. Die Datei enthält beide Schlüssel und ist nur für dich lesbar. Geht sie verloren, kann niemand die Secrets mehr entschlüsseln.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Verschlüsseln

SOPS liest seine Regeln aus .sops.yaml im Repo. Die Regel sagt: Dateien auf .enc.yaml werden mit deinem öffentlichen Schlüssel verschlüsselt, und zwar nur die Felder unter data und stringData:

AGE_PUB=$(age-keygen -y ~/argo-lab/age.key)
cat > .sops.yaml <<EOF
creation_rules:
  - path_regex: \.enc\.yaml$
    encrypted_regex: ^(data|stringData)$
    age: $AGE_PUB
EOF
cat .sops.yaml

Erwartet:

creation_rules:
  - path_regex: \.enc\.yaml$
    encrypted_regex: ^(data|stringData)$
    age: age1cmppn2qlaapjw63t45skvazp5vsex5u7vf0l720lr5txfh9aq3dqattlrl

Diesmal steht EOF ohne Anführungszeichen, damit die Shell $AGE_PUB einsetzt.

Die beiden Secrets bekommen die neue Endung und werden an Ort und Stelle verschlüsselt:

git mv apps/notes/base/db-secret.yaml apps/notes/base/db-secret.enc.yaml
git mv apps/notes/base/secret.yaml apps/notes/base/secret.enc.yaml
sops encrypt -i apps/notes/base/db-secret.enc.yaml
sops encrypt -i apps/notes/base/secret.enc.yaml
cat apps/notes/base/db-secret.enc.yaml

Erwartet (gekürzt):

apiVersion: v1
kind: Secret
metadata:
    name: notes-db
    annotations:
        argocd.argoproj.io/sync-wave: "-1"
stringData:
    password: ENC[AES256_GCM,data:whGUA6jPZCci+cXANg==,iv:9Oqu…,tag:c3SG…,type:str]
sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
            …
            -----END AGE ENCRYPTED FILE-----
          recipient: age1cmppn2qlaapjw63t45skvazp5vsex5u7vf0l720lr5txfh9aq3dqattlrl
    encrypted_regex: ^(data|stringData)$
    lastmodified: "2026-11-14T20:28:39Z"
    mac: ENC[AES256_GCM,data:+/Sy…,type:str]
    version: 3.13.3
  • Name, Annotation und Typ bleiben lesbar. Nur das Passwort ist verschlüsselt.
  • Der Block sops enthält den Datenschlüssel, verschlüsselt mit deinem öffentlichen Schlüssel, und eine Prüfsumme (mac) über die ganze Datei. Wer ein Feld von Hand ändert, macht die Datei unbrauchbar.
  • SOPS rückt mit vier Leerzeichen ein. Das ist gültiges YAML.

Zum Entschlüsseln braucht SOPS den privaten Schlüssel:

sops decrypt apps/notes/base/db-secret.enc.yaml

Erwartet (gekürzt):

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

Group 0: FAILED
  age1cmppn2qlaapjw63t45skvazp5vsex5u7vf0l720lr5txfh9aq3dqattlrl: FAILED
…

SOPS sucht den Schlüssel unter anderem in der Variablen SOPS_AGE_KEY_FILE:

export SOPS_AGE_KEY_FILE=~/argo-lab/age.key
sops decrypt apps/notes/base/db-secret.enc.yaml

Erwartet:

apiVersion: v1
kind: Secret
metadata:
    name: notes-db
    annotations:
        argocd.argoproj.io/sync-wave: "-1"
stringData:
    password: lab-db-pw-123

Damit export jede neue Sitzung überlebt, hängst du die Zeile an ~/.bashrc an:

echo 'export SOPS_AGE_KEY_FILE=~/argo-lab/age.key' >> ~/.bashrc

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der KSOPS-Generator

Die verschlüsselten Dateien darf Kustomize nicht mehr als resources lesen. Sonst landet ENC[…] als Passwort im Cluster. Stattdessen nennt ein Generator sie, und KSOPS entschlüsselt sie:

cat > apps/notes/base/secret-generator.yaml <<'EOF'
apiVersion: viaduct.ai/v1
kind: ksops
metadata:
  name: notes-secrets
  annotations:
    config.kubernetes.io/function: |
      exec:
        path: ksops
files:
  - ./secret.enc.yaml
  - ./db-secret.enc.yaml
EOF

In der kustomization.yaml fallen die beiden Secrets aus resources weg, dafür kommt generators dazu. Die ganze Datei:

cat > apps/notes/base/kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
generators:
  - secret-generator.yaml
resources:
  - db-pvc.yaml
  - db-deployment.yaml
  - db-service.yaml
  - migrate-job.yaml
  - deployment.yaml
  - service.yaml
  - smoke-job.yaml
EOF
git add -A
git status --short

Erwartet:

A  .sops.yaml
A  apps/notes/base/db-secret.enc.yaml
D  apps/notes/base/db-secret.yaml
M  apps/notes/base/kustomization.yaml
A  apps/notes/base/secret-generator.yaml
A  apps/notes/base/secret.enc.yaml
D  apps/notes/base/secret.yaml

Der repo-server kann KSOPS noch nicht. Was passiert, wenn du trotzdem pushst?

git commit -m "notes: Secrets mit SOPS verschlüsselt"
git push
argocd app get notes --refresh
sleep 10
argocd app get notes | grep -E "Sync Status|Health Status"
kubectl -n argocd get app notes -o jsonpath='{.status.conditions[0].message}'

Erwartet (gekürzt):

Sync Status:        Unknown
Health Status:      Healthy
Failed to load target state: … loading generator plugins: failed to load generator: external plugins disabled; unable to load external plugin 'ksops'

Ausprobiert: ComparisonError, aber nichts geht kaputt. Argo CD kann den Sollzustand nicht berechnen und synchronisiert deshalb gar nicht. Die Secrets im Cluster bleiben, wie sie sind, notes läuft weiter. Gleiches gilt für notes-dev.

Fortschritt speichern? Kostenlos registrieren

Drill 5: KSOPS im repo-server

Zuerst kommt der private Schlüssel als Secret in den Namespace argocd:

kubectl -n argocd create secret generic sops-age \
  --from-file=keys.txt=$HOME/argo-lab/age.key

Erwartet:

secret/sops-age created

Dann bekommt das Deployment argocd-repo-server einen Patch:

  • Ein Init-Container aus dem KSOPS-Image legt das Programm ksops in ein leeres Volume. Das Image enthält keine Shell, deshalb erledigt ksops install das Kopieren selbst.
  • Der repo-server sieht die Datei als /usr/local/bin/ksops.
  • Der Schlüssel liegt unter /sops-age, SOPS_AGE_KEY_FILE zeigt darauf.
mkdir -p ~/argo-lab/tag10
cd ~/argo-lab/tag10
cat > repo-server-ksops.yaml <<'EOF'
spec:
  template:
    spec:
      volumes:
        - name: custom-tools
          emptyDir: {}
        - name: sops-age
          secret:
            secretName: sops-age
      initContainers:
        - name: install-ksops
          image: viaductoss/ksops:v4.5.1
          command: ["/usr/local/bin/ksops", "install", "/custom-tools"]
          volumeMounts:
            - name: custom-tools
              mountPath: /custom-tools
      containers:
        - name: argocd-repo-server
          env:
            - name: SOPS_AGE_KEY_FILE
              value: /sops-age/keys.txt
          volumeMounts:
            - name: custom-tools
              mountPath: /usr/local/bin/ksops
              subPath: ksops
            - name: sops-age
              mountPath: /sops-age
EOF
kubectl -n argocd patch deploy argocd-repo-server --patch-file repo-server-ksops.yaml
kubectl -n argocd rollout status deploy argocd-repo-server --timeout 180s
kubectl -n argocd logs deploy/argocd-repo-server -c install-ksops

Erwartet (gekürzt):

deployment.apps/argocd-repo-server patched
…
deployment "argocd-repo-server" successfully rolled out
Found 2 pods, using pod/argocd-repo-server-67467f859b-hndsr
installed /custom-tools/ksops

Kustomize führt fremde Programme nur aus, wenn man es ausdrücklich erlaubt. Die Optionen dafür stehen in argocd-cm:

kubectl -n argocd patch cm argocd-cm --type merge \
  -p '{"data":{"kustomize.buildOptions":"--enable-alpha-plugins --enable-exec"}}'

Erwartet:

configmap/argocd-cm patched

Jetzt rechnet Argo CD neu. --hard-refresh verwirft dabei auch den Cache des repo-servers:

argocd app get notes --hard-refresh
sleep 15
argocd app get notes | sed -n "/GROUP/,\$p"

Erwartet (gekürzt):

GROUP  KIND                   NAMESPACE  NAME           STATUS     HEALTH   HOOK      MESSAGE
       Secret                 notes      notes-db       Synced                        secret/notes-db configured
       PersistentVolumeClaim  notes      notes-db       Synced     Healthy            persistentvolumeclaim/notes-db unchanged
…
       Secret                 notes      notes-api      Synced                        secret/notes-api configured
…

configured statt unchanged, weil KSOPS die Werte als data statt stringData liefert. Der Inhalt ist derselbe:

kubectl -n notes get secret notes-db -o jsonpath='{.data.password}' | base64 -d; echo
argocd app diff notes
echo $?
curl -s localhost:30080/notes

Erwartet:

lab-db-pw-123
0
[{"id":"3fef3430-d55d-431b-bad7-c314189bd7a9","text":"Hallo Argo CD"}]

Kein Diff, die Datenbank läuft mit demselben Passwort weiter. Wie in Tag 2 zeigen argocd app manifests und die Weboberfläche Secret-Werte nur als ++++++++, auch die entschlüsselten.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

git -C ~/argo-lab/argocd-fleet grep -c "lab-" -- apps

Erwartet: keine Ausgabe. Im Repo steht kein Passwort mehr im Klartext.

argocd app list -o name
argocd app get notes-dev | grep "Sync Status"

Erwartet: vier Applications, notes-dev ist Synced.

kubectl -n argocd get deploy argocd-repo-server \
  -o jsonpath='{.spec.template.spec.initContainers[0].image}'

Erwartet: viaductoss/ksops:v4.5.1.

Challenge

Ändere den API-Key von notes auf lab-api-key-456, ohne die Datei zu entschlüsseln oder einen Editor zu öffnen. Prüfe danach mit curl, welcher Key gilt.

Hinweis: sops set ändert einen einzelnen Wert. Und eine Umgebungsvariable liest ein Container nur beim Start.

Lösung

cd ~/argo-lab/argocd-fleet
sops set apps/notes/base/secret.enc.yaml '["stringData"]["apiKey"]' '"lab-api-key-456"'
git diff --stat
git commit -am "notes: neuer API-Key"
git push
argocd app get notes --refresh
sleep 15
kubectl -n notes get secret notes-api -o jsonpath='{.data.apiKey}' | base64 -d; echo
curl -s -o /dev/null -w "%{http_code}\n" -H "X-API-Key: lab-api-key-456" \
  -d '{"text":"neuer Key"}' localhost:30080/notes

Erwartet (gekürzt):

 apps/notes/base/secret.enc.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
…
lab-api-key-456
401

Das Secret ist neu, notes-api kennt aber noch den alten Key. Erst ein Neustart liest ihn:

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 Key"}' localhost:30080/notes
curl -s -o /dev/null -w "%{http_code}\n" -H "X-API-Key: lab-api-key-123" \
  -d '{"text":"alter Key"}' localhost:30080/notes
argocd app get notes | grep "Sync Status"

Erwartet (gekürzt):

deployment.apps/notes restarted
…
deployment "notes" successfully rolled out
201
401
Sync Status:        Synced to main (9e6ea8e)
  • sops set verschlüsselt den neuen Wert sofort. Im Diff ändern sich der Wert, mac und lastmodified.
  • rollout restart setzt eine Annotation am Pod-Template. Sie steht nicht in Git und zählt deshalb nicht als Drift.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Der Patch am repo-server ist eine Änderung von Hand an der Installation. Ob er ein Upgrade übersteht, prüfst du in Tag 14. Im Betrieb steht er in den Helm-Werten oder in einem Kustomize-Overlay für Argo CD.
  • Statt eines age-Schlüssels pro Cluster nehmen Firmen oft einen Cloud-KMS. SOPS kann AWS KMS, GCP KMS, Azure Key Vault und Vault Transit. Dann braucht der repo-server Zugang zum KMS statt einer Schlüsseldatei.
  • Mehrere Empfänger sind üblich: der Cluster und ein Notfall-Schlüssel im Tresor. sops updatekeys verschlüsselt vorhandene Dateien für neue Empfänger.
  • Damit Pods geänderte Secrets ohne Handarbeit lesen, hängt man einen Hash des Secrets ans Pod-Template oder nutzt einen Controller wie Reloader.
  • Andere Wege zum selben Ziel: Sealed Secrets verschlüsselt für einen Controller im Cluster, der External Secrets Operator holt Werte aus einem Tresor.