Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: controller-runtime ohne Kubebuilder

Ziel: restarter startet Deployments neu, sobald sich eine referenzierte ConfigMap ändert – mit Manager, Reconciler und Builder aus controller-runtime · Dauer: ca. 120 min · Voraussetzung: Tag 1

Briefing

  • controller-runtime packt Tag 1 in Bausteine: Manager (Cache, Client, Lebenszyklus), Controller (Queue, Worker) und dein Reconciler.
  • Du schreibst nur noch Reconcile(ctx, req): Es bekommt Namespace/Name, liest selbst und gleicht an.
  • Der Builder verdrahtet Watches: For (Hauptobjekt), Owns (eigene Kinder, ab Tag 4), Watches (fremde Objekte mit Mapping).
  • Rückgabe statt Queue-Aufrufe: err != nil heißt Retry mit Backoff, nil heißt Forget.
  • client.Client liest aus dem Cache und schreibt direkt an den API-Server.
 Tag 1 (client-go)                      Tag 2 (controller-runtime)
 ------------------------------------   ---------------------------------------
 SharedInformerFactory + Lister         Manager-Cache, mgr.GetClient().Get/List
 AddEventHandler -> queue.Add(key)      Builder: For / Owns / Watches
 Workqueue + Worker + processNext       Controller (intern, gleiche Workqueue)
 sync(key) error                        Reconcile(ctx, req) (Result, error)
 AddRateLimited / Forget                return err / return nil
 signal.NotifyContext                   ctrl.SetupSignalHandler()

Drill 1: Modul anlegen

source ~/op-lab/env.sh
mkdir -p ~/op-lab/tag02-restarter && cd ~/op-lab/tag02-restarter
go mod init example.com/restarter
go get sigs.k8s.io/[email protected]

Erwartet (gekürzt):

go: creating new go.mod: module example.com/restarter
go: added k8s.io/api v0.37.0
go: added k8s.io/client-go v0.37.0
go: added sigs.k8s.io/controller-runtime v0.25.0

controller-runtime v0.25 zieht client-go v0.37 mit – dieselbe Kombination, die Kubebuilder an Tag 3 erzeugt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der Reconciler

Der Vertrag: Ein Deployment mit der Annotation restarter.lab.example/configmap: <name> bekommt am Pod-Template einen Hash über die Daten dieser ConfigMap. Ändert sich der Hash, ändert sich das Template – und Kubernetes rollt neu aus, genau wie bei kubectl rollout restart.

cat > reconciler.go <<'EOF'
package main

import (
    "context"
    "crypto/sha256"
    "encoding/hex"
    "maps"
    "slices"

    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    apierrors "k8s.io/apimachinery/pkg/api/errors"
    "k8s.io/apimachinery/pkg/types"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/builder"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/handler"
    "sigs.k8s.io/controller-runtime/pkg/log"
    "sigs.k8s.io/controller-runtime/pkg/predicate"
    "sigs.k8s.io/controller-runtime/pkg/reconcile"
)

const (
    annoConfigMap = "restarter.lab.example/configmap" // am Deployment
    annoHash      = "restarter.lab.example/hash"      // am Pod-Template
)

// Restarter startet Deployments neu, wenn sich ihre ConfigMap ändert.
type Restarter struct {
    client.Client
}

// Reconcile bekommt nur Namespace/Name – den Rest liest es selbst (Level-based).
func (r *Restarter) Reconcile(ctx context.Context, req ctrl.Request) (
    ctrl.Result, error) {
    logger := log.FromContext(ctx)

    var dep appsv1.Deployment
    if err := r.Get(ctx, req.NamespacedName, &dep); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err) // gelöscht: fertig
    }
    cmName := dep.Annotations[annoConfigMap]
    if cmName == "" {
        return ctrl.Result{}, nil
    }

    var cm corev1.ConfigMap
    err := r.Get(ctx, types.NamespacedName{Namespace: dep.Namespace,
        Name: cmName}, &cm)
    if apierrors.IsNotFound(err) {
        logger.Info("ConfigMap fehlt, warte", "configmap", cmName)
        return ctrl.Result{}, nil // der ConfigMap-Watch weckt uns
    }
    if err != nil {
        return ctrl.Result{}, err // controller-runtime wiederholt mit Backoff
    }

    hash := dataHash(cm.Data)
    if dep.Spec.Template.Annotations[annoHash] == hash {
        return ctrl.Result{}, nil // aktuell: nichts schreiben
    }
    patch := client.MergeFrom(dep.DeepCopy())
    if dep.Spec.Template.Annotations == nil {
        dep.Spec.Template.Annotations = map[string]string{}
    }
    dep.Spec.Template.Annotations[annoHash] = hash // neues Template = Rollout
    if err := r.Patch(ctx, &dep, patch); err != nil {
        return ctrl.Result{}, err
    }
    logger.Info("Rollout ausgelöst", "configmap", cmName, "hash", hash)
    return ctrl.Result{}, nil
}

