Politiques de redémarrage Docker : erreurs de configuration et comment les éviter

Introduction

Les politiques de redémarrage Docker sont un élément central de la fiabilité des conteneurs, mais elles sont aussi une source fréquente de confusion. Configurer la mauvaise politique peut laisser un service de production hors ligne après un redémarrage, masquer des bogues applicatifs en redémarrant indéfiniment un conteneur défaillant, ou provoquer un redémarrage au pire moment pendant une maintenance. Ce guide explique comment fonctionnent réellement les politiques de redémarrage Docker, passe en revue les erreurs de configuration courantes avec des exemples concrets, et montre comment valider, revenir en arrière et dépanner le comportement de redémarrage en toute sécurité.

Nous couvrirons les quatre types de politiques, ce qui se passe dans différents scénarios de défaillance (redémarrage du démon, arrêts manuels, codes de sortie) et comment choisir correctement. Vous verrez des commandes réelles et des sorties attendues pour inspecter et modifier les politiques, ainsi qu'un flux de test pratique que vous pouvez exécuter localement avant de déployer en production.

Inventaire de la version et de l'environnement

Avant de modifier une politique de redémarrage, confirmez votre environnement et capturez l'état actuel. Cela évite d'apporter des modifications au mauvais conteneur ou de supposer un comportement d'une version Docker différente.

Vérifiez votre version de Docker et votre runtime

Les politiques de redémarrage sont stables depuis des années, mais la syntaxe et les valeurs par défaut peuvent varier légèrement entre Docker Engine, Docker Desktop et les installations rootless. Exécutez :

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

Exemple de sortie attendue :

24.0.7

Vérifiez également le runtime de conteneur (par exemple, containerd) et le pilote de stockage si vous dépannez la persistance du système de fichiers après les redémarrages :

docker info --format '{{.Driver}} {{.CgroupVersion}}'

Capturez les politiques de redémarrage actuelles

Listez tous les conteneurs et leurs politiques de redémarrage à l'aide d'un format personnalisé :

docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Label "com.docker.compose.project"}}'

Pour voir la politique de redémarrage exacte d'un conteneur spécifique, utilisez docker inspect :

docker inspect --format '{{.HostConfig.RestartPolicy.Name}} (max retries: {{.HostConfig.RestartPolicy.MaximumRetryCount}})' mon-app

Exemple de sortie :

always (max retries: 0)

Pour les projets Compose, la politique est définie dans docker-compose.yml sous la clé restart:. Affichez tous les services et leur état de conteneur actuel avec :

docker compose ps

Confirmez la persistance des données avant les tests de redémarrage

Si votre conteneur écrit des données avec état, vérifiez que les données vivent dans un volume ou un montage bind, pas dans la couche inscriptible du conteneur. Sinon, un redémarrage peut entraîner une perte de données.

Inspectez les montages d'un conteneur en cours d'exécution :

docker inspect --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}}{{"\n"}}{{end}}' mon-app

Exemple de sortie :

volume app_data -> /var/lib/app

