PKR-Lab

d0050 - k3s Secrets-Encryption-at-Rest + Audit-Log (Security-Härtung Phase 4)

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/d-sicherheit/d0050-secrets-encryption-audit-log.md

k3s Secrets-Encryption-at-Rest + Audit-Log (Security-Härtung Phase 4)

Detail-Doku zu Phase 4 aus capulus-core/d-sicherheit/d0010-security-hardening-roadmap.md.

Status (13.08.2026): Fertig, live und verifiziert. Rollout
durchgeführt: Config ausgerollt, Datastore-Backup (tar bei gestopptem
Dienst), zwei kontrollierte Neustarts, rotate-keys bis
reencrypt_finished. Verifiziert:


Ziel

Sealed Secrets (d-sicherheit/) verschlüsselt nur den Git-Zustand — der
private Schlüssel, mit dem der sealed-secrets-controller sie beim
Cluster-Sync entschlüsselt, landet als Klartext-Secret im
k3s-Datastore (/var/lib/rancher/k3s/server/db/state.db, SQLite). Jeder,
der Lesezugriff auf diese Datei bekommt (z. B. durch physischen
Server-Zugriff oder eine Sicherheitslücke im k3s-Prozess selbst), sieht
alle Secrets im Klartext — unabhängig von Sealed Secrets.

--secrets-encryption löst das auf Layer der etcd/SQLite-Persistenz:
Secrets werden vor dem Schreiben auf Platte verschlüsselt, der
Schlüssel liegt separat unter /var/lib/rancher/k3s/server/cred/encryption-config.json.

Zusätzlich, im selben Rutsch: Audit-Log für den kube-apiserver — bislang
gibt es keine Nachvollziehbarkeit, wer wann welche Kubernetes-Ressource
angelegt/geändert/gelöscht hat.


Design-Entscheidungen

k3s-Version und CLI-Workflow

Cluster läuft v1.36.3+k3s1 (deutlich über der v1.28-Schwelle, ab der
k3s den modernen rotate-keys-Befehl anbietet). Der alte
prepare → rotate → reencrypt-Dreischritt (so ursprünglich in
capulus-core/d-sicherheit/d0010-security-hardening-roadmap.md skizziert) ist für diese Version deprecated — hier bewusst
durch den modernen Weg ersetzt:

sudo k3s secrets-encrypt status   # vorher: Enabled/Disabled?
# Config-Flag setzen + restart (siehe Rollout unten)
sudo k3s secrets-encrypt status   # danach: "Enabled" — NEUE Secrets verschlüsselt,
                                   # bestehende noch nicht
sudo k3s secrets-encrypt rotate-keys   # verschlüsselt auch bestehende Secrets nach
sudo k3s secrets-encrypt status   # pollen bis Stage "reencrypt_finished"
sudo systemctl restart k3s        # laut k3s-Doku nach reencrypt_finished nochmal nötig

Nicht verwendet: k3s secrets-encrypt enable (CLI-Variante ohne
Config-Datei-Änderung) — für ein Ansible-verwaltetes Setup ist der
Config-Flag-Weg (secrets-encryption: true in config.yaml, dann
Restart) der zum Rest des Repos passende, deklarative Weg; beide
Mechanismen führen zum selben Ziel, sind aber keine zwei Schritte, die
man kombinieren muss.

Provider: aescbc (Default), nicht secretbox

Keine Notwendigkeit für den saubereren, aber weniger verbreiteten
secretbox-Provider (XSalsa20/Poly1305) — aescbc ist der k3s-Standard,
ausreichend für dieses Bedrohungsmodell (Schutz vor Klartext-Zugriff auf
die Datei, nicht vor einem staatlichen Akteur mit Kryptoanalyse-Budget).

Beide Änderungen (Encryption + Audit-Log) im selben Restart

Beide sind reine kube-apiserver-Startparameter — der Cluster ist so oder
so für die Dauer eines Neustarts (wenige Sekunden bis ~1 Minute) ohne
API-Server, unabhängig davon, wie viele Flags sich gleichzeitig ändern.
Ein gemeinsamer Restart statt zwei getrennter reduziert die Anzahl der
Downtime-Fenster. Über zwei unabhängige Ansible-Variablen
(k3s_secrets_encryption_enabled, k3s_audit_log_enabled in
capulus-ansible/group_vars/all.yml) lässt sich
bei Bedarf trotzdem einzeln togglen und getrennt ausrollen.

