Politique de redémarrage Docker Compose : choix et vérification

Une politique de redémarrage Docker Compose détermine ce qui se passe après l’arrêt du processus principal d’un conteneur. Choisissez-la selon le rôle du service : un import terminé, un worker en échec et un service web qui doit rester disponible demandent des comportements différents.

Ce guide concerne les conteneurs Docker Engine gérés avec Compose. Il présente les quatre politiques, l’application d’une modification et la vérification du résultat. La configuration de l’exemple a passé nos contrôles locaux ; les redémarrages de conteneurs et la reprise après redémarrage de Docker n’ont pas été exécutés dans notre environnement.

Choisir une politique de redémarrage

Placez restart directement sous le service. La référence des services Compose accepte les valeurs suivantes. Écrivez "no" entre guillemets pour conserver une chaîne de caractères.

Politique	Après un code de sortie 0	Après un code non nul	Décision habituelle
"no"	Rester arrêté	Rester arrêté	Examiner les échecs manuellement ou exécuter une tâche ponctuelle
on-failure:3	Rester arrêté	Jusqu’à trois nouvelles tentatives	Limiter les reprises d’une tâche pouvant être répétée sans risque
always	Redémarrer	Redémarrer	Maintenir un service actif, y compris après le redémarrage de Docker
unless-stopped	Redémarrer	Redémarrer	Maintenir un service actif en conservant un arrêt volontaire

Ces règles supposent que le conteneur a démarré et qu’un opérateur ne l’a pas arrêté volontairement. Sans champ restart, la valeur est no. on-failure sans limite continue les tentatives après un échec ; le suffixe numérique appartient à cette politique.

Always et unless-stopped après un arrêt manuel

Un arrêt volontaire suspend les redémarrages automatiques immédiats. La différence apparaît lorsque Docker redémarre : always peut relancer le conteneur arrêté, tandis que unless-stopped le laisse arrêté. on-failure ne garantit pas le démarrage automatique après celui du daemon. Le guide Docker des politiques de redémarrage décrit ces cas.

Pour un service web, unless-stopped est un choix de départ utile si les arrêts de maintenance doivent être conservés après un redémarrage de Docker. Pour un traitement par lot, vérifiez d’abord que sa répétition est sûre. Une nouvelle tentative peut dupliquer un e-mail, une demande de paiement ou un export si l’application ne gère pas les répétitions.

La reprise après un redémarrage de l’hôte dépend aussi du démarrage de Docker et de la disponibilité des données et de la configuration. Une politique de conteneur ne restaure pas une VM perdue. Testez séparément la reprise de l’hôte et celle du processus.

Un exemple limité avec deux codes de sortie

Créez un répertoire de test et enregistrez ceci sous compose.yaml. Utilisez un Docker Engine configuré pour les conteneurs Linux. Les deux services n’exposent aucun port, ne montent aucune donnée, utilisent un système de fichiers en lecture seule et ont le réseau désactivé. Ils affichent un message, attendent et se terminent.

services:
  fails:
    image: alpine:3.22
    user: "1000:1000"
    network_mode: none
    read_only: true
    command: ["sh", "-c", "echo 'Intentional failure'; sleep 12; exit 1"]
    restart: "on-failure:3"
  succeeds:
    image: alpine:3.22
    user: "1000:1000"
    network_mode: none
    read_only: true
    command: ["sh", "-c", "echo 'Intentional success'; sleep 12; exit 0"]
    restart: "on-failure:3"

Seul le code de sortie diffère entre les services. La limite de tentatives reste identique pour isoler cette différence. La pause de 12 secondes évite un échec immédiat au démarrage ; Docker documente une condition de démarrage réussi d’au moins dix secondes avant la surveillance. Ce délai sert à la démonstration, pas à vérifier que l’application est prête.

Le tag d’image est lisible, mais peut changer. Enregistrez une empreinte d’image testée lorsque la reproductibilité compte. Depuis ce répertoire, validez le modèle puis démarrez le projet de test :

docker compose -p restart-demo config --quiet
docker compose -p restart-demo up -d
docker compose -p restart-demo ps --all

config --quiet valide la configuration sans lancer de conteneur. Nos contrôles avec Compose v5.1.4 couvrent les quatre politiques, une valeur booléenne invalide et la modification d’un seul service. Le moteur Docker était indisponible localement : les résultats suivants sont donc attendus et restent à vérifier en exécution.

