Mise à niveau et migration du réseau overlay Docker : guide complet

Introduction

Le réseau overlay Docker permet aux conteneurs situés sur des hôtes différents de communiquer directement via un réseau virtuel et chiffré. À mesure que Docker publie de nouvelles versions de son moteur, l'implémentation de l'overlay évolue, apportant de nouvelles fonctionnalités, des corrections de bogues et parfois des changements cassants. La mise à niveau ou la migration des réseaux overlay est une opération critique qui peut perturber les services en cours d'exécution si elle n'est pas gérée avec soin.

Ce guide propose une approche pratique, étape par étape, pour planifier et exécuter les mises à niveau et migrations du réseau overlay Docker. Nous couvrons l'inventaire de votre environnement actuel, la définition d'un déploiement sûr, la vérification de la nouvelle configuration, la gestion des échecs courants et la création d'une liste de contrôle opérationnelle reproductible.

Que vous mettiez à niveau le moteur Docker, que vous passiez d'un réseau overlay hérité à un nouveau, ou que vous migriez des charges de travail entre des clusters Swarm, ce guide vous aidera à réduire les risques et à assurer une transition en douceur.

Inventaire des versions et de l'environnement

Avant de modifier quoi que ce soit, documentez l'état actuel. Commencez par vérifier les versions de Docker, l'état des nœuds Swarm, les réseaux overlay existants et les services attachés sur chaque nœud du cluster.

Sur chaque nœud, vérifiez la version du moteur Docker :

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

Exemple de sortie : 20.10.12 ou 23.0.1. Notez toute divergence de version. Swarm peut fonctionner avec des versions de moteur mixtes, mais des écarts importants peuvent entraîner des problèmes de compatibilité d'API et un comportement instable de l'overlay.

Vérifiez l'appartenance au Swarm et l'état des nœuds :

docker node ls

Assurez-vous que tous les nœuds sont Ready et Active et que les managers sont Reachable. Un nœud Down ou Unknown peut rompre le routage overlay.

Listez les réseaux overlay existants :

docker network ls --filter driver=overlay

Inspectez chaque réseau pour capturer sa configuration, y compris le sous-réseau, la passerelle, le chiffrement et les options personnalisées :

docker network inspect <nom-du-réseau>

La sortie montre la configuration IPAM, le statut attachable et si le chiffrement est activé. Conservez cette sortie pour comparaison après la mise à niveau.

Déterminez quels services sont attachés à chaque réseau overlay :

docker service ls --format 'table {{.Name}}	{{.Networks}}'

Cela liste chaque service et les réseaux auxquels il est connecté. Notez les services attachés à plusieurs réseaux, comme un proxy inverse qui se connecte à la fois à un overlay frontend et à un overlay backend.

Avant tout changement, vérifiez que le port UDP 4789 pour VXLAN est ouvert entre tous les nœuds qui participeront à l'overlay. Utilisez nc ou telnet pour tester :

nc -z -u <ip-nœud-distant> 4789

Si cela échoue, le trafic overlay ne circulera pas et les conteneurs sur différents nœuds ne pourront pas communiquer.

Créez un tableau d'inventaire pour suivre les détails. En production, il peut s'agir d'une feuille de calcul ou d'un document dans votre système de gestion de configuration. Exemple :

Nœud	Version Docker	Rôle	Réseaux overlay	Notes
node1	20.10.12	Manager	prod-overlay, test-overlay	Leader
node2	20.10.12	Worker	prod-overlay, test-overlay
node3	19.03.15	Worker	prod-overlay	Mise à niveau requise

Cet inventaire est votre source de vérité pour la migration. Sans lui, vous risquez de manquer un service qui dépend d'un réseau que vous vous apprêtez à supprimer.

Chemin de configuration sûr

La mise à niveau du réseau overlay signifie généralement mettre à niveau le moteur Docker ou modifier les configurations réseau. Une approche sûre consiste à limiter le changement à un seul réseau ou service à faible risque et à utiliser un pilote contrôlé.

Étape 1 : Planifier le pilote