Audit-Policy: Metadata-Level, kein Full-Request-Response-Dump

Read-Traffic (get/list/watch — der weitaus größte Anteil, ständiges
Polling von Grafana/vmagent/ArgoCD) komplett ausgeschlossen. Für
Secrets/ConfigMaps bewusst Metadata-Level statt RequestResponse —
sonst würde das Audit-Log genau die Klartext-Werte mitschreiben, vor
denen die Secrets-Encryption gerade schützen soll. Volle Regel-Liste:
capulus-ansible/roles/k3s/templates/audit-policy.yaml.j2.

Retention bewusst begrenzt (14 Tage / 5 Backups / 100 MB je Datei) —
Homelab-Cluster mit reichlich freiem Plattenplatz (769 Gi frei, Stand
13.08.), Grenze ist hier "sinnvoll genug für Incident-Nachvollziehbarkeit"
statt "Kapazität sparen".


Rollout

1. Config ausrollen (schreibt nur Dateien, kein Neustart, kein
Risiko):

make k3s

Prüfen, dass beide Dateien wie erwartet auf dem Server liegen:

ssh [email protected] "sudo cat /etc/rancher/k3s/config.yaml; echo ---; sudo test -f /etc/rancher/k3s/audit-policy.yaml && echo 'audit-policy.yaml vorhanden'"

2. Backup + Neustart in einem Wartungsfenster (Cluster ist für die
Dauer des Neustarts ohne API-Server — laufende Pods bleiben unberührt,
aber kubectl/ArgoCD-Sync/Traefik-Routing-Änderungen pausieren kurz):

ssh [email protected] << 'EOF'
sudo systemctl stop k3s
sudo tar czf ~/k3s-db-backup-pre-phase4-$(date +%Y%m%d-%H%M).tar.gz \
  -C /var/lib/rancher/k3s/server db
sudo systemctl start k3s
EOF

tar bei gestopptem Dienst statt cp im laufenden Betrieb (wie in
Phase 3) — hier zusätzlich sqlite state.db/state.db-wal/state.db-shm
konsistent zusammen sichern, weil diesmal die Secrets selbst betroffen
sind, nicht nur deklarative NetworkPolicy-Objekte.

3. Warten, bis der Cluster wieder gesund ist:

ssh [email protected] "sudo systemctl status k3s --no-pager | head -5"
kubectl get nodes
kubectl get pods -A --no-headers | grep -v Running | grep -v Completed

4. Verifizieren, dass Encryption + Audit-Log aktiv sind:

ssh [email protected] "sudo k3s secrets-encrypt status"
# Erwartung: "Encryption Status: Enabled"

ssh [email protected] "sudo tail -5 /var/log/k3s/audit.log"
# Erwartung: JSON-Zeilen mit "kind":"Event"

5. Bestehende Secrets nachträglich verschlüsseln (Schritt 2 aktiviert
nur NEUE/geänderte Secrets — ohne diesen Schritt bleiben alle
bestehenden Secrets im Klartext):

ssh [email protected] "sudo k3s secrets-encrypt rotate-keys"

Status pollen, bis Stage reencrypt_finished erreicht ist:

ssh [email protected] "sudo k3s secrets-encrypt status"
# mehrfach wiederholen, Stage-Feld beobachten

6. Laut k3s-Doku abschließender Neustart, damit der Server den
finalen Stand übernimmt:

ssh [email protected] "sudo systemctl restart k3s"
kubectl get nodes   # nochmal auf Ready warten

7. Verifizieren, dass Secrets tatsächlich verschlüsselt auf der Platte
liegen
(der eigentliche Beweis, nicht nur der Status-Text):

ssh [email protected] "sudo k3s secrets-encrypt status"
# Erwartung: "Encryption Status: Enabled", aktiver Key gelistet

Optional, für den harten Beweis auf Byte-Ebene (sqlite3 ist auf dem Host
nicht installiert — Kurzinstallation nur für diesen einen Check, danach
wieder entfernen, falls gewünscht):

ssh [email protected] << 'EOF'
sudo apt-get install -y sqlite3
sudo sqlite3 /var/lib/rancher/k3s/server/db/state.db \
  "select hex(substr(value,1,20)) from kine where name like '%/secrets/%' limit 1;"
