Dépannage des contextes Docker : guide pratique pour diagnostiquer et récupérer

Introduction

Les contextes Docker sont une fonctionnalité puissante pour basculer entre différents démons Docker, mais lorsqu'ils sont mal configurés, ils provoquent des erreurs subtiles qui font perdre du temps aux développeurs. Ce guide propose une approche systématique pour identifier, diagnostiquer et récupérer des problèmes courants liés aux contextes Docker. En suivant les étapes pratiques, vous comprendrez votre environnement, vérifierez les configurations et restaurerez une configuration Docker fonctionnelle.

Cet article couvre :

• L'inventaire de votre version Docker et des paramètres de contexte.
• Des chemins de configuration sûrs pour éviter les changements cassants.
• Des commandes de diagnostic avec les sorties attendues.
• Les modes de défaillance courants et la récupération étape par étape.
• Une liste de contrôle opérationnelle reproductible.

Que vous basculiez entre des hôtes Docker locaux et distants, que vous utilisiez Docker Desktop ou un moteur distant, ce guide vous aidera à résoudre les problèmes rapidement et en toute confiance.

Inventaire de la version et de l'environnement

Avant de faire des modifications, enregistrez les versions exactes et la configuration actuelle du contexte. Cela établit un état connu et facilite le retour en arrière. Commencez par vérifier les versions du CLI Docker et du démon, listez tous les contextes et inspectez le contexte actif en détail.

Vérification des versions de Docker et du CLI

Exécutez la commande suivante pour voir les informations du client et du serveur :

docker version

Sortie attendue (abrégée) :

Client: Docker Engine - Community
 Version:           24.0.7
 API version:       1.43
 Go version:        go1.20.10
 Git commit:        311b9ff
 Built:             Thu Oct 26 09:08:15 2023
 OS/Arch:           linux/amd64
 Context:           default
Server: Docker Engine - Community
 Engine:
  Version:          24.0.7
  API version:      1.43 (minimum version 1.12)
  Go version:       go1.20.10
  Git commit:       311b9ff
  Built:            Thu Oct 26 09:07:41 2023
  OS/Arch:          linux/amd64
  Experimental:     false

Notez les versions du client et du serveur ; une incompatibilité peut causer des problèmes de compatibilité d'API. Par exemple, un CLI Docker version 24.0.7 utilisant l'API 1.43 ne peut pas communiquer avec un démon Docker qui ne supporte que l'API 1.41. Si les versions diffèrent significativement, envisagez de mettre à niveau ou de rétrograder l'un des composants.

Liste des contextes Docker