Choisissez un réseau overlay à faible trafic pour tester la nouvelle configuration. Par exemple, si vous avez un réseau test-overlay utilisé par des outils internes, commencez par celui-ci plutôt que par le réseau de production. Si possible, choisissez un service qui peut tolérer une brève interruption et qui a un petit nombre de réplicas.

Étape 2 : Préparer la nouvelle configuration

Si vous mettez à niveau le moteur Docker, suivez la procédure de mise à niveau officielle pour votre système d'exploitation. Par exemple, sur Ubuntu :

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Cependant, ne mettez pas à niveau tous les nœuds en même temps. Mettez d'abord à niveau un nœud worker, vérifiez la connectivité overlay, puis passez au nœud suivant.

Pour une migration de réseau, créez un nouveau réseau overlay avec les paramètres souhaités avant de supprimer l'ancien. Exemple : créez un nouveau réseau overlay chiffré avec un sous-réseau spécifique :

docker network create \
  --driver overlay \
  --opt encrypted=true \
  --subnet 10.10.0.0/24 \
  --gateway 10.10.0.1 \
  new-prod-overlay

L'option --opt encrypted=true active le chiffrement IPsec pour le trafic overlay. Les options --subnet et --gateway vous donnent le contrôle sur l'adressage IP, ce qui est utile si vous devez éviter des conflits avec des réseaux existants ou répondre à des exigences de conformité. Vous pouvez également attacher des étiquettes personnalisées pour le suivi :

docker network create \
  --driver overlay \
  --label environment=staging \
  --label owner=platform-team \
  staging-overlay

Les étiquettes vous aident à filtrer les réseaux plus tard avec docker network ls --filter label=environment=staging.

Si vous devez migrer la configuration d'un réseau overlay existant tout en conservant le même nom, vous ne pouvez pas simplement modifier le réseau en place. Les réseaux Docker sont immuables pour la plupart des paramètres. À la place, créez un nouveau réseau avec les paramètres souhaités, migrez les services vers celui-ci, puis supprimez l'ancien.

Étape 3 : Attacher un service au nouveau réseau

Attachez un service à faible risque au nouveau réseau tout en gardant l'ancien réseau attaché. Cela vous donne une solution de repli :

docker service update \
  --network-add new-prod-overlay \
  my-service

Cette commande déclenche une mise à jour progressive du service. Docker reprogramme les tâches du service avec le nouveau rattachement réseau. Le service reste disponible sur l'ancien réseau pendant la transition.

Étape 4 : Surveiller et vérifier

Vérifiez que le service peut communiquer avec d'autres services sur le nouveau réseau. Le moyen le plus simple est d'exécuter un conteneur éphémère attaché au même réseau et d'utiliser ping ou curl :

docker run --rm -it \
  --network new-prod-overlay \
  alpine \
  ping my-service

Si le service a plusieurs réplicas, utilisez le nom du service et le DNS intégré de Docker renverra l'IP virtuelle (VIP) du service, répartissant la charge entre les réplicas.

Vérifiez également les journaux du service pour détecter les erreurs :

docker service logs my-service

Si le service ne démarre pas sur le nouveau réseau, vous verrez des erreurs de connexion refusée ou de résolution DNS dans les journaux.

Étape 5 : Supprimer l'ancien rattachement réseau

Une fois que vous avez vérifié que le service fonctionne correctement sur le nouveau réseau, supprimez l'ancien rattachement réseau :

docker service update \
  --network-rm old-prod-overlay \
  my-service

Cela déclenche une autre mise à jour progressive. Surveillez l'état du service pour vous assurer qu'il reste sain :

docker service ps my-service

Recherchez des tâches en état Running sans échecs récents. Si une tâche échoue, Docker tentera de la reprogrammer. Consultez les journaux pour identifier la cause racine.

Étape 6 : Supprimer l'ancien réseau

Après que tous les services ont été migrés hors de l'ancien réseau, supprimez-le :

docker network rm old-prod-overlay

Si vous obtenez une erreur indiquant que le réseau est toujours utilisé, utilisez docker network inspect old-prod-overlay pour voir quels conteneurs ou services y sont encore attachés. Détachez-les d'abord.

