Résoudre les 10 erreurs de déploiement Kubernetes les plus fréquentes

Les erreurs de déploiement Kubernetes représentent le quotidien de tout ingénieur infrastructure. CrashLoopBackOff, ImagePullBackOff, OOMKilled : ces messages d'erreur bloquent les mises en production. Avec 82% des utilisateurs de conteneurs exécutant Kubernetes en production, maîtriser le dépannage distingue l'administrateur système efficace du débutant.

TL;DR : La majorité des erreurs de déploiement proviennent de 3 causes : images introuvables, ressources insuffisantes, ou configuration incorrecte. Utilisez kubectl describe et kubectl logs comme premiers réflexes.

Cette compétence est essentielle pour les ingénieurs opérations Cloud Kubernetes préparant leurs certifications.

Pourquoi maîtriser les erreurs déploiement Kubernetes solutions ?

Erreur	Fréquence	Temps moyen résolution
ImagePullBackOff	Très fréquente	5-15 min
CrashLoopBackOff	Fréquente	15-60 min
OOMKilled	Fréquente	10-30 min
Pending	Fréquente	5-30 min
CreateContainerConfigError	Moyenne	10-20 min

À retenir : 80% des erreurs de déploiement se résolvent avec kubectl describe pod suivi de kubectl logs. Maîtrisez ces deux commandes.

Pour plus de tutoriels, consultez notre hub Tutoriels et guides pratiques Kubernetes.

Erreur 1 : ImagePullBackOff et ErrImagePull

Symptôme

kubectl get pods
NAME         READY   STATUS             RESTARTS   AGE
api-server   0/1     ImagePullBackOff   0          5m

Diagnostic

kubectl describe pod api-server | grep -A 10 Events

Causes possibles :

Image inexistante ou tag incorrect
Registry privé sans credentials
Limite de pull Docker Hub atteinte

Solutions erreurs déploiement Kubernetes solutions pour ImagePullBackOff

Image incorrecte : vérifiez le nom et le tag

# Vérifier que l'image existe
docker pull registry.example.com/api:v1.2.3

# Corriger le deployment
kubectl set image deployment/api-server api=registry.example.com/api:v1.2.3

Registry privé : créez un imagePullSecret

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass \
  --docker-email=user@example.com

spec:
  imagePullSecrets:
  - name: regcred
  containers:
  - name: api
    image: registry.example.com/api:v1.2.3

Pour les bonnes pratiques de manifestes, consultez notre guide Bonnes pratiques pour structurer vos manifestes YAML.

Erreur 2 : CrashLoopBackOff

Symptôme

kubectl get pods
NAME         READY   STATUS             RESTARTS   AGE
api-server   0/1     CrashLoopBackOff   5          10m

Diagnostic

# Logs du conteneur en crash
kubectl logs api-server --previous

# Events détaillés
kubectl describe pod api-server

Solutions

Application qui crash au démarrage :

# Vérifier les logs
kubectl logs api-server --previous

# Exemple de sortie
Error: Cannot connect to database at db.example.com:5432

Liveness probe mal configurée :

# Probe trop agressive
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 3  # Trop court si l'app met 30s à démarrer
  periodSeconds: 3
  failureThreshold: 1

# Configuration correcte
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30  # Laisser le temps au démarrage
  periodSeconds: 10
  failureThreshold: 3

À retenir : Le CrashLoopBackOff indique que le conteneur démarre puis s'arrête. Les logs --previous montrent ce qui s'est passé avant le crash.

Pour un guide dédié, consultez Debugger un pod en CrashLoopBackOff.

Erreur 3 : OOMKilled (Out of Memory)

Symptôme

kubectl get pods
NAME         READY   STATUS    RESTARTS   AGE
api-server   0/1     OOMKilled 3          15m

Diagnostic

kubectl describe pod api-server | grep -A 5 "Last State"

Solutions erreurs déploiement Kubernetes solutions pour OOMKilled

Augmenter les limits mémoire :

resources:
  requests:
    memory: "256Mi"
  limits:
    memory: "512Mi"  # Était 256Mi, augmenté à 512Mi

