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()undOwns()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-operatorZwei 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))
})
})
EOFDen 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
}
EOFWarum 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. GenerationChangedPredicategilt nur fürFor().metadata.generationsteigt bei jederspec-Ä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().Patchden 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},
}}
}
EOFIn 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:
CreateOrUpdatefindet ein ungelabeltes Deployment gleichen Namens nicht im Cache, versuchtCreateund scheitert mitAlreadyExists– 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.logTerminal 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
listauf Secrets!). Lieber Label-Konvention für Quellen plus Cache-Selektor odercache.Options.DefaultNamespacesfür Namespace-Scope. cache.Options.DefaultTransformmitcache.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.