Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 10: Watches, Predicates und Indexer

Ziel: Der site-operator reagiert sofort auf Änderungen an referenzierten ConfigMaps (Watch + Field-Index), ignoriert unnötige Ereignisse (Predicate) und cacht nur, was ihm gehört (Label-Selektor) · Dauer: ca. 120 min · Voraussetzung: Tag 9

Briefing

  • For() und Owns() kennen nur Besitzverhältnisse. Eine referenzierte ConfigMap gehört dem Nutzer – ihre Änderungen sieht der Controller bisher nur über den 30-s-Requeue aus Tag 4.
  • Watches() + handler.EnqueueRequestsFromMapFunc übersetzt ein Ereignis an Objekt A in Requests für Objekte B.
  • Damit die Übersetzung nicht jedes Mal alle StaticSites durchsucht, gibt es einen Field-Index im Cache.
  • Predicates filtern Ereignisse, bevor sie in der Queue landen. Cache-Selektoren filtern schon beim Watch am API-Server.
ConfigMap html geändert
   -> Informer (ConfigMap) -> MapFunc sitesForConfigMap
        -> List StaticSites MatchingFields{.spec.source.configMapRef.name: html}
        -> Requests: ns/ref, ns/andere ...  -> Workqueue -> Reconcile
StaticSite nur Label/Annotation geändert -> GenerationChangedPredicate -> verworfen

Drill 1: Erst der Test – und er ist rot

source ~/op-lab/env.sh
cp -r ~/op-lab/tag09-site-operator ~/op-lab/tag10-site-operator
cd ~/op-lab/tag10-site-operator

Zwei Erwartungen als envtest-Specs: Die Site reagiert innerhalb von 5 s auf ihre Quelle, und reine Metadaten-Änderungen lösen keinen Reconcile aus.

cat > internal/controller/watches_test.go <<'EOF'
package controller

