Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 15: Control Plane und etcd

Ziel: Du prüfst API-Server und etcd, sicherst etcd vor jedem Eingriff, findest die Ursache, wenn der API-Server nicht mehr startet, und erkennst abgelaufene oder falsche Zertifikate an ihrer Meldung. · Dauer: ca. 75 min · Voraussetzung: Tag 14

Briefing

  • /readyz und /livez des API-Servers beschreiben seinen Zustand selbst; [-] markiert die gescheiterte Prüfung.
  • Ist der API-Server weg, hilft kein kubectl: crictl, journalctl und die Dateien unter /var/log/pods auf cp1 funktionieren ohne Kubernetes.
  • Vor jedem Eingriff an der Control Plane: etcd-Snapshot.
  • Beim Client verraten sich Zertifikatsfehler an der Meldung: Unauthorized (dein Client-Zertifikat – den Grund kennt nur das API-Server-Log), x509: … expired (Zertifikat des Servers), unknown authority (CA in deiner Kubeconfig).
Fehlerbild Symptom Wo die Antwort steht
API-Server startet nicht connection … refused crictl logs, Manifest
Client-Zertifikat abgelaufen Unauthorized openssl x509, API-Log
Falsche CA in der Kubeconfig unknown authority certificate-authority-data

Drill 1: Ist die API gesund?

Der API-Server prüft sich selbst. /livez beantwortet „lebt der Prozess?“, /readyz „kann er Anfragen bedienen, antwortet etcd?“. ?verbose listet jede Einzelprüfung:

# auf cp1
mkdir -p ~/debug/tag15 && cd ~/debug/tag15
kubectl get --raw '/readyz?verbose' | head -4
kubectl get --raw '/readyz?verbose' | grep -c 'ok$'
kubectl get --raw '/readyz?verbose' | grep -v 'ok$'
kubectl get --raw '/livez?verbose' | tail -1
kubectl get --raw /readyz/etcd; echo

Erwartet:

[+]ping ok
[+]log ok
[+]etcd ok
[+]etcd-readiness ok
39
readyz check passed
livez check passed
ok

39 Prüfungen, keine mit [-]. Eine gescheiterte stünde dort als [-]etcd failed: reason withheld – den Grund schreibt der API-Server nur in sein Log. Einzelne Prüfungen fragst du direkt ab wie hier /readyz/etcd.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Vor jedem Eingriff ein etcd-Snapshot

etcd ist das Gedächtnis des Clusters. Bevor du an der Control Plane schraubst, ziehst du einen Snapshot:

# auf cp1
sudo -i rke2 etcd-snapshot save --name tag15-start 2>&1 | grep -o 'Snapshot .* saved.'
sudo -i rke2 etcd-snapshot ls 2>/dev/null | awk '{print $1, $NF}'

Erwartet:

Snapshot tag15-start-cp1-1795185570 saved.
Name Created
nach-tag12-cp1-1795167810 2026-11-20T09:43:30Z
vor-tag15-cp1-1795174399 2026-11-20T11:33:19Z
etcd-snapshot-cp1-1795176005 2026-11-20T12:00:05Z
tag15-start-cp1-1795185570 2026-11-20T14:39:30Z

nach-tag12 und vor-tag15 stammen aus dem Aufbau des Labors, etcd-snapshot-… hat RKE2 um 12 Uhr selbst gezogen – RKE2 sichert automatisch um 0 und 12 Uhr und behält fünf davon. In deiner Liste stehen deine eigenen. Die Snapshots liegen unter /var/lib/rancher/rke2/server/db/snapshots/. Ohne 2>&1 | grep siehst du Warnungen wie Unknown flag --cni found in config.yaml, skipping – etcd-snapshot kennt nicht alle Server-Optionen, harmlos.

Wiederherstellen würdest du so – nur lesen, nicht ausführen: systemctl stop rke2-server, dann rke2 server --cluster-reset --cluster-reset-restore-path=<snapshot>, danach systemctl start rke2-server. Der Cluster springt auf den Stand des Snapshots zurück, alles danach ist weg.

Fortschritt speichern? Kostenlos registrieren

Drill 3: etcd selbst fragen

RKE2 betreibt etcd als Static Pod; etcdctl liegt im Image, die Client-Zertifikate auf dem Knoten:

# auf cp1
E=$(sudo -i crictl ps --name etcd -q)
T=/var/lib/rancher/rke2/server/tls/etcd
sudo -i crictl exec $E etcdctl --cacert $T/server-ca.crt --cert $T/server-client.crt \
  --key $T/server-client.key endpoint health
