Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: Skalierung und Robustheit

Ziel: Den site-operator unter Last verstehen und härten: Worker-Zahl und Backoff messen und einstellen, Konflikte provozieren und vermeiden, Field Manager sauber setzen, den Cache verschlanken, große Listen seitenweise lesen und die Leader Election richtig konfigurieren · Dauer: ca. 150 min · Voraussetzung: Tag 12

Briefing

  • Pro Controller gibt es eine Queue und MaxConcurrentReconciles Worker (Standard 1). Derselbe Schlüssel wird nie parallel abgearbeitet.
  • Ein Fehler aus Reconcile legt den Schlüssel mit exponentiellem Backoff zurück: 5 ms, 10 ms, 20 ms … bis 1000 s. RequeueAfter umgeht den Backoff.
  • Update schickt die resourceVersion mit. Hat jemand anderes inzwischen geschrieben, antwortet der API-Server mit 409 Conflict – optimistisches Locking.
  • Der Cache hält jedes Objekt der beobachteten Typen im Speicher. Weniger Typen, Label-Selektoren und Transforms sparen RAM.
  • Leader Election schützt vor zwei aktiven Managern – aber nur, wenn Lease-Zeiten, Shutdown und Webhooks dazu passen.
Events --> Queue (dedupliziert, Backoff pro Schlüssel) --> Worker 1..N --> Reconcile
                ^                                                       |
                '------ err: Backoff  /  RequeueAfter: fester Termin ----'

Drill 1: Arbeitsstand und Mess-Suite

Messen statt raten: Eine eigene Ginkgo-Suite unter test/scale/ startet envtest und kleine Mess-Controller. Sie läuft unabhängig von der Controller-Suite aus Tag 6.

source ~/op-lab/env.sh
cp -r ~/op-lab/tag12-site-operator ~/op-lab/tag13-site-operator
cd ~/op-lab/tag13-site-operator
export ENABLE_WEBHOOKS=false
mkdir -p test/scale
cat > test/scale/suite_test.go <<'EOF'
// Package scale misst Worker, Backoff, Konflikte, Cache und Pagination
// gegen envtest. Die Specs prüfen Verhalten und geben Messwerte aus.
package scale

import (
    "context"
    "fmt"
    "path/filepath"
    "testing"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes/scheme"
    "k8s.io/client-go/rest"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/controller"
    "sigs.k8s.io/controller-runtime/pkg/envtest"
    metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
    "sigs.k8s.io/controller-runtime/pkg/reconcile"

    webv1 "example.com/site-operator/api/v1"
)

var (
    cfg       *rest.Config
    k8sClient client.Client
    testEnv   *envtest.Environment
    ctx       context.Context
    cancel    context.CancelFunc
)

func TestScale(t *testing.T) {
    RegisterFailHandler(Fail)
    RunSpecs(t, "Scale Suite")
}

var _ = BeforeSuite(func() {
    ctx, cancel = context.WithCancel(context.Background())
    Expect(webv1.AddToScheme(scheme.Scheme)).To(Succeed())
    testEnv = &envtest.Environment{ErrorIfCRDPathMissing: true,
        CRDDirectoryPaths: []string{filepath.Join("..", "..", "config", "crd", "bases")}}
    var err error
    cfg, err = testEnv.Start()
    Expect(err).NotTo(HaveOccurred())
    k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
    Expect(err).NotTo(HaveOccurred())
})

var _ = AfterSuite(func() {
    cancel()
    Expect(testEnv.Stop()).To(Succeed())
})

// createSites legt einen Namespace mit n StaticSites an.
func createSites(ns string, n int) {
    Expect(k8sClient.Create(ctx, &corev1.Namespace{
        ObjectMeta: metav1.ObjectMeta{Name: ns}})).To(Succeed())
    for i := range n {
        Expect(k8sClient.Create(ctx, &webv1.StaticSite{
            ObjectMeta: metav1.ObjectMeta{Name: fmt.Sprint("s", i), Namespace: ns},
            Spec:       webv1.StaticSiteSpec{Content: "<h1>last</h1>"},
        })).To(Succeed())
    }
}

// runController startet einen eigenen Manager mit einem Mess-Reconciler
// für die StaticSites in ns. Stoppen über das zurückgegebene cancel.
func runController(name, ns string, opts controller.Options,
    r reconcile.Func) context.CancelFunc {
    mgr, err := ctrl.NewManager(cfg, ctrl.Options{Scheme: scheme.Scheme,
        Metrics: metricsserver.Options{BindAddress: "0"}})
    Expect(err).NotTo(HaveOccurred())
    only := func(c context.Context, req reconcile.Request) (reconcile.Result, error) {
        if req.Namespace != ns {
            return reconcile.Result{}, nil
        }
        return r(c, req)
    }
    Expect(ctrl.NewControllerManagedBy(mgr).For(&webv1.StaticSite{}).
        Named(name).WithOptions(opts).Complete(reconcile.Func(only))).To(Succeed())
    c, stop := context.WithCancel(ctx)
    go func() {
        defer GinkgoRecover()
        Expect(mgr.Start(c)).To(Succeed())
    }()
    return stop
}
EOF