# Erwartung: Bytes beginnend mit dem "k8s:enc:aescbc:v1:"-Präfix (hex),
# NICHT lesbarer Klartext eines Secret-Feldnamens.
EOF

8. Cluster-weite Funktionsprüfung (wie nach jeder Phase):

kubectl get applications -n argocd -o custom-columns='NAME:.metadata.name,SYNC:.status.sync.status,HEALTH:.status.health.status'

Plus Stichproben lokal (*.homeserver) und extern über den
Cloudflare-Tunnel (*.pke-lab.de) — gleiche Disziplin wie nach dem
NetworkPolicy-Rollout (Phase 3), da ein API-Server-Neustart theoretisch
auch Traefik/ArgoCD-Reconciliation kurz stören könnte.


Rollback

Falls der apiserver nach Schritt 2 nicht mehr startet (z. B. Fehler
in der Audit-Policy-Syntax): schnellster Fix ohne Datenverlust — die
Zusatzflags aus /etc/rancher/k3s/config.yaml manuell entfernen
(secrets-encryption, kube-apiserver-arg-Block) und neu starten, dann
in Ruhe den Fehler in der Policy-Datei beheben, bevor erneut versucht
wird:

ssh [email protected] "sudo systemctl status k3s --no-pager -l | tail -30"
# Fehlerursache aus den Logs lesen, dann:
ssh [email protected] "sudo journalctl -u k3s -n 100 --no-pager"

Falls das Datastore selbst beschädigt wirkt (deutlich unwahrscheinlicher
— dieser Vorgang ändert nur, WIE geschrieben wird, nicht WAS): aus dem
Backup aus Schritt 2 wiederherstellen:

ssh [email protected] << 'EOF'
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar xzf ~/k3s-db-backup-pre-phase4-<timestamp>.tar.gz -C /var/lib/rancher/k3s/server
sudo systemctl start k3s
EOF

Zusätzlich secrets-encryption: true und den kube-apiserver-arg-Block
wieder aus capulus-ansible/group_vars/all.yml entfernen (bzw.
k3s_secrets_encryption_enabled/k3s_audit_log_enabled auf false) und
make k3s erneut laufen lassen, damit der nächste reguläre Ansible-Lauf
nicht wieder dieselbe Config schreibt.


Bekannte Einschränkungen


Fehlersuche

sudo k3s secrets-encrypt status                   # Encryption Status, aktiver Schlüssel, Stage
sudo tail -5 /var/log/k3s/audit.log               # JSON-Zeilen mit "kind":"Event"
sudo journalctl -u k3s -n 100 --no-pager
sudo cat /etc/rancher/k3s/config.yaml /etc/rancher/k3s/audit-policy.yaml
Symptom Ursache Lösung
k3s startet nach dem Einschalten nicht Syntaxfehler in der Audit-Policy oder im kube-apiserver-arg-Block journalctl -u k3s, Abschnitt „Rollback“: Zusatzflags aus config.yaml entfernen, Fehler beheben, erneut ausrollen
Encryption Status: Disabled secrets-encryption fehlt in der k3s-Konfiguration (k3s_secrets_encryption_enabled aus) Variable setzen, make k3s
Bestehende Secrets sind weiter im Klartext Aktivierung verschlüsselt nur neue und geänderte Secrets sudo k3s secrets-encrypt rotate-keys, Stage bis reencrypt_finished beobachten, danach systemctl restart k3s (Rollout Schritt 5 und 6)
Stage bleibt in reencrypt_active hängen Re-Encryption läuft noch oder ein Server wurde nicht neu gestartet warten, status wiederholen, Log lesen
Kein audit.log k3s_audit_log_enabled aus, /var/log/k3s fehlt Variable und Verzeichnis prüfen (die Rolle k3s legt es an)
audit.log wächst stark Metadata-Level zeichnet jeden Zugriff auf Policy anpassen oder Rotation prüfen
Datastore wirkt beschädigt sehr unwahrscheinlich, der Vorgang ändert nur das Schreibformat Backup aus Rollout Schritt 2 zurückspielen (Abschnitt „Rollback“)
Nach Wiederherstellung sind Secrets unlesbar Verschlüsselungsschlüssel (im Datastore-Backup) fehlt Backup mit demselben Stand der Konfiguration wiederherstellen, Incident 50010

Rolle und Variablen: k3s. Allgemeine Fehlersuche: zentrale Fehlersuche.