Gardez toujours l'ancien réseau comme solution de repli jusqu'à ce que vous soyez sûr que le nouveau fonctionne sous charge de production. Un délai courant est de conserver l'ancien réseau pendant une à deux semaines après la migration, puis de le supprimer pendant une fenêtre de maintenance.

Vérification et diagnostic

Après avoir appliqué les modifications, vérifiez que le réseau overlay fonctionne correctement. Voici les contrôles clés à effectuer :

1. Connectivité réseau

Depuis un conteneur sur le réseau overlay, envoyez un ping à un autre conteneur par nom de service :

docker exec <id-conteneur> ping <nom-service-cible>

Attendu : réponses ICMP réussies. Si les pings échouent, vérifiez que les deux services sont sur le même réseau overlay et que le port VXLAN est ouvert.

2. Résolution DNS

Vérifiez que le DNS intégré résout les noms de service vers la bonne IP virtuelle :

docker exec <id-conteneur> nslookup <nom-service-cible>

Attendu : sortie montrant l'adresse IP virtuelle du service cible. Typiquement quelque chose comme 10.10.0.2. Si le nom ne se résout pas, vérifiez que le service est attaché au bon réseau et que le DNS intégré de Docker fonctionne.

3. État du chiffrement overlay

Si vous avez activé le chiffrement, vérifiez qu'il est actif :

docker network inspect new-prod-overlay | grep -i encrypt

Attendu : "Encrypted": true dans la configuration du réseau. Si cela affiche false, le chiffrement n'est pas actif. Cela peut signifier que l'option --opt encrypted=true n'a pas été appliquée correctement, ou que le démon Docker sur un nœud ne prend pas en charge le chiffrement.

4. Maillage de routage Swarm

Vérifiez que le maillage de routage fonctionne en accédant à un port publié depuis l'extérieur du swarm :

curl http://<ip-de-tout-nœud>:<port-publié>

Attendu : une réponse du service, quel que soit le nœud sur lequel le service s'exécute. Si vous n'obtenez aucune réponse, vérifiez que le port est publié correctement et que le service est sain.

5. Journaux et événements

Inspectez les journaux du démon Docker pour détecter les erreurs liées au réseau :

journalctl -u docker | grep -i network

Recherchez des messages concernant l'état du réseau overlay, des erreurs VXLAN ou des échecs de négociation de chiffrement. Ces journaux indiquent souvent la cause racine des problèmes de connectivité.

Exécutez ces contrôles après chaque étape de migration, pas seulement à la fin. Une détection précoce réduit le rayon d'impact d'un mauvais changement.

Modes de défaillance et récupération

Même avec une planification minutieuse, des échecs peuvent survenir. Les modes de défaillance les plus courants sont :

Partition de réseau

Ce qui se passe : Les nœuds ne peuvent pas communiquer entre eux en raison d'une mauvaise configuration du pare-feu, d'un changement de groupe de sécurité ou d'un problème de routage. Le trafic overlay utilise VXLAN sur le port UDP 4789, donc ce port doit être ouvert entre tous les nœuds.

Comment détecter : nc -z -u <ip-nœud-distant> 4789 échoue. Les conteneurs sur différents nœuds ne peuvent pas se pinger.

Récupération : Rouvrez le port, vérifiez la connectivité et confirmez que les conteneurs peuvent communiquer. Si vous utilisez un fournisseur cloud, vérifiez les règles de groupe de sécurité et les listes de contrôle d'accès réseau.

Incompatibilité de versions

Ce qui se passe : Des versions Docker mixtes sur les nœuds Swarm peuvent entraîner une instabilité de l'overlay. Par exemple, un nœud exécutant Docker 19.03 peut ne pas interopérer pleinement avec un nœud exécutant Docker 24.0 en raison de changements dans le plan de contrôle overlay.

Comment détecter : Connectivité intermittente, échec de planification des tâches sur certains nœuds, ou erreurs dans les journaux du démon Docker concernant des fonctionnalités non prises en charge.

Récupération : Revenez à la version Docker précédente sur le nœud mis à niveau, ou mettez à niveau tous les nœuds vers la même version. Pour revenir en arrière sur Ubuntu :

