Erreurs courantes des contextes Docker et correctifs : guide pratique de dépannage

Introduction

Les contextes Docker vous permettent de basculer entre différents démons, points de terminaison et environnements Docker sans modifier constamment les fichiers de configuration ou les variables d'environnement. Un contexte regroupe le point de terminaison de l'hôte Docker, les paramètres TLS et l'espace de noms par défaut, de sorte qu'une seule commande peut pointer vers le moteur local, un hôte SSH distant ou un point de terminaison Kubernetes. Lorsqu'un contexte est manquant, mal configuré ou pointe vers le mauvais point de terminaison, l'échec est généralement rapide et déroutant : l'interface en ligne de commande signale des erreurs comme Cannot connect to the Docker daemon, context not found, ou les commandes s'exécutent silencieusement contre le mauvais environnement.

Ce guide se concentre sur les erreurs de contexte Docker les plus courantes et leurs solutions concrètes. Il est destiné aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui doivent passer d'un problème observé à un résultat vérifié sans deviner. Chaque section comprend les commandes pour inspecter l'état actuel, la sortie attendue et les étapes de récupération. L'objectif 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 le résultat et documenter la procédure de récupération si l'état attendu n'est pas atteint.

Vous n'avez pas besoin d'un laboratoire ni d'une connaissance approfondie des rouages internes de Docker. Une CLI Docker fonctionnelle et la capacité d'exécuter les commandes ci-dessous suffisent. Cependant, si votre environnement utilise Docker Desktop, Docker Compose ou un démon distant, certains prérequis s'appliquent, et ceux-ci sont signalés dans les sections concernées.

Inventaire des versions et de l'environnement

Avant de corriger une erreur de contexte, enregistrez la version exacte et la topologie. Cela évite d'appliquer un correctif pour Docker 20.10 à un système fonctionnant sous Docker 24.0 et de modifier le mauvais contexte. Exécutez ces commandes en lecture seule et sauvegardez la sortie :

docker version

Cela affiche à la fois la version du client et celle du serveur (démon). Si la ligne du serveur est manquante, l'interface en ligne de commande ne peut pas atteindre le démon du contexte actuel.

docker context ls

Cela liste tous les contextes avec un marqueur (*) pour le contexte actuel. Par exemple :

NAME                TYPE                DESCRIPTION                               DOCKER ENDPOINT                KUBERNETES ENDPOINT   ORCHESTRATOR
default *           moby                Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                         swarm
remote-ssh          ssh                 SSH context to staging                    ssh://[email protected]

Si le contexte attendu est manquant, quelqu'un l'a peut-être supprimé, ou le répertoire de configuration a été remplacé. Si le point de terminaison par défaut attendu est différent, DOCKER_HOST ou DOCKER_CONTEXT peuvent remplacer le contexte actuel.

docker context inspect <nom-du-contexte>

Cela affiche la configuration complète d'un contexte. Inspectez un contexte avant de le modifier :

docker context inspect remote-ssh

[
    {
        "Name": "remote-ssh",
        "Metadata": {},
        "Endpoints": {
            "docker": {
                "Host": "ssh://[email protected]",
                "SkipTLSVerify": false
            }
        },
        "TLSMaterial": {},
        "Storage": {
            "MetadataPath": "/home/user/.docker/contexts/meta/abc123...",
            "TLSPath": "/home/user/.docker/contexts/tls/abc123..."
        }
    }
]

L'inspection révèle également si le matériel TLS est configuré. Si le point de terminaison est https:// mais que le contexte n'a pas de matériel TLS, les connexions échoueront avec des erreurs de certificat.

Confirmez le contexte actuel et les variables d'environnement qui peuvent le remplacer :

docker context show
echo $DOCKER_HOST
echo $DOCKER_CONTEXT

L'ordre de résolution de Docker est : drapeau --context (par commande) > variable d'environnement DOCKER_CONTEXT > contexte actuel de la configuration CLI. DOCKER_HOST s'applique toujours au contexte default mais peut prêter à confusion lorsque d'autres contextes sont utilisés.

