Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Troubleshooting I – kaputte Nodes und Komponenten

Ziel: Du findest und reparierst Fehler in kubelet, Container-Runtime, Control-Plane und kubeconfig – auch wenn kubectl nicht mehr antwortet. · Dauer: ca. 90 min · Voraussetzung: Tag 13

Briefing

CKA: Troubleshooting (30 %) – „Troubleshoot clusters and nodes”, „Troubleshoot cluster components”. Heute machst du den Cluster absichtlich kaputt – und reparierst ihn sofort.

  Symptom                    erster Blick                dann
  Node NotReady          --> describe node          --> ssh, systemctl, journalctl
  Pods bleiben Pending   --> Scheduler-Pod          --> kubectl logs / crictl logs
  Deployment ohne Pods   --> Controller-Manager     --> Manifest prüfen
  connection refused     --> kubeconfig, API-Server --> crictl ps -a, crictl logs

Regel für jeden Drill: erst sichern, dann kaputt machen. Jede Störung wird im selben Drill repariert.

k create ns tag14

Drill 1: Das kubelet steht

Auf worker2:

sudo systemctl stop kubelet

Auf cp1, nach etwa 50 Sekunden:

k get nodes
k describe node worker2 | grep -A6 '^Conditions'

Erwartet (gekürzt):

NAME      STATUS     ROLES           AGE   VERSION
cp1       Ready      control-plane   92m   v1.37.2
worker1   Ready      <none>          91m   v1.37.2
worker2   NotReady   <none>          91m   v1.37.2
Conditions:
  Type                 Status    ...   Reason              Message
  NetworkUnavailable   False     ...   CalicoIsUp          Calico is running on ...
  MemoryPressure       Unknown   ...   NodeStatusUnknown   Kubelet stopped posting ...
  ...
  Ready                Unknown   ...   NodeStatusUnknown   Kubelet stopped posting ...

Unknown heißt: Das kubelet meldet sich nicht mehr. Auf worker2:

systemctl status kubelet --no-pager | grep Active
sudo systemctl start kubelet
systemctl is-enabled kubelet

Erwartet:

     Active: inactive (dead) since Tue 2026-11-17 22:44:13 UTC; 54s ago
enabled

Prüfe immer auch is-enabled – ein deaktivierter Dienst ist nach dem nächsten Neustart wieder weg.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das kubelet startet nicht

Auf worker1 sichern und einen Tippfehler einbauen:

sudo cp /var/lib/kubelet/config.yaml /root/kubelet-config.bak
sudo sed -i 's#/etc/kubernetes/pki/ca.crt#/etc/kubernetes/pki/ca.cert#' \
  /var/lib/kubelet/config.yaml
sudo systemctl restart kubelet
systemctl is-active kubelet

Erwartet: activating – das kubelet startet, stirbt und startet erneut. Der Grund steht im Journal:

sudo journalctl -u kubelet --no-pager -n 40 | grep -m2 -E 'error|failed'

Erwartet (gekürzt):

... run.go:72] "command failed" err="failed to run Kubelet: open
/etc/kubernetes/pki/ca.cert:
no such file or directory"
... systemd[1]: kubelet.service: Failed with result 'exit-code'.

Reparieren:

sudo sed -i 's#/etc/kubernetes/pki/ca.cert#/etc/kubernetes/pki/ca.crt#' \
  /var/lib/kubelet/config.yaml
sudo systemctl restart kubelet
systemctl is-active kubelet

Erwartet: active

Die Konfiguration des kubelets liegt an drei Stellen: /var/lib/kubelet/config.yaml, /var/lib/kubelet/kubeadm-flags.env und die systemd-Drop-ins (systemctl cat kubelet).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die Container-Runtime ist weg

Weiter auf worker1:

sudo systemctl stop containerd

Auf cp1, nach etwa 45 Sekunden:

k get node worker1
k describe node worker1 | grep -E '^\s+Ready'

Erwartet (gekürzt):

NAME      STATUS     ROLES    AGE   VERSION
worker1   NotReady   <none>   93m   v1.37.2
  Ready   False   ...   KubeletNotReady   container runtime is down

Diesmal läuft das kubelet und meldet sich – aber es hat keine Runtime. Auf worker1:

sudo crictl ps

Erwartet (gekürzt):

... level=fatal msg="validate service connection: validate CRI v1 runtime API for
endpoint
\"unix:///run/containerd/containerd.sock\": ... connect: no such file or directory\""
sudo systemctl start containerd

