Willkommen im Trainingslager
Wenig lesen, viel tippen. Dieses Buch bringt dir bei, eigene Kubernetes-Operatoren in Go zu schreiben, zu testen, auszuliefern und zu betreiben. Du betreibst Cluster, kennst Deployments, RBAC und Helm, und du kannst Go. Bisher hast du Operatoren installiert – ab heute baust du sie.
Jeder Tag bringt einen Operator ein Stück weiter.
Nach zwei Aufwärm-Tagen mit client-go und controller-runtime wächst ab
Tag 3 der site-operator – vom leeren Kubebuilder-Gerüst bis
zum getesteten, versionierten, abgesicherten Controller mit Finalizer,
Webhooks und Metriken. An Tag 14 folgt mit dem bao-operator
ein zweiter, echter Operator gegen OpenBao.
Die Trainingsregeln
- Tippen, nicht kopieren. Jede Zeile einmal selbst. Die Finger lernen mit.
- Erwartet vergleichen. Nach jedem Schritt steht, was du sehen solltest. Weicht es ab, steckt dort die eigentliche Lektion.
- Reconcile denkt in Zuständen, nicht in Events. Wenn du dich fragst „welches Event war das?“, frag stattdessen „wie sieht die Welt gerade aus?”.
- Nie dein Cluster. Geübt wird gegen envtest.
source ~/op-lab/env.shsetztKUBECONFIGfest auf die Lab-Datei; ohne laufendes envtest trifft kein Befehl irgendetwas. - Kontrollpunkt bestehen. Erst wenn das Prüfskript nur ✔ zeigt, geht es weiter.
- Challenge allein lösen. Erst den Hinweis, dann die Lösung.
- Lab-Werte bleiben im Lab. Tokens wie
lab-rootsind Spielgeld. Echte Zugangsdaten kommen aus Secrets oder Umgebungsvariablen, nie in den Code.
Aufbau jedes Trainingstags
| Abschnitt | Zweck |
|---|---|
| Briefing | Das Nötigste in wenigen Stichpunkten, oft mit Skizze |
| Drills | Code und Befehle mit erwarteter Ausgabe, Schritt für Schritt |
| Kontrollpunkt | Prüfskript: baut es, sind die Tests grün, verhält sich der Operator? |
| Challenge | Eine Erweiterung ohne Anleitung, mit Lösung |
| Enterprise-Notiz | Was in Produktion und beim Kunden anders ist |
Der Trainingsplan
| Teil | Tag | Einheit | Operator des Tages |
|---|---|---|---|
| Fundament | 0 | Trainingsgelände: Kubebuilder, setup-envtest, envtest-up | – |
| 1 | Operator-Muster mit client-go: Informer, Lister, Workqueue | labelsync |
|
| 2 | controller-runtime ohne Kubebuilder: Manager, Builder, Watches | restarter |
|
| 3 | Kubebuilder-Projekt und erste CRD, Marker, controller-gen | site-operator |
|
| Eigene APIs | 4 | Reconcile richtig: Kinder, OwnerReferences, Idempotenz | site-operator |
| 5 | Status und Conditions, Events, Printer-Columns | site-operator |
|
| 6 | Tests mit envtest: Ginkgo, Eventually, Coverage | site-operator |
|
| Profi-Werkzeuge | 7 | Finalizer und externe Ressourcen | site-operator + registrar |
| 8 | Validierung: OpenAPI, CEL, Webhooks | site-operator |
|
| 9 | API-Versionen und Conversion: v1alpha1 nach v1 | site-operator |
|
| 10 | Watches, Predicates, Indexer | site-operator |
|
| Produktion | 11 | RBAC, Leader Election, Metriken, Health | site-operator |
| 12 | Ausliefern: Image, Kustomize, Helm, OLM | site-operator |
|
| 13 | Skalierung und Robustheit: Konflikte, Backoff, Cache | site-operator |
|
| 14 | Praxis: OpenBao-Policy-Operator | bao-operator |
|
| 15 | Wettkampf: Debug-Drills | kaputte Operatoren | |
| Anhang | A | Spickzettel | – |
| B | Abschlussprüfung | – |
Die Schleife, um die sich alles dreht
+--------------------------------------------------------+
| |
v |
Watch-Event (Add/Update/Delete, Resync) |
| |
v |
Workqueue: "default/demo" (entdoppelt, Backoff pro Key) |
| |
v |
Reconcile(ctx, req) |
1. Soll lesen Get StaticSite "default/demo" |
2. Ist lesen Get ConfigMap, Deployment, Service (Cache) |
3. Angleichen Create / Update / Patch / Delete |
4. Status melden readyReplicas, url, Conditions |
| |
+-- Fehler ------------> Requeue mit Backoff ------------+
+-- RequeueAfter: 30s -> Requeue nach Zeit --------------+
+-- Erfolg ------------> fertig, bis zum nächsten Event
Reconcile weiß nicht, warum es aufgerufen wurde. Es liest den ganzen Zustand und gleicht an – egal ob einmal oder zehnmal. Das nennt man level-based und idempotent.
Der site-operator
Eine StaticSite beschreibt eine statische Webseite. Der
Operator erzeugt daraus drei Objekte, alle mit OwnerReference – löschst
du die Site, räumt die Garbage Collection auf:
StaticSite "demo" (web.lab.example/v1alpha1)
spec: content | contentFrom.configMapRef.name, replicas, image, path
status: readyReplicas, url, observedGeneration, conditions
|
| ownerReferences (controller: true)
+--> ConfigMap "demo-content" index.html aus spec.content
+--> Deployment "demo" nginx-unprivileged, Port 8080,
| Annotation web.lab.example/content-hash
+--> Service "demo" Port 80 -> 8080
url: http://demo.<ns>.svc
Finalizer web.lab.example/finalizer (Tag 7) --> registrar :18090
PUT/DELETE /records/demo
Das Trainingsgelände
Alles läuft lokal auf deinem Mac: Go 1.26, Kubebuilder, envtest
(kube-apiserver und etcd als Prozesse),
kubectl. Docker und ein echter Cluster sind nicht nötig; kind taucht an
Tag 12 nur als Option auf. Arbeitsverzeichnis ist ~/op-lab,
ein Unterordner pro Tag. Die fertigen Stände aller Tage liegen zum
Vergleich im Ordner code/ des Buch-Repos.
Tipp: Getestet mit Go 1.26.9 auf macOS (Apple Silicon), Kubebuilder v4.16.0, controller-runtime v0.25.0, controller-gen v0.22.0 und Kubernetes-API v0.37 (envtest 1.37.0). Wenn ein Befehl abweicht:
kubebuilder --help,go doc sigs.k8s.io/controller-runtime/pkg/..., book.kubebuilder.io und pkg.go.dev.
Der Begleitcode
Alle Dateien aus diesem Buch liegen öffentlich auf GitHub: https://github.com/thomaszachmann/kubernetes-operatoren-zum-anfassen. Wie du sie holst, zeigt Tag 0.
Los geht’s.
Thomas Zachmann, Oktober 2026