sudo apt-get install docker-ce=<version-précédente> docker-ce-cli=<version-précédente> containerd.io

Redémarrez ensuite le démon Docker et vérifiez que le nœud rejoint correctement le swarm.

Perturbation du service pendant la mise à jour progressive

Ce qui se passe : Une mise à jour progressive d'un service tourne mal, provoquant l'échec de certaines tâches. Cela peut arriver si le contrôle de santé du service échoue sur le nouveau réseau, ou si le nouveau réseau est mal configuré.

Comment détecter : docker service ps my-service montre des tâches en état Failed ou Rejected. Le nombre de réplicas du service tombe en dessous du nombre souhaité.

Récupération : Rattachez immédiatement le service à l'ancien réseau :

docker service update --network-add old-prod-overlay my-service

Cela rétablit la connectivité pendant que vous diagnostiquez le problème. Vous pouvez également annuler la mise à jour du service avec docker service rollback my-service.

Échec de négociation du chiffrement overlay

Ce qui se passe : Lorsque le chiffrement est activé, les nœuds échangent des clés via le plan de contrôle. Si l'horloge d'un nœud est fortement décalée ou si ses certificats sont invalides, la négociation de chiffrement échoue et tout le trafic overlay est abandonné.

Comment détecter : Les conteneurs ne peuvent pas communiquer même si le port 4789 est ouvert. Les journaux du démon Docker montrent des erreurs comme Failed to establish IPsec security association.

Récupération : Synchronisez les horloges de tous les nœuds avec NTP. Vérifiez la validité des certificats du swarm. Si nécessaire, retirez le nœud du swarm et rejoignez-le à nouveau.

Liste de contrôle de récupération

Lorsqu'un échec survient, suivez cette séquence :

Identifiez l'étendue de l'échec. Quels services sont affectés ? Quels nœuds ?
Annulez le changement le plus récent. Si vous avez mis à niveau Docker, rétrogradez-le. Si vous avez modifié un réseau, rattachez l'ancien réseau.
Vérifiez que les services sont joignables sur le réseau de repli.
Analysez les journaux pour trouver la cause racine. Vérifiez les journaux du démon Docker, les journaux des conteneurs et les traces réseau.
Planifiez une nouvelle tentative avec une configuration ajustée. N'essayez pas le même changement sans comprendre pourquoi il a échoué.
Documentez l'incident et la correction dans votre manuel d'exploitation.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour toute future mise à niveau ou migration du réseau overlay. Chaque élément a un propriétaire et une fréquence de révision pour garantir la responsabilité.

Liste de contrôle pré-changement

[ ] Inventaire complet des nœuds, versions, réseaux et services. Propriétaire : Ingénieur plateforme. Révision : avant chaque migration.
[ ] Documenter les configurations réseau actuelles (sous-réseaux, chiffrement, options). Propriétaire : Ingénieur plateforme. Révision : avant chaque migration.
[ ] Tester la connectivité entre tous les nœuds sur le port VXLAN 4789. Propriétaire : Ingénieur réseau. Révision : avant chaque migration.
[ ] Choisir un réseau ou service pilote à faible risque. Propriétaire : Propriétaire du service. Révision : lors de la réunion de planification de la migration.
[ ] Créer un nouveau réseau overlay avec les paramètres souhaités. Propriétaire : Ingénieur plateforme. Révision : avant d'attacher un service.
[ ] Sauvegarder l'état Swarm sur tous les nœuds managers. Propriétaire : Ingénieur plateforme. Révision : avant tout changement.

Liste de contrôle de migration

[ ] Attacher le service pilote au nouveau réseau en parallèle de l'ancien. Propriétaire : Propriétaire du service. Révision : immédiatement après l'attachement.
[ ] Vérifier la connectivité, le DNS et le chiffrement sur le pilote. Propriétaire : Ingénieur plateforme. Révision : dans l'heure suivant l'attachement.
[ ] Migrer progressivement tous les services vers le nouveau réseau. Propriétaire : Propriétaires de services. Révision : pour chaque migration de service.
[ ] Supprimer les anciens rattachements réseau puis l'ancien réseau. Propriétaire : Ingénieur plateforme. Révision : après vérification de tous les services.
[ ] Mettre à jour la documentation et l'inventaire. Propriétaire : Ingénieur plateforme. Révision : dans la semaine suivant la migration.

