Kubernetes troubleshooting avec des exemples pratiques : guide d'implémentation concret

Introduction

Les pannes Kubernetes peuvent être bruyantes et déroutantes sous pression. Ce guide vous propose un workflow pratique, orienté sécurité avant tout, avec des exemples concrets, des commandes précises à exécuter et des corrections ciblées que vous pouvez valider rapidement. Vous apprendrez à :

• Délimiter l'impact et trouver vite le composant fautif
• Lire les events, les Kubernetes logs de pods et de nœuds, et les champs de statut
• Classer la panne et mener des vérifications de cause racine ciblées
• Appliquer des remédiations sûres et valider le résultat
• Répéter ces gestes en local avant toute action en production

Outils connexes présents dans les exemples : Docker (images et registries), Helm (releases), GitLab CI/CD, Nginx (Services/Ingress), Ceph (StorageClasses), et Prometheus (métriques).

Vue d'ensemble du workflow

Suivez ce parcours de bout en bout. Chaque étape privilégie l'inspection en lecture seule avant toute modification.

1. Délimiter et localiser le problème

• Confirmer le contexte et l'espace de noms :

  kubectl config current-context
  kubectl get ns
  kubectl get pods -A -o wide

• Identifier la charge et le composant en défaut (pod, deployment, statefulset, daemonset, job, cronjob, service, ingress).

1. Collecter des signaux rapides (lecture seule)

• Santé globale :

  kubectl get nodes -o wide
  kubectl get pods -A --field-selector=status.phase!=Running
  kubectl get deploy, sts, ds -A

• Les events racontent l'histoire dans l'ordre :

  kubectl get events -A --sort-by=.metadata.creationTimestamp

• Describe ajoute le contexte de décision du scheduler et des contrôleurs :

  kubectl -n <ns> describe pod <pod>

• Logs de la tentative courante et précédente :

  kubectl -n <ns> logs <pod> -c <container> --tail=200
  kubectl -n <ns> logs <pod> -c <container> --previous --tail=200

• Câblage Service et Endpoints :

  kubectl -n <ns> get svc, ep
  kubectl -n <ns> describe svc <name>

• Signaux de stockage :

  kubectl -n <ns> get pvc
  kubectl -n <ns> describe pvc <pvc>
  kubectl get storageclass

• Pressions du nœud et kubelet :

  kubectl describe node <node>
  # Si vous avez un accès SSH nœud
  sudo journalctl -u kubelet -n 200 --no-pager

1. Classer la panne rapidement

Statuts courants de pod et indices associés :

• Pending : le scheduler ne peut pas placer le pod (ressources, nodeSelector, taints/tolerations, affinity, PVC en Pending)
• ContainerCreating : latence de pull d'image, montages de volumes, init CNI, montages secrets/configs
• ImagePullBackOff : référence d'image ou credentials invalides
• CrashLoopBackOff : l'application échoue de façon répétée au démarrage
• OOMKilled : limite mémoire trop basse ou fuites
• RunContainerError : problème d'entrypoint ou de permissions
• 0/1 ready (ou équivalent) : readiness probe en échec
• NodeNotReady : santé du nœud, réseau, kubelet ou cloud

Vérifications de cause racine et remédiations sûres

Ci-dessous, des playbooks ciblés avec commandes à faible risque en premier.

A. ImagePullBackOff

Checks :

• Les events et describe exposent l'erreur du registry. Vérifiez la chaîne d'image.

  kubectl -n <ns> describe pod <pod> | sed -n '/Events/,$p'

• Confirmez l'existence de l'image et du tag. Si privé, vérifiez les imagePullSecrets du service account ou du pod.

  kubectl -n <ns> get sa <sa> -o yaml
  kubectl -n <ns> get secret

Fixes :

• Corriger le nom ou le tag dans le Deployment/StatefulSet, puis lancer le rollout :

  kubectl -n <ns> set image deploy/<name> <container>=<repo>/<image>:<tag>
  kubectl -n <ns> rollout status deploy/<name>

• Ajouter ou corriger le secret du registry :

  kubectl -n <ns> create secret docker-registry regcred \
    --docker-server=<registry> --docker-username=<user> \
    --docker-password=<pass> --docker-email=<email>
  # Référencez-le dans spec.imagePullSecrets

B. CrashLoopBackOff

Checks :

• Récupérer les logs précédents pour capturer la raison du crash :

  kubectl -n <ns> logs <pod> -c <container> --previous --tail=200

• Inspecter probes, command/args, env, volumes, workingDir et securityContext :

  kubectl -n <ns> get pod <pod> -o yaml

Causes/fixes typiques :

