Healthchecks Docker : surveillance, alertes et réponse aux incidents avec des commandes pratiques

Introduction

Les healthchecks Docker sont la première ligne de défense pour garantir la fiabilité des conteneurs en production. Un healthcheck bien défini indique à Docker si un conteneur est réellement fonctionnel, et pas seulement en cours d'exécution. Sans lui, un conteneur peut rester dans un état « up » alors que l'application à l'intérieur est morte pour le trafic entrant. Cet article vous montre comment définir des healthchecks, surveiller leur sortie, alerter sur les états non sains et récupérer des échecs courants, le tout avec des commandes pratiques et des exemples que vous pouvez exécuter dès aujourd'hui.

Ce guide s'adresse aux développeurs, ingénieurs DevOps et équipes de startups qui exécutent Docker en production ou en staging. Vous apprendrez à passer de « le conteneur est up » à « le service est vérifié sain » en utilisant les fonctionnalités intégrées de Docker et un peu de script. Chaque exemple est testé avec Docker Engine 24.0 et Docker Compose v2, qui sont à jour au début de 2025.

Nous couvrirons la vérification des versions et de l'environnement, la configuration sécurisée, la vérification et le diagnostic, les modes d'échec et une liste de contrôle opérationnelle. En cours de route, vous verrez de vraies commandes, des exemples de sortie et des étapes de récupération concrètes. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, éviter de coder en dur les secrets et vérifier chaque correction.

Inventaire des versions et de l'environnement

Avant d'ajouter ou de modifier un healthcheck, confirmez la version de Docker et le driver de stockage que vous utilisez. Exécutez :

docker version --format '{{.Server.Version}}'

Sortie attendue : 24.0.7 ou similaire. Si vous utilisez Docker Compose, vérifiez :

docker compose version

Sortie attendue : Docker Compose version v2.24.0. Ces deux commandes sont en lecture seule et sûres à exécuter sur n'importe quel hôte.

Ensuite, listez les conteneurs en cours d'exécution et leur état de santé actuel si défini :

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Exemple de sortie :

NAMES         STATUS                     PORTS
web           Up 10 minutes (healthy)   0.0.0.0:8080->80/tcp
db            Up 10 minutes (unhealthy) 5432/tcp

Remarquez les suffixes (healthy) et (unhealthy). Ils n'apparaissent que si l'image définit un healthcheck ou si vous en avez fourni un au moment de l'exécution. Si un conteneur n'a pas de healthcheck, Docker ne peut pas connaître son état interne.

Pour voir la configuration de santé complète d'un conteneur, utilisez docker inspect :

docker inspect --format '{{json .Config.Healthcheck}}' web

Exemple de sortie :

{"Test":["CMD-SHELL","curl -f http://localhost/ || exit 1"],"Interval":30000000000,"Timeout":5000000000,"Retries":3}

Cela montre la commande de healthcheck, l'intervalle (30 secondes), le délai d'attente (5 secondes) et le nombre de tentatives (3). Notez que Docker stocke les durées en nanosecondes, mais docker inspect avec --format les rend lisibles.

Si vous utilisez Compose, obtenez la santé au niveau du service avec :

docker compose ps

Exemple de sortie :

NAME                COMMAND                  SERVICE             STATUS              PORTS
project-web-1      "nginx -g 'daemon of…"   web                 running (healthy)   0.0.0.0:8080->80/tcp
project-db-1       "docker-entrypoint.s…"   db                  running (healthy)   5432/tcp

Persistance des données et healthchecks

Un healthcheck lit ou écrit souvent un fichier pour prouver que l'application est vivante. L'emplacement de ce fichier est important. Si le fichier est écrit dans la couche inscriptible du conteneur, il disparaît lorsque le conteneur est recréé. Utilisez toujours un volume nommé ou un montage bind pour l'état persistant.

Exemple d'extrait Compose avec un volume nommé :

services:
  app:
    image: myapp:1.0
    volumes:
      - app_data:/var/lib/app
volumes:
  app_data:

Pour tester la persistance localement, arrêtez le conteneur et recréez-le :

docker stop app_container
docker rm app_container
docker compose up -d app

Vérifiez ensuite que les données sont toujours présentes :

docker compose exec app ls /var/lib/app

Si le répertoire est vide, le conteneur d'origine écrivait probablement dans la couche inscriptible au lieu du volume.

Chemin de configuration sûr

L'ajout d'un healthcheck doit être un changement contrôlé. Commencez par écrire le healthcheck dans un fichier Compose ou Dockerfile, et non directement en ligne de commande, afin qu'il soit versionné et révisable.

