Dépannage : Diagnostic rapide des erreurs courantes de conteneurs Docker

Les conteneurs Docker sont conçus pour être résilients, mais les échecs au démarrage font inévitablement partie du cycle de vie du développement. Lorsqu'un conteneur se termine soudainement, comprendre rapidement la cause première est primordial pour maintenir la vélocité de déploiement. Ces échecs sont souvent cryptiques, marqués uniquement par un code de sortie non nul.

Ce guide propose des méthodologies de dépannage expertes utilisant la boîte à outils de commandes Docker essentielle. Nous parcourrons un processus de diagnostic structuré, en exploitant docker ps, docker logs, et docker inspect pour identifier et résoudre rapidement les problèmes de démarrage de conteneur les plus fréquents, vous permettant ainsi de dépasser les suppositions et d'appliquer des correctifs exploitables.

Phase 1 : Triage initial et évaluation de l'état

La première étape pour diagnostiquer toute défaillance de conteneur consiste à déterminer son état actuel et récent. La commande docker ps par défaut n'affiche que les conteneurs en cours d'exécution, ce qui est peu utile lorsqu'un conteneur s'est terminé immédiatement au démarrage.

Utilisation de `docker ps -a` pour trouver les échecs

La commande cruciale pour le triage initial est docker ps -a (lister tous les conteneurs, en cours d'exécution ou arrêtés). Cela vous permet de visualiser le statut, le code de sortie et l'ancienneté du conteneur arrêté.

$ docker ps -a
ID DU CONTENEUR   IMAGE          COMMANDE                CRÉÉ il y a          STATUT                    PORTS     NOMS
2d3f4b5c6e7a   my-app:latest  "/usr/bin/start.sh"    5 minutes ago    Exited (127) 3 minutes ago          web-service
d8c9a0b1c2d3   nginx:latest   "nginx -g 'daemon..."  10 minutes ago   Up 8 minutes              80/tcp    active-proxy

Indicateurs de statut clés :

Exited (0) : Le conteneur s'est arrêté gracieusement et intentionnellement (souvent après la fin d'un job batch). Le diagnostic est généralement minimal.
Exited (Non-Zéro) : Une défaillance s'est produite. Les codes non nuls courants (1, 126, 127) indiquent des problèmes graves, tels qu'un processus en crash, un fichier introuvable ou des erreurs de permission.
Created : Le conteneur a été créé mais n'a jamais démarré, ou le démarrage a échoué trop rapidement pour que le statut soit mis à jour.

Phase 2 : Plongée en profondeur avec les journaux du conteneur

Une fois que vous avez l'ID ou le nom du conteneur, l'outil le plus précieux pour le diagnostic est le mécanisme de journalisation. Docker capture les flux de sortie standard (stdout) et d'erreur standard (stderr) du processus principal du conteneur.

Récupération des journaux historiques

Utilisez la commande docker logs pour récupérer toute la sortie capturée du conteneur défaillant. Cette sortie contient souvent le message d'erreur précis (par exemple, trace de pile, erreur de configuration ou avertissement de fichier manquant) qui a provoqué l'arrêt du conteneur.

# Récupérer les journaux pour le conteneur défaillant
$ docker logs web-service

# --- Exemple de sortie de journal ---
Standardizing environment...
Error: Configuration file not found at /etc/app/config.json
Application initialization failed. Exiting.

Conseils avancés pour le filtrage des journaux :

Option de commande	Objectif	Exemple
`-f, --follow`	Diffuser les journaux en temps réel (utile si le conteneur démarre et plante rapidement).	`docker logs -f web-service`
`--tail N`	Afficher seulement les N dernières lignes de journaux.	`docker logs --tail 50 web-service`
`-t, --timestamps`	Afficher les horodatages pour chaque entrée de journal (utile pour corréler les événements).	`docker logs -t web-service`
`--since`	Afficher les journaux générés après une heure ou une durée spécifique (par exemple, `1h`, `15m`).	`docker logs --since 15m web-service`

Meilleure pratique : Vérifiez toujours les journaux immédiatement après une défaillance. Si les journaux sont vides, la défaillance s'est produite avant que le processus d'application principal ne puisse démarrer, indiquant souvent un problème avec la configuration ENTRYPOINT ou CMD de Docker elle-même.

Phase 3 : Analyse de l'état et de la configuration avec `docker inspect`

Lorsque les journaux sont insuffisants (par exemple, affichant une erreur générique ou rien du tout), vous devez analyser la configuration interne et l'environnement d'exécution du conteneur.

Revue de l'objet d'état complet

docker inspect fournit un objet JSON complet détaillant tout sur le conteneur, des paramètres réseau aux limites de ressources, et surtout, l'état final et le message d'erreur.

$ docker inspect web-service

Concentrez-vous sur les chemins JSON clés suivants dans la sortie :

1. Informations sur l'état

Cette section contient les informations détaillées sur la sortie, y compris l'heure de la défaillance et tout message d'erreur au niveau du système (si applicable).

