Dépannage - Erreur DNS de Docker au build

1 Symptôme

Au moment d'exécuter ./construire.sh ou docker build, la commande échoue dès l'étape FROM avec un message comme celui-ci :

Message d'erreur typique

Step 1/6 : FROM httpd:alpine
Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io on [::1]:53: read udp [::1]:50506->[::1]:53: read: connection refused

Le détail révélateur est [::1]:53 : Docker tente d'interroger un serveur DNS sur le loopback IPv6 local, où aucun service n'écoute.

2 Cause

Pourquoi cela arrive

Le démon Docker hérite des serveurs DNS du système. Si /etc/resolv.conf contient une référence à 127.0.0.53 (systemd-resolved) ou à une adresse loopback IPv6, Docker la copie tel quel à l'intérieur des conteneurs de build, où ce loopback ne pointe sur rien d'utile. La résolution échoue, le pull aussi.

L'hôte, lui, continue à résoudre les noms sans problème (le service écoute bien sur son propre loopback). C'est uniquement le contexte d'exécution du build Docker qui est aveugle.

3 Maintenance et opérations

La correction consiste à fournir au démon Docker une liste de serveurs DNS publics fiables, indépendants de la configuration locale.

1

Confirmer le diagnostic

Vérifier que l'hôte résout bien le registre, ce qui exclut un problème de connectivité.

getent hosts registry-1.docker.io

Si la commande renvoie une ou plusieurs adresses IP, le réseau de la machine fonctionne. Le problème est bien côté démon Docker.

2

Configurer le DNS du démon

Créer ou compléter le fichier /etc/docker/daemon.json avec une liste de résolveurs publics. Si le fichier existe déjà, fusionner la clé dns avec le contenu en place plutôt que d'écraser.

echo '{"dns": ["1.1.1.1", "8.8.8.8"]}' | sudo tee /etc/docker/daemon.json

À propos des adresses choisies

1.1.1.1 (Cloudflare) et 8.8.8.8 (Google) sont des résolveurs publics rapides et stables. En contexte d'établissement scolaire, demandez d'abord les serveurs DNS officiels au service informatique : ils peuvent être obligatoires pour respecter le filtrage du réseau.

3

Redémarrer le démon Docker

Le démon ne relit pas daemon.json automatiquement, un redémarrage est nécessaire pour appliquer la nouvelle configuration DNS.

sudo systemctl restart docker

Effet sur les conteneurs en marche

Tous les conteneurs sont brièvement arrêtés (5 à 10 secondes). Ceux qui ont été lancés avec l'option --restart unless-stopped redémarrent seuls. Évitez de faire cette opération en pleine démonstration de classe : faites-la avant.

4

Valider la correction

Reconstruire l'image, ou tester directement le pull pour isoler le résultat.

docker pull httpd:alpine

Résultat attendu

Les couches de l'image se téléchargent normalement et la commande se termine par Status: Downloaded newer image ou Image is up to date.

4 Prévention pour les postes du laboratoire

Pour éviter que chaque étudiant rencontre l'erreur lors du tout premier build, deux options selon la maîtrise du parc de postes :

Approvisionnement initial : déployer /etc/docker/daemon.json en même temps que l'installation de Docker, via le script de préparation des postes.
Pré-téléchargement des images de base : faire un docker pull httpd:alpine et autres images du cours sur l'image disque de référence. Cela protège aussi contre les coupures réseau ponctuelles pendant les démonstrations.

Variante sans daemon.json

Sur un poste où l'on ne souhaite pas modifier la configuration globale, on peut passer le DNS uniquement à un conteneur en cours d'exécution avec --dns 1.1.1.1. Attention, cette option ne s'applique qu'aux conteneurs déjà construits, pas à l'étape de pull du build.