Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: kind-Cluster für KI-Workloads

Ziel: Der Cluster ki-lab läuft mit Ingress, Storage, metrics-server, den fünf Lab-Namespaces und vorgeladenen Images. · Dauer: ca. 60 min · Voraussetzung: Tag 0

Briefing

  • KI-Workloads sind groß: Images mit mehreren hundert MB, Modelle mit GB. Darum Storage für einen Modell-Cache und vorgeladene Images.
  • Der control-plane-Node nimmt Port 80/443 vom Laptop an und betreibt Ingress-NGINX. Modelle laufen auf dem Worker.
  • *.ki.localtest.me zeigt auf 127.0.0.1, also auf den Ingress.
  • metrics-server liefert kubectl top: Damit siehst du, was ein Modell an CPU und RAM wirklich frisst.
 Laptop 127.0.0.1:80/443
        │
 ┌──────▼─────────────────────┐   ┌─────────────────────────────┐
 │ ki-lab-control-plane       │   │ ki-lab-worker               │
 │ label ingress-ready=true   │   │ label ki-lab/role=models    │
 │ ingress-nginx (hostPort)   │──►│ ki-models: llama.cpp (Tag 2)│
 │ metrics-server             │   │ PVC model-cache (local-path)│
 └────────────────────────────┘   └─────────────────────────────┘

Drill 1: Cluster-Konfiguration

mkdir -p ~/ki-lab/code/kind-lab && cd ~/ki-lab/code/kind-lab
cat > kind-config.yaml <<'EOF'
# kind-Cluster "ki-lab": 1 control-plane (Ingress) + 1 worker (Modelle)
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: ki-lab
nodes:
  - role: control-plane
    labels:
      ingress-ready: "true"
    extraPortMappings:
      - containerPort: 80
        hostPort: 80
        listenAddress: "127.0.0.1"
      - containerPort: 443
        hostPort: 443
        listenAddress: "127.0.0.1"
  - role: worker
    labels:
      ki-lab/role: models
EOF
kind create cluster --config kind-config.yaml

Erwartet (gekürzt):

Creating cluster "ki-lab" ...
 ✓ Ensuring node image (kindest/node:v1.37.0)
 ✓ Preparing nodes
 ✓ Writing configuration
 ✓ Starting control-plane
 ✓ Installing CNI
 ✓ Installing StorageClass
 ✓ Joining worker nodes
Set kubectl context to "kind-ki-lab"

Warum listenAddress: 127.0.0.1? Ohne den Eintrag lauscht Docker auf allen Interfaces, dein Modell wäre im WLAN erreichbar.

kubectl get nodes -L ingress-ready,ki-lab/role

Erwartet (Alter weicht ab):

NAME                   STATUS   ROLES           AGE   VERSION   INGRESS-READY   ROLE
ki-lab-control-plane   Ready    control-plane   60s   v1.37.0   true
ki-lab-worker          Ready    <none>          45s   v1.37.0                   models

Achtung: Belegt schon ein anderer Prozess Port 80 oder 443, scheitert kind create mit address already in use. Prüfe mit lsof -nP -iTCP:80 -sTCP:LISTEN und ändere notfalls hostPort auf 8080/8443. Dann hängst du an jede Lab-URL :8080 an.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Namespaces

Dieselben Namespaces nutzt du später auf RKE2 (Tag 9). Labels erleichtern NetworkPolicies und Quotas.

cat > namespaces.yaml <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
  name: ki-models
  labels:
    ki-lab/layer: models
---
apiVersion: v1
kind: Namespace
metadata:
  name: ki-gateway
  labels:
    ki-lab/layer: gateway
---
apiVersion: v1
kind: Namespace
metadata:
  name: ki-chat
  labels:
    ki-lab/layer: apps
---
apiVersion: v1
kind: Namespace
metadata:
  name: ki-code
  labels:
    ki-lab/layer: apps
---
apiVersion: v1
kind: Namespace
metadata:
  name: monitoring
  labels:
    ki-lab/layer: platform
EOF
kubectl apply -f namespaces.yaml
kubectl get ns -L ki-lab/layer | grep -E 'NAME|ki-|monitoring'

Erwartet:

NAME         STATUS   AGE   LAYER
ki-chat      Active   2s    apps
ki-code      Active   2s    apps
ki-gateway   Active   2s    gateway
ki-models    Active   2s    models
monitoring   Active   2s    platform
Namespace Inhalt ab Tag
ki-models Modellserver (llama.cpp, vLLM) 2
ki-gateway LiteLLM, Postgres 4
ki-chat Open WebUI 5
ki-code Code-LLM 14
monitoring Prometheus, Grafana 9

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ingress-NGINX

Das Buch nutzt das letzte Release controller-v1.15.1 mit dem kind-Manifest des Projekts. Der Patch bindet den Controller an den Node mit den Port-Mappings.