// dataHash bildet einen stabilen Hash über die sortierten Keys und Werte.
func dataHash(data map[string]string) string {
    h := sha256.New()
    for _, k := range slices.Sorted(maps.Keys(data)) {
        h.Write([]byte(k + "=" + data[k] + "\n"))
    }
    return hex.EncodeToString(h.Sum(nil))[:16]
}
EOF

Drei Muster, die du ab jetzt in jedem Reconciler siehst:

Situation Rückgabe Warum
Objekt gelöscht client.IgnoreNotFound(err) Nichts mehr zu tun, kein Retry
Abhängigkeit fehlt Result{}, nil + Log Ein Watch weckt uns, wenn sie kommt
API-Fehler Result{}, err Backoff-Retry wie AddRateLimited
Schon aktuell Result{}, nil ohne Schreiben Idempotenz, kein Rollout-Sturm

client.MergeFrom erzeugt einen Merge-Patch aus der Differenz zum Original. So schreibst du nur das eine Feld und überschreibst keine Änderungen anderer Controller.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Watches und Mapping

Ein Event auf einer ConfigMap muss in Requests für Deployments übersetzt werden – For kennt nur Deployments. Das erledigt ein MapFunc:

cat >> reconciler.go <<'EOF'

// deploymentsFor übersetzt "ConfigMap geändert" in "diese Deployments prüfen".
func (r *Restarter) deploymentsFor(ctx context.Context,
    obj client.Object) []reconcile.Request {
    var list appsv1.DeploymentList
    if err := r.List(ctx, &list, client.InNamespace(obj.GetNamespace())); err != nil {
        log.FromContext(ctx).Error(err, "Deployments auflisten")
        return nil
    }
    var reqs []reconcile.Request
    for _, d := range list.Items {
        if d.Annotations[annoConfigMap] == obj.GetName() {
            reqs = append(reqs, reconcile.Request{NamespacedName: types.NamespacedName{
                Namespace: d.Namespace, Name: d.Name}})
        }
    }
    return reqs
}

// SetupWithManager verdrahtet Watches: Deployments direkt, ConfigMaps gemappt.
func (r *Restarter) SetupWithManager(mgr ctrl.Manager) error {
    annotated := predicate.NewPredicateFuncs(func(o client.Object) bool {
        _, ok := o.GetAnnotations()[annoConfigMap]
        return ok
    })
    return ctrl.NewControllerManagedBy(mgr).
        For(&appsv1.Deployment{}, builder.WithPredicates(annotated)).
        Watches(&corev1.ConfigMap{},
            handler.EnqueueRequestsFromMapFunc(r.deploymentsFor)).
        Named("restarter").
        Complete(r)
}
EOF
go mod tidy && go vet ./...

Erwartet: keine Ausgabe (außer go: downloading-Zeilen beim ersten Mal).

Das Prädikat filtert schon vor der Queue: Deployments ohne Annotation lösen gar keinen Reconcile aus. Das MapFunc liest per r.List aus dem Cache – kein Extra-Aufruf beim API-Server. An Tag 10 ersetzt du die Schleife durch einen Field-Index.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der Manager

cat > main.go <<'EOF'
// restarter startet Deployments neu, wenn sich eine referenzierte ConfigMap ändert.
// Tag 2: controller-runtime ohne Kubebuilder (Manager, Reconciler, Builder).
package main

import (
    "flag"
    "os"

    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/log/zap"
    metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
)

