HEALTHCHECK Docker et politiques de redémarrage pour des conteneurs fiables

Intro

Cette version française explique Docker health checks and restart policies for reliable containers avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Si vous vous appuyez sur Docker pour des services client, la fiabilité est votre marque. Deux fonctionnalités portent une bonne partie de cet enjeu : les health checks et les politiques de redémarrage (restart policies). Les health checks indiquent à Docker quand un service est réellement prêt ou cassé. Les politiques de redémarrage disent à Docker quoi faire lorsqu'un conteneur s'arrête ou plante. Avec le timing des dépendances dans Docker Compose (depends_on avec service_healthy), vous évitez les démarrages hasardeux, les échecs silencieux et les surprises nocturnes. Ce guide montre exactement comment les implémenter et les tester, avec des exemples courts que vous pouvez exécuter localement.

Vue d'ensemble du workflow

Ajoutez un HEALTHCHECK rapide et déterministe à chaque service.
Reflétez la même sonde dans Docker Compose pour vos stacks locales.
Choisissez une politique de redémarrage par service selon le comportement de panne.
Utilisez depends_on avec condition service_healthy pour l'ordre de démarrage.
Testez en local des modes d'échec courants (démarrage lent, dépendance indisponible, échec de la sonde).
Déployez progressivement avec des logs et métriques inspectables.

Fondamentaux des health checks

Un health check répond à une question simple : le conteneur fait-il un travail utile maintenant ?

Principes clés :

Gardez-le rapide : quelques secondes maximum. Une sonde lente devient elle-même le problème.
Vérifiez depuis l'intérieur du conteneur : ciblez localhost plutôt que des hôtes externes.
Utilisez les codes de sortie : 0 signifie healthy, non-zéro signifie unhealthy.
Ajoutez un warmup : avec start_period pour éviter les faux négatifs au démarrage à froid.

Exemple Dockerfile (service Node.js HTTP) :

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
# Health check : laissez le temps de chauffer, puis sondez /health
HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

Health check côté Compose pour le même service :

services:
  web:
    build: .
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/health || exit 1"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 30s

Inspecter l'état de santé :

# Afficher rapidement le statut de santé
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

# Inspecter l'historique détaillé
docker inspect --format='{{json .State.Health}}' web | jq .

# Écouter les événements de santé en continu
docker events --filter event=health_status

Politiques de redémarrage expliquées

Les politiques de redémarrage contrôlent ce que Docker fait quand un conteneur s'arrête. Elles ne redémarrent pas automatiquement un conteneur uniquement parce qu'il devient unhealthy. Les redémarrages sont déclenchés par la sortie du processus (exit), pas par l'état de santé.

Options courantes :

no : ne jamais redémarrer (valeur par défaut si non spécifiée).
on-failure[:max-retries] : redémarrage sur code de sortie non-zéro, éventuellement plafonné.
always : toujours redémarrer quand le conteneur s'arrête, quelle qu'en soit la raison.
unless-stopped : comme always, sauf si vous l'arrêtez manuellement.

Exemples Compose :

services:
  worker:
    image: myorg/worker:1.2
    restart: "on-failure:5"  # au plus 5 tentatives en cas de crash

  cron:
    image: myorg/cron:1.0
    restart: unless-stopped   # le maintenir actif sauf arrêt manuel

  api:
    build: ./api
    restart: always           # le relancer après un reboot hôte

Conseils :

Choisissez on-failure pour des jobs de courte durée qui doivent réessayer.
Choisissez always ou unless-stopped pour des services longue durée.
Si un conteneur reste unhealthy mais continue de tourner, il ne sera pas redémarré par la seule politique. Enquêtez sur la cause ou concevez l'application pour sortir en non-zéro sur erreur fatale.

Compose, health checks et timing

depends_on avec conditions de santé permet de démarrer les services dans un ordre pertinent. Cela ne les garde pas synchronisés en permanence ; cela ne fait que contrôler la phase de démarrage.

Exemple : l'API attend que Postgres soit healthy.

version: "3.9"
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s

  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://postgres: example@db:5432/postgres
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 30s

