DNS-Probleme im Docker-Netzwerk debuggen

1. Wie DNS-Auflösung in Docker-Netzwerken funktioniert

Bevor man DNS-Probleme im Docker-Netzwerk debuggen kann, muss klar sein, wie Namensauflösung dort überhaupt abläuft. In einem benutzerdefinierten Bridge-, Overlay- oder Macvlan-Netzwerk schreibt Docker beim Start eines Containers automatisch eine /etc/resolv.conf, die auf einen internen DNS-Server verweist. Anfragen nach Containernamen oder, in Compose, Servicenamen werden dort direkt beantwortet, alle anderen Anfragen werden an die konfigurierten Upstream-DNS-Server weitergeleitet, meist übernommen vom Docker-Host.

Das bedeutet: DNS im Docker-Netzwerk ist ein zweistufiges System. Erst prüft der eingebettete Resolver, ob der angefragte Name ein bekannter Container oder Service ist, dann erst geht die Anfrage nach draußen. Die meisten DNS-Probleme im Docker-Netzwerk entstehen genau an dieser Schnittstelle, entweder weil der Container nicht im richtigen Netzwerk hängt, um von der ersten Stufe zu profitieren, oder weil die zweite Stufe, die externen DNS-Server, falsch konfiguriert oder nicht erreichbar sind.

2. Der eingebettete DNS-Server 127.0.0.11

Jeder Container in einem benutzerdefinierten Netzwerk bekommt die Adresse 127.0.0.11 als DNS-Server in seine /etc/resolv.conf eingetragen. Diese Adresse ist kein echter Netzwerkdienst außerhalb des Containers, sondern wird vom Docker-Daemon per iptables-Regel innerhalb des Container-Namespaces abgefangen und intern beantwortet. Wer DNS-Probleme im Docker-Netzwerk untersucht, sollte als Erstes genau diese Datei prüfen, denn eine fehlende oder falsche 127.0.0.11-Zeile deutet meist auf ein grundlegendes Netzwerkproblem hin.

Wichtig zu verstehen: der eingebettete DNS-Server kennt ausschließlich Container und Services im selben benutzerdefinierten Netzwerk. Ein Container, der versucht, den Namen eines Containers in einem völlig anderen Netzwerk aufzulösen, bekommt keine Antwort, selbst wenn beide Container auf demselben Host laufen. Diese Netzwerkgrenze ist eine der häufigsten Ursachen für DNS-Probleme im Docker-Netzwerk, die auf den ersten Blick wie ein DNS-Fehler aussehen, tatsächlich aber ein Netzwerk-Segmentierungsproblem sind.

# Inspect the resolv.conf inside a running container
docker exec my-app cat /etc/resolv.conf

# Expected output in a custom network:
# nameserver 127.0.0.11
# options ndots:0

# Check which network a container actually belongs to
docker inspect my-app --format '{{range $net, $conf := .NetworkSettings.Networks}}{{$net}} {{end}}'

3. Typische Symptome eines DNS-Problems

Das klassische Symptom für DNS-Probleme im Docker-Netzwerk ist eine Fehlermeldung wie Name or service not known oder Could not resolve host, ausgelöst von der Anwendung selbst, oft schon beim Start, wenn sie versucht, eine Verbindung zur Datenbank oder zu einem anderen Service aufzubauen. Ein zweites, subtileres Symptom ist keine harte Fehlermeldung, sondern eine spürbare Verzögerung von mehreren Sekunden vor jeder Verbindung, verursacht durch DNS-Timeouts, die im Hintergrund ablaufen, bevor ein Fallback greift.

Ein drittes Muster zeigt sich häufig nach einem docker compose restart: die Anwendung funktionierte vor dem Neustart, danach schlägt die Namensauflösung plötzlich fehl, obwohl sich an der Konfiguration nichts geändert hat. Das deutet fast immer auf gecachte DNS-Antworten in der Anwendung selbst hin, nicht auf ein tatsächliches DNS-Problem im Docker-Netzwerk, denn Docker selbst aktualisiert seine internen DNS-Einträge sofort bei jedem Container-Neustart.

4. Diagnosewerkzeuge im Container einsetzen

Für die systematische Diagnose von DNS-Problemen im Docker-Netzwerk braucht es Werkzeuge innerhalb des Containers, nicht nur auf dem Host, weil die Namensauflösung im Container-Namespace stattfindet. nslookup und dig sind die Standardwerkzeuge, sind aber in minimalen Images wie Alpine oder Distroless oft nicht vorinstalliert und müssen nachträglich installiert oder über ein Debug-Image bereitgestellt werden. getent hosts nutzt hingegen die Standard-C-Bibliothek zur Namensauflösung und ist in praktisch jedem Linux-Image bereits verfügbar.