func main() {
    opts := zap.Options{Development: true}
    opts.BindFlags(flag.CommandLine) // -zap-log-level, -zap-devel, ...
    flag.Parse()                     // -kubeconfig registriert controller-runtime
    ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))
    setupLog := ctrl.Log.WithName("setup")

    // GetConfig: -kubeconfig, $KUBECONFIG, In-Cluster, ~/.kube/config.
    if os.Getenv("KUBECONFIG") == "" && flag.Lookup("kubeconfig").Value.String() == "" {
        setupLog.Info("KUBECONFIG nicht gesetzt – Abbruch (Lab-Schutz)")
        os.Exit(1)
    }
    cfg := ctrl.GetConfigOrDie()

    mgr, err := ctrl.NewManager(cfg, ctrl.Options{
        Metrics:                metricsserver.Options{BindAddress: "0"}, // aus
        HealthProbeBindAddress: "0",                                     // aus
    })
    if err != nil {
        setupLog.Error(err, "Manager anlegen")
        os.Exit(1)
    }
    if err := (&Restarter{Client: mgr.GetClient()}).SetupWithManager(mgr); err != nil {
        setupLog.Error(err, "Controller anlegen")
        os.Exit(1)
    }

    setupLog.Info("starte Manager", "host", cfg.Host)
    if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        setupLog.Error(err, "Manager beendet")
        os.Exit(1)
    }
}
EOF
go mod tidy && go build -o restarter . && env -u KUBECONFIG ./restarter
echo "exit=$?"

Erwartet (ohne Zeitstempel):

INFO    setup   KUBECONFIG nicht gesetzt – Abbruch (Lab-Schutz)
exit=1

ctrl.GetConfigOrDie() würde sonst – wie kubectl – auf ~/.kube/config zurückfallen. Metrik- und Probe-Server sind mit "0" abgeschaltet; die kommen an Tag 11.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Live gegen envtest

Terminal 2: source ~/op-lab/env.sh && envtest-up. Terminal 1:

./restarter > restarter.log 2>&1 &
kubectl create namespace lab
kubectl -n lab create configmap app-config --from-literal=greeting=hallo
kubectl -n lab create deployment web --image=nginxinc/nginx-unprivileged:1.31-alpine
kubectl -n lab annotate deployment web restarter.lab.example/configmap=app-config
sleep 2
kubectl -n lab get deploy web \
  -o jsonpath='{.metadata.generation} {.spec.template.metadata.annotations}{"\n"}'

Erwartet (Hash und Generation können abweichen):

namespace/lab created
configmap/app-config created
deployment.apps/web created
deployment.apps/web annotated
3 {"restarter.lab.example/hash":"7620aab77b54f1d4"}

Der erste Reconcile setzt den Hash – ein einmaliger Rollout beim Einschalten. Jetzt die ConfigMap ändern:

kubectl -n lab patch configmap app-config --type merge \
  -p '{"data":{"greeting":"moin"}}'
kubectl -n lab create deployment plain --image=nginxinc/nginx-unprivileged:1.31-alpine
sleep 2
COLS='NAME:.metadata.name,GEN:.metadata.generation'
COLS+=',HASH:.spec.template.metadata.annotations.restarter\.lab\.example/hash'
kubectl -n lab get deploy -o custom-columns="$COLS"

Erwartet:

configmap/app-config patched
deployment.apps/plain created
NAME    GEN   HASH
plain   1     <none>
web     4     795887ea11db139d

Neuer Hash, neue Generation: In einem echten Cluster würde der Deployment-Controller jetzt neue Pods starten. plain hat keine Annotation – das Prädikat hat es gar nicht erst in die Queue gelassen.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Logs lesen und umschalten

Die Log-Zeilen tragen automatisch Controller, Objekt und eine reconcileID – das hat der Builder in den ctx gelegt, log.FromContext(ctx) holt es heraus:

grep 'Rollout ausgelöst' restarter.log | tail -1 | tr ',' '\n' | head -9

Erwartet (gekürzt):

