Mise à niveau et migration des contextes Docker : guide pratique pour des opérations sûres

Introduction

Les contextes Docker vous permettent de basculer entre différents hôtes Docker, comme un moteur local, un serveur distant ou un fournisseur cloud, sans reconfigurer votre CLI à chaque fois. Ils stockent les détails de connexion tels que l'URL de l'hôte, les paramètres TLS et les identifiants dans un simple profil nommé. La mise à niveau ou la migration de ces contextes devient nécessaire lorsque vous migrez vers une nouvelle infrastructure, faites tourner des certificats ou adoptez une version plus récente de Docker avec un comportement de contexte différent.

Ce guide s'adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups qui gèrent Docker en production ou dans des environnements partagés. Il couvre le cycle de vie complet d'un changement de contexte : inventorier votre configuration actuelle, planifier un chemin de configuration sûr, valider le nouveau contexte, gérer les échecs et suivre une liste de contrôle reproductible. Vous trouverez des commandes réelles, les sorties attendues et les étapes de récupération afin de pouvoir adapter les exemples à vos propres hôtes.

Le principe fondamental est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier chaque résultat et documenter la façon de récupérer si l'état attendu n'est pas atteint. Les mises à niveau de contexte échouent souvent non pas à cause de Docker lui-même, mais à cause d'hypothèses non remarquées concernant les chemins de fichiers, les variables d'environnement ou l'expiration des certificats. Cet article vous aide à mettre en évidence ces hypothèses dès le début.

Inventaire des versions et de l'environnement

Avant de toucher à un contexte, vous devez disposer d'un inventaire complet de ce que vous avez. Exécutez ces commandes en lecture seule et enregistrez la sortie. Ne sautez pas cette étape ; de nombreux échecs de migration proviennent d'une vision incomplète de la situation.

Vérifiez les versions de votre CLI Docker et du moteur :

docker version

La sortie attendue comprend une section Client et une section Server. Par exemple :

Client: Docker Engine - Community
 Version:           27.3.1
 API version:       1.47
 Go version:        go1.21.13
 Git commit:        ce12230
 Built:             Fri Sep 20 11:41:00 2024
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          27.3.1
  API version:      1.47 (minimum version 1.24)
  Go version:       go1.21.13
  Git commit:       41ca978
  Built:            Fri Sep 20 11:41:00 2024
  OS/Arch:          linux/amd64
  Experimental:     false

Notez les versions du client et du serveur. Les contextes Docker sont stockés côté client, donc la version du client est la plus importante pour les fonctionnalités de contexte. Si votre client est plus ancien que votre moteur distant, certains champs de contexte peuvent ne pas être interprétés correctement.

Listez tous les contextes existants :

docker context ls

Exemple de sortie :

NAME                TYPE                DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT   ORCHESTRATOR
default *           moby                Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                         swarm
remote-prod         ssh                 Production server via SSH                 ssh://[email protected]
desktop-linux       moby                Docker Desktop                            unix:///home/user/.docker/desktop/docker.sock

L'astérisque marque le contexte actif. Toutes les commandes que vous exécutez maintenant cibleront ce contexte. Si vous êtes sur le point de migrer, vous voudrez probablement passer à un autre contexte ou en créer un nouveau, mais capturez d'abord les détails de l'actuel.

Inspectez le contexte actif en profondeur :

docker context inspect

Cela affiche la configuration complète en JSON, y compris les chemins du matériel TLS et les paramètres de l'hôte. Voici un exemple tronqué :

[
    {
        "Name": "remote-prod",
        "Metadata": {
            "Description": "Production server via SSH"
        },
        "Endpoints": {
            "docker": {
                "Host": "ssh://[email protected]",
                "SkipTLSVerify": false
            }
        },
        "TLSMaterial": {},
        "Storage": {
            "MetadataPath": "/home/user/.docker/contexts/meta/remote-prod/meta.json",
            "TLSPath": "/home/user/.docker/contexts/tls/remote-prod"
        }
    }
]