Pour les projets Compose, exécutez docker compose ps, docker compose logs -f <service> et docker compose exec <service> sh uniquement après avoir confirmé que le contexte actuel pointe vers la machine où les conteneurs du fichier Compose doivent s'exécuter.

La persistance des données entre les contextes est une défaillance cachée courante. Un volume nommé comme app_data:/var/lib/app est géré par Docker et généralement plus facile à réutiliser lors des reconstructions de conteneurs. Un montage de liaison comme ./data:/var/lib/app mappe directement un répertoire hôte et est utile pour le développement local, mais peut exposer des problèmes de permissions, de portabilité et de sauvegarde si le même chemin n'existe pas sur une autre machine. Les contextes ne modifient pas les volumes, mais ils changent le démon sur lequel les conteneurs s'exécutent. Avant de changer de contexte, vérifiez où vivent les données :

# Sur le contexte actuel
docker volume ls
docker volume inspect app_data

Un test local de type production devrait inclure un test de redémarrage : arrêtez le conteneur, recréez-le et confirmez que l'application voit toujours les fichiers attendus. Si les données disparaissent, le service écrivait probablement dans le système de fichiers du conteneur au lieu d'un volume ou d'un montage.

Chemin de configuration sûr

La plupart des erreurs de contexte sont corrigées en mettant à jour la configuration du contexte elle-même. Le chemin sûr est : lister les contextes, inspecter le contexte actuel, créer ou mettre à jour un contexte avec des paramètres explicites, puis basculer dessus et vérifier avec une commande inoffensive.

Commencez par identifier les contextes et le contexte actuel :

docker context ls
docker context show

Si vous devez vous connecter à un démon Docker distant via SSH, créez un nouveau contexte avec le type ssh :

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

Pour un démon Docker exposé en HTTPS avec TLS, créez un contexte puis définissez le matériel TLS :

docker context create secure-remote --docker "host=https://prod.example.com:2376"
docker context update secure-remote --docker "ca=$PWD/ca.pem,cert=$PWD/cert.pem,key=$PWD/key.pem"

Remarque : Les chemins dans ca, cert et key sont stockés dans les métadonnées du contexte. Si les fichiers sont déplacés ultérieurement, Docker conserve des copies du matériel TLS dans le répertoire de stockage du contexte et les utilisera. Pour utiliser délibérément un nouveau matériel TLS, exécutez à nouveau docker context update avec les nouveaux chemins.

Si vous devez mettre à jour le point de terminaison d'un contexte existant (par exemple, l'hôte SSH a changé) :

docker context update existing-context --docker "host=ssh://newuser@newhost"

Pour supprimer un contexte obsolète :

docker context rm old-context

Si le contexte que vous essayez de supprimer est actuellement actif, Docker renvoie une erreur. Basculez d'abord vers un autre contexte :

docker context use default
docker context rm old-context

Après avoir modifié un contexte, vérifiez-le toujours sans rien altérer :

docker context use remote-prod
docker ps

docker ps devrait lister les conteneurs en cours d'exécution sur le démon distant. En cas d'échec, inspectez le contexte et la joignabilité du démon.

L'une des erreurs les plus courantes est de modifier à la main l'entrée du contexte actuel dans le fichier ~/.docker/config.json. La clé current est mise à jour par la commande docker context use et ne doit pas être modifiée manuellement. Une modification manuelle peut créer un nom de contexte qui ne correspond à aucune entrée dans contexts, entraînant des erreurs context not found à chaque commande. Si vous soupçonnez que cela s'est produit, utilisez docker context use <contexte-existant> pour réinitialiser le pointeur actuel.

Vérification et diagnostic

Après un changement de contexte, la vérification doit porter à la fois sur la configuration du contexte et sur la capacité à effectuer une opération réelle contre le démon sélectionné. Utilisez d'abord des commandes en lecture seule.

Vérifiez le contexte actuel et son point de terminaison :

docker context show
docker context inspect $(docker context show) --format '{{.Endpoints.docker.Host}}'

Testez ensuite la connexion avec une commande qui ne modifie pas l'état :

docker info

