E-NO
DevOps 10 min de lecture

Dépannage réseau de Docker BuildKit avec exemples pratiques

calendar_today Publié : 2026-11-03
update Dernière mise à jour : 2026-11-03
analytics Efficacité SEO : 100%
Illustration du guide technique pour « Dépannage réseau de Docker BuildKit avec exemples pratiques ».

Introduction

Docker BuildKit est le moteur moderne pour la construction d'images de conteneurs. Il apporte des constructions parallèles, une meilleure mise en cache et des fonctionnalités avancées comme les secrets et le transfert SSH, mais il introduit également un nouveau comportement réseau qui peut dérouter même les développeurs expérimentés. Lorsqu'une construction qui fonctionnait avec l'ancien générateur échoue soudainement avec des erreurs DNS, des messages de délai d'attente ou une incapacité à atteindre des services externes, la cause profonde réside souvent dans la configuration réseau de BuildKit.

Ce guide propose une approche systématique pour diagnostiquer et corriger les problèmes réseau de BuildKit. Vous apprendrez à recueillir les bonnes informations sur votre environnement, à appliquer des modifications de configuration en toute sécurité, à tester efficacement la connectivité et à récupérer après les modes de défaillance courants. Chaque commande inclut la sortie attendue afin que vous puissiez comparer directement les résultats.

À la fin de cet article, vous serez en mesure de résoudre des problèmes tels que :

  • Échecs de résolution DNS à l'intérieur des conteneurs de construction
  • Impossibilité de se connecter aux dépôts de paquets externes
  • Services hôtes inaccessibles depuis les étapes de construction
  • Performances réseau lentes pendant les constructions

Nous éviterons les conjectures en suivant un chemin de dépannage structuré. Les techniques présentées ici fonctionnent sur les hôtes Linux, macOS et Windows exécutant Docker 20.10 ou version ultérieure avec BuildKit activé par défaut.

Inventaire des versions et de l'environnement

Avant de modifier toute configuration, vous devez avoir une vision claire de votre système. Commencez par collecter les informations de version de Docker et de BuildKit. Cela permet d'identifier les bogues connus et de s'assurer que vous utilisez une configuration prise en charge.

Ouvrez un terminal et exécutez :

docker version

La sortie attendue inclut les versions du client et du serveur, comme :

Client: Docker Engine - Community
 Version:           24.0.5
 API version:       1.43
 Go version:        go1.20.6
 Git commit:        ced0996
 Built:             Fri Jul 21 18:20:40 2023
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          24.0.5
  API version:      1.43 (minimum version 1.12)
  Go version:       go1.20.6
  Git commit:       a61e2b4
  Built:            Fri Jul 21 18:20:40 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.21
  GitCommit:        3dce8eb055cbb6874e1c4c0f4e5c5b1d5a0a4e1
 runc:
  Version:          1.1.7
  GitCommit:        v1.1.7-0-g860f061
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Notez la version de Docker Engine et si BuildKit est le générateur par défaut. À partir de Docker 23.0, BuildKit est le générateur par défaut pour toutes les constructions. Pour vérifier explicitement le générateur actuel :

docker buildx ls

Sortie typique :

NAME/NODE       DRIVER/ENDPOINT STATUS  BUILDKIT             PLATFORMS
default *       docker
  default       default         running 23.0.3               linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6

Si vous voyez « buildkit » sous BUILDKIT, vous êtes sur BuildKit. Sinon, vous pouvez l'activer en définissant la variable d'environnement DOCKER_BUILDKIT=1 ou en configurant le démon.

Ensuite, examinez la configuration réseau du démon Docker. Le démon gère le réseau pont par défaut, les paramètres DNS et le MTU. Exécutez :

docker network ls

La sortie liste les réseaux existants :

NETWORK ID     NAME      DRIVER    SCOPE
9f904e7c5d7a   bridge    bridge    local
2a9bc1e4b9dc   host      host      local
c24e0d1f3a5f   none      null      local

