Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Das Operator-Muster mit client-go von Hand

Ziel: labelsync kopiert das Label team vom Namespace auf alle Pods darin – gebaut aus Informer, Lister und Workqueue, ohne Framework · Dauer: ca. 120 min · Voraussetzung: Tag 0

Briefing

  • Ein Operator ist eine Schleife: beobachten – vergleichen – angleichen (Reconcile), immer wieder.
  • Der Informer hält per List+Watch eine lokale Kopie (Cache); der Lister liest daraus, ohne den API-Server zu belasten.
  • Event-Handler legen nur einen Key in die Workqueue – nie Logik im Handler.
  • Die Queue entdoppelt Keys, Worker holen sie ab; Fehler gehen mit exponentiellem Backoff zurück in die Queue.
  • sync ist level-based: Es schaut sich den ganzen Ist-Zustand an, nicht das einzelne Event.
 API-Server --List/Watch--> Informer --> Cache (Indexer) <--Get/List-- Lister
                               |                                         ^
                       Add/Update-Event                                  |
                               v                                         |
                      Handler: queue.Add("shop")                         |
                               v                                         |
          Workqueue  [ "shop", "dev" ]  (entdoppelt, Rate-Limiter)       |
                               v                                         |
          Worker: key := Get() -> sync(key) ------------------------------
                               |      \--- Fehler: AddRateLimited(key)
                               v
                    PATCH Pod-Labels --> API-Server

Drill 1: Modul anlegen

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

Erwartet (gekürzt):

go: creating new go.mod: module example.com/labelsync
go: added k8s.io/api v0.37.0
go: added k8s.io/apimachinery v0.37.0
go: added k8s.io/client-go v0.37.0

client-go, api und apimachinery tragen immer dieselbe Minor-Version (v0.37 = Kubernetes 1.37). Mischen führt zu Compile-Fehlern.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Informer, Lister und Handler

Die Struktur hält, was der Controller braucht. Die Queue ist typisiert ([string]) – der Key ist hier einfach der Namespace-Name, denn ein Namespace ist die Einheit, die wir angleichen.

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

import (
    "context"
    "encoding/json"
    "fmt"
    "log/slog"
    "time"

    corev1 "k8s.io/api/core/v1"
    apierrors "k8s.io/apimachinery/pkg/api/errors"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/labels"
    "k8s.io/apimachinery/pkg/types"
    "k8s.io/apimachinery/pkg/util/wait"
    "k8s.io/client-go/informers"
    "k8s.io/client-go/kubernetes"
    listersv1 "k8s.io/client-go/listers/core/v1"
    "k8s.io/client-go/tools/cache"
    "k8s.io/client-go/util/workqueue"
)

const labelKey = "team"

// Controller kopiert das Label "team" vom Namespace auf alle Pods darin.
type Controller struct {
    client  kubernetes.Interface
    nsList  listersv1.NamespaceLister
    podList listersv1.PodLister
    synced  []cache.InformerSynced
    queue   workqueue.TypedRateLimitingInterface[string] // Key: Namespace-Name
}

// New verdrahtet Informer, Lister und Workqueue.
func New(client kubernetes.Interface, f informers.SharedInformerFactory) *Controller {
    nsInf := f.Core().V1().Namespaces()
    podInf := f.Core().V1().Pods()
    c := &Controller{
        client:  client,
        nsList:  nsInf.Lister(),
        podList: podInf.Lister(),
        synced: []cache.InformerSynced{
            nsInf.Informer().HasSynced, podInf.Informer().HasSynced,
        },
        queue: workqueue.NewTypedRateLimitingQueue(
            workqueue.DefaultTypedControllerRateLimiter[string]()),
    }
    // Event-Handler machen nichts außer "Namespace X ansehen" in die Queue legen.
    _, _ = nsInf.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{
        AddFunc:    func(obj any) { c.enqueueNS(obj) },
        UpdateFunc: func(_, obj any) { c.enqueueNS(obj) },
    })
    _, _ = podInf.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{
        AddFunc:    func(obj any) { c.enqueuePod(obj) },
        UpdateFunc: func(_, obj any) { c.enqueuePod(obj) },
    })
    return c
}