Nach etwa 20 Sekunden ist worker1 wieder Ready. Laufende Container überleben einen containerd-Neustart übrigens – die Shims laufen weiter.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Pods bleiben Pending – der Scheduler

Auf cp1:

sudo cp /etc/kubernetes/manifests/kube-scheduler.yaml /root/kube-scheduler.yaml.bak
sudo sed -i 's#--kubeconfig=/etc/kubernetes/scheduler.conf#&f#' \
  /etc/kubernetes/manifests/kube-scheduler.yaml

Nach etwa 40 Sekunden einen Pod starten:

k run probe -n tag14 --image=nginx:1.29
k get pod probe -n tag14
k describe pod probe -n tag14 | tail -1

Erwartet:

NAME    READY   STATUS    RESTARTS   AGE
probe   0/1     Pending   0          10s
Events:                      <none>

Pending ohne Events heißt: Niemand hat überhaupt versucht, den Pod zu platzieren. Bei einem Platzproblem stünde dort FailedScheduling (Tag 5).

k get pods -n kube-system -l component=kube-scheduler
k logs -n kube-system kube-scheduler-cp1 | tail -1

Erwartet:

NAME                 READY   STATUS             RESTARTS      AGE
kube-scheduler-cp1   0/1     CrashLoopBackOff   2 (25s ago)   41s
E1117 22:47:34.120554  1 run.go:72] "command failed" err="stat
/etc/kubernetes/scheduler.conff:
no such file or directory"

Reparieren:

sudo sed -i 's#scheduler.conff#scheduler.conf#' \
  /etc/kubernetes/manifests/kube-scheduler.yaml

Nach etwa 30 Sekunden läuft der Scheduler, und probe wird auf einen Worker gesetzt.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Deployment ohne Pods – der Controller-Manager

sudo mv /etc/kubernetes/manifests/kube-controller-manager.yaml /root/
k create deployment ghost -n tag14 --image=nginx:1.29 --replicas=2
k get deploy,rs,pods -n tag14 -l app=ghost
k get pods -n kube-system -l component=kube-controller-manager

Erwartet:

deployment.apps/ghost created
NAME                    READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/ghost   0/2     0            0           11s
No resources found in kube-system namespace.

Das Deployment existiert, aber kein ReplicaSet: Der Deployment-Controller, der es anlegen würde, lebt im Controller-Manager. Reparieren:

sudo mv /root/kube-controller-manager.yaml /etc/kubernetes/manifests/

Nach etwa 40 Sekunden:

k get deploy ghost -n tag14

Erwartet: READY zeigt 2/2.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Der API-Server ist tot

Jetzt die schwerste Störung – ohne API-Server hilft kubectl nicht mehr:

sudo cp /etc/kubernetes/manifests/kube-apiserver.yaml /root/kube-apiserver.yaml.bak
sudo sed -i 's#127.0.0.1:2379#127.0.0.1:2399#' \
  /etc/kubernetes/manifests/kube-apiserver.yaml

Nach etwa einer Minute:

k get nodes

Erwartet (gekürzt):

... dial tcp 172.16.0.126:6443: connect: connection refused ...

Eine Ebene tiefer – die Runtime fragen:

sudo crictl ps -a --name kube-apiserver

Erwartet:

CONTAINER       IMAGE           CREATED                  STATE     NAME             ...
a1dbdea6509df   7a918dfe48696   Less than a second ago   Created   kube-apiserver   ...
7686936e813f5   7a918dfe48696   22 seconds ago           Exited    kube-apiserver   ...

-a zeigt auch beendete Container – deren Logs verraten den Grund:

ID=$(sudo crictl ps -a --name kube-apiserver --state exited -q | head -1)
sudo crictl logs $ID 2>&1 | tail -1

Erwartet:

E1117 22:49:41.420449  1 run.go:72] "command failed" err="error creating storage
factory:
etcd grpc connection not ready: context deadline exceeded"

Weiter oben stehen Zeilen mit 127.0.0.1:2399 – der falsche Port. Dieselben Logs liegen auch als Dateien unter /var/log/pods/kube-system_kube-apiserver-cp1_*/. Reparieren:

sudo sed -i 's#127.0.0.1:2399#127.0.0.1:2379#' \
  /etc/kubernetes/manifests/kube-apiserver.yaml

Nach ein bis zwei Minuten antwortet k get nodes wieder.

Fortschritt speichern? Kostenlos registrieren

Drill 7: kubectl spricht ins Leere