sudo -i crictl exec $E etcdctl --cacert $T/server-ca.crt --cert $T/server-client.crt \
  --key $T/server-client.key endpoint status -w json \
  | jq -c '.[0].Status | {version, dbSize, dbSizeInUse, raftIndex}'
sudo -i crictl exec $E etcdctl --cacert $T/server-ca.crt --cert $T/server-client.crt \
  --key $T/server-client.key member list -w simple | cut -c1-88
sudo -i crictl exec $E etcdctl --cacert $T/server-ca.crt --cert $T/server-client.crt \
  --key $T/server-client.key alarm list | wc -l

Erwartet:

127.0.0.1:2379 is healthy: successfully committed proposal: took = 28.185044ms
{"version":"3.7.1","dbSize":59551744,"dbSizeInUse":21426176,"raftIndex":180212}
1ff2278c0fd14cc3, started, cp1-6c528aa2, https://172.16.0.126:2380, https://172.16.0.126
0

Ein Mitglied, gesund, 60 MB Datenbank, davon gut 20 MB in Gebrauch. alarm list gibt eine Zeile je aktivem Alarm aus – hier keine. Der Exit-Code hilft nicht: Er ist auch bei aktivem Alarm 0. Ein NOSPACE hieße: Quota voll, etcd nimmt keine Schreibzugriffe mehr an. -w table ist bei etcd 3.7 über 200 Zeichen breit, daher JSON.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der API-Server startet nicht

Einbauen: Ein Feature-Gate, das es nicht gibt – so wie eines, das ein Upgrade entfernt hat:

Achtung: Danach ist die Control Plane weg, bis du den Fehler behebst. Snapshot aus Drill 2 vorher prüfen.

# auf cp1
sudo mkdir -p /etc/rancher/rke2/config.yaml.d
echo 'kube-apiserver-arg: [feature-gates=DebugBuchGate=true]' \
  | sudo tee /etc/rancher/rke2/config.yaml.d/90-kaputt.yaml
sudo systemctl restart rke2-server --no-block

Erwartet:

kube-apiserver-arg: [feature-gates=DebugBuchGate=true]

--no-block kehrt sofort zurück, statt auf einen Start zu warten, der nie fertig wird.

Symptom (nach etwa einer Minute):

# auf cp1
sleep 60
kubectl get nodes
systemctl is-active rke2-server

Erwartet (Zeile umbrochen):

The connection to the server 127.0.0.1:6443 was refused - did you specify the right
  host or port?
activating

Untersuchen: crictl fragt containerd direkt, ganz ohne API-Server:

# auf cp1
sudo -i crictl ps -a --name kube-apiserver | tr -s ' ' | cut -c1-88
sudo -i crictl logs $(sudo -i crictl ps -a --name kube-apiserver -q | head -1) 2>&1 \
  | tail -1 | cut -c1-88
sudo sh -c 'tail -qn1 /var/log/pods/kube-system_kube-apiserver-*/kube-apiserver/*.log' \
  | sed 's/^[^ ]* [^ ]* F //' | cut -c1-88
sudo grep feature-gates /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml
sudo journalctl -u rke2-server -b --no-pager | grep -o 'Polling for API server.*' \
  | tail -1 | cut -c1-88

Erwartet (gekürzt):

CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID POD NAMESPACE
4f2b11200f3d4 6d31c161dcb90 10 seconds ago Exited kube-apiserver 3 a1664c15bb8a3 kube-ap
E1120 14:40:25.164233       1 run.go:72] "command failed" err="unrecognized feature gate
E1120 14:40:25.164233       1 run.go:72] "command failed" err="unrecognized feature gate
    - --feature-gates=DebugBuchGate=true
Polling for API server readiness: GET /readyz failed: Get \"https://127.0.0.1:6443/ready

Container-Log, dieselbe Zeile als Datei unter /var/log/pods/ (überlebt auch das Löschen des Containers), das von RKE2 gerenderte Static-Pod-Manifest und das Journal von rke2-server, das auf den API-Server wartet.

Ursache: kube-apiserver bricht beim Parsen seiner Flags ab: unrecognized feature gate: DebugBuchGate. Das Kubelet startet den Static Pod immer wieder neu (ATTEMPT steigt). Ohne API-Server stehen Controller, Scheduler und kubectl still – die laufenden Pods arbeiten aber weiter.