Faites attention aux chemins de stockage. Les contextes sont stockés sous forme de fichiers sur le disque, généralement sous ~/.docker/contexts/. Le sous-répertoire meta contient la définition du contexte, et le sous-répertoire tls contient les certificats et les clés. Lors d'une mise à niveau ou d'une migration, vous devrez peut-être déplacer ou copier ces fichiers vers une nouvelle machine.

Vérifiez si des conteneurs ou des services sont actuellement en cours d'exécution sur le contexte actif :

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Pour un hôte de production, vous pourriez voir :

NAMES               STATUS              PORTS
web-1               Up 3 hours          0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
db-1                Up 3 hours          5432/tcp
cache-1             Up 3 hours          6379/tcp

Enregistrez ces noms et statuts. Si quelque chose se casse pendant la migration, vous pouvez comparer avec cette base de référence pour voir ce qui a changé.

Si vous utilisez Docker Compose, exécutez également :

docker compose ps

Et pour voir les journaux récents sans rien modifier :

docker compose logs --tail=100

Maintenant, vérifiez où résident vos données. Les données persistantes doivent être dans des volumes nommés ou des montages liés, pas dans le système de fichiers du conteneur. Listez les volumes :

docker volume ls

Et inspectez un volume spécifique utilisé par un conteneur :

docker inspect db-1 --format '{{range .Mounts}}{{.Name}} -> {{.Destination}}{{println}}{{end}}'

Exemple de sortie :

db_data -> /var/lib/postgresql/data

Cela signifie que le volume db_data est monté à l'emplacement attendu. Si au contraire vous ne voyez aucun montage et que les données sont écrites directement dans la couche du conteneur, vous perdrez ces données lorsque le conteneur sera recréé. Corrigez cela avant toute migration.

Enfin, exécutez un test de redémarrage sur un conteneur non critique pour confirmer la persistance des données :

docker stop cache-1
docker start cache-1
docker logs cache-1 --tail=20

Si l'application revient et peut lire ses données, le stockage est correctement configuré. Si elle échoue, vous avez trouvé un problème avant la migration, pas après.

Chemin de configuration sûr

Le chemin sûr pour une mise à niveau ou une migration de contexte est d'apporter des modifications sur une copie, de tester minutieusement, puis de basculer le contexte actif. Ne modifiez jamais le seul contexte fonctionnel en place sans solution de repli.

Étape 1 : Exporter le contexte actuel

Vous pouvez exporter un contexte vers un fichier pour la sauvegarde ou le transfert. La commande est :

docker context export remote-prod

Cela crée un fichier nommé remote-prod.dockercontext dans votre répertoire actuel. Il contient les métadonnées du contexte et le matériel TLS. Stockez ce fichier dans un endroit sûr, comme un emplacement de sauvegarde versionné.

Pour l'importer sur une autre machine ou après une réinitialisation :

docker context import remote-prod remote-prod.dockercontext

Mais attention : l'importation avec le même nom écrasera le contexte existant. Utilisez un nouveau nom pour les tests :

docker context import remote-prod-test remote-prod.dockercontext

Vous avez maintenant une copie pour expérimenter.

Étape 2 : Créer un nouveau contexte ciblant l'hôte mis à niveau

Supposons que vous passiez d'un ancien serveur à un nouveau avec un nom d'hôte ou une version Docker différente. Créez un nouveau contexte :

docker context create new-prod --docker "host=ssh://[email protected]"

Ou si vous utilisez TLS avec des certificats :

docker context create new-prod-tls \
  --docker "host=tcp://new-prod.example.com:2376,ca=/path/to/ca.pem,cert=/path/to/cert.pem,key=/path/to/key.pem"

Le contexte stocke ces valeurs. Elles ne sont pas chiffrées au repos, assurez-vous donc que les permissions des fichiers sont restreintes (par exemple, chmod 600 sur le fichier de clé).

Étape 3 : Tester le nouveau contexte sans basculer globalement

Vous pouvez utiliser un contexte pour une seule commande avec le drapeau --context :

docker --context new-prod ps

