Image Pull Timeout: Network, DNS oder Registry? So stellst du es sicher

Ein Image Pull Timeout ist eines der häufigsten Symptome, wenn Kubernetes-Workloads nicht starten: Pods bleiben in ImagePullBackOff, ErrImagePull oder hängen lange in „ContainerCreating“. In der Praxis führt das schnell zu der Frage: Ist das Problem Network, DNS oder Registry – und wie stelle ich es sicher, statt nur zu raten? Genau hier hilft ein strukturiertes Vorgehen, das den Pull-Prozess in klare Prüfschritte zerlegt: Namensauflösung (DNS), Routing/Egress (Netzwerkpfad), TLS/Handshake (Transport), Auth (Credentials) und Registry-spezifische Limits (Rate Limiting, Throttling, WAF, Geo/Policy). Weil ein Image Pull oft über mehrere Schichten läuft – Node, CNI, NAT-Gateway, DNS-Resolver, Proxy, Registry-CDN – sind Timeouts nicht automatisch „die Registry ist down“. Ebenso kann ein einzelner fehlerhafter DNS-Path dafür sorgen, dass alles wie ein Netzwerkproblem aussieht. Dieser Artikel zeigt praxisnah, wie Sie Image Pull Timeouts sauber differenzieren, welche Indikatoren Sie in Events und Logs suchen, wie Sie reproduzierbar testen und welche Gegenmaßnahmen dauerhaft stabilisieren.

Wie ein Image Pull technisch abläuft (und wo Timeouts entstehen)

Bevor Sie debuggen, lohnt sich ein kurzer mentaler Ablaufplan. Ein Node (genauer: die Container Runtime wie containerd oder CRI-O) muss typischerweise:

• Registry-Hostnamen auflösen (DNS A/AAAA/CNAME, ggf. über Corporate DNS oder CoreDNS-Forwarder)
• TCP-Verbindung aufbauen (Port 443, manchmal 80 für Redirects; über NAT/Proxy/Egress)
• TLS aushandeln (Zertifikatskette, SNI, ggf. TLS-Inspection/Proxy)
• Authentifizieren (Bearer Token Flow, Basic Auth, Cloud IAM, Pull Secrets)
• Manifeste und Layer herunterladen (HTTP GET, Range Requests, parallele Downloads, Content Store)
• Layer entpacken/verifizieren (I/O und CPU auf dem Node können ebenfalls relevant sein)

Ein Timeout kann in jedem Schritt auftreten. Entscheidend ist daher: Sie müssen den Zeitpunkt und die Phase erkennen. „Timeout“ bei DNS ist etwas anderes als „timeout“ beim Layer-Download oder beim Token-Endpoint.

Erste Orientierung: Was verraten Pod Events und Fehlermeldungen?

Die schnellste Entscheidungshilfe ist oft die Fehlermeldung in den Pod Events. Viele Umgebungen liefern dort bereits Hinweise, ob DNS, Netzwerk oder Registry/Authentifizierung das Problem ist.

• DNS-typisch: „no such host“, „Temporary failure in name resolution“, „lookup <host> on <dns>: i/o timeout“
• Netzwerk-typisch: „dial tcp … i/o timeout“, „connect: connection timed out“, „context deadline exceeded“
• TLS/Proxy-typisch: „x509: certificate signed by unknown authority“, „remote error: tls: handshake failure“
• Registry/Auth-typisch: „unauthorized: authentication required“, „denied: requested access“, „429 Too Many Requests“
• Rate/Throttling: wiederkehrende Timeouts nur bei Last oder parallel startenden Pods, oft kombiniert mit 429/5xx

Wichtig: Events sind nicht immer vollständig. Wenn Sie nur „context deadline exceeded“ sehen, müssen Sie tiefer in Runtime-Logs, Node-Logs und Netzwerk-Telemetrie.

DNS als Ursache sicher prüfen (nicht nur vermuten)

DNS ist eine überraschend häufige Root Cause-Kategorie, weil Image Pulls in der Regel vom Node ausgehen – und dessen Resolver-Path kann sich vom Pod-DNS unterscheiden. Dazu kommen Split-Horizon-DNS, Forwarder-Ketten, Corporate DNS, Stub Resolver und Caching-Effekte.

