Tag 0: Das Trainingsgelände
Ziel: Aus drei leeren Ubuntu-VMs wird der RKE2-Cluster
debug, auf dem du ab morgen Fehler einbaust und findest. · Dauer: ca. 90 min · Voraussetzung: drei VMs mit Ubuntu 24.04, SSH-Zugang undsudo
Briefing
- Du baust einen RKE2-Cluster aus drei Knoten:
cp1ist Server (Control Plane, etcd) und zugleich dein Arbeitsplatz,worker1undworker2sind Agents. - RKE2 bringt Canal als CNI, Traefik, CoreDNS und metrics-server mit. Eine StorageClass ergänzt du selbst, aber bewusst nicht als Default.
- Heute lernst du die Orte kennen, an denen später die Antworten
stehen: das Journal von
rke2-serverundrke2-agent,crictlauf dem Knoten und die Kubeconfig. - Talos kommt erst an Tag 18 dazu, als eigener Cluster auf der VM
argo.
Management-Netz 172.16.0.0/24
────┬──────────────────┬──────────────────┬────
cp1 .126 worker1 .228 worker2 .83
rke2-server rke2-agent rke2-agent
etcd, API-Server kubelet kubelet
= Arbeitsplatz containerd containerd
kubectl k9s helm
Drill 1: Die Ausgangslage
Das Buch wurde auf drei VMs unter Proxmox getestet: cp1
mit 4 vCPU und 11 GiB RAM, die beiden Worker mit je 2 vCPU und 4 GiB.
Alle laufen mit Ubuntu 24.04 auf amd64.
# auf cp1
lsb_release -ds
nproc
free -h | head -2
dpkg --print-architecture
sudo ufw statusErwartet:
Ubuntu 24.04.5 LTS
4
total used free shared buff/cache available
Mem: 11Gi 434Mi 11Gi 1.1Mi 297Mi 11Gi
amd64
Status: inactive
Ist ufw aktiv, brauchst du Regeln für 6443 und 9345
(TCP, Server), 10250 und 30000–32767 (TCP, alle Knoten; NodePorts, ab
Tag 4), 8472 (UDP, VXLAN von Canal) und 9099 (TCP, Health-Check von
Canal). Die Liste stammt aus der RKE2-Doku; auf einem Worker mit aktivem
ufw lief damit alles (Pods, Services, NodePorts, DNS). Die
Challenge zeigt, wie eine blockierte 9345 aussieht.
Für die Knoten-Tage gehst du von cp1 per SSH auf die
Worker. Trag die Namen ein und leg einen Schlüssel an, falls
cp1 noch keinen hat:
# auf cp1
sudo tee -a /etc/hosts <<'EOF'
172.16.0.126 cp1
172.16.0.228 worker1
172.16.0.83 worker2
EOF
[ -f ~/.ssh/id_ed25519 ] || ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pubDen öffentlichen Schlüssel hängst du auf beiden Workern an
~/.ssh/authorized_keys an, auf dem Weg, auf dem du auch
deinen eigenen Schlüssel hinterlegt hast. Danach:
# auf cp1
ssh -o StrictHostKeyChecking=accept-new worker1 hostname
ssh -o StrictHostKeyChecking=accept-new worker2 hostnameErwartet:
worker1
worker2
Fortschritt speichern? Kostenlos registrieren
Drill 2: Die Konfiguration des Servers
RKE2 liest beim ersten Start
/etc/rancher/rke2/config.yaml. Jeder Schlüssel entspricht
einer Option von rke2 server. Die Datei muss liegen,
bevor der Dienst zum ersten Mal startet.
# auf cp1
mkdir -p ~/debug/tag00 && cd ~/debug/tag00
openssl rand -hex 32 > rke2-token
chmod 600 rke2-token
sudo mkdir -p /etc/rancher/rke2
sudo tee /etc/rancher/rke2/config.yaml >/dev/null <<EOF
node-name: cp1
node-ip: 172.16.0.126
token: $(cat rke2-token)
tls-san:
- 172.16.0.126
- cp1
write-kubeconfig-mode: "0600"
cni: canal
EOF
sudo chmod 600 /etc/rancher/rke2/config.yaml
sudo sed 's/^token: .*/token: <gekürzt>/' /etc/rancher/rke2/config.yamlErwartet:
node-name: cp1
node-ip: 172.16.0.126
token: <gekürzt>
tls-san:
- 172.16.0.126
- cp1
write-kubeconfig-mode: "0600"
cni: canal
Warum? Der Heredoc-Marker EOF steht hier ohne
Anführungszeichen, damit die Shell $(cat rke2-token)
einsetzt. token ist das gemeinsame Geheimnis von Server und
Agents, tls-san nimmt IP und Namen ins Zertifikat des
API-Servers auf.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Den Server starten und sein Log lesen
# auf cp1
curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_VERSION=v1.37.2+rke2r1 sh -
time sudo systemctl enable --now rke2-server.serviceErwartet (gekürzt):
[INFO] using v1.37.2+rke2r1 as release
[INFO] verifying tarball
[INFO] unpacking tarball file to /usr/local
Created symlink /etc/systemd/system/multi-user.target.wants/rke2-server.service → ...
real 1m29.932s
systemctl kehrt erst zurück, wenn etcd und API-Server
laufen – beim ersten Start mit dem Laden der Images rund anderthalb
Minuten. Das Log ist der erste Ort, an dem du nachsiehst, wenn das
länger dauert:
# auf cp1
sudo journalctl -u rke2-server -b -o cat \
| grep -E 'Starting rke2|Wrote kubeconfig|level=error' | cut -c1-88Erwartet (gekürzt):
time="2026-11-20T06:29:51Z" level=info msg="Starting rke2 v1.37.2+rke2r1 (972ca61add47ea
time="2026-11-20T06:29:56Z" level=error msg="Sending HTTP/1.1 503 response to 127.0.0.1:
time="2026-11-20T06:29:56Z" level=info msg="Wrote kubeconfig /etc/rancher/rke2/rke2.yaml
time="2026-11-20T06:30:24Z" level=error msg="Failed to process image event: failed to im
time="2026-11-20T06:31:19Z" level=error msg="Failed to process image event: failed to im
Warum? Nicht jedes level=error ist ein Fehler. Die
503 … runtime core not ready stammen aus den ersten
Sekunden, in denen der Supervisor schon Anfragen bekommt, aber etcd noch
nicht bereit ist. Die
Failed to process image event … not found meldet der Import
der Image-Listen; die Images holt das kubelet danach trotzdem.
Entscheidend ist, ob danach Pods laufen – das zeigt Drill 4.
Tipp:
journalctl -u rke2-server -ffolgt dem Log live. Fehler in derconfig.yaml(unbekannter Schlüssel, falsche Einrückung) stehen ganz am Anfang.
Fortschritt speichern? Kostenlos registrieren
Drill 4: kubectl, Kubeconfig und die drei Variablen
RKE2 legt kubectl, crictl und
ctr unter /var/lib/rancher/rke2/bin ab und
schreibt die Admin-Kubeconfig nach
/etc/rancher/rke2/rke2.yaml, lesbar nur für root.
crictl findet den Socket von containerd nur mit
CRI_CONFIG_FILE.
# auf cp1
sudo tee /etc/profile.d/rke2.sh >/dev/null <<'EOF'
export PATH=$PATH:/var/lib/rancher/rke2/bin
export CRI_CONFIG_FILE=/var/lib/rancher/rke2/agent/etc/crictl.yaml
if [ "$(id -u)" = 0 ]; then export KUBECONFIG=/etc/rancher/rke2/rke2.yaml; fi
EOF
sudo ln -s /var/lib/rancher/rke2/bin/kubectl /usr/local/bin/kubectl
mkdir -p ~/.kube
sudo install -m 600 -o "$USER" -g "$USER" /etc/rancher/rke2/rke2.yaml ~/.kube/config
kubectl get nodesErwartet:
NAME STATUS ROLES AGE VERSION
cp1 NotReady control-plane,etcd 49s v1.37.2+rke2r1
NotReady ist in der ersten Minute normal: Canal muss
erst starten, bevor das kubelet das Pod-Netz meldet. Jetzt dasselbe aus
Sicht von containerd. sudo -i öffnet eine Login-Shell und
liest dabei /etc/profile.d/rke2.sh:
# auf cp1
sudo -i crictl ps -o table | head -5 | cut -c1-88Erwartet (gekürzt):
CONTAINER IMAGE CREATED STATE NAME
9b0b5d0288151 ddf8337da7bdb 40 seconds ago Running cloud-c
c568c35ccde1d 6d31c161dcb90 44 seconds ago Running kube-sc
924396c58fd99 6d31c161dcb90 44 seconds ago Running kube-co
a35a7f4fd0f0b 6d31c161dcb90 54 seconds ago Running kube-ap
Warum? Die Control Plane läuft bei RKE2 als Static Pods, die das
kubelet selbst startet. Fällt der API-Server aus, siehst du sie mit
kubectl nicht mehr, mit crictl schon (Tag
15).
Fortschritt speichern? Kostenlos registrieren
Drill 5: Die Agents
Der Agent meldet sich über den Supervisor-Port 9345 beim Server an, nicht über 6443. Über diese Verbindung holt er Zertifikate und Konfiguration. Zuerst bekommt jeder Worker das Token:
# auf cp1
cd ~/debug/tag00
scp -q rke2-token worker1: && scp -q rke2-token worker2:# auf worker1
sudo mkdir -p /etc/rancher/rke2
sudo tee /etc/rancher/rke2/config.yaml >/dev/null <<EOF
server: https://172.16.0.126:9345
node-name: worker1
node-ip: 172.16.0.228
token: $(cat ~/rke2-token)
EOF
sudo chmod 600 /etc/rancher/rke2/config.yaml
rm ~/rke2-token
curl -sfL https://get.rke2.io | \
sudo INSTALL_RKE2_VERSION=v1.37.2+rke2r1 INSTALL_RKE2_TYPE=agent sh -
sudo systemctl enable --now rke2-agent.serviceAuf worker2 dasselbe mit node-name: worker2
und node-ip: 172.16.0.83. Auch auf beiden Workern brauchst
du die Variablen aus Drill 4: Leg dort dieselbe Datei
/etc/profile.d/rke2.sh an (die
KUBECONFIG-Zeile greift auf Agents ins Leere und stört
nicht). Das Log des Agents:
# auf worker1
sudo journalctl -u rke2-agent -b -o cat \
| grep -E 'Starting rke2|Remotedialer|Running kubelet' | cut -c1-88Erwartet:
time="2026-11-20T06:32:43Z" level=info msg="Starting rke2 agent v1.37.2+rke2r1 (972ca61a
time="2026-11-20T06:32:58Z" level=info msg="Remotedialer connected to proxy" url="wss://
time="2026-11-20T06:34:00Z" level=info msg="Running kubelet --alsologtostderr=false --cl
Remotedialer connected heißt: Der Tunnel zum Supervisor
steht. Fehlt die Zeile, liegt das Problem zwischen Agent und Port
9345.
# auf cp1
kubectl get nodes -o wide | cut -c1-88Erwartet:
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL
cp1 Ready control-plane,etcd 8m49s v1.37.2+rke2r1 172.16.0.126 <none>
worker1 Ready <none> 6m v1.37.2+rke2r1 172.16.0.228 <none>
worker2 Ready <none> 4m38s v1.37.2+rke2r1 172.16.0.83 <none>
Fortschritt speichern? Kostenlos registrieren
Drill 6: Was RKE2 mitbringt
Die Zusatzkomponenten installiert RKE2 als Helm-Charts über einen
eigenen Controller. Jedes Chart ist ein Objekt vom Typ
HelmChart, installiert von einem Job
helm-install-<name>.
# auf cp1
kubectl -n kube-system get helmcharts
kubectl get nodes -o custom-columns=NAME:.metadata.name,\
RUNTIME:.status.nodeInfo.containerRuntimeVersionErwartet (gekürzt):
NAME REPO CHART VERSION TARGETNAMESPACE BOOTSTRAP ...
rke2-canal true ...
rke2-coredns true ...
rke2-gateway-api-crd ...
rke2-metrics-server ...
rke2-runtimeclasses ...
rke2-security-responder ...
rke2-snapshot-controller ...
rke2-snapshot-controller-crd ...
rke2-traefik ...
rke2-traefik-crd ...
NAME RUNTIME
cp1 containerd://2.3.7-k3s1
worker1 containerd://2.3.7-k3s1
worker2 containerd://2.3.7-k3s1
Warum? In RKE2 1.37 ist Traefik der Standard-Ingress-Controller, die
Gateway-API-CRDs kommen aus einem eigenen Chart. Bleibt ein Pod
helm-install-… in Error hängen, steht der
Grund in seinem Log (Tag 9).
Talos: Talos bringt weder Ingress noch metrics-server mit; was das für die Fehlersuche heißt, zeigen Tag 18 und 19.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Die Werkzeuge
helm, k9s und die Kyverno-CLI installierst
du architekturneutral. Die Kyverno-CLI nennt amd64 x86_64,
deshalb die Ersetzung in KARCH.
# auf cp1
cd ~/debug/tag00
ARCH=$(dpkg --print-architecture)
curl -sSfLO https://get.helm.sh/helm-v4.3.2-linux-${ARCH}.tar.gz
tar xzf helm-v4.3.2-linux-${ARCH}.tar.gz linux-${ARCH}/helm
sudo install -m 755 linux-${ARCH}/helm /usr/local/bin/helm
K9S=https://github.com/derailed/k9s/releases/download/v0.51.0
curl -sSfLO ${K9S}/k9s_Linux_${ARCH}.tar.gz
tar xzf k9s_Linux_${ARCH}.tar.gz k9s
sudo install -m 755 k9s /usr/local/bin/k9s
KARCH=${ARCH/amd64/x86_64}
KYV=https://github.com/kyverno/kyverno/releases/download/v1.20.0
curl -sSfLO ${KYV}/kyverno-cli_v1.20.0_linux_${KARCH}.tar.gz
tar xzf kyverno-cli_v1.20.0_linux_${KARCH}.tar.gz kyverno
sudo install -m 755 kyverno /usr/local/bin/kyverno
rm -rf linux-${ARCH} k9s kyverno *.tar.gz
helm version --short
k9s version | head -1
kyverno version | head -1Erwartet:
v4.3.2+g8346aaa
Version v0.51.0
Version: v1.20.0
jq, curl und openssl bringt
Ubuntu 24.04 schon mit.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Eine StorageClass, aber kein Default
RKE2 hat keine StorageClass. Du installierst den local-path-provisioner. Sein Manifest setzt kein Default-Kennzeichen, und das bleibt so: In Tag 3 und 10 brauchst du das Fehlerbild „PVC ohne StorageClass“.
# auf cp1
kubectl apply -f https://raw.githubusercontent.com/rancher/\
local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml
kubectl -n local-path-storage rollout status deploy/local-path-provisioner
kubectl get storageclassErwartet (gekürzt):
namespace/local-path-storage created
...
storageclass.storage.k8s.io/local-path created
configmap/local-path-config created
deployment "local-path-provisioner" successfully rolled out
NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ...
local-path rancher.io/local-path Delete WaitForFirstConsumer ...
Hinter local-path steht kein (default). Ob
wirklich ein Volume entsteht, zeigt ein kleiner Test:
# auf cp1
cat > pvc-test.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: daten, namespace: tag00}
spec:
storageClassName: local-path
accessModes: [ReadWriteOnce]
resources: {requests: {storage: 100Mi}}
---
apiVersion: v1
kind: Pod
metadata: {name: schreiber, namespace: tag00}
spec:
containers:
- name: schreiber
image: busybox:1.37
command: [sh, -c, 'date > /daten/hallo.txt; cat /daten/hallo.txt; sleep 3600']
volumeMounts: [{name: daten, mountPath: /daten}]
volumes:
- name: daten
persistentVolumeClaim: {claimName: daten}
EOF
kubectl create namespace tag00
kubectl apply -f pvc-test.yaml
kubectl -n tag00 wait pod/schreiber --for=condition=Ready --timeout=120s
kubectl -n tag00 get pod schreiber -o wide | cut -c1-72
kubectl get pv -o custom-columns=PATH:.spec.hostPath.path | cut -c1-88Erwartet:
namespace/tag00 created
persistentvolumeclaim/daten created
pod/schreiber created
pod/schreiber condition met
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE
schreiber 1/1 Running 0 13s 10.42.1.5 worker1 <none>
PATH
/opt/local-path-provisioner/pvc-6626be9a-953e-42e6-98d6-8c30e89d4f60_tag00_daten
Das Verzeichnis liegt auf dem Knoten aus der Spalte
NODE, bei dir eventuell auf worker2:
# auf worker1
sudo cat /opt/local-path-provisioner/*_tag00_daten/hallo.txtErwartet:
Fri Nov 20 06:37:38 UTC 2026
Tipp: Mach jetzt einen Snapshot aller drei VMs. Ab Tag 3 baust du Fehler ein; jeder Tag räumt zwar auf, aber ein Snapshot ist der schnellste Weg zurück.
Fortschritt speichern? Kostenlos registrieren
Übung: Speed-Drills
- Zeig Name, kubelet-Version und Container-Runtime aller Knoten. Zeitziel: 30 s
- Zeig von
cp1aus die Flannel-Container aufworker2. Zeitziel: 30 s - Zähl die
level=error-Zeilen vonrke2-serverseit dem letzten Boot. Zeitziel: 30 s - Prüf, ob der API-Server bereit ist, und zeig nur die letzte Zeile. Zeitziel: 20 s
Lösung
# auf cp1
kubectl get nodes -o custom-columns=NAME:.metadata.name,\
VERSION:.status.nodeInfo.kubeletVersion,\
RUNTIME:.status.nodeInfo.containerRuntimeVersion
ssh worker2 sudo -i crictl ps --name flannel | cut -c1-88
sudo journalctl -u rke2-server -b -o cat | grep -c level=error
kubectl get --raw='/readyz?verbose' | tail -1Erwartet (gekürzt):
NAME VERSION RUNTIME
cp1 v1.37.2+rke2r1 containerd://2.3.7-k3s1
worker1 v1.37.2+rke2r1 containerd://2.3.7-k3s1
worker2 v1.37.2+rke2r1 containerd://2.3.7-k3s1
CONTAINER IMAGE CREATED STATE NAME
d27d5570b3822 4f23b420044ae 5 minutes ago Running kube-fla
6
readyz check passed
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
# auf cp1
kubectl get nodesErwartet: drei Knoten, alle Ready,
Version v1.37.2+rke2r1.
# auf cp1
kubectl get storageclass -o nameErwartet:
storageclass.storage.k8s.io/local-path
# auf cp1
kubectl get storageclass local-path \
-o jsonpath='{.metadata.annotations.storageclass\.kubernetes\.io/is-default-class}'Erwartet: keine Ausgabe – local-path
ist nicht Default.
# auf cp1
ssh worker1 sudo -i crictl version | tail -2Erwartet:
RuntimeVersion: v2.3.7-k3s1
RuntimeApiVersion: v1
Challenge
Blockiere auf cp1 den Port 9345 nur für
worker2, starte dort rke2-agent neu und finde
die Meldung, die den Grund verrät. Nimm die Sperre danach zurück.
Hinweis: Der Agent spricht den Supervisor über einen lokalen Loadbalancer auf Port 6444 an – die Meldung nennt deshalb nicht nur 9345.
Lösung
# auf cp1
sudo iptables -I INPUT -p tcp --dport 9345 -s 172.16.0.83 -j REJECT# auf worker2
sudo systemctl restart rke2-agent --no-block
systemctl is-active rke2-agent
sudo journalctl -u rke2-agent --since -1min -o cat | grep level=error | tail -2
nc -zv -w3 172.16.0.126 9345
nc -zv -w3 172.16.0.126 6443Erwartet (Zeilen umbrochen):
activating
time="2026-11-20T06:38:32Z" level=error msg="Failed to validate connection to
cluster at https://172.16.0.126:9345: failed to get CA certs:
Get \"https://127.0.0.1:6444/cacerts\": EOF"
nc: connect to 172.16.0.126 port 9345 (tcp) failed: Connection refused
Connection to 172.16.0.126 6443 port [tcp/*] succeeded!
Der Dienst hängt in activating, und nach rund 50
Sekunden steht worker2 in kubectl get nodes
auf NotReady. Port 6443 ist offen, das reicht dem Agent
aber nicht. Sperre zurücknehmen:
# auf cp1
sudo iptables -D INPUT -p tcp --dport 9345 -s 172.16.0.83 -j REJECT
kubectl get nodesErwartet: nach etwa 30 Sekunden alle drei Knoten
wieder Ready.
Fortschritt speichern? Kostenlos registrieren
Aufräumen
# auf cp1
kubectl delete namespace tag00
rm ~/debug/tag00/rke2-token
kubectl get pvErwartet:
namespace "tag00" deleted
No resources found
Das Token brauchst du für weitere Knoten nicht mehr aus der Datei: Es
steht in /etc/rancher/rke2/config.yaml auf
cp1.
Interview-Notiz
- Wie meldet sich ein RKE2-Agent an? Über den Supervisor-Port 9345 mit dem gemeinsamen Token; erst danach bekommt er Zertifikate und startet das kubelet.
- Wo schaust du zuerst, wenn ein RKE2-Knoten nicht hochkommt?
journalctl -u rke2-serverbzw.rke2-agent, danncrictl ps -aauf dem Knoten. - Warum keine Default-StorageClass? Ein PVC ohne
storageClassNamesoll sichtbar hängen bleiben, statt still auf einem lokalen Pfad zu landen.
Enterprise-Notiz
- Produktiv drei Server (etcd-Quorum) hinter einer festen
Registrierungsadresse (DNS oder VIP) in
server:undtls-san, nie die IP eines einzelnen Servers. - Das Token gehört in einen Secret-Store; neue Knoten bekommen es per
Automatisierung, nicht per
scp. - Air-Gap: Images als Tarball unter
/var/lib/rancher/rke2/agent/images/und eine eigene Registry inregistries.yaml(Tag 4). - Firewall-Regeln für 6443, 9345, 10250, NodePorts und 8472/UDP als Code pflegen; die meisten „Agent kommt nicht hoch“-Tickets sind Ports.
- Für Storage in Produktion ein verteiltes System (Longhorn, Ceph, Cloud-CSI) statt local-path; local-path bindet Pods an Knoten.