docker info affiche des détails sur le démon, notamment le nombre de conteneurs, d'images et la version du serveur. C'est un signal fort que l'interface en ligne de commande peut communiquer. Si elle se bloque, le point de terminaison est injoignable. Si elle renvoie une erreur TLS, vérifiez les certificats dans le contexte.

Pour un conteneur qui devrait être en cours d'exécution, vérifiez son état :

docker ps --filter "name=my-app"

Si le conteneur n'est pas listé, vérifiez tous les conteneurs, y compris ceux arrêtés :

docker ps -a --filter "name=my-app"

Si le conteneur s'est arrêté, inspectez ses journaux et son code de sortie :

docker logs my-app --tail 100
docker inspect my-app --format '{{.State.ExitCode}} {{.State.Error}}'

Le diagnostic doit toujours séparer l'observation de l'intervention. Capturez d'abord l'état actuel et les horodatages, protégez les informations d'identification et le matériel privé, puis ne modifiez qu'un élément limité lorsque son rayon d'impact et son chemin de récupération sont compris.

Pour les projets Compose, les vérifications équivalentes sont :

docker compose ps
docker compose logs -f <service>
docker compose exec <service> sh

Mais n'oubliez pas que Compose utilisera le contexte actuel. Si docker compose up -d ne produit aucun effet visible, exécutez docker compose ps et vérifiez quel démon il signale. S'il signale des conteneurs sur le moteur local alors que vous attendiez l'hôte de préproduction distant, le contexte actuel est incorrect.

Exemple de discordance de contexte :

$ docker context ls
NAME       DESCRIPTION                               DOCKER ENDPOINT
default *  Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
staging    Staging server                            ssh://[email protected]

$ docker compose up -d
[+] Running 2/2
 ✔ Network myapp_default  Created
 ✔ Container myapp-db-1   Started

Mais lorsque vous vérifiez le serveur de préproduction distant, les conteneurs n'y sont pas. Le contexte actuel était default, pas staging. La solution est de basculer et de réexécuter :

docker context use staging
docker compose up -d

Vérifiez également le contexte pour les opérations individuelles sur les conteneurs :

docker context use staging
docker ps

Si docker ps affiche toujours des conteneurs locaux, vérifiez DOCKER_HOST ou DOCKER_CONTEXT :

echo $DOCKER_HOST
echo $DOCKER_CONTEXT

Si DOCKER_HOST est défini sur une valeur non vide, il peut remplacer le contexte uniquement pour le contexte default ; les autres contextes ne sont pas affectés. Si DOCKER_CONTEXT est défini, il remplace le contexte actuel pour toutes les commandes. Désactivez-le s'il cause de la confusion :

unset DOCKER_CONTEXT

Pour les contextes SSH distants, l'authentification par clé SSH doit être correctement configurée. Si docker ps renvoie permission denied (publickey), vérifiez que l'utilisateur et la clé sont corrects :

ssh -T [email protected]

Si SSH fonctionne mais que les commandes Docker échouent, l'utilisateur distant n'a peut-être pas la permission d'accéder au socket Docker. Sur l'hôte distant, ajoutez l'utilisateur au groupe docker ou utilisez un utilisateur SSH disposant des bonnes permissions.

Modes de défaillance et récupération

Cette section couvre les modes de défaillance les plus fréquemment observés pour les contextes Docker et les étapes de récupération.

1. Contexte introuvable

Symptôme : L'exécution de toute commande Docker renvoie une erreur comme :

context not found: my-context

Cause : Le contexte actuel dans ~/.docker/config.json fait référence à un nom de contexte qui n'existe pas dans la carte contexts. Cela peut se produire après une modification manuelle, une migration partielle ou un outil qui a enregistré une configuration invalide.

Récupération : Listez les contextes disponibles et basculez vers un contexte valide :

docker context ls
docker context use default

Si le contexte dont vous avez besoin est réellement manquant, recréez-le à partir de paramètres connus, comme indiqué dans la section Chemin de configuration sûr.

2. Impossible de se connecter au démon Docker

Symptôme :

error during connect: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json: dial unix /var/run/docker.sock: connect: no such file or directory

