Résoudre les erreurs courantes de déploiement sur Kubernetes

Résoudre les erreurs courantes de déploiement sur Kubernetes représente une compétence critique pour tout ingénieur opérations Cloud Kubernetes. Les équipes IT passent en moyenne 34 jours de travail par an à résoudre des problèmes Kubernetes selon Cloud Native Now.

Plus de 60% du temps de gestion des clusters est consacré au troubleshooting d'après Spectro Cloud. Ce guide vous donne les commandes exactes et les solutions éprouvées pour diagnostiquer et corriger CrashLoopBackOff, ImagePullBackOff et les autres erreurs fréquentes.

TL;DR : Les erreurs de déploiement Kubernetes suivent des patterns prévisibles. Ce guide couvre les 7 erreurs les plus fréquentes avec leurs commandes de diagnostic, causes racines et solutions. Maîtrisez kubectl describe, kubectl logs --previous et kubectl get events pour résoudre 90% des problèmes.

Pour maîtriser le debugging pods Kubernetes en conditions réelles, suivez la formation LFD459 Kubernetes pour les développeurs d'applications.

Index rapide des symptômes

À retenir : 82% des utilisateurs de conteneurs exécutent Kubernetes en production selon le CNCF Annual Survey 2025. Une maîtrise du troubleshooting est indispensable.

