Anhang A: Spickzettel
Getestet mit Kubebuilder v4.16.0, controller-runtime v0.25.0,
controller-gen v0.22.0, envtest 1.37.0 und Go 1.26.9. Namen entsprechen
dem Lab (site-operator, StaticSite, Gruppe
web.lab.example, ab Tag 9 Hub-Version
webv1).
Gelände
# Umgebung in jedem Terminal (PATH, GOTOOLCHAIN, KUBEBUILDER_ASSETS, KUBECONFIG)
source ~/op-lab/env.sh
# Control Plane starten, CRDs gleich mit installieren (Ctrl+C beendet)
envtest-up -crds config/crd/bases
# Wohin zeigt kubectl? Muss "envtest" sein
kubectl config current-context
# envtest-Binaries: verfügbare, installierte, Pfad
setup-envtest list
setup-envtest list -i --bin-dir ~/op-lab/envtest
setup-envtest use -i -p path --bin-dir ~/op-lab/envtest 1.37.0Kubebuilder
# Projekt und API
kubebuilder init --domain lab.example --repo example.com/site-operator
kubebuilder create api --group web --version v1alpha1 --kind StaticSite
# Nur den Typ, keinen Controller (z. B. zweite Version)
kubebuilder create api --group web --version v1 --kind StaticSite \
--resource --controller=false
# Clusterweite Ressource
kubebuilder create api --group web --version v1alpha1 --kind SitePolicy \
--namespaced=false
# Defaulting- und Validating-Webhook
kubebuilder create webhook --group web --version v1alpha1 --kind StaticSite \
--defaulting --programmatic-validation
# Conversion-Webhook: Hub = --version, Spokes = --spoke
kubebuilder create webhook --group web --version v1 --kind StaticSite \
--conversion --spoke v1alpha1
# Helm-Chart aus dem Projekt erzeugen
kubebuilder edit --plugins=helm/v2-alpha
# Projekt aus PROJECT neu erzeugen bzw. auf neue Kubebuilder-Version heben
kubebuilder alpha generate
kubebuilder alpha updateMake-Targets
make manifests # CRDs, RBAC, Webhook-Configs aus Markern (controller-gen)
make generate # zz_generated.deepcopy.go
make fmt vet # gofmt und go vet
make test # Unit- und envtest-Tests (lädt envtest nach bin/)
make lint # golangci-lint
make build # bin/manager
make run # Operator lokal gegen KUBECONFIG
make install # CRDs in den Cluster aus KUBECONFIG
make uninstall # CRDs entfernen
make docker-build IMG=registry.example/site-operator:0.1.0
make build-installer IMG=registry.example/site-operator:0.1.0 # dist/install.yaml
make deploy IMG=registry.example/site-operator:0.1.0
make undeployAchtung:
make run,make installundmake deploytreffen den Cluster ausKUBECONFIG. Vorherkubectl config current-context.
Operator lokal starten
# Ohne Probe-Port, mit Metriken per HTTP auf :8080
go run ./cmd/main.go -health-probe-bind-address=0 \
-metrics-bind-address=:8080 -metrics-secure=false 2>&1 | tee run.log
# Debug-Logs von controller-runtime (Reconciling, Reconcile successful)
go run ./cmd/main.go -zap-log-level=5
# Webhooks mit eigenem Zertifikat (tls.crt/tls.key im Verzeichnis)
go run ./cmd/main.go -webhook-cert-path=lab/certs
# Webhooks abschalten (Kubebuilder-Gerüst)
ENABLE_WEBHOOKS=false go run ./cmd/main.go
# Als ServiceAccount (Token-Kubeconfig, Tag 11)
go run ./cmd/main.go -kubeconfig ~/op-lab/sa.kubeconfig
# RBAC aus den Markern ins Lab (Tag 11)
kubectl apply -k config/lab-rbac
# Leader Election außerhalb des Clusters (Flag aus Tag 11)
go run ./cmd/main.go --leader-elect --leader-election-namespace=site-operator-system
# Geschützte Metriken (HTTPS, Token mit Rolle metrics-reader, Tag 11)
curl -sk -H "Authorization: Bearer $T" https://localhost:8443/metricsMarker: Typ und CRD
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:shortName=site,categories=lab
// +kubebuilder:resource:scope=Cluster
// +kubebuilder:storageversion
// +kubebuilder:deprecatedversion:warning="web.lab.example/v1alpha1 ist veraltet"
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
// +kubebuilder:printcolumn:name="Image",type=string,JSONPath=`.spec.image`,priority=1
// +kubebuilder:selectablefield:JSONPath=`.spec.image`priority=1 zeigt die Spalte nur bei
-o wide. Marker-Zeilen lassen sich nicht umbrechen. Für
kubectl scale gibt es zusätzlich
+kubebuilder:subresource:scale mit specpath
und statuspath.
Marker: Validierung und Defaults
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=10
// +kubebuilder:validation:MinLength=1
// +kubebuilder:validation:MaxLength=65536
// +kubebuilder:validation:Pattern=`^/([a-z0-9-]+/)*$`
// +kubebuilder:validation:Enum=Retain;Delete
// +kubebuilder:validation:Format=date-time
// +kubebuilder:validation:MaxItems=20
// +kubebuilder:default=1
// +kubebuilder:default="nginxinc/nginx-unprivileged:1.31-alpine"
// +optional
// +required
// +nullable
// +listType=map
// +listMapKey=type
// Am Typ: genau eins / höchstens eins / mindestens eins der Felder
// +kubebuilder:validation:ExactlyOneOf=content;source
// +kubebuilder:validation:AtMostOneOf=content;source
// +kubebuilder:validation:AtLeastOneOf=content;sourceMarker: CEL
// Feld: Wert prüfen
// +kubebuilder:validation:XValidation:rule="!self.endsWith(':latest')"
// Mit eigener Meldung
// +kubebuilder:validation:XValidation:rule="self <= 5",message="höchstens 5"
// Transition Rule: unveränderlich (nur bei Update geprüft)
// +kubebuilder:validation:XValidation:rule="self == oldSelf"
// Nur wachsen
// +kubebuilder:validation:XValidation:rule="self >= oldSelf"
// Typ: optionales Feld nur mit has() ansprechen
// +kubebuilder:validation:XValidation:rule="!has(self.path)||self.path.startsWith('/')"Dynamische Meldungen:
messageExpression="'zu viele: ' + string(self.size())"
statt message. Kosten: CEL-Regeln auf Listen brauchen
MaxItems, sonst lehnt der API-Server die CRD oft ab
(geschätzte Kosten über dem Budget).
Marker: RBAC und Webhooks
// Ein Marker pro Zeile, Verben aufteilen – controller-gen fasst zusammen
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites,verbs=get;list;watch
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites,verbs=update;patch
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites/status,verbs=get;patch
// +kubebuilder:rbac:groups="",resources=configmaps;services,verbs=get;list;watch
// +kubebuilder:rbac:groups="",resources=configmaps;services,verbs=create;update;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=create;update;patch
// +kubebuilder:rbac:groups=events.k8s.io,resources=events,verbs=create;patch
// Clusterweite Rolle nur für einen Namespace? Dann Role statt ClusterRole:
// +kubebuilder:rbac:groups=apps,namespace=web,resources=deployments,verbs=getDen Webhook-Marker schreibt kubebuilder create webhook
(eine lange Zeile). Seine Felder:
| Feld | Lab-Wert | Bedeutung |
|---|---|---|
path |
/validate-web-lab-example-v1alpha1-staticsite |
URL im Webhook-Server |
mutating |
false |
Validating (true: Defaulting) |
failurePolicy |
fail |
Webhook weg = Request abgelehnt |
sideEffects |
None |
Pflicht für --dry-run=server |
verbs |
create;update |
Wann aufgerufen |
name |
vstaticsite-v1alpha1.kb.io |
Eindeutiger Name in der Config |
Dazu kommt resources=staticsites/finalizers,verbs=update
– nötig, sobald Kinder per blockOwnerDeletion auf die
StaticSite zeigen. Rolle nach jeder Änderung prüfen:
make manifests && git diff config/rbac/role.yaml.
controller-runtime: Builder und Watches
func (r *StaticSiteReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&webv1.StaticSite{}, // Haupt-Objekt
builder.WithPredicates(predicate.Or(
predicate.GenerationChangedPredicate{}, // nur Spec-Änderungen
predicate.AnnotationChangedPredicate{}))).
Owns(&appsv1.Deployment{}). // Kinder mit Controller-Owner
Watches(&corev1.ConfigMap{}, // fremde Objekte
handler.EnqueueRequestsFromMapFunc(r.sitesForConfigMap)).
WithOptions(controller.Options{MaxConcurrentReconciles: 2}).
Named("staticsite").
Complete(r)
}Weitere Prädikate: predicate.LabelChangedPredicate{},
predicate.ResourceVersionChangedPredicate{},
predicate.NewPredicateFuncs(func(o client.Object) bool {…}),
predicate.And(…). Für alle Quellen gleichzeitig:
.WithEventFilter(p).
controller-runtime: Field-Index und MapFunc
const configMapRefIndex = ".spec.source.configMapRef.name"
// in SetupWithManager, vor dem Builder
err := mgr.GetFieldIndexer().IndexField(ctx, &webv1.StaticSite{},
configMapRefIndex, func(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}
})
func (r *StaticSiteReconciler) sitesForConfigMap(ctx context.Context,
cm client.Object) []reconcile.Request {
var sites webv1.StaticSiteList
if err := r.List(ctx, &sites, client.InNamespace(cm.GetNamespace()),
client.MatchingFields{configMapRefIndex: cm.GetName()}); err != nil {
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
}controller-runtime: Client
// Lesen (aus dem Cache), gelöscht = kein Fehler
if err := r.Get(ctx, req.NamespacedName, &site); err != nil {
return ctrl.Result{}, client.IgnoreNotFound(err)
}
// Auflisten mit Filtern
err := r.List(ctx, &deps, client.InNamespace(ns),
client.MatchingLabels{"app.kubernetes.io/managed-by": "site-operator"})
// Anlegen oder angleichen, mit Owner
op, err := controllerutil.CreateOrUpdate(ctx, r.Client, dep, func() error {
mutateDeployment(dep, site, hash)
return controllerutil.SetControllerReference(site, dep, r.Scheme)
})
// Merge-Patch: nur der Diff, kein Locking
orig := site.DeepCopy()
site.Labels["team"] = "web"
err = r.Patch(ctx, site, client.MergeFrom(orig))
// Patch mit optimistischem Locking (Conflict bei fremder Änderung)
err = r.Patch(ctx, site, client.MergeFromWithOptions(orig,
client.MergeFromWithOptimisticLock{}))
// Server-Side Apply (Apply-Configuration aus k8s.io/client-go/applyconfigurations)
err = r.Apply(ctx, svcApplyConfig, client.FieldOwner("site-operator"),
client.ForceOwnership)
// Löschen mit Vordergrund-Kaskade
err = r.Delete(ctx, dep,
client.PropagationPolicy(metav1.DeletePropagationForeground))
// Am Cache vorbei lesen
err = mgr.GetAPIReader().Get(ctx, key, &cm)controller-runtime: Status, Conditions, Events
orig := site.DeepCopy()
site.Status.ObservedGeneration = site.Generation
meta.SetStatusCondition(&site.Status.Conditions, metav1.Condition{
Type: "Available", Status: metav1.ConditionTrue,
Reason: "AllReplicasReady", Message: "1/1 Pods bereit",
ObservedGeneration: site.Generation,
})
if !equality.Semantic.DeepEqual(orig.Status, site.Status) { // Hotloop-Bremse
err = r.Status().Patch(ctx, site, client.MergeFrom(orig))
}
ready := meta.IsStatusConditionTrue(site.Status.Conditions, "Available")
c := meta.FindStatusCondition(site.Status.Conditions, "Degraded")
// Events (events.k8s.io): Objekt, related, Typ, Reason, Action, Note
r.Recorder.Eventf(site, nil, corev1.EventTypeWarning, "ContentMissing",
"Reconcile", "ConfigMap %s fehlt", name)
// in main.go
Recorder: mgr.GetEventRecorder("site-operator"),controller-runtime: Finalizer, Requeue, Fehler
const finalizer = "web.lab.example/finalizer"
if !site.DeletionTimestamp.IsZero() { // wird gelöscht
if controllerutil.ContainsFinalizer(site, finalizer) {
if err := r.cleanupExternal(ctx, site); err != nil {
return ctrl.Result{}, err // Backoff, Finalizer bleibt
}
controllerutil.RemoveFinalizer(site, finalizer)
return ctrl.Result{}, r.Update(ctx, site)
}
return ctrl.Result{}, nil
}
if controllerutil.AddFinalizer(site, finalizer) { // true = war noch nicht da
if err := r.Update(ctx, site); err != nil {
return ctrl.Result{}, err
}
}
return ctrl.Result{RequeueAfter: 30 * time.Second}, nil // später wieder
return ctrl.Result{}, err // Backoff der Workqueue
return ctrl.Result{}, reconcile.TerminalError(err) // kein Retry
// Konflikt gezielt wiederholen (k8s.io/client-go/util/retry)
err := retry.RetryOnConflict(retry.DefaultRetry, func() error {
if err := r.Get(ctx, key, &fresh); err != nil {
return err
}
fresh.Labels["team"] = "web"
return r.Update(ctx, &fresh)
})controller-runtime: Logs und Metriken
log := logf.FromContext(ctx) // enthält controller, name, reconcileID
log.Info("Deployment abgeglichen", "operation", op)
log.V(1).Info("Details", "gen", site.Generation) // ab Level debug (Gerüst-Default)
log.Error(err, "Registrar nicht erreichbar")
var reconcileSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: "staticsite_reconcile_seconds", Help: "Dauer eines Reconciles",
}, []string{"result"})
func init() { metrics.Registry.MustRegister(reconcileSeconds) }Eingebaute Metriken:
controller_runtime_reconcile_total{result},
controller_runtime_reconcile_errors_total,
controller_runtime_reconcile_time_seconds,
workqueue_depth, workqueue_retries_total.
Cache und Client tunen
mgr, err := ctrl.NewManager(cfg, ctrl.Options{
Cache: cache.Options{
DefaultNamespaces: map[string]cache.Config{"web": {}}, // nur Namespace web
ByObject: map[client.Object]cache.ByObject{
&appsv1.Deployment{}: {Label: mine}, // nur eigene (Tag 10)
},
},
Client: client.Options{Cache: &client.CacheOptions{
DisableFor: []client.Object{&corev1.Secret{}}, // Secrets nie cachen
}},
LeaderElection: true,
LeaderElectionID: "b986d597.lab.example",
})envtest und Ginkgo
testEnv = &envtest.Environment{
CRDDirectoryPaths: []string{
filepath.Join("..", "..", "config", "crd", "bases"),
},
ErrorIfCRDPathMissing: true,
WebhookInstallOptions: envtest.WebhookInstallOptions{ // nur für Webhook-Tests
Paths: []string{filepath.Join("..", "..", "config", "webhook")},
},
}
cfg, err := testEnv.Start()
k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme}) // ohne Cache
// Warten, bis der Operator geliefert hat (Gomega)
Eventually(func(g Gomega) {
g.Expect(k8sClient.Get(ctx, key, dep)).To(Succeed())
g.Expect(dep.Spec.Replicas).To(HaveValue(Equal(int32(1))))
}).WithContext(ctx).Should(Succeed())
// Stabil bleiben (kein Hotloop)
Consistently(resourceVersions).WithContext(ctx).
WithTimeout(2 * time.Second).Should(Equal(before))
// Aufräumen nach dem Test
DeferCleanup(func(ctx SpecContext) {
Expect(k8sClient.Delete(ctx, site)).To(Succeed())
})
// Fehlerart prüfen
Expect(apierrors.IsInvalid(err)).To(BeTrue(), "err = %v", err)
Expect(metav1.IsControlledBy(dep, site)).To(BeTrue())make test # alles, envtest nach bin/
go test ./internal/controller/ -ginkgo.v # ausführlich
go test ./internal/controller/ -ginkgo.focus=Hotloop # nur passende Specs
go test ./api/... -run TestRoundTrip -v # normale Go-Tests
go test ./... -coverprofile=cover.out && go tool cover -func=cover.out | tail -1Tipp: envtest hat keinen Deployment-Controller, keinen Garbage Collector und keinen Namespace-Controller. Status von Deployments setzt du im Test selbst (
Status().Patch), Kinder gelöschter Besitzer bleiben liegen.
kubectl: Debugging
# Felder und Schema der CRD
kubectl explain staticsite.spec --recursive
kubectl api-resources --api-group=web.lab.example
# Bestimmte API-Version lesen (Conversion prüfen)
kubectl get staticsites.v1alpha1.web.lab.example demo -o yaml
kubectl get --raw /apis/web.lab.example/v1/namespaces/default/staticsites/demo
# Wer hat was geschrieben?
kubectl get site demo --show-managed-fields -o jsonpath=\
'{range .metadata.managedFields[*]}{.manager} {.operation} {.subresource}{"\n"}{end}'
# Conditions kompakt
kubectl get site demo -o jsonpath=\
'{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'
# Warten wie ein Skript
kubectl wait site/demo --for=condition=Available --timeout=60s
kubectl wait site/demo --for=condition=Degraded=false --timeout=60s
# Events eines Objekts
kubectl events --for staticsite/demo
kubectl get events --field-selector involvedObject.name=demo
# Löschen hängt?
kubectl get site -o custom-columns=\
'NAME:.metadata.name,DEL:.metadata.deletionTimestamp,FIN:.metadata.finalizers[*]'
# Besitzer der Kinder
OWN='OWNER:.metadata.ownerReferences[0].name'
kubectl get deploy,cm,svc -l app.kubernetes.io/managed-by=site-operator \
-o custom-columns="KIND:.kind,NAME:.metadata.name,$OWN"
# RBAC des Operators
SA=system:serviceaccount:site-operator-system:site-operator-controller-manager
kubectl auth can-i create deployments --as=$SA -n default
kubectl auth can-i --list --as=$SA -n default
# Status von Hand setzen (Tests, Simulation)
kubectl patch site demo --subresource=status --type merge \
-p '{"status":{"readyReplicas":1}}'
# Webhooks und Conversion
kubectl get validatingwebhookconfiguration,mutatingwebhookconfiguration
kubectl get crd staticsites.web.lab.example \
-o jsonpath='{.spec.conversion.strategy} {.status.storedVersions}{"\n"}'
# Metriken des lokal laufenden Operators
curl -s localhost:8080/metrics | grep 'controller="staticsite"'
# API-Aufrufe von kubectl sehen
kubectl get site demo -v=6Typische Fehler
| Meldung / Symptom | Ursache | Lösung |
|---|---|---|
no matches for kind "StaticSite" |
CRD nicht installiert | make install bzw.
envtest-up -crds config/crd/bases |
the object has been modified |
Update mit veralteter resourceVersion |
Patch mit MergeFrom, Fehler zurückgeben
(Tag 15) |
... is forbidden: User "system:serviceaccount:..." |
RBAC-Marker fehlt | Marker, make manifests, Rolle anwenden |
timed out waiting for cache to be synced |
list/watch fehlt oder Scheme
unbekannt |
RBAC, AddToScheme in main.go |
no kind is registered for the type |
Typ nicht im Scheme | utilruntime.Must(xyz.AddToScheme(scheme)) |
| Reconcile-Rate explodiert | Status nicht deterministisch, kein Prädikat | Status ohne Zeitstempel,
GenerationChangedPredicate |
Jeder Lauf updated ohne Spec-Änderung |
Server-Defaults nicht gesetzt | Default im Code setzen oder SSA (Tag 4) |
Objekt hängt mit deletionTimestamp |
Finalizer ohne zuständigen Controller | Ursache klären, gezielt per JSON-Patch entfernen |
failed calling webhook ... connection refused |
Webhook-Server läuft nicht | Operator starten, PDB, mehr Replikas |
x509: certificate signed by unknown authority |
caBundle passt nicht |
CA neu injizieren (cert-manager) |
conversion webhook ... failed |
Conversion-Webhook nicht erreichbar | Webhook reparieren; alte Version sonst unlesbar |
| Feld nach Update weg | Conversion verliert Daten | Round-Trip-Test, Annotation für Hub-Felder |
NotFound, obwohl kubectl get es zeigt |
Cache-Selektor/Namespace-Filter | DisableFor oder GetAPIReader() |
already exists, obwohl Reconcile nichts fand |
Objekt fiel aus dem Label-gefilterten Cache | Labels zurück, Objekte umlabeln (Tag 15) |
| Drift wird nicht zurückgedreht | Owner Reference fehlt | SetControllerReference |
panic: flag redefined: kubeconfig |
eigenes -kubeconfig-Flag |
anderen Namen wählen (Tag 0) |
Invalid value: ... failed rule |
CEL-Regel schlägt an | Objekt korrigieren, Regel mit message lesbar
machen |