ou pour les contextes distants :

error during connect: Get https://prod.example.com:2376/v1.24/containers/json: net/http: TLS handshake timeout

Cause : Le contexte actuel pointe vers un démon qui n'est pas en cours d'exécution, n'est pas joignable, ou un pare-feu réseau bloque le port. Pour les contextes locaux, le démon Docker n'est peut-être pas démarré (courant sur Linux après un redémarrage). Pour les contextes distants, l'hôte est peut-être hors ligne ou le port TLS est bloqué.

Récupération :

• Pour le local : démarrez Docker (sudo systemctl start docker sur Linux, ou démarrez Docker Desktop).
• Pour le distant : testez la connectivité réseau et l'état du démon sur l'hôte distant.

# Depuis le local
ping prod.example.com
nc -zv prod.example.com 2376

# Sur l'hôte distant
sudo systemctl status docker

Si le port est bloqué, ajustez les règles du pare-feu ou utilisez plutôt un contexte SSH.

3. Échec de la vérification du certificat TLS

Symptôme :

x509: certificate signed by unknown authority

Cause : Le contexte est configuré pour HTTPS avec vérification TLS, mais le certificat CA est manquant, incorrect ou expiré. Le certificat du serveur peut ne pas correspondre au nom d'hôte.

Récupération : Inspectez le matériel TLS du contexte :

docker context inspect <nom-du-contexte>

Vérifiez la date d'expiration du certificat CA :

openssl x509 -in /chemin/vers/ca.pem -noout -dates

Mettez à jour le contexte avec les certificats corrects :

docker context update <nom-du-contexte> --docker "ca=/nouveau/ca.pem,cert=/nouveau/cert.pem,key=/nouveau/key.pem"

Ne définissez pas SkipTLSVerify sur true en production ; cela désactive la vérification et permet les attaques de l'homme du milieu. Si le point de terminaison est interne et utilise des certificats auto-signés, ajoutez le bon CA au contexte.

4. Mauvais contexte utilisé silencieusement

Symptôme : Les commandes réussissent mais affectent le mauvais démon. Vous pouvez déployer sur localhost alors que vous vouliez déployer sur la préproduction.

Cause : Le contexte actuel n'est pas celui que vous pensiez, ou une variable d'environnement le remplace.

Récupération : Avant toute action destructrice, vérifiez le contexte actuel :

docker context show

S'il est incorrect, basculez :

docker context use <contexte-prévu>

Pour éviter les surprises, adoptez la pratique de toujours exécuter docker context show au début d'un script de déploiement, ou utilisez explicitement le drapeau --context sur chaque commande Docker dans les scripts :

docker --context staging ps

Ce drapeau a priorité sur le contexte actuel et les variables d'environnement, rendant la cible explicite.

5. Contexte créé avec un mauvais type de point de terminaison

Symptôme : Vous avez créé un contexte avec host=tcp://... mais le démon distant exige SSH. La connexion échoue avec des erreurs de protocole.

Cause : Le type ou le protocole du point de terminaison est incorrect.

Récupération : Recréez le contexte avec le bon type. Pour SSH :

docker context rm wrong-context
docker context create right-context --docker "host=ssh://user@host"

Si le démon prend en charge à la fois TCP et SSH, préférez SSH pour le chiffrement intégré et l'authentification par clé.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après tout changement lié au contexte. Chaque élément nomme le responsable (une personne, pas un groupe) et la fréquence de révision recommandée.

Chaque élément de la liste de contrôle doit être exécuté dans l'ordre. En cas d'échec d'une vérification, arrêtez-vous et diagnostiquez avant de continuer. Le responsable indiqué est chargé de s'assurer que l'étape est effectuée correctement et répétée à la fréquence indiquée.

Pièges courants et comment les éviter

Cette section résume les erreurs les plus courantes qui conduisent à des erreurs de contexte Docker, avec des conseils pratiques pour les éviter ou s'en remettre.

Piège 1 : Modifier ~/.docker/config.json à la main

