Tag 14: Fehlerbilder
Ziel: Acht typische Pannen mit sops und Sealed Secrets erkennst du an ihrer Meldung, findest die Ursache in einem Befehl und behebst sie, ohne Werte zu verlieren. · Dauer: ca. 75 min · Voraussetzung: Tag 13
Briefing
- Fast jede Meldung von sops nennt die Stelle: MAC (Datei als Ganzes), AES_GCM (ein einzelner Wert), Group 0: FAILED (Schlüssel) oder metadata not found (keine sops-Datei).
- Bei Schlüsselfehlern listet sops jeden Recipient der Datei mit seinem Ergebnis. Lies die Liste – sie sagt dir, welcher Schlüssel gebraucht würde.
- Sealed Secrets kennt im Kern eine Meldung: no key could decrypt secret. Die Ursache ist entweder der Scope (Tag 12) oder ein fremder bzw. fehlender Schlüssel (Tag 13).
- Geübt wird in einem eigenen Klon
~/sops/tag14/klon, aus dem nichts gepusht wird. Dein Haupt-Klon und Forgejo bleiben sauber. - Jedes Fehlerbild folgt dem Muster Einbauen → Symptom → Untersuchen → Ursache → Fix → Nachweis.
| Meldung | Ebene | Tag |
|---|---|---|
MAC mismatch |
Datei | 3, Drill 2 hier |
Could not decrypt with AES_GCM |
Wert | Drill 1 hier |
Group 0: FAILED |
Schlüssel | 4, 5, Drill 4/5 hier |
no key could decrypt secret |
Sealed Secrets | 12, 13, Drill 7 hier |
Drill 1: Hand am verschlüsselten Wert
Einbauen: Ein Klon zum Üben, dann ein „kleiner
Tippfehler“ in einem ENC[…]-Wert – etwa beim Auflösen eines
Konflikts von Hand.
# auf argo
mkdir -p ~/sops/tag14 && cd ~/sops/tag14
git clone -q http://172.16.0.182:30300/lab/secrets.git klon
cd klon
git config core.hooksPath hooks
sed -i 's/password: ENC\[AES256_GCM,data:./password: ENC[AES256_GCM,data:A/' \
dev/notes-db.yamlSymptom:
# auf argo
cd ~/sops/tag14/klon
sops decrypt dev/notes-db.yaml 2>&1 | tail -1Erwartet (Zeile umbrochen):
Error decrypting tree: Error walking tree: Could not decrypt value: Could not decrypt
with AES_GCM: cipher: message authentication failed
Untersuchen und Ursache: git diff zeigt
die geänderte Zeile. AES-GCM schützt jeden Wert mit einer eigenen
Prüfsumme; ein einziges geändertes Zeichen, und der Wert ist nicht mehr
zu öffnen. Retten lässt er sich nicht – nur aus Git zurückholen.
Fix und Nachweis:
# auf argo
cd ~/sops/tag14/klon
git diff --stat
git checkout -q dev/notes-db.yaml
sops decrypt --extract '["metadata"]["name"]' dev/notes-db.yamlErwartet:
dev/notes-db.yaml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
notes-db
Fortschritt speichern? Kostenlos registrieren
Drill 2: Klartext daneben geändert
Einbauen: Jemand zieht das Secret in einen anderen
Namespace um – mit sed, weil metadata ja
lesbar ist.
# auf argo
cd ~/sops/tag14/klon
sed -i 's/namespace: notes-dev/namespace: notes-qa/' dev/notes-db.yaml
sops decrypt dev/notes-db.yaml 2>&1 | cut -c1-40Erwartet:
MAC mismatch. File has 66C57B21830010AFB
Ursache: Der MAC deckt alle Werte ab, auch die unverschlüsselten (Tag 3). Jede Änderung am Klartext außerhalb von sops bricht ihn.
Fix: Die Änderung ist gewollt – also mit
--ignore-mac entschlüsseln und neu verschlüsseln. Das
berechnet den MAC über den neuen Stand.
# auf argo
cd ~/sops/tag14/klon
sops decrypt --ignore-mac dev/notes-db.yaml \
| sops encrypt --filename-override dev/notes-db.yaml /dev/stdin \
> ~/sops/tag14/fix.yaml
mv ~/sops/tag14/fix.yaml dev/notes-db.yaml
sops decrypt --extract '["metadata"]["namespace"]' dev/notes-db.yaml
git checkout -q dev/notes-db.yamlErwartet:
notes-qa
Tipp:
--ignore-macheißt: „Ich weiß, wer die Datei geändert hat.“ Bei einer Datei aus fremder Hand ist ein MAC-Fehler ein Alarmzeichen, kein Ärgernis.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Merge-Konflikt
Einbauen: Zwei Branches ändern verschiedene Werte derselben Datei.
# auf argo
cd ~/sops/tag14/klon
git switch -q -c pw
sops set dev/notes-db.yaml '["data"]["password"]' "\"$(printf lab-db-pw-1 | base64)\""
git commit -q -am "Passwort"
git switch -q main && git switch -q -c user
sops set dev/notes-db.yaml '["data"]["user"]' "\"$(printf notes | base64)\""
git commit -q -am "Benutzer"
git merge -q pw 2>&1 | grep CONFLICTErwartet:
CONFLICT (content): Merge conflict in dev/notes-db.yaml
Symptom und Untersuchen:
# auf argo
cd ~/sops/tag14/klon
grep -c '^<<<<<<<' dev/notes-db.yaml
sops decrypt dev/notes-db.yaml 2>&1 | tail -1Erwartet:
2
yaml: line 3: could not find expected ':'
Ursache: Beide Seiten haben
lastmodified und mac geändert, dazu ihre
Werte. Git kann das nicht zusammenführen, und von Hand geht es nicht
(Drill 1).
Fix: Eine Seite ganz übernehmen und die Änderung der
anderen mit sops nachziehen. git show :3:datei ist „ihre“
Version, /dev/stdin mit --filename-override
liest sie, ohne sie auf die Platte zu schreiben.
# auf argo
cd ~/sops/tag14/klon
git checkout --ours dev/notes-db.yaml
diff <(git show :3:dev/notes-db.yaml \
| sops decrypt --filename-override dev/notes-db.yaml /dev/stdin) \
<(sops decrypt dev/notes-db.yaml)
P=$(git show :3:dev/notes-db.yaml | sops decrypt \
--filename-override dev/notes-db.yaml --extract '["data"]["password"]' /dev/stdin)
sops set dev/notes-db.yaml '["data"]["password"]' "\"$P\""
git add dev/notes-db.yaml && git commit -q -m "Merge pw"Erwartet (gekürzt):
Updated 1 path from the index
3c3,4
< password: bGFiLWRiLXB3LTE=
---
> password: bGFiLWRiLWRldi05OTk=
> user: bm90ZXM=
Nachweis:
# auf argo
cd ~/sops/tag14/klon
sops decrypt dev/notes-db.yaml | yq '.data | map_values(@base64d)'
git switch -q mainErwartet:
password: lab-db-pw-1
user: notes
Tipp: Weniger Konflikte entstehen, wenn jedes Secret eine eigene Datei hat und Branches kurz leben. Ein Merge-Treiber für sops existiert nicht im Projekt selbst.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Recipient nur in
.sops.yaml
Einbauen: Die Kollegin (Tag 5) soll
dev/ lesen. Jemand trägt sie in die Regel ein – und
committet.
# auf argo
cd ~/sops/tag14/klon
K=$(age-keygen -y ~/sops/tag01/kollegin.key)
yq -i '(.creation_rules[] | select(.path_regex == "^dev/.*\\.yaml$")).age
+= ",'"$K"'"' .sops.yamlSymptom: Die Kollegin kann trotzdem nicht lesen.
# auf argo
cd ~/sops/tag14/klon
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag01/kollegin.key \
sops decrypt dev/notes-db.yaml 2>&1 | grep -E 'Group|FAILED'Erwartet (gekürzt):
Group 0: FAILED
age1rnz4tqupd0f3lm4kfs564cfgys5j80497rk7ajzn2ekxh3d2g3uqdtdnv2: FAILED
age1ymx7x29j3nctlanp5kwt76xve66dc0dm4lpklcq5jykxr7vq55fsmhu7ts: FAILED
Untersuchen und Ursache: Die Liste zeigt die
Recipients der Datei – dein Schlüssel und der von Argo
CD. Die Kollegin fehlt, denn .sops.yaml wirkt nur beim
Verschlüsseln und bei updatekeys.
Fix und Nachweis:
# auf argo
cd ~/sops/tag14/klon
sops updatekeys -y dev/notes-db.yaml 2>&1 | tail -1 | cut -c21-
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag01/kollegin.key \
sops decrypt --extract '["metadata"]["name"]' dev/notes-db.yaml
git checkout -q .Erwartet:
File /home/ubuntu/sops/tag14/klon/dev/notes-db.yaml synced with new keys
notes-db
Fortschritt speichern? Kostenlos registrieren
Drill 5: Welcher Schlüssel fehlt?
Einbauen: Ben (Tag 6) will
prod/notes-db.yaml lesen.
# auf argo
cd ~/sops/tag14/klon
env -u VAULT_TOKEN XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag06/ben.key \
sops decrypt prod/notes-db.yaml 2>&1 | grep -E 'FAILED|Code'Erwartet:
Group 0: FAILED
age1r025nv6kv083tjhqa7xpslvkc0m8qm2jljd0aqn55nzr859xqe7q4798ks: FAILED
http://172.16.0.182:30820/v1/transit/keys/sops: FAILED
| Code: 403. Errors:
Untersuchen und Ursache: Zwei Wege öffnen die Datei:
der prod-Schlüssel age1r025… und Transit. Ben hat keinen
von beiden, und ohne Token sagt OpenBao 403. Welcher Schlüssel welcher
ist, verrät age-keygen -y:
# auf argo
for k in ~/sops/tag04/prod.key ~/sops/tag06/ben.key; do
echo "$(basename $k): $(age-keygen -y $k | cut -c1-12)…"
doneErwartet:
prod.key: age1r025nv6k…
ben.key: age1z32l8zxd…
Fix: Kein technischer – das ist eine
Berechtigungsfrage. Soll Ben prod lesen, kommt sein Schlüssel in die
prod-Regel und updatekeys läuft (Drill 4). Soll er nicht,
ist die Meldung genau richtig.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Keine sops-Datei – oder schon eine
Zwei Meldungen, die verwirren, weil sie das Gegenteil des Erwarteten sagen.
# auf argo
cd ~/sops/tag14/klon
printf 'a: 1\n' > ~/sops/tag14/klar.yaml
sops decrypt ~/sops/tag14/klar.yaml 2>&1 | tail -1
sops encrypt dev/notes-db.yaml 2>&1 | head -1Erwartet:
sops metadata not found
The file you have provided contains a top-level entry called 'sops', or for
Ursache: metadata not found – die Datei
ist gar nicht verschlüsselt (oder der Block sops: fehlt,
etwa nach einem Copy-and-paste nur der Werte). Die zweite Meldung: Die
Datei ist schon verschlüsselt; sops verweigert das doppelte
Verschlüsseln und schlägt sops edit vor.
Fix: Mit sops filestatus vorher prüfen,
statt zu raten:
# auf argo
sops filestatus ~/sops/tag14/klar.yaml
sops filestatus ~/sops/tag14/klon/dev/notes-db.yamlErwartet:
{"encrypted":false}
{"encrypted":true}
Fortschritt speichern? Kostenlos registrieren
Drill 7: SealedSecret aus dem falschen Cluster
Einbauen: Ein Kollege versiegelt mit dem Zertifikat „seines“ Clusters. Hier simuliert ein selbst erzeugtes Zertifikat den fremden Cluster.
# auf argo
cd ~/sops/tag14
openssl req -x509 -newkey rsa:4096 -nodes -keyout fremd.key -out fremd.pem \
-days 30 -subj "/CN=anderer-cluster" 2>/dev/null
kubectl create secret generic falsch -n notes-stage --from-literal=x=lab-x-123 \
--dry-run=client -o yaml | kubeseal --cert fremd.pem -o yaml > falsch.sealed.yaml
kubectl apply -f falsch.sealed.yaml
sleep 3Symptom:
# auf argo
kubectl -n notes-stage get sealedsecret falsch \
-o jsonpath='{.status.conditions[0].message}'; echoErwartet:
no key could decrypt secret (x)
Untersuchen: Dieselbe Meldung wie beim falschen
Scope (Tag 12). Erkennen lässt sich das schon vor dem Merge –
kubeseal --validate fragt den Controller:
# auf argo
cd ~/sops/tag14
kubeseal --validate < falsch.sealed.yaml; echo "rc=$?"
kubeseal --validate < ~/sops/repo/sealed/notes-stage/notes-db.sealed.yaml; echo "rc=$?"Erwartet:
error: unable to decrypt sealed secret: falsch
rc=1
rc=0
Ursache und Fix: Falsches Zertifikat. Neu versiegeln
mit kubeseal --fetch-cert dieses Clusters (bzw. dem
cert.pem aus dem Repo).
# auf argo
cd ~/sops/tag14
kubectl delete -f falsch.sealed.yaml
shred -u fremd.key && rm fremd.pem falsch.sealed.yamlErwartet:
sealedsecret.bitnami.com "falsch" deleted from notes-stage namespace
Fortschritt speichern? Kostenlos registrieren
Drill 8: Mein Wert verschwindet
Einbauen und Symptom: Schnell-Fix in der Nacht – das Passwort direkt im Secret ändern und gleich nachsehen.
# auf argo
kubectl -n notes-stage patch secret notes-db -p '{"stringData":{"password":"von-hand"}}'
kubectl -n notes-stage get secret notes-db -o jsonpath='{.data.password}' \
| base64 -d; echoErwartet:
secret/notes-db patched
lab-db-stage-456
Der Patch wurde angenommen – und der alte Wert steht trotzdem schon wieder da.
Ursache: Das Secret gehört dem SealedSecret
(ownerReferences, Tag 12). Der Controller beobachtet seine
Secrets und stellt den versiegelten Stand wieder her. Genauso arbeiten
Flux und Argo CD mit Self-Heal: Die Quelle der Wahrheit ist Git.
Fix: Der Weg über Git – neu versiegeln mit
--merge-into (Tag 12), committen, anwenden. Für den Notfall
ohne Git: das SealedSecret vorübergehend löschen
(--cascade=orphan lässt das Secret stehen) und das Secret
dann von Hand pflegen – und das im Ticket festhalten.
Fortschritt speichern? Kostenlos registrieren
Übung: Speed-Drills
Ordne jede Meldung in höchstens 10 Sekunden einer Ursache zu:
MAC mismatch. File has …, computed …Could not decrypt with AES_GCM: cipher: message authentication failedGroup 0: FAILEDmit genau den Schlüsseln aus.sops.yaml– nur nicht deinemno key could decrypt secret (password)direkt nach einem Umbenennensops metadata not found
Lösung
- Klartext außerhalb von sops geändert (Drill 2).
- Ein
ENC[…]-Wert ist beschädigt, meist von Hand (Drill 1). - Du bist nicht Recipient der Datei (Drill 4/5) –
.sops.yamlsagt nichts über die Datei selbst. - Scope
strict, Name oder Namespace geändert (Tag 12). - Datei ist nicht (mehr) verschlüsselt (Drill 6).
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
# auf argo
cd ~/sops/tag14/klon && git status -s | wc -l
git log --oneline origin/main..user | wc -l
kubectl get sealedsecrets -n notes-stage --no-headers | awk '{print $1, $2}'Erwartet:
0
3
notes-api True
notes-db True
regcred True
Der Klon hat nur lokale Commits (Branch user mit dem
aufgelösten Merge), nichts davon liegt in Forgejo.
Challenge
Eine Datei ist kaputt, aber du weißt nicht, wie:
~/sops/tag14/raetsel.yaml. Bau sie dir selbst – kopiere
dev/neu.yaml aus dem Klon und ändere darin
eine zufällige Zeile, ohne nachzusehen, welche (z. B.
per sed mit einer Zufallszahl). Finde mit
sops decrypt und den Meldungen aus diesem Tag heraus,
welche Art von Schaden es ist.
Hinweis: shuf -i 1-20 -n 1 liefert eine
Zufallszahl.
Lösung
# auf argo
cd ~/sops/tag14
cp klon/dev/neu.yaml raetsel.yaml
N=$(shuf -i 1-20 -n 1)
sed -i "${N}s/[a-z]/X/" raetsel.yaml
sops decrypt raetsel.yaml >/dev/null 2>fehler.txt; echo "rc=$?"
grep -oE 'MAC mismatch|AES_GCM|metadata not found|yaml: .*|Failed to get the data key' \
fehler.txt | head -1Erwartet (je nach Zeile eine davon, oder
rc=0):
rc=1
MAC mismatch
rc=0 heißt: Die Zeile lag in einem Teil, den sops nicht
prüft (ein Kommentar in den Metadaten oder die Schreibweise eines
Schlüssels im sops-Block, die keinen Wert ändert) – dann
noch einmal. AES_GCM = ein ENC[…]-Wert;
MAC mismatch = Klartext;
Failed to get the data key = der Block
sops.age ist beschädigt.
Fortschritt speichern? Kostenlos registrieren
Aufräumen
# auf argo
rm -rf ~/sops/tag14
cd ~/sops/repo && git status -sb | head -1Erwartet:
## main...origin/main
Der Haupt-Klon ist unverändert. Controller, notes-stage
und alle Schlüssel bleiben für Tag 15.
Interview-Notiz
- sops sagt
MAC mismatch– was ist passiert? Jemand hat die Datei außerhalb von sops geändert, meist den Klartext. Wenn gewollt:--ignore-macentschlüsseln und neu verschlüsseln; wenn nicht: als Manipulation behandeln. - Wie löst du einen Merge-Konflikt in einer sops-Datei? Eine
Seite übernehmen, die Änderung der anderen mit
sops setnachziehen. Nie dieENC[…]-Zeilen von Hand mischen. - Ich habe den Recipient in
.sops.yamleingetragen, warum geht es nicht?updatekeysfehlt.
Enterprise-Notiz
- CI prüft jede sops-Datei:
sops filestatus(verschlüsselt?) und ein Entschlüsselungsversuch mit dem CI-Schlüssel – das findet kaputte MACs vor dem Merge. - Für SealedSecrets dasselbe mit
kubeseal --validategegen den Ziel-Cluster. - Kurze Branches und eine Datei pro Secret halten Merge-Konflikte selten.
- Runbook pro Meldung (wie die Tabelle oben) spart in der Nacht die meiste Zeit.