Docker-Proxy: Der komplette Leitfaden für den Einsatz von Containern hinter Unternehmensfirewalls

Die meisten Firmennetzwerke nutzen Proxy-Server, um den Internetverkehr zu überwachen und zu filtern. Das führt zu Problemen, wenn Docker versucht, Images aus Registern abzurufen. Es kann zu Verbindungszeitüberschreitungen, Authentifizierungsfehlern und fehlgeschlagenen Builds kommen, die in deinem Heimnetzwerk funktionieren. Diese Probleme mit Proxys können Entwicklungsteams, die nicht auf die benötigten Basisimages zugreifen können, ganz schön aus der Bahn werfen.

Die Docker-Proxy-Konfiguration löst diese Verbindungsprobleme, verbessert die Leistung durch Caching und erfüllt die Sicherheitsanforderungen von Unternehmen. Sobald die Konfiguration erledigt ist, holen deine Container die Images ab, egal welche Netzwerkbeschränkungen es gibt.

In diesem Tutorial zeige ich dir, wie du die Proxy-Einstellungen für den Docker-Daemon machst, die Umgebungsvariablen für Container konfigurierst und die Proxy-Einstellungen in Docker Compose anpasst.

Du bist neu bei Docker und fühlst dich von all den Netzwerkkonzepten überfordert? Fang mit den Docker-Grundlagen an und hol dir Schritt für Schritt mehr Sicherheit.

Die Architektur von Docker Proxy verstehen

Verschiedene Teile des Docker-Ökosystems brauchen eine Proxy-Konfiguration auf verschiedenen Ebenen.

Proxys sind sozusagen die Mittelsmänner zwischen deinen Docker-Komponenten und externen Netzwerken. Wenn Docker Images abrufen muss, Container Internetzugang brauchen oder Builds externe Ressourcen brauchen, kümmern sich Proxy-Server um die Steuerung und Überwachung dieser Verbindungen. Sie sitzen zwischen deinen containerisierten Anwendungen und der Außenwelt und filtern Anfragen und Antworten.

Firmen nutzen Proxys mit Docker, um die Leistung zu verbessern, die Sicherheit zu erhöhen und Vorschriften einzuhalten.

Die Leistung kommt vom Zwischenspeichern oft genutzter Ressourcen wie Basisimages, was die Downloadzeiten für dein Team verkürzt. Zu den Sicherheitsvorteilen gehören Traffic-Filterung, Malware-Scans und das Blockieren von Zugriff auf nicht autorisierte Websites. Die Compliance-Regeln sagen, dass der ganze Netzwerkverkehr über überwachte Kanäle mit ordentlichen Zugriffskontrollen und Prüfpfaden laufen muss.

Die Docker-Proxy-Konfiguration läuft in vier Schichten ab:

• Client-Proxy: Betrifft Docker-CLI-Befehle wie „ docker pull “ und docker push

• Daemon-Proxy: Steuert, wie der Docker-Daemon auf externe Registrierungen zugreift.

• Container-Laufzeit-Proxy: Setzt Proxy-Variablen für Anwendungen in Containern.

• Build-Zeit-Proxy: kümmert sich um die Proxy-Einstellungen während der „ docker build “-Operationen, wenn Dockerfiles Internetzugang brauchen.

Jede Schicht hat ihren Zweck und braucht ihre eigene Konfiguration.

Um Docker-Netzwerke zu verstehen, muss man erst mal wissen, wie Container miteinander reden. 

Docker für die Verwendung eines Proxys einrichten

Damit Docker mit deinem Firmen-Proxy funktioniert, musst du sowohl den Docker-Daemon als auch den Client einrichten.

Warum? Weil sie verschiedene Arten von Netzwerk-Anfragen bearbeiten. 

Der Daemon kümmert sich um das Abrufen und Hochladen von Images sowie um die Registrierungsauthentifizierung, während der Client die CLI-Operationen und API-Aufrufe übernimmt. Wenn eine der beiden Konfigurationen fehlt, entstehen Lücken, in denen Docker-Vorgänge mit Verbindungsfehlern scheitern können.

So richtest du den Docker-Daemon ein

Der Docker-Daemon liest die Proxy-Einstellungen aus der Datei „ /etc/docker/daemon.json “. Erstell diese Datei, falls sie noch nicht da ist:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

Das Feld „ noProxy “ zeigt die Adressen, die den Proxy umgehen sollen. Trag hier deine internen Registrierungsdomänen und Localhost-Adressen ein.

Systemd-Dienst-Überschreibungen einrichten

Auf Linux-Systemen mit systemd musst du auch den Docker-Dienst selbst so einrichten, dass er den Proxy nutzt. Mach das Verzeichnis zum Überschreiben und die Konfigurationsdatei:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Füge dann diese Umgebungsvariablen zur Datei „ http-proxy.conf “ hinzu:

