Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 15: Wettkampf – Debug-Drills

Ziel: Acht typische Operator-Fehler unter Zeitdruck finden und beheben – mit Logs, Events, Conditions, Metriken und managedFields statt 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 git die 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 -1

Erwartet (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/bases

Webhooks (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.kubeconfig

Erwartet:

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.log

Erwartet (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 site

Erwartet:

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 --stat danach 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 --stat

Erwartet:

 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 -1

Erwartet:

FAIL

Tipp: -zap-log-level=5 zeigt die Debug-Logs von controller-runtime: LEVEL(-5) Reconciling und Reconcile successful pro Durchlauf – bei einem Hotloop hunderte pro Sekunde.

Lösung. Beide Änderungen zurück:

git checkout -- internal/controller/status.go \
  internal/controller/staticsite_controller.go

Jede 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 setzt meta.SetStatusCondition nur 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_bahn

Fortschritt 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 --stat

Erwartet:

 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
done

Symptome: 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.go

Operator neu starten, die Schleife von oben noch einmal laufen lassen:

grep -c 'Reconciler error' run.log

Erwartet:

0

Lessons:

  • Status-Writes per Status().Patch(ctx, obj, client.MergeFrom(orig)) – oder Server-Side Apply (Tag 4, Challenge). Update nur, 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_bahn

Fortschritt 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=5s

Symptome:

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 finalizer

Erwartet (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 alt

Erwartet:

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=alt

Lessons:

  • Nie pauschal finalizers: null patchen: 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") plus AddFinalizer für den neuen, dann ein Update.
  • Die zweite häufige Ursache: Der eigene Finalizer hängt, weil der externe Dienst ausfällt (Tag 7, /admin/outage). Dann zeigen Log und Degraded den Retry – hier hilft Warten oder Reparieren, nicht Patchen.
reset_bahn

Fortschritt 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.example

Symptome (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 --overwrite

Symptome (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 -issuer

Erwartet (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 --overwrite

Erwartet (umbrochen):

validatingwebhookconfiguration.admissionregistration.k8s.io/validating-webhook-
  configuration patched
staticsite.web.lab.example/demo labeled

Lessons:

  • failurePolicy: Fail plus ein einziger Operator-Pod heißt: Operator weg, API weg. In Produktion mindestens zwei Replikas, PodDisruptionBudget und ein namespaceSelector, der kube-system und 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 caBundle per Annotation cert-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_bahn

Fortschritt 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 --stat

Erwartet:

 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 TestRoundTrip

Erwartet (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 TestRoundTrip

Erwartet:

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_bahn

Fortschritt 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 --stat

Erwartet:

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>"
EOF

Symptome: 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.log

Erwartet (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 default

Erwartet:

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 name

Erwartet:

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 von role.yaml im Review lesen, nicht nur den Go-Code.
  • Fehlt list oder watch, ist es schlimmer: Der Informer startet nie, nach CacheSyncTimeout (2 min) bricht der Controller mit timed out waiting for cache to be synced ab.
  • Teste lokal immer als ServiceAccount (Token-Kubeconfig wie in Tag 11 und heute) – als system:masters findest du keinen RBAC-Fehler.
reset_bahn

Fortschritt 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 --stat

Erwartet:

 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.go

Erwartet:

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.log

Erwartet (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: NotFound ohne Hinweis, gefolgt von AlreadyExists.
  • 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: …} oder mgr.GetAPIReader() – beides kostet einen API-Call pro Zugriff.
reset_bahn

Fortschritt 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 --stat

Erwartet:

 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.go

Nach 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-by sind 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 waise

Fortschritt 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.sh

Erwartet:

✔ 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.go

Erwartet:

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 mit deletionTimestamp ä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.