GH=https://raw.githubusercontent.com/kubernetes/ingress-nginx
kubectl apply -f $GH/controller-v1.15.1/deploy/static/provider/kind/deploy.yaml
kubectl -n ingress-nginx patch deployment ingress-nginx-controller \
  --type merge -p '{"spec":{"template":{"spec":{"nodeSelector":
  {"ingress-ready":"true","kubernetes.io/os":"linux"}}}}}'
kubectl -n ingress-nginx rollout status deployment ingress-nginx-controller \
  --timeout=180s

Erwartet (gekürzt):

namespace/ingress-nginx created
...
ingressclass.networking.k8s.io/nginx created
deployment.apps/ingress-nginx-controller patched
Waiting for deployment "ingress-nginx-controller" rollout to finish: ...
deployment "ingress-nginx-controller" successfully rolled out

Warum der Patch? Das Manifest erlaubt den control-plane-Node, erzwingt ihn aber nicht. Landet der Pod auf dem Worker, hat er dort keine Port-Mappings und curl läuft ins Leere.

Achtung: Ingress-NGINX ist seit März 2026 eingestellt (keine Releases, keine Sicherheitsfixes). Im Wegwerf-Lab ist das vertretbar, auf RKE2 entscheidest du an Tag 9 bewusst.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ingress testen

Ein winziger Echo-Server prüft die Kette Laptop → Port 80 → Ingress → Service → Pod.

cat > ~/ki-lab/tag01/echo.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
  namespace: ki-chat
spec:
  replicas: 1
  selector:
    matchLabels: {app: echo}
  template:
    metadata:
      labels: {app: echo}
    spec:
      containers:
        - name: echo
          image: hashicorp/http-echo:1.0
          args: ["-text=Hallo aus kind"]
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: echo
  namespace: ki-chat
spec:
  selector: {app: echo}
  ports:
    - port: 80
      targetPort: 5678
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo
  namespace: ki-chat
spec:
  ingressClassName: nginx
  rules:
    - host: echo.ki.localtest.me
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: echo
                port:
                  number: 80
EOF
kubectl apply -f ~/ki-lab/tag01/echo.yaml
kubectl -n ki-chat rollout status deploy/echo
curl -s http://echo.ki.localtest.me/
curl -s -o /dev/null -w '%{http_code}\n' http://nix.ki.localtest.me/

Erwartet:

deployment "echo" successfully rolled out
Hallo aus kind
404

Ein unbekannter Host liefert 404 vom Default-Backend des Controllers. Kommt stattdessen dieser Fehler, ist der Controller noch nicht bereit:

Error from server (InternalError): error when creating "echo.yaml": Internal error
occurred: failed calling webhook "validate.nginx.ingress.kubernetes.io": ...
connect: connection refused

Warte auf das rollout status aus Drill 3 und wende die Datei erneut an.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Storage für Modelle

kind bringt den local-path-provisioner mit. Ein PVC wird zu einem Verzeichnis im Node-Container, erst wenn ein Pod es nutzt.

kubectl get storageclass
cat > ~/ki-lab/tag01/pvc-test.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-test
  namespace: ki-models
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 100Mi
---
apiVersion: v1
kind: Pod
metadata:
  name: pvc-test
  namespace: ki-models
spec:
  containers:
    - name: sh
      image: busybox:1.37
      command: ["sh", "-c", "echo modell-cache > /data/probe.txt && sleep 3600"]
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: pvc-test
EOF
kubectl apply -f ~/ki-lab/tag01/pvc-test.yaml
kubectl -n ki-models wait pod/pvc-test --for=condition=Ready --timeout=90s
kubectl -n ki-models get pvc pvc-test

Erwartet (gekürzt):

NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE
standard (default)   rancher.io/local-path   Delete          WaitForFirstConsumer
persistentvolumeclaim/pvc-test created
pod/pvc-test created
pod/pvc-test condition met
NAME       STATUS   VOLUME                                     CAPACITY   ...
pvc-test   Bound    pvc-05b31c99-686e-49af-a076-95cd6f912594   100Mi      ...

Wo liegen die Daten wirklich?

kubectl get pv -o jsonpath='{range .items[*]}{.spec.hostPath.path}{"\n"}{end}'
NODE=$(kubectl -n ki-models get pod pvc-test -o jsonpath='{.spec.nodeName}')
docker exec $NODE sh -c 'cat /var/local-path-provisioner/*pvc-test/probe.txt'

Erwartet:

/var/local-path-provisioner/pvc-05b31c99-..._ki-models_pvc-test
modell-cache