Identifier les fuites mémoire :

# Surveiller la consommation
kubectl top pod api-server --containers

# Profiler l'application
kubectl exec -it api-server -- jcmd 1 VM.native_memory summary

Selon ScaleOps, 65%+ des workloads tournent à moins de la moitié de leurs ressources allouées. Le rightsizing évite les OOMKilled tout en optimisant les coûts.

Erreur 4 : Pod stuck en Pending

Symptôme

kubectl get pods
NAME         READY   STATUS    RESTARTS   AGE
api-server   0/1     Pending   0          20m

Diagnostic

kubectl describe pod api-server | grep -A 10 Events

Messages typiques :

Insufficient cpu / Insufficient memory
0/3 nodes are available: 3 node(s) had taints that the pod didn't tolerate
pod has unbound immediate PersistentVolumeClaims

Solutions

Ressources insuffisantes :

# Vérifier les ressources disponibles
kubectl describe nodes | grep -A 5 "Allocated resources"

# Réduire les requests ou ajouter des nœuds

Taints non tolérées :

spec:
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "api"
    effect: "NoSchedule"

PVC non lié :

kubectl get pvc
kubectl describe pvc data-volume

Pour comparer les outils de développement local, consultez Minikube vs Kind vs K3s.

Erreur 5 : CreateContainerConfigError

Symptôme

kubectl get pods
NAME         READY   STATUS                       RESTARTS   AGE
api-server   0/1     CreateContainerConfigError   0          5m

Diagnostic

kubectl describe pod api-server | grep -A 10 Events

Solutions

Secret ou ConfigMap manquant :

# Vérifier que le secret existe
kubectl get secret db-credentials
kubectl get configmap app-config

# Créer le secret manquant
kubectl create secret generic db-credentials \
  --from-literal=username=admin \
  --from-literal=password=secret

Clé inexistante dans ConfigMap :

# Erreur : la clé DATABASE_URL n'existe pas
env:
- name: DB_URL
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: DATABASE_URL  # Vérifiez que cette clé existe

À retenir : CreateContainerConfigError signifie presque toujours un Secret ou ConfigMap absent ou mal référencé.

Erreur 6 : Service non accessible

Symptôme

curl http://api-service:8080
curl: (7) Failed to connect to api-service port 8080

Diagnostic

# Vérifier le service
kubectl get svc api-service
kubectl describe svc api-service

# Vérifier les endpoints
kubectl get endpoints api-service

Solutions erreurs déploiement Kubernetes solutions pour Services

Pas d'endpoints :

kubectl get endpoints api-service
NAME          ENDPOINTS   AGE
api-service   <none>      10m

Le sélecteur ne correspond à aucun pod :

# Service
spec:
  selector:
    app: api-server  # Doit matcher les labels des pods

# Pod
metadata:
  labels:
    app: api-server  # Vérifiez que c'est identique

Port incorrect :

# Service expose le port 80, mais le pod écoute sur 8080
spec:
  ports:
  - port: 80
    targetPort: 8080  # Doit correspondre au containerPort

Pour la formation administrateur système, consultez notre page dédiée formation Kubernetes administrateur système.

Erreur 7 : FailedScheduling avec PodAffinity

Symptôme

kubectl describe pod api-server
Events:
  Warning  FailedScheduling  0/3 nodes are available: 3 node(s) didn't match pod affinity rules

Diagnostic

kubectl get pods -o wide --show-labels
kubectl get nodes --show-labels

Solutions

Affinity trop stricte :

# Utiliser preferredDuringScheduling au lieu de required
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: api-server
        topologyKey: kubernetes.io/hostname

Pour le déploiement en production, consultez notre hub Déploiement et mise en production Kubernetes.

Erreur 8 : Readiness probe failed

Symptôme

kubectl get pods
NAME         READY   STATUS    RESTARTS   AGE
api-server   0/1     Running   0          5m

Le pod est Running mais pas Ready (0/1).

Diagnostic

kubectl describe pod api-server | grep -A 15 Readiness

Solutions

Endpoint de santé incorrect :

