Skip to content

Modul 17: Cloud Native: Docker & Kubernetes

Go in der Cloud nativ betreiben: Multi-Stage-Dockerfiles mit Distroless-Images, 12-Factor-Konfiguration mit sauberen Liveness- und Readiness-Endpoints, Kubernetes-Automatisierung mit client-go, Operatoren auf Basis von controller-runtime und kubebuilder, und Sidecars, Webhooks & CRDs als Erweiterungsmuster.

Fortschritt0/5 Lektionen
81

Multi-Stage-Dockerfiles & schlanke Go-Images

Lektion 81 von 100

Vom Go-Binary zum Container: »Kant & Kurve« zieht in die Cloud

Die Buchhandlung »Kant & Kurve« hat ihre API aus Modul 12 im Betrieb — bisher auf einem einzelnen VM-Server. Der Verkehr schwankt stark (Weihnachtsgeschäft!), und das Team entscheidet sich für Kubernetes. Der erste Schritt dorthin ist kleiner als gedacht und größer als unterschätzt: das Container-Image.

Go hat hier einen unfairen Vorteil: Der Compiler erzeugt statische Binaries. Ein Go-Service braucht im Container keine Laufzeit, keine Paketverwaltung, keine Shell — nur die Binary selbst. Während Node-Images schnell 900 MB und mehr wiegen, ist ein schlankes Go-Image mit scratch- oder Distroless-Basis oft unter 10 MB groß. Kleine Images bedeuten schnellere Pulls, schnellere Rollouts, kleinere Angriffsfläche und weniger Rechenzentren-Traffic. Das ist keine Kosmetik, sondern direkt spürbare Operations-Qualität.

Der Mechanismus dafür ist das Multi-Stage-Dockerfile: Eine Stufe baut mit dem vollen Go-Toolchain, die zweite Stufe kopiert nur die fertige Binary in ein minimales Laufzeit-Image. Was im Builder passiert (Quelltext, Module-Cache, Compiler), bleibt im Builder.

Multi-Stage heißt: Bau-Werkzeug bleibt draußen

Ein Docker-Image ist eine Reihe von Dateisystem-Schichten. Multi-Stage-Builds nutzen das aus: FROM golang:1.24-alpine AS build liefert Compiler und Module-Cache, FROM gcr.io/distroless/static-debian12:nonroot liefert nur noch eine minimale Laufzeit — inklusive CA-Zertifikaten, Zeitzonendaten und einem Nicht-Root-Nutzer, aber ohne Shell, ohne Paketmanager, ohne apk. Die fertige Binary wandert per COPY --from=build zwischen den Stufen. Alles, was nur zum Bauen nötig war, landet nie im ausgelieferten Image.

Das Dockerfile für die Bookstore-API

Hier das vollständige Multi-Stage-Dockerfile, wie es im Projekt liegen könnte:

# ---------- Stage 1: Builder ----------
FROM golang:1.24-alpine AS build
WORKDIR /src
# go.mod und go.sum zuerst: diese Schicht bleibt bei jedem Code-Commit gleich
# und der Module-Cache aus dem BuildKit-Cache-Mount wird wiederverwendet
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=v2.4.1" -o /out/bookstore-api ./cmd/bookstore-api

# ---------- Stage 2: Laufzeit ----------
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/bookstore-api /bookstore-api
USER nonroot
EXPOSE 8080
ENTRYPOINT ["/bookstore-api"]

Drei Details tragen die meiste Wirkung: CGO_ENABLED=0 erzwingt eine statische Binary (dazu gleich mehr), -ldflags "-s -w" streicht Debug-Symbole und spart rund 30 Prozent Binary-Größe, und -X main.version=v2.4.1 injiziert die Build-Nummer in eine Paketvariable — genau die, die unser Programm beim Start ausgibt:

// cmd/bookstore-api/main.go — Versionsstempel, den der Builder injiziert
package main

import (
	"fmt"
	"runtime"
)

// Diese Werte setzt der Docker-Build per -ldflags "-X main.version=…"
var (
	version   = "dev"
	buildTime = "unknown"
)

func main() {
	fmt.Println("bookstore-api", version, "build", buildTime, runtime.GOOS+"/"+runtime.GOARCH, "runtime", runtime.Version())
}
// → bookstore-api v2.4.1 build 2026-11-07T09:15:02Z linux/amd64 runtime go1.24.2

Im Incident-Fall laufen mehrere Pods mit unterschiedlichen Versionen (Rollout im Gange) — genau dieses Start-Logging klärt in einer Sekunde, welcher Pod welche Binary ausführt.

Kontrolle im Container: UID, CA-Zertifikate, Größe

Distroless-Images halten Zusagen, die man auch prüfen sollte. Ein Selbst-Check im Container — als go run-Helfer oder als Test in der CI, der das fertige Image startet:

// cmd/selfcheck/main.go — prüft, ob das Laufzeit-Image die Zusagen hält
package main

import (
	"fmt"
	"os"
	"os/user"
)