Options de healthcheck

Un healthcheck peut être défini dans un Dockerfile :

FROM nginx:latest
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Ou dans un fichier Compose :

services:
  web:
    image: nginx:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

Paramètres clés :

• test : la commande à exécuter. Utilisez CMD pour la forme exec ou CMD-SHELL pour la forme shell.
• interval : la fréquence d'exécution du check (par défaut 30 s).
• timeout : temps maximum pour que le check se termine (par défaut 30 s).
• retries : échecs consécutifs nécessaires pour marquer comme non sain (par défaut 3).
• start_period : période de grâce avant que les checks ne comptent (par défaut 0 s). Utile pour les applications à démarrage lent.

Une bonne commande de healthcheck est légère et échoue rapidement. Évitez les opérations lourdes comme les migrations de base de données ou les appels API externes. Pour un service web, curl -f http://localhost/health est courant. Pour une base de données, utilisez un ping client :

db:
  image: postgres:16
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 10s
    timeout: 5s
    retries: 5

Pour un conteneur Redis :

redis:
  image: redis:7
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]
    interval: 10s
    timeout: 3s
    retries: 3

Protection des secrets dans les healthchecks

Ne codez jamais en dur les identifiants dans les commandes de healthcheck. Si votre healthcheck doit s'authentifier, utilisez des variables d'environnement ou des secrets Docker. Par exemple, un healthcheck de base de données avec un mot de passe :

db:
  image: postgres:16
  environment:
    POSTGRES_PASSWORD_FILE: /run/secrets/db_password
  secrets:
    - db_password
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres && PGPASSWORD=$(cat /run/secrets/db_password) psql -U postgres -c 'SELECT 1' >/dev/null 2>&1"]
secrets:
  db_password:
    file: ./db_password.txt

Le mot de passe est lu à partir d'un fichier secret au moment de l'exécution, jamais commité dans le contrôle de source.

Déploiement incrémental

Lorsque vous ajoutez un healthcheck à un service existant, envisagez de l'activer d'abord en staging, d'observer pendant quelques jours, puis de le promouvoir en production. Un healthcheck trop strict peut provoquer des redémarrages inutiles ou marquer des conteneurs sains comme non sains.

Une erreur courante est de définir un interval trop faible. Chaque exécution de healthcheck consomme du CPU et peut ajouter de la charge à l'application. Pour la plupart des services web, 10 à 30 secondes est raisonnable. Ajustez en fonction du temps de démarrage de l'application et des modèles de trafic.

Vérification et diagnostic

Une fois un healthcheck en place, vérifiez qu'il fonctionne comme prévu. Commencez par vérifier directement l'état de santé :

docker inspect --format '{{.State.Health.Status}}' web

Sortie attendue : healthy.

Pour voir l'historique des résultats de healthcheck :

docker inspect --format '{{json .State.Health}}' web | jq

Exemple de sortie :

{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "2025-03-25T10:00:00.123456789Z",
      "End": "2025-03-25T10:00:00.234567890Z",
      "ExitCode": 0,
      "Output": "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                 Dload  Upload   Total   Spent    Left  Speed\n\r  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r100  6154  100  6154    0     0  135k      0 --:--:-- --:--:-- --:--:--  135k\n"
    }
  ]
}

ExitCode 0 signifie succès. Non zéro signifie échec. Le champ Output peut aider à déboguer pourquoi un healthcheck échoue.

Si un conteneur est non sain, obtenez ses journaux :

docker logs --tail 50 unhealthy_container

Recherchez les erreurs d'application, les dépendances manquantes ou les conflits de port.

Débogage à l'intérieur du conteneur

Parfois, vous devez exécuter la commande de healthcheck manuellement à l'intérieur du conteneur pour voir sa sortie :

docker exec -it web sh
# à l'intérieur du conteneur
curl -f http://localhost/ || echo "healthcheck failed"

Si curl n'est pas installé, vous devrez peut-être utiliser wget ou la CLI de l'application. Certaines images sont minimales et n'incluent pas curl ; dans ce cas, envisagez de passer à une image de base différente ou d'utiliser un healthcheck qui repose sur des outils intégrés.

Pour les services Compose, utilisez :

docker compose exec web sh

Pour un conteneur de base de données, testez la connectivité :

docker exec db pg_isready -U postgres

Sortie attendue : postgres:5432 - accepting connections.

Healthcheck et politiques de redémarrage