Cela interroge le nouvel hôte mais laisse votre contexte par défaut inchangé. Vérifiez que vous pouvez voir les conteneurs :

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Si c'est vide, c'est normal si c'est un hôte frais. Ensuite, exécutez une commande inoffensive pour tester la connectivité et les permissions :

docker --context new-prod info --format '{{.ServerVersion}}'

Sortie attendue comme 27.3.1. Si vous obtenez une erreur TLS, vérifiez que vos chemins de certificat et le nom d'hôte correspondent.

Étape 4 : Valider Docker Compose sur le nouveau contexte

Si vous utilisez Compose, pointez-le vers le nouveau contexte :

docker --context new-prod compose -f docker-compose.yml config

Cela analyse et valide le fichier Compose sans rien démarrer. Il affichera la configuration fusionnée. Si votre fichier Compose utilise des variables d'environnement qui ne sont que sur votre machine locale, vous verrez des erreurs ici. Corrigez-les avant de continuer.

Étape 5 : Basculer le contexte actif

Une fois que vous êtes confiant, basculez votre shell vers le nouveau contexte :

docker context use new-prod

Puis vérifiez :

docker context ls

L'astérisque doit maintenant être à côté de new-prod. Exécutez docker ps pour voir les conteneurs sur le nouvel hôte.

Étape 6 : Conserver l'ancien contexte comme solution de repli

Ne supprimez pas immédiatement l'ancien contexte. Gardez-le pendant au moins un cycle de déploiement complet ou une fenêtre de restauration définie. Si quelque chose ne va pas sur le nouvel hôte, vous pouvez revenir instantanément :

docker context use remote-prod

Ne supprimez l'ancien contexte qu'après avoir confirmé que le nouveau fonctionne pour tous les cas d'utilisation et que vous avez mis à jour tous les scripts ou pipelines CI qui référençaient l'ancien nom de contexte.

Vérification et diagnostic

Après avoir basculé de contexte, vous devez vérifier que l'environnement est pleinement fonctionnel. Fiez-vous à des signaux objectifs, pas seulement à une impression de « ça a l'air bien ».

Exécuter le contrôle de santé Docker

docker info

Recherchez les avertissements ou les erreurs. Une sortie saine comprend :

Server Version: 27.3.1
Storage Driver: overlay2
...
WARNING: No memory limit support

Les avertissements ne sont pas nécessairement fatals, mais notez-les. Si vous voyez ERROR: Cannot connect to the Docker daemon, votre contexte est mal configuré.

Vérifier le statut des conteneurs sur le nouvel hôte

docker ps -a

Comparez la liste à votre inventaire de base. Si des conteneurs manquent, assurez-vous que vos images sont disponibles sur le nouvel hôte. Vous devrez peut-être les tirer ou les pousser depuis un registre.

Vérifier les journaux pour les erreurs d'application

docker logs web-1 --tail=100

Recherchez les traces de pile, les échecs de connexion à la base de données ou les erreurs de certificat. Celles-ci n'apparaissent souvent qu'après la migration car le nouvel hôte a des paramètres réseau ou DNS différents.

Vérifier la connectivité réseau

Si votre application dépend de la découverte de services ou du DNS interne, testez depuis l'intérieur d'un conteneur :

docker exec web-1 curl -I http://db-1:5432

La commande exacte dépend de votre application, mais le principe est de reproduire le chemin de communication qui compte. Pour une application web qui parle à une base de données, un simple test TCP peut être :

docker exec web-1 sh -c 'nc -zv db-1 5432'

Sortie attendue : Connection to db-1 5432 port [tcp/postgresql] succeeded!

Si cela échoue, vérifiez votre configuration réseau Docker sur le nouvel hôte. Vous devrez peut-être recréer les réseaux ou ajuster les règles de pare-feu.

Valider les permissions de fichiers et les volumes

Sur un nouvel hôte, les identifiants d'utilisateur et les permissions de fichiers diffèrent souvent. Vérifiez que vos conteneurs peuvent écrire dans leurs volumes :

docker run --rm -v app_data:/data alpine sh -c 'touch /data/test && ls /data'

