Training Module

Kubernetes Operator härten: Admission- & Conversion-Webhooks mit Kubebuilder

In diesem 140-Minuten-Modul schließt ihr die Lücke, die das Modul Kubernetes Operator entwickeln mit Kubebuilder (Go) bewusst offengelassen hat: Dort reconciliert euer Controller jede CronTab anstandslos – egal ob cronSpec ein gültiger Cron-Ausdruck ist oder drei zufällige Sternchen, egal ob replicas negativ ist. Heute verschiebt ihr diese Regeln vom Reconciler an den Rand: an den API-Server selbst, über echte Admission-Webhooks. Los geht es mit dem Webhook-Scaffold: kubebuilder create webhook –group stable –version v1 –kind CronTab –defaulting –programmatic-validation ergänzt api/v1/crontab_webhook.go um dieselbe CronTab-CRD, die der Vorgängerkurs bereits angelegt hat – keine neue CRD, kein neues Beispiel. Im Kern des Moduls implementiert ihr einen Mutating-Webhook ( Default(ctx, obj), setzt replicas auf 1, wenn der Wert fehlt) und einen Validating-Webhook ( ValidateCreate/ValidateUpdate/ ValidateDelete, lehnt einen syntaktisch kaputten cronSpec und negative replicas direkt bei kubectl apply ab statt erst beim Beobachten eines nie feuernden Controllers). Beide Webhooks testet ihr nicht nur als isolierte Go-Funktionen, sondern über einen echten, lokal gestarteten API-Server mit echtem TLS-Webhook-Server via envtest – derselbe hohe Verifikationsgrad wie im Vorgängerkurs, jetzt zusätzlich mit einem echten HTTPS-Roundtrip durch den Admission-Mechanismus. Zum Abschluss der Conversion-Webhook: eine zweite, historische CRD-Version v1alpha1 mit einem umbenannten Feld (schedule statt cronSpec) – genau das Beispiel, das der CRD-Kurs als Ausblick genannt hatte –, über das Hub-und-Spoke-Modell (conversion.Hub/ Convertible, ConvertTo/ConvertFrom) konvertiert und ebenfalls per envtest real gegen den API-Server bewiesen: Ein als v1 angelegtes Objekt, über v1alpha1 gelesen, kommt mit korrekt umbenanntem Feld zurück – der API-Server hat den /convert-Endpunkt eures Managers tatsächlich aufgerufen. Voraussetzung ist das Modul “Kubernetes Operator entwickeln mit Kubebuilder (Go)” – Pflicht, wird hier nicht wiederholt. Die Session läuft komplett lokal über Minikube (–driver=docker), ohne Cloud-Account und ohne Kostenwirkung.

Format

140 Minuten, live (remote oder vor Ort), Input & vier Hands-on-Blöcke

Teilnehmende

Entwickler:innen, die ihren eigenen Kubernetes-Operator gegen falsche Eingaben und CRD-Versionsbrüche härten wollen

Voraussetzungen

Abgeschlossenes Modul “Kubernetes Operator entwickeln mit Kubebuilder (Go)” (Pflicht), lauffähige lokale Docker-Umgebung für Minikube

Warum dieses Training für deine Organisation wirkt

Vom Reconciler-Zufall zur Eingangskontrolle

Der Vorgängerkurs endete bewusst bei einem Reconciler, der jede CronTab kommentarlos akzeptiert. Dieses Modul liefert die Eingangskontrolle nach – am selben CronTab-Beispiel, nicht an einem neuen Spielzeug.

Echte Webhooks, echtes TLS

Default() und ValidateCreate() laufen im Hands-on nicht nur als isolierte Funktionsaufrufe, sondern hinter einem echten, per envtest lokal gestarteten Webhook-Server mit TLS-Zertifikat – derselbe Mechanismus, den ein produktiver Cluster nutzt.

Konversion bewiesen, nicht behauptet