Typische DNS-Indikatoren bei Image Pull Timeout

• Intermittierend: Manche Nodes ziehen Images, andere nicht (unterschiedliche Resolver, NodeLocal DNS Cache, lokale DNS-Probleme).
• Nur bestimmte Registries: z. B. nur „registry-1.docker.io“ oder private Registry-Domains.
• Lange Lookup-Zeiten: Timeouts treten vor dem Verbindungsaufbau auf, oft mit „lookup … i/o timeout“.

Praktische Tests für DNS

• Resolver-Pfad klären: Prüfen Sie, welchen DNS-Server der Node nutzt (nicht nur der Pod).
• Mehrfachauflösung: Mehrere Queries hintereinander (Caching vs. flapping).
• AAAA vs. A: IPv6-Dual-Stack kann dazu führen, dass zuerst AAAA gewählt wird und dann Zeit verloren geht, wenn IPv6 im Egress nicht sauber funktioniert.
• CDN/Geo-DNS: Registries nutzen häufig CDNs; falsche Antworten oder suboptimale Edges können Timeouts verstärken.

Netzwerk/Egress als Ursache sicher prüfen

Wenn DNS sauber ist, kommt der Netzwerkpfad. Image Pulls sind „Egress-heavy“: viele parallele Verbindungen, große Downloads, oft über NAT-Gateways, Firewalls, Proxies oder Service Controls. Ein Image Pull Timeout entsteht häufig durch NAT-Port-Exhaustion, Throughput-Limits, Packet Loss, MTU-Probleme oder restriktive Egress-Policies.

Typische Netzwerk-Indikatoren bei Image Pull Timeout

• Nur bei Deployments/Autoscaling: Viele Pods starten gleichzeitig, danach normalisiert es sich.
• Node-spezifisch: Ein Node in einer AZ/Subnetz-Kombination ist auffällig (Route Table, NACL, Security Group, Firewall).
• Timeout erst beim Download: Handshake klappt, aber Layer-Download bricht ab oder hängt.
• Verbindung steht, Daten fließen nicht: Hinweise auf MTU/PMTUD oder Packet Loss.

Netzwerk-Checkliste für reproduzierbare Beweise

• Routing & Egress: Können Nodes die Registry-IP/Ports erreichen? Gibt es einen Proxy, der zwingend genutzt werden muss?
• NAT-Kapazität: NAT-Gateway/Firewall-Session-Limits, Port-Auslastung, conntrack-Limits auf Nodes.
• Throughput-Limits: Bandbreite pro Node, pro ENI, pro NAT-Gateway oder pro egress path.
• MTU: Overlay/Cloud-VPN/PrivateLink kann effektive MTU reduzieren, was große Transfers stören kann.
• Packet Loss/RTT: Erhöhte Latenz und Retransmits verlängern Downloads und triggern Timeouts.

Warum „gleichzeitig viele Pods“ so oft der Auslöser ist

Wenn ein Deployment 200 Pods hochfährt, startet die Runtime viele parallele Downloads. Damit steigen gleichzeitig TCP-Verbindungen, NAT-Sessions und DNS-Queries. Wenn Ihr Egress-Design knapp dimensioniert ist, wirkt das wie „die Registry ist langsam“, obwohl der Engpass lokal (NAT/conntrack/Firewall) entsteht.

Registry als Ursache sicher prüfen (inklusive Auth, Rate Limits und CDN)

Auch wenn DNS und Netzwerk grundsätzlich funktionieren, kann die Registry selbst (oder ihr Auth-/Token-Endpoint) Timeouts auslösen. Besonders häufig sind:

• Rate Limiting (z. B. 429 bei öffentlichen Registries oder bei Shared Egress-IP)
• Throttling durch CDN-Edges, die Ihre Region/Netzroute ungünstig bedienen
• Auth-Flow-Probleme (falsche Pull Secrets, abgelaufene Tokens, IAM-Policies)
• Private Registry Policies (IP-Allowlists, WAF-Regeln, Geo-Block, TLS-Inspection Inkompatibilität)