func (c *Controller) enqueueNS(obj any) {
    if ns, ok := obj.(*corev1.Namespace); ok {
        c.queue.Add(ns.Name)
    }
}

func (c *Controller) enqueuePod(obj any) {
    if pod, ok := obj.(*corev1.Pod); ok {
        c.queue.Add(pod.Namespace)
    }
}
EOF

Warum landet bei einem Pod-Event der Namespace in der Queue? Weil sync immer den ganzen Namespace angleicht. Zehn Pod-Events für shop werden so zu einem einzigen Queue-Eintrag – die Queue entdoppelt gleiche Keys.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Workqueue, Worker und sync

cat >> controller.go <<'EOF'

// Run wartet auf die Caches und startet die Worker, bis ctx endet.
func (c *Controller) Run(ctx context.Context, workers int) error {
    defer c.queue.ShutDown()
    if !cache.WaitForNamedCacheSyncWithContext(ctx, c.synced...) {
        return fmt.Errorf("caches nicht synchron")
    }
    slog.Info("caches synchron, starte worker", "workers", workers)
    for range workers {
        go wait.UntilWithContext(ctx, c.worker, time.Second)
    }
    <-ctx.Done()
    return nil
}

func (c *Controller) worker(ctx context.Context) {
    for c.processNext(ctx) {
    }
}

// processNext holt einen Key, ruft sync und entscheidet über Retry.
func (c *Controller) processNext(ctx context.Context) bool {
    key, quit := c.queue.Get()
    if quit {
        return false
    }
    defer c.queue.Done(key) // Key wieder freigeben (sonst nie wieder verarbeitet)

    if err := c.sync(ctx, key); err != nil {
        slog.Error("sync fehlgeschlagen", "ns", key, "err", err,
            "retries", c.queue.NumRequeues(key))
        c.queue.AddRateLimited(key) // exponentielles Backoff: 5ms, 10ms, ...
        return true
    }
    c.queue.Forget(key) // Erfolg: Backoff-Zähler zurücksetzen
    return true
}

// sync bringt alle Pods eines Namespace auf den Label-Wert des Namespace.
func (c *Controller) sync(ctx context.Context, nsName string) error {
    ns, err := c.nsList.Get(nsName) // liest aus dem Cache, nicht vom API-Server
    if apierrors.IsNotFound(err) {
        return nil // Namespace weg: nichts zu tun
    }
    if err != nil {
        return err
    }
    want, has := ns.Labels[labelKey]

    pods, err := c.podList.Pods(nsName).List(labels.Everything())
    if err != nil {
        return err
    }
    for _, pod := range pods {
        got, podHas := pod.Labels[labelKey]
        if got == want && podHas == has {
            continue // schon richtig: nichts schreiben (Idempotenz)
        }
        if err := c.patchPod(ctx, pod, want, has); err != nil {
            return err
        }
        slog.Info("label gesetzt", "pod", nsName+"/"+pod.Name,
            labelKey, want, "entfernt", !has)
    }
    return nil
}

// patchPod schreibt nur das eine Label per JSON-Merge-Patch (null = löschen).
func (c *Controller) patchPod(ctx context.Context, pod *corev1.Pod,
    value string, set bool) error {
    var v any // nil wird zu JSON null
    if set {
        v = value
    }
    patch, err := json.Marshal(map[string]any{
        "metadata": map[string]any{"labels": map[string]any{labelKey: v}},
    })
    if err != nil {
        return err
    }
    _, err = c.client.CoreV1().Pods(pod.Namespace).Patch(ctx, pod.Name,
        types.MergePatchType, patch, metav1.PatchOptions{})
    return err
}
EOF
go mod tidy && go vet ./...

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

