Docker : vérifications de santé et politiques de redémarrage, guide pratique pour des conteneurs fiables

Si vous comptez sur Docker pour exécuter des services orientés client, la fiabilité est votre marque. Deux fonctionnalités portent une grande partie de ce poids : les vérifications de santé (health checks) et les politiques de redémarrage (restart policies). Les vérifications de santé indiquent à Docker quand un service est réellement prêt ou défaillant. Les politiques de redémarrage disent à Docker quoi faire lorsqu’un conteneur s’arrête ou plante. Ensemble avec la gestion des dépendances dans Docker Compose, elles permettent d’éviter les démarrages instables, les échecs silencieux et les surprises nocturnes. Ce guide montre exactement comment les implémenter et les tester, avec de courts exemples que vous pouvez exécuter sur votre ordinateur portable.

Aperçu du flux de travail

Ajoutez une vérification de santé HEALTHCHECK rapide et déterministe à chaque service.
Reproduisez la même sonde dans Docker Compose pour les piles locales.
Choisissez une politique de redémarrage par service selon son comportement en cas d’échec.
Utilisez depends_on avec service_healthy pour ordonner le démarrage.
Testez localement les modes de défaillance courants (démarrage lent, dépendance indisponible, échec de la sonde).
Déployez progressivement avec des journaux et des métriques que vous pouvez inspecter.

Fondamentaux des vérifications de santé

Les vérifications de santé répondent à une question simple : le conteneur effectue-t-il un travail utile en ce moment ?

Principes clés :

Restez rapide : quelques secondes maximum. Une vérification lente devient elle-même le problème.
Vérifiez depuis l’intérieur du conteneur : ciblez localhost, pas des hôtes externes.
Utilisez les codes de sortie : 0 signifie sain, non‑zéro signifie malsain.
Prévoyez une période de chauffe : utilisez start_period pour éviter les faux négatifs au démarrage à froid.

Exemple Dockerfile (service HTTP Node.js) :

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

Vérification de santé dans 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é de santé
docker inspect --format='{{json .State.Health}}' web | jq .

# Suivre les événements de santé
docker events --filter event=health_status

Politiques de redémarrage expliquées

Les politiques de redémarrage contrôlent ce que Docker fait lorsqu’un conteneur s’arrête. Elles ne redémarrent pas automatiquement un conteneur simplement parce qu’il est malsain. Les redémarrages sont déclenchés par la sortie, pas par l’état de santé.

Options courantes :

no : ne jamais redémarrer (par défaut si non spécifié).
on-failure[:max-retries] : redémarrer sur les codes de sortie non‑zéro, éventuellement plafonné.
always : toujours redémarrer lorsque le conteneur s’arrête pour quelque raison que ce soit.
unless-stopped : redémarrer comme always, sauf si vous l’arrêtez manuellement.

Exemples Compose :

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

  cron:
    image: myorg/cron:1.0
    restart: unless-stopped     # le maintenir en vie sauf arrêt utilisateur

  api:
    build: ./api
    restart: always             # le relancer après redémarrage de l’hôte

Conseils :

Choisissez on-failure pour les tâches de courte durée qui doivent réessayer.
Choisissez always ou unless-stopped pour les services de longue durée.
Si un conteneur reste malsain mais continue de tourner, la politique ne le redémarrera pas. Investiguez la cause ou faites en sorte que l’application quitte avec un code non‑zéro en cas d’erreur fatale.

Vérifications de santé et chronométrage dans Compose

depends_on avec conditions de santé permet de démarrer les services dans un ordre logique. Il ne les maintient pas synchronisés indéfiniment ; il ne fait que conditionner le démarrage.

Exemple : l’API attend que Postgres soit sain.

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 sera signalé sain qu’après des succès répétés de pg_isready.
api ne démarrera pas avant que db ne soit sain, réduisant les échecs au démarrage.
Si db tombe plus tard, api reste en vie ; gérez la reconnexion dans l’application.

Modes de défaillance et dépannage

Problèmes courants et comment les gérer :

Démarrage à froid lent fait échouer la vérification trop tôt
Augmentez start_period pour couvrir le warmup.
Utilisez moins de tentatives avec un intervalle légèrement plus long pour réduire le clignotement.

La vérification de santé clignote sous charge
Gardez les vérifications légères. Évitez les appels complets aux dépendances quand c’est possible.
Vérifiez un point de terminaison de prête (/ready) interne, pas la page d’accueil.

Malsain mais pas redémarré
Rappelez‑vous : les politiques agissent sur la sortie. Si le service est irrécupérable, faites‑le quitter avec un code non‑zéro pour que la politique puisse agir.

Problèmes réseau ou DNS à l’intérieur du conteneur
Ciblez localhost ou le nom du conteneur de service, pas des domaines externes.
Pour les auto‑vérifications, préférez 127.0.0.1 aux noms d’hôte.

Outils manquants dans les images minimales
Alpine inclut souvent wget via BusyBox ; curl peut ne pas être installé.
Si vous avez besoin de curl, ajoutez‑le explicitement (ex. RUN apk add --no-cache curl) et mesurez l’impact sur la taille de l’image.

Vérifications qui modifient l’état
Rendez les sondes idempotentes. Elles ne doivent pas écrire en base ni muter les caches.

Entrées/sorties longues dans les vérifications
Définissez timeout sur une valeur faible (1‑5 s) pour qu’une sonde bloquée échoue rapidement.

Prêt vs vivacité de la base de données
Un port TCP ouvert n’équivaut pas à une base prête. Utilisez pg_isready ou l’équivalent pour votre SGBD.

Commandes utiles :

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

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

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

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

Plan pilote local

Commencez petit, mesurez les résultats et restez en local d’abord.

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

Étapes :

Sélectionnez un service qui possède un point de terminaison /health ou similaire.
Ajoutez HEALTHCHECK dans le Dockerfile avec start_period et des timeouts courts.
Reproduisez la vérification dans docker-compose.yml.
Choisissez une politique de redémarrage adaptée à l’intention (ex. always pour une API).
Testez localement :

Normal : docker compose up -d ; confirmez que le statut affiche (healthy).
Dépendance absente : arrêtez la dépendance, confirmez que la santé passe à (unhealthy), puis restaurez.
Crash : docker kill -s SIGKILL <conteneur> ; confirmez le redémarrage selon la politique.

Enregistrez les durées : temps de warmup, durée moyenne de la sonde, faux échecs, redémarrages.
Ajustez start_period, interval, timeout et retries pour éliminer les faux négatifs.

Commandes :

# Lancer la pile
docker compose up -d --build

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

# Provocer un crash
docker kill -s SIGKILL api

# Arrêter et nettoyer
docker compose down -v

Critères de sortie :

La santé devient saine dans la fenêtre de warmup attendue.
Un crash déclenche un redémarrage comme prévu.
Un état malsain est visible dans docker ps et les logs, sans clignotement bruyant.

Conclusion

Des conteneurs fiables associent des vérifications de santé rapides et significatives à des politiques de redémarrage adaptées au comportement de chaque service en cas d’échec. Utilisez les vérifications de santé Compose et depends_on pour ordonner le démarrage, puis testez localement les démarrages lents, les plantages et la perte de dépendances. Commencez par un petit pilote, mesurez les résultats et étendez le motif à l’ensemble de la pile. Le résultat : des opérations plus simples et moins de surprises.