Registry-Indikatoren aus Sicht der Logs

• HTTP-Statuscodes: 401/403 (Auth/Policy), 429 (Rate Limit), 5xx (Registry/CDN-Problem)
• Token-Endpunkt: Timeouts beim Bearer-Token-Request sehen oft wie „Registry down“ aus, sind aber Auth-spezifisch.
• Nur bestimmte Repositories/Tags: Manche Images sind deutlich größer oder liegen auf anderen Backends.

Ein häufiger Stolperstein: Shared Egress-IP und Rate Limits

Viele Cluster gehen über eine gemeinsame Egress-IP (NAT). Für öffentliche Registries kann das bedeuten: Ein einzelner Peak im Cluster triggert Rate Limits, die dann alle Deployments betreffen. Das Problem sieht wie ein generischer „timeout“ aus, wenn Clients aggressiv retryen und der Backoff ungünstig ist.

Systematisches Runbook: So trennen Sie DNS, Netzwerk und Registry in 15–30 Minuten

Das folgende Vorgehen ist bewusst pragmatisch und arbeitet von „schnellster Gewissheit“ zu „tiefer Diagnose“.

• Phase 1: Scope bestimmen
  • Tritt der Image Pull Timeout clusterweit auf oder nur auf einzelnen Nodes?
  • Betrifft es nur eine Registry (z. B. Docker Hub) oder mehrere (ECR/GCR/ACR/private)?
  • Tritt es nur bei Scale-Up/Deployments auf (Burst) oder auch im steady state?
• Phase 2: DNS schnell validieren
  • Auf betroffenen Nodes prüfen, ob der Registry-Hostname stabil auflösbar ist.
  • AAAA/A-Verhalten kontrollieren, wenn Dual-Stack aktiv ist.
  • CoreDNS/Forwarder-Metriken prüfen (Latency, SERVFAIL, Timeouts).
• Phase 3: Netzwerkpfad verifizieren
  • TCP-Verbindung zu Registry:443 vom Node testen (nicht nur aus einem Pod).
  • Wenn möglich, RTT/Packet Loss Indikatoren betrachten.
  • NAT/conntrack/Firewall-Limits prüfen, besonders bei Burst-Events.
• Phase 4: Registry/Auth prüfen
  • HTTP-Statuscodes aus Runtime-Logs extrahieren (401/403/429/5xx).
  • Pull Secrets/IAM prüfen (ServiceAccount, ImagePullSecrets, Workload Identity).
  • Rate-Limit-/Throttling-Indikatoren: korreliert mit parallelen Starts?

Timeouts quantifizieren: Wann ist es „echter Timeout“ vs. „zu langsam“?

In Incidents wird „Timeout“ oft als binäres Ereignis gesehen. Praktischer ist es, das Problem als Budget zu betrachten: Wie lange darf DNS dauern, wie lange TLS, wie lange darf ein Layer-Download dauern? Wenn Sie das als Zielwerte definieren, können Sie Messungen dagegen halten.

$\mathrm{T\_total}=\mathrm{T\_dns}+\mathrm{T\_tcp}+\mathrm{T\_tls}+\mathrm{T\_auth}+\mathrm{T\_download}$

Wenn Ihr beobachtetes T_dns bereits nahe am Gesamt-Deadline liegt, ist die Root Cause sehr wahrscheinlich DNS. Wenn T_dns klein ist, aber T_download stark schwankt und bei Bursts explodiert, ist eher Egress/Throttling oder Bandbreite der Flaschenhals.

Dauerhafte Gegenmaßnahmen: Stabilisieren statt nur „Retry erhöhen“

Ein höheres Timeout kaschiert oft nur das Problem. Nachhaltige Fixes reduzieren die Wahrscheinlichkeit, dass Pulls überhaupt scheitern, und verringern den Blast Radius bei Bursts.