Warum wichtig? Das Modell aus Tag 2 liegt genau so im Node-Container. kind delete cluster löscht es mit. WaitForFirstConsumer legt das Volume auf dem Node an, auf dem der Pod landet, danach ist der Pod an diesen Node gebunden.

kubectl delete -f ~/ki-lab/tag01/pvc-test.yaml

Fortschritt speichern? Kostenlos registrieren

Drill 6: metrics-server

helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
helm upgrade --install metrics-server metrics-server/metrics-server \
  --version 3.14.0 -n kube-system \
  --set 'args={--kubelet-insecure-tls}' --wait
sleep 60
kubectl top nodes
kubectl top pods -A --sort-by=memory | head -4

Erwartet (Werte weichen ab):

NAME                   CPU(cores)   CPU(%)   MEMORY(bytes)   MEMORY(%)
ki-lab-control-plane   84m          2%       841Mi           10%
ki-lab-worker          21m          0%       230Mi           2%
NAMESPACE       NAME                                         CPU(cores)   MEMORY(bytes)
kube-system     kube-apiserver-ki-lab-control-plane          21m          257Mi
kube-system     kube-controller-manager-ki-lab-control-plane 9m           60Mi
ingress-nginx   ingress-nginx-controller-575c4d8bc6-tzkwz    2m           58Mi

Warum --kubelet-insecure-tls? Die Kubelets in kind haben selbstsignierte Zertifikate ohne passende IP-SANs. Nur im Lab, auf RKE2 (Tag 9) bleibt die Prüfung an. Die erste Messung braucht etwa eine Minute, vorher meldet kubectl top metrics not available yet.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Images vorladen

Das Image des Modellservers für Tag 2 ist rund 280 MB komprimiert. Lädst du es einmal vom Host in die Nodes, startet jeder Pod ohne Pull, auch offline und nach einem Cluster-Neubau aus dem lokalen Docker-Cache.

IMG=ghcr.io/ggml-org/llama.cpp:server-b11515
PLATFORM=$(docker version --format '{{.Server.Os}}/{{.Server.Arch}}')
docker pull --platform $PLATFORM $IMG
docker save --platform $PLATFORM $IMG -o /tmp/llamacpp.tar
kind load image-archive /tmp/llamacpp.tar --name ki-lab
rm /tmp/llamacpp.tar
for n in $(kind get nodes --name ki-lab); do
  echo "$n: $(docker exec $n crictl images | grep -c llama.cpp)"
done

Erwartet:

ki-lab-control-plane: 1
ki-lab-worker: 1

Warum nicht einfach kind load docker-image? Mit dem containerd-Image-Store von Docker 29 kennt der Host nur die Schichten deiner Plattform, das Multi-Arch-Image verweist aber auf alle. Der Import bricht dann ab:

ERROR: failed to load image: command "docker exec --privileged -i ki-lab-control-plane
ctr --namespace=k8s.io images import --all-platforms ..." failed with error: exit
status 1
Command Output: ctr: content digest sha256:2c213d6c...: not found

docker save --platform schreibt nur die passende Plattform ins Archiv. Im Pod sorgt imagePullPolicy: IfNotPresent (Default bei festem Tag) dafür, dass das vorgeladene Image genutzt wird.

Tipp: Mit :latest wäre die Policy Always, und jeder Pod-Start zieht das Image neu. Feste Tags sparen bei KI-Images Minuten.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Alles in einem Skript

Du baust den Cluster in Teil A mehrmals neu. up.sh fasst Drill 1–7 zusammen und ist idempotent.

cat > ~/ki-lab/code/kind-lab/up.sh <<'EOF'
#!/usr/bin/env bash
# Baut den kind-Cluster "ki-lab" komplett auf (idempotent).
set -euo pipefail
cd "$(dirname "$0")"

CLUSTER=ki-lab
CTX=kind-$CLUSTER
INGRESS_VERSION=controller-v1.15.1
METRICS_CHART=3.14.0
GH=https://raw.githubusercontent.com/kubernetes/ingress-nginx

if ! kind get clusters | grep -qx "$CLUSTER"; then
  kind create cluster --config kind-config.yaml
fi
kubectl config use-context "$CTX" >/dev/null
kubectl apply -f namespaces.yaml

kubectl apply -f "$GH/$INGRESS_VERSION/deploy/static/provider/kind/deploy.yaml"
kubectl -n ingress-nginx patch deployment ingress-nginx-controller \
  --type merge -p '{"spec":{"template":{"spec":{"nodeSelector":
  {"ingress-ready":"true","kubernetes.io/os":"linux"}}}}}'
kubectl -n ingress-nginx rollout status deployment ingress-nginx-controller \
  --timeout=180s

helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/ \
  --force-update >/dev/null
helm upgrade --install metrics-server metrics-server/metrics-server \
  --version "$METRICS_CHART" -n kube-system \
  --set 'args={--kubelet-insecure-tls}' --wait