Fix: RKE2 schreibt das Manifest bei jedem Start neu, also reicht die Konfiguration:

# auf cp1
sudo rm /etc/rancher/rke2/config.yaml.d/90-kaputt.yaml
sudo rmdir /etc/rancher/rke2/config.yaml.d
sudo systemctl restart rke2-server

Nachweis:

# auf cp1
kubectl get --raw /readyz; echo
sudo -i crictl ps --name kube-apiserver | tr -s ' ' | cut -c1-88

Erwartet:

ok
CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID POD NAMESPACE
86397b7cb87e9 6d31c161dcb90 36 seconds ago Running kube-apiserver 0 85353367e72ff kube-a

Der Neustart von rke2-server dauert im Labor knapp eine Minute.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Das Zertifikat, das nach zehn Minuten abläuft

Einbauen: Die Benutzerin anna bekommt ein Client-Zertifikat über die Kubernetes-CA – mit der kürzesten erlaubten Laufzeit von 600 Sekunden:

# auf cp1
kubectl create namespace tag15
kubectl -n tag15 create configmap hallo --from-literal=gruss=moin
kubectl -n tag15 create rolebinding anna-view --clusterrole=view --user=anna
openssl genrsa -out anna.key 2048
openssl req -new -key anna.key -subj '/CN=anna' -out anna.csr
cat > anna-csr.yaml <<EOF
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata: {name: anna}
spec:
  request: $(base64 -w0 anna.csr)
  signerName: kubernetes.io/kube-apiserver-client
  expirationSeconds: 600
  usages: [client auth]
EOF
kubectl apply -f anna-csr.yaml
kubectl certificate approve anna
kubectl get csr anna

Erwartet (gekürzt):

namespace/tag15 created
configmap/hallo created
rolebinding.rbac.authorization.k8s.io/anna-view created
certificatesigningrequest.certificates.k8s.io/anna created
certificatesigningrequest.certificates.k8s.io/anna approved
NAME   AGE   SIGNERNAME                            REQUESTOR      REQUESTEDDURATION ...
anna   0s    kubernetes.io/kube-apiserver-client   system:admin   10m               ...

Diesmal steht EOF ohne Anführungszeichen: Die Shell soll $(base64 …) einsetzen. Aus dem Zertifikat wird eine eigene Kubeconfig:

# auf cp1
kubectl get csr anna -o jsonpath='{.status.certificate}' | base64 -d > anna.crt
kubectl config view --minify --raw \
  -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt
K=anna.kubeconfig
kubectl config set-cluster debug --server=https://127.0.0.1:6443 \
  --certificate-authority=ca.crt --embed-certs --kubeconfig=$K
kubectl config set-credentials anna --client-certificate=anna.crt \
  --client-key=anna.key --embed-certs --kubeconfig=$K
kubectl config set-context anna --cluster=debug --user=anna --namespace=tag15 \
  --kubeconfig=$K
kubectl config use-context anna --kubeconfig=$K
kubectl --kubeconfig=$K get configmaps

Erwartet:

Cluster "debug" set.
User "anna" set.
Context "anna" created.
Switched to context "anna".
NAME               DATA   AGE
hallo              1      4s
kube-root-ca.crt   1      4s

Symptom: Zehn Minuten später, an der Kubeconfig hat sich nichts geändert:

# auf cp1
sleep 600
kubectl --kubeconfig=anna.kubeconfig get configmaps

Erwartet:

error: You must be logged in to the server (Unauthorized)

Untersuchen: Unauthorized heißt: Der API-Server weiß nicht, wer du bist. Bei Client-Zertifikaten ist der erste Verdacht das Ablaufdatum:

# auf cp1
kubectl config view --kubeconfig=anna.kubeconfig --raw \
  -o jsonpath='{.users[0].user.client-certificate-data}' \
  | base64 -d | openssl x509 -noout -subject -enddate
date -u
kubectl -n kube-system logs kube-apiserver-cp1 --since=2m \
  | grep -m1 -o 'x509: certificate has expired[^,]*' | head -1 | fold -w 86

Erwartet:

subject=CN = anna
notAfter=Nov 20 14:51:26 2026 GMT
Fri Nov 20 14:51:29 UTC 2026
x509: certificate has expired or is not yet valid: current time 2026-11-20T14:51:28Z i
s after 2026-11-20T14:51:26Z