Ein oft übersehener Diagnoseschritt: docker network inspect auf dem Host zeigt, welche Container tatsächlich in einem Netzwerk registriert sind und unter welchem Namen. Stimmt der erwartete Servicename nicht mit dem tatsächlich registrierten Namen überein, etwa wegen eines Tippfehlers im Compose-File, erklärt das viele scheinbar mysteriöse DNS-Probleme im Docker-Netzwerk sofort, ganz ohne tiefere DNS-Analyse.

# Resolve a name using getent, available in almost every image
docker exec my-app getent hosts shop-db

# If dig is available, inspect the full DNS response
docker exec my-app dig shop-db +short

# List all containers actually registered in a network
docker network inspect shop-network \
  --format '{{range .Containers}}{{.Name}} {{end}}'

# Quick one-off debug container with full networking tools
docker run --rm --network shop-network nicolaka/netshoot \
  dig shop-db

5. Ursache eins: Container im Default-Bridge-Netzwerk

Die mit Abstand häufigste Ursache für DNS-Probleme im Docker-Netzwerk ist ein Container, der noch im Default-Bridge-Netzwerk läuft, weil beim docker run kein --network-Parameter angegeben wurde. Die Default-Bridge betreibt keinen eingebetteten DNS-Server für Containernamen, Container müssen sich dort über feste IP-Adressen erreichen. Wer aus Gewohnheit einen Servicenamen verwendet, wie er es aus Compose-Setups kennt, bekommt in der Default-Bridge zuverlässig einen Namensauflösungsfehler.

Die Lösung ist einfach, aber leicht zu übersehen: ein benutzerdefiniertes Netzwerk anlegen und beide Container diesem Netzwerk zuweisen. In Compose-Projekten tritt dieses DNS-Problem im Docker-Netzwerk seltener auf, weil Compose automatisch ein Projekt-Netzwerk erstellt, kann aber trotzdem entstehen, wenn ein Service explizit network_mode: host oder ein externes Netzwerk ohne DNS-Unterstützung nutzt.

6. Ursache zwei: Externe DNS-Server und IPv6-Timeouts

Ein zweites häufiges Muster bei DNS-Problemen im Docker-Netzwerk betrifft die Auflösung externer Domains, etwa wenn ein Container ein NPM-Paket oder ein PHP-Composer-Paket von einem öffentlichen Registry-Server laden soll. Schlägt diese Auflösung fehl, liegt es oft nicht am Docker-DNS selbst, sondern an den externen DNS-Servern, die der Docker-Daemon vom Host übernommen hat, etwa wenn der Host in einem restriktiven Firmennetz mit internen DNS-Servern läuft, die aus dem Container-Namespace heraus nicht erreichbar sind.

Ein zweiter, sehr häufiger Sonderfall sind IPv6-bedingte Verzögerungen. Manche Anwendungen fragen standardmäßig zuerst nach einem AAAA-Eintrag, bevor sie auf IPv4 zurückfallen, und dieser fehlgeschlagene erste Versuch produziert bei fehlendem IPv6 im Docker-Netzwerk spürbare Wartezeiten, die wie ein DNS-Problem im Docker-Netzwerk aussehen, tatsächlich aber ein Protokoll-Fallback-Timeout sind. Das lässt sich in vielen Anwendungen durch explizites Erzwingen von IPv4 umgehen.

# Check which DNS servers the Docker daemon uses by default
cat /etc/resolv.conf   # on the host, usually inherited by containers

# Force IPv4 resolution to rule out IPv6 fallback delays
docker exec my-app curl -4 --connect-timeout 3 https://registry.npmjs.org

# Compare timing between IPv4-forced and default resolution
docker exec my-app time curl -o /dev/null -s https://registry.npmjs.org

7. Ursache drei: DNS-Caching und Alias-Konflikte

Anwendungen und Laufzeitumgebungen cachen DNS-Antworten häufig selbst, unabhängig vom Betriebssystem. Node.js, JVM-basierte Anwendungen und einige PHP-Erweiterungen halten aufgelöste IP-Adressen im Prozessspeicher, teils für die gesamte Laufzeit des Prozesses. Startet ein Datenbankcontainer neu und bekommt dabei eine neue interne IP-Adresse, kann eine lange laufende Anwendung mit gecachter alter Adresse dann scheinbar grundlos die Verbindung verlieren, ein DNS-Problem im Docker-Netzwerk, das in Wirklichkeit ein Caching-Problem der Anwendungsebene ist.

