Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Kubebuilder-Projekt und erste CRD

Ziel: Das Gerüst des site-operator steht: Kubebuilder-Projekt, API-Typ StaticSite, generierte CRD in envtest, kubectl explain zeigt deine Felder · Dauer: ca. 120 min · Voraussetzung: Tag 2

Briefing

  • Kubebuilder erzeugt das Projekt (Manager, Makefile, Kustomize) und pro API einen Go-Typ plus Controller-Gerüst.
  • Die Wahrheit liegt im Go-Typ: Marker-Kommentare // +kubebuilder:... steuern Schema, Defaults und Subressourcen.
  • controller-gen macht daraus CRD-YAML, RBAC und DeepCopy-Code: make manifests generate.
  • Der API-Server prüft und defaultet – ganz ohne laufenden Operator.
  • Ab heute ist site-operator das Projekt, das bis Tag 13 wächst.
 api/v1alpha1/staticsite_types.go      (Go-Typ + Marker)
            |
            |  make manifests            make generate
            v                                 v
 config/crd/bases/*.yaml (CRD)      zz_generated.deepcopy.go
 config/rbac/role.yaml   (RBAC)               |
            |                                 v
            v                         go build ./... (Manager)
 kube-apiserver: Schema, Defaults, Validierung, kubectl explain

Drill 1: Projekt anlegen

source ~/op-lab/env.sh
mkdir -p ~/op-lab/tag03-site-operator && cd ~/op-lab/tag03-site-operator
kubebuilder init --domain lab.example --repo example.com/site-operator \
  --project-name site-operator --license none

Erwartet (gekürzt, ohne go: downloading-Zeilen):

INFO Writing kustomize manifests for you to edit...
INFO Writing scaffold for you to edit...
INFO Get controller runtime
INFO Update dependencies
Next: define a resource with:
$ kubebuilder create api

--project-name hält den Namen stabil, auch wenn du den Ordner später für Tag 4 kopierst; --license none spart den Apache-Kopf in jeder Datei. Welche Versionen hat Kubebuilder gewählt?

grep -E 'controller-runtime|k8s.io/(api|client-go) |^go ' go.mod
grep -E '^(CONTROLLER_TOOLS|KUSTOMIZE|GOLANGCI_LINT)_VERSION' Makefile

Erwartet:

go 1.26.0
    k8s.io/client-go v0.37.0
    sigs.k8s.io/controller-runtime v0.25.0
    k8s.io/api v0.37.0 // indirect
KUSTOMIZE_VERSION ?= v5.8.1
CONTROLLER_TOOLS_VERSION ?= v0.22.0
GOLANGCI_LINT_VERSION ?= v2.13.1

Fortschritt speichern? Kostenlos registrieren

Drill 2: Rundgang durchs Gerüst

ls; ls config

Erwartet:

AGENTS.md   config      go.mod      Makefile    README.md
cmd         Dockerfile  go.sum      PROJECT     test
default     manager     network-policy  prometheus  rbac
Pfad Inhalt Wer schreibt? Ab Tag
cmd/main.go Manager: Flags, Scheme, Controller registrieren du (selten) 3
api/<version>/ Go-Typen deiner CRDs du 3
internal/controller/ Reconciler und envtest-Suite du 4
config/ Kustomize: CRD, RBAC, Manager-Deployment make manifests 12
PROJECT Gedächtnis von Kubebuilder Kubebuilder 3

Der Manager in cmd/main.go ist derselbe wie an Tag 2 – nur mit mehr Flags (Metriken, Probes, Leader Election, Webhooks):

grep -nE 'NewManager|LeaderElectionID|HealthProbeBindAddress' cmd/main.go

Erwartet (die ID ist bei dir eine andere Zufallszahl):

141:    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
145:        HealthProbeBindAddress: probeAddr,
147:        LeaderElectionID:       "b986d597.lab.example",

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die API anlegen

kubebuilder create api --group web --version v1alpha1 --kind StaticSite \
  --resource --controller

Erwartet (gekürzt):

WARN unable to find boilerplate file. ...
INFO api/v1alpha1/staticsite_types.go
INFO api/v1alpha1/groupversion_info.go
INFO internal/controller/suite_test.go
INFO internal/controller/staticsite_controller.go
INFO internal/controller/staticsite_controller_test.go
INFO Update dependencies
INFO Running make
Downloading sigs.k8s.io/controller-tools/cmd/[email protected]
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests

Die WARN-Zeile ist die Folge von --license none und harmlos. --resource --controller beantwortet die beiden Rückfragen vorab. Gruppe und Domain ergeben die API-Gruppe:

grep -oE '\+groupName=.*|Group: "[^"]*"' api/v1alpha1/groupversion_info.go
tail -6 PROJECT

Erwartet:

+groupName=web.lab.example
Group: "web.lab.example"
  domain: lab.example
  group: web
  kind: StaticSite
  path: example.com/site-operator/api/v1alpha1
  version: v1alpha1
version: "3"

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der Typ StaticSite

Ersetze das Beispielfeld foo durch den Vertrag des site-operator. Jede Zeile mit + ist ein Marker für controller-gen; normale Kommentare werden zur Feldbeschreibung in kubectl explain.

cat > api/v1alpha1/staticsite_types.go <<'EOF'
package v1alpha1

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/runtime"
)

// ConfigMapReference zeigt auf eine ConfigMap im selben Namespace.
type ConfigMapReference struct {
    // name der ConfigMap.
    // +kubebuilder:validation:MinLength=1
    // +required
    Name string `json:"name"`
}

// ContentSource beschreibt, woher der HTML-Inhalt kommt.
type ContentSource struct {
    // configMapRef liest den Inhalt aus dem Key index.html einer ConfigMap.
    // +optional
    ConfigMapRef *ConfigMapReference `json:"configMapRef,omitempty"`
}

// StaticSiteSpec ist der Wunschzustand einer StaticSite.
type StaticSiteSpec struct {
    // content ist der HTML-Inhalt der Seite (alternativ zu contentFrom).
    // +kubebuilder:validation:MaxLength=65536
    // +optional
    Content string `json:"content,omitempty"`

    // contentFrom verweist auf eine vorhandene ConfigMap (alternativ zu content).
    // +optional
    ContentFrom *ContentSource `json:"contentFrom,omitempty"`

    // replicas ist die Anzahl der nginx-Pods.
    // +kubebuilder:default=1
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=10
    // +optional
    Replicas int32 `json:"replicas,omitempty"`

    // image ist das Webserver-Image.
    // +kubebuilder:default="nginxinc/nginx-unprivileged:1.31-alpine"
    // +optional
    Image string `json:"image,omitempty"`

    // path ist der URL-Pfad, unter dem die Seite ausgeliefert wird.
    // +kubebuilder:default="/"
    // +optional
    Path string `json:"path,omitempty"`
}

// StaticSiteStatus ist der beobachtete Zustand einer StaticSite.
type StaticSiteStatus struct {
    // readyReplicas ist die Zahl der bereiten Pods des Deployments.
    // +optional
    ReadyReplicas int32 `json:"readyReplicas,omitempty"`

    // url ist die clusterinterne Adresse, z. B. http://demo.default.svc.
    // +optional
    URL string `json:"url,omitempty"`

    // observedGeneration ist die zuletzt verarbeitete metadata.generation.
    // +optional
    ObservedGeneration int64 `json:"observedGeneration,omitempty"`

    // conditions: Available, Progressing, Degraded.
    // +listType=map
    // +listMapKey=type
    // +optional
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:shortName=site

// StaticSite liefert eine statische Webseite mit nginx aus.
type StaticSite struct {
    metav1.TypeMeta `json:",inline"`

    // +optional
    metav1.ObjectMeta `json:"metadata,omitzero"`

    // +required
    Spec StaticSiteSpec `json:"spec"`

    // +optional
    Status StaticSiteStatus `json:"status,omitzero"`
}

// +kubebuilder:object:root=true

// StaticSiteList enthält eine Liste von StaticSites.
type StaticSiteList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitzero"`
    Items           []StaticSite `json:"items"`
}

func init() {
    SchemeBuilder.Register(func(s *runtime.Scheme) error {
        s.AddKnownTypes(SchemeGroupVersion, &StaticSite{}, &StaticSiteList{})
        return nil
    })
}
EOF
go build ./...

Erwartet:

# example.com/site-operator/api/v1alpha1
api/v1alpha1/zz_generated.deepcopy.go:74:8: in.Foo undefined (type *StaticSiteSpec ...

Richtig so: Der generierte DeepCopy-Code kennt noch das alte Feld foo. Generierter Code folgt dem Typ nie von selbst – das erledigt Drill 5.

Marker Wirkung im CRD-Schema Wer prüft?
+kubebuilder:default=1 default: 1, Feld wird beim Speichern gesetzt API-Server
+kubebuilder:validation:Maximum=10 maximum: 10 API-Server
+kubebuilder:validation:MaxLength=65536 max. 64 KiB HTML API-Server
+kubebuilder:subresource:status /status getrennt von spec API-Server
+kubebuilder:resource:shortName=site kubectl get site kubectl
+listType=map + +listMapKey=type Conditions per type mergebar (SSA) API-Server

Achtung: Ob content oder contentFrom gesetzt ist, prüft noch niemand. Diese Regel kommt als CEL-Ausdruck an Tag 8.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Generieren

make manifests generate
ls config/crd/bases
grep -nE 'default:|maximum|minimum: 1|maxLength: 65536|- site' \
  config/crd/bases/web.lab.example_staticsites.yaml
go build ./... && echo "build ok"

Erwartet (gekürzt):

".../bin/controller-gen" rbac:roleName=manager-role crd webhook paths="./..." ...
".../bin/controller-gen" object paths="./..."
web.lab.example_staticsites.yaml
15:    - site
47:                maxLength: 65536
66:                default: nginxinc/nginx-unprivileged:1.31-alpine
70:                default: /
75:                default: 1
78:                maximum: 10
79:                minimum: 1
build ok

make generate schreibt zz_generated.deepcopy.go. Ohne DeepCopyObject() ist dein Typ kein runtime.Object und der Client nimmt ihn nicht an:

grep -n '^func' api/v1alpha1/zz_generated.deepcopy.go | head -4

Erwartet:

13:func (in *ConfigMapReference) DeepCopyInto(out *ConfigMapReference) {
18:func (in *ConfigMapReference) DeepCopy() *ConfigMapReference {
28:func (in *ContentSource) DeepCopyInto(out *ContentSource) {
38:func (in *ContentSource) DeepCopy() *ContentSource {

Auch RBAC kommt aus Markern – aus den +kubebuilder:rbac-Zeilen über Reconcile:

grep -n 'kubebuilder:rbac' internal/controller/staticsite_controller.go | cut -c1-80
grep -A2 'apiGroups' config/rbac/role.yaml | head -3

Erwartet:

20:// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites,verbs=get;l
21:// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites/status,verb
22:// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites/finalizers,
- apiGroups:
  - web.lab.example
  resources:

Tipp: Generierte Dateien nie von Hand ändern. Typ oder Marker anpassen, make manifests generate, fertig. Ein git diff danach zeigt genau, was der Marker bewirkt hat.

Fortschritt speichern? Kostenlos registrieren

Drill 6: CRD in envtest installieren

Öffne ein zweites Terminal und starte die Lab-Control-Plane aus Tag 0 – diesmal ohne CRDs, denn die installiert gleich das Makefile:

source ~/op-lab/env.sh
envtest-up

Erwartet (Port variiert):

envtest läuft: https://127.0.0.1:59710/
export KUBECONFIG=/Users/<du>/op-lab/envtest.kubeconfig
Beenden mit Ctrl+C

Zurück im ersten Terminal. make install baut die CRD mit Kustomize und schickt sie per kubectl apply an den Cluster aus KUBECONFIG – dank env.sh an envtest:

kubectl config current-context
make install
kubectl wait --for condition=established crd/staticsites.web.lab.example
kubectl api-resources --api-group=web.lab.example

Erwartet (gekürzt):

envtest
Downloading sigs.k8s.io/kustomize/kustomize/[email protected]
customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example created
customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example condition met
NAME          SHORTNAMES   APIVERSION                 NAMESPACED   KIND
staticsites   site         web.lab.example/v1alpha1   true         StaticSite

Achtung: make install, make deploy und go run ./cmd/main.go nehmen den Cluster aus KUBECONFIG oder ~/.kube/config. Prüfe vorher mit kubectl config current-context, dass dort envtest steht.

Jetzt kennt der API-Server dein Schema – inklusive deiner Kommentare:

kubectl explain staticsite.spec
kubectl explain site.status --recursive | sed -n '/FIELDS/,$p'

Erwartet (gekürzt):

FIELDS:
  content   <string>
    content ist der HTML-Inhalt der Seite (alternativ zu contentFrom).

  contentFrom   <Object>
    contentFrom verweist auf eine vorhandene ConfigMap (alternativ zu content).
  ...
FIELDS:
  conditions    <[]Object>
    lastTransitionTime  <string> -required-
    ...
  observedGeneration    <integer>
  readyReplicas <integer>
  url   <string>

Tipp: Für spätere Tage geht es kürzer: envtest-up -crds config/crd/bases, im Projektordner gestartet, installiert die CRDs direkt beim Start.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Defaults und Validierung live

Das Beispiel-Manifest von Kubebuilder bekommt echten Inhalt:

cat > config/samples/web_v1alpha1_staticsite.yaml <<'EOF'
apiVersion: web.lab.example/v1alpha1
kind: StaticSite
metadata:
  labels:
    app.kubernetes.io/name: site-operator
    app.kubernetes.io/managed-by: kustomize
  name: staticsite-sample
spec:
  content: |
    <h1>Hallo vom site-operator</h1>
  replicas: 2
EOF
kubectl apply -f config/samples/web_v1alpha1_staticsite.yaml
kubectl get site staticsite-sample -o yaml | sed -n '/^spec:/,$p'

Erwartet:

staticsite.web.lab.example/staticsite-sample created
spec:
  content: |
    <h1>Hallo vom site-operator</h1>
  image: nginxinc/nginx-unprivileged:1.31-alpine
  path: /
  replicas: 2

image und path hat der API-Server ergänzt – kein Operator läuft. Jetzt ein kaputtes Objekt:

cat > /tmp/kaputt.yaml <<'EOF'
apiVersion: web.lab.example/v1alpha1
kind: StaticSite
metadata:
  name: kaputt
spec:
  replicas: 0
  contentFrom:
    configMapRef: {}
EOF
kubectl apply -f /tmp/kaputt.yaml

Erwartet (gekürzt):

The StaticSite "kaputt" is invalid:
* spec.replicas: Invalid value: 0: ... should be greater than or equal to 1
* spec.contentFrom.configMapRef.name: Required value

Warum? Ein Default greift nur, wenn das Feld fehlt. Eine explizite 0 wird validiert und abgelehnt.

Die Status-Subressource trennt spec (gehört dem Benutzer) von status (gehört dem Operator):

kubectl patch site staticsite-sample --type merge \
  -p '{"status":{"url":"http://falsch"}}'
kubectl patch site staticsite-sample --subresource=status --type merge \
  -p '{"status":{"url":"http://staticsite-sample.default.svc"}}'
kubectl patch site staticsite-sample --type merge -p '{"spec":{"replicas":3}}'
kubectl get site staticsite-sample \
  -o jsonpath='{.metadata.generation} {.status.url}{"\n"}'

Erwartet:

staticsite.web.lab.example/staticsite-sample patched (no change)
staticsite.web.lab.example/staticsite-sample patched
staticsite.web.lab.example/staticsite-sample patched
2 http://staticsite-sample.default.svc

Ein status-Feld im normalen Patch wird still verworfen. metadata.generation zählt nur spec-Änderungen – das nutzt du an Tag 5 für observedGeneration.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Gerüst und Tests im Zusammenspiel

Der leere Reconciler läuft schon – als Prozess auf deinem Mac gegen envtest. -health-probe-bind-address=0 schaltet den Probe-Port ab, Metriken sind per Default aus:

go run ./cmd/main.go -health-probe-bind-address=0

Erwartet (gekürzt; nach ein paar Sekunden Ctrl+C):

INFO    setup   Starting manager
INFO    Starting EventSource    {"controller": "staticsite", ...
INFO    Starting Controller {"controller": "staticsite", ...
INFO    Starting workers    {"controller": "staticsite", ... "worker count": 1}
^C
INFO    Shutdown signal received, waiting for all workers to finish
INFO    Wait completed, proceeding to shutdown the manager

Was der API-Server garantiert, hältst du in einem Test fest. Die Kubebuilder-Suite (suite_test.go) startet ihre eigene envtest-Instanz und installiert die CRDs aus config/crd/bases:

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

import (
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    apierrors "k8s.io/apimachinery/pkg/api/errors"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

    webv1alpha1 "example.com/site-operator/api/v1alpha1"
)

var _ = Describe("StaticSite API", func() {
    newSite := func(name string) *webv1alpha1.StaticSite {
        return &webv1alpha1.StaticSite{
            ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: "default"},
            Spec:       webv1alpha1.StaticSiteSpec{Content: "<h1>Test</h1>"},
        }
    }

    It("setzt Defaults im API-Server", func(ctx SpecContext) {
        site := newSite("defaults")
        Expect(k8sClient.Create(ctx, site)).To(Succeed())
        DeferCleanup(func(ctx SpecContext) {
            Expect(k8sClient.Delete(ctx, site)).To(Succeed())
        })
        // Create schreibt die Antwort des Servers zurück in site.
        Expect(site.Spec.Replicas).To(Equal(int32(1)))
        Expect(site.Spec.Image).To(Equal("nginxinc/nginx-unprivileged:1.31-alpine"))
        Expect(site.Spec.Path).To(Equal("/"))
    })

    It("lehnt replicas > 10 ab", func(ctx SpecContext) {
        site := newSite("zu-viele")
        site.Spec.Replicas = 11
        err := k8sClient.Create(ctx, site)
        Expect(apierrors.IsInvalid(err)).To(BeTrue(), "err = %v", err)
    })
})
EOF
go test ./internal/controller/ -v -ginkgo.v -ginkgo.no-color 2>&1 \
  | grep -E '^(StaticSite|Ran [0-9]|SUCCESS)'

Erwartet (gekürzt, Reihenfolge kann abweichen):

StaticSite Controller When reconciling a resource should successfully reconcile ...
StaticSite API setzt Defaults im API-Server
StaticSite API lehnt replicas > 10 ab
Ran 3 of 3 Specs in 5.008 seconds
SUCCESS! -- 3 Passed | 0 Failed | 0 Pending | 0 Skipped

Warum? Create schreibt die Antwort des Servers zurück in site – deshalb siehst du die Defaults ohne erneutes Get. Die ERROR Failed to read directory ../../bin/k8s-Zeile im Log ist harmlos: Die Suite sucht dort Binaries, du lieferst sie über KUBEBUILDER_ASSETS.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

envtest-up läuft im zweiten Terminal, CRD und Beispiel sind installiert:

cd ~/op-lab/tag03-site-operator
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
go build ./... && go vet ./... && ok "Build und vet" || nok "Build/vet"
grep -q 'default: nginxinc/nginx-unprivileged:1.31-alpine' \
  config/crd/bases/web.lab.example_staticsites.yaml && ok "CRD mit Defaults" \
  || nok "CRD fehlt – make manifests"
go test ./internal/... >/dev/null 2>&1 && ok "envtest-Suite grün" || nok "Tests"
[ "$(kubectl config current-context)" = envtest ] && ok "Kontext envtest" \
  || nok "Kontext – env.sh gesourct? envtest-up läuft?"
kubectl explain staticsite.spec.contentFrom >/dev/null 2>&1 \
  && ok "CRD installiert (kubectl explain)" || nok "make install"
[ "$(kubectl get site staticsite-sample -o jsonpath='{.spec.image}')" = \
  nginxinc/nginx-unprivileged:1.31-alpine ] && ok "Default von image gesetzt" \
  || nok "Sample fehlt"

Erwartet:

✔ Build und vet
✔ CRD mit Defaults
✔ envtest-Suite grün
✔ Kontext envtest
✔ CRD installiert (kubectl explain)
✔ Default von image gesetzt

Danach envtest-up im zweiten Terminal mit Ctrl+C beenden.

Challenge

Beweise per Test, dass eine StaticSite mit contentFrom.configMapRef: {} (ohne name) abgelehnt wird – und dass die Fehlermeldung das Feld nennt.

Hinweis: ContentFrom und ConfigMapRef sind Pointer; +required am Feld name macht es im Schema zur Pflicht, der Fehler ist wieder IsInvalid.

Lösung

cat >> internal/controller/staticsite_api_test.go <<'EOF'

var _ = Describe("StaticSite API – contentFrom", func() {
    It("verlangt configMapRef.name", func(ctx SpecContext) {
        site := &webv1alpha1.StaticSite{
            ObjectMeta: metav1.ObjectMeta{Name: "ohne-name", Namespace: "default"},
            Spec: webv1alpha1.StaticSiteSpec{
                ContentFrom: &webv1alpha1.ContentSource{
                    ConfigMapRef: &webv1alpha1.ConfigMapReference{},
                },
            },
        }
        err := k8sClient.Create(ctx, site)
        Expect(apierrors.IsInvalid(err)).To(BeTrue(), "err = %v", err)
        Expect(err.Error()).To(ContainSubstring("spec.contentFrom.configMapRef.name"))
    })
})
EOF
go test ./internal/controller/ -count=1 -v -ginkgo.no-color 2>&1 \
  | grep -E '^(Ran [0-9]|ok)'

Erwartet:

Ran 4 of 4 Specs in 5.110 seconds
ok      example.com/site-operator/internal/controller   5.451s

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • API-Gruppe ist ein Vertrag: eine echte, eigene Domain (web.firma.de), nie example oder fremde Domains. Umbenennen heißt neue CRD.
  • v1alpha1 signalisiert „kann brechen”. Ab der ersten produktiven Nutzung gelten Kompatibilitätsregeln (Tag 9).
  • CRDs sind cluster-weit: Wer sie installiert, braucht Cluster-Admin-Rechte. Oft liefert das Plattform-Team die CRD getrennt vom Operator aus.
  • Defaults im Schema statt im Code: Sie sind für kubectl, GitOps-Diffs und andere Clients sichtbar.
  • Generierte Dateien (config/crd, zz_generated.*) gehören ins Git; die CI prüft mit make manifests generate && git diff --exit-code.