Si le touch échoue avec une erreur de permission, le volume a été créé avec une propriété différente sur l'ancien hôte. Vous devrez peut-être corriger la propriété à l'intérieur du conteneur ou utiliser un volume nommé avec un utilisateur défini.

Examiner la configuration du contexte pour les secrets

Exécutez à nouveau docker context inspect et confirmez qu'aucun secret ou chemin incorrect n'est présent. En particulier, assurez-vous que le chemin de la clé TLS est correct et que le certificat n'a pas expiré :

openssl x509 -enddate -noout -in /path/to/cert.pem

Cela affiche la date d'expiration du certificat. Si elle est proche ou dépassée, renouvelez-le avant de vous fier au contexte.

Modes de défaillance et récupération

Même avec une planification minutieuse, les choses peuvent mal tourner. Voici les modes de défaillance les plus courants et comment récupérer de chacun.

Défaillance 1 : Certificat expiré ou non-concordance du nom d'hôte

Symptôme : docker ps renvoie x509: certificate has expired or is not yet valid ou cannot validate certificate for 10.0.0.5 because it doesn't contain any IP SANs.

Cause : Le certificat TLS utilisé par le démon Docker a expiré ou a été généré pour un nom d'hôte différent de celui auquel vous vous connectez.

Récupération : Régénérez le certificat sur l'hôte Docker, ou mettez à jour le contexte pour pointer vers le bon nom d'hôte qui correspond au certificat. Si vous avez utilisé un certificat auto-signé, vous pouvez également ajouter skipTLSVerify: true au contexte pour les tests, mais ne l'utilisez jamais en production. Mieux vaut corriger le certificat.

Défaillance 2 : Fichier de contexte corrompu ou matériel TLS manquant

Symptôme : docker context use my-context fonctionne, mais docker ps échoue avec failed to load TLS files: open /home/user/.docker/contexts/tls/my-context/ca.pem: no such file or directory.

Cause : Les métadonnées du contexte référencent des fichiers TLS qui ont été supprimés ou non déplacés pendant la migration.

Récupération : Réimportez le contexte depuis votre fichier de sauvegarde exporté, qui comprend le matériel TLS. Si vous n'avez pas de sauvegarde, vous devez recréer le contexte manuellement avec les bons chemins de certificat.

Défaillance 3 : Conflits de contexte Docker Desktop

Symptôme : Après la mise à niveau de Docker Desktop, vos contextes personnalisés disparaissent ou le contexte par défaut devient desktop-linux de manière inattendue.

Cause : Docker Desktop gère ses propres contextes et peut écraser le contexte par défaut lors des mises à niveau.

Récupération : Recréez vos contextes personnalisés à partir des exports ou en utilisant docker context create. Pour éviter cela, utilisez toujours des noms de contexte spécifiques pour les hôtes distants et évitez de vous fier au contexte par défaut pour la production.

Défaillance 4 : Problèmes de permissions sur le nouvel hôte

Symptôme : Les conteneurs démarrent mais les applications ne peuvent pas écrire dans les volumes montés, en enregistrant des erreurs comme Permission denied.

Cause : L'identifiant d'utilisateur à l'intérieur du conteneur n'a pas la permission d'écrire dans le répertoire hôte monté en volume.

Récupération : Ajustez la propriété du contenu du volume sur l'hôte, ou exécutez le conteneur avec un utilisateur correspondant. Par exemple, si le conteneur s'exécute en tant qu'UID 1000, assurez-vous que le répertoire du volume appartient à l'UID 1000 : sudo chown -R 1000:1000 /path/to/volume.

Défaillance 5 : Problèmes de connectivité réseau après la migration

Symptôme : Les conteneurs ne peuvent pas se joindre par nom, ou l'accès réseau externe échoue.

Cause : Le nouvel hôte a des règles de pare-feu différentes, des conflits de sous-réseau ou des configurations réseau Docker différentes.

Récupération : Comparez docker network ls sur les anciens et nouveaux hôtes. Recréez les réseaux personnalisés avec les mêmes paramètres. Vérifiez les règles de pare-feu de l'hôte (par exemple, iptables -L) et assurez-vous que les règles de Docker sont présentes. Si vous utilisez une infrastructure cloud, vérifiez les paramètres du groupe de sécurité ou des ACL réseau.