Si vous ne voyez aucun montage et que l'application écrit dans /var/lib/app à l'intérieur du conteneur, ces données seront perdues lorsque le conteneur sera supprimé (mais pas lors d'un simple redémarrage). Concevez toujours les conteneurs avec état pour utiliser des volumes ou des montages bind.

Comprendre les politiques de redémarrage

Docker fournit quatre valeurs de politique de redémarrage :

Différences clés :

• always redémarrera un conteneur même si vous l'avez arrêté manuellement avant le redémarrage du démon Docker. Cela peut vous surprendre pendant les fenêtres de maintenance.
• unless-stopped se souvient que vous avez arrêté manuellement le conteneur et ne le redémarrera pas après un redémarrage du démon. C'est le choix recommandé pour la plupart des charges de travail en production.
• on-failure permet un nombre maximal de tentatives. Une fois dépassé, le conteneur s'arrête. Cela aide à éviter les boucles de redémarrage infinies pour les applications cassées.

Qu'est-ce qui déclenche un redémarrage ?

Une politique de redémarrage entre en jeu lorsque le processus principal du conteneur se termine. Docker ne redémarre pas un conteneur qui est en cours d'exécution mais non sain (sauf si vous utilisez un health check avec autoheal, ce qui est distinct). La politique de redémarrage ne s'applique pas non plus si le conteneur est supprimé ou si le démon est arrêté pendant que le conteneur est encore en cours d'exécution (le conteneur est arrêté normalement puis redémarré selon la politique au démarrage du démon).

Politiques par défaut

• docker run sans --restart utilise par défaut no.
• Docker Compose utilise par défaut no (sauf remplacement).
• Certains orchestrateurs (par exemple, Kubernetes) gèrent eux-mêmes les redémarrages ; cet article se concentre sur Docker simple et Compose.

Chemin de configuration sûr

Maintenant que vous comprenez les politiques, suivez un processus contrôlé pour en changer une.

Étape 1 : Identifiez la cible et la politique actuelle

Choisissez un seul conteneur et enregistrez sa politique actuelle à l'aide de docker inspect comme indiqué précédemment. Pour Compose, notez le nom du service et le répertoire du projet.

Étape 2 : Choisissez la nouvelle politique avec justification

Posez-vous les questions suivantes :

• S'agit-il d'un service à longue durée de vie qui devrait toujours être opérationnel ? Utilisez unless-stopped (recommandé) ou always.
• S'agit-il d'un traitement par lots ou d'un worker éphémère ? Utilisez no ou on-failure avec un petit nombre de tentatives.
• Ai-je besoin de limiter les tentatives de redémarrage pour éviter les boucles de crash ? Utilisez on-failure:5 (redémarrez 5 fois, puis arrêtez).

Exemple : un serveur web doit redémarrer sauf si un opérateur l'a délibérément arrêté pour maintenance. Donc :

services:
  web:
    image: nginx:1.25
    restart: unless-stopped

Étape 3 : Appliquez le changement

Pour un conteneur en cours d'exécution, vous ne pouvez pas modifier la politique de redémarrage via docker update. En fait, docker update prend en charge --restart depuis Docker 1.11. Vous pouvez donc mettre à jour un conteneur en cours d'exécution sans le recréer :

docker update --restart unless-stopped mon-app

Pour un conteneur créé avec docker run, spécifiez la politique à la création :

docker run -d --name mon-app --restart unless-stopped nginx:1.25

Pour Compose, modifiez docker-compose.yml et exécutez :

docker compose up -d

Cela recrée le service avec la nouvelle politique si la configuration a changé.

Étape 4 : Vérifiez la nouvelle politique

Vérifiez immédiatement que la politique est correctement définie :

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' mon-app

Sortie attendue : unless-stopped.

Étape 5 : Exécutez un test de redémarrage contrôlé

Ne vous fiez pas seulement au réglage ; simulez la condition de défaillance. Pour unless-stopped, arrêtez le conteneur manuellement et confirmez qu'il ne redémarre pas tout seul :

docker stop mon-app
sleep 5
docker ps -a --filter name=mon-app --format '{{.Status}}'

La sortie attendue montre le conteneur comme Exited (0) et non en cours d'exécution. C'est correct pour un arrêt manuel avec unless-stopped. Pour tester le redémarrage automatique en cas d'échec, tuez le processus principal avec un code de sortie non nul :

docker kill --signal=SIGKILL mon-app
sleep 2
docker ps --filter name=mon-app --format '{{.Status}}'

Vous devriez voir le conteneur Restarting ou Up (avec une nouvelle heure de démarrage).

Plan de retour en arrière

Si la nouvelle politique provoque un comportement inattendu (par exemple, une boucle de redémarrage), revenez immédiatement à la politique précédente :

• Pour les conteneurs docker run, utilisez docker update --restart <ancienne-politique> mon-app.
• Pour Compose, modifiez restart: dans le YAML et exécutez à nouveau docker compose up -d.
• Si le conteneur est bloqué dans une boucle de redémarrage, vous devrez peut-être d'abord l'arrêter : docker stop mon-app (cela fonctionne même avec une politique de redémarrage sauf qu'avec always, le redémarrage du démon redémarrera le conteneur ; pour unless-stopped, il restera arrêté).

Vérification et diagnostics

Après avoir modifié une politique de redémarrage, vérifiez à la fois la configuration et le comportement réel en cas de défaillance.

Inspectez le nombre de redémarrages et la dernière sortie

Utilisez docker inspect pour voir combien de fois le conteneur a redémarré :

docker inspect --format '{{.RestartCount}}' mon-app

Si le compte augmente rapidement, le conteneur est en boucle de crash. Examinez le code de sortie :

docker inspect --format '{{.State.ExitCode}}' mon-app

Un code de sortie 0 signifie une sortie propre ; non nul indique une erreur. Pour on-failure, un nombre élevé de tentatives peut épuiser le maximum et arrêter définitivement le conteneur.

Consultez les journaux pour la cause de la défaillance

docker logs mon-app --tail 100

Recherchez des traces de pile, des fichiers manquants ou des conflits de port. Si l'application nécessite un health check, combinez la politique de redémarrage avec un contrôle de santé Docker pour éviter de redémarrer un conteneur qui fonctionne mais qui n'est pas sain :

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

Utilisez ensuite unless-stopped afin que Docker ne redémarre qu'en cas de défaillance du processus, pas en cas d'échec du health check (sauf si vous utilisez une fonctionnalité d'orchestrateur).

Testez le comportement au redémarrage du démon

Une erreur courante consiste à supposer qu'un conteneur avec always démarrera après un redémarrage de l'hôte. Testez toujours en redémarrant le démon Docker ou l'hôte dans un environnement de staging.

Sur un serveur Linux avec systemd :

sudo systemctl restart docker
sleep 10
docker ps --filter name=mon-app

Si le conteneur n'apparaît pas, vérifiez docker ps -a pour voir s'il est arrêté. Pour unless-stopped, si vous l'aviez arrêté manuellement avant le redémarrage du démon, il restera arrêté. C'est attendu.

Modes de défaillance et récupération

Plusieurs modes de défaillance découlent d'une mauvaise configuration de la politique de redémarrage. Voici les plus courants et comment s'en remettre.

1. Définir always alors que unless-stopped est prévu

Symptôme : Vous arrêtez un conteneur pour maintenance, redémarrez le serveur et le conteneur redémarre de manière inattendue. Cela peut provoquer un split-brain ou une contention de ressources si le service doit rester arrêté.

Cause : always ignore les arrêts manuels lors des redémarrages du démon. Docker suppose que vous voulez que le conteneur soit en cours d'exécution quoi qu'il arrive.

Récupération : Changez la politique en unless-stopped :

docker update --restart unless-stopped mon-app

Ensuite, si vous avez besoin qu'il soit arrêté, arrêtez-le avant le redémarrage ; il restera arrêté.

2. Utiliser on-failure sans limite sur une application cassée

Symptôme : Le conteneur redémarre constamment, épuisant le CPU et remplissant les journaux.

Cause : on-failure sans MaximumRetryCount (ou on-failure:0) signifie des tentatives illimitées. L'application peut se terminer avec le code 1 à plusieurs reprises.

Récupération : Définissez un nombre fini de tentatives, par exemple 5 :

docker update --restart on-failure:5 mon-app

Ensuite, diagnostiquez la cause profonde en consultant les journaux pendant que le conteneur est arrêté.

3. Oublier de définir une politique de redémarrage

Symptôme : Après un redémarrage de l'hôte, votre service est hors ligne.

Cause : La politique par défaut est no. Le conteneur ne redémarre jamais automatiquement.

Récupération : Ajoutez --restart unless-stopped (ou always) à docker run, ou restart: unless-stopped dans Compose. Recréez le conteneur.

4. Appliquer une politique de redémarrage à une tâche ponctuelle

Symptôme : Une migration de données ou un traitement par lots s'exécute à plusieurs reprises après son achèvement parce que le conteneur se termine avec le code 0 et que la politique est always ou unless-stopped.

Cause : Ces politiques redémarrent quel que soit le code de sortie. Une tâche qui se termine avec succès ne doit pas être redémarrée.

Récupération : Utilisez --restart no ou on-failure avec des tentatives pour les tâches. Si elle est déjà en cours d'exécution, arrêtez et supprimez le conteneur, puis exécutez-en un nouveau avec la bonne politique.

5. Mal comprendre on-failure et le code de sortie 0

Symptôme : Vous vous attendez à ce que on-failure redémarre lorsque l'application plante, mais elle ne redémarre pas lorsque l'application se termine avec le code 0 après une erreur fatale (certaines applications terminent avec 0 même en cas d'échec).

Cause : on-failure ne se déclenche que sur des codes de sortie non nuls. Si l'application interprète un crash comme un arrêt propre (sortie 0), Docker ne la redémarrera pas.

Récupération : Corrigez l'application pour qu'elle sorte avec un code non nul en cas d'erreur fatale, ou utilisez un script wrapper qui mappe les erreurs vers la sortie 1. Utilisez ensuite on-failure ou unless-stopped.

6. Conflit de politique de redémarrage avec depends_on de Compose

Symptôme : Dans Compose, le service A (avec restart: always) redémarre en continu, ce qui fait que le service B (qui dépend de A) redémarre également parce que depends_on fait recréer B lorsque A redémarre. Cela crée une cascade.

Cause : La condition par défaut de depends_on dans Compose est service_started, pas service_healthy. Si A plante, B peut démarrer correctement mais A redémarre, et Compose peut redémarrer les deux.

Récupération : Utilisez depends_on avec condition: service_healthy et définissez des healthchecks. Limitez la politique de redémarrage de A à on-failure avec un nombre fini de tentatives pour éviter les boucles infinies.

7. Perte de données en raison d'une mauvaise configuration du volume

Symptôme : Le conteneur redémarre correctement mais les données sont manquantes après un redémarrage (par exemple, les fichiers de base de données ont disparu).

Cause : Les données ont été écrites dans la couche inscriptible du conteneur au lieu d'un volume. Un simple redémarrage préserve la couche inscriptible, mais si le conteneur est recréé (par exemple, par Compose up après un changement de politique), toutes les données sont perdues.

Récupération : Reconfigurez avec un volume ou un montage bind. Si les données sont critiques, récupérez à partir des sauvegardes. Testez la persistance en recréant délibérément le conteneur avant la production.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et après avoir modifié les politiques de redémarrage en production. Attribuez un seul responsable pour le changement et une date de révision.

• [ ] Responsable : Priya Shah, responsable de l'ingénierie. Date de révision : après chaque changement et audit trimestriel.
• [ ] Confirmez que la version de Docker et le runtime sont connus (docker version, docker info).
• [ ] Capturez la politique de redémarrage actuelle du conteneur cible : docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' <conteneur>.
• [ ] Vérifiez si le conteneur a des volumes ou des montages bind et que les données sont persistées à l'extérieur du conteneur.
• [ ] Choisissez la nouvelle politique avec une justification documentée. Exemple : changez no en unless-stopped pour le service web car il doit survivre aux redémarrages de l'hôte sauf s'il est délibérément arrêté.
• [ ] Appliquez le changement via docker update --restart ou une modification du fichier Compose + docker compose up -d.
• [ ] Vérifiez la nouvelle politique avec docker inspect.
• [ ] Exécutez des tests de redémarrage contrôlés :
• Arrêt manuel : le conteneur doit rester arrêté pour unless-stopped ; il doit redémarrer pour always uniquement après le redémarrage du démon. En fait, l'arrêt manuel outrepasse always jusqu'au redémarrage du démon. Testez le redémarrage du démon séparément.
• Simulez une défaillance : docker kill le processus principal et confirmez le redémarrage.
• Vérifiez le nombre de redémarrages : docker inspect --format '{{.RestartCount}}' doit augmenter.
• [ ] Vérifiez les journaux pour les messages d'erreur : docker logs --tail 100.
• [ ] Confirmez le chemin de retour en arrière : sachez comment revenir rapidement à la politique précédente.
• [ ] Documentez le changement dans le runbook avec l'horodatage et le responsable.
• [ ] Planifiez une révision trimestrielle de toutes les politiques de redémarrage des conteneurs pour vous assurer qu'elles correspondent toujours aux exigences des services.

Pièges courants et comment les éviter

Au-delà des modes de défaillance ci-dessus, ces pièges se produisent fréquemment :

1. Supposer que always est plus sûr que unless-stopped. En réalité, always peut faire démarrer des conteneurs après un redémarrage même si vous vouliez les garder arrêtés pour maintenance. Utilisez unless-stopped pour la plupart des services.

1. Ne pas tester le comportement au redémarrage du démon. De nombreux développeurs ne testent que le meurtre du processus de conteneur, pas le redémarrage du démon Docker. Testez toujours les deux dans un environnement de staging.

1. Ignorer les codes de sortie. Une application qui sort avec 0 en cas d'erreur fatale contrecarre on-failure. Assurez-vous que votre application suit les conventions Unix : non nul pour les erreurs.

1. Utiliser on-failure avec trop de tentatives. Si l'application échoue définitivement, un nombre élevé de tentatives retarde la détection. Utilisez un petit nombre (3-5) et surveillez les journaux.

1. Changer la politique sans vérifier la persistance des données. Si vous recréez un conteneur pour appliquer un changement de politique (par exemple, Compose up recrée), les données dans la couche inscriptible du conteneur sont perdues. Utilisez toujours des volumes pour les services avec état.

1. Ne pas documenter le choix de la politique. Les équipes peuvent ne pas savoir pourquoi une politique a été définie, ce qui entraîne des modifications accidentelles. Ajoutez des commentaires dans les fichiers Compose :

services:
  db:
    image: postgres:16
    restart: unless-stopped  # rester en marche sauf arrêt manuel pour maintenance

Conclusion

Les politiques de redémarrage Docker sont simples dans leur concept mais faciles à mal configurer en production. En comprenant le comportement exact de no, on-failure, always et unless-stopped, et en suivant un processus de changement minutieux avec vérification et retour en arrière, vous pouvez vous assurer que vos conteneurs sont disponibles quand ils doivent l'être et arrêtés quand vous en avez besoin.

Commencez par un conteneur à faible risque dans un environnement de staging. Capturez sa politique actuelle, appliquez un changement, exécutez les tests de redémarrage décrits ici et documentez les résultats. Étendez ensuite le processus à la production. Auditez régulièrement vos politiques de redémarrage dans le cadre de l'hygiène opérationnelle, et vous éviterez les pièges les plus courants qui conduisent à des temps d'arrêt inattendus ou à des redémarrages incontrôlés.