[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.company.com"

Dadurch wird sichergestellt, dass der Docker-Daemon-Prozess selbst über deinen Proxy auf externe Dienste zugreifen kann.

Docker übernimmt die Proxy-Änderungen erst, wenn du den Daemon neu startest. Führ diese Befehle aus, um systemd neu zu laden und Docker neu zu starten:

sudo systemctl daemon-reload
sudo systemctl restart docker

Der Befehl „daemon reload“ sagt systemd, dass es die neue Dienstkonfiguration lesen soll, während der Befehl „Docker restart“ die Änderungen in „ daemon.json “ anwendet.

Plattformspezifische Überlegungen

Docker Desktop macht die Proxy-Einstellungen anders als bei Server-Installationen. Unter Windows und macOS kannst du die Proxy-Einstellungen über die Docker Desktop-Benutzeroberfläche im Bereich „Ressourcen – Proxies“ vornehmen. Diese Einstellungen richten sowohl den Daemon als auch den Client automatisch ein.

Linux-Hosts mit Docker Engine brauchen die oben beschriebene manuelle Konfiguration. Manche Distributionen packen Docker anders, also check mal, ob dein System direkt dockerd nutzt oder über einen anderen Dienstmanager.

Überprüfe deine Einstellungen

Prüfe, ob Docker externe Registrierungen mit einem einfachen Pull-Befehl erreichen kann:

docker pull hello-world

Du kannst auch die aktuelle Konfiguration des Daemons checken:

docker system info | grep -i proxy

Hier siehst du, ob Docker deine Proxy-Einstellungen erkannt und übernommen hat.

Wenn das immer noch nicht klappt, check mal die Protokolle deines Proxy-Servers, um sicherzugehen, dass Docker die Anfragen richtig weiterleitet.

Hast du Probleme mit dem Netzwerk? Docker-Ports richtig freigeben, um Probleme mit der Verbindung zu vermeiden.

Proxy-Umgebungsvariablen einstellen

Docker-CLI-Befehle brauchen ihre eigene Proxy-Konfiguration, die von den Daemon-Einstellungen getrennt ist. Mit Umgebungsvariablen kannst du ganz flexibel steuern, wie Docker-Clients über Firmen-Proxys verbunden werden.

Client-Proxys steuern Docker-CLI-Operationen wie „ docker pull “, „ docker push “ und „ docker login “. Wenn du diese Befehle ausführst, macht der Docker-Client HTTP-Anfragen an Registries und muss wissen, welchen Proxy-Server er verwenden soll. Ohne Client-Proxy-Einstellungen funktionieren diese Vorgänge nicht, auch wenn der Daemon richtig eingerichtet ist.

JSON-Konfigurationsmethode

Der sauberste Ansatz nutzt die Konfigurationsdatei von Docker unter ~/.docker/config.json:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

Mit dieser Methode bleiben die Proxy-Einstellungen in der Docker-Konfiguration und haben keinen Einfluss auf andere Anwendungen auf deinem System.

Alternative für die Umgebungsvariable

Du kannst auch Standard-Proxy-Umgebungsvariablen festlegen, die Docker automatisch erkennt, indem du diese Befehle verwendest:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

Diese Variablen funktionieren für jede Anwendung, die Proxy-Standards beachtet – nicht nur für Docker.

Globale Konfiguration vs. Konfiguration pro Benutzer

Für die systemweite Konfiguration füg die Umgebungsvariablen zu „ /etc/environment ” hinzu oder erstelle ein Skript in „ /etc/profile.d/ ”:

# /etc/profile.d/proxy.sh
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

Für eine benutzerspezifische Konfiguration füge sie zu deinem Shell-Profil hinzu (~/.bashrc, ~/.zshrc) oder nutze die JSON-Konfigurationsmethode. Mit den Einstellungen pro Benutzer können Entwickler flexibel verschiedene Proxys nutzen oder sie zum Testen komplett umgehen.

Sicherheit

Du solltest Benutzernamen und Passwörter niemals in Konfigurationsdateien oder Umgebungsvariablen fest codieren. 

Proxy-Anmeldedaten im Klartext sind ein Sicherheitsrisiko, vor allem in geteilten Umgebungen oder Versionskontrollsystemen.

Probier lieber diese Ansätze aus:

• Konfigurier deinen Proxy-Server nach Möglichkeit für die IP-basierte Authentifizierung.
• Verwende Hilfsprogramme für Anmeldedaten oder sichere Speichersysteme für die Authentifizierung.
• Richte Service-Konten mit minimalen Berechtigungen für Docker-Operationen ein.

Wenn du Anmeldedaten angeben musst, benutze das Format „ http://username:password@proxy.company.com:8080 “, speicher diese aber in geschützten Dateien mit eingeschränkten Berechtigungen.

Proxy-Konfiguration beim Erstellen

Docker-Builds brauchen Proxy-Einstellungen, die explizit über Build-Argumente übergeben werden müssen:

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t myapp .

Build-Argumente werden zu Umgebungsvariablen innerhalb des Build-Kontexts.

Dadurch können die Befehle „ RUN “ Pakete und Abhängigkeiten über deinen Proxy herunterladen. Ohne diese Argumente schlagen Builds fehl, wenn Dockerfiles versuchen, Software zu installieren oder Ressourcen aus dem Internet abzurufen.

Die Proxy-Einstellungen aus der Build-Phase bleiben im finalen Image nicht erhalten, es sei denn, du legst sie explizit mit den Anweisungen „ ENV “ in deiner Dockerfile fest.

Mit Umgebungsvariablen kannst du die Proxy-Einstellungen ganz flexibel so anpassen, wie es für deinen Arbeitsablauf am besten passt.

Findest du Build-Argumente verwirrend? Lerne die Argumente für den Docker-Build mit echten Beispielen, die wirklich funktionieren.

Container und Proxy-Injektion während der Erstellung

Mit der Docker-Client-Konfiguration bist du erst halb fertig – deine Container und Builds brauchen ihre eigenen Proxy-Einstellungen. In diesem Abschnitt zeige ich dir, wie du die Proxy-Konfiguration zur Laufzeit und zur Erstellungszeit einfügen kannst.

Laufzeitumgebungsvariablen

Container übernehmen nicht die Proxy-Einstellungen deines Hosts.

Du musst Proxy-Variablen beim Starten von Containern explizit übergeben. Docker bietet dir mehrere Möglichkeiten, dies zu tun, je nachdem, ob du alle Container oder nur bestimmte Container konfigurieren möchtest.

Die JSON-Konfiguration ist der sauberste Weg für einheitliche Proxy-Einstellungen – wie schon erwähnt. Um das zusammenzufassen, füge das hier zu deiner Datei „ ~/.docker/config.json “ hinzu:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

Docker fügt diese Variablen automatisch in jeden Container ein, den du startest. Keine zusätzlichen Flags nötig.

CLI-Flags geben dir mehr Kontrolle über jeden Container:

docker run \
  --env HTTP_PROXY=http://proxy.company.com:8080 \
  --env HTTPS_PROXY=http://proxy.company.com:8080 \
  --env NO_PROXY=localhost,127.0.0.1 \
  nginx

Du kannst auch eine ganze Umgebungsdatei übergeben:

# proxy.env
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1

docker run --env-file proxy.env nginx

In vorhandene Container können nach dem Start mit „ docker exec “ Proxy-Variablen eingefügt werden:

docker exec -e HTTP_PROXY=http://proxy.company.com:8080 container_name curl google.com

Das klappt bei einzelnen Befehlen, bleibt aber nicht so, wenn der Container neu gestartet wird.

Proxy-Konfiguration beim Erstellen

Das Erstellen von Images klappt in Proxy-Umgebungen nicht, wenn du die Proxy-Einstellungen nicht extra angibst.

Build-Argumente sind die Standardmethode, um Proxy-Variablen während des Builds einzufügen:

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  --tag myapp .

Deine Dockerfile-Datei muss diese Argumente angeben, damit sie verwendet werden können:

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Use proxy for package installation
RUN apt-get update && apt-get install -y curl

# Don't persist proxy in final image

Mit Dockerfile-Deklarationen kannst du Standardwerte für den Proxy festlegen:

ARG HTTP_PROXY=http://proxy.company.com:8080
ARG HTTPS_PROXY=http://proxy.company.com:8080

ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN pip install requests

Der Befehl „ ENV “ macht Proxy-Variablen für alle folgenden „ RUN “-Befehle in deinem Build verfügbar.

Bitte beachte, dass Einschränkungen von BuildKit bei neueren Docker-Versionen zu Proxy-Problemen führen können. BuildKit speichert Build-Kontexte ziemlich aggressiv zwischen, was manchmal dazu führt, dass Proxy-Änderungen ignoriert werden.

Du kannst BuildKit dazu bringen, Proxy-Updates zu erkennen:

DOCKER_BUILDKIT=1 docker build \
  --no-cache \
  --build-arg HTTP_PROXY=$HTTP_PROXY \
  --tag myapp .

Oder du kannst BuildKit für proxy-empfindliche Builds komplett deaktivieren:

DOCKER_BUILDKIT=0 docker build --build-arg HTTP_PROXY=$HTTP_PROXY --tag myapp .

Bei mehrstufigen Builds muss die Proxy-Konfiguration in allen Phasen einheitlich sein:

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Build stage
FROM python:3.13 AS builder
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

COPY requirements.txt .
RUN pip install -r requirements.txt

# Runtime stage
FROM python:3.13-slim AS runtime
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

COPY --from=builder /usr/local/lib/python*/site-packages /usr/local/lib/python*/site-packages
RUN apt-get update && apt-get install -y curl

# Clear proxy variables for final image
ENV HTTP_PROXY=
ENV HTTPS_PROXY=
ENV NO_PROXY=

Jede Stufe übernimmt die Build-Argumente, aber nicht die Umgebungsvariablen aus den vorherigen Stufen. Proxy-Variablen musst du in jeder Phase, in der sie gebraucht werden, explizit setzen.

Kurz gesagt: Einmal einrichten, überall nutzen.

Bist du verwirrt wegen ENTRYPOINT und CMD in deinen Containern mit Proxy? Hol dir die komplette Aufschlüsselung mit praktischen Beispielen.

Konfigurieren von Paketmanagern für die Verwendung eines Proxys in Containern

Die Proxy-Einstellungen von Docker werden nicht automatisch an die Paketmanager in deinen Containern weitergegeben. Du musst jeden Paketmanager einzeln einrichten, um Pakete über deinen Firmenproxy runterladen zu können.

Paketmanager wie apt-get, yum und apk stellen direkte HTTP-Verbindungen zu Paket-Repositorys her. In eingeschränkten Netzwerken klappt das nicht, wenn der Paketmanager nicht weiß, dass du einen Proxy-Server benutzt.

Die normalen Umgebungsvariablen reichen nicht aus. Die meisten Paketmanager haben ihre eigenen Konfigurationsdateien, die die systemweiten Proxy-Einstellungen überschreiben.

Ubuntu/Debian: apt-get-Konfiguration

Erstell eine Proxy-Konfigurationsdatei, die „ apt-get “ während der Paketinstallation liest.

Füge das hier zu deiner Dockerfile hinzu:

FROM python:3.13

# Configure apt proxy
RUN echo 'Acquire::http::Proxy "http://proxy.company.com:8080";' > /etc/apt/apt.conf.d/proxy.conf && \
    echo 'Acquire::https::Proxy "http://proxy.company.com:8080";' >> /etc/apt/apt.conf.d/proxy.conf

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

Die Datei „ /etc/apt/apt.conf.d/proxy.conf “ sagt „ apt-get “, dass alle Paket-Downloads über deinen Proxy laufen sollen. Die Datei bleibt über alle Befehle „ RUN “ in deinem Build erhalten.

Du kannst auch Proxy-Ausschlüsse für interne Repositorys festlegen:

RUN echo 'Acquire::http::Proxy::internal.company.com "DIRECT";' >> /etc/apt/apt.conf.d/proxy.conf

Alpine Linux: apk-Konfiguration

Alpine nutzt den Paketmanager „ apk “, der die Proxy-Einstellungen von „ /etc/apk/repositories “ und den Umgebungsvariablen liest.

FROM python:3.13-alpine

# Configure apk proxy
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080

RUN apk add --no-cache curl wget

apk von Alpine hält sich an die Standard-HTTP-Proxy-Umgebungsvariablen, sodass du keine separaten Konfigurationsdateien brauchst. Du kannst aber auch eine eigene Datei erstellen, um mehr Kontrolle zu haben:

RUN echo 'http_proxy=http://proxy.company.com:8080' > /etc/environment && \
    echo 'https_proxy=http://proxy.company.com:8080' >> /etc/environment

CentOS/RHEL: yum-Konfiguration

CentOS- und RHEL-Systeme benutzen „ yum “ oder „ dnf “, die die Proxy-Einstellungen aus „ /etc/yum.conf “ holen.

FROM centos:8

# Configure yum proxy
RUN echo 'proxy=http://proxy.company.com:8080' >> /etc/yum.conf

RUN yum update -y && yum install -y curl wget

Für neuere CentOS-Versionen mit „ dnf “ mach Folgendes:

FROM centos:stream9

# Configure dnf proxy
RUN echo 'proxy=http://proxy.company.com:8080' >> /etc/dnf/dnf.conf

RUN dnf update -y && dnf install -y curl wget

Du kannst auch bestimmte Domänen vom Proxy-Routing ausschließen, indem du diesen Befehl hinzufügst:

RUN echo 'proxy_exclude=internal.company.com,localhost' >> /etc/yum.conf

Proxy-Funktion testen

Zuerst musst du checken, ob dein Paketmanager über den Proxy auf die Repositories zugreifen kann.

Füge Testbefehle zu deiner Dockerfile hinzu:

FROM python:3.13

# Configure proxy
RUN echo 'Acquire::http::Proxy "http://proxy.company.com:8080";' > /etc/apt/apt.conf.d/proxy.conf

# Test package manager connectivity
RUN apt-get update && \
    apt-get install -y --dry-run curl && \
    echo "Package manager proxy test passed"

# Install actual packages
RUN apt-get install -y curl python3-pip

Der Schalter „ --dry-run “ testet die Paketauflösung, ohne wirklich was zu installieren. Wenn das klappt, ist deine Proxy-Einstellung in Ordnung.

Du kannst auch mit ausführlicher Ausgabe testen, um Verbindungsprobleme zu beheben:

RUN apt-get -o Debug::Acquire::http=true update

Hier siehst du genau, welche URLs apt-get versucht zu erreichen und ob die Proxy-Verbindungen funktionieren.

Für Tests in den Alpen solltest du Folgendes verwenden:

RUN apk update --verbose && \
    apk add --simulate curl && \
    echo "Alpine proxy test passed"

Also nochmal: Stell jeden Paketmanager einzeln ein, dann funktionieren deine Builds auch über jeden Proxy.

Müssen Sie proxybezogene Build-Artefakte bereinigen? Mit den Docker-Prune-Befehlen kannst du Speicherplatz freigeben und dein System sauber halten.

Erweiterte Proxy-Implementierungen

Einfache HTTP-Proxys sind ein guter Anfang, aber in Produktionsumgebungen braucht man mehr Kontrolle über den Zugriff auf die Registrierung und das Zwischenspeichern von Images. So richtest du Caching-Proxys und Registrierungs-Mirrors ein, um die Leistung und Zuverlässigkeit zu verbessern.

Zwischenspeichern von Proxy-Registrierungen

Das ständige Herunterladen derselben Basisbilder verschwendet Bandbreite und verlangsamt den Build-Prozess.

Zwischenspeicher-Proxys sitzen zwischen deinen Docker-Clients und externen Registern wie Docker Hub. Sie speichern oft genutzte Bilder lokal, sodass spätere Abrufe über dein internes Netzwerk statt über das Internet erfolgen.

Die beliebteste Wahl für Unternehmensumgebungen ist Harbor:

# docker-compose.yml for Harbor
version: '3.8'
services:
  harbor-core:
    image: goharbor/harbor-core:v2.8.0
    environment:
      - CORE_SECRET=your-secret-key
      - JOBSERVICE_SECRET=your-job-secret
    ports:
      - "80:8080"
    volumes:
      - ./harbor.yml:/etc/core/app.conf

Du kannst Harbor als Proxy-Cache einrichten, indem du die Datei „ harbor.yml “ bearbeitest:

# harbor.yml
hostname: harbor.company.com
http:
  port: 80

database:
  password: harbor-db-password

data_volume: /data

proxy_cache:
  - endpoint: https://registry-1.docker.io
    username: your-dockerhub-username
    password: your-dockerhub-token

Wenn du eine einfachere Alternative für grundlegendes Caching suchst, probier Docker Registry Proxy aus. So geht's:

docker run -d \
  --name registry-proxy \
  -p 5000:5000 \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -v registry-cache:/var/lib/registry \
  registry:2

Dann richtest du deine Docker-Clients auf den Caching-Proxy:

{
  "registry-mirrors": ["http://harbor.company.com"]
}

Hier sind alle Vorteile, die du mit Caching-Proxys bekommst:

• Schnelleres Abrufen von Bildern nach dem ersten Download
• Weniger Internet-Bandbreite verbraucht
• Verbessere die Zuverlässigkeit beim Erstellen, wenn es Probleme mit externen Registern gibt.
• Zentrale Zugriffskontrolle und Bildscannen

Registry-Spiegel und BuildKit

Mit Registry-Mirrors kannst du das Abrufen von Images auf interne oder näher gelegene Registries umleiten.

Mit der Einzelspiegelkonfiguration werden alle Docker Hub-Anfragen über einen Spiegel geleitet:

{
  "registry-mirrors": ["https://mirror.company.com"],
  "insecure-registries": ["harbor.company.com:5000"]
}

Füge das hier zu „ /etc/docker/daemon.json “ hinzu und starte Docker neu. Alle Befehle „ docker pull “ versuchen es zuerst über den Mirror und greifen dann auf Docker Hub zurück, wenn der Mirror nicht verfügbar ist.

Mehrere Spiegel sorgen für Redundanz:

{
  "registry-mirrors": [
    "https://mirror1.company.com",
    "https://mirror2.company.com",
    "https://registry-1.docker.io"
  ]
}

Docker probiert die Spiegel nacheinander aus, bis einer funktioniert.

Die Einrichtung des BuildKit-Spiegels muss separat konfiguriert werden, da BuildKit einige Daemon-Einstellungen umgeht:

# buildkitd.toml
debug = true

[registry."docker.io"]
  mirrors = ["mirror.company.com"]

[registry."mirror.company.com"]
  http = true
  insecure = true

Du kannst BuildKit mit der benutzerdefinierten Konfiguration starten:

buildkitd --config=/etc/buildkit/buildkitd.toml

Oder nimm die Inline-Spiegelkonfiguration von BuildKit:

docker buildx create \
  --name mybuilder \
  --config /etc/buildkit/buildkitd.toml \
  --use

Teste zum Schluss deine Spiegelkonfiguration, indem du ein Image erstellst, das aus Docker Hub gezogen wird:

FROM python:3.13-slim
RUN pip install requests

docker build --progress=plain .

Das Flag „ --progress=plain “ zeigt an, welche Registrierung BuildKit tatsächlich kontaktiert. Du solltest deine Spiegel-URLs in der Build-Ausgabe sehen.

Das war's schon!

Komplizierte Proxy-Setups mit mehreren Containern verwalten? Docker Compose macht die Vernetzung und die Erkennung von Diensten einfacher.

Sicherheit verbessern

Proxy-Konfigurationen bringen neue Angriffsmöglichkeiten mit sich, die man echt im Auge behalten sollte. So sperrst du den Zugriff auf den Docker-Socket und schützt die Proxy-Anmeldedaten vor unbefugtem Zugriff.

Docker-Socket-Proxy

Wenn du den Socket von Docker direkt freigibst, ist das ein echtes Sicherheitsrisiko.

Der Docker-Socket (/var/run/docker.sock) gibt dir Root-Zugriff auf dein gesamtes Host-System. Jeder Prozess, der auf diesen Socket schreiben kann, kann Container mit Zugriff auf das Dateisystem des Hosts starten, Rechte ausweiten oder die Isolation des Containers komplett umgehen.

Die direkte Sockelmontage ist gefährlich:

# DON'T DO THIS
docker run -v /var/run/docker.sock:/var/run/docker.sock myapp

Dieses Muster taucht in Docker-in-Docker-Setups und CI/CD-Pipelines auf, ist aber ein echtes Sicherheitsproblem. Ein gehackter Container kann den ganzen Docker-Daemon kontrollieren.

Socket-Proxy-Dienste machen die Verbindung sicherer, indem sie eine zusätzliche Schicht dazwischen schalten. Sie filtern Docker-API-Aufrufe und schränken ein, was Container tatsächlich tun können.

Probier mal den Docker-Socket-Proxy von Tecnativa aus:

# docker-compose.yml
version: '3.8'
services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - CONTAINERS=1
      - IMAGES=1
      - NETWORKS=1
      - VOLUMES=1
      - BUILD=0
      - COMMIT=0
      - CONFIGS=0
      - SECRETS=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "2375:2375"

Der Proxy zeigt nur bestimmte Docker-API-Endpunkte an. Setz die Umgebungsvariablen auf „ 1 “ für erlaubte Vorgänge und auf „ 0 “ für gesperrte Vorgänge.

Deine Anwendungen verbinden sich mit dem Proxy statt mit dem Raw-Socket:

docker run --env DOCKER_HOST=tcp://docker-proxy:2375 myapp

Hier sind noch ein paar Tipps, wie du die Sicherheit deiner Sockets verbessern kannst:

• Starte den Socket-Proxy in einem separaten Netzwerksegment.
• TLS-Authentifizierung zwischen Clients und dem Proxy verwenden
• Überwach die Proxy-Protokolle der Sockets auf verdächtige API-Aufrufe.
• Proxy-Zugangsdaten regelmäßig ändern

Verwaltung von Anmeldedaten

Proxy-Anmeldedaten in Klartext-URLs tauchen überall auf – in Protokollen, Prozesslisten und Umgebungsauszügen.

Verpackt niemals Anmeldedaten in Proxy-URLs:

# SECURITY RISK - credentials visible in process list
export HTTP_PROXY=http://admin:password123@proxy.company.com:8080

Jeder, der Zugriff auf „ ps aux “ oder Umgebungsvariablendumps hat, kann dein Proxy-Passwort sehen. Dazu gehören Anwendungsprotokolle, Containerüberprüfung und Tools zur Systemüberwachung.

Verwende stattdessen Authentifizierungsdateien:

# Create credentials file with restricted permissions
echo "admin:password123" > ~/.proxy-creds
chmod 600 ~/.proxy-creds

# Configure proxy without embedded credentials
export HTTP_PROXY=http://proxy.company.com:8080

Richte deinen Proxy-Server so ein, dass er die Anmeldedaten aus der Datei liest, oder nutze externe Authentifizierungssysteme.

TLS-Proxys verschlüsseln den ganzen Proxy-Datenverkehr, auch die Authentifizierungs-Handshakes:

# HTTPS proxy encrypts credentials in transit
export HTTPS_PROXY=https://proxy.company.com:8443

Richte deinen Proxy-Server mit den richtigen TLS-Zertifikaten ein – entweder von einer Zertifizierungsstelle oder mit selbst signierten Zertifikaten, die auf den Client-Rechnern verteilt werden.

Mit der Zertifikat-basierten Authentifizierung brauchst du keine Passwörter mehr:

# Client certificate authentication
export HTTPS_PROXY=https://proxy.company.com:8443
curl --cert client.crt --key client.key --cacert proxy-ca.crt https://example.com

Der Proxy überprüft Client-Zertifikate statt Benutzername/Passwort-Kombinationen. Zertifikate können einzeln gesperrt werden, wenn sie in die falschen Hände geraten sind.

Die Geheimnisverwaltung von Kubernetes hält Proxy-Anmeldedaten aus Container-Images raus:

apiVersion: v1
kind: Secret
metadata:
  name: proxy-credentials
type: Opaque
data:
  username: YWRtaW4=  # base64 encoded
  password: cGFzc3dvcmQxMjM=  # base64 encoded

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: myapp
        env:
        - name: PROXY_USER
          valueFrom:
            secretKeyRef:
              name: proxy-credentials
              key: username
        - name: PROXY_PASS
          valueFrom:
            secretKeyRef:
              name: proxy-credentials
              key: password

Geheimnisse bleiben im Ruhezustand verschlüsselt und werden zur Laufzeit eingefügt, ohne in Bildschichten zu erscheinen.

Sperr den Zugriff auf Sockets und verschlüssele deine Zugangsdaten – dein zukünftiges Ich wird es dir danken.

Suchst du nach Alternativen zu Docker für deine Proxy-Einrichtung? Vergleich Docker mit Podman, um das richtige Containerisierungstool für dich zu finden.

Häufige Probleme lösen

Proxy-Probleme zeigen sich als Zeitüberschreitungen, Verbindungsfehler und mysteriöse Build-Fehler, die außerhalb deines Netzwerks kein Problem machen. Hier ist ein systematischer Ansatz, um die häufigsten Probleme mit dem Docker-Proxy zu finden und zu beheben.

Strukturierter Diagnoseansatz

Fang mit den Grundlagen an und arbeite dich dann nach oben.

Schritt 1: Überprüfe die Proxy-Verbindung vom Host aus.

Probier mal, ob dein Proxy-Server erreichbar ist:

curl -x http://proxy.company.com:8080 https://registry-1.docker.io/v2/

Wenn das nicht klappt, stimmt was mit deiner Proxy-Einstellung oder deinem Netzwerk-Routing nicht. Wende dich an dein Netzwerkteam, bevor du Probleme mit Docker behebst.

Schritt 2: Überprüfe die Proxy-Einstellungen des Docker-Daemons.

Überprüfe, ob der Daemon deine Proxy-Einstellungen richtig liest:

docker info | grep -i proxy

Du solltest jetzt deine Proxy-URLs aufgelistet sehen. Wenn sie fehlen, schau mal unter „ /etc/docker/daemon.json “ nach und starte den Docker-Dienst neu.

Schritt 3: Docker-Client-Operationen testen

Versuch mal, ein einfaches Bild zu laden:

docker pull hello-world

Wenn das klappt, sind die Einstellungen für den Client-Proxy in Ordnung. Der Fehler deutet auf Probleme mit dem Proxy auf Daemon-Ebene hin.

Schritt 4: Verbindung auf Containerebene testen

Starte einen Container und probier die ausgehenden Verbindungen aus:

docker run --rm \
  -e HTTP_PROXY=http://proxy.company.com:8080 \
  -e HTTPS_PROXY=http://proxy.company.com:8080 \
  python:3.13-slim \
  python -c "import urllib.request; print(urllib.request.urlopen('https://pypi.org').getcode())"

Dadurch wird herausgefunden, ob das Problem bei den Docker-Vorgängen oder beim Container-Netzwerk liegt.

Häufige Probleme und Lösungen

Problem: „ docker pull “ läuft ab

Dieser Fehler wird angezeigt, wenn Docker keine externen Registrierungen erreichen kann:

Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io: no such host

Teste erst mal die grundlegende Verbindung, um zu sehen, wo das Problem liegt:

# Check if DNS resolution works through proxy
nslookup registry-1.docker.io

# Test direct registry access
curl -I https://registry-1.docker.io/v2/

# Verify daemon proxy configuration
sudo journalctl -u docker.service | grep -i proxy

Behebe das Problem, indem du die DNS- und Proxy-Einstellungen überprüfst:

• DNS-Server hinzufügen zu /etc/docker/daemon.json

• NO_PROXY für interne DNS-Server einrichten

• Überprüfe, ob der Proxy die HTTPS CONNECT-Methode unterstützt.

Problem: Die Installation des Pakets schlägt während des Builds fehl.

Paketmanager in Containern können nicht auf Repositorys zugreifen und zeigen Fehler wie diesen an:

E: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/jammy/Release

Probier mal die Verbindung zum Paketmanager direkt in einem temporären Container aus:

# Test package manager connectivity in a running container
docker run -it --rm python:3.13 bash
apt-get update -o Debug::Acquire::http=true

Die ausführliche Ausgabe zeigt genau, wo die Verbindung nicht klappt.

Löse das, indem du die Paketmanager so einstellst, dass sie deinen Proxy benutzen:

• Konfigurier die Proxy-Einstellungen für den Paketmanager in der Dockerfile
• Proxy-Build-Argumente an Docker-Build übergeben
• Schau mal, ob der Proxy die Domains des Paket-Repositorys blockiert.

Problem: BuildKit ignoriert die Proxy-Einstellungen

BuildKit geht mit Proxys anders um als der alte Builder, was zu Fehlern wie diesem führt:

failed to solve: failed to fetch remote https://github.com/user/repo.git

Probier mal aus, ob das Problem mit BuildKit zu tun hat, indem du deine Builder-Einstellungen checkst:

# Check BuildKit configuration
docker buildx inspect

# Build with legacy builder
DOCKER_BUILDKIT=0 docker build .

Wenn der Legacy Builder funktioniert, hast du ein Problem mit der BuildKit-Proxy-Konfiguration.

Behebt Probleme mit dem BuildKit-Proxy mit diesen Ansätzen:

• Konfigurier die BuildKit-spezifischen Proxy-Einstellungen in buildkitd.toml
• Verwende „ --build-arg “, um Proxy-Variablen explizit zu übergeben.
• BuildKit für proxy-sensitive Builds deaktivieren

Problem: Der Container kann keine externen Dienste erreichen.

Deine Anwendung im Container kann keine Verbindung zu externen APIs herstellen:

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='api.example.com', port=443)