readinessProbe:
  httpGet:
    path: /healthz  # Vérifiez que ce path existe
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

Dépendance non disponible :

# L'application attend une base de données
kubectl logs api-server | grep -i "connection"

À retenir : Un pod Running mais pas Ready ne reçoit pas de trafic. La readinessProbe protège les utilisateurs des instances non fonctionnelles.

Erreur 9 : Volume mount failed

Symptôme

kubectl describe pod api-server
Warning  FailedMount  Unable to mount volumes: timeout expired waiting for volumes

Diagnostic

kubectl get pv
kubectl get pvc
kubectl describe pvc data-volume

Solutions

PVC non provisionné :

# Vérifier la StorageClass
kubectl get sc

# Créer un PVC avec la bonne StorageClass
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-volume
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: standard
  resources:
    requests:
      storage: 10Gi
EOF

Pour la migration depuis Docker Compose, consultez Migrer de Docker Compose à Kubernetes.

Erreur 10 : NetworkPolicy blocking traffic

Symptôme

kubectl exec -it client-pod -- curl http://api-service:8080
curl: (7) Failed to connect

Mais le service et les endpoints sont corrects.

Diagnostic

kubectl get networkpolicy -A
kubectl describe networkpolicy -n default

Solutions

Ajouter une règle d'ingress :

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-api-access
  namespace: default
spec:
  podSelector:
    matchLabels:
      app: api-server
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: client
    ports:
    - protocol: TCP
      port: 8080

Pour la sécurité des workloads, consultez Sécuriser vos workloads Kubernetes.

Checklist de diagnostic rapide

# 1. État du pod
kubectl get pod <pod-name> -o wide

# 2. Events
kubectl describe pod <pod-name> | tail -20

# 3. Logs
kubectl logs <pod-name> --previous

# 4. État du conteneur
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].state}'

# 5. Ressources du nœud
kubectl describe node <node-name> | grep -A 10 "Allocated"

À retenir : Cette séquence de 5 commandes résout 90% des problèmes de déploiement. Mémorisez-la.

Passez à l'action : maîtrisez le dépannage Kubernetes

Le dépannage représente une compétence clé de l'examen CKA. Selon la Linux Foundation, l'examen dure 2 heures avec un score de passage de 66%. Les questions pratiques de troubleshooting comptent pour une part significative du score.

Formez-vous avec SFEIR pour acquérir ces réflexes :

La formation LFS458 Administration Kubernetes inclut des labs de dépannage sur 4 jours
La formation Kubernetes les fondamentaux pose les bases pour comprendre les erreurs
La formation LFD459 pour développeurs aborde le debugging applicatif

Contactez nos conseillers pour organiser une formation adaptée aux besoins de votre équipe.

Points clés

Pourquoi maîtriser les erreurs déploiement Kubernetes solutions ?

Erreur 1 : ImagePullBackOff et ErrImagePull

Symptôme

Diagnostic

Solutions erreurs déploiement Kubernetes solutions pour ImagePullBackOff

Erreur 2 : CrashLoopBackOff

Symptôme

Diagnostic

Solutions

Erreur 3 : OOMKilled (Out of Memory)

Symptôme

Diagnostic

Solutions erreurs déploiement Kubernetes solutions pour OOMKilled

Erreur 4 : Pod stuck en Pending

Symptôme

Diagnostic

Solutions

Erreur 5 : CreateContainerConfigError

Symptôme

Diagnostic

Solutions

Erreur 6 : Service non accessible

Symptôme

Diagnostic

Solutions erreurs déploiement Kubernetes solutions pour Services

Erreur 7 : FailedScheduling avec PodAffinity

Symptôme

Diagnostic

Solutions

Erreur 8 : Readiness probe failed

Symptôme

Diagnostic

Solutions

Erreur 9 : Volume mount failed

Symptôme

Diagnostic

Solutions

Erreur 10 : NetworkPolicy blocking traffic

Symptôme

Diagnostic

Solutions

Checklist de diagnostic rapide

Passez à l'action : maîtrisez le dépannage Kubernetes