• Mauvaise configuration ou clé env/secret manquante : corriger la ConfigMap/Secret et redémarrer le rollout.

  kubectl -n <ns> rollout restart deploy/<name>
  kubectl -n <ns> rollout status deploy/<name>

• Démarrage lent de l'app : augmenter initialDelaySeconds ou les timeouts des probes.
• Entrypoint erroné : corriger command/args vers le binaire ou script attendu.

C. OOMKilled

Checks :

• Confirmer la raison de terminaison et l'usage mémoire :

  kubectl -n <ns> describe pod <pod> | grep -i -E 'oom|memory'
  kubectl top pod -n <ns> <pod>

Fixes :

• Augmenter la limite mémoire ou réduire l'usage. Ajuster requests à des besoins réalistes pour éviter évictions et churn de scheduling.
• Pour des pics, limiter heap/workers ou activer des limites côté application.

D. Pending (non planifiable)

Checks :

• Les events de scheduling disent pourquoi le pod n'est pas placé :

  kubectl -n <ns> describe pod <pod> | sed -n '/Events/,$p'
  kubectl get nodes

• Recherchez des requests au-delà des capacités, des tolerations manquantes, ou des selectors qui ne correspondent à aucun nœud.

Fixes :

• Réduire des requests démesurées et les caler sur l'usage réel.
• Assouplir selectors/labels ou les aligner.
• Ajouter un node pool compatible si la charge le nécessite réellement.

E. Readiness/Liveness probes en échec

Checks :

• Détails des probes dans describe et les logs :

  kubectl -n <ns> describe pod <pod>
  kubectl -n <ns> logs <pod> -c <container> --tail=200

• Exec : commande présente et exécutable. HTTP : chemin et port valides. TCP : port à l'écoute.

Fixes :

• Corriger chemin, port ou commande. Ajouter initialDelaySeconds pour cold starts. S'assurer que l'app écoute sur 0.0.0.0 et non 127.0.0.1.

F. Service sans endpoints (trou noir de trafic)

Checks :

• Comparer le selector du Service avec les labels des pods :

  kubectl -n <ns> get svc <name> -o yaml
  kubectl -n <ns> get pods -l <selector> -o wide --show-labels
  kubectl -n <ns> get ep <name> -o yaml

Fixes :

• Aligner labels et selectors. Avec Helm, s'assurer que les values rendent des labels cohérents côté Service et Deployment.

G. PVC Pending ou erreurs de montage

Checks :

• Les events du PVC montrent l'erreur du provisioner :

  kubectl -n <ns> describe pvc <pvc>
  kubectl get storageclass

• Vérifier accessModes et storageClassName (ex. RBD vs filesystem). Confirmer les quotas et la capacité.

Fixes :

• Définir le bon storageClassName. Aligner l'access mode avec la charge (ReadWriteOnce dans la plupart des cas). Demander une taille réaliste.
• Avec Ceph, s'assurer que la StorageClass existe et que le cluster peut provisionner.

H. DNS ou add-on DNS de cluster

Checks :

• Tester la résolution depuis un pod éphémère :

  kubectl -n <ns> run dnsutils --rm -it --image=busybox:1.36 -- nslookup kubernetes.default

• Inspecter CoreDNS et ses logs :

  kubectl -n kube-system get pods -l k8s-app=kube-dns
  kubectl -n kube-system logs deploy/coredns --tail=200

• Vérifier que les NetworkPolicies n'interdisent pas UDP/TCP 53 vers CoreDNS.

Fixes :

• Corriger le ConfigMap de CoreDNS si nécessaire. Assouplir les policies pour autoriser le DNS.

I. Node NotReady ou sous pression

Checks :

• Conditions et taints du nœud :

  kubectl describe node <node>

• Problèmes fréquents : DiskPressure, MemoryPressure, PIDPressure, agent réseau.

Fixes (ordre sûr) :

• Cordonner le nœud pour stopper le scheduling, puis drainer si besoin de déplacer des pods :

  kubectl cordon <node>
  kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

• Après remédiation, uncordon :

  kubectl uncordon <node>

Vérifier, puis revenir en arrière si besoin

• Suivre le rollout et la santé :

  kubectl -n <ns> rollout status deploy/<name>
  kubectl -n <ns> get pods, svc, ep
  kubectl -n <ns> get events --sort-by=.metadata.creationTimestamp | tail -n 20

• Si la modification n'aide pas, revenir en arrière rapidement :

  kubectl -n <ns> rollout undo deploy/<name>

• Avec Helm, privilégier un dry run avant les changements :

  helm -n <ns> upgrade <rel> <chart> --dry-run --values values.yaml

Mini playbooks pratiques

1. CrashLoopBackOff causé par une clé ConfigMap manquante