runController baut für jede Messung einen frischen Manager mit einem reconcile.Func – so misst du die Mechanik von controller-runtime, nicht deinen Reconciler.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Worker – MaxConcurrentReconciles

Die Datei queue_test.go misst beides, was die Queue ausmacht: Worker (dieser Drill) und Backoff (Drill 3). Jeder Mess-Reconcile der ersten Spec schläft 200 ms (ein langsamer API- oder Registrar-Aufruf); 20 Sites, 1, 4 und 10 Worker:

cat > test/scale/queue_test.go <<'EOF'
package scale

import (
    "context"
    "errors"
    "fmt"
    "sync"
    "sync/atomic"
    "time"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    "k8s.io/client-go/util/workqueue"
    "sigs.k8s.io/controller-runtime/pkg/controller"
    "sigs.k8s.io/controller-runtime/pkg/reconcile"
)

var _ = Describe("MaxConcurrentReconciles", func() {
    It("arbeitet 20 langsame Reconciles mit 1, 4 und 10 Workern ab", func() {
        createSites("workers", 20)
        for _, w := range []int{1, 4, 10} {
            var done, active, peak atomic.Int32
            start := time.Now()
            stop := runController(fmt.Sprint("workers-", w), "workers",
                controller.Options{MaxConcurrentReconciles: w},
                func(context.Context, reconcile.Request) (reconcile.Result, error) {
                    n := active.Add(1)
                    for p := peak.Load(); n > p; p = peak.Load() {
                        if peak.CompareAndSwap(p, n) {
                            break
                        }
                    }
                    time.Sleep(200 * time.Millisecond) // langsamer API-Call
                    active.Add(-1)
                    done.Add(1)
                    return reconcile.Result{}, nil
                })
            Eventually(done.Load).WithTimeout(10 * time.Second).Should(BeEquivalentTo(20))
            stop()
            GinkgoWriter.Printf("Worker=%2d  Dauer=%-6v  parallel max=%d\n",
                w, time.Since(start).Round(10*time.Millisecond), peak.Load())
            Expect(peak.Load()).To(BeNumerically("<=", w))
        }
    })
})

type limiter = workqueue.TypedRateLimiter[reconcile.Request]

// gaps lässt einen immer scheiternden Reconciler 8 s laufen und liefert
// die Abstände zwischen den Versuchen.
func gaps(name string, rl limiter) []time.Duration {
    var mu sync.Mutex
    var calls []time.Time
    stop := runController(name, "backoff", controller.Options{RateLimiter: rl},
        func(context.Context, reconcile.Request) (reconcile.Result, error) {
            mu.Lock()
            defer mu.Unlock()
            calls = append(calls, time.Now())
            return reconcile.Result{}, errors.New("registrar nicht erreichbar")
        })
    time.Sleep(8 * time.Second) // Messfenster, kein Warten auf einen Zustand
    stop()
    mu.Lock()
    defer mu.Unlock()
    var d []time.Duration
    for i := 1; i < len(calls); i++ {
        d = append(d, calls[i].Sub(calls[i-1]).Round(time.Millisecond))
    }
    return d
}

var _ = Describe("Backoff", func() {
    It("vergleicht Standard- und eigenen Rate-Limiter", func() {
        createSites("backoff", 1)
        std := gaps("backoff-std", nil)
        GinkgoWriter.Printf("Standard  : %2d Versuche %v\n", len(std)+1, std)
        own := gaps("backoff-own", workqueue.
            NewTypedItemExponentialFailureRateLimiter[reconcile.Request](
            500*time.Millisecond, 30*time.Second))
        GinkgoWriter.Printf("0,5s..30s : %2d Versuche %v\n", len(own)+1, own)
        Expect(len(own)).To(BeNumerically("<", len(std)))
    })
})
EOF
go test ./test/scale/ -count=1 -v -ginkgo.v -ginkgo.focus=MaxConcurrent \
  | grep 'Worker='

Erwartet:

  Worker= 1  Dauer=4.23s   parallel max=1
  Worker= 4  Dauer=1.22s   parallel max=4
  Worker=10  Dauer=620ms   parallel max=10

Mit einem Worker addieren sich die Wartezeiten (20 × 200 ms + Cache-Sync). Mehr Worker helfen, solange Reconcile wartet (Netzwerk) – nicht, wenn der API-Server schon am Limit ist. Dieselbe Site wird nie doppelt bearbeitet: Die Queue gibt einen Schlüssel erst wieder heraus, wenn sein Worker fertig ist.

Der Operator bekommt die Worker-Zahl als Feld. In internal/controller/staticsite_controller.go:

type StaticSiteReconciler struct {
    // ... bisherige Felder
    // Options: Worker-Zahl und Rate-Limiter, gesetzt in cmd/main.go (Tag 13).
    Options controller.Options
}

und in SetupWithManager vor Complete(r):

        Named("staticsite").
        WithOptions(r.Options).
        Complete(r)

(Import "sigs.k8s.io/controller-runtime/pkg/controller".) Das Flag und die Verdrahtung in cmd/main.go folgen in Drill 3 zusammen mit dem Backoff.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Backoff – der Rate-Limiter