Ce que cela vous apporte :

db ne passe à healthy qu'après des succès répétés de pg_isready.
api ne démarre pas avant que db soit healthy, réduisant les échecs au boot.
Si db tombe plus tard, api reste en marche ; gérez la reconnexion côté application.

Modes d'échec et troubleshooting

Problèmes fréquents et façons de les gérer :

Démarrage à froid lent qui fait échouer la sonde trop tôt :
Augmentez start_period pour couvrir la chauffe.
Réduisez les retries et augmentez légèrement interval pour limiter les oscillations.

Sonde qui oscille sous charge :
Gardez les probes légères. Évitez les appels complets à des dépendances.
Visez un endpoint interne de readiness, pas la page d'accueil.

Unhealthy mais pas de redémarrage :
Rappel : les politiques se déclenchent sur la sortie du processus. Si le service est irrécupérable, faites-le sortir en non-zéro pour activer la politique.

Accrocs réseau ou DNS dans le conteneur :
Ciblez localhost ou le nom du service, pas des domaines externes.
Pour l'auto-sondage, préférez 127.0.0.1 aux hostnames.

Outils manquants dans les images minimales :
Alpine a souvent wget via BusyBox ; curl peut être absent.
Si vous avez besoin de curl, ajoutez-le explicitement (ex. RUN apk add --no-cache curl) et mesurez l'impact sur la taille.

Probes qui modifient l'état :
Rendez-les idempotentes. Elles ne doivent ni écrire en base ni muter des caches.

I/O longues dans les probes :
Fixez timeout à une petite valeur (1-5 s) pour échouer vite si ça bloque.

Disponibilité TCP d'une base vs readiness :
Un port ouvert n'implique pas la disponibilité fonctionnelle. Utilisez pg_isready ou l'équivalent.

Commandes utiles :

# Voir les transitions de santé en direct
docker events --filter event=health_status

# Surveiller l'état courant en boucle
watch -n2 'docker ps --format "table {{.Names}}\t{{.Status}}"'

# Forcer un test d'échec en mettant une dépendance en pause
docker pause db && sleep 20 && docker unpause db

# Afficher les derniers logs de santé
docker inspect --format='{{json .State.Health.Log}}' api | jq '.[-5:]'

Plan pilote local

Commencez étroit, mesurez, et restez local au départ.

Objectif : ajouter un health check et une politique de redémarrage à un service, vérifier le comportement dans trois scénarios, et collecter des signaux simples de réussite/échec.

Étapes :

Sélectionnez un service qui expose /health ou équivalent.
Ajoutez HEALTHCHECK dans le Dockerfile avec start_period et de petits timeouts.
Reproduisez la sonde dans docker-compose.yml.
Choisissez une politique alignée à l'intention (ex. always pour une API).
Testez en local :

Normal : docker compose up -d; confirmez que Status inclut (healthy).
Dépendance indisponible : arrêtez la dépendance, vérifiez que la santé passe à (unhealthy), puis restaurez.
Crash : docker kill -s SIGKILL <container>; confirmez le redémarrage selon la politique.

Relevez les temps : warmup, durée moyenne des probes, faux échecs et redémarrages.
Ajustez start_period, interval, timeout et retries pour supprimer les faux négatifs.

Commandes :

# Monter la stack
docker compose up -d --build

# Vérifier le résumé de santé
docker compose ps

# Provoquer un crash
docker kill -s SIGKILL api

# Arrêter et nettoyer
docker compose down -v

Critères de sortie :

La santé devient healthy dans une fenêtre de chauffe attendue.
Un crash déclenche un redémarrage comme prévu.
L'état unhealthy est visible via docker ps et les logs, sans oscillations bruyantes.

Conclusion

Des conteneurs fiables marient des health checks rapides et pertinents avec des politiques de redémarrage adaptées au comportement attendu. Utilisez les health checks Compose et depends_on pour ordonner les démarrages, puis testez localement les démarrages lents, les crashes et la perte de dépendances. Démarrez par un petit pilote, mesurez, et déployez progressivement le schéma à tout le stack. Résultat : des opérations plus simples et moins de surprises.