func main() {
	u, err := user.Current()
	if err != nil {
		fmt.Println("Fehler:", err)
		return
	}
	_, sslErr := os.Stat("/etc/ssl/certs/ca-certificates.crt")
	fmt.Printf("uid=%s gruppe=%s ssl-certs=%v", u.Uid, u.Gid, sslErr == nil)
}
// Terminal: docker run --rm bookstore-api:v2.4.1 /bookstore-api (bzw. im Pod)
// → uid=65532 gruppe=65532 ssl-certs=true

uid=65532 ist der nonroot-Nutzer der Distroless-Images — der Prozess läuft also nachweislich ohne Root-Rechte, und ssl-certs=true bestätigt, dass HTTPS-Aufrufe an externe APIs (Zahlungsdienst, Auslieferung) funktionieren. Der Größenvergleich am Ende des Builds:

docker image ls bookstore-api
REPOSITORY       TAG       SIZE
bookstore-api    v2.4.1    4.9 MB
bookstore-api    fat       913 MB   (alter Ein-Stage-Build auf golang:1.24-Basis)

4,9 MB statt 913 MB — ein Faktor von über 180, mit direktem Effekt auf Rollout-Geschwindigkeit und Angriffsfläche. Das Image lässt sich zusätzlich mit docker sbom (Software-Bill-of-Materials) und einem Scanner wie trivy auf bekannte CVEs prüfen; in der CI lohnt sich ausserdem ein Blick auf das ko-Projekt (github.com/ko-build/ko), das Go-Images direkt aus dem Modul-Hash baut und damit reproduzierbar macht.

⚠ Häufiger Fehler: Die Binary ist kopiert, der Pfad stimmt, der Start bricht trotzdem ab mit einer kryptischen Meldung wie no such file or directory — obwohl die Datei nachweislich existiert. Ursache ist fast immer ein dynamisch gelinktes Binary: Ohne CGO_ENABLED=0 verlinkt der Go-Compiler gegen die C-Bibliothek des Builders, und im scratch- oder Distroless-Image fehlt der dynamische Loader schlicht. Die Fehlermeldung des Kernels bezieht sich auf den Loader, nicht auf die Binary — daher die Verwirrung. Wer sicher ist, dass cgo nicht gebraucht wird (reines Go, keine sqlite- oder net-C-Pakete), baut immer mit CGO_ENABLED=0; Alternativen sind die Statisch-Link-Flags oder eine alpine-Laufzeit mit musl.

✅ Wichtige Erkenntnisse