Les conteneurs de construction BuildKit s'attachent généralement à un réseau dédié. Vous pouvez inspecter le pont par défaut pour voir son sous-réseau et sa passerelle :

docker network inspect bridge

Les champs pertinents incluent :

[
    {
        "Name": "bridge",
        "Id": "...",
        "Created": "...",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": [
                {
                    "Subnet": "172.17.0.0/16",
                    "Gateway": "172.17.0.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {},
        "Options": {
            "com.docker.network.bridge.default_bridge": "true",
            "com.docker.network.bridge.enable_icc": "true",
            "com.docker.network.bridge.enable_ip_masquerade": "true",
            "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
            "com.docker.network.bridge.name": "docker0",
            "com.docker.network.driver.mtu": "1500"
        },
        "Labels": {}
    }
]

Notez la valeur MTU. Dans certains environnements, comme les VPN ou les réseaux superposés, le MTU de l'hôte peut être inférieur à 1500. BuildKit hérite du MTU du démon Docker par défaut, et une incompatibilité peut provoquer des blocages réseau ou des délais d'attente.

Vérifiez également la configuration DNS de l'hôte, car BuildKit transfère les requêtes DNS au résolveur de l'hôte. Sous Linux, inspectez /etc/resolv.conf :

cat /etc/resolv.conf

Exemple :

nameserver 127.0.0.53
options edns0 trust-ad
search example.com

Sur macOS, utilisez scutil --dns. Sur Windows, exécutez ipconfig /all et recherchez les serveurs DNS.

Enfin, confirmez que vous pouvez atteindre Internet depuis l'hôte. Un test rapide :

ping -c 1 8.8.8.8

Si cela échoue, le problème peut être au niveau de l'hôte, et non spécifique à BuildKit. De même, testez la résolution DNS :

nslookup google.com

Rassemblez toutes ces informations dans un tableau d'inventaire simple pour référence :

ComposantVersion / ValeurNotes
Docker Engine24.0.5Vérifiez le dernier correctif
Version BuildKit23.0.3 (depuis buildx ls)Générateur par défaut
Sous-réseau réseau par défaut172.17.0.0/16Passerelle 172.17.0.1
MTU sur docker01500Comparez avec l'interface hôte
Serveur DNS hôte127.0.0.53systemd-resolved local
Accès Internet hôteOKping 8.8.8.8 fonctionne

Cet inventaire vous permet de repérer rapidement les incohérences et fournit une base de référence pour les comparaisons ultérieures.

Question rapide 1 sur 2

Selon le passage de référence, quelle est l'adresse du serveur DNS par défaut utilisée par les conteneurs sur un réseau personnalisé dans Docker ?

Le passage indique que les conteneurs sur un réseau personnalisé utilisent le serveur DNS intégré de Docker, dont l'adresse est 127.0.0.11.

Chemin de configuration sûr

Les modifications de configuration peuvent casser les constructions existantes. Faites toujours de petits changements réversibles et testez après chacun. Privilégiez les options spécifiques à BuildKit plutôt que les modifications globales du démon Docker chaque fois que possible. Cette section décrit des moyens sûrs d'ajuster le comportement réseau de BuildKit.

Utiliser les paramètres DNS au moment de la construction

BuildKit vous permet de remplacer les serveurs DNS et les domaines de recherche pour les conteneurs de construction sans affecter l'hôte. Vous pouvez les définir dans le Dockerfile en utilisant les arguments de construction --dns et --dns-search ou via la ligne de commande docker build.

Pour une construction unique, utilisez :

docker build --dns 8.8.8.8 --dns 1.1.1.1 -t monimage .

Alternativement, vous pouvez les définir dans le Dockerfile en utilisant les instructions ARG et RUN avec des paramètres --network explicites, mais la ligne de commande est plus simple. Si vous devez définir le DNS de manière permanente pour toutes les constructions, configurez le démon Docker. Sous Linux, éditez /etc/docker/daemon.json et ajoutez :

{
  "dns": ["8.8.8.8", "1.1.1.1"],
  "dns-search": ["example.com"]
}

Puis redémarrez Docker :

sudo systemctl restart docker

Cela s'applique à tous les conteneurs, y compris les conteneurs de construction. Cependant, c'est un changement global, donc testez d'abord avec la substitution en ligne de commande.

Configurer le mode réseau pour les constructions

Par défaut, BuildKit exécute chaque étape de construction dans son propre espace de noms réseau avec NAT vers l'hôte. Cet isolement peut causer des problèmes lorsque la construction doit accéder à des services sur l'hôte ou sur un réseau local. Vous pouvez changer le mode réseau par construction en utilisant le drapeau --network.

Par exemple, pour permettre à la construction d'utiliser directement la pile réseau de l'hôte, ce qui peut contourner de nombreux problèmes de routage :

docker build --network=host -t monimage .

Cela est utile pour accéder aux services hôtes ou lorsque l'environnement de construction a des routes personnalisées. Cependant, cela réduit l'isolement et peut ne pas être autorisé dans certains environnements CI. Une autre option consiste à utiliser un réseau Docker personnalisé avec des paramètres spécifiques. Créez d'abord un réseau :

docker network create --subnet=192.168.100.0/24 buildnet

Puis construisez en utilisant ce réseau :

docker buildx build --network=buildnet -t monimage .

Cela vous donne le contrôle sur le sous-réseau et la passerelle, ce qui peut aider si le pont par défaut entre en conflit avec votre réseau local.

Ajuster les paramètres MTU

Si vous soupçonnez une incompatibilité MTU, en particulier sur VPN, vous pouvez définir un MTU inférieur pour le démon Docker. Dans daemon.json :

{
  "mtu": 1400
}

Redémarrez Docker et testez les constructions. Alternativement, vous pouvez définir le MTU pour un réseau spécifique :

docker network create -o "com.docker.network.driver.mtu=1400" buildnet-low-mtu

Puis utilisez --network=buildnet-low-mtu dans votre construction. Cela est moins invasif que de changer le défaut du démon.

Utiliser les paramètres de proxy

Si votre environnement nécessite un proxy HTTP/HTTPS, assurez-vous que la construction peut l'utiliser. Vous pouvez passer les variables de proxy comme arguments de construction :

docker build --build-arg HTTP_PROXY=http://proxy.example.com:3128 \
             --build-arg HTTPS_PROXY=http://proxy.example.com:3128 \
             --build-arg NO_PROXY=localhost,127.0.0.1,.example.com \
             -t monimage .

Mais ces arguments doivent être utilisés dans le Dockerfile via ARG et ENV pour affecter les commandes RUN suivantes :

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY
ENV HTTP_PROXY=$HTTP_PROXY \
    HTTPS_PROXY=$HTTPS_PROXY \
    NO_PROXY=$NO_PROXY

RUN apt-get update && apt-get install -y curl

Alternativement, configurez le client Docker pour utiliser un proxy en définissant des variables d'environnement pour la commande docker elle-même, mais cela ne se propage pas toujours dans les conteneurs de construction. La méthode la plus sûre est d'utiliser des arguments de construction explicites.

Résumé de la configuration

Tous les changements ci-dessus sont réversibles. Les drapeaux en ligne de commande n'affectent qu'une seule construction. Les modifications de daemon.json nécessitent un redémarrage du démon mais peuvent être annulées en restaurant le fichier et en redémarrant. Les réseaux personnalisés peuvent être supprimés avec docker network rm. Gardez une trace des modifications pour pouvoir revenir en arrière si nécessaire.

Vérification et diagnostics

Après avoir appliqué un changement de configuration, vérifiez la connectivité depuis un contexte de construction. Le moyen le plus simple est de créer un conteneur temporaire utilisant les mêmes paramètres réseau que votre construction et d'exécuter des tests réseau. Vous pouvez également ajouter des étapes de diagnostic directement dans un Dockerfile pendant le dépannage, mais n'oubliez pas de les supprimer plus tard.

Tester la résolution DNS dans la construction

Exécutez une construction ponctuelle avec un test simple. Créez un Dockerfile temporaire nommé Dockerfile.test avec :

FROM alpine:3.18
RUN nslookup google.com

Puis construisez-le :

docker build -f Dockerfile.test --progress=plain .

La sortie attendue de la commande nslookup montre une résolution réussie :

#6 [2/2] RUN nslookup google.com
#6 sha256:...
#6 0.123 Server:  10.0.2.3
#6 0.123 Address: 10.0.2.3:53
#6 0.123
#6 0.124 Non-authoritative answer:
#6 0.124 Name:    google.com
#6 0.124 Address: 142.250.72.14
#6 DONE 0.2s

Si le DNS échoue, vous verrez une erreur comme server can't find google.com: NXDOMAIN ou un délai d'attente. Dans ce cas, vérifiez l'adresse du serveur DNS affichée. Il peut s'agir du DNS interne de BuildKit (par exemple, 10.0.2.3) qui transmet à l'hôte. Si le DNS de l'hôte est mal configuré, le DNS interne échouera également.

Pour tester avec un DNS explicite, utilisez le drapeau --dns :

docker build --dns 8.8.8.8 -f Dockerfile.test --progress=plain .

Si cela fonctionne, le problème vient de la configuration DNS par défaut.

Tester la connectivité externe

Utilisez une simple requête HTTP depuis la construction. Ajoutez ceci à votre Dockerfile de test :

FROM alpine:3.18
RUN wget -O- https://example.com | head -n 5

Construisez et vérifiez la réponse. Une exécution réussie montre le début de la page example.com. Un échec montrera connection refused ou timeout.

Si vous devez tester la connectivité TCP vers un port spécifique, utilisez nc (netcat). Par exemple, pour tester la connexion à une base de données à l'hôte db.example.com port 5432 :

FROM alpine:3.18
RUN apk add --no-cache netcat-openbsd && \
    nc -zv db.example.com 5432

Sortie attendue :

db.example.com (192.168.1.100:5432) open

Si cela échoue, vous verrez un délai d'attente ou Connection refused.

Inspecter l'espace de noms réseau de BuildKit

Pour des diagnostics plus approfondis, vous pouvez inspecter l'espace de noms réseau d'un conteneur de construction en cours d'exécution. Tout d'abord, démarrez une construction qui dort, en utilisant une image multi-étapes :

FROM alpine:3.18
RUN sleep 300

Dans un autre terminal, pendant que la construction est en cours, trouvez le conteneur :

docker ps

Recherchez un conteneur avec l'image alpine:3.18 et la commande sleep 300. Notez son ID. Puis inspectez ses paramètres réseau :

docker inspect <container-id> | grep -A10 NetworkSettings

Cela montre l'adresse IP, la passerelle et le DNS. Vous pouvez également exécuter des commandes dans le conteneur (s'il reste en cours d'exécution) et lancer des commandes réseau :

docker exec -it <container-id> sh

À l'intérieur, exécutez ip addr, ip route, cat /etc/resolv.conf, etc. Cela vous donne une vue directe de l'environnement de construction.

Utiliser les outils de débogage de BuildKit

BuildKit dispose d'un serveur de débogage intégré qui peut être activé pour des journaux verbeux. Définissez BUILDKIT_PROGRESS=plain pour voir plus de sortie, et utilisez --progress=plain pour désactiver l'interface graphique. Pour encore plus de détails, définissez la variable d'environnement BUILDKIT_DEBUG=1 avant d'exécuter docker build :

BUILDKIT_DEBUG=1 docker build --progress=plain -t monimage .

Cela affiche les journaux internes de BuildKit, y compris les messages liés au réseau, sur la console. Recherchez les lignes contenant network, dns ou dial pour repérer les problèmes.

Tableau de diagnostic

Résumez les tests courants et les résultats attendus :

TestCommandeRésultat attenduÉchec indique
Recherche DNSnslookup google.com dans la constructionAdresse IP retournéeMauvaise configuration DNS
Connectivité HTTPwget -O- https://example.comHTTP 200 et contenuProblème de pare-feu ou de routage
Vérification de port TCPnc -zv host port« open »Service inaccessible ou port bloqué
Journal de débogage BuildKitBUILDKIT_DEBUG=1 docker build ...Aucune erreur réseauN/A (le journal révèle les problèmes)

Modes de défaillance et récupération

Comprendre les modes de défaillance courants vous aide à récupérer rapidement. Voici les problèmes réseau typiques de BuildKit, comment les identifier et les étapes pour les corriger.

Échec de résolution DNS

Symptômes : RUN apt-get update ou RUN npm install échoue avec Could not resolve host ou Temporary failure in name resolution.

Cause : Le serveur DNS du conteneur de construction est inaccessible ou mal configuré. Cela peut se produire si le DNS de l'hôte est cassé, si les paramètres DNS du démon Docker sont erronés ou si un pare-feu bloque le port 53.

Diagnostic : Exécutez le test DNS de la section de vérification. Vérifiez /etc/resolv.conf à l'intérieur du conteneur avec docker exec ou en ajoutant RUN cat /etc/resolv.conf à un Dockerfile temporaire. Le serveur de noms doit être une adresse IP valide accessible depuis le conteneur.

Récupération : Remplacez le DNS avec --dns 8.8.8.8 (ou votre DNS d'entreprise). Si cela fonctionne, rendez le changement permanent dans daemon.json ou dans votre configuration de construction. Vérifiez également que le /etc/resolv.conf de l'hôte est correct. Si vous utilisez systemd-resolved, assurez-vous qu'il fonctionne et n'est pas mal configuré.

Délai d'attente de connexion aux services externes

Symptômes : La construction se bloque pendant un long moment et échoue finalement avec connection timed out ou no route to host.

Cause : Isolement réseau, incompatibilité MTU ou pare-feu bloquant les connexions sortantes. Les VPN causent souvent des problèmes de MTU.

Diagnostic : Testez d'abord la connectivité au service cible depuis l'hôte. Si l'hôte fonctionne mais pas la construction, le problème est probablement dans le réseau Docker. Vérifiez le MTU : comparez le MTU de docker network inspect bridge avec le MTU de l'interface hôte (ip link show). Une incompatibilité peut causer des pertes de paquets.

Récupération : Définissez le MTU pour correspondre au MTU effectif de l'hôte. Utilisez --network=host comme solution de contournement temporaire pour voir si cela résout le problème. Si oui, vous savez que c'est un problème de réseau de conteneur. Ajustez le MTU dans daemon.json ou créez un réseau personnalisé avec le MTU correct.

Impossible d'accéder aux services hôtes

Symptômes : La construction tente de se connecter à un service exécuté sur l'hôte (par exemple, une base de données locale ou une API) mais échoue.

Cause : Par défaut, les conteneurs de construction sont sur un réseau pont séparé et ne peuvent pas atteindre l'hôte via localhost ou 127.0.0.1. Ils doivent utiliser l'IP de l'hôte sur le réseau pont (souvent 172.17.0.1).

Diagnostic : Depuis un conteneur de construction, essayez ping 172.17.0.1. Si cela fonctionne, utilisez cette IP dans votre construction. Alternativement, utilisez le nom DNS spécial host.docker.internal sur Docker Desktop (macOS/Windows).

Récupération : Utilisez --network=host pour la construction (si acceptable). Ou, dans votre Dockerfile, utilisez --add-host=host.docker.internal:host-gateway pour mapper le nom d'hôte à l'IP de passerelle de l'hôte. Pour Linux, vous devrez peut-être ajouter extra_hosts dans le démon ou utiliser le drapeau --add-host :

docker build --add-host=host.docker.internal:host-gateway -t monimage .

Puis dans le Dockerfile, référez-vous à host.docker.internal.

Blocage par pare-feu ou groupe de sécurité

Symptômes : Des ports spécifiques sont bloqués, mais d'autres fonctionnent. Par exemple, HTTPS (443) fonctionne mais HTTP (80) échoue.

Cause : Les règles de pare-feu de l'hôte ou du groupe de sécurité cloud restreignent le trafic sortant du réseau pont de Docker.

Diagnostic : Depuis l'hôte, testez le port en utilisant nc ou telnet. Puis depuis l'intérieur d'un conteneur, testez le même. Si le conteneur échoue mais que l'hôte réussit, le pare-feu bloque probablement l'interface pont Docker (docker0).

Récupération : Ajustez les règles de pare-feu pour autoriser le trafic depuis le sous-réseau Docker (par exemple, 172.17.0.0/16). Sous Linux avec iptables :

sudo iptables -I OUTPUT -s 172.17.0.0/16 -j ACCEPT

Mais soyez prudent avec les modifications de pare-feu ; suivez toujours votre politique de sécurité. Alternativement, utilisez --network=host pour contourner le pont Docker (bien que cela puisse avoir ses propres restrictions).

Stratégies de retour en arrière

Si un changement de configuration aggrave les choses, annulez-le immédiatement. Gardez une sauvegarde de daemon.json et de tout script personnalisé. Pour les changements en ligne de commande, supprimez simplement les drapeaux. Pour daemon.json, restaurez le fichier précédent et redémarrez Docker. Pour les réseaux personnalisés, supprimez-les avec docker network rm. Documentez chaque changement pour savoir quoi annuler.

Question rapide 2 sur 2

Que se passe-t-il si le composant Buildx est manquant lorsque DOCKER_BUILDKIT=1 est défini ?

Le passage indique que si BuildKit est explicitement activé mais que le composant Buildx est manquant, une erreur est affichée et la construction échoue.

Pièges courants et comment les éviter

Voici les erreurs fréquentes que les développeurs commettent avec le réseau de BuildKit, ainsi que des conseils de prévention et de récupération.

Supposer que BuildKit se comporte comme l'ancien générateur

Pourquoi cela arrive : Les développeurs sont habitués à l'ancien réseau du générateur, moins isolé et partageant souvent le réseau hôte.

Comment éviter : Comprenez que BuildKit crée un espace de noms réseau séparé pour chaque étape de construction par défaut. Testez la connectivité tôt dans un nouveau pipeline de construction.

Récupération : Si une construction échoue en raison de l'isolement, essayez --network=host comme test rapide, puis ajustez votre Dockerfile ou vos paramètres réseau en conséquence.

Négliger l'incompatibilité MTU

Pourquoi cela arrive : Le MTU n'est souvent pas considéré jusqu'à ce que des symptômes comme des transferts lents ou des délais d'attente apparaissent, en particulier sur les VPN.

Comment éviter : Vérifiez toujours le MTU lorsque les constructions se bloquent pendant les opérations réseau. Comparez le MTU de l'hôte avec celui de Docker.

Récupération : Définissez le MTU correct dans daemon.json ou utilisez un réseau personnalisé avec le MTU approprié.

Coder en dur les serveurs DNS sans test

Pourquoi cela arrive : Les équipes codent en dur un DNS public comme 8.8.8.8 dans daemon.json, ce qui peut contourner le DNS d'entreprise et provoquer des échecs de résolution de noms internes.

Comment éviter : Testez d'abord avec --dns sur une seule construction. Utilisez les serveurs DNS d'entreprise si disponibles.

Récupération : Supprimez le DNS codé en dur de daemon.json et configurez un DNS approprié dans l'environnement de construction.

Ignorer les exigences de proxy

Pourquoi cela arrive : Dans les environnements d'entreprise, les constructions échouent car les variables de proxy ne sont pas transmises correctement.

Comment éviter : Passez toujours les paramètres de proxy comme arguments de construction et utilisez-les dans le Dockerfile via ARG/ENV. Testez avec une simple commande RUN curl.

Récupération : Ajoutez les arguments de construction de proxy manquants et reconstruisez.

Ne pas documenter les changements réseau

Pourquoi cela arrive : Les équipes font des corrections rapides sans les enregistrer, ce qui crée de la confusion plus tard.

Comment éviter : Tenez un runbook des changements de configuration réseau et de leur justification.

Récupération : Consultez l'historique git et les sauvegardes de daemon.json pour comprendre les changements passés.

Liste de contrôle des opérations

Utilisez la liste de contrôle suivante pour dépanner systématiquement et prévenir les problèmes futurs. Parcourez ces éléments dans l'ordre, des vérifications de base aux diagnostics avancés.

Vérifications préalables

  • [ ] Confirmez les versions de Docker et BuildKit avec docker version et docker buildx ls.
  • [ ] Vérifiez la connectivité Internet de l'hôte : ping 8.8.8.8 et nslookup google.com.
  • [ ] Vérifiez les paramètres du réseau pont par défaut : docker network inspect bridge.
  • [ ] Notez les paramètres MTU et DNS.

Pendant le dépannage

  • [ ] Reproduisez le problème avec un Dockerfile minimal (par exemple, un seul RUN qui échoue).
  • [ ] Testez la résolution DNS dans une construction en utilisant nslookup.
  • [ ] Testez la connectivité externe avec wget ou curl.
  • [ ] Testez des ports TCP spécifiques avec nc.
  • [ ] Essayez de remplacer le DNS en utilisant --dns 8.8.8.8.
  • [ ] Essayez --network=host pour isoler les problèmes de réseau de conteneur.
  • [ ] Inspectez le conteneur de construction en cours avec docker exec et ip addr.
  • [ ] Activez les journaux de débogage BuildKit : BUILDKIT_DEBUG=1 docker build --progress=plain ....

Après la correction

  • [ ] Confirmez que la construction se termine avec succès.
  • [ ] Documentez le changement et la raison.
  • [ ] Si un changement global a été effectué (par exemple, daemon.json), assurez-vous qu'il n'affecte pas les autres constructions.
  • [ ] Envisagez d'ajouter des tests de régression (par exemple, une construction de vérification de santé dans la CI).

Maintenance de routine

  • [ ] Mettez à jour périodiquement Docker et BuildKit pour obtenir des correctifs réseau.
  • [ ] Surveillez la santé de l'infrastructure DNS.
  • [ ] Examinez les règles de pare-feu pour les sous-réseaux Docker.
  • [ ] Tenez un runbook avec les symptômes courants et les corrections.

Conclusion

Les problèmes réseau de Docker BuildKit peuvent être complexes, mais une approche structurée simplifie le dépannage. Commencez par recueillir les détails de version et d'environnement, puis apportez de petits changements de configuration réversibles. Utilisez des tests de diagnostic ciblés pour vérifier la connectivité et identifier les causes profondes. Connaître les modes de défaillance courants tels que la mauvaise configuration DNS, l'incompatibilité MTU et les problèmes d'accès à l'hôte permet une récupération rapide.

Ce guide a fourni des commandes pratiques et des sorties attendues pour vous guider à chaque étape. En suivant la liste de contrôle des opérations, vous pouvez résoudre efficacement les problèmes et prévenir les récidives. N'oubliez pas de documenter vos découvertes et d'ajuster vos processus de construction en conséquence. Avec ces outils, vous pouvez gérer en toute confiance les défis réseau de BuildKit et maintenir vos constructions fluides.

Recherches connexes

Score de qualité de l’article

Utilité pour le lecteur 100%
  • check_circle Guide prêt à lire
  • check_circle Exemples pratiques inclus
  • check_circle URL d’article optimisée pour le SEO