Troubleshooting Kubernetes

Le troubleshooting représente 30% de l’examen CKA. Ce guide présente une méthodologie systématique pour diagnostiquer et résoudre les problèmes les plus courants : Pods en échec, problèmes de scheduling, erreurs réseau, et défaillances de cluster.

CKA — Troubleshooting (30%)

Le domaine “Troubleshooting” est le plus important de la CKA. Maîtrisez les commandes de diagnostic et la méthodologie de cette page.

Méthodologie générale

Appliquez cette approche systématique pour tout problème Kubernetes :

1. Observer — Quel est l’état actuel ? (kubectl get, kubectl describe)
2. Logs — Que disent les logs ? (kubectl logs, journald)
3. Events — Quels événements récents ? (kubectl get events)
4. Comparer — L’état actuel correspond-il à l’état désiré ?
5. Isoler — Quel composant est en cause ?
6. Corriger — Appliquer le fix et valider

---

Commandes essentielles

# Alias recommandés
alias k=kubectl
alias kd='kubectl describe'
alias kl='kubectl logs'
alias kg='kubectl get'

# Vue d'ensemble rapide
kubectl get all -A
kubectl get events -A --sort-by='.lastTimestamp' | tail -20

# État des nœuds
kubectl get nodes -o wide
kubectl top nodes

# État des Pods
kubectl get pods -A -o wide | grep -v Running

---

Section 1 — Troubleshooting Pods

États des Pods et leur signification

État	Signification	Action
Pending	En attente de scheduling	Vérifier ressources, affinités, taints
ContainerCreating	Image en cours de pull ou volumes montés	Vérifier events, image, PVC
Running	Conteneur actif	Vérifier readiness, logs si problème
CrashLoopBackOff	Redémarre en boucle	Vérifier logs, commande, ressources
Error	Conteneur terminé avec erreur	Vérifier logs du conteneur
ImagePullBackOff	Échec de téléchargement image	Vérifier nom image, credentials
ErrImagePull	Erreur initiale de pull	Vérifier registry, réseau
Terminating	En cours de suppression	Vérifier finalizers, preStop hooks

Glissez pour voir

Pod Pending

Un Pod reste Pending quand le scheduler ne trouve pas de nœud approprié.

# Diagnostic
kubectl describe pod <pod-name> | grep -A10 Events

# Messages courants et solutions
# "Insufficient cpu" → Augmenter ressources cluster ou réduire requests
# "Insufficient memory" → Idem
# "node(s) had untolerated taint" → Ajouter toleration ou retirer taint
# "node(s) didn't match Pod's node affinity" → Vérifier labels des nœuds
# "persistentvolumeclaim not found" → Créer le PVC manquant

Checklist Pending :

# Ressources disponibles sur les nœuds
kubectl describe nodes | grep -A5 "Allocated resources"

# Taints des nœuds
kubectl get nodes -o custom-columns='NAME:.metadata.name,TAINTS:.spec.taints[*].key'

# PVC en attente
kubectl get pvc -A | grep -v Bound

Pod CrashLoopBackOff

Le conteneur démarre mais crash immédiatement, Kubernetes le redémarre en boucle.

# Logs du crash actuel
kubectl logs <pod-name>

# Logs du crash précédent
kubectl logs <pod-name> --previous

# Si multi-container
kubectl logs <pod-name> -c <container-name> --previous

Causes fréquentes :

Cause	Diagnostic	Solution
Command/Args invalides	Logs montrent erreur de syntaxe	Corriger command/args
Config manquante	”file not found”, “env not set”	Vérifier ConfigMaps/Secrets
Dépendance indisponible	”connection refused”	Vérifier Services dépendants
OOMKilled	kubectl describe pod → OOMKilled	Augmenter memory limit
Permissions	”permission denied”	Vérifier securityContext, volumes

Glissez pour voir

# Vérifier si OOMKilled
kubectl get pod <pod> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.reason}'

# Détail du restart
kubectl describe pod <pod> | grep -A5 "Last State"

Pod ImagePullBackOff

Kubernetes ne parvient pas à télécharger l’image.

# Diagnostic
kubectl describe pod <pod> | grep -A5 "Events"

# Causes fréquentes :
# - Image inexistante : vérifier le nom exact
# - Registry privé : vérifier imagePullSecrets
# - Réseau : vérifier l'accès au registry depuis les nœuds

Vérifier les credentials :

# Lister les secrets de type docker-registry
kubectl get secrets -A -o json | jq -r '.items[] | select(.type=="kubernetes.io/dockerconfigjson") | "\(.metadata.namespace)/\(.metadata.name)"'

# Vérifier qu'un Pod utilise le bon secret
kubectl get pod <pod> -o jsonpath='{.spec.imagePullSecrets}'

Debug avec ephemeral containers

Depuis Kubernetes 1.25+, vous pouvez injecter un conteneur de debug dans un Pod running :

# Ajouter un conteneur de debug
kubectl debug -it <pod-name> --image=busybox:1.36 --target=<container-name>

# Debug avec une copie du Pod
kubectl debug <pod-name> -it --copy-to=debug-pod --container=debug --image=busybox:1.36

---

Section 2 — Troubleshooting Nodes

États des nœuds

# Vue d'ensemble
kubectl get nodes -o wide

# Détail d'un nœud
kubectl describe node <node-name>

# Conditions importantes
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .status.conditions[*]}{.type}={.status}{" "}{end}{"\n"}{end}'

Conditions des nœuds

Condition	True = problème	Diagnostic
MemoryPressure	⚠️	Mémoire insuffisante
DiskPressure	⚠️	Disque plein
PIDPressure	⚠️	Trop de processus
NetworkUnavailable	⚠️	CNI non configuré
Ready	✅ Normal	Nœud opérationnel

Glissez pour voir

Node NotReady

# Diagnostic rapide
kubectl describe node <node> | grep -A5 Conditions

# Vérifier kubelet sur le nœud
ssh <node> "systemctl status kubelet"
ssh <node> "journalctl -u kubelet --since '10 minutes ago' | tail -50"

# Vérifier les certificats
ssh <node> "openssl x509 -in /var/lib/kubelet/pki/kubelet.crt -noout -dates"

Causes fréquentes :

Symptôme	Cause probable	Solution
kubelet stopped	Service crashé	systemctl restart kubelet
certificate expired	Certificats expirés	Renouveler avec kubeadm
connection refused	API server inaccessible	Vérifier réseau, firewall
disk full	/var/lib/kubelet plein	Nettoyer images/logs

Glissez pour voir

Ressources insuffisantes

# Voir l'utilisation CPU/mémoire
kubectl top nodes

# Détail par nœud
kubectl describe node <node> | grep -A10 "Allocated resources"

# Pods sur un nœud spécifique
kubectl get pods -A --field-selector spec.nodeName=<node> -o wide

---

Section 3 — Troubleshooting Services et Networking

Service ne route pas vers les Pods

1. Vérifier que le Service existe et a des endpoints

   kubectl get svc <service>
   kubectl get endpoints <service>

2. Vérifier que les labels correspondent

   # Labels du selector du Service
   kubectl get svc <service> -o jsonpath='{.spec.selector}'
   
   # Labels des Pods
   kubectl get pods -l <label-selector> --show-labels

3. Vérifier que les Pods sont Ready

   kubectl get pods -l <label-selector>
   # Un Pod non-Ready n'apparaît pas dans les endpoints

4. Tester la connectivité depuis un Pod

   kubectl run debug --rm -it --image=busybox:1.36 -- wget -qO- --timeout=2 <service>:<port>

Endpoints vides

# Diagnostic
kubectl get endpoints <service>
# Si ENDPOINTS est <none> :

# 1. Vérifier le selector du Service
kubectl get svc <service> -o yaml | grep -A5 selector

# 2. Vérifier que des Pods matchent ce selector
kubectl get pods -l <key>=<value>

# 3. Vérifier que ces Pods sont Ready
kubectl get pods -l <key>=<value> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}'

DNS ne résout pas

# Tester la résolution DNS depuis un Pod
kubectl run dnstest --rm -it --image=busybox:1.36 -- nslookup kubernetes.default

# Vérifier que CoreDNS fonctionne
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns

# Vérifier la configuration DNS d'un Pod
kubectl exec <pod> -- cat /etc/resolv.conf

NetworkPolicy bloque le trafic

# Lister les NetworkPolicies
kubectl get netpol -A

# Détail d'une policy
kubectl describe netpol <name>

# Test de connectivité
kubectl run tester --rm -it --image=nicolaka/netshoot -- curl -v <target>:<port>

Effet deny-all

Une NetworkPolicy avec podSelector: {} sans règle ingress/egress bloque tout le trafic pour les Pods du namespace.

---

Section 4 — Troubleshooting Control Plane

API Server non accessible

# Depuis un nœud control plane
kubectl cluster-info

# Vérifier les composants
kubectl get componentstatuses  # Déprécié mais encore utile
kubectl get pods -n kube-system | grep -E 'api|controller|scheduler|etcd'

# Logs API server
kubectl logs -n kube-system kube-apiserver-<node>
# Ou sur le nœud :
journalctl -u kubelet | grep apiserver

etcd en échec

# État des Pods etcd
kubectl get pods -n kube-system -l component=etcd

# Logs etcd
kubectl logs -n kube-system etcd-<node>

# Santé du cluster etcd (depuis un control plane)
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint health

Scheduler ou Controller Manager

# Pods kube-system
kubectl get pods -n kube-system | grep -E 'scheduler|controller'

# Logs
kubectl logs -n kube-system kube-scheduler-<node>
kubectl logs -n kube-system kube-controller-manager-<node>

# Vérifier les manifests statiques
ls -la /etc/kubernetes/manifests/

---

Section 5 — Troubleshooting Applications

Liveness/Readiness probe failures

# Voir les events
kubectl describe pod <pod> | grep -A10 Events

# Messages courants :
# "Liveness probe failed" → L'app ne répond pas, Pod sera redémarré
# "Readiness probe failed" → L'app n'est pas prête, retirée des endpoints

Checklist probes :

# Tester manuellement l'endpoint de probe
kubectl exec <pod> -- wget -qO- http://localhost:<port>/<path>
kubectl exec <pod> -- curl -s http://localhost:<port>/<path>

# Vérifier la configuration des probes
kubectl get pod <pod> -o jsonpath='{.spec.containers[0].livenessProbe}'
kubectl get pod <pod> -o jsonpath='{.spec.containers[0].readinessProbe}'

Application lente ou timeout

# Ressources utilisées vs limites
kubectl top pod <pod>
kubectl get pod <pod> -o jsonpath='{.spec.containers[0].resources}'

# Throttling CPU (si limite trop basse)
kubectl exec <pod> -- cat /sys/fs/cgroup/cpu/cpu.cfs_throttled_periods

# Logs applicatifs
kubectl logs <pod> --tail=100 -f

---

Section 6 — Exercices CKA Troubleshooting

Exercice 1 : Pod bloqué Pending (3 min)

Un Pod stuck-pod est Pending depuis 5 minutes. Identifiez la cause et corrigez.

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: stuck-pod
spec:
  nodeSelector:
    disktype: nvme
  containers:
  - name: nginx
    image: nginx:1.25
EOF

Solution

# Diagnostic
kubectl describe pod stuck-pod | grep -A10 Events
# "0/X nodes are available: X node(s) didn't match Pod's node affinity"

# Vérifier les labels des nœuds
kubectl get nodes --show-labels | grep disktype
# Aucun nœud n'a le label disktype=nvme

# Solution A : Labelliser un nœud
kubectl label node <node-name> disktype=nvme

# Solution B : Retirer le nodeSelector
kubectl patch pod stuck-pod --type='json' -p='[{"op": "remove", "path": "/spec/nodeSelector"}]'
# Note : Patch de nodeSelector sur un Pod existant ne fonctionne pas, il faut recréer

# Solution pratique : Supprimer et recréer sans nodeSelector
kubectl delete pod stuck-pod
kubectl run stuck-pod --image=nginx:1.25

Exercice 2 : CrashLoopBackOff (4 min)

Diagnostiquez pourquoi ce Pod crash en boucle :

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: crash-pod
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ['sh', '-c', 'cat /config/app.conf && sleep 3600']
EOF

Solution

# Diagnostic
kubectl describe pod crash-pod
kubectl logs crash-pod --previous
# "cat: can't open '/config/app.conf': No such file or directory"

# Le fichier /config/app.conf n'existe pas

# Solution : Créer un ConfigMap et le monter
kubectl create configmap app-config --from-literal=app.conf="key=value"

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: crash-pod-fixed
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ['sh', '-c', 'cat /config/app.conf && sleep 3600']
    volumeMounts:
    - name: config
      mountPath: /config
  volumes:
  - name: config
    configMap:
      name: app-config
EOF

kubectl delete pod crash-pod

Exercice 3 : Service sans endpoints (4 min)

Le Service web-svc ne route pas vers les Pods. Trouvez pourquoi.

kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: webapp  # Attention ici
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
---
apiVersion: v1
kind: Service
metadata:
  name: web-svc
spec:
  selector:
    app: web
  ports:
  - port: 80
EOF

Solution

# Diagnostic
kubectl get endpoints web-svc
# ENDPOINTS: <none>

kubectl get svc web-svc -o jsonpath='{.spec.selector}'
# {"app":"web"}

kubectl get pods --show-labels
# app=webapp (pas app=web)

# Le selector du Service (app=web) ne matche pas les labels des Pods (app=webapp)

# Solution : Corriger les labels du Deployment
kubectl patch deployment web -p '{"spec":{"template":{"metadata":{"labels":{"app":"web"}}}}}'

# Vérifier
kubectl get endpoints web-svc
# Maintenant les endpoints apparaissent

Exercice 4 : Node NotReady (5 min)

Simulez et diagnostiquez un nœud NotReady.

Solution (concept)

# Sur le nœud worker (SSH)
sudo systemctl stop kubelet

# Sur le control plane, observer
kubectl get nodes
# Le nœud passe NotReady après ~40 secondes (node-monitor-grace-period)

kubectl describe node <worker> | grep -A5 Conditions
# Ready: False - Kubelet stopped posting node status

# Diagnostic
ssh <worker> "systemctl status kubelet"
# inactive (dead)

# Solution
ssh <worker> "sudo systemctl start kubelet"

kubectl get nodes
# Ready

---

Checklist récapitulative

Pod qui ne démarre pas

kubectl get pod <name>                          # État actuel
kubectl describe pod <name> | tail -30          # Events
kubectl logs <name> --previous                  # Logs du crash précédent
kubectl get events --field-selector involvedObject.name=<name>

Service non fonctionnel

kubectl get svc <name>                          # Ports, ClusterIP
kubectl get endpoints <name>                    # Pods backend
kubectl get pods -l <selector> -o wide          # État des Pods
kubectl run test --rm -it --image=busybox -- wget -qO- <svc>:<port>

Nœud en échec

kubectl describe node <name> | grep -A10 Conditions
ssh <node> "systemctl status kubelet"
ssh <node> "journalctl -u kubelet --since '10 min ago'"
ssh <node> "df -h; free -m"                     # Ressources système

---

À retenir

1. Toujours commencer par kubectl describe et kubectl get events
2. Pod Pending = problème de scheduling (ressources, taints, affinités)
3. CrashLoopBackOff = regarder kubectl logs --previous
4. Service sans endpoints = vérifier que selector matche les labels des Pods Ready
5. Node NotReady = vérifier kubelet et ses logs
6. DNS = tester depuis un Pod avec nslookup/dig
7. NetworkPolicy = peut bloquer silencieusement le trafic

---

Prochaines étapes

Scheduling avancé Contrôler le placement des Pods

Debug d'applications Techniques de debugging avancées

Exercices CKA Entraînement format examen

Network Policies Sécurisation du réseau

×

📖 Voir la documentation →