Finde den Fehler, indem du die Verbindung aus dem Container heraus testest:

# Test from inside the container
docker exec container_name curl -v https://api.example.com

# Check container environment variables
docker exec container_name env | grep -i proxy

Hier siehst du, ob die Proxy-Variablen da sind und ob die Verbindung geklappt hat.

Löse Probleme mit der Container-Verbindung, indem du sicherstellst, dass der Proxy richtig eingerichtet ist:

• Proxy-Umgebungsvariablen zur Laufzeit übergeben
• Proxy-Einstellungen für bestimmte Apps anpassen
• Ziel zur NO_PROXY-Liste hinzufügen

Log-Analyse und Konnektivitätstests

Die Protokolle des Docker-Daemons zeigen dir alles, was bei Proxy-Verhandlungen passiert und was schiefgelaufen ist.

Auf Systemen mit systemd kannst du mit „ journalctl “ die Docker-Dienstprotokolle in Echtzeit verfolgen:

# SystemD systems
sudo journalctl -u docker.service -f

Bei Systemen, die normale Log-Dateien nutzen, schau einfach direkt im Docker-Log nach:

# Direct log file
sudo tail -f /var/log/docker.log

Such in den Protokollen nach bestimmten Mustern, die mit Proxys zu tun haben. Verbindungsfehler zeigen an, dass der Proxy-Server nicht erreichbar ist. Fehler bei der Authentifizierung werden als Meldung „407 Proxy-Authentifizierung erforderlich“ angezeigt. Zeitüberschreitungsfehler deuten auf Probleme mit der Netzwerkverbindung oder eine Überlastung des Proxy-Servers hin.

