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.
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: OhneCGO_ENABLED=0verlinkt der Go-Compiler gegen die C-Bibliothek des Builders, und imscratch- 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, dasscgonicht gebraucht wird (reines Go, keinesqlite- odernet-C-Pakete), baut immer mitCGO_ENABLED=0; Alternativen sind die Statisch-Link-Flags oder einealpine-Laufzeit mitmusl.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
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:
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 mittime.Sleep(2 * time.Second)undListin 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:
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 mitRequeueAfterperiodisch 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:
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: Failund 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, sogarkubectl deleteauf dem Webhook-Objekt). Betriebsempfehlung daher: Webhook-Bereiche eng fassen, den Webhook selbst und System-Namensräume ausnehmen, Timeouts niedrig ansetzen und für ÜbergangsphasenfailurePolicy: Ignoreerwägen, bis der Webhook seine Stabilität bewiesen hat.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: