Cette section aborde les techniques et commandes courantes pour diagnostiquer et résoudre les problèmes dans un cluster Kubernetes.
Les problèmes au niveau du cluster peuvent se manifester de diverses manières : nœuds non prêts, API Server inaccessible, pods non schedulés, etc.
1. Vérifier l'accessibilité de l'API Server et la configuration kubeconfig:
La première étape est souvent de vérifier si kubectl peut communiquer avec l'API Server. Une erreur courante est :
kubectl get nodes
The connection to the server <host>:<port> was refused - did you specify the right host or port?
Causes possibles :
kube-apiserver) n'est pas en cours d'exécution sur le(s) nœud(s) master.kubeconfig (souvent ~/.kube/config) pointe vers une mauvaise adresse ou un mauvais port, ou les certificats/tokens sont invalides.Actions : Vérifiez la configuration
kubeconfig. Si vous êtes sur un nœud master, vérifiez le statut du servicekube-apiserver(s'il est géré par systemd) ou le Pod statiquekube-apiserverdans/etc/kubernetes/manifestset ses logs (docker logs <container_id>oucrictl logs <container_id>si vous utilisez containerd/CRI-O, ou viakubectl logs -n kube-system kube-apiserver-<nodename>si le pod miroir existe et quekubectlfonctionne partiellement).
2. Vérifier l'état des Nœuds :
kubectl get nodes -o wide
Regardez la colonne STATUS. Un nœud doit être Ready pour accepter des Pods. S'il est NotReady ou Unknown:
NotReady : Le nœud est joignable mais le Kubelet rencontre un problème (CRI down, CNI non prêt, manque de ressources, etc.).Unknown : Le control plane n'arrive pas à joindre le Kubelet de ce nœud (probablement un problème réseau ou le Kubelet est arrêté).3. Décrire le Nœud problématique :
kubectl describe node <nom-du-noeud-problematique>
Analysez attentivement les sections :
Conditions : Donne l'état détaillé (Ready, MemoryPressure, DiskPressure, PIDPressure, NetworkUnavailable). Regardez les messages associés à chaque condition False ou Unknown.Events : Liste les événements récents liés au nœud, qui peuvent indiquer la cause du problème (ex: erreurs de CNI, problèmes de ressources).System Info : Vérifiez si les versions (Kubelet, OS, CRI) sont cohérentes.Allocatable / Capacity : Pour détecter d'éventuels problèmes de ressources.4. Vérifier les Services Critiques sur le Nœud :
Connectez-vous au nœud concerné (via SSH par exemple) et vérifiez le statut des services essentiels :
# Vérifier le Kubelet
systemctl status kubelet
journalctl -u kubelet -n 50 --no-pager # Voir les 50 derniers logs
# Vérifier le Container Runtime Interface (CRI)
systemctl status docker # Si Docker est utilisé
systemctl status containerd # Si containerd est utilisé
journalctl -u docker -n 50 --no-pager
journalctl -u containerd -n 50 --no-pager
Redémarrez les services si nécessaire (systemctl restart <service>).
5. Vérifier les Pods du Control Plane (kube-system) :
Les composants du control plane (API Server, Scheduler, Controller Manager, etcd, CoreDNS, CNI, Kube-proxy) tournent souvent comme des Pods (statiques ou non) dans le namespace kube-system. Des problèmes avec ces Pods peuvent paralyser le cluster.
# Lister les pods dans kube-system
kubectl get pods -n kube-system -o wide
# Regarder les pods non 'Running' ou avec des 'RESTARTS' élevés
# Décrire un pod problématique
kubectl describe pod <nom-pod-problematique> -n kube-system
# Consulter les logs d'un pod problématique
kubectl logs <nom-pod-problematique> -n kube-system
# Si le pod a redémarré, voir les logs précédents
kubectl logs <nom-pod-problematique> -n kube-system -p
Faites particulièrement attention à etcd (si visible), kube-apiserver, kube-scheduler, kube-controller-manager, coredns, et les pods de votre plugin CNI (ex: calico-node, flannel).
6. Consulter les Logs des Composants :
Si les composants tournent comme des services systemd (moins courant avec kubeadm), leurs logs sont dans journalctl (voir étape 4).
S'ils tournent comme des Pods statiques, leurs logs peuvent être dans /var/log/pods sur le nœud master, ou accessibles via docker logs/crictl logs du container correspondant sur le nœud master. Les logs de l'API Server, du Scheduler et du Controller Manager sont souvent très verbeux mais peuvent contenir des indices cruciaux.
# Exemple pour voir les logs de l'api-server (si pod statique)
kubectl logs -n kube-system kube-apiserver-<nom-noeud-master>
Lorsqu'une application déployée via un Pod, Deployment, StatefulSet, etc. ne fonctionne pas comme prévu.
1. Vérifier l'état du Pod :
kubectl get pods -n <namespace> -o wide
Regardez la colonne STATUS. Statuts courants indiquant un problème :
Pending : Le Pod n'a pas encore été schedulé sur un nœud ou est en train de télécharger une image. Causes : ressources insuffisantes, taints non tolérés, affinité/anti-affinité non satisfaite, PVC non lié (Pending).CrashLoopBackOff : Le container démarre, crashe immédiatement, et Kubernetes essaie de le redémarrer en boucle avec un délai croissant. C'est un problème applicatif ou de configuration dans le container.ImagePullBackOff / ErrImagePull : Kubernetes n'arrive pas à télécharger l'image Docker spécifiée. Causes : nom d'image incorrect, tag inexistant, problème de registre (privé sans credentials, etc.), problème réseau sur le nœud.CreateContainerConfigError : Problème lors de la création de la configuration du container. Souvent lié à un Secret ou une ConfigMap manquant(e) référencé(e) dans la spec du Pod (ex: envFrom, volumeMount).RunContainerError : Erreur lors du démarrage du container lui-même (après la création de la config).Terminating : Le Pod est en cours d'arrêt mais est bloqué (ex: finalizer, problème de stockage).Failed : Le Pod (souvent un Job ou avec restartPolicy: Never/OnFailure) s'est terminé avec un code d'erreur non nul.2. Décrire le Pod :
C'est souvent l'étape la plus informative.
kubectl describe pod <nom-du-pod> -n <namespace>
Analysez :
Status : Confirme le statut vu dans get pods.Reason / Message : Peuvent donner une indication plus précise (ex: pour Pending, ça peut indiquer Unschedulable).Containers > State / Last State : Indique l'état actuel et précédent du/des container(s). Pour CrashLoopBackOff, Last State montrera souvent Terminated avec un Reason: Error et un Exit Code non nul.Events : La section la plus importante ! Elle liste chronologiquement les événements liés au cycle de vie du Pod : scheduling, pull d'image, création/démarrage de container, échecs de sondes (liveness/readiness), etc. Les messages d'erreur ici sont cruciaux.3. Consulter les Logs du Container :
Indispensable pour les problèmes applicatifs (CrashLoopBackOff, comportement inattendu).
# Voir les logs actuels du container par défaut
kubectl logs <nom-du-pod> -n <namespace>
# Si plusieurs containers, spécifier le container
kubectl logs <nom-du-pod> -c <nom-du-container> -n <namespace>
# Suivre les logs en temps réel
kubectl logs -f <nom-du-pod> -c <nom-du-container> -n <namespace>
# Voir les logs du container précédent (après un crash/redémarrage)
kubectl logs -p <nom-du-pod> -c <nom-du-container> -n <namespace>
# Voir les N dernières lignes
kubectl logs --tail=50 <nom-du-pod> -c <nom-du-container> -n <namespace>
4. Exécuter une commande dans le Container (exec) :
Si le Pod est Running mais ne fonctionne pas correctement, on peut obtenir un shell ou exécuter des commandes de diagnostic à l'intérieur.
# Obtenir un shell interactif dans le container (si l'image contient sh/bash)
kubectl exec -it <nom-du-pod> -c <nom-du-container> -n <namespace> -- /bin/sh # ou /bin/bash
# Exécuter une commande spécifique
kubectl exec <nom-du-pod> -c <nom-du-container> -n <namespace> -- ps aux
kubectl exec <nom-du-pod> -c <nom-du-container> -n <namespace> -- curl localhost:<port-app>
Attention :
kubectl execnécessite que le container soit en cours d'exécution. Ça ne fonctionne pas pour les PodsPending,CrashLoopBackOff(sauf très brièvement), ouFailed.
5. Vérifier les Probes (Liveness/Readiness/Startup) :
Des probes mal configurées peuvent causer des redémarrages inutiles (Liveness) ou empêcher un Pod de recevoir du trafic (Readiness). Vérifiez les Events dans kubectl describe pod pour des messages comme Liveness probe failed ou Readiness probe failed. Testez la commande/URL de la probe manuellement depuis le Pod (kubectl exec) ou depuis un autre Pod si possible.
Les problèmes réseau peuvent être complexes. Voici quelques pistes :
1. Vérifier le DNS :
# Depuis un pod de test (ex: busybox)
nslookup <nom-service>.<namespace>.svc.cluster.local
nslookup <nom-service> # Devrait fonctionner si dans le même namespace
nslookup www.google.com
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system <pod-coredns-xxxx>
/etc/resolv.conf à l'intérieur d'un Pod (kubectl exec <pod> -- cat /etc/resolv.conf). Il doit pointer vers l'IP du Service kube-dns.2. Vérifier les Services et Endpoints :
kubectl get svc <nom-service> -n <namespace>)kubectl get endpoints <nom-service> -n <namespace>
# Ou pour les versions récentes, utiliser EndpointSlice
kubectl get endpointslice -l kubernetes.io/service-name=<nom-service> -n <namespace>
ENDPOINTS est vide ou <none>, vérifiez le selector du Service et les labels des Pods cibles. Vérifiez aussi que les Pods cibles sont Running et Ready (la readiness probe réussit).targetPort du Service correspond-il au port où l'application écoute dans les Pods ?3. Vérifier kube-proxy :
Ce composant tourne sur chaque nœud et configure les règles (iptables/IPVS) pour router le trafic des Services vers les Pods. Vérifiez qu'il tourne (souvent un DaemonSet dans kube-system). Consultez ses logs.
4. Vérifier les Network Policies :
kubectl get networkpolicy -n <namespace>
kubectl describe networkpolicy <nom-policy> -n <namespace>
5. Utiliser des Outils de Diagnostic Réseau :
Lancer un Pod avec des outils réseau comme netshoot pour tester la connectivité depuis l'intérieur du cluster.
apiVersion: v1
kind: Pod
metadata:
name: netshoot-debug
namespace: default
spec:
containers:
- name: netshoot
image: nicolaka/netshoot # Contient curl, ping, dig, netstat, etc.
command: ["sleep", "infinity"]
Appliquer, puis utiliser kubectl exec :
kubectl exec -it netshoot-debug -- bash
# Depuis ce shell :
# ping <ip-autre-pod>
# curl <nom-service>:<port>
# dig <nom-service>.<namespace>.svc.cluster.local @<ip-coredns>
Pending (Unschedulable) :
kubectl describe pod <pod-pending> montrera souvent des messages indiquant un manque de CPU, de mémoire, ou des conflits de taints/tolerations/affinity.kubectl top node.requests du Pod et les ressources allocatable des nœuds.OOMKilled (Out Of Memory Killed) :
limit de mémoire.kubectl describe pod <pod> montrera Terminated avec Reason: OOMKilled dans Last State.limit de mémoire ou optimisez la consommation mémoire de l'application.limit (s'il en a une) ou sature ses requests si le nœud est chargé.kubectl top pod <pod> --containers.requests/limits ou optimisez l'application.Ce guide couvre les scénarios de dépannage les plus courants pour la CKA. La clé est d'utiliser kubectl describe et kubectl logs de manière méthodique pour isoler la cause première du problème.