Ursache: Das Client-Zertifikat ist abgelaufen. Der API-Server weist es bei jeder Anfrage ab, sagt dem Client aber aus Sicherheitsgründen nur Unauthorized; den Grund schreibt er in sein eigenes Log, das du mit dem Admin-Zugang lesen kannst.

Fix: Ein neues Zertifikat über denselben Weg. Der alte CSR muss vorher weg, und die Laufzeit wird diesmal ein Tag – sonst stehst du in zehn Minuten wieder hier:

# auf cp1
kubectl delete csr anna
sed -i 's/expirationSeconds: 600/expirationSeconds: 86400/' anna-csr.yaml
kubectl apply -f anna-csr.yaml
kubectl certificate approve anna
kubectl get csr anna -o jsonpath='{.status.certificate}' | base64 -d > anna.crt
kubectl config set-credentials anna --client-certificate=anna.crt \
  --client-key=anna.key --embed-certs --kubeconfig=anna.kubeconfig

Erwartet:

certificatesigningrequest.certificates.k8s.io "anna" deleted
certificatesigningrequest.certificates.k8s.io/anna created
certificatesigningrequest.certificates.k8s.io/anna approved
User "anna" set.

Nachweis:

# auf cp1
openssl x509 -in anna.crt -noout -enddate
kubectl --kubeconfig=anna.kubeconfig get configmap hallo

Erwartet:

notAfter=Nov 21 14:46:30 2026 GMT
NAME    DATA   AGE
hallo   1      10m

Das neue Zertifikat gilt bis morgen; der Signer rechnet die Laufzeit ab fünf Minuten vor der Ausstellung, deshalb 14:46 statt 14:51.

Meldung beim Client Was falsch ist
Unauthorized dein Client-Zertifikat oder Token
x509: certificate has expired … Serving-Zertifikat des Servers oder deine Uhr
x509: … signed by unknown authority die CA in deiner Kubeconfig

Fortschritt speichern? Kostenlos registrieren

Drill 6: Wann laufen die Cluster-Zertifikate ab?

RKE2 führt seine eigenen Zertifikate selbst und zeigt sie mit einem Befehl:

# auf cp1
sudo -i rke2 certificate check --output json 2>/dev/null \
  | jq -r '.Certificates[] | select(.Usages[0] != "CertSign")
      | "\(.ExpiryTime) \(.Status) \(.Filename)"' | sort | head -4
sudo -i rke2 certificate check --output json 2>/dev/null \
  | jq -r '.Certificates[].Status' | sort | uniq -c

Erwartet:

2027-11-20T05:29:51Z OK client-admin.crt
2027-11-20T05:29:51Z OK client-auth-proxy.crt
2027-11-20T05:29:51Z OK client-controller.crt
2027-11-20T05:29:51Z OK client-kube-apiserver.crt
     34 OK

Leaf-Zertifikate gelten ein Jahr, die CAs zehn. RKE2 erneuert beim Start jedes Zertifikat, das in weniger als 120 Tagen abläuft. Von Hand: systemctl stop rke2-server, rke2 certificate rotate, systemctl start rke2-server – danach ist auch /etc/rancher/rke2/rke2.yaml neu. Kopierte Kubeconfigs funktionieren noch bis zum alten Ablaufdatum – dann neu kopieren.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Zeig nur die gescheiterten Prüfungen von /readyz. Zeitziel: 20 s
  2. Zeig alle etcd-Snapshots mit Namen. Zeitziel: 20 s
  3. Zeig Inhaber und Ablaufdatum des Client-Zertifikats in ~/.kube/config. Zeitziel: 45 s

Lösung

# auf cp1
kubectl get --raw '/readyz?verbose' | grep '^\[-\]'; echo "rc=$?"
sudo -i rke2 etcd-snapshot ls 2>/dev/null | awk '{print $1}'
kubectl config view --raw --minify \
  -o jsonpath='{.users[0].user.client-certificate-data}' \
  | base64 -d | openssl x509 -noout -subject -enddate

Erwartet:

rc=1
Name
nach-tag12-cp1-1795167810
vor-tag15-cp1-1795174399
etcd-snapshot-cp1-1795176005
tag15-start-cp1-1795185570
subject=O = system:masters, CN = system:admin
notAfter=Nov 20 05:29:51 2027 GMT

rc=1 heißt: grep hat keine Zeile mit [-] gefunden – alles grün. Die RKE2-Kubeconfig gehört system:admin in system:masters (Tag 11).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