Les healthchecks interagissent avec les politiques de redémarrage. Si un conteneur est unhealthy et a une politique de redémarrage comme unless-stopped, Docker ne le redémarre pas automatiquement simplement parce qu'il est non sain. Les redémarrages ne se produisent que lorsque le conteneur se termine. Cependant, certains orchestrateurs comme Docker Swarm peuvent remplacer les répliques non saines. Dans Docker autonome, vous avez besoin d'outils externes pour agir sur l'état non sain.

Un moyen simple de redémarrer les conteneurs non sains est une tâche cron ou un script de surveillance. Par exemple :

#!/bin/bash
# redémarre les conteneurs non sains chaque minute
for c in $(docker ps -q --filter "health=unhealthy"); do
  echo "Redémarrage de $c"
  docker restart $c
done

Attention : redémarrer aveuglément peut masquer des problèmes sous-jacents. Utilisez ceci comme solution temporaire pendant que vous corrigez la cause racine.

Modes d'échec et récupération

Les healthchecks peuvent échouer pour de nombreuses raisons. Comprendre les modes d'échec courants vous aide à réagir rapidement.

1. Commande de healthcheck introuvable

Si l'image ne contient pas l'outil utilisé dans le healthcheck, chaque check échoue. Par exemple, utiliser curl dans une image basée sur Alpine qui n'a pas curl installé.

Pourquoi cela arrive : La commande de healthcheck n'est pas présente dans le système de fichiers du conteneur.

Comment éviter : Utilisez des commandes disponibles dans l'image de base, ou installez l'outil requis dans le Dockerfile. Pour Alpine, utilisez wget ou busybox wget comme alternative.

Récupération : Mettez à jour le healthcheck pour utiliser une commande disponible ou installez l'outil.

2. Le healthcheck expire

Si le check prend plus de temps que timeout, il est considéré comme échoué.

Pourquoi cela arrive : La commande est trop lente, l'application est surchargée ou le réseau est lent.

Comment éviter : Définissez un délai raisonnable (5 à 10 secondes). Optimisez la commande de healthcheck pour qu'elle soit rapide.

Récupération : Augmentez temporairement le délai, mais recherchez pourquoi le check est lent.

3. Le healthcheck renvoie un mauvais code de sortie

Votre script de healthcheck peut sortir avec 0 même lorsque le service est en panne, ou vice versa.

Pourquoi cela arrive : La logique du script est défectueuse, par exemple, ne vérifie pas correctement le corps de la réponse ou vérifie seulement si le port est ouvert.

Comment éviter : Testez la commande de healthcheck manuellement pendant le développement. Assurez-vous qu'elle renvoie non zéro en cas d'échec.

Récupération : Corrigez le script pour refléter précisément la santé du service.

4. Conteneur marqué non sain car start_period non défini

Des checks qui échouent rapidement pendant le démarrage peuvent marquer le conteneur non sain avant que l'application ne soit prête.

Pourquoi cela arrive : Le healthcheck s'exécute avant que l'application ne finisse son initialisation.

Comment éviter : Définissez start_period pour couvrir le temps de démarrage attendu.

Récupération : Ajoutez ou augmentez start_period.

5. Le healthcheck provoque une charge CPU élevée

Si l'intervalle est trop court et la commande lourde, cela peut consommer des ressources importantes.

Pourquoi cela arrive : Le healthcheck s'exécute trop fréquemment ou fait des opérations coûteuses.

Comment éviter : Utilisez des checks légers, définissez l'intervalle à au moins 10 s et évitez les commandes shell complexes.

Récupération : Simplifiez le healthcheck et augmentez l'intervalle.

6. Le healthcheck interfère avec le comportement de l'application

Certains healthchecks effectuent des opérations d'écriture (par exemple, créer un fichier temporaire) qui peuvent affecter l'application.

Pourquoi cela arrive : La commande de healthcheck a des effets de bord.

Comment éviter : Utilisez des checks en lecture seule autant que possible.

Récupération : Changez pour un check en lecture seule.

Intégration de la surveillance et des alertes

Les healthchecks Docker seuls ne fournissent pas d'alertes. Vous devez les intégrer à un système de surveillance. Voici des exemples utilisant des scripts simples et des outils courants.

Surveillance de base avec les événements Docker

Docker émet des événements lorsque l'état de santé d'un conteneur change. Vous pouvez écouter ces événements :

docker events --filter event=health_status

Exemple de sortie :

2025-03-25T10:00:00.123456789Z container health_status: unhealthy 1234567890abcdef
2025-03-25T10:00:30.123456789Z container health_status: healthy 1234567890abcdef