Testen auf Containerebene mit curl und wget geben dir einen genauen Einblick ins Proxy-Verhalten.

Teste HTTP-Verbindungen über deinen Proxy, um genau zu sehen, was während des Handshakes passiert:

# Test HTTP proxy
docker run --rm \
  -e HTTP_PROXY=http://proxy.company.com:8080 \
  python:3.13-slim \
  curl -v http://httpbin.org/ip

Die ausführliche Ausgabe zeigt die DNS-Auflösung, den Aufbau der Proxy-Verbindung und den tatsächlichen Ablauf der HTTP-Anfrage. Wenn der Proxy-Tunnel richtig funktioniert, siehst du Zeilen wie „Verbunden mit proxy.company.com“ gefolgt von „CONNECT httpbin.org:80“.

HTTPS-Verbindungen brauchen einen Proxy, der die CONNECT-Methode unterstützt:

# Test HTTPS proxy
docker run --rm \
  -e HTTPS_PROXY=http://proxy.company.com:8080 \
  python:3.13-slim \
  curl -v https://httpbin.org/ip

Achte auf „CONNECT httpbin.org:443 HTTP/1.1” in der Ausgabe. Wenn du die Meldung „Methode nicht erlaubt“ oder so ähnlich siehst, unterstützt dein Proxy kein HTTPS-Tunneling.