# auf cp1
kubectl get --raw /readyz; echo
sudo ls /etc/rancher/rke2/

Erwartet:

ok
config.yaml  registries.yaml  rke2-pss.yaml  rke2.yaml

Kein config.yaml.d mehr – der kaputte Drop-in aus Drill 4 ist weg.

Challenge

Ein Kollege schickt dir seine Kubeconfig fremd.kubeconfig mit der Bitte: „Geht seit der Neuinstallation nicht mehr.“ Finde heraus, welches Zertifikat nicht passt, und repariere die Datei, ohne die Zugangsdaten anzufassen.

# auf cp1
cp anna.kubeconfig fremd.kubeconfig
openssl req -x509 -newkey rsa:2048 -nodes -keyout fremd-ca.key -out fremd-ca.crt \
  -days 1 -subj '/CN=fremde-ca' 2>/dev/null
kubectl config set-cluster debug --certificate-authority=fremd-ca.crt --embed-certs \
  --kubeconfig=fremd.kubeconfig

Hinweis: Vergleiche die CA in der Datei mit dem Aussteller des Zertifikats, das der API-Server ausliefert.

Lösung

# auf cp1
kubectl --kubeconfig=fremd.kubeconfig get configmaps 2>&1 | fold -w 86
kubectl config view --kubeconfig=fremd.kubeconfig --raw \
  -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' \
  | base64 -d | openssl x509 -noout -subject
echo | openssl s_client -connect 127.0.0.1:6443 2>/dev/null \
  | openssl x509 -noout -issuer
kubectl config set-cluster debug --certificate-authority=ca.crt --embed-certs \
  --kubeconfig=fremd.kubeconfig
kubectl --kubeconfig=fremd.kubeconfig get configmap hallo

Erwartet:

Unable to connect to the server: tls: failed to verify certificate: x509: certificate
signed by unknown authority
subject=CN = fremde-ca
issuer=CN = rke2-server-ca@1795156191
Cluster "debug" set.
NAME    DATA   AGE
hallo   1      21m

AGE hängt davon ab, wie lange du seit Drill 5 gebraucht hast – Annas Zertifikat gilt jetzt einen Tag. Die Kubeconfig vertraut fremde-ca, der API-Server zeigt ein Zertifikat von rke2-server-ca@…. Nach einer Neuinstallation hat der Cluster eine neue CA – alte Kubeconfigs scheitern dann genau so. Die Zugangsdaten (users) bleiben unberührt; nur clusters[].certificate-authority-data wird ersetzt.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

Die Snapshots bleiben liegen – sie sind dein Rückweg für die nächsten Tage.

# auf cp1
kubectl delete csr anna
kubectl delete namespace tag15
rm -f anna.key fremd-ca.key anna.kubeconfig fremd.kubeconfig
kubectl get csr

Erwartet:

certificatesigningrequest.certificates.k8s.io "anna" deleted
namespace "tag15" deleted
No resources found

Interview-Notiz

  • API-Server antwortet nicht – was nun? Auf den Control-Plane-Knoten: crictl ps -a --name kube-apiserver, crictl logs, /var/log/pods, Journal des Dienstes; die Ursache steht fast immer in der letzten Zeile des Container-Logs.
  • Was machst du vor einem Eingriff an der Control Plane? etcd prüfen (endpoint health, alarm list) und einen Snapshot ziehen; den Restore-Weg kennen, bevor man ihn braucht.
  • Unauthorized vs. x509? Unauthorized: der Server lehnt dein Client-Zertifikat/Token ab. x509 beim Client: du vertraust dem Server nicht (CA, Ablauf, Uhr).

Enterprise-Notiz

  • Drei oder fünf etcd-Mitglieder, Snapshots zusätzlich nach S3 (etcd-s3 in RKE2); ein Snapshot auf demselben Knoten hilft nicht, wenn die Platte stirbt.
  • Den Restore regelmäßig üben – auf einer Kopie, nicht im Betrieb.
  • Zertifikatsablauf überwachen (apiserver_client_certificate_expiration_seconds, rke2 certificate check per Cron); Menschen bekommen kurzlebige Zugänge über OIDC statt Client-Zertifikate.
  • Änderungen an config.yaml erst auf einem Server testen, dann der Reihe nach ausrollen – nie alle Control-Plane-Knoten gleichzeitig.
  • Für Talos laufen dieselben Fragen über talosctl etcd, talosctl logs und kubernetesdynamiccerts (Tag 18 und 19).