Pourquoi cela arrive : Il semble simple de changer le contexte actuel ou d'ajouter une entrée de contexte directement dans le fichier JSON.

Comment l'éviter : Utilisez toujours les commandes docker context (create, update, use, rm, inspect). Elles valident les entrées et maintiennent la cohérence.

Récupération si cela est fait : Exécutez docker context ls pour voir si Docker peut analyser la configuration. Sinon, restaurez à partir d'une sauvegarde ou supprimez le fichier (perdant tous les contextes mais permettant un nouveau départ). Recréez ensuite les contextes.

Piège 2 : Ignorer les remplacements de variables d'environnement

Pourquoi cela arrive : DOCKER_HOST et DOCKER_CONTEXT sont souvent définis dans les profils shell ou les pipelines CI et oubliés.

Comment l'éviter : Vérifiez ces variables avant d'exécuter des commandes Docker, en particulier dans les scripts. Utilisez le drapeau --context pour forcer le contexte prévu.

Récupération : unset DOCKER_HOST DOCKER_CONTEXT ou définissez-les sur les valeurs correctes. Dans la CI, assurez-vous que l'environnement est propre.

Piège 3 : Utiliser SkipTLSVerify=true pour faire taire les erreurs de certificat

Pourquoi cela arrive : Cela élimine immédiatement les erreurs TLS.

Comment l'éviter : Fournissez toujours des certificats CA et des certificats de serveur corrects. Utilisez SkipTLSVerify=false dans tout environnement contenant des données réelles.

Récupération : Mettez à jour le contexte avec un matériel TLS approprié et définissez SkipTLSVerify=false.

Piège 4 : Supposer que les volumes de données se déplacent entre les contextes

Pourquoi cela arrive : Le même nom de conteneur et la même image peuvent s'exécuter sur différents démons, mais les volumes sont locaux au démon.

Comment l'éviter : Avant de changer de contexte, sauvegardez les volumes ou utilisez un pilote de stockage qui peut être attaché au démon cible.

Récupération : Copiez les données du volume de l'ancien démon vers le nouveau en utilisant docker run --rm -v app_data:/data alpine tar czf - /data | ssh target 'docker run --rm -i -v app_data:/data alpine tar xzf -'.

Piège 5 : Créer un contexte avec un point de terminaison ou un utilisateur mal orthographié

Pourquoi cela arrive : Les fautes de frappe dans la chaîne d'hôte ou le nom d'utilisateur sont courantes.

Comment l'éviter : Testez la connectivité SSH avant de créer le contexte : ssh -T user@host.

Récupération : Mettez à jour le contexte avec le bon point de terminaison ou supprimez-le et recréez-le.

Conclusion

Les erreurs de contexte Docker sont généralement simples à corriger une fois que vous savez comment inspecter la configuration actuelle et vérifier la connexion au démon prévu. La clé est d'agir délibérément : enregistrez l'état actuel, identifiez précisément l'erreur, appliquez le plus petit changement susceptible de la corriger et vérifiez avec une commande en lecture seule avant de faire quoi que ce soit de destructeur.

Ce guide a couvert l'inventaire des versions et de l'environnement nécessaire pour établir une base de référence, le chemin de configuration sûr pour créer et mettre à jour les contextes, les diagnostics pour la vérification, les modes de défaillance spécifiques avec les étapes de récupération, une liste de contrôle des opérations avec une propriété claire et une cadence de révision, et les pièges courants avec des stratégies d'évitement.

Comme prochaine étape, choisissez une vérification à faible risque pour votre propre environnement. Exécutez docker context show et docker ps sur chaque contexte que vous utilisez régulièrement. Comparez les résultats avec vos attentes. Si un contexte pointe vers le mauvais point de terminaison ou ne parvient pas à se connecter, suivez les étapes de récupération de ce guide. Ensuite, examinez l'utilisation par votre équipe des variables d'environnement comme DOCKER_CONTEXT et DOCKER_HOST pour éviter les discordances silencieuses.

Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Avec les commandes et les vérifications de ce guide, vous pouvez maintenir les contextes Docker fiables et éviter les pièges courants qui font perdre des heures de débogage.