• Symptôme :

  kubectl -n app describe pod api-xyz | sed -n '/Events/,$p'
  kubectl -n app logs api-xyz -c api --previous --tail=200
  # montre : KeyError: MISSING_URL

• Fix : ajouter la clé manquante dans la ConfigMap ou corriger envFrom, puis redémarrer le rollout.

  kubectl -n app apply -f configmap.yaml
  kubectl -n app rollout restart deploy/api
  kubectl -n app rollout status deploy/api

1. Service sans endpoints à cause d'un label mismatch

• Symptôme :

  kubectl -n web get svc nginx
  kubectl -n web get ep nginx -o yaml  # subsets vides
  kubectl -n web get deploy nginx -o yaml | grep labels -n

• Fix : aligner le selector du Service avec les labels du pod template du Deployment, puis appliquer.

  kubectl -n web apply -f svc.yaml -f deploy.yaml
  kubectl -n web get ep nginx -o yaml  # endpoints désormais présents

1. PVC Pending avec StorageClass erronée

• Symptôme :

  kubectl -n data describe pvc db-data | sed -n '/Events/,$p'
  # ProvisioningFailed: storageclass "ceph-block" not found

• Fix : définir une StorageClass existante, par exemple "ceph-rbd" exposée par votre cluster, puis réappliquer.

  kubectl -n data apply -f pvc.yaml
  kubectl -n data get pvc db-data

1. ImagePullBackOff dû à l'absence de credentials

• Symptôme :

  kubectl -n ci describe pod runner-abc | sed -n '/Events/,$p'
  # error: unauthorized: authentication required

• Fix : créer un secret docker-registry et le référencer via imagePullSecrets.

  kubectl -n ci create secret docker-registry regcred \
    --docker-server=registry.example.com \
    --docker-username=ci-user --docker-password='$TOKEN' [email protected]
  kubectl -n ci patch sa default -p '{"imagePullSecrets":[{"name":"regcred"}]}'
  kubectl -n ci rollout restart deploy/runner

Plan pilote local

Entraînez-vous dans un cluster bac à sable pour observer chaque signal de bout en bout.

Scope

• Objectif : détecter, diagnostiquer, corriger et vérifier 4 pannes en moins de 30 minutes au total.
• Environnement : cluster local (par exemple kind ou minikube) et kubectl.

Setup

• Déployer une app simple (Deployment Nginx + Service ClusterIP + Ingress optionnel) et une petite API avec ConfigMap et Secret.
• Installer metrics-server si vous voulez utiliser kubectl top.

Exercices (induire, puis corriger)

1. Label mismatch

• Casse : modifier le selector du Service vers un label non correspondant.
• Détection : endpoints vides. Correction : aligner labels et selectors.

1. Readiness probe fail

• Casse : définir le chemin de readiness sur /bad.
• Détection : erreurs de probe dans describe. Correction : corriger le chemin et ajuster initialDelaySeconds.

1. ImagePullBackOff

• Casse : définir un tag d'image inexistant.
• Détection : events montrant une erreur de pull. Correction : corriger le tag ou ajouter un imagePullSecret.

1. PVC Pending

• Casse : demander une StorageClass inexistante.
• Détection : events du PVC avec ProvisioningFailed. Correction : définir une classe existante.

Mesure

• Pour chaque exercice, consigner : temps jusqu'au premier signal, cause racine, correctif appliqué, et sortie de la commande de vérification.
• Critères de succès : rollout status au vert et endpoints/pods sains après chaque correctif.

Sécurité

• Utiliser des commandes non destructives tant que la panne n'est pas comprise.
• Préférer rollout restarts et corrections de spec aux suppressions de pods. Si suppression, s'assurer qu'un contrôleur possède le pod pour qu'il soit recréé.

Conclusion

Vous disposez maintenant d'un workflow de Kubernetes troubleshooting progressif et de playbooks reproductibles pour les Kubernetes errors les plus courantes. Prochaines étapes :

• Transformer ce workflow en runbook d'équipe avec commandes prêtes à copier-coller
• Répéter chaque trimestre sur un bac à sable pour garder les bons réflexes
• Ajouter des pré-vérifications rapides dans vos pipelines GitLab CI/CD ou Helm (par exemple kubectl apply --dry-run=server, helm --dry-run) pour détecter tôt les incohérences de labels, probes et stockage
• Instrumenter avec Prometheus et des alertes pour readiness, pics de restarts et échecs de provisioning de PVC

Lors d'un incident, commencez par l'inspection en lecture seule, classez rapidement, appliquez la plus petite correction sûre, puis vérifiez. La constance l'emporte sur l'improvisation sous pression.