Affichez tous les contextes et identifiez le contexte actif (marqué d'un astérisque) :

docker context ls

Sortie attendue :

NAME       TYPE   DESCRIPTION                         DOCKER ENDPOINT               KUBERNETES ENDPOINT   ORCHESTRATOR
default    moby   Current DOCKER_HOST based config   unix:///var/run/docker.sock                       swarm
remote *   moby   Remote Docker host                 tcp://192.168.1.100:2375

L'astérisque indique le contexte actif. Si le contexte que vous attendez n'est pas actif, c'est un problème courant. Par exemple, après un redémarrage ou une mise à jour de Docker Desktop, le contexte actif peut revenir à default.

Inspection d'un contexte spécifique

Pour une configuration détaillée d'un contexte, utilisez :

docker context inspect <nom-du-contexte>

Exemple :

docker context inspect remote

Sortie attendue :

[
    {
        "Name": "remote",
        "Metadata": {},
        "Endpoints": {
            "docker": {
                "Host": "tcp://192.168.1.100:2375",
                "SkipTLSVerify": false
            }
        },
        "TLSMaterial": {},
        "Storage": {
            "MetadataPath": "/home/user/.docker/contexts/meta/...",
            "TLSPath": "/home/user/.docker/contexts/tls/..."
        }
    }
]

Vérifiez l'exactitude du champ Host. Les erreurs courantes incluent l'utilisation de http:// au lieu de tcp://, l'oubli du port ou la spécification d'une adresse IP qui n'est plus joignable.

Prérequis de l'environnement

Assurez-vous des éléments suivants avant de continuer :

• Le CLI Docker est installé et fonctionnel.
• Connectivité réseau au démon Docker (pour les contextes distants).
• Permissions suffisantes pour gérer les contextes Docker (généralement au niveau utilisateur, stockés dans ~/.docker/contexts).
• Pour les contextes avec TLS, des certificats client valides.

Documentez ces détails avant de faire des modifications. Par exemple, vous pouvez enregistrer la sortie de docker version et docker context ls dans un fichier :

docker version > docker-version-avant.txt
docker context ls > docker-contexts-avant.txt

Chemin de configuration sûr

Lorsque vous modifiez des contextes Docker, préférez les opérations non destructives et créez des sauvegardes pour permettre un retour en arrière. Cette section couvre la création de contextes, la commutation en toute sécurité, la sauvegarde des métadonnées, l'utilisation de variables d'environnement pour des remplacements temporaires et la portée des changements.

Création d'un contexte

Pour ajouter un nouveau contexte sans altérer les existants, utilisez docker context create. La syntaxe est :

docker context create <nom> --docker "host=<point-de-terminaison>"

Exemple :

docker context create myremote --docker "host=tcp://192.168.1.100:2375"

Sortie attendue :

myremote
Successfully created docker context "myremote"

Cette commande crée un nouveau contexte nommé myremote qui pointe vers le point de terminaison TCP. Des options supplémentaires comme --description, --docker "ca=...,cert=...,key=..." peuvent être utilisées pour TLS.

Commutation de contexte en toute sécurité

Basculez vers un contexte temporairement pour les tests :

docker context use myremote

Sortie attendue :

myremote
Current context is now "myremote"

Après les tests, revenez au contexte d'origine pour éviter d'affecter d'autres travaux. Par exemple, si vous utilisiez précédemment default, exécutez :

docker context use default

Notez que le changement de contexte modifie la cible du CLI Docker pour toutes les commandes suivantes dans le shell courant. Cela n'affecte pas les autres shells ou processus en arrière-plan.

Sauvegarde des métadonnées de contexte

Les métadonnées de contexte Docker sont stockées dans ~/.docker/contexts. Créez une sauvegarde avant de supprimer ou de modifier :

cp -r ~/.docker/contexts ~/.docker/contexts-backup-$(date +%Y%m%d)

Cela préserve toutes les définitions de contexte, y compris le matériel TLS. Pour restaurer plus tard, copiez la sauvegarde :

cp -r ~/.docker/contexts-backup-AAAAMMJJ ~/.docker/contexts

Utilisation des variables d'environnement comme remplacements

Pour des changements temporaires, définissez la variable d'environnement DOCKER_CONTEXT :

export DOCKER_CONTEXT=myremote
docker ps

Cela remplace le contexte actif uniquement pour la session shell actuelle. C'est utile pour tester un contexte sans changer le défaut global. Pour annuler, utilisez :

unset DOCKER_CONTEXT

Alternativement, vous pouvez utiliser le drapeau --context sur des commandes individuelles, qui a priorité sur le contexte actif et DOCKER_CONTEXT :

docker --context myremote ps

Portée des changements

• Évitez les modifications globales comme docker context rm sans sauvegarde.
• Préférez créer de nouveaux contextes et basculer plutôt que de modifier les existants.
• Testez les nouveaux contextes depuis un seul shell avant de les rendre par défaut.

Par exemple, si vous devez mettre à jour le point de terminaison d'un contexte existant, envisagez de créer un nouveau contexte avec les bons paramètres, de le tester, puis de supprimer l'ancien uniquement lorsque vous êtes sûr.

Vérification et diagnostics

Après avoir configuré un contexte, vérifiez qu'il fonctionne réellement en exécutant des commandes Docker de base et en vérifiant la connectivité. Cette section fournit une séquence de diagnostics pour confirmer que le contexte est fonctionnel.

Test de connectivité de base

Exécutez docker info pour confirmer que le démon répond :

docker info

Sortie attendue (champs clés) :

Client:
 Context:    myremote
 Debug Mode: false
Server:
 Containers: 3
  Running: 1
  Paused: 0
  Stopped: 2
 Images: 10
 Server Version: 24.0.7
 Storage Driver: overlay2
 ...

Si la commande se bloque ou expire, il peut y avoir un problème réseau ou le démon n'est pas en cours d'exécution. Utilisez docker info --format '{{.ServerVersion}}' pour obtenir rapidement la version du serveur :

docker info --format '{{.ServerVersion}}'

Test avec docker ps

Listez les conteneurs sur le contexte actif :

docker ps

Sortie attendue (lorsqu'aucun conteneur n'est en cours d'exécution) :

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Si la sortie est vide, le démon est joignable mais n'a pas de conteneurs en cours d'exécution. Pour voir tous les conteneurs (y compris arrêtés), utilisez docker ps -a.

Vérification des journaux

Les journaux du démon Docker peuvent révéler des problèmes de connexion. Cherchez les lignes contenant level=error ou msg="..." qui indiquent des échecs d'authentification, des problèmes TLS ou des problèmes réseau.

• Sur Linux avec systemd, utilisez :

journalctl -u docker.service -n 50 --no-pager

• Sur Docker Desktop, consultez les journaux du tableau de bord ou exécutez docker desktop logs (si disponible).

Par exemple, une erreur typique dans les journaux peut être :

level=error msg="Handler for GET /v1.43/containers/json returned error: error during connect: Get http://192.168.1.100:2375/v1.43/containers/json: dial tcp 192.168.1.100:2375: connect: connection refused"

Utilisation de docker context show

Confirmez quel contexte est actif :

docker context show

Sortie attendue :

myremote

Si la sortie est default mais que vous attendiez myremote, vous devez changer de contexte.

Diagnostic des problèmes TLS

Si vous rencontrez des erreurs de certificat, testez directement la connexion TLS avec curl. Pour un démon Docker sécurisé avec TLS sur le port 2376, exécutez :

curl https://192.168.1.100:2376/_ping --cacert ca.pem --cert cert.pem --key key.pem

Sortie attendue : OK si TLS est correctement configuré. Si vous obtenez une erreur de vérification de certificat, vérifiez le chemin du certificat CA et assurez-vous que le certificat client est valide. Pour les certificats auto-signés, vous pouvez définir SkipTLSVerify à true dans le contexte (non recommandé pour la production) ou utiliser le bon CA.

Vérification de la résolution du point de terminaison

Assurez-vous que le nom d'hôte ou l'adresse IP est joignable :

ping 192.168.1.100

Sortie attendue : réponses réussies. Si le ping échoue, vérifiez la connectivité réseau et les règles de pare-feu. Pour les vérifications de port TCP, utilisez nc (netcat) :

nc -zv 192.168.1.100 2375

Sortie attendue : Connection to 192.168.1.100 2375 port [tcp/*] succeeded!

Modes de défaillance et récupération

Cette section décrit les défaillances courantes des contextes Docker et fournit des procédures de récupération étape par étape.

Défaillance : "Cannot connect to the Docker daemon"

Cette erreur apparaît lorsque le CLI Docker ne peut pas joindre le démon au point de terminaison configuré. Les causes courantes incluent :

• Point de terminaison incorrect dans le contexte.
• Le démon Docker n'est pas en cours d'exécution.
• Problèmes de connectivité réseau ou pare-feu bloquant.
• Mauvaise configuration TLS.

Étapes de récupération :

1. Vérifiez si le démon est en cours d'exécution :

• Sur Linux : systemctl status docker
• Sur Docker Desktop : vérifiez que l'application est en cours d'exécution.

1. Vérifiez le point de terminaison :

   docker context inspect <contexte>

Assurez-vous que le champ Host est correct. Par exemple, s'il devrait être tcp://192.168.1.100:2375, cherchez les fautes de frappe.

1. Testez la connectivité réseau :

   nc -zv 192.168.1.100 2375

Devrait afficher open ou succeeded.

1. Si vous utilisez HTTPS, vérifiez les paramètres TLS comme décrit précédemment.
2. Consultez les journaux du démon Docker pour plus de détails.

Défaillance : "Error response from daemon: client version 1.44 is too new"

Cela indique que le CLI Docker est plus récent que le démon et que les versions d'API sont incompatibles. Par exemple, le CLI version 25.0.0 utilise l'API 1.44, mais le démon ne supporte que jusqu'à l'API 1.43.

Options de récupération :

• Rétrograder le CLI Docker vers une version compatible avec le démon.
• Mettre à niveau le démon Docker vers une version qui supporte la nouvelle API.
• Définir temporairement la variable d'environnement DOCKER_API_VERSION pour forcer une version d'API inférieure :

export DOCKER_API_VERSION=1.43
docker ps

Notez que cela peut ne pas fonctionner si le CLI utilise des fonctionnalités non disponibles dans l'ancienne API. Il est préférable d'aligner correctement les versions.

Défaillance : Contexte manquant après une mise à jour

Parfois, après une mise à jour de Docker Desktop ou une mise à niveau système, les contextes peuvent disparaître. Cela peut arriver si le processus de mise à jour réinitialise le répertoire ~/.docker/contexts ou s'il y a un problème de migration.

Récupération :

• Restaurez à partir d'une sauvegarde si vous en avez une :

  cp -r ~/.docker/contexts-backup-AAAAMMJJ/* ~/.docker/contexts/

• Recréez le contexte manuellement en utilisant docker context create.
• Vérifiez si le contexte existe dans un autre profil utilisateur ou une autre machine.

Défaillance : Échec de la vérification TLS

Cela se produit lorsque les certificats client sont expirés, invalides ou que le certificat CA n'est pas approuvé.

Récupération :

• Régénérez les certificats client et serveur en utilisant votre CA.
• Mettez à jour le contexte avec le nouveau matériel TLS :

  docker context update <contexte> --docker "host=tcp://192.168.1.100:2376,ca=/chemin/vers/ca.pem,cert=/chemin/vers/cert.pem,key=/chemin/vers/key.pem"

• Testez la connexion TLS avec curl comme montré précédemment.
• Si vous utilisez des certificats auto-signés, envisagez de définir SkipTLSVerify=true temporairement pour les tests (non sécurisé pour la production).

Procédure de retour en arrière

Si un nouveau contexte ne fonctionne pas, revenez à un contexte connu comme bon :

docker context use default

Si un contexte a été supprimé par erreur, restaurez à partir de la sauvegarde :

cp -r ~/.docker/contexts-backup-AAAAMMJJ/meta/* ~/.docker/contexts/meta/
cp -r ~/.docker/contexts-backup-AAAAMMJJ/tls/* ~/.docker/contexts/tls/

Puis vérifiez avec docker context ls.

Exemple de flux de récupération

Scénario : Vous avez créé un contexte "badremote" avec la mauvaise adresse IP 192.168.1.99 et vous y avez basculé. Maintenant, les commandes Docker échouent avec "Cannot connect to the Docker daemon".

Récupération étape par étape :

1. Identifiez le contexte actif :

   docker context show

Sortie : badremote

1. Revenez à un contexte connu comme bon :

   docker context use default

Sortie : Current context is now "default"

1. Supprimez le contexte défectueux :

   docker context rm badremote

Sortie : badremote (supprimé)

1. Recréez le contexte avec la bonne adresse IP :

   docker context create goodremote --docker "host=tcp://192.168.1.101:2375"

1. Testez le nouveau contexte :

   docker context use goodremote
   docker info

Si docker info renvoie les détails du serveur, le contexte fonctionne. Sinon, répétez les diagnostics.

Liste de contrôle opérationnelle

Utilisez la liste de contrôle suivante pour les opérations de routine et le dépannage des contextes Docker. Elle résume les commandes et vérifications clés dans un format tabulaire pour une référence rapide.

Passez régulièrement en revue les contextes et élaguez ceux qui ne sont plus utilisés pour éviter la confusion. Par exemple, exécutez docker context ls mensuellement et supprimez les contextes qui ne sont plus nécessaires. Documentez également l'objectif de chaque contexte dans le champ de description pour faciliter leur identification ultérieure.

Conclusion

Le dépannage des contextes Docker devient gérable avec une approche systématique : inventoriez votre environnement, configurez en toute sécurité, vérifiez avec des commandes pratiques et récupérez en utilisant des modèles connus. En suivant les étapes de ce guide, vous pouvez résoudre la plupart des problèmes de contexte sans temps d'arrêt.

Points clés à retenir :

• Vérifiez toujours docker version et docker context ls en premier.
• Utilisez la création et la commutation non destructives, et sauvegardez les données de contexte.
• Vérifiez la connectivité avec docker info et docker ps.
• Sachez comment revenir à un contexte fonctionnel.
• Maintenez une liste de contrôle opérationnelle pour la cohérence.

Prochaines étapes : appliquez ces techniques à votre configuration Docker actuelle, documentez vos contextes spécifiques et établissez une routine de sauvegarde. Envisagez d'automatiser les sauvegardes de contexte avec une tâche cron ou un script pour vous assurer d'avoir toujours une copie récente.