Der Conversion-Webhook wird nicht nur als Go-Funktion getestet, sondern über einen echten v1-Write gefolgt von einem echten v1alpha1-Read gegen denselben envtest-API-Server – der API-Server ruft dafür tatsächlich den eigenen /convert-Endpunkt auf.

Was Teilnehmende mitnehmen

  • Das Webhook-Scaffold mit kubebuilder create webhook –defaulting –programmatic-validation auf einer bestehenden CRD anlegen, statt bei null anzufangen.
  • Einen Mutating-Webhook mit Default(ctx context.Context, obj *CronTab) error schreiben, der ein fehlendes Feld auf einen sinnvollen Default setzt, bevor das Objekt überhaupt gespeichert wird.
  • Einen Validating-Webhook mit ValidateCreate/ValidateUpdate/ValidateDelete schreiben, der strukturierte field.ErrorList-Fehler über apierrors.NewInvalid(…) zurückgibt – dieselben Fehlermeldungen, die kubectl apply am Terminal anzeigt.
  • Beide Webhooks über einen echten, per envtest lokal gestarteten API-Server und einen echten TLS-Webhook-Server end-to-end testen – kein direkter Funktionsaufruf, sondern ein echter Admission-Request über HTTPS.
  • Das Hub-und-Spoke-Konversionsmodell (conversion.Hub/conversion.Convertible, ConvertTo/ConvertFrom) an einem echten Feld-Umbenennungs-Fall (schedulecronSpec) implementieren.
  • Eine verlustbehaftete Feld-Konvertierung (ein Feld, das die alte Version gar nicht kennt) über eine Zwischenlager-Annotation round-trip-sicher machen, statt Daten stillschweigend zu verlieren.
  • Benennen, was dieses Modul bewusst nicht behandelt: Operator Lifecycle Manager (OLM) für Paketierung, Versionierung und Upgrade-Pfade – nur Ausblick, kein eigenes Hands-on.

Für wen dieses Modul ideal ist

  • • Entwickler:innen mit abgeschlossenem Modul “Kubernetes Operator entwickeln mit Kubebuilder (Go)” oder gleichwertigen Vorkenntnissen
  • • Alle, die im Kubebuilder-Kurs bewusst am “Admission-/Conversion-Webhooks nur benannt”-Punkt aufgehört haben und jetzt die fehlende Härtung nachholen wollen
  • • Teams, die einen eigenen Operator produktiv betreiben oder planen und wissen wollen, wie viel Aufwand echte Eingangskontrolle und CRD-Versionierung tatsächlich sind

Rahmendaten

  • • Dauer: 140 Minuten live (remote oder vor Ort)
  • • Format: Input, Live-Coding, vier Hands-on-Blöcke (Scaffold, Mutating-Webhook, Validating-Webhook & Test, Conversion-Webhook)
  • • Voraussetzungen: abgeschlossenes Modul “Kubernetes Operator entwickeln mit Kubebuilder (Go)” (Pflicht), lauffähige lokale Docker-Umgebung für Minikube, keine Cloud-Kostenwirkung