...
"State": {
    "Status": "exited",
    "Running": false,
    "Paused": false,
    "Restarting": false,
    "OOMKilled": false, 
    "Dead": false,
    "Pid": 0,
    "ExitCode": 127,
    "Error": "", // Souvent vide, mais peut contenir des messages au niveau du noyau
    "StartedAt": "2023-10-26T14:30:00.123456789Z",
    "FinishedAt": "2023-10-26T14:30:00.223456789Z"
},
...

2. Point d'entrée et commande

Si le conteneur s'est terminé avec le code 127 (commande introuvable) ou 126 (commande non exécutable), vérifiez le Path et les Args dans les sections Config ou State pour vous assurer que le processus principal est correctement spécifié et que le chemin existe dans l'image.

...
"Config": {
    "Entrypoint": [
        "/usr/bin/start.sh"
    ],
    "Cmd": [
        "--mode=production"
    ],
...

3. Montages et volumes

Si l'application a échoué en raison de fichiers manquants ou d'erreurs de permission, vérifiez la section Mounts pour confirmer que les volumes hôtes ont été correctement mappés, sont accessibles et possèdent les permissions nécessaires.

Phase 4 : Scénarios de défaillance de démarrage courants et résolutions

En combinant les journaux et les données d'inspection, vous pouvez catégoriser la défaillance et appliquer un correctif ciblé.

Scénario 1 : Port déjà alloué (Erreur de liaison)

Cela se produit lorsque le port hôte que vous essayez de mapper (-p 8080:80) est déjà utilisé par un autre processus (soit un autre conteneur, soit un processus s'exécutant sur la machine hôte).

Diagnostic : Le conteneur échoue souvent à démarrer immédiatement, ou les journaux affichent une erreur telle que bind: address already in use.

Résolution :
1. Arrêtez le processus ou le conteneur en conflit.
2. Modifiez le mappage de port hôte (par exemple, -p 8081:80).

Scénario 2 : Commande introuvable (Code de sortie 127)

Cela signifie que le runtime Docker n'a pas pu exécuter la commande spécifiée dans la directive ENTRYPOINT ou CMD.

Diagnostic : Vérifiez docker logs (qui peuvent être vides) et examinez la section Config à l'aide de docker inspect.

Résolution :
1. Assurez-vous que le chemin de l'exécutable est correct (par exemple, /usr/local/bin/app, pas seulement app).
2. Vérifiez que l'exécutable existe dans l'image. Vous devrez peut-être exécuter un conteneur de débogage temporaire pour examiner le système de fichiers de l'image :

# Exécutez temporairement l'image, en remplaçant la commande défaillante
$ docker run -it --entrypoint /bin/bash my-app:latest
# Maintenant, à l'intérieur du conteneur, vérifiez : ls -l /usr/bin/start.sh

Scénario 3 : Permission refusée (Code de sortie 126 ou erreurs de volume)

Se produit généralement lorsque l'utilisateur du conteneur manque de permission pour accéder à un fichier, un répertoire ou un point de montage de volume requis.

Diagnostic : Les journaux affichent des erreurs telles que Permission denied ou cannot open file.

Résolution :
1. Permissions du volume : Si vous utilisez des montages hôtes (-v /host/data:/container/data), assurez-vous que le dossier hôte a les permissions de lecture/écriture pour l'ID utilisateur sous lequel le conteneur s'exécute (souvent UID 1000 ou root).
2. Permissions du point d'entrée : Assurez-vous que le script spécifié dans ENTRYPOINT a le drapeau exécutable défini dans le Dockerfile (RUN chmod +x /path/to/script).

Scénario 4 : Mémoire insuffisante (OOMKilled)

Il s'agit d'une défaillance au niveau du système où le noyau termine le processus principal du conteneur en raison d'une consommation excessive de mémoire.

Diagnostic : Vérifiez docker ps -a pour STATUS Exited (137) ou exécutez docker inspect [id] et recherchez le champ "OOMKilled": true dans l'objet State.

Résolution :
1. Augmentez la limite de mémoire du conteneur à l'aide du drapeau -m (par exemple, --memory 2g).
2. Optimisez l'application pour réduire l'utilisation de la mémoire.

Résumé et prochaines étapes

Un dépannage Docker efficace repose sur une approche structurée : commencez par docker ps -a pour évaluer la défaillance, utilisez docker logs comme principal outil d'investigation, et réservez docker inspect pour les problèmes de configuration et d'environnement plus approfondis. En comprenant la signification des codes de sortie et en sachant où chercher dans l'état du conteneur, vous pouvez réduire considérablement le temps passé à résoudre les échecs de démarrage courants.

Actions supplémentaires :

Si le problème concerne l'image, reconstruisez l'image en incluant des étapes de débogage temporaires (par exemple, l'impression des variables d'environnement) dans le Dockerfile.
Si les journaux sont rares, basculez temporairement l'initialisation du conteneur sur bash ou sh pour naviguer manuellement dans le système de fichiers et tester les commandes dans l'environnement.