Vous pouvez rediriger cela vers un script qui envoie des alertes via webhook ou e-mail.

Utilisation d'une tâche cron pour vérifier la santé et alerter

Une simple tâche cron peut vérifier la santé de tous les conteneurs et envoyer une notification si certains sont non sains :

#!/bin/bash
unhealthy=$(docker ps -q --filter "health=unhealthy")
if [ -n "$unhealthy" ]; then
  echo "Conteneurs non sains : $unhealthy" | mail -s "Alerte de santé Docker" [email protected]
fi

Planifiez-la chaque minute avec cron.

Intégration avec Prometheus et Alertmanager

Pour une surveillance plus robuste, utilisez cAdvisor ou le point de terminaison de métriques Prometheus de Docker. Le daemon Docker peut exposer des métriques sur 127.0.0.1:9323/metrics, y compris l'état de santé. Configurez Prometheus pour scraper et Alertmanager pour alerter.

Exemple de règle d'alerte Prometheus :

groups:
  - name: docker-health
    rules:
      - alert: ContainerUnhealthy
        expr: docker_container_health_status == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Le conteneur {{ $labels.name }} est non sain"

Cela nécessite que les métriques du daemon Docker soient activées et un exportateur Prometheus qui rapporte l'état de santé.

Tableaux de bord avec Grafana

Grafana peut visualiser l'état de santé des conteneurs au fil du temps en utilisant les données Prometheus. Créez un panneau montrant le nombre de conteneurs non sains par service.

Une requête simple de tableau de bord :

count(docker_container_health_status == 0) by (name)

Cela donne une vue en temps réel des conteneurs non sains.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et après le déploiement de conteneurs avec des healthchecks. Attribuez un responsable pour chaque élément (par exemple, le responsable DevOps) et planifiez une revue hebdomadaire de la configuration des healthchecks.

Chaque élément doit avoir une étape de récupération documentée en cas d'échec. Par exemple, si les healthchecks sont manquants, ajoutez-les au Dockerfile ou au fichier Compose et redéployez.

Pièges et erreurs courants

Au-delà des modes d'échec, voici des pièges que les équipes rencontrent souvent :

1. Ne pas définir de healthcheck du tout. De nombreux conteneurs fonctionnent sans healthchecks. Sans eux, Docker ne peut pas savoir si l'application est fonctionnelle.
2. Utiliser le même healthcheck pour différents services. Un healthcheck de serveur web ne fonctionne pas pour une base de données. Personnalisez par service.
3. Healthcheck qui dépend de l'accès réseau à des services externes. Si le healthcheck nécessite un accès Internet, il peut échouer lorsque seul le réseau interne est disponible.
4. Ignorer les conteneurs non sains. Certaines équipes voient unhealthy mais ne font rien car le conteneur fonctionne toujours. Cela va à l'encontre du but.
5. Trop de tentatives ou intervalles longs. Cela retarde la détection des échecs.
6. Ne pas tester les healthchecks en CI/CD. Exécutez toujours un conteneur en CI et vérifiez qu'il devient sain.
7. Oublier de mettre à jour les healthchecks lorsque l'application change. Si le chemin du point de terminaison de santé change, le healthcheck échouera.

Comment éviter : incluez la vérification des healthchecks dans votre pipeline CI. Pour chaque service, exécutez le conteneur, attendez qu'il devienne sain et faites échouer le build s'il ne l'est pas.

Conclusion

Les healthchecks Docker sont un outil simple mais puissant pour garantir que les applications conteneurisées sont réellement disponibles. En définissant des healthchecks clairs, en les surveillant et en configurant des alertes, vous pouvez détecter les problèmes avant les utilisateurs. Les commandes et exemples de cet article vous donnent une base solide. Commencez par ajouter un healthcheck à un service critique, observez son comportement et déployez progressivement vers le reste. N'oubliez pas : un healthcheck n'est utile que si vous agissez sur ses signaux. Intégrez-le à votre pile de surveillance et à votre processus de réponse aux incidents.

Pour les prochaines étapes, choisissez un conteneur qui manque actuellement de healthcheck, ajoutez-en un en utilisant les conseils ci-dessus et vérifiez qu'il signale sain. Ensuite, configurez une alerte simple en utilisant une tâche cron ou Prometheus. Enfin, documentez les étapes de récupération en cas d'échec du healthcheck. Avec ces pratiques, vous passerez d'un dépannage réactif à une fiabilité proactive.