Tag 2: controller-runtime ohne Kubebuilder
Ziel:
restarterstartet 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 bekommtNamespace/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 != nilheißt Retry mit Backoff,nilheißtForget. client.Clientliest 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]
}
EOFDrei 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 -9Erwartet (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 %1Erwartet:
configmap/app-config patched
{"level":"info","msg":"Rollout ausgelöst","hash":"da2ca8f2b03831a9"}
Tipp:
-zap-log-level=debugzeigt mehr,-zap-log-level=2noch mehr (V(2)-Logs). Strukturierte Felder ("configmap", cmName) stattfmt.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
maxUnavailablemitdenken. - Etablierte Alternativen wie Stakater Reloader lösen genau dieses Problem – vor dem Eigenbau prüfen.
- RBAC:
get/list/watchauf ConfigMaps,get/list/watch/patchauf 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).