Liste de contrôle post-changement

[ ] Planifier des révisions régulières des versions Docker et des paramètres réseau. Propriétaire : Responsable de l'ingénierie plateforme. Révision : trimestrielle.
[ ] Effectuer un post-mortem après toute migration échouée. Propriétaire : Responsable de l'ingénierie plateforme. Révision : dans les 5 jours ouvrés.

En attribuant un propriétaire unique à chaque étape et en définissant quand cette étape est révisée, vous évitez l'effet spectateur et garantissez que la migration se déroule de manière cohérente.

Pièges courants et comment les éviter

Même les équipes expérimentées rencontrent les mêmes obstacles lorsqu'elles travaillent avec des réseaux overlay. Voici les pièges les plus courants, pourquoi ils surviennent et comment les éviter ou s'en remettre.

1. Oublier le port VXLAN

Pourquoi cela arrive : Dans un centre de données privé, les règles de pare-feu peuvent être gérées par une équipe distincte. Lors de l'ajout de nouveaux nœuds au swarm, la règle nécessaire pour le port UDP 4789 est facilement oubliée.

Comment éviter : Incluez le port 4789 dans votre liste de contrôle standard d'approvisionnement des nœuds. Utilisez l'infrastructure en tant que code pour appliquer les règles de groupe de sécurité.

Comment récupérer : Si vous découvrez que le port est fermé, ouvrez-le sur tous les nœuds concernés, puis testez avec nc -z -u. La connectivité overlay devrait reprendre immédiatement.

2. Ne pas sauvegarder l'état Swarm

Pourquoi cela arrive : Docker Swarm n'a pas de mécanisme de sauvegarde intégré, donc de nombreuses équipes ignorent les sauvegardes jusqu'à ce qu'elles en aient besoin.

Comment éviter : Sauvegardez régulièrement le répertoire /var/lib/docker/swarm sur tous les nœuds managers. Utilisez une tâche cron ou un outil de gestion de configuration pour automatiser cela.

Comment récupérer : Si l'état Swarm est perdu ou corrompu, restaurez le répertoire de sauvegarde et redémarrez le démon Docker. Le swarm devrait récupérer ses définitions de services et ses configurations réseau.

3. Supprimer un ancien réseau trop tôt

Pourquoi cela arrive : Après une migration réussie, il y a une tentation de nettoyer immédiatement.

Comment éviter : Conservez l'ancien réseau pendant une période définie, par exemple deux semaines, et définissez un rappel pour le supprimer plus tard. Surveillez tout service retardataire qui dépend encore de l'ancien réseau.

Comment récupérer : Si vous supprimez un réseau prématurément, vous devez le recréer et rattacher les services affectés. Cela peut entraîner une interruption, donc évitez-le en attendant.

4. Ne pas tester la résolution DNS

Pourquoi cela arrive : De nombreuses équipes testent la connectivité en pingant une adresse IP, pas un nom de service. Elles manquent les problèmes DNS parce que la couche réseau fonctionne.

Comment éviter : Testez toujours avec des noms de service, pas des IP. Utilisez nslookup ou un simple curl vers un nom de service pour vérifier la résolution DNS.

Comment récupérer : Si le DNS échoue, vérifiez que le service est attaché au bon réseau et que le DNS intégré de Docker fonctionne. Redémarrer le service peut également rafraîchir ses enregistrements DNS.

5. Mettre à niveau tous les nœuds en même temps

Pourquoi cela arrive : Dans un petit swarm, il semble efficace de mettre à niveau tous les nœuds dans une seule fenêtre de maintenance.

Comment éviter : Mettez à niveau les nœuds un par un, en commençant par un worker. Vérifiez la connectivité overlay après chaque mise à niveau de nœud avant de passer au suivant.