Haken setzen, um deinen Lernfortschritt zu markieren:

    82

    12-Factor-Konfiguration & Health-Endpoints

    Lektion 82 von 100

    Konfiguration, die mit dem Cluster atmet

    »Kant & Kurve« läuft jetzt auf Kubernetes — und plötzlich ändert sich die Umgebung mit jedem Deployment: andere Datenbank-Hosts, andere Log-Level im Staging, andere Shard-Zahlen im Weihnachtsgeschäft. Eine Konfiguration, die zur Bauzeit gebrannt wird (Konfigurationsdatei im Image), erzwingt für jede Umgebung ein eigenes Image. Genau das verbietet der 12-Factor-Grundsatz Config: Konfiguration lebt in der Umgebung, nicht im Artefakt — ein Image, viele Umgebungen.

    Für Kubernetes ist das keine Empfehlung, sondern die native Sprache des Systems: ConfigMaps und Secrets landen als Umgebungsvariablen oder Dateien im Pod. Der Architektur-Kurs ordnet das Modell ein — Modul 3: Architekturstile behandelt 12-Factor ausdrücklich als Architektur-Stil mit Konsequenzen bis in die Deployment-Pipeline. Hier die Go-Seite davon.

    Defaults im Code, Werte in der Env, Geheimnisse nie im Image

    Drei Regeln reichen: 1) Sachliche Defaults (Port, Log-Level, Timeouts) gehören in den Code, damit der Service lokal ohne Zutun startet. 2) Umgebungsspezifische Werte (DSNs, Hostnamen, Shard-Zahlen) kommen aus der Env — os.LookupEnv statt os.Getenv, weil LookupEnv zwischen »nicht gesetzt« und »leer« unterscheidet. 3) Geheimnisse bekommen keinen Default und keinen Fallback: Fehlt das Datenbank-Passwort, startet der Service kontrolliert mit einer klaren Fehlermeldung, statt stillschweigend mit einem Leeren zu laufen.

    Konfiguration laden: LookupEnv, Validierung, klare Fehler

    Kein Framework nötig — die Standardbibliothek reicht für den Anfang völlig aus. Wer mehr will (Prefixes, Parsing, Defaults deklarativ), greift zu github.com/caarlos0/env/v11 oder zu Viper aus Modul 12 (github.com/spf13/viper); beide lösen dasselbe Problem, aber os.LookupEnv zeigt den Mechanismus ohne Magie:

    // internal/config/config.go — 12-Factor: Konfiguration aus der Umgebung
    package config
    
    import (
    	"fmt"
    	"os"
    	"strconv"
    )
    
    type Config struct {
    	HTTPAddr    string
    	LogLevel    string
    	Shards      int
    	DatabaseDSN string
    }
    
    func FromEnv() (Config, error) {
    	cfg := Config{
    		HTTPAddr: getEnv("BOOKSTORE_HTTP_ADDR", ":8080"),
    		LogLevel: getEnv("BOOKSTORE_LOG_LEVEL", "info"),
    		// Geheimnisse: kein Default, keine Vermutungen
    		DatabaseDSN: os.Getenv("BOOKSTORE_DB_DSN"),
    	}
    	shards, err := getEnvInt("BOOKSTORE_SHARDS", 8)
    	if err != nil {
    		return Config{}, err
    	}
    	cfg.Shards = shards
    
    	if cfg.DatabaseDSN == "" {
    		return Config{}, fmt.Errorf("BOOKSTORE_DB_DSN fehlt — Konfiguration kommt aus der Env, nicht aus dem Image")
    	}
    	return cfg, nil
    }
    
    func getEnv(key, fallback string) string {
    	if v, ok := os.LookupEnv(key); ok && v != "" {
    		return v
    	}
    	return fallback
    }
    
    func getEnvInt(key string, fallback int) (int, error) {
    	v, ok := os.LookupEnv(key)
    	if !ok || v == "" {
    		return fallback, nil
    	}
    	n, err := strconv.Atoi(v)
    	if err != nil {
    		return 0, fmt.Errorf("%s=%q ist keine ganze Zahl: %w", key, v, err)
    	}
    	return n, nil
    }
    
    // Beispiel: BOOKSTORE_SHARDS=16 BOOKSTORE_DB_DSN=postgres://prod... ./bookstore-api
    // → cfg: addr=:8080 log_level=info shards=16 db=postgres://prod… (Quelle: Env)
    

    Health-Endpoints: Liveness und Readiness sind verschieden

    Kubernetes stellt zwei fundamentale Fragen an jeden Pod, und sie verdienen unterschiedliche Antworten: Lebt der Prozess noch? (Liveness) und Kann er Traffic annehmen? (Readiness). Ein Go-Service, der beim SIGTERM sauber drainiert (Modul 15), braucht dafür genau zwei Routen — und die Disziplin, dort unterschiedliche Dinge zu prüfen:

    // internal/health/health.go — Liveness und Readiness sauber trennen
    package health
    
    import (
    	"context"
    	"encoding/json"
    	"net/http"
    	"sync"
    	"time"
    
    	"golang.org/x/sync/errgroup"
    )
    
    type Checker func(ctx context.Context) error
    
    // Liveness: lebt der Prozess selbst? Bewusst KEINE Abhängigkeiten prüfen.
    func Liveness(w http.ResponseWriter, _ *http.Request) {
    	w.WriteHeader(http.StatusOK)
    }
    
    // Readiness: können wir Traffic annehmen? Abhängigkeiten prüfen, mit Timeout.
    func Readiness(checks map[string]Checker) http.HandlerFunc {
    	return func(w http.ResponseWriter, r *http.Request) {
    		ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    		defer cancel()
    
    		var mu sync.Mutex
    		results := make(map[string]string, len(checks))
    		g, gctx := errgroup.WithContext(ctx)
    		for name, check := range checks {
    			g.Go(func() error {
    				err := check(gctx)
    				mu.Lock()
    				defer mu.Unlock()
    				if err != nil {
    					results[name] = err.Error()
    					return nil // sammeln, nicht abbrechen: wir wollen das Gesamtbild
    				}
    				results[name] = "ok"
    				return nil
    			})
    		}
    		_ = g.Wait()
    
    		status := http.StatusOK
    		for _, v := range results {
    			if v != "ok" {
    				status = http.StatusServiceUnavailable
    			}
    		}
    		w.Header().Set("Content-Type", "application/json")
    		w.WriteHeader(status)
    		_ = json.NewEncoder(w).Encode(results)
    	}
    }
    
    // Terminal: curl -s localhost:8080/readyz   (Suchdienst gerade down)
    // → {"database":"ok","payments":"ok","search":"dial tcp 10.2.7.44:9200: connect: connection refused"}
    

    Dazu die passenden Probes im Deployment: livenessProbe auf /healthz (lieber großzügig: failureThreshold: 5), readinessProbe auf /readyz (streng: bei 503 nimmt der Service den Pod sofort aus den Endpoints der Services, ohne ihn neu zu starten). Beobachtbar wird das Ganze über die Events des Clusters — genau die lernen wir in der nächsten Lektion mit client-go selbst zu lesen.

    ⚠ Häufiger Fehler: In die Liveness-Probe werden Datenbank-Pings und andere Abhängigkeits-Checks eingebaut — schließlich will man ja wissen, ob »alles gut« ist. Wenn dann die Datenbank kurz hakt, sprechen alle Pods gleichzeitig unhealthy, und das Kubelet startet alle Pods neu — ein Neustart-Sturm, der die Datenbank bei jedem Hochkommen zusätzlich belastet und den Ausfall verstärkt statt abzufedern. Liveness bedeutet nur »Prozess hängt nicht endgültig« (Deadlocks, GC-Kollaps), Readiness bedeutet »nimm mich aus dem Loadbalancing, bis ich wieder kann«. Abhängigkeits-Checks gehören ausschließlich in /readyz.

    ✅ Wichtige Erkenntnisse

    Haken setzen, um deinen Lernfortschritt zu markieren:

      83

      client-go: Pods, Deployments & Events automatisieren

      Lektion 83 von 100

      Vom kubectl zum eigenen Go-Programm

      Das Ops-Team von »Kant & Kurve« tippt jeden Morgen dieselben drei kubectl-Befehle: Pods listen, Events der letzten Nacht sichten, den Worker skalieren. Das ist der Moment, in dem sich client-go auszahlt: Dieselbe API, die kubectl benutzt, ist als Go-Bibliothek verfügbar — k8s.io/client-go, das offizielle Kubernetes-Go-Client-Paket, gepflegt im Kubernetes-Projekt selbst. Alles, was kubectl kann, kann auch Ihr Go-Programm: lesen, schreiben, watchen, skalieren.

      Der Schlüssel zum Code ist die Architektur der Kubernetes-API: Sie ist ein typisierter REST-Dienst. client-go übersetzt das in Go-Typen aus k8s.io/api/core/v1 (Pods, Events, Services) und k8s.io/apimachinery (Optionen, Labels). Ein Clientset (k8s.io/client-go/kubernetes) bündelt die typisierten Clients für alle Kern-Objekte; für eigene Ressourcen wie CRDs kommt später in Lektion 84 ein generischer Client ins Spiel.

      Zwei Wege zur Cluster-Config — und einer entscheidet von selbst

      Ein Programm, das im Pod läuft, authentifiziert sich über den ServiceAccount des Pods: rest.InClusterConfig() liest Token und CA aus /var/run/secrets/kubernetes.io/serviceaccount/. Dasselbe Programm auf dem Laptop nimmt stattdessen die KUBECONFIG-Datei. Der etablierte Trick ist die Reihenfolge: erst InClusterConfig versuchen, dann auf die lokale kubeconfig zurückfallen — dann läuft ein Binary überall. Für Rollen und Rechte gilt: Der ServiceAccount braucht ein RBAC-ClusterRole/Role-Binding mit genau den Verben (get, list, watch), die das Programm benutzt — nicht mehr.

      Pods auflisten: Client bauen, typisiert lesen

      Das erste Automatisierungs-Programm listet alle Bookstore-Pods in einem Namespace und entscheidet selbst, woher die Cluster-Konfiguration kommt:

      // cmd/kube-report/main.go — Pods auflisten: In-Cluster zuerst, kubeconfig als Fallback
      package main
      
      import (
      	"context"
      	"fmt"
      
      	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
      	"k8s.io/client-go/kubernetes"
      	"k8s.io/client-go/rest"
      	"k8s.io/client-go/tools/clientcmd"
      )
      
      func newClientset() (*kubernetes.Clientset, error) {
      	if cfg, err := rest.InClusterConfig(); err == nil {
      		return kubernetes.NewForConfig(cfg) // im Pod: ServiceAccount
      	}
      	loading := clientcmd.NewDefaultClientConfigLoadingRules()
      	cfg, err := clientcmd.
      		NewNonInteractiveDeferredLoadingClientConfig(loading, &clientcmd.ConfigOverrides{}).
      		ClientConfig()
      	if err != nil {
      		return nil, err
      	}
      	return kubernetes.NewForConfig(cfg) // lokal: ~/.kube/config
      }
      
      func main() {
      	cs, err := newClientset()
      	if err != nil {
      		fmt.Println("kein Cluster erreichbar:", err)
      		return
      	}
      	ctx := context.Background()
      	pods, err := cs.CoreV1().Pods("production").
      		List(ctx, metav1.ListOptions{LabelSelector: "app.kubernetes.io/name=bookstore"})
      	if err != nil {
      		fmt.Println("List-Fehler:", err)
      		return
      	}
      	for _, p := range pods.Items {
      		fmt.Printf("%-45s %s", p.Name, p.Status.Phase)
      	}
      }
      // → bookstore-api-7d9c5b6f4-kvj2m                   Running
      // → bookstore-api-7d9c5b6f4-q8x7p                   Running
      // → bookstore-worker-59df7d8bc-2nll4                Running
      

      Events live beobachten: Watch statt Polling

      Die Morgensichtung der Events ist der zweite Klassiker. Statt alle dreissig Sekunden List aufzurufen (das belastet den API-Server und verpasst trotzdem Events zwischen zwei Abfragen), öffnet man einen Watch: eine HTTP-Verbindung, auf der der API-Server Änderungen als Stream schickt:

      // cmd/kube-events/main.go — Events als Stream lesen
      package main
      
      import (
      	"context"
      	"fmt"
      
      	corev1 "k8s.io/api/core/v1"
      	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
      )
      
      func watchEvents(ctx context.Context, cs *kubernetes.Clientset) error {
      	watcher, err := cs.CoreV1().Events("production").Watch(ctx, metav1.ListOptions{})
      	if err != nil {
      		return err
      	}
      	defer watcher.Stop()
      
      	for event := range watcher.ResultChan() {
      		e, ok := event.Object.(*corev1.Event)
      		if !ok {
      			continue // Statusmeldungen des Watch ignorieren
      		}
      		fmt.Printf("%-7s %-14s %s", string(event.Type), e.Reason, e.InvolvedObject.Name)
      	}
      	return nil
      }
      // → ADDED   Scheduled     bookstore-api-7d9c5b6f4-kvj2m
      // → ADDED   Pulling       bookstore-api-7d9c5b6f4-kvj2m
      // → ADDED   Unhealthy     bookstore-api-7d9c5b6f4-kvj2m
      // → MODIFIED BackOff       bookstore-worker-59df7d8bc-2nll4
      

      Der rohe Watch hat zwei Schwächen, die man kennen muss: Die Verbindung reißt regelmäßig (Timeout, Netzwerk-Wartung), und nach einem Riss muss die Anwendung selbstständig neu verbinden und die verpassten Events über die resourceVersion nachziehen. Für Produktionscode sind deshalb Informer die richtige Abstraktion (k8s.io/client-go/informers): Ein SharedInformerFactory hält einen lokalen Cache des gewünschten Objekttyps, verbindet Watch und Re-Sync automatisch neu und ruft Ihre Callbacks (AddFunc, UpdateFunc, DeleteFunc) auf. Mehrere Controller im selben Prozess teilen sich dieselbe Factory und damit dieselbe Verbindung — deshalb shared. Wer bloß gelegentlich abfragt, bleibt beim einfachen Clientset; wer kontinuierlich reagiert, nimmt Informer. Und auch das Skalieren ist ein Einzeiler: cs.AppsV1().Deployments("production").Update(...) mit angepasster Spec.Replicas — dieselbe Operation, die kubectl scale macht. Die konzeptionelle Einordnung von Automatisierung und Skalierung als Plattform-Aufgabe leistet der Architektur-Kurs in Modul 7: Skalierbarkeit.

      ⚠ Häufiger Fehler: Eine for-Schleife mit time.Sleep(2 * time.Second) und List in jedem Durchlauf — »Watch ist doch nur Komfort«. Diese Polling-Schleife skaliert katastrophal: Jeder Durchlauf serialisiert und überträgt die komplette Objektliste vom API-Server, bei zehn solcher Programme spricht der Cluster auf seinem eigenen Control-Plane-Traffic an. Verschärft wird es, wenn die Schleife ausserdem pro Durchlauf einen neuen Clientset oder gar eine neue HTTP-Verbindung aufbaut. Für kontinuierliche Beobachtung gehören Watch respektive Shared-Informer mit lokalem Cache her — und der Clientset wird einmal beim Programmstart gebaut.

      ✅ Wichtige Erkenntnisse

      Haken setzen, um deinen Lernfortschritt zu markieren:

        84

        Operatoren mit controller-runtime & kubebuilder

        Lektion 84 von 100

        Der Wunsch nach einer eigenen Ressource

        Das Team wünscht sich für jede Buchhandlung-Filiale eine Kubernetes-Ressource, die alles Notwendige bündelt: Deployment, Service, Ingress mit Filial-Hostname, HPA-Grenzen. YAML-Templates kopieren ist wartungsanfällig; Helm-Charts helfen beim ersten Deployment, aber nicht beim Betrieb (Ressource driftet, niemand gleicht ab). Die Kubernetes-Antwort auf wiederkehrende Betriebslogik ist der Operator: eine Custom Resource Definition (CRD) plus ein Controller-Prozess, der den gewünschten Zustand (Spec) kontinuierlich mit dem tatsächlichen Zustand (Status) abgleicht.

        Gebaut wird das seit Jahren mit sigs.k8s.io/controller-runtime, gescaffoldt mit kubebuilder (aktuell Plugin kubebuilder v4 beziehungsweise der go/v4-Skeleton). Das Werkzeug erzeugt CRD-YAML, RBAC-Manifeste, den Manager-Rahmen und eine Reconcile-Funktion — die eigentliche Domain-Logik bleibt Ihre Aufgabe.

        Level-triggered, nicht edge-triggered

        Der Reconcile-Loop wird nicht »pro Event einmal« aufgerufen, sondern so oft, bis der Zustand passt — und danach zusätzlich periodisch oder nach RequeueAfter. Das nennt man level-triggered: Die Funktion schaut auf den aktuellen Stand (»Wie viele Replicas sind deployed?«), nicht auf ein Ereignis (»Replicas wurde geändert auf…«). Daraus folgt die wichtigste Regel für Operator-Code: Reconcile muss idempotent sein und aus Ist- und Soll-Zustand entscheiden. Wer Events mitzählt oder auf »nur beim ersten Mal«-Flags setzt, verliert, sobald der Loop nach einem Timeout erneut läuft — und er läuft erneut, garantiert.

        Der Reconciler: Wunschzustand herstellen

        Unser Website-Operator: Die CR beschreibt Filiale, Image und Replica-Zahl; der Reconciler stellt das zugehörige Deployment sicher und setzt Status und Conditions zurück in die CR:

        // internal/controller/website_controller.go — der Kern des Operators
        package controller
        
        import (
        	"context"
        	"fmt"
        
        	appsv1 "k8s.io/api/apps/v1"
        	"k8s.io/apimachinery/pkg/api/errors"
        	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
        	"k8s.io/utils/ptr"
        	ctrl "sigs.k8s.io/controller-runtime"
        	"sigs.k8s.io/controller-runtime/pkg/client"
        	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
        	"sigs.k8s.io/controller-runtime/pkg/reconcile"
        
        	bookstorev1 "github.com/kant-kurve/bookstore-operator/api/v1"
        )
        
        // +kubebuilder:rbac:groups=bookstore.kant-kurve.de,resources=websites,verbs=get;list;watch;update
        // +kubebuilder:rbac:groups=bookstore.kant-kurve.de,resources=websites/status,verbs=get;update;patch
        // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
        
        func (r *WebsiteReconciler) Reconcile(ctx context.Context, req reconcile.Request) (ctrl.Result, error) {
        	// 1) Wunsch lesen — NotFound ist normal (gelöschte CR), kein Fehler
        	var site bookstorev1.Website
        	if err := r.Get(ctx, req.NamespacedName, &site); err != nil {
        		if errors.IsNotFound(err) {
        			return ctrl.Result{}, nil
        		}
        		return ctrl.Result{}, err
        	}
        
        	// 2) Soll-Zustand berechnen und Ist-Zustand abgleichen (CreateOrUpdate = idempotent)
        	want := &appsv1.Deployment{
        		ObjectMeta: metav1.ObjectMeta{Namespace: site.Namespace, Name: site.Name + "-dep"},
        	}
        	if _, err := controllerutil.CreateOrUpdate(ctx, r.Client, want, func() error {
        		want.Spec.Replicas = ptr.To(site.Spec.Replicas)
        		want.Spec.Selector = selectorFor(&site)
        		want.Spec.Template = podTemplateFor(&site)
        		return controllerutil.SetControllerReference(&site, want, r.Scheme)
        	}); err != nil {
        		return ctrl.Result{}, fmt.Errorf("Deployment synchronisieren: %w", err)
        	}
        
        	// 3) Beobachteten Zustand zurück in die CR schreiben
        	site.Status.ReadyReplicas = want.Status.ReadyReplicas
        	if err := r.Status().Update(ctx, &site); err != nil {
        		return ctrl.Result{}, err // Konflikt? Nächster Loop löst es — level-triggered
        	}
        
        	// 4) Regelmäßig nachfassen, auch ohne Events
        	return ctrl.Result{RequeueAfter: resyncInterval(site)}, nil
        }
        // Terminal: kubectl get websites -n production
        // → NAME           REPLICAS   READY   IMAGE                                        HOSTNAME
        // → kant-kurve-de  3          3/3     ghcr.io/kant-kurve/bookstore-api:v2.4.1     kant-kurve.de
        

        Die +kubebuilder:rbac-Kommentare sind übrigens keine Deko: kubebuilder generiert daraus die RBAC-Manifeste des Operators — Rechte als Code, direkt neben der Logik, die sie braucht.

        Der Manager: Cache, Leader-Election, Start

        Der zweite Baustein ist der Rahmen: ctrl.NewManager verbindet den Cache (dieselbe Informer-Technik aus Lektion 83!), Leader-Election für Mehrfach-Instanzen und den Controller-Server. Nach dem Scaffolden bleibt davon überrasch wenig Eigenes:

        // cmd/main.go — Manager starten und Controller registrieren
        package main
        
        import (
        	"os"
        
        	ctrl "sigs.k8s.io/controller-runtime"
        	"sigs.k8s.io/controller-runtime/pkg/log/zap"
        
        	"github.com/kant-kurve/bookstore-operator/internal/controller"
        )
        
        var setupLog = ctrl.Log.WithName("setup")
        
        func main() {
        	ctrl.SetLogger(zap.New(zap.UseDevMode(false)))
        
        	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{})
        	if err != nil {
        		setupLog.Error(err, "Manager lässt sich nicht starten")
        		os.Exit(1)
        	}
        
        	if err := (&controller.WebsiteReconciler{
        		Client: mgr.GetClient(), // Lesezugriffe laufen über den Cache
        		Scheme: mgr.GetScheme(),
        	}).SetupWithManager(mgr); err != nil {
        		setupLog.Error(err, "Controller-Registrierung")
        		os.Exit(1)
        	}
        
        	setupLog.Info("Manager startet")
        	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        		setupLog.Error(err, "Manager beendet mit Fehler")
        		os.Exit(1)
        	}
        }
        // → Manager startet: website-controller registriert, Cache synced, Leader-Election aktiv
        

        Testen lässt sich das ohne Cluster-Spezialwissen mit envtest (sigs.k8s.io/controller-runtime/pkg/envtest): Es startet kube-apiserver und etcd als Binaries und führt echte Reconcile-Durchläufe gegen die eigene CRD aus — Controller-Tests, die tatsächlich die Kubernetes-Semantik prüfen. Der strategische Kontext — wann sich ein Operator lohnt und was Automatisierung über alle Ebenen bedeutet — gehört zu den Skalierbarkeits-Entscheidungen, die der Architektur-Kurs in Modul 7: Skalierbarkeit behandelt.

        ⚠ Häufiger Fehler: Reconcile-Code, der davon ausgeht, »genau einmal pro Änderung« aufgerufen zu werden — zum Beispiel ein if site.Status.Phase == ""-Init-Block, der Konfiguration nur beim ersten Durchlauf setzt, oder Fehler ohne Rückgabe, sodass kein Requeue passiert und der Zustand still driftet. controller-runtime ruft Reconcile jederzeit erneut auf: nach Timeout, nach Cache-Resync, nach verlorenem Leader-Election-Rennen, nach Konflikt beim Status-Update. Nur idempotente Logik, die jedes Mal komplett aus Spec und beobachtetem Zustand ableitet (und mit RequeueAfter periodisch nachfasst), überlebt diesen Vertrag; alles andere funktioniert in der Demo und fällt im Betrieb durch.

        ✅ Wichtige Erkenntnisse

        Haken setzen, um deinen Lernfortschritt zu markieren:

          85

          Sidecars, Webhooks & CRDs als Erweiterungsmuster

          Lektion 85 von 100

          Drei Wege, Kubernetes zu erweitern — und wann welcher passt

          Der Operator aus Lektion 84 ist nur eines von drei großen Erweiterungsmustern, die Kubernetes mitbringt — und die Entscheidung zwischen ihnen ist eine Architektur-Entscheidung, kein Go-Detail. Die Daumenregeln:

          • Sidecar (zweiter Container im selben Pod): erweitert einen Pod um eine Fähigkeit, ohne dass die Applikation davon weiss — Log-Shipping, TLS-Terminierung, Proxy zu Legacy-Systemen. Der Service-Mesh-Gedanke (Envoy-Sidecars bei Istio/Linkerd) ist genau dieses Muster in Serie.
          • Admission-Webhook (validierend oder mutierend): erweitert die Plattform-Politik — jede Objekt-Anfrage kann geprüft oder mit Defaults angereichert werden, bevor sie ins etcd darf. Zentral, clusterweit, ohne eigene Prozess-Typen.
          • CRD + Operator: erweitert das Ressourcen-Modell — ein neuer Objekttyp mit eigener Betriebslogik, wenn Deployment/Service/ConfigMap nicht mehr ausreichen.

          Erweiterungsmuster nach Reichweite wählen

          Die drei Muster unterscheiden sich in der Reichweite: Der Sidecar wirkt pro Pod und ist sofort rückbaubar (Container aus dem Pod-Manifest streichen); der Webhook wirkt clusterweit auf jede Anfrage seines Match-Bereichs — mächtig und riskant zugleich, weil ein Fehler den API-Zugriff blockiert; die CRD schafft ein neues, versionierbares Domänen-Objekt mit eigenem Lifecycle. Faustregel: Pod-lokale Belange (Logs, TLS, Protokoll-Übersetzung) → Sidecar; organisationsweite Regeln (Limits, Verbote, Defaults) → Webhook; neue Domänen-Objekte mit Betriebslogik (»eine Filiale«, »ein Datenbank-Cluster«) → CRD mit Operator.

          Mutierender Webhook: Defaults, bevor etcd sie sieht

          Das Plattform-Team will, dass jedes neue Deployment automatisch Resource-Requests und ein revisionHistoryLimit bekommt — nachträgliche Korrekturen sind zäh. Ein mutierender Webhook mit controller-runtime (sigs.k8s.io/controller-runtime/pkg/webhook/admission) fängt CREATE-Anfragen ab und schreibt die Patches in die Antwort:

          // internal/webhook/deployment_mutator.go — Defaults injizieren bei CREATE
          package webhook
          
          import (
          	"context"
          	"encoding/json"
          	"net/http"
          
          	appsv1 "k8s.io/api/apps/v1"
          	"k8s.io/utils/ptr"
          	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
          )
          
          // +kubebuilder:webhook:path=/mutate-apps-v1-deployment,mutating=true,failurePolicy=Fail,groups=apps,resources=deployments,verbs=create,versions=v1,name=mdeployment.kb.io
          
          type DeploymentMutator struct {
          	decoder *admission.Decoder
          }
          
          func (m *DeploymentMutator) Handle(_ context.Context, req admission.Request) admission.Response {
          	dep := appsv1.Deployment{}
          	if err := m.decoder.Decode(req, &dep); err != nil {
          		return admission.Errored(http.StatusBadRequest, err)
          	}
          	if dep.Spec.RevisionHistoryLimit == nil {
          		dep.Spec.RevisionHistoryLimit = ptr.To(int32(3)) // Rollout-Historie begrenzen
          	}
          
          	marshaled, err := json.Marshal(dep)
          	if err != nil {
          		return admission.Errored(http.StatusInternalServerError, err)
          	}
          	return admission.PatchResponseFromRaw(req.Object.Raw, marshaled)
          }
          // Terminal: kubectl apply -f api-deployment.yaml (ohne Limits eingereicht)
          // → deployment.apps/bookstore-api created (Webhook mdeployment.kb.io hat revisionHistoryLimit=3 ergänzt)
          

          Validierende Webhooks sehen identisch aus, nur mit admission.Denied(...) statt Patch-Antwort — etwa wenn spec.hostname bei einer Website fehlt. Und der Betriebshinweis, der dazugehört: Webhooks werden über den Webhook-Server des Managers auf TLS-Port 9443 ausgeliefert und über Konfigurations-Objekte registriert; die Zertifikate besorgt in der Regel cert-manager.

          Sidecar in Go: Log-Shipper auf gemeinsamem Volume

          Auch ein Sidecar ist natürlich ein Go-Programm. Das klassische Setup: Die Applikation schreibt strukturierte Logs in eine Datei auf einem gemeinsamen emptyDir-Volume, der Sidecar liest und leitet weiter — die Applikation bleibt vollständig unberührt:

          // cmd/log-shipper/main.go — Sidecar: liest vom gemeinsamen Volume und leitet weiter
          package main
          
          import (
          	"bufio"
          	"fmt"
          	"os"
          	"time"
          )
          
          func main() {
          	file, err := os.Open("/var/log/bookstore/access.log")
          	if err != nil {
          		fmt.Println("open:", err)
          		os.Exit(1)
          	}
          	defer file.Close()
          
          	scanner := bufio.NewScanner(file)
          	for scanner.Scan() {
          		// shortcut: kein Tailen nach EOF — Produktion nutzt fluent-bit oder github.com/hpcloud/tail
          		fmt.Printf("shipper %s %s", time.Now().UTC().Format(time.RFC3339), scanner.Text())
          	}
          	if err := scanner.Err(); err != nil {
          		fmt.Println("scan:", err)
          		os.Exit(1)
          	}
          }
          // → shipper 2026-11-07T10:02:11Z GET /api/v1/books/978-3-423-2089-8 200 3ms
          

          Im Pod-Manifest lebt der Shipper als zweiter containers:-Eintrag mit volumeMounts auf dasselbe emptyDir; seit Kubernetes 1.29 gibt es ausserdem native Sidecars (initContainers mit restartPolicy: Always), die vor dem Hauptcontainer starten und mit ihm beendet werden — genau das, was Log- und Mesh-Sidecars vorher über Lifecycle-Hacks erreichen mussten. Wer kein eigenes Go-Binary betreiben will, nimmt für Logs fluent-bit, für Meshes Envoy — das Muster bleibt dasselbe, und es lohnt sich, es in Go einmal selbst gebaut zu haben.

          Damit schließt Modul 17. Die fünf Lektionen haben eine Kette gebildet: schlankes Image (81) → konfiguriert und beobachtbar (82) → automatisiert lesend (83) → automatisiert steuernd (84) → erweitert (85). Damit ist »Kant & Kurve« eine echte Cloud-Native-Anwendung — von der Binary bis zur eigenen Plattform-Ressource.

          ⚠ Häufiger Fehler: Ein Admission-Webhook mit failurePolicy: Fail und zu breitem Regel-Match — zum Beispiel alle Ressourcen aller Namensräume —, dessen Endpoint dann ausfällt. Folgen: Der API-Server lehnt jede Anfrage im Match-Bereich ab; je nach Match betreffen das auch die Mittel, die den Webhook reparieren würden (Deployments des Webhooks selbst, seine Konfiguration, sogar kubectl delete auf dem Webhook-Objekt). Betriebsempfehlung daher: Webhook-Bereiche eng fassen, den Webhook selbst und System-Namensräume ausnehmen, Timeouts niedrig ansetzen und für Übergangsphasen failurePolicy: Ignore erwägen, bis der Webhook seine Stabilität bewiesen hat.

          ✅ Wichtige Erkenntnisse

          Haken setzen, um deinen Lernfortschritt zu markieren:

            This site uses essential cookies for Stripe payments. No tracking cookies.