Probier mal die Authentifizierung aus, indem du die Anmeldedaten in die Proxy-URL einbaust:

# Test with authentication
docker run --rm \
  -e HTTPS_PROXY=http://user:pass@proxy.company.com:8080 \
  python:3.13-slim \
  wget -O- https://httpbin.org/ip

Authentifizierungsfehler werden als „407 Proxy Authentication Required”-Antworten angezeigt. Wenn die Authentifizierung klappt, geht's direkt zur gewünschten Anfrage.

Debugging auf Netzwerkebene mit tcpdump fängt die echten Pakete zwischen Docker und deinem Proxy-Server ab.

Starte tcpdump, um den gesamten Datenverkehr zu deinem Proxy anzuzeigen:

# Capture proxy traffic
sudo tcpdump -i any host proxy.company.com and port 8080

Diese rohe Paketaufzeichnung zeigt Verbindungsversuche, Datenübertragungen und Verbindungsabbrüche. Achte auf den Aufbau einer TCP-Verbindung (SYN/ACK-Pakete) und dann auf HTTP-Datenverkehr. Verbindungszeitüberschreitungen werden als wiederholte SYN-Pakete ohne Antwort angezeigt.

DNS-Auflösungstests beseitigt eine häufige Ursache für Probleme mit Proxys.

