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
/readyzund/livezdes API-Servers beschreiben seinen Zustand selbst;[-]markiert die gescheiterte Prüfung.- Ist der API-Server weg, hilft kein
kubectl:crictl,journalctlund die Dateien unter/var/log/podsaufcp1funktionieren 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; echoErwartet:
[+]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 -lErwartet:
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-blockErwartet:
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-serverErwartet (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-88Erwartet (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-serverNachweis:
# auf cp1
kubectl get --raw /readyz; echo
sudo -i crictl ps --name kube-apiserver | tr -s ' ' | cut -c1-88Erwartet:
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 annaErwartet (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 configmapsErwartet:
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 configmapsErwartet:
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 86Erwartet:
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.kubeconfigErwartet:
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 halloErwartet:
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 -cErwartet:
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
- Zeig nur die gescheiterten Prüfungen von
/readyz. Zeitziel: 20 s - Zeig alle etcd-Snapshots mit Namen. Zeitziel: 20 s
- 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 -enddateErwartet:
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.kubeconfigHinweis: 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 halloErwartet:
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 csrErwartet:
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. Unauthorizedvs.x509?Unauthorized: der Server lehnt dein Client-Zertifikat/Token ab.x509beim Client: du vertraust dem Server nicht (CA, Ablauf, Uhr).
Enterprise-Notiz
- Drei oder fünf etcd-Mitglieder, Snapshots zusätzlich nach S3
(
etcd-s3in 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 checkper Cron); Menschen bekommen kurzlebige Zugänge über OIDC statt Client-Zertifikate. - Änderungen an
config.yamlerst 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 logsundkubernetesdynamiccerts(Tag 18 und 19).