Ein zweiter Fall betrifft --network-alias: wenn zwei unterschiedliche Container versehentlich denselben Alias im selben Netzwerk registrieren, liefert die Namensauflösung round-robin abwechselnd beide IP-Adressen zurück, was zu inkonsistentem Verhalten führt, das schwer zu reproduzieren ist. Das Auflisten aller registrierten Aliase mit docker network inspect deckt solche Konflikte zuverlässig auf, bevor sie als scheinbar zufälliges DNS-Problem im Docker-Netzwerk fehlinterpretiert werden.

# List all registered aliases for containers in a network
docker network inspect shop-network \
  --format '{{json .Containers}}' | python3 -m json.tool

# Resolve the same name repeatedly to spot round-robin alias conflicts
for i in 1 2 3 4 5; do
  docker exec my-app getent hosts shop-cache
done

8. DNS-Optionen gezielt konfigurieren

Für Fälle, in denen die Standard-DNS-Konfiguration nicht ausreicht, bietet sowohl docker run als auch Docker Compose explizite Optionen. Mit --dns lässt sich ein zusätzlicher oder alternativer externer DNS-Server für einen Container festlegen, unabhängig von der Host-Konfiguration. --dns-search ergänzt Suchdomains, sodass unqualifizierte Namen automatisch mit einer Domain-Endung ergänzt werden, bevor die Auflösung fehlschlägt. --add-host beziehungsweise extra_hosts in Compose fügt statische Einträge direkt in /etc/hosts ein, was für Sonderfälle nützlich ist, die kein reguläres DNS im Docker-Netzwerk abbilden kann.

Diese Optionen sollten sparsam eingesetzt werden, weil sie die automatische, selbstkonfigurierende Namensauflösung von Docker teilweise überschreiben und damit Konfigurationsdrift zwischen Umgebungen begünstigen. Der bevorzugte Weg bleibt, das eingebettete DNS im Docker-Netzwerk korrekt zu nutzen, und externe DNS-Optionen nur für tatsächliche Sonderfälle wie interne Firmen-Domains zu reservieren.

services:
  app:
    image: shop-app:latest
    dns:
      - 8.8.8.8
      - 1.1.1.1
    dns_search:
      - internal.example.com
    extra_hosts:
      - "legacy-api.internal:10.0.5.20"
    networks:
      - shop-network

networks:
  shop-network:
    driver: bridge

9. Default-Bridge-DNS und benutzerdefiniertes Netzwerk im Vergleich

Die folgende Tabelle stellt gegenüber, wie sich DNS-Verhalten je nach Netzwerktyp unterscheidet, ein zentraler Punkt, um DNS-Probleme im Docker-Netzwerk von vornherein zu vermeiden statt sie später aufwendig zu debuggen.

Diese Übersicht macht deutlich, dass ein Großteil der DNS-Probleme im Docker-Netzwerk vermeidbar ist, sobald konsequent benutzerdefinierte Netzwerke statt der Default-Bridge verwendet werden. Die verbleibenden Fälle betreffen fast immer externe DNS-Konfiguration, Caching auf Anwendungsebene oder Alias-Kollisionen, alle drei mit klar identifizierbaren, reproduzierbaren Symptomen.

10. Zusammenfassung

DNS-Probleme im Docker-Netzwerk lassen sich in den meisten Fällen auf drei Grundursachen zurückführen: Container laufen noch in der Default-Bridge ohne eingebetteten DNS-Server, externe DNS-Server sind falsch konfiguriert oder aus dem Container-Namespace nicht erreichbar, oder Anwendungen cachen aufgelöste IP-Adressen über Container-Neustarts hinweg. Der eingebettete DNS-Server unter 127.0.0.11 löst Container- und Servicenamen zuverlässig auf, sofern die beteiligten Container im selben benutzerdefinierten Netzwerk laufen.

Werkzeuge wie getent hosts, dig und docker network inspect machen die Diagnose systematisch statt geraten. Explizite DNS-Optionen wie --dns und --dns-search lösen Sonderfälle, sollten aber sparsam bleiben, um die automatische Namensauflösung von Docker nicht unnötig zu überschreiben. Wer diese Grundlagen kennt, findet DNS-Probleme im Docker-Netzwerk in wenigen Minuten, statt stundenlang im Dunkeln zu debuggen.

11. FAQ: DNS-Probleme im Docker-Netzwerk debuggen