Tag 15: Wettkampf – Debug-Drills
Ziel: Acht typische Operator-Fehler unter Zeitdruck finden und beheben – mit Logs, Events, Conditions, Metriken und
managedFieldsstatt Raten · Dauer: ca. 180 min · Voraussetzung: Tag 13
Briefing
- Jeder Drill startet mit einer Störung: ein Saboteur-Befehl verändert Code oder Cluster. Danach siehst du nur Symptome – wie im Ticket.
- Stoppuhr ab Auslösen der Störung, Stopp, wenn der Schiedsrichter (Kontrollpunkt) wieder nur ✔ zeigt.
- Erst selbst diagnostizieren, dann den Diagnose-Pfad lesen. Die Lösung zuletzt.
- Nach jedem Drill setzt
gitdie Wettkampfbahn auf den sauberen Stand zurück.
Symptom (Ticket) Werkzeug Frage
---------------------- -------------------------------- -------------------------
CPU hoch, Log läuft reconcile_total, resourceVersion Wer schreibt dauernd?
"object modified" run.log, --show-managed-fields Wer schreibt noch mit?
Löschen hängt deletionTimestamp, finalizers Wem gehört der Finalizer?
apply scheitert Webhook-Config, openssl Läuft er, passt die CA?
alter Client scheitert Round-Trip-Test, beide Versionen Wo geht es verloren?
forbidden kubectl auth can-i --as Was fehlt in der Rolle?
"already exists" Cache-Optionen, Labels Was sieht der Cache?
Drift bleibt ownerReferences Wer weckt den Operator?
Startaufstellung
Die Wettkampfbahn ist eine Kopie deines site-operators im
Stand von Tag 12, mit git als Rücksetzknopf. Warum
nicht Tag 13? Dort fängst du Konflikte bereits leise ab – Drill 2 hätte
dann keine Symptome mehr. Terminal 1:
source ~/op-lab/env.sh
cp -r ~/op-lab/tag12-site-operator ~/op-lab/tag15-site-operator
cd ~/op-lab/tag15-site-operator
printf 'run.log\nlab/certs/\nlab/*.kubeconfig\nlab/webhooks-local.yaml\n' \
>> .gitignore
git init -q; git add -A && git commit -qm "Startaufstellung"
reset_bahn() { git checkout -q -- . && git clean -fdq; }
git log --oneline | head -1Erwartet (Hash variiert):
3f9e005 Startaufstellung
git init in einem vorhandenen Repository schadet nicht.
reset_bahn verwirft alle Änderungen und neuen Dateien –
ignorierte wie lab/certs/ bleiben.
Terminal 2: Control Plane mit den CRDs von heute:
source ~/op-lab/env.sh
cd ~/op-lab/tag15-site-operator && envtest-up -crds config/crd/basesWebhooks (Tag 8) und Conversion (Tag 9) brauchen TLS. Das Lab-Zertifikat aus Tag 8 gilt 30 Tage, liegt aber nicht in der kopierten Bahn – also neu ausstellen und Webhooks samt Conversion wieder eintragen, genau wie an Tag 8 (Drill 8) und Tag 9 (Drill 7). Zurück in Terminal 1:
mkdir -p lab/certs
openssl req -x509 -newkey rsa:2048 -nodes -days 30 \
-keyout lab/certs/tls.key -out lab/certs/tls.crt \
-subj /CN=127.0.0.1 -addext subjectAltName=IP:127.0.0.1 2>/dev/null
CA=$(base64 < lab/certs/tls.crt | tr -d '\n')
perl -0pe "s|service:\n\s+name: webhook-service\n\s+namespace: system\n\s+path: (\S+)\
|caBundle: $CA\n url: https://127.0.0.1:9443\$1|g" \
config/webhook/manifests.yaml > lab/webhooks-local.yaml
kubectl apply -f lab/webhooks-local.yaml
kubectl patch crd staticsites.web.lab.example --type=merge -p '{"spec":{"conversion":{
"strategy":"Webhook","webhook":{"conversionReviewVersions":["v1"],
"clientConfig":{"url":"https://127.0.0.1:9443/convert","caBundle":"'"$CA"'"}}}}}'Erwartet (gekürzt):
mutatingwebhookconfiguration.admissionregistration.k8s.io/mutating-webhook-... created
validatingwebhookconfiguration.admissionregistration.k8s.io/validating-webh... created
customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example patched
Der Operator läuft heute wie in Produktion als ServiceAccount mit genau der Rolle aus den RBAC-Markern – Rezept aus Tag 11, Drill 2 (das Token dort ist längst abgelaufen):
kubectl apply -k config/lab-rbac | grep -E 'namespace/|serviceaccount/|manager-role '
cp ~/op-lab/envtest.kubeconfig ~/op-lab/sa.kubeconfig
TOKEN=$(kubectl create token site-operator-controller-manager \
-n site-operator-system --duration=4h)
export KUBECONFIG=~/op-lab/sa.kubeconfig
kubectl config set-credentials operator --token="$TOKEN" >/dev/null
kubectl config set-context operator --cluster=envtest --user=operator >/dev/null
kubectl config use-context operator
kubectl auth whoami -o jsonpath='{.status.userInfo.username}{"\n"}'
export KUBECONFIG=~/op-lab/envtest.kubeconfigErwartet:
namespace/site-operator-system created
serviceaccount/site-operator-controller-manager created
clusterrole.rbac.authorization.k8s.io/site-operator-manager-role created
Switched to context "operator".
system:serviceaccount:site-operator-system:site-operator-controller-manager
Terminal 3 startet den Operator – mit Metriken ohne TLS, Webhook-Zertifikat und der ServiceAccount-Kubeconfig. Diesen Befehl brauchst du nach jeder Störung wieder (Ctrl+C, Pfeil hoch, Enter):
source ~/op-lab/env.sh
cd ~/op-lab/tag15-site-operator
go run ./cmd/main.go -health-probe-bind-address=0 \
-metrics-bind-address=:8080 -metrics-secure=false \
-webhook-cert-path=lab/certs -kubeconfig ~/op-lab/sa.kubeconfig 2>&1 | tee run.logErwartet (gekürzt):
INFO controller-runtime.webhook Registering webhook {"path": "/convert"}
INFO controller-runtime.webhook Serving webhook server {"host": "", "port": 9443}
INFO controller-runtime.metrics Serving metrics server {"bindAddress": ":8080", ...
INFO Starting workers {"controller": "staticsite", ..., "worker count": 1}
Zum Schluss die Startobjekte in Terminal 1 – eine
Site per v1alpha1, eine per v1 mit
ConfigMap-Quelle:
kubectl create configmap html --from-literal=index.html='<h1>CM</h1>'
kubectl apply -f lab/demo.yaml
kubectl apply -f - <<'EOF'
apiVersion: web.lab.example/v1
kind: StaticSite
metadata:
name: neu
spec:
source:
configMapRef:
name: html
EOF
kubectl get siteErwartet:
configmap/html created
Warning: v1alpha1 ist veraltet, nutze v1
staticsite.web.lab.example/demo created
staticsite.web.lab.example/neu created
NAME READY AVAILABLE URL AGE
demo False http://demo.default.svc 0s
neu False http://neu.default.svc 0s
AVAILABLE False ist in envtest normal: Es gibt keinen
Deployment-Controller, also keine Pods (Tag 0). Lege jetzt den
Schiedsrichter aus dem Kontrollpunkt an und prüfe, dass er nur ✔ zeigt –
das ist dein Ziel nach jedem Drill.
Tipp: Die Saboteur-Befehle treffen Code, den du an Tag 4 bis 10 geschrieben hast. Zeigt
git diff --statdanach keine Änderung, weicht dein Stand ab: Baue die Störung dann von Hand nach dem gezeigten Diff ein.
Stoppuhr in Terminal 1: SECONDS=0 beim Auslösen,
echo "$((SECONDS / 60)) min" am Ende.
Drill 1: Hotloop – der Operator redet mit sich selbst
Zeitlimit: 10 min
Störung auslösen. Ein Kollege wollte zweierlei: im Status sehen, „wann zuletzt geprüft wurde”, und dass auch Annotationen den Operator wecken. Also tauscht er das Prädikat aus Tag 10 gleich mit aus:
export NEU='"geprüft um "+metav1.Now().Format("15:04:05.000000")'
perl -pi -e 's/"alle Objekte abgeglichen"/$ENV{NEU}/' internal/controller/status.go
perl -pi -e 's/GenerationChangedPredicate/ResourceVersionChangedPredicate/' \
internal/controller/staticsite_controller.go
git diff --statErwartet:
internal/controller/staticsite_controller.go | 2 +-
internal/controller/status.go | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
Operator in Terminal 3 neu starten. SECONDS=0.
Symptome: Das Log in Terminal 3 rast, der Lüfter
läuft an, kubectl get site sieht unauffällig aus.
Diagnose-Pfad. Erst messen, dann lesen. Die Reconcile-Rate aus den Metriken:
OKS='controller_runtime_reconcile_total{controller="staticsite",result="success"}'
m() { curl -s localhost:8080/metrics | awk -v k="$OKS" 'index($0, k) == 1 {print $2}'; }
a=$(m); sleep 10; echo "Reconciles in 10 s: $(( $(m) - a ))"Erwartet (Zahl variiert, Hauptsache weit über null):
Reconciles in 10 s: 4667
Was ändert sich? resourceVersion springt,
generation bleibt – also ändert sich nur der Status:
for i in 1 2; do kubectl get site demo \
-o jsonpath='{.metadata.resourceVersion} {.metadata.generation}{"\n"}'; sleep 1; done
kubectl get site demo --show-managed-fields -o jsonpath=\
'{range .metadata.managedFields[*]}{.manager} {.operation} {.subresource}{"\n"}{end}'
kubectl get site demo \
-o jsonpath='{.status.conditions[?(@.type=="Degraded")].message}{"\n"}'Erwartet:
6658 1
7234 1
kubectl-client-side-apply Update
kubectl-annotate Update
main Update status
geprüft um 11:43:46.650626
Der Manager main (so heißt das Binary von
go run) schreibt den Status-Subresource, jedes Mal mit
neuer Uhrzeit. Jeder Status-Patch ist ein Update-Event auf der
StaticSite; ResourceVersionChangedPredicate lässt jedes
Update durch – nächster Reconcile, nächste Uhrzeit, nächster Patch. Die
Bremse aus Tag 5 (equality.Semantic.DeepEqual vor dem
Patch) greift nie, weil der Status sich wirklich ändert. Der Test aus
Tag 6 sieht es auch:
go test ./internal/controller/ -ginkgo.focus=Hotloop 2>&1 | tail -1Erwartet:
FAIL
Tipp:
-zap-log-level=5zeigt die Debug-Logs von controller-runtime:LEVEL(-5) ReconcilingundReconcile successfulpro Durchlauf – bei einem Hotloop hunderte pro Sekunde.
Lösung. Beide Änderungen zurück:
git checkout -- internal/controller/status.go \
internal/controller/staticsite_controller.goJede für sich hätte den Loop schon gestoppt (live getestet): Ein
deterministischer Status ändert sich beim zweiten Lauf nicht mehr, und
GenerationChangedPredicate filtert Status-Writes, weil sie
generation nicht erhöhen. Wer Annotationen wirklich
braucht, kombiniert statt zu tauschen:
For(&webv1.StaticSite{},
builder.WithPredicates(predicate.Or(
predicate.GenerationChangedPredicate{},
predicate.AnnotationChangedPredicate{}))).Lessons:
- Status muss deterministisch sein: gleicher Ist-Zustand, gleicher
Status. Keine Zeitstempel, Zähler oder Zufallswerte – Zeit gehört in
lastTransitionTime, und die setztmeta.SetStatusConditionnur bei einem echten Wechsel. - Prädikate sind ein Gurt, kein Ersatz: Ein nicht deterministisches
Kind (z. B. Zeitstempel-Annotation am Deployment) loopt über
Owns()trotzdem. - Reconcile-Rate gehört ins Monitoring: Im Ruhezustand ist sie null.
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 2: Konflikte – „the object has been modified”
Zeitlimit: 10 min
Störung auslösen. „Patch ist zu kompliziert, Update reicht”:
export NEU='Update(ctx, site, client.FieldOwner("site-operator"))'
perl -pi -e 's/Patch\(ctx, site, client\.MergeFrom\(orig\)\)/$ENV{NEU}/' \
internal/controller/status.go
git diff --statErwartet:
internal/controller/status.go | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Operator neu starten. Dazu ein zweiter Schreiber, wie ihn jeder
Cluster hat (GitOps, HPA, ein Kollege mit kubectl):
SECONDS=0
for i in $(seq 1 20); do
kubectl patch site demo --type merge \
-p "{\"spec\":{\"replicas\":$((i % 3 + 1))}}" >/dev/null
kubectl annotate site demo lab/ping=$i --overwrite >/dev/null
doneSymptome: Fehler im Log, Status hinkt hinterher, aber „irgendwann stimmt es”.
Diagnose-Pfad.
grep -c 'Reconciler error' run.log
grep 'Reconciler error' run.log | head -1 | sed 's/.*"error": //'
curl -s localhost:8080/metrics | grep 'reconcile_errors_total{controller="staticsite"'
kubectl get site demo --show-managed-fields -o jsonpath=\
'{range .metadata.managedFields[*]}{.manager} {.operation} {.subresource}{"\n"}{end}'Erwartet (umbrochen):
13
"Operation cannot be fulfilled on staticsites.web.lab.example \"demo\": the object
has been modified; please apply your changes to the latest version and try again"}
controller_runtime_reconcile_errors_total{controller="staticsite"} 13
controller_runtime_terminal_reconcile_errors_total{controller="staticsite"} 0
kubectl-client-side-apply Update
main Update status
kubectl-annotate Update
kubectl-patch Update
site-operator Update status
managedFields verrät die Mitspieler:
kubectl-annotate und kubectl-patch schreiben
parallel. Update schickt das ganze Objekt mit der
resourceVersion aus dem Cache. Hat inzwischen jemand
anderes geschrieben, lehnt der API-Server ab (optimistisches Locking,
Tag 13). Patch mit MergeFrom schickt nur den
Diff, ohne resourceVersion.
Lösung.
git checkout -- internal/controller/status.goOperator neu starten, die Schleife von oben noch einmal laufen lassen:
grep -c 'Reconciler error' run.logErwartet:
0
Lessons:
- Status-Writes per
Status().Patch(ctx, obj, client.MergeFrom(orig))– oder Server-Side Apply (Tag 4, Challenge).Updatenur, wenn du das Locking wirklich willst. - Ein vereinzelter Conflict ist kein Bug: Reconcile gibt den Fehler zurück, die Workqueue versucht es mit Backoff neu. Ein Dauer-Conflict ist einer.
managedFields(--show-managed-fields) ist das Schreiber-Protokoll eines Objekts: Wer hat welches Feld zuletzt angefasst?
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 3: Hängender Finalizer
Zeitlimit: 10 min
Störung auslösen. Version 0.9 des Operators hieß der Finalizer noch anders. Eine alte Site trägt ihn bis heute:
kubectl apply -f - <<'EOF'
apiVersion: web.lab.example/v1
kind: StaticSite
metadata:
name: alt
spec:
content: "<h1>Alt</h1>"
EOF
kubectl patch site alt --type json -p \
'[{"op":"add","path":"/metadata/finalizers","value":["web.lab.example/cleanup"]}]'
SECONDS=0
kubectl delete site alt --timeout=5sSymptome:
staticsite.web.lab.example "alt" deleted from default namespace
error: timed out waiting for the condition on staticsites/alt
Die Site ist „gelöscht” und trotzdem da; Pipelines, die auf das Löschen warten, hängen.
Diagnose-Pfad.
COLS='NAME:.metadata.name,GELOESCHT:.metadata.deletionTimestamp'
kubectl get site -o custom-columns="$COLS,FINALIZER:.metadata.finalizers[*]"
kubectl get site alt --show-managed-fields -o jsonpath=\
'{range .metadata.managedFields[*]}{.manager} {.operation} {.fieldsV1}{"\n"}{end}' \
| grep finalizerErwartet (umbrochen):
NAME GELOESCHT FINALIZER
alt 2026-10-10T08:47:33Z web.lab.example/cleanup
demo <none> <none>
neu <none> <none>
kubectl-patch Update {"f:metadata":{"f:finalizers":{".":{},
"v:\"web.lab.example/cleanup\"":{}}}}
deletionTimestamp ist gesetzt, der Finalizer heißt nicht
web.lab.example/finalizer (Tag 7). Kein Controller fühlt
sich zuständig – niemand entfernt ihn.
Lösung. Erst klären, was der alte Finalizer schützen
sollte (hier: einen DNS-Eintrag beim Registrar, Tag 7). Ist extern
aufgeräumt, gezielt nur diesen Finalizer entfernen –
test verhindert, dass du den falschen Index erwischst:
curl -s localhost:18090/records # falls der Registrar läuft: Eintrag "alt"?
kubectl patch site alt --type json -p '[
{"op":"test","path":"/metadata/finalizers/0","value":"web.lab.example/cleanup"},
{"op":"remove","path":"/metadata/finalizers/0"}]'
kubectl get site altErwartet:
staticsite.web.lab.example/alt patched
Error from server (NotFound): staticsites.web.lab.example "alt" not found
envtest hat keinen Garbage Collector – die Kinder räumst du hier von Hand ab:
kubectl delete deploy,cm,svc -l app.kubernetes.io/name=altLessons:
- Nie pauschal
finalizers: nullpatchen: Das entfernt auch den Finalizer deines Operators und hinterlässt externe Leichen. - Benennst du einen Finalizer um, migriert der Operator alte Objekte
selbst:
controllerutil.RemoveFinalizer(&site, "web.lab.example/cleanup")plusAddFinalizerfür den neuen, dann einUpdate. - Die zweite häufige Ursache: Der eigene Finalizer hängt, weil der
externe Dienst ausfällt (Tag 7,
/admin/outage). Dann zeigen Log undDegradedden Retry – hier hilft Warten oder Reparieren, nicht Patchen.
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 4: Webhook down und falsches caBundle
Zeitlimit: 15 min (zwei Runden)
Störung auslösen, Runde A. Der Operator stürzt ab –
simuliert durch Ctrl+C in Terminal 3.
SECONDS=0. Dann in Terminal 1:
kubectl label site demo lab/test=1 --overwrite
kubectl patch site demo --subresource=status --type merge \
-p '{"status":{"url":"http://test"}}'
kubectl get staticsites.v1alpha1.web.lab.exampleSymptome (umbrochen):
Error from server (InternalError): Internal error occurred: Internal error occurred:
conversion webhook for web.lab.example/v1, Kind=StaticSite failed: Post
"https://127.0.0.1:9443/convert?timeout=30s": dial tcp 127.0.0.1:9443: connect:
connection refused
staticsite.web.lab.example/demo patched
Warning: v1alpha1 ist veraltet, nutze v1
Error from server (StorageReadError): failed to read one or more
staticsites.web.lab.example from the storage: StorageError: corrupt object, ...
Das Label scheitert schon vor den Admission-Webhooks: Die sind nur
für v1alpha1 registriert, also muss der API-Server das
Objekt erst konvertieren – über denselben toten Port. Die alte
API-Version ist komplett unlesbar. Nur der Status-Patch auf
v1 geht durch: keine Conversion nötig, und die
Webhook-Regeln für staticsites umfassen
staticsites/status nicht. Auch das Entfernen eines
Finalizers ist ein Update – es scheitert genauso.
Diagnose-Pfad.
VWC=validatingwebhookconfiguration/validating-webhook-configuration
kubectl get crd staticsites.web.lab.example \
-o jsonpath='{.spec.conversion.webhook.clientConfig.url}{"\n"}'
kubectl get $VWC -o jsonpath=\
'{.webhooks[0].clientConfig.url} {.webhooks[0].failurePolicy}{"\n"}'
nc -z 127.0.0.1 9443 && echo "Port offen" || echo "niemand hört auf 9443"Erwartet:
https://127.0.0.1:9443/convert
https://127.0.0.1:9443/validate-web-lab-example-v1alpha1-staticsite Fail
niemand hört auf 9443
Lösung A: Operator in Terminal 3 wieder starten; das Label von oben geht dann durch. Der Manager startet den Webhook-Server vor den Caches – sonst könnte er seine eigenen Objekte nie lesen.
Störung auslösen, Runde B. cert-manager hat das
Zertifikat erneuert, aber das caBundle wurde nicht
nachgezogen – simuliert mit einer fremden CA:
openssl req -x509 -newkey rsa:2048 -nodes -days 1 -subj "/CN=falsche-ca" \
-keyout /dev/null -out lab/certs/falsch.crt 2>/dev/null
kubectl patch $VWC --type json -p \
"[{\"op\":\"replace\",\"path\":\"/webhooks/0/clientConfig/caBundle\",
\"value\":\"$(base64 < lab/certs/falsch.crt | tr -d '\n')\"}]"
SECONDS=0
kubectl label site demo lab/test=2 --overwriteSymptome (umbrochen):
validatingwebhookconfiguration.admissionregistration.k8s.io/validating-webhook-
configuration patched
Error from server (InternalError): Internal error occurred: failed calling webhook
"vstaticsite-v1alpha1.kb.io": failed to call webhook: Post "https://127.0.0.1:9443/
validate-web-lab-example-v1alpha1-staticsite?timeout=10s": tls: failed to verify
certificate: x509: certificate signed by unknown authority
Der Mutating-Webhook und die Conversion laufen weiter – nur die Validierung vertraut dem Server nicht mehr.
Diagnose-Pfad. Wem vertraut der API-Server, wer hat das Serverzertifikat ausgestellt?
grep 'TLS handshake error' run.log | tail -1
kubectl get $VWC -o jsonpath='{.webhooks[0].clientConfig.caBundle}' \
| base64 -d | openssl x509 -noout -subject
openssl s_client -connect 127.0.0.1:9443 </dev/null 2>/dev/null \
| openssl x509 -noout -issuerErwartet (umbrochen):
2026/10/10 11:45:38 http: TLS handshake error from 127.0.0.1:54206: remote error:
tls: bad certificate
subject=CN=falsche-ca
issuer=CN=127.0.0.1
caBundle (falsche-ca) passt nicht zum Aussteller des
Serverzertifikats (das selbstsignierte CN=127.0.0.1 aus der
Startaufstellung).
Lösung B:
kubectl patch $VWC --type json -p \
"[{\"op\":\"replace\",\"path\":\"/webhooks/0/clientConfig/caBundle\",
\"value\":\"$(base64 < lab/certs/tls.crt | tr -d '\n')\"}]"
kubectl label site demo lab/test=3 --overwriteErwartet (umbrochen):
validatingwebhookconfiguration.admissionregistration.k8s.io/validating-webhook-
configuration patched
staticsite.web.lab.example/demo labeled
Lessons:
failurePolicy: Failplus ein einziger Operator-Pod heißt: Operator weg, API weg. In Produktion mindestens zwei Replikas, PodDisruptionBudget und einnamespaceSelector, derkube-systemund den Operator-Namespace ausnimmt.- Ein toter Conversion-Webhook ist schlimmer als ein toter Admission-Webhook: Er macht auch das Lesen unmöglich, sobald eine Version konvertiert werden muss.
- Im Cluster injiziert cert-manager das
caBundleper Annotationcert-manager.io/inject-ca-from(Tag 8). Fehlt die Annotation nach einem Umbau, kommt genau dieser Fehler – oft erst bei der nächsten Rotation.
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 5: Conversion verliert Daten
Zeitlimit: 15 min
Störung auslösen. Beim Aufräumen in
ConvertFrom (Hub v1 → Spoke
v1alpha1, Tag 9) ist der Block verschwunden, der
source nach contentFrom kopiert:
perl -0pi -e 's/\tif s := src\.Spec\.Source;.*?\n\t\}\n//s' \
api/v1alpha1/staticsite_conversion.go
git diff --statErwartet:
api/v1alpha1/staticsite_conversion.go | 7 -------
1 file changed, 7 deletions(-)
Operator neu starten, SECONDS=0. Die Site
neu aus der Startaufstellung neu anlegen, dann tut die alte
GitOps-Pipeline, was sie immer tut – sie spricht noch
v1alpha1:
kubectl delete site neu
kubectl apply -f - <<'EOF'
apiVersion: web.lab.example/v1
kind: StaticSite
metadata:
name: neu
spec:
source:
configMapRef:
name: html
EOF
sleep 2
kubectl get staticsites.v1.web.lab.example neu -o jsonpath='{.spec.source}{"\n"}'
kubectl patch staticsites.v1alpha1.web.lab.example neu --type merge \
-p '{"spec":{"replicas":2}}'Symptome (umbrochen):
{"configMapRef":{"name":"html"}}
Warning: v1alpha1 ist veraltet, nutze v1
The StaticSite "neu" is invalid: spec: Invalid value: exactly one of the fields in
[content contentFrom] must be set
Über v1 ist alles da, der Operator (er spricht
v1, Tag 9) liefert die Seite aus. Aber jeder alte Client
scheitert – mit einer Meldung über ein Feld, das er gar nicht anfassen
wollte.
Diagnose-Pfad. Dasselbe Objekt in beiden Versionen lesen, dann den Round-Trip-Test aus Tag 9:
kubectl get staticsites.v1alpha1.web.lab.example neu -o jsonpath='{.spec}{"\n"}'
go test ./api/v1alpha1/ -run TestRoundTripErwartet (gekürzt):
Warning: v1alpha1 ist veraltet, nutze v1
{"image":"nginxinc/nginx-unprivileged:1.31-alpine","path":"/","replicas":1}
--- FAIL: TestRoundTrip (0.00s)
--- FAIL: TestRoundTrip/contentFrom (0.00s)
staticsite_conversion_test.go:34: Round-Trip verändert:
in {Content: ContentFrom:0xbc134c1e3b0 Replicas:0 Image: Path:}
out {Content: ContentFrom:<nil> Replicas:0 Image: Path:}
FAIL
Die Conversion v1 → v1alpha1 verliert
source. Beim Patch wandelt der API-Server das gespeicherte
Objekt in die Version des Clients, wendet den Patch an und validiert –
ohne Quelle greift die CEL-Regel „genau eins” aus Tag 8. Ohne diese
Regel wäre der Patch durchgegangen und hätte source
still gelöscht.
Lösung. Conversion zurückholen, Test grün, Operator neu starten:
git checkout -- api/v1alpha1/staticsite_conversion.go
go test ./api/v1alpha1/ -run TestRoundTripErwartet:
ok example.com/site-operator/api/v1alpha1 0.159s
Live beobachtet: Die während der Störung geschriebene Site lehnt
v1alpha1-Patches auch nach dem Fix noch ab, bis sie einmal
über v1 neu gespeichert wurde – derselbe Befehl wie bei der
Storage-Migration in Tag 9:
kubectl get staticsites.v1.web.lab.example neu -o json | kubectl replace -f -
kubectl patch staticsites.v1alpha1.web.lab.example neu --type merge \
-p '{"spec":{"replicas":2}}'
kubectl get staticsites.v1.web.lab.example neu \
-o jsonpath='{.spec.source} {.spec.replicas}{"\n"}'Erwartet:
staticsite.web.lab.example/neu replaced
Warning: v1alpha1 ist veraltet, nutze v1
staticsite.web.lab.example/neu patched
{"configMapRef":{"name":"html"}} 2
Lessons:
- Jede Conversion braucht einen Round-Trip-Test (Tag 9) – in der CI, nicht nur auf dem Laptop. Er hätte diese Störung vor dem Merge gefunden.
- CEL-Regeln sind Verteidigung in der Tiefe: Hier haben sie aus stillem Datenverlust einen lauten Fehler gemacht.
- Felder, die es nur im Hub gibt, parkt der Spoke als Annotation – sonst verliert jeder Schreibzugriff über die alte Version sie.
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 6: Fehlende RBAC – forbidden
Zeitlimit: 10 min
Störung auslösen. Beim Aufräumen der Marker ist eine Zeile zu viel verschwunden:
perl -ni -e 'print unless m{resources=deployments,verbs=create;update;patch}' \
internal/controller/staticsite_controller.go
make manifests && kubectl apply -k config/lab-rbac | grep manager-role
git diff --statErwartet:
clusterrole.rbac.authorization.k8s.io/site-operator-manager-role configured
clusterrolebinding.rbac.authorization.k8s.io/site-operator-manager-rolebinding unchanged
config/rbac/role.yaml | 3 ---
internal/controller/staticsite_controller.go | 1 -
2 files changed, 4 deletions(-)
Operator neu starten, SECONDS=0, eine neue Site:
kubectl apply -f - <<'EOF'
apiVersion: web.lab.example/v1
kind: StaticSite
metadata:
name: rbac
spec:
content: "<h1>RBAC</h1>"
EOFSymptome: Die ConfigMap entsteht, das Deployment nie.
Diagnose-Pfad. Conditions und Events zuerst – der Operator meldet seinen Fehler selbst (Tag 5):
kubectl get site rbac -o jsonpath=\
'{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'
kubectl get events --field-selector involvedObject.name=rbac \
-o custom-columns=TYPE:.type,REASON:.reason,MSG:.message | cut -c1-80
grep -c forbidden run.logErwartet (gekürzt):
Degraded=True ReconcileError
Available=False ReplicasNotReady
TYPE REASON MSG
Normal ReplicasNotReady Available=False: kein Deployment
Warning ReconcileError Degraded=True: deployment: deployments.apps is forb
11
Die volle Meldung im Log nennt User, Verb, Ressource und Namespace:
deployments.apps is forbidden: User "system:serviceaccount:site-operator-system:
site-operator-controller-manager" cannot create resource "deployments" in API group
"apps" in the namespace "default"
Gegenprobe ohne Operator:
SA=system:serviceaccount:site-operator-system:site-operator-controller-manager
kubectl auth can-i create deployments --as=$SA -n default
kubectl auth can-i list deployments --as=$SA -n defaultErwartet:
no
yes
Lösung. Marker zurück, Rolle neu erzeugen und anwenden – ohne Neustart, RBAC wirkt sofort, die Workqueue versucht es per Backoff weiter:
git checkout -- internal/controller/staticsite_controller.go
make manifests && kubectl apply -k config/lab-rbac | grep manager-role
sleep 20; kubectl get deploy rbac -o nameErwartet:
clusterrole.rbac.authorization.k8s.io/site-operator-manager-role configured
clusterrolebinding.rbac.authorization.k8s.io/site-operator-manager-rolebinding unchanged
deployment.apps/rbac
Lessons:
- RBAC ist Code: Marker →
make manifests→role.yaml. Den Diff vonrole.yamlim Review lesen, nicht nur den Go-Code. - Fehlt
listoderwatch, ist es schlimmer: Der Informer startet nie, nachCacheSyncTimeout(2 min) bricht der Controller mittimed out waiting for cache to be syncedab. - Teste lokal immer als ServiceAccount (Token-Kubeconfig wie in Tag 11
und heute) – als
system:mastersfindest du keinen RBAC-Fehler.
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 7: Der Cache sieht das eigene Deployment nicht
Zeitlimit: 15 min
Störung auslösen. Neue Label-Konvention im Team:
managed-by mit Domain. Ein Einzeiler im Code:
perl -pi -e 's/(managed-by"\] = )"site-operator"/$1"site-operator.lab.example"/' \
internal/controller/resources.go
git diff --statErwartet:
internal/controller/resources.go | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Operator neu starten, SECONDS=0.
Symptome: Sekunden später ist jede Site
Degraded – mit einer absurden Meldung:
grep -c 'Reconciler error' run.log
kubectl get site demo \
-o jsonpath='{.status.conditions[?(@.type=="Degraded")].message}{"\n"}'Erwartet (Zahl wächst):
22
deployment: deployments.apps "demo" already exists
CreateOrUpdate liest, findet nichts, legt an – und der
API-Server sagt: gibt es schon.
Diagnose-Pfad. Der Operator liest über den Cache (Tag 2). Was sieht der Cache, was der API-Server?
kubectl get deploy -L app.kubernetes.io/managed-by
grep -n 'Label: mine\|managed-by' internal/controller/cache.goErwartet:
NAME READY UP-TO-DATE AVAILABLE AGE MANAGED-BY
demo 0/3 0 0 8m4s site-operator.lab.example
neu 0/2 0 0 8m4s site-operator.lab.example
15: "app.kubernetes.io/managed-by": "site-operator",
18: &appsv1.Deployment{}: {Label: mine},
19: &corev1.Service{}: {Label: mine},
Die CacheOptions aus Tag 10 cachen Deployments und
Services nur mit managed-by=site-operator. Der erste Lauf
nach dem Neustart schreibt das neue Label – damit fällt das Deployment
aus dem Cache. Für r.Get existiert es nicht mehr
(NotFound), Create scheitert an
AlreadyExists, Backoff, von vorn.
Lösung. Erst den Code zurück, Operator neu starten:
git checkout -- internal/controller/resources.go
sleep 5; grep -c 'Reconciler error' run.logErwartet (nach dem Neustart weiter Fehler):
23
Der Code stimmt wieder, aber die Objekte im Cluster tragen noch das neue Label – der Cache sieht sie weiterhin nicht. Also die Objekte zurück-labeln:
kubectl label deploy,svc,cm \
-l app.kubernetes.io/managed-by=site-operator.lab.example \
app.kubernetes.io/managed-by=site-operator --overwrite
sleep 15
kubectl get site -o custom-columns=\
'NAME:.metadata.name,DEGRADED:.status.conditions[?(@.type=="Degraded")].reason'Erwartet:
deployment.apps/demo labeled
deployment.apps/neu labeled
service/demo labeled
service/neu labeled
NAME DEGRADED
demo AsExpected
neu AsExpected
Die ConfigMaps hat der Operator schon selbst zurückgesetzt – sie liegen ungefiltert im Cache.
Lessons:
- Cache-Filter (
ByObject,DefaultNamespaces,DefaultLabelSelector) sparen Speicher, aber machen Objekte unsichtbar:NotFoundohne Hinweis, gefolgt vonAlreadyExists. - Labels, auf die ein Cache filtert, sind API: Eine Umbenennung braucht eine Migration (beide Werte im Selektor, umlabeln, alten Wert entfernen).
- Für Objekte außerhalb des Filters:
client.CacheOptions{DisableFor: …}odermgr.GetAPIReader()– beides kostet einen API-Call pro Zugriff.
reset_bahnFortschritt speichern? Kostenlos registrieren
Drill 8: Fehlende Owner Reference – Waisen
Zeitlimit: 10 min
Störung auslösen. „SetControllerReference macht nur Ärger beim Umzug”:
export ALT='return controllerutil.SetControllerReference(site, dep, r.Scheme)'
perl -0pi -e 's/(hash\)\n\t\t)\Q$ENV{ALT}\E/${1}return nil/' \
internal/controller/staticsite_controller.go
git diff --statErwartet:
internal/controller/staticsite_controller.go | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Operator neu starten, SECONDS=0:
kubectl apply -f - <<'EOF'
apiVersion: web.lab.example/v1
kind: StaticSite
metadata:
name: waise
spec:
content: "<h1>Waise</h1>"
EOF
sleep 2; kubectl scale deploy waise --replicas=4; sleep 2
kubectl get deploy waise -o jsonpath='{.spec.replicas}{"\n"}'Symptome: Die Drift-Korrektur aus Tag 4 wirkt nicht mehr:
deployment.apps/waise scaled
4
Im echten Cluster käme später dazu: Nach
kubectl delete site waise räumt der Garbage Collector
ConfigMap und Service ab – das Deployment bleibt als Waise stehen und
läuft weiter.
Diagnose-Pfad.
kubectl get deploy,cm,svc -l app.kubernetes.io/name=waise -o custom-columns=\
'KIND:.kind,NAME:.metadata.name,OWNER:.metadata.ownerReferences[0].name'Erwartet:
KIND NAME OWNER
Deployment waise <none>
ConfigMap waise-content waise
Service waise waise
Owns(&appsv1.Deployment{}) ordnet Events über die
Controller-Owner-Reference dem Besitzer zu. Ohne sie landet nichts in
der Queue – der Operator erfährt vom scale nie.
Lösung. Code zurück, Operator neu starten. Beim
Start reconciled er jede Site, CreateOrUpdate setzt die
Owner Reference am vorhandenen Deployment nach und dreht die Drift
zurück:
git checkout -- internal/controller/staticsite_controller.goNach dem Neustart:
kubectl get deploy waise -o custom-columns=\
'NAME:.metadata.name,REPLICAS:.spec.replicas,OWNER:.metadata.ownerReferences[0].name'
kubectl get deploy -l app.kubernetes.io/managed-by=site-operator -o custom-columns=\
'NAME:.metadata.name,OWNER:.metadata.ownerReferences[0].kind' \
| awk 'NR==1||$2=="<none>"'Erwartet:
NAME REPLICAS OWNER
waise 1 waise
NAME OWNER
Die zweite Abfrage ist die Waisen-Suche: Sie listet Deployments mit unserem Label, aber ohne Besitzer. Leer heißt sauber; echte Waisen (Site schon gelöscht) löschst du nach Prüfung von Hand.
Lessons:
- Jedes Kind bekommt
SetControllerReference– der Test „mit Owner” aus Tag 6 (metav1.IsControlledBy) fängt diese Störung. - Labels wie
app.kubernetes.io/managed-bysind die zweite Leine: Ohne sie findest du Waisen nicht wieder. - Owner References gehen nur im selben Namespace; für alles andere Finalizer (Tag 7).
reset_bahn
kubectl delete site rbac waiseFortschritt speichern? Kostenlos registrieren
Bewertung
Pro Drill: in der Zeit ohne Blick in Diagnose-Pfad und Lösung 3 Punkte, in der Zeit mit Blick 1 Punkt, sonst 0.
| Drill | Zeitlimit | Leitspur | Punkte |
|---|---|---|---|
| 1 Hotloop | 10 min | reconcile_total, managedFields |
|
| 2 Konflikte | 10 min | Reconciler error, Schreiber in
managedFields |
|
| 3 Hängender Finalizer | 10 min | deletionTimestamp, Finalizer-Name |
|
| 4 Webhook down / caBundle | 15 min | connection refused, unknown authority |
|
| 5 Conversion-Verlust | 15 min | Round-Trip-Test | |
| 6 Fehlende RBAC | 10 min | forbidden, auth can-i --as |
|
| 7 Cache und Labels | 15 min | already exists, -L managed-by,
CacheOptions |
|
| 8 Owner Reference | 10 min | ownerReferences, Waisen-Suche |
18 von 24 Punkten: einsatzbereit für die Rufbereitschaft deines Operators. Für jeden verpassten Drill eine Zeile ins Runbook: Symptom, erster Befehl, Ursache.
Kontrollpunkt
Der Schiedsrichter prüft nach jedem Drill den Gesamtzustand. Operator läuft in Terminal 3 mit den Flags der Startaufstellung:
cat > lab/schiedsrichter.sh <<'EOF'
# Schiedsrichter: prüft, ob der site-operator wieder gesund ist.
ok() { echo "✔ $1"; }
nok() { echo "✘ $1"; }
chk() { if eval "$2" >/dev/null 2>&1; then ok "$1"; else nok "$1"; fi; }
SA=system:serviceaccount:site-operator-system:site-operator-controller-manager
m() { curl -s localhost:8080/metrics | awk -v k="$1" 'index($0, k) == 1 {print $2}'; }
OKS='controller_runtime_reconcile_total{controller="staticsite",result="success"}'
ERR='controller_runtime_reconcile_errors_total{controller="staticsite"}'
kubectl annotate site --all lab/schiedsrichter="$(date +%s)" --overwrite >/dev/null
sleep 3; a=$(m "$OKS"); e=$(m "$ERR"); sleep 5
chk "Operator liefert Metriken" '[ -n "$a" ]'
chk "kein Hotloop (0 Reconciles in 5 s Ruhe)" '[ "$(m "$OKS")" = "$a" ]'
chk "keine Reconcile-Fehler" '[ "$(m "$ERR")" = "$e" ]'
chk "keine hängende Löschung" \
'[ -z "$(kubectl get site -o jsonpath="{.items[*].metadata.deletionTimestamp}")" ]'
chk "Webhook antwortet" \
'kubectl label site demo lab/ping=1 --overwrite --dry-run=server'
chk "Conversion verlustfrei" 'go test ./api/...'
chk "RBAC: Deployments anlegen" \
'[ "$(kubectl auth can-i create deployments --as=$SA -n default)" = yes ]'
chk "keine Waisen-Deployments" '[ -z "$(kubectl get deploy \
-l app.kubernetes.io/managed-by=site-operator \
-o custom-columns=N:.metadata.name,O:.metadata.ownerReferences[0].kind \
--no-headers | awk "\$2==\"<none>\"")" ]'
chk "keine StaticSite Degraded" '! kubectl get site -o jsonpath=\
"{.items[*].status.conditions[?(@.type==\"Degraded\")].status}" | grep -q True'
EOF
git add lab/schiedsrichter.sh && git commit -qm "Schiedsrichter"
bash lab/schiedsrichter.shErwartet:
✔ Operator liefert Metriken
✔ kein Hotloop (0 Reconciles in 5 s Ruhe)
✔ keine Reconcile-Fehler
✔ keine hängende Löschung
✔ Webhook antwortet
✔ Conversion verlustfrei
✔ RBAC: Deployments anlegen
✔ keine Waisen-Deployments
✔ keine StaticSite Degraded
Gegenprobe mit Drill 1 und 8 gleichzeitig eingebaut:
✘ kein Hotloop (0 Reconciles in 5 s Ruhe)
✘ keine Waisen-Deployments
Der Commit sorgt dafür, dass reset_bahn den
Schiedsrichter nicht mit wegräumt. Nach dem Wettkampf: Operator und
envtest-up mit Ctrl+C beenden.
Challenge
Mach Drill 2 zum Regressionstest: Ein envtest-Spec spielt den
Störenfried (20 Patches auf Spec und Annotation) und verlangt, dass
controller_runtime_reconcile_errors_total für
staticsite dabei nicht steigt. Mit der Störung aus Drill 2
muss er rot werden, ohne sie grün.
Hinweis: Die Metriken von controller-runtime liegen
in der globalen Registry metrics.Registry – auch im Test,
auch ohne Metrik-Port; Gather() liefert sie als
Protobuf-Familien.
Lösung
cat > internal/controller/conflict_test.go <<'EOF'
package controller
import (
"fmt"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
appsv1 "k8s.io/api/apps/v1"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/metrics"
)
// reconcileErrors liest controller_runtime_reconcile_errors_total{staticsite}.
func reconcileErrors() float64 {
mfs, err := metrics.Registry.Gather()
Expect(err).NotTo(HaveOccurred())
for _, mf := range mfs {
if mf.GetName() != "controller_runtime_reconcile_errors_total" {
continue
}
for _, m := range mf.GetMetric() {
for _, l := range m.GetLabel() {
if l.GetName() == "controller" && l.GetValue() == "staticsite" {
return m.GetCounter().GetValue()
}
}
}
}
return 0
}
var _ = Describe("Parallele Schreiber", func() {
It("erzeugen keine Reconcile-Fehler (Konflikte)", func(ctx SpecContext) {
ns := newNamespace(ctx)
site := newStaticSite(ns, "demo")
Expect(k8sClient.Create(ctx, site)).To(Succeed())
key := client.ObjectKeyFromObject(site)
Eventually(func() error {
return k8sClient.Get(ctx, key, &appsv1.Deployment{})
}).WithContext(ctx).Should(Succeed())
before := reconcileErrors()
for i := range 20 { // der Störenfried aus Drill 2
patch := []byte(fmt.Sprintf(`{"spec":{"replicas":%d},`+
`"metadata":{"annotations":{"lab/ping":"%d"}}}`, i%3+1, i))
Expect(k8sClient.Patch(ctx, site,
client.RawPatch(client.Merge.Type(), patch))).To(Succeed())
}
Consistently(reconcileErrors).WithContext(ctx).
WithTimeout(3 * time.Second).Should(Equal(before))
})
})
EOF
go test ./internal/controller/ -count=1 -ginkgo.focus=Parallele 2>&1 | tail -1
export NEU='Update(ctx, site, client.FieldOwner("site-operator"))'
perl -pi -e 's/Patch\(ctx, site, client\.MergeFrom\(orig\)\)/$ENV{NEU}/' \
internal/controller/status.go
go test ./internal/controller/ -count=1 -ginkgo.focus=Parallele 2>&1 | tail -1
git checkout -- internal/controller/status.goErwartet:
ok example.com/site-operator/internal/controller 9.493s
FAIL
Behalte den Test:
git add internal/controller/conflict_test.go && git commit -qm "Konflikt-Test".
Die Differenz before/nachher macht ihn unabhängig von
anderen Specs, die absichtlich Fehler erzeugen (Registrar-Ausfall aus
Tag 7). Die ganze Suite läuft damit weiter grün (live:
ok … 22.443s).
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Jeder Drill von heute gehört als Alarm ins Monitoring:
Reconcile-Rate pro Objekt,
reconcile_errors_total, Objekte mitdeletionTimestampälter als 10 min, Webhook-Latenz und -Fehler (apiserver_admission_webhook_rejection_count). - Ein Runbook pro Operator: Symptom → erster Befehl → Ursache → Notbremse. Die Bewertungstabelle oben ist der Anfang.
- Notbremsen (Finalizer entfernen, Webhook-Konfiguration löschen) nur mit Vier-Augen-Prinzip und Ticket: Sie umgehen genau die Schutzmechanismen, die du gebaut hast.
- Debug-Logs (
-zap-log-level=5) nur befristet einschalten; im Hotloop füllen sie Log-Pipelines in Minuten. - Übe Drills im Team-GameDay gegen eine Staging-Umgebung – mit Stoppuhr, wie heute.