[ "${PRELOAD:-1}" = 1 ] && ./preload.sh

echo "✔ Cluster $CLUSTER bereit (Kontext $CTX)"
EOF
chmod +x ~/ki-lab/code/kind-lab/up.sh

preload.sh und down.sh liegen im Begleitmaterial unter ~/ki-lab/code/kind-lab/. preload.sh enthält die Schleife aus Drill 7 mit einer Image-Liste, die spätere Tage erweitern. Teste den Neubau:

~/ki-lab/code/kind-lab/down.sh
~/ki-lab/code/kind-lab/up.sh | tail -1

Erwartet (dauert je nach Netz und Cache 2–5 min):

Deleting cluster "ki-lab" ...
✔ Cluster ki-lab bereit (Kontext kind-ki-lab)

Ohne Vorladen: PRELOAD=0 ~/ki-lab/code/kind-lab/up.sh.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Kontext kind-ki-lab" '[ "$(kubectl config current-context)" = kind-ki-lab ]'
check "2 Nodes Ready" \
  '[ "$(kubectl get nodes --no-headers | grep -c " Ready ")" -eq 2 ]'
check "Worker-Label models" \
  'kubectl get nodes -l ki-lab/role=models -o name | grep -q .'
for ns in ki-models ki-gateway ki-chat ki-code monitoring; do
  check "Namespace $ns" "kubectl get ns $ns"
done
check "Ingress antwortet" \
  '[ "$(curl -s -o /dev/null -w "%{http_code}" http://nix.ki.localtest.me/)" = 404 ]'
check "StorageClass standard" 'kubectl get sc standard'
check "kubectl top" 'kubectl top nodes'
check "llama.cpp vorgeladen" \
  'docker exec ki-lab-worker crictl images | grep -q llama.cpp'

Challenge

Schütze den Laptop vor einem gierigen Modell: Im Namespace ki-models sollen alle Pods zusammen höchstens 4 CPU und 6 GiB RAM anfordern und 8 GiB Limit haben dürfen. Container ohne Angaben bekommen Defaults. Beweise, dass ein Pod mit 10 GiB abgelehnt wird.

Hinweis: ResourceQuota begrenzt die Summe, LimitRange setzt Defaults für Container ohne resources.

Lösung

cat > ~/ki-lab/code/kind-lab/quota-ki-models.yaml <<'EOF'
apiVersion: v1
kind: LimitRange
metadata:
  name: defaults
  namespace: ki-models
spec:
  limits:
    - type: Container
      defaultRequest:
        cpu: 100m
        memory: 128Mi
      default:
        memory: 512Mi
---
apiVersion: v1
kind: ResourceQuota
metadata:
  name: ki-models
  namespace: ki-models
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 6Gi
    limits.memory: 8Gi
    persistentvolumeclaims: "5"
EOF
kubectl apply -f ~/ki-lab/code/kind-lab/quota-ki-models.yaml
kubectl -n ki-models run gierig --image=busybox:1.37 --restart=Never \
  --overrides='{"spec":{"containers":[{"name":"gierig","image":"busybox:1.37",
  "command":["sleep","60"],"resources":{"requests":{"memory":"10Gi"},
  "limits":{"memory":"10Gi"}}}]}}'

Erwartet:

limitrange/defaults created
resourcequota/ki-models created
Error from server (Forbidden): pods "gierig" is forbidden: exceeded quota: ki-models,
requested: limits.memory=10Gi,requests.memory=10Gi, used: limits.memory=0,
requests.memory=0, limited: limits.memory=8Gi,requests.memory=6Gi

Die Quota bleibt für Tag 2 bestehen: Der llama.cpp-Pod passt mit 1 GiB Request und 2 GiB Limit hinein. Ein CPU-Limit setzt die Quota bewusst nicht, CPU wird gedrosselt, nicht getötet.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Ingress-NGINX ist eingestellt. Neue Plattformen setzen auf eine Gateway-API-Implementierung (z. B. Cilium, Envoy Gateway, Traefik) – das Ingress-Objekt bleibt für Bestandsanwendungen.
  • Große KI-Images gehören in eine interne Registry mit Pull-Through-Cache (Harbor, Zot), nicht per kind load auf Nodes.
  • Modelle nie auf Node-lokalem Storage ohne Plan B: Entweder ein gemeinsamer Modell-Store (S3, NFS, OCI-Artefakt) oder bewusst lokales NVMe mit Neu-Download beim Ausfall.
  • Quotas und LimitRanges pro Team-Namespace sind Pflicht, sobald mehrere Teams GPUs teilen (Tag 10).
  • --kubelet-insecure-tls nur im Lab; produktiv signiert die Cluster-CA die Kubelet-Serving-Zertifikate.