Tag 0: Das Trainingsgelände
Ziel: Go 1.26, Kubebuilder, setup-envtest und eine Lab-Control-Plane auf Knopfdruck – ohne einen echten Cluster anzufassen · Dauer: ca. 60 min · Voraussetzung: Go, kubectl, git, Internet
Briefing
- Alles liegt unter
~/op-lab: Binaries inbin/, envtest-Assets inenvtest/, ein Ordner pro Tag. - envtest ist ein echter
kube-apiserverplusetcdals lokale Prozesse – ohne Nodes, Scheduler und Controller-Manager. envtest-up(heute selbst gebaut) startet diese Control Plane und schreibt eine Kubeconfig.env.shsetztKUBECONFIGfest auf die Lab-Datei. Dein echter Cluster bleibt unberührt.- kind brauchst du nicht; es taucht erst an Tag 12 als Option auf.
~/op-lab/
├── env.sh source ~/op-lab/env.sh (PATH, Go, envtest, KUBECONFIG)
├── bin/ kubebuilder, setup-envtest, envtest-up
├── envtest/k8s/1.37.0-.../ etcd, kube-apiserver, kubectl
├── envtest.kubeconfig existiert nur, solange envtest-up läuft
├── tools/envtest-up/ Quellcode des Lab-Werkzeugs
├── tag01-labelsync/ client-go von Hand
├── tag02-restarter/ controller-runtime ohne Kubebuilder
└── tag03-site-operator/ ab hier: Kubebuilder-Projekt, wächst bis Tag 13
Drill 1: Werkzeuge prüfen
go version
GOTOOLCHAIN=go1.26.9 go version
kubectl version --client
git --versionErwartet (deine Versionen können abweichen; die
downloading-Zeile nur beim ersten Mal):
go version go1.25.5 darwin/arm64
go: downloading go1.26.9 (darwin/arm64)
go version go1.26.9 darwin/arm64
Client Version: v1.37.1
Kustomize Version: v5.8.1
git version 2.56.0
Warum GOTOOLCHAIN? Go lädt die gewünschte Toolchain
selbst nach, ohne dein System-Go anzufassen. Hast du schon Go 1.26,
entfällt der Download.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Ordner und Kubebuilder
mkdir -p ~/op-lab/{bin,envtest,tools} && cd ~/op-lab/bin
KB=v4.16.0; OS=$(go env GOOS); ARCH=$(go env GOARCH)
URL=https://github.com/kubernetes-sigs/kubebuilder/releases/download/$KB
curl -sSLO "$URL/kubebuilder_${OS}_${ARCH}"
curl -sSL "$URL/checksums.txt" | grep " kubebuilder_${OS}_${ARCH}$" \
| shasum -a 256 -c
mv "kubebuilder_${OS}_${ARCH}" kubebuilder && chmod +x kubebuilder
./kubebuilder version | head -2Erwartet:
kubebuilder_darwin_arm64: OK
KubeBuilder: v4.16.0
Kubernetes: 1.37.0
Sicherheit: Binaries aus dem Netz immer gegen die veröffentlichte Prüfsumme prüfen. Schlägt
shasum -cfehl, nicht weitermachen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: setup-envtest und die Kubernetes-Binaries
setup-envtest lädt passende
etcd/kube-apiserver-Binaries. Die Version
passt zu controller-runtime v0.25.0, das Kubebuilder v4.16.0
erzeugt:
GOTOOLCHAIN=go1.26.9 GOBIN=$HOME/op-lab/bin \
go install sigs.k8s.io/controller-runtime/tools/[email protected]
~/op-lab/bin/setup-envtest list | head -3
~/op-lab/bin/setup-envtest use 1.37.0 --bin-dir ~/op-lab/envtestErwartet (gekürzt):
(available) v1.37.0 darwin/arm64
(available) v1.36.2 darwin/arm64
(available) v1.36.0 darwin/arm64
Version: 1.37.0
OS/Arch: darwin/arm64
sha512: fb38cfacdd71b5e97a4d4cceac861af5f55069cf783f0e49cf181bfc32eb3e557c2...
Path: /Users/<du>/op-lab/envtest/k8s/1.37.0-darwin-arm64
GOBIN lenkt go install nach
~/op-lab/bin statt nach ~/go/bin – nichts
landet global.
Fortschritt speichern? Kostenlos registrieren
Drill 4: env.sh – ein Befehl für die ganze Umgebung
cat > ~/op-lab/env.sh <<'EOF'
# Lab-Umgebung für "Kubernetes-Operatoren zum Anfassen": source ~/op-lab/env.sh
export PATH="$HOME/op-lab/bin:$PATH"
export GOTOOLCHAIN=go1.26.9 # Go 1.26, auch wenn das System-Go älter ist
export KUBEBUILDER_ASSETS="$(setup-envtest use -i -p path \
--bin-dir "$HOME/op-lab/envtest" 1.37.0)"
export KUBECONFIG="$HOME/op-lab/envtest.kubeconfig" # nie dein echter Cluster
EOF
source ~/op-lab/env.sh
which kubebuilder setup-envtest
echo "$KUBEBUILDER_ASSETS"Erwartet:
/Users/<du>/op-lab/bin/kubebuilder
/Users/<du>/op-lab/bin/setup-envtest
/Users/<du>/op-lab/envtest/k8s/1.37.0-darwin-arm64
Ab jetzt beginnt jeder Tag mit source ~/op-lab/env.sh –
in jedem Terminal, das du öffnest.
KUBEBUILDER_ASSETS ist die Variable, über die envtest seine
Binaries findet; -i heißt „nur lokal suchen, nichts
laden”.
Fortschritt speichern? Kostenlos registrieren
Drill 5: envtest-up bauen
Ein kleines Go-Programm startet die Control Plane über
envtest.Environment – genau die Klasse, die später auch
deine Tests nutzen – und legt einen Admin-User mit Kubeconfig an:
mkdir -p ~/op-lab/tools/envtest-up && cd ~/op-lab/tools/envtest-up
go mod init example.com/envtest-up
go get sigs.k8s.io/[email protected]
cat > main.go <<'EOF'
// envtest-up startet eine envtest-Control-Plane (etcd + kube-apiserver),
// schreibt eine Kubeconfig und läuft, bis du Ctrl+C drückst.
// Lab-Werkzeug: keine Controller, kein Scheduler, keine Nodes.
package main
import (
"context"
"flag"
"fmt"
"log"
"os"
"os/signal"
"path/filepath"
"strings"
"syscall"
"time"
"sigs.k8s.io/controller-runtime/pkg/envtest"
)
func main() {
home, _ := os.UserHomeDir()
out := flag.String("out",
filepath.Join(home, "op-lab", "envtest.kubeconfig"), "Ziel der Kubeconfig")
crds := flag.String("crds", "", "CRD-Verzeichnisse, kommagetrennt (optional)")
flag.Parse()
if os.Getenv("KUBEBUILDER_ASSETS") == "" {
log.Fatal("KUBEBUILDER_ASSETS ist leer – erst ~/op-lab/env.sh sourcen")
}
// Signale ab sofort abfangen – auch während Start und Stop, damit ein
// zweites Ctrl+C keine verwaisten etcd/kube-apiserver-Prozesse hinterlässt.
ctx, stop := signal.NotifyContext(context.Background(),
os.Interrupt, syscall.SIGTERM)
defer stop()
env := &envtest.Environment{
ErrorIfCRDPathMissing: true,
// Hängt der kube-apiserver beim Stoppen, beendet envtest ihn per SIGKILL.
ControlPlaneStopTimeout: 10 * time.Second,
}
if *crds != "" {
env.CRDDirectoryPaths = strings.Split(*crds, ",")
}
cfg, err := env.Start()
if err != nil {
log.Fatalf("envtest start: %v", err)
}
// Ab hier muss die Control Plane in jedem Fall wieder gestoppt werden.
if err := writeKubeconfig(env, *out); err != nil {
log.Print(err)
} else {
fmt.Printf("envtest läuft: %s\n", cfg.Host)
fmt.Printf("export KUBECONFIG=%s\n", *out)
fmt.Println("Beenden mit Ctrl+C")
<-ctx.Done()
}
fmt.Println("stoppe envtest ...")
_ = os.Remove(*out)
if err := env.Stop(); err != nil {
log.Printf("envtest stop: %v (Prozess hart beendet)", err)
}
fmt.Println("envtest gestoppt, Kubeconfig gelöscht")
}
// writeKubeconfig legt einen Admin-User an und schreibt dessen Kubeconfig.
func writeKubeconfig(env *envtest.Environment, path string) error {
admin, err := env.AddUser(envtest.User{
Name: "lab-admin",
Groups: []string{"system:masters"},
}, nil)
if err != nil {
return fmt.Errorf("user anlegen: %w", err)
}
data, err := admin.KubeConfig()
if err != nil {
return fmt.Errorf("kubeconfig erzeugen: %w", err)
}
if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
return err
}
return os.WriteFile(path, data, 0o600)
}
EOF
go mod tidy && go vet . && go build -o ~/op-lab/bin/envtest-up . && echo "gebaut"Erwartet (gekürzt):
go: creating new go.mod: module example.com/envtest-up
go: added k8s.io/client-go v0.37.0
go: added sigs.k8s.io/controller-runtime v0.25.0
gebaut
Warum -out statt -kubeconfig?
controller-runtime registriert -kubeconfig schon selbst als
globales Flag; ein zweites gäbe panic: flag redefined.
Manchmal braucht der kube-apiserver beim Beenden länger;
nach 10 s beendet envtest ihn hart und envtest-up meldet
timeout waiting for process kube-apiserver to stop –
harmlos. Das Ziel ist bewusst fest
~/op-lab/envtest.kubeconfig und nicht
$KUBECONFIG – sonst könnte das Tool eine echte Kubeconfig
überschreiben und beim Beenden löschen.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Erster Start
Terminal 2 (bleibt offen, solange du übst):
source ~/op-lab/env.sh
envtest-upErwartet (Port variiert):
envtest läuft: https://127.0.0.1:61450/
export KUBECONFIG=/Users/<du>/op-lab/envtest.kubeconfig
Beenden mit Ctrl+C
Terminal 1:
kubectl get ns
kubectl auth whoami \
-o jsonpath='{.status.userInfo.username} {.status.userInfo.groups}{"\n"}'
kubectl get --raw /version | grep gitVersionErwartet:
NAME STATUS AGE
default Active 2s
kube-node-lease Active 2s
kube-public Active 2s
kube-system Active 2s
lab-admin ["system:masters","system:authenticated"]
"gitVersion": "v1.37.0",
Jetzt die wichtigste Lektion über envtest:
kubectl create deployment web --image=nginxinc/nginx-unprivileged:1.31-alpine \
--replicas=2
sleep 3; kubectl get deploy,rs,podsErwartet:
deployment.apps/web created
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/web 0/2 0 0 3s
Kein ReplicaSet, kein Pod: Es läuft kein Controller-Manager. envtest
speichert und validiert Objekte, aber nur dein Operator
reagiert darauf. Status-Felder wie readyReplicas setzt hier
niemand – das simulierst du in Tests selbst (Tag 5 und 6).
Fortschritt speichern? Kostenlos registrieren
Drill 7: Das Sicherheitsnetz
Vor jedem schreibenden Befehl gilt: Wohin zeigt
kubectl?
kubectl config current-context
kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}{"\n"}'Erwartet:
envtest
https://127.0.0.1:61450
Beende envtest-up in Terminal 2 mit Ctrl+C:
^Cstoppe envtest ...
envtest gestoppt, Kubeconfig gelöscht
Und in Terminal 1:
kubectl get nsErwartet (gekürzt):
E1010 10:37:20.710116 ... "Couldn't get current server API group list" ...
The connection to the server localhost:8080 was refused - did you specify the right
host or port?
Genau so soll es sein: KUBECONFIG zeigt auf eine Datei,
die es nicht mehr gibt – kubectl fällt
nicht auf ~/.kube/config zurück. Ohne
laufendes envtest kann kein Lab-Befehl einen echten Cluster treffen.
Achtung: Ein neues Terminal ohne
source ~/op-lab/env.shhat dein normalesKUBECONFIG. Die Programme aus Tag 1 und 2 brechen deshalb ab, wennKUBECONFIGleer ist – und Kubebuilder-Projekte prüfst du mitkubectl config current-context.
Den fertigen Code jedes Tages gibt es zum Vergleichen im Begleitcode auf GitHub. Hol ihn jetzt; erst tippst du selbst, dann siehst du nach:
git clone https://github.com/thomaszachmann/kubernetes-operatoren-zum-anfassen.git \
~/kubernetes-operatoren-zum-anfassen
ls -1 ~/kubernetes-operatoren-zum-anfassen/toolsErwartet:
Cloning into '…/kubernetes-operatoren-zum-anfassen'...
envtest-up
Die Ordner heißen wie deine in ~/op-lab. Nach Tag 1
zeigt etwa
diff -r ~/op-lab/tag01-labelsync ~/kubernetes-operatoren-zum-anfassen/tag01-labelsync,
wo du abweichst.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Das Skript startet envtest selbst im Hintergrund und stoppt es wieder:
source ~/op-lab/env.sh
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
go version | grep -q ' go1\.26' && ok "Go 1.26" || nok "Go 1.26 fehlt"
kubebuilder version | grep -q 'v4.16.0' && ok "Kubebuilder v4.16.0" || nok "Kubebuilder"
[ -x "$KUBEBUILDER_ASSETS/kube-apiserver" ] && ok "envtest-Assets" \
|| nok "setup-envtest"
envtest-up > /tmp/envtest-up.log 2>&1 & PID=$!
for i in $(seq 1 30); do [ -f "$KUBECONFIG" ] && break; sleep 1; done
kubectl get ns default >/dev/null 2>&1 && ok "envtest antwortet" || nok "envtest-up"
[ "$(kubectl config current-context)" = envtest ] && ok "Kontext envtest" \
|| nok "KUBECONFIG"
kill -INT $PID; wait $PID
[ ! -f "$KUBECONFIG" ] && ok "sauber gestoppt" || nok "Stopp"Erwartet:
✔ Go 1.26
✔ Kubebuilder v4.16.0
✔ envtest-Assets
✔ envtest antwortet
✔ Kontext envtest
✔ sauber gestoppt
Challenge
Dein Operator soll auch auf dem älteren Kubernetes 1.36 der Kundenumgebung laufen. Starte envtest einmalig mit 1.36.2, prüfe die Server-Version und räume die Binaries danach wieder ab.
Hinweis: KUBEBUILDER_ASSETS lässt sich
für einen einzelnen Befehl überschreiben;
setup-envtest cleanup löscht Versionen.
Lösung
source ~/op-lab/env.sh
KUBEBUILDER_ASSETS=$(setup-envtest use -p path --bin-dir ~/op-lab/envtest 1.36.2) \
envtest-up > /tmp/envtest-136.log 2>&1 & PID=$!
for i in $(seq 1 60); do [ -f "$KUBECONFIG" ] && break; sleep 1; done
kubectl version
kill -INT $PID; wait $PID
setup-envtest cleanup --bin-dir ~/op-lab/envtest 1.36.2
setup-envtest list -i --bin-dir ~/op-lab/envtestErwartet:
Client Version: v1.37.1
Kustomize Version: v5.8.1
Server Version: v1.36.2
removed 1.36.2 (darwin/arm64)
(installed) v1.37.0 darwin/arm64
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Tool-Versionen gehören ins Repo: Kubebuilder pinnt sie im
Makefile(CONTROLLER_TOOLS_VERSION,ENVTEST_K8S_VERSION); die CI nutzt dieselben. - In der CI ersetzt
setup-envtestjeden Test-Cluster: kein Docker, kein Cloud-Konto, Start in wenigen Sekunden. - Teste gegen die älteste und die neueste Kubernetes-Version, die deine Kunden betreiben (Matrix in der CI).
- Hinter Proxy oder im Air-Gap: envtest-Binaries und Go-Module über
einen internen Mirror (Artifactory, Athens) beziehen;
setup-envtest --indexzeigt auf einen eigenen Index. - Echte Cluster-Kontexte nie in Lab- oder CI-Shells: eigene Kubeconfig
pro Umgebung,
KUBECONFIGexplizit setzen.