Comment récupérer : Si vous mettez à niveau tous les nœuds et rencontrez un problème de compatibilité, vous devez rétrograder tous les nœuds, ce qui est plus perturbateur. Évitez en échelonnant la mise à niveau.

6. Ignorer le surcoût du chiffrement

Pourquoi cela arrive : Activer le chiffrement overlay ajoute un surcoût CPU pour le traitement IPsec. Les équipes peuvent l'activer sans considérer l'impact sur les performances des services sensibles au réseau.

Comment éviter : Évaluez vos services avec le chiffrement activé dans un environnement de test. Si les performances sont inacceptables, envisagez d'utiliser une décharge de chiffrement dédiée ou de limiter le chiffrement aux réseaux sensibles.

Comment récupérer : Si le chiffrement cause des problèmes de performances, vous pouvez le désactiver en recréant le réseau sans l'option --opt encrypted. Migrez les services vers le nouveau réseau non chiffré.

Exemple de flux de travail de migration

Pour illustrer le processus, voici un exemple complet de migration d'un service de production d'un ancien réseau overlay vers un nouveau réseau chiffré.

Supposons que vous ayez un cluster Swarm avec deux nœuds managers et trois nœuds workers. Le service webapp est attaché au réseau legacy-overlay, qui n'a pas de chiffrement et utilise le sous-réseau par défaut. Vous voulez migrer vers un nouveau réseau secure-overlay avec chiffrement et un sous-réseau personnalisé.

Inventaire

Exécutez les commandes d'inventaire de la première section. Documentez que webapp est le seul service sur legacy-overlay et qu'il s'exécute sur les trois nœuds workers.

Créer le nouveau réseau

   docker network create \
     --driver overlay \
     --opt encrypted=true \
     --subnet 10.20.0.0/24 \
     --gateway 10.20.0.1 \
     secure-overlay

Attacher webapp au nouveau réseau tout en gardant l'ancien

   docker service update \
     --network-add secure-overlay \
     webapp

Cela déclenche une mise à jour progressive. Surveillez la progression :

   docker service ps webapp

Attendez que toutes les tâches soient en cours d'exécution et que les anciennes tâches soient arrêtées.

Vérifier la connectivité sur le nouveau réseau

Exécutez un conteneur éphémère :

   docker run --rm -it \
     --network secure-overlay \
     alpine \
     ping webapp

Vous devriez voir des réponses de l'IP virtuelle de webapp.

Testez également le DNS :

   docker run --rm -it \
     --network secure-overlay \
     alpine \
     nslookup webapp

La sortie devrait montrer une adresse dans le sous-réseau 10.20.0.0/24.

Supprimer l'ancien rattachement réseau

Après avoir confirmé que le trafic circule sur secure-overlay, détachez webapp de legacy-overlay :

   docker service update \
     --network-rm legacy-overlay \
     webapp

Surveillez à nouveau pour vous assurer qu'aucune tâche n'échoue.

Supprimer l'ancien réseau

Une fois que webapp est uniquement sur secure-overlay, supprimez l'ancien réseau :

   docker network rm legacy-overlay

Vérifier et mettre à jour la documentation

Exécutez les contrôles de vérification de la section précédente. Mettez à jour votre inventaire et vos diagrammes réseau.

Ce flux de travail peut être adapté à n'importe quel service. Pour les migrations plus importantes, regroupez les services par groupe de dépendances et déplacez un groupe à la fois.

Conclusion

La mise à niveau et la migration du réseau overlay Docker nécessitent une planification minutieuse et une exécution réfléchie. Un inventaire complet, un pilote délimité, une vérification rigoureuse et un plan de retour en arrière solide sont les clés pour minimiser les perturbations. Utilisez la liste de contrôle opérationnelle pour standardiser les changements futurs et attribuer des responsabilités claires.

Commencez par appliquer ce guide dans un environnement de test. Documentez vos étapes spécifiques, adaptez la liste de contrôle aux normes de votre organisation et affinez votre processus en fonction des leçons apprises. Avec ces pratiques, vos mises à niveau de réseau overlay seront fluides, prévisibles et à faible risque.