Tag 1: Das Operator-Muster mit client-go von Hand
Ziel:
labelsynckopiert das Labelteamvom 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.
syncist 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)
}
}
EOFWarum 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 ./labelsyncErwartet:
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.Startstartet nur Informer, die vorher per.Informer()oder.Lister()angefordert wurden. Rufst duStartvorNew, startet kein Informer – undWaitForCacheSyncwartet 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 teamErwartet:
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 teamErwartet:
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 teamErwartet:
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 -6Erwartet (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 teamErwartet:
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.logErwartet:
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) oderWithNamespace(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/watchauf Namespaces und Pods,patchauf 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.