Die drei Queue-Regeln, die jeder Controller einhält:

Aufruf Wann Folge, wenn vergessen
Done(key) immer nach Get Key wird nie wieder verarbeitet
Forget(key) nach Erfolg Backoff wächst weiter
AddRateLimited(key) nach Fehler Fehler geht verloren oder Hotloop

Fortschritt speichern? Kostenlos registrieren

Drill 4: main – Kubeconfig, Factory, Signale

cat > main.go <<'EOF'
// labelsync kopiert das Label "team" vom Namespace auf alle Pods darin.
// Tag 1: Operator-Muster von Hand mit client-go (Informer, Lister, Workqueue).
package main

import (
    "context"
    "errors"
    "flag"
    "log/slog"
    "os"
    "os/signal"
    "syscall"
    "time"

    "k8s.io/client-go/informers"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"
)

func main() {
    kubeconfig := flag.String("kubeconfig", os.Getenv("KUBECONFIG"),
        "Pfad zur Kubeconfig (Pflicht, kein Fallback auf ~/.kube/config)")
    workers := flag.Int("workers", 2, "parallele Worker")
    flag.Parse()

    if err := run(*kubeconfig, *workers); err != nil {
        slog.Error("abbruch", "err", err)
        os.Exit(1)
    }
}

func run(kubeconfig string, workers int) error {
    if kubeconfig == "" {
        return errors.New("-kubeconfig oder KUBECONFIG setzen")
    }
    cfg, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
    if err != nil {
        return err
    }
    slog.Info("verbinde", "host", cfg.Host)
    client, err := kubernetes.NewForConfig(cfg)
    if err != nil {
        return err
    }

    ctx, stop := signal.NotifyContext(context.Background(),
        os.Interrupt, syscall.SIGTERM)
    defer stop()

    // Resync 10 min: alle Objekte kommen periodisch erneut als Update-Event.
    factory := informers.NewSharedInformerFactory(client, 10*time.Minute)
    c := New(client, factory)
    factory.Start(ctx.Done()) // erst NACH New(): Informer müssen registriert sein
    defer factory.Shutdown()

    err = c.Run(ctx, workers)
    slog.Info("beendet")
    return err
}
EOF
go mod tidy && go build -o labelsync . && env -u KUBECONFIG ./labelsync

Erwartet:

2026/10/10 10:14:52 ERROR abbruch err="-kubeconfig oder KUBECONFIG setzen"

Bewusst kein Fallback auf ~/.kube/config (wie es kubectl macht): Ein Lab-Tool, das versehentlich im Produktionskontext Pods patcht, ist schlimmer als eines, das gar nicht startet.

Achtung: factory.Start startet nur Informer, die vorher per .Informer() oder .Lister() angefordert wurden. Rufst du Start vor New, startet kein Informer – und WaitForCacheSync wartet ewig.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Live gegen envtest

Terminal 2: source ~/op-lab/env.sh && envtest-up. Dann in Terminal 1 einen Namespace mit zwei Pods anlegen – einer ohne, einer mit falschem Label:

kubectl create namespace shop
kubectl label namespace shop team=blau
kubectl -n shop run web-1 --image=nginx
kubectl -n shop run web-2 --image=nginx --labels=team=rot
kubectl -n shop get pods -L team

Erwartet:

namespace/shop created
namespace/shop labeled
pod/web-1 created
pod/web-2 created
NAME    READY   STATUS    RESTARTS   AGE   TEAM
web-1   0/1     Pending   0          0s
web-2   0/1     Pending   0          0s    rot

Pending für immer – envtest hat keinen Scheduler (Tag 0). Für labelsync spielt das keine Rolle. Jetzt den Controller starten:

./labelsync > labelsync.log 2>&1 &
sleep 3; cat labelsync.log; kubectl -n shop get pods -L team

Erwartet:

2026/10/10 10:12:18 INFO verbinde host=https://127.0.0.1:55759
I1010 10:12:18.478964    4284 shared_informer.go:524] "Waiting for caches to sync"
I1010 10:12:18.581137    4284 shared_informer.go:531] "Caches are synced"
2026/10/10 10:12:18 INFO caches synchron, starte worker workers=2
2026/10/10 10:12:18 INFO label gesetzt pod=shop/web-1 team=blau entfernt=false
2026/10/10 10:12:18 INFO label gesetzt pod=shop/web-2 team=blau entfernt=false
NAME    READY   STATUS    RESTARTS   AGE   TEAM
web-1   0/1     Pending   0          3s    blau
web-2   0/1     Pending   0          3s    blau

Die I1010-Zeilen schreibt client-go selbst (klog). Jetzt ändern sich die Welt und der Controller zieht nach:

kubectl label namespace shop team=gruen --overwrite
kubectl -n shop run web-3 --image=nginx
sleep 1; kubectl -n shop get pods -L team
kubectl label namespace shop team-
sleep 1; kubectl -n shop get pods -L team

Erwartet:

NAME    READY   STATUS    RESTARTS   AGE   TEAM
web-1   0/1     Pending   0          10s   gruen
web-2   0/1     Pending   0          10s   gruen
web-3   0/1     Pending   0          1s    gruen
NAME    READY   STATUS    RESTARTS   AGE   TEAM
web-1   0/1     Pending   0          11s
web-2   0/1     Pending   0          11s
web-3   0/1     Pending   0          2s

Ein Blick ins Log zeigt etwas Wichtiges:

grep gruen labelsync.log | cut -c21-

Erwartet (die Doppelung kann bei dir einen anderen Pod treffen oder fehlen):

INFO label gesetzt pod=shop/web-1 team=gruen entfernt=false
INFO label gesetzt pod=shop/web-2 team=gruen entfernt=false
INFO label gesetzt pod=shop/web-2 team=gruen entfernt=false
INFO label gesetzt pod=shop/web-3 team=gruen entfernt=false

Warum ein Pod zweimal? Der Patch von web-1 löst ein Pod-Event aus, shop kommt erneut in die Queue – aber der Cache kennt die neue Version von web-2 noch nicht. Der Cache ist eventually consistent. Das ist harmlos, weil der Patch idempotent ist: Gleiches Label zweimal setzen ändert nichts.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Fehler, Backoff und Rate-Limiting

Was passiert, wenn der API-Server den Patch ablehnt? Eine ValidatingAdmissionPolicy (CEL, seit Kubernetes 1.30 GA) verbietet team=gelb auf Pods – envtest wertet sie wie ein echter Cluster aus:

cat > /tmp/kein-gelb.yaml <<'EOF'
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: kein-team-gelb
spec:
  matchConstraints:
    resourceRules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      operations: ["UPDATE"]
      resources: ["pods"]
  validations:
  - expression: "object.metadata.?labels.team.orValue('') != 'gelb'"
    message: "team=gelb ist verboten (Lab-Policy)"
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: kein-team-gelb
spec:
  policyName: kein-team-gelb
  validationActions: [Deny]
EOF
kubectl apply -f /tmp/kein-gelb.yaml
sleep 2; kubectl label namespace shop team=gelb
sleep 5; grep fehlgeschlagen labelsync.log | grep -oE '^.{19}|retries=[0-9]+' \
  | paste - - | tail -6

Erwartet (gekürzt):

2026/10/10 10:12:38 retries=0
2026/10/10 10:12:38 retries=1
...
2026/10/10 10:12:39 retries=7
2026/10/10 10:12:40 retries=8
2026/10/10 10:12:41 retries=9
2026/10/10 10:12:43 retries=10

Der Default-Rate-Limiter verdoppelt die Wartezeit pro Fehlschlag: 5 ms, 10 ms, 20 ms … bis maximal 1000 s. Zusätzlich begrenzt ein globaler Token-Bucket (10/s, Burst 100) alle Keys zusammen. Jetzt die Ursache beheben:

kubectl delete validatingadmissionpolicybinding kein-team-gelb
sleep 12; kubectl -n shop get pods -L team

Erwartet:

validatingadmissionpolicybinding.admissionregistration.k8s.io "kein-team-gelb" deleted
NAME    READY   STATUS    RESTARTS   AGE   TEAM
web-1   0/1     Pending   0          41s   gelb
web-2   0/1     Pending   0          41s   gelb
web-3   0/1     Pending   0          32s   gelb

Der nächste geplante Retry gewinnt, Forget setzt den Zähler zurück. Kein Neustart, kein manueller Eingriff – das ist Selbstheilung durch Reconcile.

kill -INT %1; sleep 1; tail -1 labelsync.log

Erwartet:

2026/10/10 10:12:59 INFO beendet

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tests mit dem fake Clientset

fake.NewClientset ist ein Clientset, das Objekte im Speicher hält und Patches anwendet – inklusive Watch, also funktionieren auch Informer. Tabellen-Tests (wie im Go-Buch, Tag 4) prüfen die Fälle von sync:

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

import (
    "context"
    "testing"

    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/informers"
    "k8s.io/client-go/kubernetes/fake"
    "k8s.io/client-go/tools/cache"
)

func ns(name, team string) *corev1.Namespace {
    n := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: name}}
    if team != "" {
        n.Labels = map[string]string{labelKey: team}
    }
    return n
}

func pod(ns, name string, lbl map[string]string) *corev1.Pod {
    return &corev1.Pod{ObjectMeta: metav1.ObjectMeta{
        Namespace: ns, Name: name, Labels: lbl}}
}

func TestSync(t *testing.T) {
    tests := []struct {
        name    string
        team    string            // Label am Namespace ("" = keins)
        podLbl  map[string]string // Labels am Pod vorher
        want    string
        wantHas bool
    }{
        {"setzt Label", "blau", nil, "blau", true},
        {"korrigiert Label", "blau", map[string]string{labelKey: "rot"}, "blau", true},
        {"entfernt Label", "", map[string]string{labelKey: "rot"}, "", false},
        {"lässt fremde Pods", "", nil, "", false},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            ctx, cancel := context.WithCancel(context.Background())
            defer cancel()
            client := fake.NewClientset(ns("shop", tt.team),
                pod("shop", "web-1", tt.podLbl))
            f := informers.NewSharedInformerFactory(client, 0)
            c := New(client, f)
            f.Start(ctx.Done())
            if !cache.WaitForCacheSync(ctx.Done(), c.synced...) {
                t.Fatal("cache nicht synchron")
            }

            if err := c.sync(ctx, "shop"); err != nil {
                t.Fatalf("sync: %v", err)
            }

            p, err := client.CoreV1().Pods("shop").Get(ctx, "web-1",
                metav1.GetOptions{})
            if err != nil {
                t.Fatal(err)
            }
            got, has := p.Labels[labelKey]
            if got != tt.want || has != tt.wantHas {
                t.Errorf("label = %q (%v), want %q (%v)", got, has, tt.want, tt.wantHas)
            }
        })
    }
}

func TestSyncNamespaceWeg(t *testing.T) {
    client := fake.NewClientset()
    c := New(client, informers.NewSharedInformerFactory(client, 0))
    if err := c.sync(context.Background(), "gibtsnicht"); err != nil {
        t.Errorf("sync auf fehlenden Namespace: %v", err)
    }
}
EOF
go mod tidy && go test -race -count=1 -v . 2>&1 | grep -E '^(---|    ---|ok)'

Erwartet:

--- PASS: TestSync (1.28s)
    --- PASS: TestSync/setzt_Label (0.96s)
    --- PASS: TestSync/korrigiert_Label (0.11s)
    --- PASS: TestSync/entfernt_Label (0.11s)
    --- PASS: TestSync/lässt_fremde_Pods (0.10s)