Modulaufbau & Agenda

  1. Kick-off & Abgrenzung (10 min): Rückbezug auf den ungeschützten Reconciler aus dem Vorgängerkurs, kein erneutes Reconciler-/envtest-Grundlagen-Repetitorium.

  2. Hands-on: Webhook-Scaffold (15 min, Hands-on): kubebuilder create webhook –group stable –version v1 –kind CronTab –defaulting –programmatic-validation, die generierte api/v1/crontab_webhook.go und die +kubebuilder:webhook-Marker einordnen.

  3. Hands-on: Mutating-Webhook implementieren (25 min, Hands-on): Default(ctx, obj) schreiben, replicas-Default setzen, gegen die bestehende Reconciler-Logik aus dem Vorgängerkurs abgrenzen.

  4. Hands-on: Validating-Webhook implementieren (25 min, Hands-on): ValidateCreate/ValidateUpdate/ValidateDelete, strukturierte Fehler über field.ErrorList und apierrors.NewInvalid.

  5. Hands-on: Testing mit envtest & echtem TLS-Webhook-Server (25 min, Hands-on): envtest.WebhookInstallOptions, ein Manager mit echtem Zertifikat, kubectl apply-Äquivalente Create-Requests, die tatsächlich über HTTPS beim eigenen Webhook-Server ankommen.

  6. Hands-on: Conversion-Webhook v1alpha1 → v1 (25 min, Hands-on): conversion.Hub/Convertible, ConvertTo/ConvertFrom, die Annotation-Technik für ein Feld, das die alte Version nicht kennt.

  7. Deployment, OLM-Ausblick & Abgrenzung (15 min): cert-manager als produktiver Ersatz für envtests Testzertifikate einordnen, failurePolicy: Fail vs. Ignore diskutieren; explizit NICHT behandelt: Operator Lifecycle Manager (OLM).

Dieses Modul setzt das Aufbaumodul Kubernetes Operator entwickeln mit Kubebuilder (Go) zwingend voraus. Reconciler, Status-Subresource und die CronTab-CRD aus diesem Vorgängerkurs gelten als bekannt und werden hier nicht neu erklärt – dieses Modul fügt Webhooks hinzu, es ersetzt den Reconciler nicht.

Was dieses Modul bewusst nicht behandelt: Der Operator Lifecycle Manager (OLM) für Paketierung, Versionierung und koordinierte Upgrade-Pfade eines Operators über einen ganzen Cluster hinweg – Modul 7 ordnet OLM kurz als Konzept ein (was es löst, wie es sich zu einem einzelnen make deploy verhält), aber es gibt in diesem Kurs kein eigenes OLM-Hands-on und keinen zugesagten Folgetermin dafür. Vertieft im Aufbaumodul Kubernetes Operator betreiben: Lifecycle-Management mit OLM weiter, direkt auf demselben crontab-operator samt Webhooks.

Hands-on Inhalte (Auszug)

Webhook-Scaffold

  • kubebuilder create webhook –group stable –version v1 –kind CronTab –defaulting –programmatic-validation auf der bestehenden CronTab-CRD ausführen
  • Die generierten +kubebuilder:webhook-Marker lesen: Pfad, failurePolicy, sideEffects, betroffene Operationen

Mutating- & Validating-Webhook

  • Default(ctx, cronTab *CronTab) error setzt replicas auf 1, wenn nil
  • ValidateCreate lehnt einen cronSpec ohne fünf Whitespace-getrennte Felder über field.Invalid ab

Testing mit echtem TLS-Webhook-Server

  • envtest.WebhookInstallOptions erzeugt Zertifikat, Host und Port automatisch – ein echter Manager horcht per HTTPS darauf
  • k8sClient.Create(ctx, ct) läuft durch den echten API-Server und den eigenen Mutating-/Validating-Webhook, kein direkter Funktionsaufruf

Conversion-Webhook v1alpha1 → v1

  • (*CronTab) Hub() markiert v1 als Konversions-Hub, ConvertTo/ConvertFrom in v1alpha1 übersetzen schedulecronSpec
  • Ein als v1 angelegtes Objekt, per v1alpha1-Client gelesen, kommt mit korrekt umbenanntem Feld zurück – bewiesen über den echten /convert-Endpunkt, nicht nur über einen direkten ConvertTo()-Aufruf

Dieses Modul ist Teil unserer Pilotphase. Gemeinsam mit euch definieren wir passende Metriken (z. B. Zeit vom Scaffold bis zum ersten grünen envtest-Lauf gegen den eigenen Webhook-Server) und werten sie im Anschluss transparent aus. Ergebnisse veröffentlichen wir, sobald sie belastbar sind.

Bereit, das Modul zu buchen?

Wir passen die Hands-on-Übung auf euren Erfahrungsstand und eure Zielumgebung an.

Academy Briefing anfragen