Tag 3: Kubebuilder-Projekt und erste CRD
Ziel: Das Gerüst des
site-operatorsteht: Kubebuilder-Projekt, API-TypStaticSite, generierte CRD in envtest,kubectl explainzeigt 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-genmacht 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-operatordas 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 noneErwartet (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' MakefileErwartet:
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 configErwartet:
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.goErwartet (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 --controllerErwartet (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 PROJECTErwartet:
+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
contentodercontentFromgesetzt 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 -4Erwartet:
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 -3Erwartet:
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. Eingit diffdanach 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-upErwartet (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.exampleErwartet (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 deployundgo run ./cmd/main.gonehmen den Cluster ausKUBECONFIGoder~/.kube/config. Prüfe vorher mitkubectl config current-context, dass dortenvteststeht.
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.yamlErwartet (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=0Erwartet (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), nieexampleoder fremde Domains. Umbenennen heißt neue CRD. v1alpha1signalisiert „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 mitmake manifests generate && git diff --exit-code.