CrashLoopBackOff : le conteneur redémarre en boucle {#crashloopbackoff}

Le CrashLoopBackOff indique que votre conteneur démarre, crash, et Kubernetes tente de le relancer avec un backoff exponentiel. Ce statut représente 40% des tickets de support Kubernetes.

Symptôme

$ kubectl get pods
NAME           READY   STATUS             RESTARTS      AGE
api-server-1   0/1     CrashLoopBackOff   5 (2m ago)    10m

Étape 1 : Examiner les logs du conteneur crashé

# Logs de l'instance actuelle
kubectl logs api-server-1

# Logs de l'instance précédente (après crash)
kubectl logs api-server-1 --previous

# Suivre les logs en temps réel
kubectl logs api-server-1 -f

Étape 2 : Analyser les events du pod

kubectl describe pod api-server-1 | grep -A20 "Events:"

Causes et solutions

# Exemple de correction : ajout d'une variable manquante
spec:
  containers:
  - name: api
    env:
    - name: DATABASE_URL
      valueFrom:
        secretKeyRef:
          name: db-credentials
          key: url

ImagePullBackOff : image introuvable {#imagepullbackoff}

ImagePullBackOff signifie que Kubernetes ne peut pas télécharger l'image conteneur spécifiée. Ce problème survient lors de 25% des premiers déploiements.

Symptôme

$ kubectl get pods
NAME         READY   STATUS             RESTARTS   AGE
web-app-1    0/1     ImagePullBackOff   0          5m

Diagnostic

# Voir le message d'erreur exact
kubectl describe pod web-app-1 | grep -A5 "Events:"

# Vérifier le nom de l'image
kubectl get pod web-app-1 -o jsonpath='{.spec.containers[*].image}'

Causes et solutions

# Créer un secret pour registry privé
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass \
  --docker-email=user@example.com

# Référencer dans le pod
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets": [{"name": "regcred"}]}'

Pour approfondir ces techniques, consultez le guide de debugging avancé des pods et conteneurs.

Pending : pod non schedulé {#pending}

Un pod Pending n'a pas été assigné à un nœud par le scheduler. La cause est généralement un manque de ressources ou des contraintes impossibles à satisfaire.

Diagnostic

# Identifier la raison du pending
kubectl describe pod mon-pod | grep -A10 "Events:"

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

# Lister les taints des nœuds
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Causes et solutions

# Exemple : ajuster les requests pour éviter pending
resources:
  requests:
    memory: "128Mi"  # Réduire si trop élevé
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "500m"

À retenir : Configurez toujours des requests réalistes. Des requests surévaluées bloquent le scheduling même si le nœud a de la capacité réelle.

CreateContainerConfigError : problème de configuration {#createcontainerconfigerror}

CreateContainerConfigError indique une erreur dans la configuration du conteneur avant même son démarrage. Le problème vient souvent des Secrets ou ConfigMaps référencés.

Diagnostic

kubectl describe pod mon-pod | grep -A3 "Warning"

# Vérifier que le Secret existe
kubectl get secret mon-secret

# Vérifier que la clé existe dans le Secret
kubectl get secret mon-secret -o jsonpath='{.data}'

Causes et solutions

# Créer un secret manquant
kubectl create secret generic app-secret \
  --from-literal=API_KEY=abc123

# Vérifier les références dans le deployment
kubectl get deployment mon-app -o yaml | grep -A5 "secretKeyRef"

La gestion des ConfigMaps et Secrets est couverte en détail dans nos guides de développement applications Kubernetes.

OOMKilled : dépassement mémoire {#oomkilled}

OOMKilled signifie que le conteneur a dépassé sa limite mémoire et a été tué par le kernel Linux. C'est une protection pour éviter que le nœud entier devienne instable.

Diagnostic

# Voir la raison de terminaison
kubectl describe pod mon-pod | grep -A3 "Last State"

# Voir l'historique des restarts
kubectl get pod mon-pod -o jsonpath='{.status.containerStatuses[0].lastState}'

# Monitorer la consommation mémoire
kubectl top pod mon-pod

Solution

# Augmenter la limite mémoire
resources:
  requests:
    memory: "256Mi"
  limits:
    memory: "512Mi"  # Doubler si OOMKilled fréquent

# Analyser la consommation avant d'augmenter
kubectl exec mon-pod -- cat /sys/fs/cgroup/memory/memory.usage_in_bytes

À retenir : Ne jamais fixer limits.memory trop proche de requests.memory. Laissez une marge de 50% pour les pics.

Probes Liveness et Readiness : échecs silencieux {#probes-liveness-et-readiness}

Les probes défaillantes causent des comportements subtils. Liveness en échec tue le conteneur. Readiness en échec retire le pod du Service sans le tuer.

Diagnostic

# Voir les échecs de probes
kubectl describe pod mon-pod | grep -E "(Liveness|Readiness)"

# Tester manuellement l'endpoint
kubectl exec mon-pod -- curl -s localhost:8080/health
kubectl exec mon-pod -- wget -qO- localhost:8080/ready

Erreurs fréquentes

# Configuration robuste des probes
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

Eviction : pod expulsé du nœud {#eviction}

L'eviction survient quand un nœud manque de ressources critiques. Le kubelet expulse les pods pour protéger le nœud.

Diagnostic

# Voir les conditions du nœud
kubectl describe node mon-node | grep -A5 "Conditions:"

# Voir les pods evicted
kubectl get pods --field-selector=status.phase=Failed | grep Evicted

# Nettoyer les pods evicted
kubectl delete pods --field-selector=status.phase=Failed

Toolkit de diagnostic universel

# Commandes essentielles pour tout debugging
kubectl get pods -o wide                    # Vue étendue avec nœud
kubectl describe pod <pod>                  # Détails complets
kubectl logs <pod> --previous               # Logs du crash précédent
kubectl get events --sort-by=.lastTimestamp # Events récents
kubectl exec -it <pod> -- /bin/sh           # Shell dans le conteneur
kubectl top pods                            # Consommation ressources

Script de diagnostic rapide

#!/bin/bash
POD=$1
echo "=== Status ==="
kubectl get pod $POD -o wide
echo "=== Events ==="
kubectl describe pod $POD | grep -A15 "Events:"
echo "=== Logs (dernières 50 lignes) ==="
kubectl logs $POD --tail=50
echo "=== Previous logs ==="
kubectl logs $POD --previous --tail=20 2>/dev/null || echo "Pas de logs précédents"

Prévention : éviter les erreurs avant déploiement

Validez vos manifests avant de les appliquer. 70% des organisations utilisent Kubernetes avec Helm selon Orca Security 2025. Utilisez les outils de validation.

# Valider la syntaxe YAML
kubectl apply --dry-run=client -f deployment.yaml

# Valider côté serveur (détecte plus d'erreurs)
kubectl apply --dry-run=server -f deployment.yaml

# Avec Helm
helm template my-release ./chart | kubectl apply --dry-run=server -f -

Pour aller plus loin dans les bonnes pratiques, explorez les différences entre Helm et Kustomize et les patterns de développement cloud-native.

À retenir : Testez systématiquement avec --dry-run=server avant chaque déploiement en production. Cette commande détecte les erreurs de configuration que --dry-run=client manque.

Formations pour maîtriser le troubleshooting Kubernetes

Comme le souligne un CTO d'entreprise dans le State of Kubernetes 2025 de Spectro Cloud : "Just given the capabilities that exist with Kubernetes, and the company's desire to consume more AI tools, we will use Kubernetes more in future."

La formation Kubernetes les fondamentaux permet de découvrir les bases du debugging en 1 jour. Pour une maîtrise complète, la formation LFD459 Kubernetes pour les développeurs couvre le troubleshooting avancé en 3 jours et prépare à la certification CKAD. Les ingénieurs infrastructure préparant le CKA trouveront des techniques approfondies dans la formation LFS458 Administration Kubernetes. Pour approfondir, consultez notre formation Développement applications Kubernetes entreprise Le CTO pilotant la transformation Cloud-Native.

Consultez notre guide complet de formation Kubernetes pour identifier le parcours adapté à votre profil, ou découvrez la formation pour administrateurs système et les enjeux de sécurité Kubernetes.