• succeeds doit se terminer avec le code 0, sans nouvelle tentative automatique.
• fails doit se terminer avec le code 1 et recevoir au maximum trois nouvelles tentatives automatiques.
• Attendez la fin des tentatives avant d’interpréter l’état final. Une lecture immédiate ne décrit pas toute la séquence.

Utilisez ps --all pour afficher aussi les conteneurs terminés. L’option -d laisse le projet fonctionner indépendamment du terminal.

Examiner la politique reçue par Docker

La première commande fournit l’identifiant du conteneur fails. Remplacez CONTAINER_ID dans les trois commandes d’inspection par cet identifiant, puis consultez les journaux des deux services.

docker compose -p restart-demo ps --all --quiet fails
docker inspect --type container --format '{{json .HostConfig.RestartPolicy}}' CONTAINER_ID
docker inspect --type container --format '{{.RestartCount}}' CONTAINER_ID
docker inspect --type container --format '{{json .State}}' CONTAINER_ID
docker compose -p restart-demo logs --tail 30 fails succeeds

docker inspect lit le conteneur existant. Vérifiez sa politique, le maximum de tentatives, le compteur de redémarrages, ainsi que le code de sortie, l’erreur et les horodatages de son état. Recherchez de nouveau l’identifiant si Compose recrée le conteneur.

La référence du moteur décrit les compteurs et les délais entre tentatives. Le compteur concerne ce conteneur ; il ne représente pas l’historique complet de l’application. Comparez-le aux horodatages et aux journaux pour comprendre l’échec.

Notre guide Docker logs explique la consultation et la rotation des journaux. Lors d’un incident réel, conservez les erreurs utiles avant de remplacer le conteneur. Retirez les identifiants secrets et les données personnelles avant de partager un diagnostic.

Appliquer une modification avec Compose up

Pour modifier la démonstration, remplacez uniquement fails.restart par "no" dans le YAML, puis lancez :

docker compose -p restart-demo config --quiet
docker compose -p restart-demo up -d --no-deps fails

docker compose up applique la nouvelle configuration en recréant le conteneur concerné si nécessaire. La démonstration repart alors sans tentative automatique pour fails. Le nouveau conteneur possède son propre état et compteur. --no-deps limite l’opération au service choisi ; cet exemple n’a pas de dépendances.

docker compose restart redémarre les conteneurs existants sans appliquer les modifications du fichier Compose. Après un changement, inspectez de nouveau le conteneur pour vérifier la correspondance entre le YAML et la configuration exécutée.

Pour un service réel, prévoyez l’interruption et vérifiez l’emplacement des données durables avant toute recréation. Notre guide des volumes Docker traite de la persistance et des sauvegardes. La politique de redémarrage ne remplace pas cette préparation.

Distinguer santé, dépendances et politique de déploiement

Un healthcheck en échec peut rendre un conteneur unhealthy sans arrêter son processus principal. Les politiques ordinaires du moteur ne réagissent pas à ce seul état. Notre guide des healthchecks Compose couvre les sondes et la disponibilité. Configurez séparément la surveillance et une éventuelle reprise fondée sur la santé.

depends_on.<service>.restart: true relance un service dépendant après une opération Compose explicite sur sa dépendance. Il ne suit pas chaque redémarrage automatique effectué par le moteur. Le guide de l’ordre de démarrage explique ce comportement et service_healthy. L’application doit toujours gérer les connexions qui échouent après son démarrage.

deploy.restart_policy relève de la spécification Deploy, facultative, qui définit notamment une condition, un délai, un nombre de tentatives et une fenêtre. Leur prise en charge dépend de l’implémentation de déploiement. Ne supposez pas que chaque champ se comporte de façon identique dans Compose local et Swarm. Vérifiez la plateforme avant de combiner les deux formes ; cet exemple utilise restart au niveau du service.

Arrêter l’exemple et diagnostiquer les échecs répétés

docker compose stop conserve les conteneurs pour une reprise avec docker compose start. Pour supprimer cette démonstration après examen, lancez depuis son répertoire :

docker compose -p restart-demo down

docker compose down supprime les conteneurs des services et les réseaux concernés. Un conteneur supprimé ne peut pas redémarrer. Cet exemple n’a aucun volume persistant ; n’ajoutez pas d’option de suppression des volumes à un autre projet.

Si un service réel redémarre en boucle, examinez d’abord la cause : configuration invalide, dépendance indisponible, fichier absent ou limite de ressources. Consultez l’état de sortie et les journaux, corrigez la cause, appliquez la modification, puis vérifiez le travail réel de l’application. Choisissez séparément la politique de reprise et l’alerte signalant son échec.