Die zweite Spec in queue_test.go (gaps) lässt einen Reconciler immer scheitern – wie bei einem ausgefallenen Registrar – und misst 8 Sekunden lang die Abstände zwischen den Versuchen: einmal mit dem Standard-Limiter, einmal mit 0,5 s bis 30 s.

go test ./test/scale/ -count=1 -v -ginkgo.v -ginkgo.focus=Backoff | grep Versuche

Erwartet:

  Standard  : 11 Versuche [5ms 11ms 21ms 41ms 82ms 161ms 322ms 642ms 1.282s 2.561s]
  0,5s..30s :  5 Versuche [502ms 1s 2.002s 4.001s]

Der Standard verdoppelt ab 5 ms bis maximal 1000 s. In den ersten Sekunden hämmert der Operator also zehnmal auf den kaputten Dienst. Seit controller-runtime v0.23 nutzt jeder Controller standardmäßig die Priority Queue – mit rein exponentiellem Limiter pro Schlüssel; der frühere zusätzliche Token-Bucket (10 QPS über alle Schlüssel) entfällt. Ein Erfolg setzt den Zähler des Schlüssels zurück (Forget).

Jetzt in den Operator damit. In cmd/main.go drei Flags zu den anderen:

    var workers int
    var backoffBase, backoffMax time.Duration
    flag.IntVar(&workers, "max-concurrent-reconciles", 4,
        "Parallele Reconciles des StaticSite-Controllers")
    flag.DurationVar(&backoffBase, "backoff-base", 500*time.Millisecond,
        "Erste Wartezeit nach einem Reconcile-Fehler")
    flag.DurationVar(&backoffMax, "backoff-max", 5*time.Minute,
        "Längste Wartezeit nach wiederholten Fehlern")

