Zum Inhalt springen
Trainingslager IT-Trainingslager

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 in bin/, envtest-Assets in envtest/, ein Ordner pro Tag.
  • envtest ist ein echter kube-apiserver plus etcd als lokale Prozesse – ohne Nodes, Scheduler und Controller-Manager.
  • envtest-up (heute selbst gebaut) startet diese Control Plane und schreibt eine Kubeconfig.
  • env.sh setzt KUBECONFIG fest 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 --version

Erwartet (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 -2

Erwartet:

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 -c fehl, 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/envtest

Erwartet (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-up

Erwartet (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 gitVersion

Erwartet:

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,pods

Erwartet:

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 ns

Erwartet (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.sh hat dein normales KUBECONFIG. Die Programme aus Tag 1 und 2 brechen deshalb ab, wenn KUBECONFIG leer ist – und Kubebuilder-Projekte prüfst du mit kubectl 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/tools

Erwartet:

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/envtest

Erwartet:

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-envtest jeden 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 --index zeigt auf einen eigenen Index.
  • Echte Cluster-Kontexte nie in Lab- oder CI-Shells: eigene Kubeconfig pro Umgebung, KUBECONFIG explizit setzen.