import (
    "time"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "sigs.k8s.io/controller-runtime/pkg/client"

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

var _ = Describe("Watch auf referenzierte ConfigMaps", func() {
    It("reagiert sofort auf Anlegen und Ändern der Quelle", func(ctx SpecContext) {
        ns := newNamespace(ctx)
        site := newStaticSite(ns, "ref", func(s *webv1.StaticSite) {
            s.Spec.Content = ""
            s.Spec.Source = &webv1.ContentSource{
                ConfigMapRef: &webv1.ConfigMapReference{Name: "html"}}
        })
        Expect(k8sClient.Create(ctx, site)).To(Succeed())

        hash := func() string {
            var dep appsv1.Deployment
            key := client.ObjectKey{Namespace: ns, Name: "ref"}
            if err := k8sClient.Get(ctx, key, &dep); err != nil {
                return ""
            }
            return dep.Spec.Template.Annotations["web.lab.example/content-hash"]
        }
        Consistently(hash, time.Second).Should(BeEmpty()) // Quelle fehlt noch

        src := &corev1.ConfigMap{
            ObjectMeta: metav1.ObjectMeta{Name: "html", Namespace: ns},
            Data:       map[string]string{"index.html": "<h1>v1</h1>"},
        }
        Expect(k8sClient.Create(ctx, src)).To(Succeed())
        Eventually(hash, 5*time.Second).ShouldNot(BeEmpty()) // nicht erst nach 30 s
        before := hash()

        src.Data["index.html"] = "<h1>v2</h1>"
        Expect(k8sClient.Update(ctx, src)).To(Succeed())
        Eventually(hash, 5*time.Second).ShouldNot(Equal(before))
    })
})
EOF

Den zweiten Test misst du an der Metrik controller_runtime_reconcile_total, die controller-runtime ohnehin für jeden Controller führt:

cat > internal/controller/predicate_test.go <<'EOF'
package controller

import (
    "time"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/metrics"
)

// reconciles liest controller_runtime_reconcile_total für unseren Controller.
func reconciles() float64 {
    families, err := metrics.Registry.Gather()
    Expect(err).NotTo(HaveOccurred())
    var sum float64
    for _, f := range families {
        if f.GetName() != "controller_runtime_reconcile_total" {
            continue
        }
        for _, m := range f.GetMetric() {
            for _, l := range m.GetLabel() {
                if l.GetName() == "controller" && l.GetValue() == "staticsite" {
                    sum += m.GetCounter().GetValue()
                }
            }
        }
    }
    return sum
}

var _ = Describe("GenerationChangedPredicate", func() {
    It("ignoriert Metadaten, reagiert auf spec", func(ctx SpecContext) {
        site := newStaticSite(newNamespace(ctx), "quiet")
        Expect(k8sClient.Create(ctx, site)).To(Succeed())
        Eventually(func() bool { // warten, bis der Controller zur Ruhe kommt
            n := reconciles()
            time.Sleep(time.Second)
            return n == reconciles()
        }, 20*time.Second).Should(BeTrue())
        Expect(k8sClient.Get(ctx, client.ObjectKeyFromObject(site), site)).
            To(Succeed())
        before := reconciles()

        patch := client.MergeFrom(site.DeepCopy())
        site.Annotations = map[string]string{"team": "web"}
        Expect(k8sClient.Patch(ctx, site, patch)).To(Succeed())
        Consistently(reconciles, 2*time.Second).Should(Equal(before))

        patch = client.MergeFrom(site.DeepCopy())
        site.Spec.Replicas = 2
        Expect(k8sClient.Patch(ctx, site, patch)).To(Succeed())
        Eventually(reconciles).Should(BeNumerically(">", before))
    })
})
EOF
go test ./internal/controller/ -count=1 -v -ginkgo.no-color \
  -ginkgo.focus='Watch|Generation' 2>&1 \
  | grep -E '^(Ran|FAIL!)|^  \[FAILED\] (Timed|Failed)'

Erwartet:

  [FAILED] Timed out after 5.002s.
  [FAILED] Failed after 0.011s.
Ran 2 of 23 Specs in 13.218 seconds
FAIL! -- 0 Passed | 2 Failed | 0 Pending | 21 Skipped

Beide rot – genau richtig. Die Quelle kommt erst nach 30 s an, und die Annotation weckt den Controller.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Field-Index und MapFunc

Der Index ist eine Funktion „Objekt → Schlüssel”. controller-runtime pflegt ihn im Informer-Cache; List mit MatchingFields fragt ihn ab, ohne den API-Server zu belasten.

cat > internal/controller/watches.go <<'EOF'
package controller

import (
    "context"

    "sigs.k8s.io/controller-runtime/pkg/client"
    logf "sigs.k8s.io/controller-runtime/pkg/log"
    "sigs.k8s.io/controller-runtime/pkg/reconcile"

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

// configMapRefIndex ist der Name des Field-Index im Cache.
const configMapRefIndex = ".spec.source.configMapRef.name"

// indexConfigMapRef liefert die ConfigMap, auf die eine StaticSite zeigt.
func indexConfigMapRef(obj client.Object) []string {
    site := obj.(*webv1.StaticSite)
    if site.Spec.Source == nil || site.Spec.Source.ConfigMapRef == nil {
        return nil
    }
    return []string{site.Spec.Source.ConfigMapRef.Name}
}

// sitesForConfigMap übersetzt ein ConfigMap-Ereignis in Requests für alle
// StaticSites im selben Namespace, die auf diese ConfigMap zeigen.
func (r *StaticSiteReconciler) sitesForConfigMap(ctx context.Context,
    cm client.Object) []reconcile.Request {
    var sites webv1.StaticSiteList
    err := r.List(ctx, &sites, client.InNamespace(cm.GetNamespace()),
        client.MatchingFields{configMapRefIndex: cm.GetName()})
    if err != nil {
        logf.FromContext(ctx).Error(err, "StaticSites nicht lesbar")
        return nil
    }
    reqs := make([]reconcile.Request, 0, len(sites.Items))
    for _, s := range sites.Items {
        key := client.ObjectKeyFromObject(&s)
        reqs = append(reqs, reconcile.Request{NamespacedName: key})
    }
    return reqs
}
EOF

Warum Namespace und Index? ConfigMap-Referenzen gelten nur im eigenen Namespace (Tag 3). Ohne InNamespace würde eine ConfigMap html in team-a auch die Sites in team-b wecken.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Watch und Predicate verdrahten

SetupWithManager in internal/controller/staticsite_controller.go komplett ersetzen und die Imports builder, handler und predicate aus sigs.k8s.io/controller-runtime/pkg/... ergänzen:

// SetupWithManager: Owns() weckt den Besitzer bei Änderungen an Kindern,
// Watches() bei Änderungen an referenzierten ConfigMaps (Field-Index).
func (r *StaticSiteReconciler) SetupWithManager(mgr ctrl.Manager) error {
    if err := mgr.GetFieldIndexer().IndexField(context.Background(),
        &webv1.StaticSite{}, configMapRefIndex, indexConfigMapRef); err != nil {
        return err
    }
    return ctrl.NewControllerManagedBy(mgr).
        For(&webv1.StaticSite{},
            builder.WithPredicates(predicate.GenerationChangedPredicate{})).
        Owns(&corev1.ConfigMap{}).
        Owns(&appsv1.Deployment{}).
        Owns(&corev1.Service{}).
        Watches(&corev1.ConfigMap{},
            handler.EnqueueRequestsFromMapFunc(r.sitesForConfigMap)).
        Named("staticsite").
        Complete(r)
}
go vet ./... && go test ./internal/controller/ -count=1 -v -ginkgo.no-color \
  -ginkgo.focus='Watch|Generation' 2>&1 | grep -E '^(Ran|SUCCESS|FAIL!)'

Erwartet:

Ran 2 of 23 Specs in 10.430 seconds
SUCCESS! -- 2 Passed | 0 Failed | 0 Pending | 21 Skipped

Drei Details, die man leicht übersieht:

  • Der Index muss vor dem Start des Managers registriert sein – deshalb steht er in SetupWithManager, nicht im Reconcile.
  • GenerationChangedPredicate gilt nur für For(). metadata.generation steigt bei jeder spec-Änderung – und beim Löschen mit Finalizer (Tag 7), deshalb laufen die Finalizer-Tests weiter.
  • Status-Updates erhöhen die Generation nicht. Damit weckt dein eigenes Status().Patch den Controller nicht mehr – ein Hotloop-Risiko weniger.

Achtung: Ein Predicate auf For() filtert auch Änderungen, auf die du vielleicht reagieren willst – etwa Labels oder Annotationen als Schalter. Das ist die Challenge.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Nur cachen, was dir gehört

Jeder Owns()-Typ startet einen Informer – standardmäßig auf alle Objekte dieses Typs im Cluster. In einem Cluster mit 20 000 Deployments hält dein Operator dann 20 000 Deployments im Speicher, obwohl ihm zehn gehören. Der Cache-Selektor schränkt schon den Watch am API-Server ein:

cat > internal/controller/cache.go <<'EOF'
package controller

import (
    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/labels"
    "sigs.k8s.io/controller-runtime/pkg/cache"
    "sigs.k8s.io/controller-runtime/pkg/client"
)

// CacheOptions: Deployments und Services nur cachen, wenn sie uns gehören.
// ConfigMaps bleiben ungefiltert – die Quellen der Nutzer tragen kein Label.
func CacheOptions() cache.Options {
    mine := labels.SelectorFromSet(labels.Set{
        "app.kubernetes.io/managed-by": "site-operator",
    })
    return cache.Options{ByObject: map[client.Object]cache.ByObject{
        &appsv1.Deployment{}: {Label: mine},
        &corev1.Service{}:    {Label: mine},
    }}
}
EOF

In cmd/main.go bei ctrl.NewManager(...) eine Zeile:

        Scheme:                 scheme,
        Cache:                  controller.CacheOptions(),

In internal/controller/suite_test.go dasselbe für den Test-Manager, dazu eine Variable cached client.Client im var-Block, die den Client des Managers festhält:

    mgr, err := ctrl.NewManager(cfg, ctrl.Options{
        Scheme:  scheme.Scheme,
        Cache:   CacheOptions(),
        Metrics: metricsserver.Options{BindAddress: "0"}, // kein Port im Test
    })
    Expect(err).NotTo(HaveOccurred())
    cached = mgr.GetClient()

Der Test zeigt die Kehrseite: Ein fremdes Deployment ist für den Operator unsichtbar.

cat > internal/controller/cache_test.go <<'EOF'
package controller

import (
    "time"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    apierrors "k8s.io/apimachinery/pkg/api/errors"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "sigs.k8s.io/controller-runtime/pkg/client"
)

var _ = Describe("Cache mit Label-Selektor", func() {
    It("sieht fremde Deployments nicht", func(ctx SpecContext) {
        ns := newNamespace(ctx)
        labels := map[string]string{"app": "fremd"}
        dep := &appsv1.Deployment{
            ObjectMeta: metav1.ObjectMeta{Name: "fremd", Namespace: ns},
            Spec: appsv1.DeploymentSpec{
                Selector: &metav1.LabelSelector{MatchLabels: labels},
                Template: corev1.PodTemplateSpec{
                    ObjectMeta: metav1.ObjectMeta{Labels: labels},
                    Spec: corev1.PodSpec{Containers: []corev1.Container{
                        {Name: "c", Image: "nginxinc/nginx-unprivileged:1.31-alpine"}}},
                },
            },
        }
        Expect(k8sClient.Create(ctx, dep)).To(Succeed())
        key := client.ObjectKeyFromObject(dep)

        Expect(k8sClient.Get(ctx, key, &appsv1.Deployment{})).To(Succeed())
        Consistently(func() bool {
            return apierrors.IsNotFound(cached.Get(ctx, key, &appsv1.Deployment{}))
        }, time.Second).Should(BeTrue())
    })
})
EOF
go test ./internal/controller/ -count=1 -v -ginkgo.no-color \
  -ginkgo.focus='Watch|Cache|Generation' 2>&1 | grep -E '^(Ran|SUCCESS|FAIL!)'

Erwartet:

Ran 3 of 24 Specs in 12.112 seconds
SUCCESS! -- 3 Passed | 0 Failed | 0 Pending | 21 Skipped

Achtung: Unsichtbar heißt auch: CreateOrUpdate findet ein ungelabeltes Deployment gleichen Namens nicht im Cache, versucht Create und scheitert mit AlreadyExists – in einer Schleife. Labels, nach denen du cachst, müssen auf jedem erzeugten Objekt stehen (Tag 4: labelsFor). Diesen Fall übst du an Tag 15.

ConfigMaps bleiben ungefiltert: Die Quellen deiner Nutzer tragen kein Operator-Label. Wer hier sparen muss, verlangt ein Label an Quell-ConfigMaps und filtert danach – eine API-Entscheidung, keine Optimierung im Verborgenen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Live – Quelle ändern, Site folgt

Terminal 1: envtest-up --crds config/crd/bases (aus ~/op-lab/tag10-site-operator). Terminal 3: Operator ohne Webhooks – heute geht es nur um Ereignisse:

source ~/op-lab/env.sh && cd ~/op-lab/tag10-site-operator
ENABLE_WEBHOOKS=false go run ./cmd/main.go -health-probe-bind-address=0 \
  2>&1 | tee run.log

Terminal 2: eine Site, deren Quelle es noch nicht gibt:

cat > lab/ref.yaml <<'EOF'
apiVersion: web.lab.example/v1
kind: StaticSite
metadata:
  name: ref
spec:
  source:
    configMapRef:
      name: html
EOF
H='{.spec.template.metadata.annotations.web\.lab\.example/content-hash}{"\n"}'
kubectl apply -f lab/ref.yaml; sleep 2
kubectl get site ref \
  -o jsonpath='{.status.conditions[?(@.type=="Degraded")].reason}{"\n"}'
kubectl create configmap html --from-literal=index.html='<h1>v1</h1>'; sleep 1
kubectl get deploy ref -o jsonpath="$H"
kubectl patch configmap html --type merge -p '{"data":{"index.html":"<h1>v3</h1>"}}'
sleep 1; kubectl get deploy ref -o jsonpath="$H"

Erwartet (Hashes variieren):

staticsite.web.lab.example/ref created
ContentMissing
configmap/html created
c5484ff4f6706fb9
configmap/html patched
d3a048128d387b2b

Eine Sekunde statt bis zu 30: Das Deployment existiert, sobald die ConfigMap da ist, und ein neuer Hash im Pod-Template bedeutet im echten Cluster einen Rollout mit dem neuen Inhalt.

Jetzt das Predicate. Jeder Reconcile schreibt Service abgeglichen ins Log – zählen, Annotation setzen, spec ändern:

n() { grep -c 'Service abgeglichen.*"name": "ref"' run.log; }
echo "Reconciles: $(n)"
kubectl annotate site ref team=web; sleep 2; echo "nach annotate: $(n)"
kubectl patch site ref --type merge -p '{"spec":{"replicas":2}}'
sleep 2; echo "nach replicas: $(n)"

Erwartet (Zahlen variieren):

Reconciles: 7
staticsite.web.lab.example/ref annotated
nach annotate: 7
staticsite.web.lab.example/ref patched
nach replicas: 9

Die Annotation lässt den Zähler stehen. Die spec-Änderung zählt doppelt: einmal für die StaticSite, einmal für das Ereignis am geänderten Deployment (Owns).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Operator (Terminal 3) und envtest-up laufen noch aus Drill 5.

cd ~/op-lab/tag10-site-operator
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
C=internal/controller/staticsite_controller.go
go test ./... -count=1 2>&1 | grep -q FAIL && nok "Tests" || ok "Tests grün"
grep -q 'IndexField' $C && ok "Field-Index registriert" || nok "Index fehlt"
grep -q 'GenerationChangedPredicate' $C && ok "Predicate auf For()" \
  || nok "Predicate fehlt"
A='{.spec.template.metadata.annotations}'
OLD=$(kubectl get deploy ref -o jsonpath="$A")
kubectl patch configmap html --type merge \
  -p '{"data":{"index.html":"<h1>check</h1>"}}' >/dev/null; sleep 2
NEW=$(kubectl get deploy ref -o jsonpath="$A")
[ -n "$NEW" ] && [ "$OLD" != "$NEW" ] && ok "Watch: Hash folgt der ConfigMap" \
  || nok "Watch (läuft der Operator?)"
grep -q 'CacheOptions()' cmd/main.go && ok "Cache-Selektor in main.go" || nok "Cache"

Erwartet:

✔ Tests grün
✔ Field-Index registriert
✔ Predicate auf For()
✔ Watch: Hash folgt der ConfigMap
✔ Cache-Selektor in main.go

Danach Operator und envtest-up mit Ctrl+C beenden.

Challenge

Nutzer wollen einen Reconcile per Annotation erzwingen können (kubectl annotate site ref web.lab.example/reconcile-now=$(date +%s)), Labels sollen weiter ignoriert werden. Passe das Predicate an und den Test aus Drill 1 so, dass er beides prüft.

Hinweis: predicate.Or(...) kombiniert Predicates; controller-runtime bringt predicate.AnnotationChangedPredicate mit.

Lösung

In SetupWithManager:

        For(&webv1.StaticSite{},
            builder.WithPredicates(predicate.Or(
                predicate.GenerationChangedPredicate{},
                predicate.AnnotationChangedPredicate{}))).

In predicate_test.go die Annotation durch ein Label ersetzen und einen Block für die Annotation einfügen (vor dem spec-Patch):

        site.Labels = map[string]string{"team": "web"}
        Expect(k8sClient.Patch(ctx, site, patch)).To(Succeed())
        Consistently(reconciles, 2*time.Second).Should(Equal(before))

        patch = client.MergeFrom(site.DeepCopy())
        site.Annotations = map[string]string{"web.lab.example/reconcile-now": "1"}
        Expect(k8sClient.Patch(ctx, site, patch)).To(Succeed())
        Eventually(reconciles).Should(BeNumerically(">", before))
        before = reconciles()
go test ./internal/controller/ -count=1 -v -ginkgo.no-color \
  -ginkgo.focus=Generation 2>&1 | grep -E '^(Ran|SUCCESS|FAIL!)'

Erwartet:

Ran 1 of 24 Specs in 10.047 seconds
SUCCESS! -- 1 Passed | 0 Failed | 0 Pending | 23 Skipped

Jede Annotation-Änderung weckt den Controller jetzt – auch die von kubectl apply (last-applied-configuration). Wer das nicht will, schreibt ein eigenes predicate.Funcs mit UpdateFunc, das nur den einen Schlüssel vergleicht.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Field-Indizes kosten Speicher pro Objekt, sparen aber teure Listen-Scans im MapFunc. Bei vielen Referenzen (Secrets, ConfigMaps) sind sie Pflicht.
  • Watches auf alle ConfigMaps/Secrets eines Clusters sind teuer und sicherheitsrelevant (RBAC list auf Secrets!). Lieber Label-Konvention für Quellen plus Cache-Selektor oder cache.Options.DefaultNamespaces für Namespace-Scope.
  • cache.Options.DefaultTransform mit cache.TransformStripManagedFields() spart bei großen Clustern spürbar Speicher.
  • Predicates sind Optimierung, keine Logik: Reconcile muss trotzdem idempotent und vollständig sein – Resync, Neustart und Leader-Wechsel liefern alle Objekte erneut.
  • Ereignisse ohne Generationsänderung (Labels, Annotationen, Status fremder Objekte) bewusst entscheiden und dokumentieren – „mein Operator ignoriert Labels” ist eine API-Eigenschaft.