Pièges courants et comment les éviter

De nombreuses mises à niveau de contexte échouent en raison d'erreurs évitables. Voici les pièges les plus fréquents et comment les éviter.

Piège 1 : Ne pas exporter les contextes avant d'apporter des modifications

Ce qui se passe : Vous modifiez ou supprimez un contexte, puis vous réalisez que vous aviez besoin de l'ancienne configuration pour revenir en arrière.

Pourquoi cela arrive : Les contextes semblent être une configuration simple, donc les gens sautent l'étape de sauvegarde.

Comment l'éviter : Exécutez toujours docker context export <nom> avant tout changement. Stockez le fichier dans un contrôle de version ou un emplacement de sauvegarde sécurisé. Faites-en une habitude.

Piège 2 : Utiliser le même nom de contexte pour les anciens et nouveaux hôtes

Ce qui se passe : Vous créez un nouveau contexte avec le même nom que l'ancien, l'écrasant. Lorsque le nouvel hôte échoue, vous n'avez pas d'ancien contexte vers lequel basculer.

Pourquoi cela arrive : Vous voulez un nom propre, donc vous réutilisez l'ancien.

Comment l'éviter : Utilisez des noms distincts avec une version ou une date, par exemple, prod-old-20250101 et prod-new-20250115. Ne renommez ou ne supprimez qu'après que le nouveau a fait ses preuves.

Piège 3 : Ignorer les différences de version client-serveur

Ce qui se passe : Vous mettez à niveau votre CLI Docker mais le moteur distant est plus ancien. Certaines fonctionnalités ou drapeaux de contexte peuvent ne pas fonctionner, provoquant des erreurs déroutantes.

Pourquoi cela arrive : Vous supposez que les versions client et serveur sont toujours synchronisées, mais les hôtes distants sont souvent en retard.

Comment l'éviter : Exécutez docker version sur chaque contexte et comparez. S'il y a une différence de version majeure, envisagez de mettre à niveau le moteur ou de fixer votre CLI à une version compatible. Documentez la plage de versions prise en charge pour votre équipe.

Piège 4 : Coder en dur les noms de contexte dans les scripts et la CI

Ce qui se passe : Après la migration, votre pipeline CI référence toujours l'ancien nom de contexte, donc les déploiements échouent silencieusement ou vont vers le mauvais hôte.

Pourquoi cela arrive : Les noms de contexte sont intégrés dans les scripts shell et la configuration CI, et personne ne les recherche lors de la migration.

Comment l'éviter : Avant de basculer, recherchez dans votre base de code et les configurations CI l'ancien nom de contexte. Utilisez une variable de configuration au lieu d'une chaîne codée en dur si possible. Après la bascule, mettez à jour toutes les références dans le même ensemble de modifications et exécutez un déploiement de test.

Piège 5 : Garder des secrets dans les fichiers de contexte sans protection

Ce qui se passe : Vous créez un contexte avec des chemins de clés TLS ou des variables d'environnement contenant des secrets, puis vous copiez le contexte sur une autre machine, et les secrets finissent dans un dépôt public ou un système de fichiers partagé.

Pourquoi cela arrive : Les fichiers de contexte ne sont pas chiffrés, et les gens oublient qu'ils contiennent des éléments sensibles.

Comment l'éviter : Traitez les fichiers de contexte comme des secrets. Restreignez les permissions des fichiers, ne les validez jamais dans un contrôle de version, et utilisez la gestion des secrets (par exemple, les variables d'environnement ou un coffre) pour tout ce qui est vraiment sensible. Préférez les contextes SSH au TLS lorsque c'est possible pour éviter les fichiers de certificats.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant, pendant et après toute mise à niveau ou migration de contexte. Attribuez chaque élément à un seul propriétaire responsable (pas un groupe) et définissez une fréquence de révision.

Avant la migration