2026-10-10T10:14:33+02:00   INFO    Rollout ausgelöst   {"controller": "restarter"
 "controllerGroup": "apps"
 "controllerKind": "Deployment"
 "Deployment": {"name":"web"
"namespace":"lab"}
 "namespace": "lab"
 "name": "web"
 "reconcileID": "c5516067-d715-4096-8269-f755aae0beb7"
 "configmap": "app-config"

Für Produktion willst du JSON. Die zap-Flags hat opts.BindFlags registriert:

kill -INT %1; sleep 1
./restarter -zap-devel=false > restarter.json 2>&1 &
sleep 2; kubectl -n lab patch configmap app-config --type merge \
  -p '{"data":{"greeting":"servus"}}'
sleep 2; grep Rollout restarter.json | jq -c '{level, msg, hash}'
kill -INT %1

Erwartet:

configmap/app-config patched
{"level":"info","msg":"Rollout ausgelöst","hash":"da2ca8f2b03831a9"}

Tipp: -zap-log-level=debug zeigt mehr, -zap-log-level=2 noch mehr (V(2)-Logs). Strukturierte Felder ("configmap", cmName) statt fmt.Sprintf – nur so kann Loki oder Elasticsearch danach filtern.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tests mit dem fake Client

controller-runtime bringt einen eigenen fake Client mit. Er braucht keine Informer: Du rufst Reconcile direkt auf und prüfst danach das Objekt.

cat > reconciler_test.go <<'EOF'
package main

import (
    "context"
    "testing"

    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/types"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/client/fake"
)

func deploy(name, cm string) *appsv1.Deployment {
    d := &appsv1.Deployment{ObjectMeta: metav1.ObjectMeta{
        Namespace: "lab", Name: name}}
    if cm != "" {
        d.Annotations = map[string]string{annoConfigMap: cm}
    }
    return d
}

func configMap(name, value string) *corev1.ConfigMap {
    return &corev1.ConfigMap{
        ObjectMeta: metav1.ObjectMeta{Namespace: "lab", Name: name},
        Data:       map[string]string{"setting": value},
    }
}

// reconcileHash ruft Reconcile auf und liefert den Hash am Pod-Template.
func reconcileHash(t *testing.T, c client.Client, name string) string {
    t.Helper()
    ctx := context.Background()
    key := types.NamespacedName{Namespace: "lab", Name: name}
    r := &Restarter{Client: c}
    if _, err := r.Reconcile(ctx, ctrl.Request{NamespacedName: key}); err != nil {
        t.Fatalf("Reconcile: %v", err)
    }
    var d appsv1.Deployment
    if err := c.Get(ctx, key, &d); err != nil {
        t.Fatal(err)
    }
    return d.Spec.Template.Annotations[annoHash]
}

func TestReconcileSetztUndAendertHash(t *testing.T) {
    cm := configMap("app-config", "a")
    c := fake.NewClientBuilder().WithObjects(deploy("web", "app-config"), cm).Build()

    first := reconcileHash(t, c, "web")
    if first == "" {
        t.Fatal("kein Hash gesetzt")
    }
    if again := reconcileHash(t, c, "web"); again != first {
        t.Errorf("Hash ohne Änderung neu: %s != %s", again, first)
    }

    cm.Data["setting"] = "b"
    if err := c.Update(context.Background(), cm); err != nil {
        t.Fatal(err)
    }
    if changed := reconcileHash(t, c, "web"); changed == first {
        t.Error("Hash nach ConfigMap-Änderung unverändert")
    }
}

func TestReconcileOhneAnnotationOderConfigMap(t *testing.T) {
    c := fake.NewClientBuilder().
        WithObjects(deploy("plain", ""), deploy("waiting", "fehlt")).Build()
    for _, name := range []string{"plain", "waiting"} {
        if h := reconcileHash(t, c, name); h != "" {
            t.Errorf("%s: unerwarteter Hash %q", name, h)
        }
    }
}

func TestDeploymentsFor(t *testing.T) {
    c := fake.NewClientBuilder().WithObjects(deploy("a", "app-config"),
        deploy("b", "andere"), deploy("c", "app-config")).Build()
    r := &Restarter{Client: c}
    reqs := r.deploymentsFor(context.Background(), configMap("app-config", "x"))
    if len(reqs) != 2 {
        t.Fatalf("got %d requests, want 2: %v", len(reqs), reqs)
    }
}

func TestDataHashStabil(t *testing.T) {
    a := dataHash(map[string]string{"x": "1", "y": "2"})
    b := dataHash(map[string]string{"y": "2", "x": "1"})
    if a != b || len(a) != 16 {
        t.Errorf("hash instabil: %s vs %s", a, b)
    }
}
EOF
go mod tidy && go test -race -count=1 -v . 2>&1 | grep -E '^(---|ok)'

Erwartet:

--- PASS: TestReconcileSetztUndAendertHash (0.44s)
--- PASS: TestReconcileOhneAnnotationOderConfigMap (0.00s)
--- PASS: TestDeploymentsFor (0.01s)
--- PASS: TestDataHashStabil (0.00s)
ok      example.com/restarter   1.810s

Der fake Client prüft keine Schemas, Defaults oder Admission. Für Logik ist er ideal – was der API-Server garantiert, testest du ab Tag 3 mit envtest.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

envtest läuft in Terminal 2:

cd ~/op-lab/tag02-restarter
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
go vet ./... && go test -race -count=1 ./... >/dev/null && ok "vet und Tests" \
  || nok "Tests"
go build -o restarter . || nok "Build"
./restarter > kp.log 2>&1 & PID=$!
kubectl create ns kp >/dev/null
kubectl -n kp create configmap cfg --from-literal=a=1 >/dev/null
kubectl -n kp create deployment app --image=nginx >/dev/null
kubectl -n kp annotate deployment app restarter.lab.example/configmap=cfg >/dev/null
sleep 2; H1=$(kubectl -n kp get deploy app \
  -o jsonpath='{.spec.template.metadata.annotations.restarter\.lab\.example/hash}')
kubectl -n kp patch configmap cfg --type merge -p '{"data":{"a":"2"}}' >/dev/null
sleep 2; H2=$(kubectl -n kp get deploy app \
  -o jsonpath='{.spec.template.metadata.annotations.restarter\.lab\.example/hash}')
[ -n "$H1" ] && ok "Hash gesetzt" || nok "kein Hash"
[ -n "$H2" ] && [ "$H1" != "$H2" ] && ok "Rollout nach Änderung" || nok "kein Rollout"
kill -INT $PID; wait $PID
grep -q 'Wait completed' kp.log && ok "sauber beendet" || nok "Shutdown"

Erwartet:

✔ vet und Tests
✔ Hash gesetzt
✔ Rollout nach Änderung
✔ sauber beendet

Challenge

Ein List ohne client.InNamespace würde Deployments in allen Namespaces finden, die zufällig eine gleichnamige ConfigMap referenzieren. Beweise per Test, dass deploymentsFor nur den Namespace der ConfigMap berücksichtigt.

Hinweis: Lege mit deploy() zwei Deployments an und setze bei einem Namespace auf "anderer".

Lösung

cat >> reconciler_test.go <<'EOF'

func TestDeploymentsForNurEigenerNamespace(t *testing.T) {
    fremd := deploy("x", "app-config")
    fremd.Namespace = "anderer"
    c := fake.NewClientBuilder().WithObjects(deploy("a", "app-config"), fremd).Build()
    reqs := (&Restarter{Client: c}).deploymentsFor(context.Background(),
        configMap("app-config", "neu"))
    if len(reqs) != 1 || reqs[0].Namespace != "lab" {
        t.Errorf("reqs = %v, want nur lab/a", reqs)
    }
}
EOF
go test -race -count=1 -run NurEigener -v . 2>&1 | grep -E '^(---|ok)'

Erwartet:

--- PASS: TestDeploymentsForNurEigenerNamespace (0.00s)
ok      example.com/restarter   1.512s

Entferne zur Probe client.InNamespace(...) in deploymentsFor – der Test wird rot.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Der Manager cached alle ConfigMaps und Deployments des Clusters. In großen Clustern: Cache auf Namespaces oder Label beschränken (cache.Options, Tag 10 und 13).
  • Ein Rollout-Sturm ist ein echtes Risiko: Eine ConfigMap, an der 200 Deployments hängen, startet 200 Rollouts. Rate-Limits und maxUnavailable mitdenken.
  • Etablierte Alternativen wie Stakater Reloader lösen genau dieses Problem – vor dem Eigenbau prüfen.
  • RBAC: get/list/watch auf ConfigMaps, get/list/watch/patch auf Deployments. ConfigMaps können sensible Daten enthalten – Secrets nie ohne Not in den Cache holen.
  • Mehrere Instanzen nur mit Leader Election (LeaderElection: true, Tag 11).