--- PASS: TestSyncNamespaceWeg (0.00s)
ok      example.com/labelsync   2.741s

Warum kein envtest? sync braucht nur Lister und einen Client. Der fake Clientset ist schneller und prüft genau die Logik. envtest lohnt sich, wenn der echte API-Server mitspielen muss (Validierung, Defaults, Admission) – ab Tag 3.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

envtest läuft in Terminal 2, Namespace shop existiert noch:

cd ~/op-lab/tag01-labelsync
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
go vet ./... && go test -race -count=1 ./... >/dev/null && ok "vet und Tests" \
  || nok "Tests"
go build -o labelsync . || nok "Build"
./labelsync > kp.log 2>&1 & PID=$!
kubectl create namespace kp >/dev/null && kubectl label ns kp team=kontrolle >/dev/null
kubectl -n kp run probe --image=nginx >/dev/null; sleep 3
[ "$(kubectl -n kp get pod probe -o jsonpath='{.metadata.labels.team}')" = \
  kontrolle ] && ok "Label kopiert" || nok "Label fehlt"
kill -INT $PID; wait $PID
grep -q 'INFO beendet' kp.log && ok "sauber beendet" || nok "Shutdown"

Erwartet:

✔ vet und Tests
✔ Label kopiert
✔ sauber beendet

Challenge

Beweise per Test, dass ein zweiter sync auf denselben Namespace keinen weiteren Patch schickt.

Hinweis: Der fake Clientset zeichnet jeden Aufruf auf: client.ClearActions() leert die Liste, client.Actions() liefert sie mit GetVerb(). Warte vorher, bis der Informer den gepatchten Pod im Cache hat.

Lösung

Ergänze "time" im Import-Block von controller_test.go, dann:

cat >> controller_test.go <<'EOF'

func TestSyncIdempotent(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    client := fake.NewClientset(ns("shop", "blau"), pod("shop", "web-1", nil))
    f := informers.NewSharedInformerFactory(client, 0)
    c := New(client, f)
    f.Start(ctx.Done())
    cache.WaitForCacheSync(ctx.Done(), c.synced...)

    if err := c.sync(ctx, "shop"); err != nil {
        t.Fatal(err)
    }
    // Warten, bis der Informer den gepatchten Pod im Cache hat.
    for {
        p, _ := c.podList.Pods("shop").Get("web-1")
        if p.Labels[labelKey] == "blau" {
            break
        }
        time.Sleep(10 * time.Millisecond)
    }
    client.ClearActions()
    if err := c.sync(ctx, "shop"); err != nil {
        t.Fatal(err)
    }
    for _, a := range client.Actions() {
        if a.GetVerb() == "patch" {
            t.Errorf("zweiter sync patcht erneut: %v", a)
        }
    }
}
EOF
go test -race -count=1 -run Idempotent -v . 2>&1 | grep -E '^(---|ok)'

Erwartet:

--- PASS: TestSyncIdempotent (0.53s)
ok      example.com/labelsync   1.877s

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Pods aller Namespaces im Cache kosten Speicher: Bei 50 000 Pods sind das schnell Gigabytes. Filtere mit informers.WithTweakListOptions (Label-Selektor) oder WithNamespace (Tag 10 und 13).
  • Mehrere Replikas desselben Controllers patchen sich gegenseitig: Ohne Leader Election (Tag 11) nie mehr als eine Instanz.
  • Der Controller braucht RBAC: get/list/watch auf Namespaces und Pods, patch auf Pods – nicht mehr.
  • Label-Kopien sind Policy: In vielen Firmen erledigt das Kyverno oder eine Mutating-Policy. Ein eigener Controller lohnt sich, wenn Logik oder externe Systeme ins Spiel kommen.
  • client-go von Hand schreibt heute kaum noch jemand. Es zu verstehen, hilft beim Debuggen von controller-runtime (Tag 2) – darunter steckt genau das.