• [ ] Propriétaire : Ingénieur DevOps (par exemple, Priya Shah) – Exécutez docker version et docker context ls sur la configuration actuelle, et enregistrez la sortie dans le document de migration. Fréquence de révision : une fois par migration.
• [ ] Propriétaire : Développeur principal (par exemple, Alex Chen) – Identifiez toutes les applications et services qui utilisent le contexte actuel, y compris les scripts et les pipelines CI. Fréquence de révision : une fois par migration.
• [ ] Propriétaire : Ingénieur DevOps – Exportez tous les contextes existants à l'aide de docker context export et stockez les fichiers dans un emplacement sécurisé et versionné. Fréquence de révision : une fois par migration.
• [ ] Propriétaire : Ingénieur sécurité (par exemple, Jordan Lee) – Vérifiez qu'aucun secret n'est stocké en clair dans les fichiers de contexte ou les variables d'environnement. Remplacez par des références sécurisées. Fréquence de révision : avant chaque migration ou trimestriel.
• [ ] Propriétaire : Ingénieur DevOps – Créez le nouveau contexte sur une machine de test ou en utilisant un nouveau nom, et vérifiez la connectivité avec docker --context new-name ps. Fréquence de révision : une fois par migration.

Pendant la migration

• [ ] Propriétaire : Ingénieur DevOps – Basculez le contexte actif à l'aide de docker context use new-name et exécutez immédiatement docker ps et docker info pour confirmer que le nouvel hôte est joignable. Fréquence de révision : au moment du basculement.
• [ ] Propriétaire : Propriétaire de l'application (par exemple, Maria Garcia) – Exécutez des tests de fumée sur le nouvel hôte, y compris un test de redémarrage pour les services avec état. Fréquence de révision : immédiatement après le basculement.
• [ ] Propriétaire : Ingénieur DevOps – Gardez l'ancien contexte disponible et ne le supprimez pas jusqu'à la fermeture de la fenêtre de restauration (par exemple, 7 jours). Fréquence de révision : après le basculement, contrôle quotidien jusqu'à la fermeture de la fenêtre.

Après la migration

• [ ] Propriétaire : Ingénieur DevOps – Mettez à jour tous les pipelines CI/CD et scripts pour référencer le nouveau nom de contexte. Fréquence de révision : dans les 24 heures suivant le basculement.
• [ ] Propriétaire : Développeur principal – Exécutez un pipeline de déploiement complet sur le nouveau contexte et confirmez le succès. Fréquence de révision : dans les 48 heures suivant le basculement.
• [ ] Propriétaire : Ingénieur DevOps – Après l'expiration de la fenêtre de restauration, supprimez l'ancien contexte et mettez à jour la documentation. Fréquence de révision : après la fenêtre de restauration (par exemple, jour 8).
• [ ] Propriétaire : Ingénieur sécurité – Faites tourner les identifiants ou certificats qui ont été utilisés pendant la migration. Fréquence de révision : immédiatement après la migration, puis tous les 90 jours.

Conclusion

La mise à niveau et la migration des contextes Docker est une tâche relativement petite lorsque vous la traitez comme une opération contrôlée plutôt qu'une commande rapide. La clé est d'observer d'abord, de changer une chose à la fois de manière limitée, de vérifier avec des commandes concrètes et des sorties attendues, et de toujours garder un chemin de restauration.

Vous disposez maintenant d'un flux de travail complet : inventorier votre environnement, créer et tester un nouveau contexte sur une copie, basculer seulement après validation, surveiller les défaillances courantes et suivre une liste de contrôle avec une propriété explicite et des délais de révision. La prochaine étape est d'appliquer cela à votre propre configuration. Commencez par les commandes d'inventaire de la première section. Enregistrez ce que vous voyez. Ensuite, exportez un contexte comme sauvegarde. Ce n'est qu'après cela que vous devriez apporter des modifications.

Un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force une décision. Avec les contextes Docker, cela signifie que chaque migration doit se terminer par un nouvel environnement vérifié, une restauration documentée et aucun doute persistant sur l'endroit où vos conteneurs sont réellement exécutés.