Viele Proxy-Probleme sind eigentlich nur DNS-Probleme, die sich anders zeigen. DNS-Auflösung in Containern testen:

# Test DNS inside containers  
docker run --rm python:3.13-slim nslookup registry-1.docker.io

Wenn das nicht klappt, kann der Container überhaupt keine Domainnamen auflösen. Probier mal einen öffentlichen DNS-Server, um das Problem einzugrenzen:

# Test with custom DNS
docker run --dns 8.8.8.8 --rm python:3.13-slim nslookup registry-1.docker.io

In Firmen gibt's oft DNS-Server, die nur innerhalb des Netzwerks funktionieren. Dein Proxy muss vielleicht DNS-Anfragen und HTTP-Datenverkehr verarbeiten, oder du musst Container mit bestimmten DNS-Servern konfigurieren, die über deinen Proxy laufen.

Geh jede Schicht systematisch durch, dann findest du die Ursache.

Suchst du nach Optionen, die Proxys anders handhaben? Wir haben einen Leitfaden zu Docker-Alternativen, damit du dir einen Überblick über die aktuellen Containerisierungstools im Jahr 2025 verschaffen kannst.

Fazit

Bei der Docker-Proxy-Konfiguration geht's nicht nur darum, Images runterzuladen, sondern auch darum, zuverlässige und sichere containerisierte Anwendungen in Unternehmensumgebungen zu erstellen.

Ich habe dir gezeigt, wie du die Proxy-Einstellungen auf vier verschiedenen Ebenen konfigurieren kannst: Client-Operationen, Daemon-Prozesse, Container-Laufzeit und Build-Operationen. Jede Schicht hat einen bestimmten Zweck und braucht ihre eigene Konfiguration, von JSON-Dateien und Umgebungsvariablen bis hin zu Paketmanager-Einstellungen und BuildKit-Konfigurationen. Eine mehrschichtige Proxy-Strategie schützt dich vor einzelnen Fehlerquellen.

Willst du mehr über Docker, Containerisierung und Sicherheit erfahren ? Schau dir unsere Liste mit ausgewählten Kursen an:

• Einführung in Docker
• Docker für Fortgeschrittene
• Containerisierung und Virtualisierung – Was ist das?
• Containerisierung und Virtualisierung mit Docker und Kubernetes
• DevOps-Konzepte
• Einführung in Kubernetes