Nicht jeder connection refused ist ein toter API-Server:

cp ~/.kube/config /tmp/kubeconfig.bak
sed -i 's#:6443#:6444#' ~/.kube/config
k get nodes
k config view --minify -o jsonpath='{.clusters[0].cluster.server}{"\n"}'

Erwartet:

The connection to the server 172.16.0.126:6444 was refused - did you specify the right
host
or port?
https://172.16.0.126:6444

Der Port steht in der Fehlermeldung – vergleiche ihn mit dem Manifest (--secure-port=6443). Reparieren:

sed -i 's#:6444#:6443#' ~/.kube/config
k get --raw='/readyz?verbose' | tail -2

Erwartet:

[+]shutdown ok
readyz check passed

/readyz?verbose prüft alle Teile des API-Servers einschließlich etcd – der schnellste Gesundheitscheck.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Zeige die letzten 20 Zeilen des kubelet-Journals auf worker1. Zeitziel: 20 s
  2. Liste alle Control-Plane-Pods mit Neustarts. Zeitziel: 20 s
  3. Prüfe, ob etcd aus Sicht des API-Servers gesund ist. Zeitziel: 15 s

Lösung

Auf worker1:

sudo journalctl -u kubelet --no-pager -n 20

Auf cp1:

k get pods -n kube-system -l tier=control-plane
k get --raw='/livez/etcd'; echo

Erwartet (Ausschnitt):

NAME                          READY   STATUS    RESTARTS      AGE
etcd-cp1                      1/1     Running   1 (17m ago)   16m
kube-apiserver-cp1            1/1     Running   0             16m
kube-controller-manager-cp1   1/1     Running   2 (82s ago)   31s
kube-scheduler-cp1            1/1     Running   1 (3m ago)    3m30s
ok

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

k get nodes

Erwartet: alle drei Nodes Ready.

k get pods -n kube-system -l tier=control-plane --no-headers | grep -vc Running

Erwartet: 0

k get pod probe -n tag14 -o jsonpath='{.status.phase}{"\n"}'

Erwartet: Running

Challenge

Ein Kollege meldet: „Auf worker2 starten keine neuen Pods, die alten laufen.” Baue die Störung nach, indem du auf worker2 den Socket in /var/lib/kubelet/config.yaml auf unix:///var/run/containerd/containerd.sockx änderst und das kubelet neu startest. Finde den Fehler nur mit Node-Werkzeugen und behebe ihn.

Hinweis: journalctl -u kubelet und der Schlüssel containerRuntimeEndpoint.

Lösung

Auf worker2:

sudo cp /var/lib/kubelet/config.yaml /root/kubelet-config.bak
sudo sed -i 's#containerd.sock$#containerd.sockx#' /var/lib/kubelet/config.yaml
sudo systemctl restart kubelet
sudo journalctl -u kubelet --no-pager -n 20 | grep -m1 -i 'sockx'
sudo grep containerRuntimeEndpoint /var/lib/kubelet/config.yaml
sudo sed -i 's#containerd.sockx#containerd.sock#' /var/lib/kubelet/config.yaml
sudo systemctl restart kubelet
systemctl is-active kubelet

Erwartet (gekürzt):

... grpc: addrConn.createTransport failed to connect to
{Addr: "/var/run/containerd/containerd.sockx", ServerName: "localhost", }. ...
containerRuntimeEndpoint: unix:///var/run/containerd/containerd.sockx
active

Aufräumen:

k delete ns tag14

Fortschritt speichern? Kostenlos registrieren

Prüfungstipp

  • Node NotReady: ssh auf den Node, dann systemctl status kubelet, journalctl -u kubelet, systemctl status containerd – in dieser Reihenfolge.
  • Control-Plane kaputt: zuerst /etc/kubernetes/manifests prüfen, dann crictl ps -a und crictl logs. Ein Tippfehler im Manifest ist der häufigste Grund.
  • Nach einer Reparatur am Manifest ein bis zwei Minuten warten – das kubelet braucht Zeit, den Pod neu zu erzeugen.

Enterprise-Notiz

  • Node-Probleme erkennt man in Produktion per Monitoring (node-exporter, kube-state-metrics, Alarme auf NotReady), nicht durch Nutzerbeschwerden.
  • Der node-problem-detector meldet Kernel- und Runtime-Probleme als Node-Conditions.
  • Änderungen an Control-Plane-Manifesten gehören in die kubeadm-Konfiguration, sonst überschreibt das nächste Upgrade sie (Tag 13).