Zum Inhalt springen
Trainingslager IT-Trainingslager

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.0

Kubebuilder

# 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 update

Make-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 undeploy

Achtung: make run, make install und make deploy treffen den Cluster aus KUBECONFIG. Vorher kubectl 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/metrics

Marker: 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;source

Marker: 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=get

Den 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 -1

Tipp: 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=6

Typische 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