• Image Caching: Nutzen Sie Node-Image-Caches oder Pre-Pulls (DaemonSet), insbesondere für Basis-Images.
• Private Registry Mirror: Spiegeln Sie häufig genutzte Images in eine interne Registry nahe am Cluster.
• Pull-Parallelität begrenzen: Konfigurieren Sie Runtime/Node so, dass nicht alle Pods gleichzeitig große Layer ziehen.
• NAT/conntrack dimensionieren: Erhöhen Sie Kapazitäten, verteilen Sie Egress über mehrere NATs/Paths.
• DNS robust machen: NodeLocal DNS Cache, stabile Forwarder, klare Split-Horizon-Regeln.
• Registry-Auth härten: Rotationsprozesse für Tokens/Secrets, IAM-Policies testen, 401/403 sauber alarmieren.
• Beobachtbarkeit: Metriken für Pull-Dauer, Fehlercodes, DNS-Latenz, NAT-Session-Auslastung, Node conntrack.

Warum Pre-Pulling oft der schnellste „SRE-Fix“ ist

Wenn ein Deployment in einem Incident hunderte Pods neu startet, gewinnen Sie mit Pre-Pulls sofort: Der Pull verschwindet aus dem kritischen Pfad, und Sie reduzieren gleichzeitig Registry- und Egress-Last. Das ersetzt keine Root Cause Analyse, verhindert aber, dass sich Probleme bei jeder Skalierung wiederholen.

Häufige Fehlannahmen (und wie Sie sie vermeiden)

• „Pods haben Internet, also haben Nodes Internet“: Image Pulls passieren über die Node-Runtime. Pod-Connectivity ist kein Beweis für Node-Egress.
• „DNS ist ok, weil andere Domains funktionieren“: Registry-Domains können über andere Resolver/Forwarder gehen oder Geo-DNS nutzen.
• „Registry ist langsam“: Häufig ist es NAT/conntrack/Throughput. Prüfen Sie Burst-Korrelationen.
• „Mehr Retries löst es“: Retries können Egress und Registry weiter überlasten und Timeouts verstärken.

Outbound-Links zu relevanten Informationsquellen

• Images in Kubernetes: Pulling, ImagePullPolicy, Secrets
• Kubernetes Debugging: Running Pods und Troubleshooting
• DNS Debugging in Kubernetes (CoreDNS, Resolution)
• containerd CRI Konfiguration (Timeouts, Registry Mirrors)
• Docker Hub Rate Limits (Hintergrund und Symptome)
• EKS: Troubleshooting Image Pull Errors (AWS Knowledge Center)

Cisco Netzwerkdesign, CCNA Support & Packet Tracer Projekte

Cisco Networking • CCNA • Packet Tracer • Network Configuration

Ich biete professionelle Unterstützung im Bereich Cisco Computer Networking, einschließlich CCNA-relevanter Konfigurationen, Netzwerkdesign und komplexer Packet-Tracer-Projekte. Die Lösungen werden praxisnah, strukturiert und nach aktuellen Netzwerkstandards umgesetzt.

Diese Dienstleistung eignet sich für Unternehmen, IT-Teams, Studierende sowie angehende CCNA-Kandidaten, die fundierte Netzwerkstrukturen planen oder bestehende Infrastrukturen optimieren möchten. Finden Sie mich auf Fiverr.

Leistungsumfang:

• Netzwerkdesign & Topologie-Planung

• Router- & Switch-Konfiguration (Cisco IOS)

• VLAN, Inter-VLAN Routing

• OSPF, RIP, EIGRP (Grundlagen & Implementierung)

• NAT, ACL, DHCP, DNS-Konfiguration

• Troubleshooting & Netzwerkoptimierung

• Packet Tracer Projektentwicklung & Dokumentation

• CCNA Lern- & Praxisunterstützung

Lieferumfang:

• Konfigurationsdateien

• Packet-Tracer-Dateien (.pkt)

• Netzwerkdokumentation

• Schritt-für-Schritt-Erklärungen (auf Wunsch)

Arbeitsweise:Strukturiert • Praxisorientiert • Zuverlässig • Technisch fundiert

CTA:
Benötigen Sie professionelle Unterstützung im Cisco Networking oder für ein CCNA-Projekt?
Kontaktieren Sie mich gerne für eine Projektanfrage oder ein unverbindliches Gespräch. Finden Sie mich auf Fiverr.