Und beim Erzeugen des Reconcilers:

    if err := (&controller.StaticSiteReconciler{
        // ... Client, Scheme, Recorder wie bisher
        Registrar: reg,
        Options: ctrlcontroller.Options{
            MaxConcurrentReconciles: workers,
            RateLimiter: workqueue.
                NewTypedItemExponentialFailureRateLimiter[reconcile.Request](
                    backoffBase, backoffMax),
        },
    }).SetupWithManager(mgr); err != nil {

Neue Imports: "time", "k8s.io/client-go/util/workqueue", ctrlcontroller "sigs.k8s.io/controller-runtime/pkg/controller" (der Name controller ist schon dein eigenes Paket) und "sigs.k8s.io/controller-runtime/pkg/reconcile".

Terminal 1: envtest-up --crds config/crd/bases (bis Tagesende). Terminal 2: Operator im Hintergrund, mit einem Registrar, den es nicht gibt:

make build >/dev/null
bin/manager -health-probe-bind-address=:8081 --metrics-bind-address=:8080 \
  --metrics-secure=false --registrar-url=http://127.0.0.1:18099 \
  > lab/run.log 2>&1 &
echo $! > lab/manager.pid
kubectl apply -f lab/site.yaml
sleep 10
grep 'Reconciler error' lab/run.log | awk '{print $1}' | cut -c12-19 | uniq -c
curl -s localhost:8080/metrics | grep '^controller_runtime_max_concurrent'

Erwartet:

staticsite.web.lab.example/demo created
   2 11:56:10
   1 11:56:11
   1 11:56:13
   1 11:56:17
controller_runtime_max_concurrent_reconciles{controller="staticsite"} 4

Vier Worker, und der Abstand zwischen den Fehlern verdoppelt sich ab 0,5 s. Mit dem Standard-Limiter wären es in denselben 10 Sekunden über zehn Versuche gewesen. --backoff-max begrenzt nach oben: Kommt der Dienst zurück, ist der Operator spätestens nach dieser Zeit wieder dran.

kill "$(cat lab/manager.pid)"

Tipp: RequeueAfter (Tag 4) läuft am Rate-Limiter vorbei: fester Termin, kein Backoff. Für „Inhalt fehlt noch” richtig, für „Dienst kaputt” falsch – dort gehört der Fehler zurückgegeben.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Konflikte provozieren

Update schickt die resourceVersion des gelesenen Objekts mit. Hat ein anderer inzwischen geschrieben, lehnt der API-Server ab: 409 Conflict. Zwanzig Goroutinen schreiben gleichzeitig dieselbe Site:

cat > test/scale/conflict_test.go <<'EOF'
package scale

import (
    "fmt"
    "sync"
    "sync/atomic"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    apierrors "k8s.io/apimachinery/pkg/api/errors"
    "k8s.io/client-go/util/retry"
    "sigs.k8s.io/controller-runtime/pkg/client"

    webv1 "example.com/site-operator/api/v1"
)

// write liest die Site, setzt eine eigene Annotation und schreibt zurück –
// per Update (mit resourceVersion) oder per Merge-Patch (nur der Diff).
func write(i int, patch bool) error {
    var s webv1.StaticSite
    key := client.ObjectKey{Namespace: "conflict", Name: "s0"}
    if err := k8sClient.Get(ctx, key, &s); err != nil {
        return err
    }
    base := s.DeepCopy()
    if s.Annotations == nil {
        s.Annotations = map[string]string{}
    }
    s.Annotations[fmt.Sprint("writer-", i)] = "x"
    if patch {
        return k8sClient.Patch(ctx, &s, client.MergeFrom(base))
    }
    return k8sClient.Update(ctx, &s)
}

// race lässt 20 Goroutinen gleichzeitig schreiben und zählt 409-Fehler.
func race(name string, f func(i int) error) int32 {
    var conflicts atomic.Int32
    var wg sync.WaitGroup
    for i := range 20 {
        wg.Go(func() {
            defer GinkgoRecover()
            if err := f(i); apierrors.IsConflict(err) {
                conflicts.Add(1)
            } else {
                Expect(err).NotTo(HaveOccurred())
            }
        })
    }
    wg.Wait()
    GinkgoWriter.Printf("%-24s 20 Schreiber, %2d Konflikte\n", name, conflicts.Load())
    return conflicts.Load()
}

var _ = Describe("Konflikte", func() {
    It("provoziert 409 und vergleicht Gegenmittel", func() {
        createSites("conflict", 1)
        update := func(i int) error { return write(i, false) }
        Expect(race("Update", update)).To(BeNumerically(">", 0))
        race("RetryOnConflict", func(i int) error {
            return retry.RetryOnConflict(retry.DefaultBackoff,
                func() error { return update(i) })
        })
        Expect(race("MergeFrom-Patch", func(i int) error { return write(i, true) })).
            To(BeZero())
    })
})
EOF
go test ./test/scale/ -count=1 -v -ginkgo.v -ginkgo.focus=Konflikte | grep Schreiber

Erwartet (die Zahlen schwanken von Lauf zu Lauf):

  Update                   20 Schreiber, 19 Konflikte
  RetryOnConflict          20 Schreiber,  8 Konflikte
  MergeFrom-Patch          20 Schreiber,  0 Konflikte

Was du daraus lernst:

  • Nur einer von zwanzig gewinnt. Optimistisches Locking verhindert, dass Änderungen still verloren gehen.
  • retry.RetryOnConflict mit DefaultBackoff (4 Versuche ab 10 ms) senkt die Zahl, garantiert aber nichts; DefaultRetry (5 × 10 ms) streut noch weniger.
  • Ein Merge-Patch schickt keine resourceVersion, nur den Diff – kein Konflikt. Dafür überschreibt er Listen komplett; wer das nicht will, nimmt client.MergeFromWithOptions(base, client.MergeFromWithOptimisticLock{}).

Im Controller gilt: nicht in Reconcile mit Schleifen wiederholen. Ein Konflikt heißt „mein Cache war veraltet” – neu lesen, neu rechnen. Genau das macht die Queue. Wie sieht das im echten Operator aus? Starte ihn ohne Registrar und hämmere parallel auf Spec, Deployment und Service:

bin/manager -health-probe-bind-address=:8081 > lab/run.log 2>&1 &
echo $! > lab/manager.pid
cat > lab/hammer.sh <<'EOF'
# 100 Runden: Spec ändern und gleichzeitig Deployment/Service annotieren
for i in $(seq 1 100); do
  kubectl patch staticsite demo --type=merge \
    -p "{\"spec\":{\"replicas\":$((i % 3 + 1))}}" >/dev/null &
  kubectl annotate deploy demo hammer=$i --overwrite >/dev/null &
  kubectl annotate svc demo hammer=$i --overwrite >/dev/null &
done
wait
EOF
sleep 3; bash lab/hammer.sh; sleep 2
echo "Konflikte: $(grep -c 'object has been modified' lab/run.log)"
echo "Reconciler error: $(grep -c 'Reconciler error' lab/run.log)"
echo "Warning-Events: $(grep -c '"type": "Warning"' lab/run.log)"

Erwartet (Zahlen schwanken):

Konflikte: 27
Reconciler error: 23
Warning-Events: 4

Der eigentliche Schaden steht in der letzten Zeile: Jeder Konflikt landet über updateStatus als Degraded=True mit Reason ReconcileError im Status und als Warning-Event – Alarm für etwas, das sich eine Zehntelsekunde später von selbst erledigt. Konflikte sind kein Fehlerzustand. In Reconcile direkt nach reconcileResources:

    dep, recErr := r.reconcileResources(ctx, &site)
    if apierrors.IsConflict(recErr) {
        // Jemand hat zwischen Cache-Lesen und Schreiben geändert: kein Fehler-
        // zustand, nur veraltete Daten. Status nicht anfassen, gleich neu lesen.
        logf.FromContext(ctx).V(1).Info("Konflikt, neuer Versuch",
            "error", recErr.Error())
        return ctrl.Result{RequeueAfter: 100 * time.Millisecond}, nil
    }

apierrors.IsConflict findet den 409 auch in Fehlern, die mit %w verpackt sind.

make build >/dev/null && kill "$(cat lab/manager.pid)"
bin/manager -health-probe-bind-address=:8081 > lab/run.log 2>&1 &
echo $! > lab/manager.pid
sleep 3; bash lab/hammer.sh; sleep 2
echo "Konflikte: $(grep -c 'Konflikt, neuer Versuch' lab/run.log)"
echo "Reconciler error: $(grep -c 'Reconciler error' lab/run.log)"
echo "Warning-Events: $(grep -c '"type": "Warning"' lab/run.log)"

Erwartet:

Konflikte: 4
Reconciler error: 0
Warning-Events: 0

Konflikte gibt es weiter – aber leise, ohne falschen Alarm und ohne Backoff-Strafe.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Server-Side Apply und Field Manager

Der zweite Weg aus den Konflikten: Server-Side Apply (SSA). Der Operator schickt nur die Felder, die er besitzen will; der API-Server führt zusammen und merkt sich in managedFields, wem welches Feld gehört. Keine resourceVersion, kein 409 durch fremde Schreiber auf anderen Feldern. Der Service ist der kleinste Kandidat. Ersetze reconcileService komplett:

// reconcileService nutzt Server-Side Apply: Der API-Server führt zusammen,
// wem welches Feld gehört (managedFields). Kein resourceVersion, kein 409.
func (r *StaticSiteReconciler) reconcileService(ctx context.Context,
    site *webv1alpha1.StaticSite) error {
    owner := metav1ac.OwnerReference().
        WithAPIVersion(webv1alpha1.GroupVersion.String()).WithKind("StaticSite").
        WithName(site.Name).WithUID(site.UID).
        WithController(true).WithBlockOwnerDeletion(true)
    svc := corev1ac.Service(site.Name, site.Namespace).
        WithLabels(labelsFor(site)).
        WithOwnerReferences(owner).
        WithSpec(corev1ac.ServiceSpec().
            WithSelector(selectorLabels(site)).
            WithPorts(corev1ac.ServicePort().
                WithName("http").WithPort(80).WithProtocol(corev1.ProtocolTCP).
                WithTargetPort(intstr.FromInt32(containerPort))))
    err := r.Apply(ctx, svc, client.FieldOwner(fieldOwner), client.ForceOwnership)
    if err != nil {
        return fmt.Errorf("service: %w", err)
    }
    return nil
}

Dazu eine Konstante und drei Imports:

// fieldOwner steht in managedFields aller Felder, die der Operator per Apply setzt.
const fieldOwner = "site-operator"
    "k8s.io/apimachinery/pkg/util/intstr"
    corev1ac "k8s.io/client-go/applyconfigurations/core/v1"
    metav1ac "k8s.io/client-go/applyconfigurations/meta/v1"

client.Client.Apply mit typisierten Apply Configurations ist seit controller-runtime v0.22 der empfohlene Weg; client.Patch(…, client.Apply) ist deprecated. Der Zähler countWrite("Service", …) entfällt – SSA meldet kein „unchanged/updated”. mutateService in resources.go braucht niemand mehr – lösche die Funktion samt intstr-Import dort, sonst meldet make lint sie als unused.

make build >/dev/null && kill "$(cat lab/manager.pid)"
kubectl delete service demo
bin/manager -health-probe-bind-address=:8081 > lab/run.log 2>&1 &
echo $! > lab/manager.pid
sleep 3
kubectl get svc demo --show-managed-fields \
  -o jsonpath='{range .metadata.managedFields[*]}{.manager} {.operation}{"\n"}{end}'

Erwartet:

service "demo" deleted from default namespace
site-operator Apply

Jetzt will „Team A” den Port per SSA ändern:

cat > lab/svc-team-a.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: demo
spec:
  ports:
  - name: http
    port: 80
    targetPort: 9090
EOF
kubectl apply --server-side --field-manager=team-a -f lab/svc-team-a.yaml 2>&1 \
  | head -1 | cut -c1-80
kubectl apply --server-side --field-manager=team-a --force-conflicts \
  -f lab/svc-team-a.yaml
sleep 2
kubectl get svc demo -o jsonpath='{.spec.ports[0].targetPort}{"\n"}'

Erwartet:

error: Apply failed with 1 conflict: conflict with "site-operator": .spec.ports[
service/demo serverside-applied
8080

Der Konflikt ist hier gewollt: Er sagt Team A, wem das Feld gehört. Mit --force-conflicts übernimmt Team A trotzdem – der Operator sieht die Änderung (Owns), applied erneut mit ForceOwnership und holt sich 8080 zurück. Felder, die der Operator nicht setzt (Annotationen, zusätzliche Labels), lässt SSA in Ruhe.

Achtung: Wechselst du ein Objekt von Update auf Apply, bleibt der alte Manager (manager, Operation Update) in managedFields stehen und besitzt weiter seine Felder. Entfernst du später ein Feld aus deiner Apply-Konfiguration, löscht der API-Server es deshalb nicht. Darum oben das kubectl delete service demo – in Produktion migriert man die managedFields (siehe csaupgrade in client-go).

Fortschritt speichern? Kostenlos registrieren

Drill 6: Den Cache verschlanken

Owns(&corev1.ConfigMap{}) heißt: Der Manager cacht alle ConfigMaps im Cluster – auch die, die mit dem Operator nichts zu tun haben. Wie viel kostet das? Die Datei enthält schon die Hilfsfunktion pages für Drill 7.

cat > test/scale/cache_test.go <<'EOF'
package scale

import (
    "fmt"
    "runtime"
    "sync"
    "time"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/labels"
    "k8s.io/client-go/kubernetes/scheme"
    "sigs.k8s.io/controller-runtime/pkg/cache"
    "sigs.k8s.io/controller-runtime/pkg/client"
)

var cmOnce sync.Once

// ensureConfigMaps legt einmalig 2000 ConfigMaps mit 30 Schlüsseln in "mem" an.
func ensureConfigMaps() {
    cmOnce.Do(func() {
        createSites("mem", 0)
        data := map[string]string{}
        for k := range 30 {
            data[fmt.Sprint("key-", k)] = "wert"
        }
        for i := range 2000 {
            cm := &corev1.ConfigMap{Data: data}
            cm.Name, cm.Namespace = fmt.Sprint("cm-", i), "mem"
            Expect(k8sClient.Create(ctx, cm)).To(Succeed())
        }
    })
}

func heapKiB() int64 {
    runtime.GC()
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    return int64(m.HeapAlloc) / 1024
}

// cacheCost startet einen ConfigMap-Cache und misst den belegten Heap.
func cacheCost(name string, opts cache.Options) {
    time.Sleep(time.Second) // vorherige Caches sicher beenden lassen
    before := heapKiB()
    opts.Scheme = scheme.Scheme
    c, err := cache.New(cfg, opts)
    Expect(err).NotTo(HaveOccurred())
    var l corev1.ConfigMapList
    go func() { _ = c.Start(ctx) }()
    Expect(c.WaitForCacheSync(ctx)).To(BeTrue())
    Expect(c.List(ctx, &l, client.InNamespace("mem"))).To(Succeed()) // lädt Informer
    GinkgoWriter.Printf("%-16s %4d Objekte %6d KiB\n", name, len(l.Items),
        heapKiB()-before)
    runtime.KeepAlive(c)
}

var _ = Describe("Cache-Speicher", func() {
    It("misst den Heap je Cache-Variante", func() {
        ensureConfigMaps()
        cacheCost("alles", cache.Options{})
        cacheCost("ohne managedF.", cache.Options{
            DefaultTransform: cache.TransformStripManagedFields()})
        cacheCost("nur managed-by", cache.Options{ByObject: map[client.Object]cache.ByObject{
            &corev1.ConfigMap{}: {Label: labels.SelectorFromSet(labels.Set{
                "app.kubernetes.io/managed-by": "site-operator"})}}})
    })
})

// pages listet die 2000 ConfigMaps aus "mem" in Seiten zu 500.
func pages(r client.Reader) error {
    for cont, n := "", 1; ; n++ {
        var l corev1.ConfigMapList
        err := r.List(ctx, &l, client.InNamespace("mem"), client.Limit(500),
            client.Continue(cont))
        if err != nil {
            return err
        }
        GinkgoWriter.Printf("Seite %d: %3d Objekte, continue=%q\n", n, len(l.Items),
            l.Continue[:min(12, len(l.Continue))])
        if cont = l.Continue; cont == "" {
            return nil
        }
    }
}

var _ = Describe("Pagination", Ordered, func() {
    It("liest vom API-Server seitenweise", func() {
        ensureConfigMaps()
        Expect(pages(k8sClient)).To(Succeed())
    })
    It("scheitert am Cache", func() {
        c, err := cache.New(cfg, cache.Options{Scheme: scheme.Scheme})
        Expect(err).NotTo(HaveOccurred())
        go func() { _ = c.Start(ctx) }()
        Expect(c.WaitForCacheSync(ctx)).To(BeTrue())
        err = pages(c)
        GinkgoWriter.Println("Cache:", err)
        Expect(err).To(HaveOccurred())
    })
})
EOF
go test ./test/scale/ -count=1 -v -ginkgo.v -ginkgo.focus=Cache-Speicher \
  | grep 'KiB'

Erwartet (Heap-Messungen schwanken um einige Prozent):

  alles            2000 Objekte   8124 KiB
  ohne managedF.   2000 Objekte   6984 KiB
  nur managed-by      0 Objekte    391 KiB

managedFields (Drill 5) machen bei kleinen Objekten rund 15 % aus – der Operator liest sie nie. Den größten Hebel hat ein Label-Selektor wie an Tag 10 für Deployments und Services: Fremde Objekte kommen gar nicht erst in den Speicher. Für ConfigMaps geht das bei uns nicht, weil die Quell-ConfigMaps der Nutzer kein Operator-Label tragen (Tag 10) – also bleibt der Transform. In internal/controller/cache.go wird CacheOptions zu:

    return cache.Options{
        ByObject: map[client.Object]cache.ByObject{
            &appsv1.Deployment{}: {Label: mine},
            &corev1.Service{}:    {Label: mine},
        },
        // managedFields braucht der Operator nicht – raus aus dem Speicher.
        DefaultTransform: cache.TransformStripManagedFields(),
    }

Weil Manager und Test-Suite dieselbe Funktion nutzen, gilt der Transform überall.

Achtung: Was nicht im Cache ist, findet r.Get nicht – auch nicht, wenn es im Cluster existiert. Objekte außerhalb des Selektors liest du über mgr.GetAPIReader() (direkt vom API-Server, ohne Cache) oder nimmst den Typ per client.Options{Cache: &client.CacheOptions{DisableFor: …}} ganz aus dem Cache.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Große Listen seitenweise

Ein List ohne Limit holt alles in einem Rutsch – bei 50 000 Objekten eine Antwort von hunderten MB und Last auf etcd. Der API-Server kann seitenweise (limit + continue), der Cache nicht. pages aus cache_test.go liest die 2000 ConfigMaps in Seiten zu 500 – einmal über den direkten Client, einmal über einen Cache:

go test ./test/scale/ -count=1 -v -ginkgo.v -ginkgo.focus=Pagination \
  | grep -E 'Seite|Cache:'

Erwartet:

  Seite 1: 500 Objekte, continue="eyJ2IjoibWV0"
  Seite 2: 500 Objekte, continue="eyJ2IjoibWV0"
  Seite 3: 500 Objekte, continue="eyJ2IjoibWV0"
  Seite 4: 500 Objekte, continue=""
  Seite 1: 500 Objekte, continue="continue-not"
  Cache: continue list option is not supported by the cache

Der Cache nimmt Limit an, schneidet aber nur ab und setzt den Platzhalter continue-not-supported als Token – dieselbe Schleife scheitert in Runde 2. Der continue-Token des API-Servers ist ein opaker String; er verfällt nach einigen Minuten (etcd-Compaction). Seitenweise listen heißt deshalb: mgr.GetAPIReader() (Tools, Migrationen, Aufräumjobs). Im Reconcile liest du ohnehin aus dem Cache – dort ist List billig, weil er lokal im Speicher läuft.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Leader-Election-Fallen

An Tag 11 dauerte der Wechsel nach einem sauberen kill 17 Sekunden: Der alte Leader hielt die Lease bis zum Ablauf. In cmd/main.go steht im Gerüst schon der Kommentar dazu – aktiviere die Option in den ctrl.Options:

        LeaderElectionReleaseOnCancel: true,

Das ist sicher, weil main nach mgr.Start sofort endet: Nach dem Freigeben der Lease arbeitet dieser Prozess garantiert nicht weiter.

make build >/dev/null && kill "$(cat lab/manager.pid)"
bin/manager -health-probe-bind-address=:8081 --leader-elect \
  --leader-election-namespace=default > lab/le-1.log 2>&1 &
echo $! > lab/le-1.pid
until grep -q 'Successfully acquired' lab/le-1.log; do sleep 0.5; done
bin/manager -health-probe-bind-address=:8082 --leader-elect \
  --leader-election-namespace=default > lab/le-2.log 2>&1 &
echo $! > lab/le-2.pid
sleep 3
date +%T.%N | cut -c1-12; kill "$(cat lab/le-1.pid)"
until grep -q 'Successfully acquired' lab/le-2.log; do sleep 0.1; done
date +%T.%N | cut -c1-12
kill "$(cat lab/le-2.pid)"

Erwartet:

11:57:35.267
11:57:36.291

Eine Sekunde statt 17 – der Wartende fragt im Takt von RetryPeriod (2 s) nach, je nach Zeitpunkt dauert es also 0 bis 2 Sekunden. Bei kill -9, OOM-Kill oder Node-Ausfall hilft das nicht – dort bleibt es bei LeaseDuration. Die Stellschrauben:

Option Standard Bedeutung
LeaseDuration 15 s So lange warten Anwärter nach dem letzten Renew
RenewDeadline 10 s Schafft der Leader kein Renew, gibt er auf
RetryPeriod 2 s Takt für Renew- und Übernahmeversuche
LeaderElectionReleaseOnCancel false Lease beim sauberen Stopp freigeben

Die Fallen in der Praxis:

  • Kürzer ist nicht besser. Schafft der Leader das Renew nicht (überlasteter API-Server), kehrt mgr.Start mit leader election lost zurück und der Prozess endet – gewollt, damit nie zwei Leader schreiben. Häufige Neustarts mit dieser Meldung: Zeiten erhöhen, API-Server prüfen.
  • Nicht alles ist Leader-gebunden. Webhooks, Probes und Metriken laufen auf jeder Replica; eigene Runnables (mgr.Add) laufen standardmäßig nur auf dem Leader. Soll ein Runnable überall laufen (z. B. ein Cache-Wärmer), implementiert es NeedLeaderElection() bool mit false.
  • Gleiche ID, gleicher Namespace. LeaderElectionID muss über alle Versionen des Operators gleich bleiben. Ändert ein Upgrade die ID, laufen während des Rollouts alte und neue Version gleichzeitig als Leader.
  • Kein Ersatz für Idempotenz. Zwischen Lease-Verlust und Prozessende vergehen Millisekunden, in denen ein Reconcile noch schreibt – Reconcile muss deshalb immer idempotent bleiben.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cat > lab/check.sh <<'EOF'
ok()  { echo "✔ $1"; }
nok() { echo "✘ $1"; }
out=$(go test ./test/scale/ -count=1 -v -ginkgo.v -ginkgo.no-color 2>&1)
echo "$out" | grep -q '^SUCCESS!' && ok "Mess-Suite grün" || nok "Mess-Suite rot"
echo "$out" | grep -q 'MergeFrom-Patch .* 0 Konflikte' && ok "Patch ohne 409" \
  || nok "Patch-Konflikte"
go test ./internal/... -count=1 >/dev/null 2>&1 && ok "Controller-Tests grün" \
  || nok "Controller-Tests rot"
grep -q 'WithOptions(r.Options)' internal/controller/staticsite_controller.go \
  && ok "Controller-Optionen verdrahtet" || nok "WithOptions fehlt"
grep -q 'apierrors.IsConflict(recErr)' internal/controller/staticsite_controller.go \
  && ok "Konflikte leise" || nok "Konflikt-Behandlung fehlt"
grep -q 'client.FieldOwner(fieldOwner)' internal/controller/staticsite_controller.go \
  && ok "SSA mit Field Owner" || nok "SSA fehlt"
grep -q 'TransformStripManagedFields' internal/controller/cache.go \
  && ok "Cache-Transform" \
  || nok "Transform fehlt"
grep -q 'LeaderElectionReleaseOnCancel: *true' cmd/main.go && ok "ReleaseOnCancel" \
  || nok "ReleaseOnCancel fehlt"
EOF
bash lab/check.sh

Erwartet:

✔ Mess-Suite grün
✔ Patch ohne 409
✔ Controller-Tests grün
✔ Controller-Optionen verdrahtet
✔ Konflikte leise
✔ SSA mit Field Owner
✔ Cache-Transform
✔ ReleaseOnCancel

Challenge

Mach die Lease-Dauer per Flag --lease-duration einstellbar (Standard 15 s) und leite RenewDeadline als zwei Drittel davon ab. Miss danach mit kill -9 den Wechsel bei --lease-duration=6s.

Hinweis: ctrl.Options erwartet für LeaseDuration und RenewDeadline Zeiger (*time.Duration); RenewDeadline muss kleiner als LeaseDuration sein, sonst startet der Manager nicht.

Lösung

    var leaseDuration time.Duration
    flag.DurationVar(&leaseDuration, "lease-duration", 15*time.Second,
        "Gültigkeit der Leader-Lease")
    // ... nach flag.Parse():
    renewDeadline := leaseDuration * 2 / 3
    // ... in ctrl.Options:
        LeaseDuration: &leaseDuration,
        RenewDeadline: &renewDeadline,
make build >/dev/null
bin/manager -health-probe-bind-address=:8081 --leader-elect \
  --leader-election-namespace=default --lease-duration=6s > lab/le-1.log 2>&1 &
echo $! > lab/le-1.pid
until grep -q 'Successfully acquired' lab/le-1.log; do sleep 0.5; done
bin/manager -health-probe-bind-address=:8082 --leader-elect \
  --leader-election-namespace=default --lease-duration=6s > lab/le-2.log 2>&1 &
echo $! > lab/le-2.pid
sleep 3
date +%T; kill -9 "$(cat lab/le-1.pid)"
until grep -q 'Successfully acquired' lab/le-2.log; do sleep 0.2; done; date +%T
kill "$(cat lab/le-2.pid)"

Erwartet:

12:00:57
12:01:03

Der Code-Stand in code/tag13-site-operator enthält die Challenge nicht.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Worker-Zahl und Backoff gehören in die Helm-Values (manager.args) und werden unter Last gemessen, nicht geschätzt: workqueue_depth, workqueue_queue_duration_seconds und controller_runtime_reconcile_time_seconds zeigen, ob mehr Worker helfen.
  • Der API-Server schützt sich selbst mit API Priority and Fairness (APF). Ein Operator mit vielen Workern landet in der FlowSchema seines ServiceAccounts und wird gedrosselt (HTTP 429) – eigene FlowSchema/PriorityLevel für kritische Operatoren mit dem Plattform-Team abstimmen.
  • Client-seitig drosselt controller-runtime standardmäßig nicht: ctrl.GetConfigOrDie() setzt QPS = -1 und verlässt sich auf APF. Wer eigene Grenzen braucht (z. B. ein geteilter API-Server beim Kunden), setzt cfg.QPS/cfg.Burst bewusst selbst.
  • Speicher: Der Cache wächst mit der Zahl aller beobachteten Objekte im Cluster. Label-Selektoren, DefaultNamespaces (nur bestimmte Namespaces) und Transforms vor dem ersten Kunden mit 10 000 ConfigMaps einbauen; Memory-Limit des Pods danach messen.
  • SSA konsequent: ein fester Field Manager je Operator (nie der Binary-Name), ForceOwnership nur für Felder, die wirklich dem Operator gehören. Migrationen von Update auf Apply mit csaupgrade planen – sonst bleiben verwaiste Feldbesitzer.