Proxy de Docker: Guía completa para que los contenedores funcionen detrás de los cortafuegos corporativos

La mayoría de las redes empresariales utilizan servidores proxy para supervisar y filtrar el tráfico de Internet. Esto crea barreras cuando Docker intenta extraer imágenes de los registros. Te encontrarás con tiempos de espera de conexión, errores de autenticación y compilaciones fallidas que funcionan en tu red doméstica. Estos problemas relacionados con los proxies pueden entorpecer el trabajo de los equipos de desarrollo que no pueden acceder a las imágenes base que necesitan.

La configuración del proxy de Docker resuelve estos problemas de conectividad al tiempo que mejora el rendimiento mediante el almacenamiento en caché y cumple los requisitos de seguridad corporativos. Una vez configurados, tus contenedores extraerán imágenes independientemente de las restricciones de red.

En este tutorial, te guiaré a través de la configuración del proxy del demonio Docker, la configuración de las variables de entorno del contenedor y el manejo de la configuración del proxy en Docker Compose.

¿Eres nuevo en Docker y te sientes abrumado por todos los conceptos de redes? Comienza con los conceptos básicos de Docker y gana confianza paso a paso.

Comprender la arquitectura del proxy de Docker

Las diferentes partes del ecosistema Docker necesitan una configuración de proxy en diferentes capas.

Los proxies actúan como intermediarios entre los componentes de Docker y las redes externas. Cuando Docker necesita extraer imágenes, los contenedores necesitan acceso a Internet o las compilaciones requieren recursos externos, los servidores proxy controlan y supervisan estas conexiones. Se sitúan entre tus aplicaciones en contenedores y el mundo exterior, filtrando las solicitudes y las respuestas.

Las organizaciones utilizan proxies con Docker para mejorar el rendimiento, la seguridad y el cumplimiento normativo.

El rendimiento se obtiene al almacenar en caché los recursos a los que se accede con frecuencia, como las imágenes base, lo que reduce los tiempos de descarga de todo el equipo. Las ventajas en materia de seguridad incluyen el filtrado del tráfico, el análisis de malware y el bloqueo del acceso a sitios no autorizados. Los requisitos de cumplimiento exigen que todo el tráfico de red pase por canales supervisados con controles de acceso y registros de auditoría adecuados.

La configuración del proxy de Docker se realiza en cuatro capas:

• Proxy del cliente: afecta a los comandos de la CLI de Docker, como docker pull y docker push

• Proxy daemon: controla cómo el demonio Docker accede a los registros externos

• Proxy de tiempo de ejecución del contenedor: establece variables proxy para aplicaciones dentro de contenedores.

• Proxy de tiempo de compilación: gestiona la configuración del proxy durante las operaciones « docker build » cuando los archivos Dockerfile necesitan acceso a Internet.

Cada capa tiene una función y requiere su propio enfoque de configuración.

Para comprender las redes de Docker, primero hay que entender cómo se comunican los contenedores. 

Configuración de Docker para utilizar un proxy

Para que Docker funcione con el proxy de tu empresa, debes configurar tanto el demonio como el cliente de Docker.

¿Por qué? Porque gestionan diferentes tipos de solicitudes de red. 

El demonio gestiona las extracciones y envíos de imágenes, así como la autenticación del registro, mientras que el cliente se encarga de las operaciones de la CLI y las llamadas a la API. Si falta alguna de las configuraciones, se producirán lagunas que pueden provocar errores de conexión en las operaciones de Docker.

Cómo configurar el demonio Docker

El demonio Docker lee la configuración del proxy desde /etc/docker/daemon.json. Crea este archivo si no existe:

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

El campo « noProxy » (Excepciones de proxy) muestra las direcciones que deben omitir el proxy. Incluye aquí tus dominios de registro interno y direcciones localhost.

Configuración de las anulaciones del servicio systemd

En sistemas Linux basados en systemd, también es necesario configurar el propio servicio Docker para que utilice el proxy. Crea el directorio de anulación y el archivo de configuración:

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

A continuación, añade estas variables de entorno al archivo http-proxy.conf:

[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"

Esto garantiza que el proceso del demonio Docker pueda acceder a servicios externos a través de tu proxy.

Docker no detectará los cambios en el proxy hasta que reinicies el demonio. Ejecuta estos comandos para recargar systemd y reiniciar Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

El comando «daemon reload» indica a systemd que lea la nueva configuración del servicio, mientras que «Docker restart» aplica los cambios en « daemon.json ».

Consideraciones específicas de la plataforma

Docker Desktop gestiona la configuración del proxy de forma diferente a las instalaciones en servidor. En Windows y macOS, utiliza la interfaz gráfica de usuario de Docker Desktop para configurar los ajustes del proxy en la sección Recursos - Proxies. Estos ajustes configuran automáticamente tanto el demonio como el cliente.

Los hosts Linux que utilizan Docker Engine necesitan la configuración manual descrita anteriormente. Algunas distribuciones empaquetan Docker de forma diferente, así que comprueba si tu sistema utiliza dockerd directamente o a través de un gestor de servicios diferente.

Verificación de la configuración

Comprueba que Docker puede acceder a registros externos con un sencillo comando pull:

docker pull hello-world

También puedes comprobar la configuración efectiva del demonio:

docker system info | grep -i proxy

Esto muestra si Docker ha detectado y aplicado tu configuración de proxy.

Si las extracciones siguen fallando, comprueba los registros del servidor proxy para confirmar que Docker está enrutando las solicitudes correctamente.

¿Tienes problemas con la red? Exponen correctamente los puertos de Docker para evitar problemas de conectividad.

Configuración de variables de entorno de proxy

Los comandos de la CLI de Docker necesitan su propia configuración de proxy, independiente de la configuración del demonio. Las variables de entorno te ofrecen un control flexible sobre cómo se conectan los clientes de Docker a través de proxies corporativos.

Los proxies de clientes controlan las operaciones de la CLI de Docker, como docker pull, docker push y docker login. Cuando ejecutas estos comandos, el cliente Docker realiza solicitudes HTTP a los registros y necesita saber qué servidor proxy debe utilizar. Sin la configuración del proxy del cliente, estas operaciones fallan incluso cuando el demonio está correctamente configurado.

Método de configuración JSON

El método más limpio utiliza el archivo de configuración de Docker en ~/.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"
    }
  }
}

Este método mantiene la configuración del proxy dentro de la configuración de Docker y no afecta a otras aplicaciones del sistema.

Variable de entorno alternativa

También puedes configurar variables de entorno proxy estándar que Docker detectará automáticamente utilizando estos comandos:

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

Estas variables funcionan para cualquier aplicación que respete los estándares de proxy, no solo para Docker.

Configuración global frente a configuración por usuario

Para la configuración de todo el sistema, añade las variables de entorno a /etc/environment o crea un script en /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

Para la configuración por usuario, añádelos a tu perfil de terminal (~/.bashrc, ~/.zshrc) o utiliza el método de configuración JSON. La configuración por usuario ofrece a los programadores flexibilidad para utilizar diferentes proxies o ignorarlos por completo para realizar pruebas.

Consideraciones de seguridad

Nunca debes codificar de forma fija los nombres de usuario y contraseñas en archivos de configuración o variables de entorno. 

Las credenciales de proxy en texto sin formato crean riesgos de seguridad, especialmente en entornos compartidos o sistemas de control de versiones.

En su lugar, utiliza estos enfoques:

• Configura tu servidor proxy para la autenticación basada en IP siempre que sea posible.
• Utiliza ayudantes de credenciales o sistemas de almacenamiento seguro para la autenticación.
• Configurar cuentas de servicio con permisos mínimos para operaciones de Docker.

Si debes incluir credenciales, utiliza el formato http://username:password@proxy.company.com:8080, pero guárdalas en archivos protegidos con permisos restringidos.

Configuración del proxy en tiempo de compilación

Las compilaciones de Docker necesitan que la configuración del proxy se pase explícitamente a través de los argumentos de compilación:

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 .

Los argumentos de compilación se convierten en variables de entorno dentro del contexto de compilación.

Esto permite que las instrucciones « RUN » descarguen paquetes y dependencias a través de tu proxy. Sin estos argumentos, las compilaciones fallan cuando los archivos Dockerfile intentan instalar software u obtener recursos de Internet.

La configuración del proxy en tiempo de compilación no se mantiene en la imagen final a menos que la establezcas explícitamente con las instrucciones ENV en tu Dockerfile.

Las variables de entorno te ofrecen flexibilidad para gestionar la configuración del proxy al nivel adecuado para tu flujo de trabajo.

¿Te resultan confusos los argumentos de compilación? Domina los argumentos de compilación de Docker con ejemplos reales que realmente funcionan.

Inyección de proxy en contenedores y en tiempo de compilación

La configuración del cliente Docker solo te lleva hasta la mitad del camino: tus contenedores y compilaciones necesitan su propia configuración de proxy. En esta sección, te mostraré cómo inyectar la configuración del proxy en tiempo de ejecución y en tiempo de compilación.

Variables de entorno de tiempo de ejecución

Los contenedores no heredan la configuración de proxy de tu host.

Debes pasar las variables proxy explícitamente al iniciar los contenedores. Docker te ofrece varias formas de hacerlo, dependiendo de si deseas configurar todos los contenedores o solo algunos específicos.

La configuración JSON es el método más limpio para obtener una configuración de proxy coherente, como se ha comentado anteriormente. En resumen, añade esto a tu archivo ~/.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"
    }
  }
}

Docker inyecta automáticamente estas variables en cada contenedor que inicias. No se necesitan banderas adicionales.

Las banderas CLI te proporcionan más control por contenedor:

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

También puedes pasar un archivo de entorno completo:

# 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

Los contenedores existentes pueden recibir variables proxy inyectadas después del inicio utilizando docker exec:

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

Este enfoque funciona para comandos únicos, pero no persiste tras reiniciar el contenedor.

Configuración del proxy en tiempo de compilación

La creación de imágenes falla en entornos proxy a menos que pases explícitamente la configuración del proxy.

Los argumentos de compilación son la forma estándar de inyectar variables proxy durante las compilaciones:

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 .

Tu Dockerfile debe declarar estos argumentos para poder utilizarlos:

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

Las declaraciones de Dockerfile te permiten establecer valores predeterminados para el proxy:

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

La instrucción « ENV » hace que las variables proxy estén disponibles para todos los comandos « RUN » posteriores en la compilación.

Debes tener en cuenta que las limitaciones de BuildKit pueden causar problemas de proxy con las versiones más recientes de Docker. BuildKit almacena en caché los contextos de compilación de forma agresiva, lo que a veces ignora los cambios de proxy.

Puedes forzar a BuildKit para que reconozca las actualizaciones del proxy:

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

O bien, puedes desactivar BuildKit por completo para compilaciones sensibles al proxy:

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

Cuando se trata de compilaciones en varias etapas, es necesario que la configuración del proxy sea coherente en todas las etapas:

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=

Cada etapa hereda los argumentos de compilación, pero no las variables de entorno de las etapas anteriores. Establece las variables proxy explícitamente en cada etapa que las necesite.

En resumen: configura una vez, inyecta en todas partes.

¿Tenéis dudas sobre la diferencia entre ENTRYPOINT y CMD en vuestros contenedores habilitados para proxy? Obtén el desglose completo con ejemplos prácticos.

Configuración de los gestores de paquetes para utilizar un proxy en contenedores

La configuración del proxy de Docker no se aplica automáticamente a los gestores de paquetes dentro de los contenedores. Debes configurar cada gestor de paquetes por separado para descargar paquetes a través del proxy corporativo.

Los gestores de paquetes como apt-get, yum y apk establecen conexiones HTTP directas con los repositorios de paquetes. En entornos de red restringidos, estas conexiones fallan a menos que el gestor de paquetes conozca tu servidor proxy.

Las variables de entorno estándar no son suficientes. La mayoría de los gestores de paquetes tienen sus propios archivos de configuración que anulan los ajustes de proxy del sistema.

Ubuntu/Debian: configuración de apt-get

Crea un archivo de configuración de proxy que apt-get leerá durante la instalación del paquete.

Añade esto a tu Dockerfile:

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

El archivo /etc/apt/apt.conf.d/proxy.conf indica a apt-get que dirija todas las descargas de paquetes a través de tu proxy. El archivo persiste a través de los comandos « RUN » en tu compilación.

También puedes configurar exclusiones de proxy para repositorios internos:

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

Alpine Linux: configuración de apk

Alpine utiliza el gestor de paquetes apk, que lee la configuración del proxy desde /etc/apk/repositories y las variables de entorno.

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 de Alpine respeta las variables de entorno proxy HTTP estándar, por lo que no necesitas archivos de configuración independientes. Pero puedes crear uno para tener más control:

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

CentOS/RHEL: configuración de yum

Los sistemas CentOS y RHEL utilizan yum o dnf, que leen la configuración del proxy desde /etc/yum.conf.

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

Para las versiones más recientes de CentOS que utilizan dnf, utiliza lo siguiente:

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

También puedes excluir dominios específicos del enrutamiento del proxy añadiendo este comando:

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

Prueba de la funcionalidad del proxy

En primer lugar, debes comprobar que tu gestor de paquetes puede acceder a los repositorios a través del proxy.

Añade comandos de prueba a tu Dockerfile:

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

La bandera --dry-run comprueba la resolución del paquete sin instalar nada. Si tiene éxito, la configuración del proxy funciona.

También puedes probar con una salida detallada para depurar problemas de conexión:

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

Esto muestra exactamente a qué URL intenta acceder apt-get y si las conexiones proxy se realizan correctamente.

Para las pruebas alpinas, utiliza lo siguiente:

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

En resumen, configura cada gestor de paquetes individualmente y tus compilaciones funcionarán detrás de cualquier proxy.

¿Necesitas limpiar los artefactos de compilación relacionados con el proxy? Los comandos prune de Docker liberarán espacio y mantendrán tu sistema limpio.

Implementaciones avanzadas de proxy

Los proxies HTTP básicos son suficientes para empezar, pero los entornos de producción necesitan un mayor control sobre el acceso al registro y el almacenamiento en caché de imágenes. A continuación se explica cómo configurar proxies de almacenamiento en caché y réplicas del registro para mejorar el rendimiento y la fiabilidad.

Registros proxy de almacenamiento en caché

Extraer las mismas imágenes base una y otra vez desperdicia ancho de banda y ralentiza las compilaciones.

Los proxies de almacenamiento en caché se sitúan entre tus clientes Docker y registros externos como Docker Hub. Almacenan las imágenes a las que se accede con frecuencia de forma local, por lo que las descargas posteriores se realizan desde tu red interna en lugar de desde Internet.

La opción más popular para entornos empresariales es 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

Puedes configurar Harbor como caché proxy editando harbor.yml:

# 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

Si necesitas una alternativa más sencilla para el almacenamiento en caché básico, utiliza Docker Registry Proxy. Así es como se hace:

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

A continuación, dirige tus clientes Docker al proxy de almacenamiento en caché:

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

Estas son todas las ventajas que obtienes con los proxies de almacenamiento en caché:

• Descarga más rápida de imágenes tras la primera descarga.
• Reducción del uso del ancho de banda de Internet
• Mejora la fiabilidad de las compilaciones cuando los registros externos tienen problemas.
• Control de acceso centralizado y escaneo de imágenes

Espejos del registro y BuildKit

Los espejos de registro te permiten redirigir las extracciones de imágenes a registros internos o geográficamente más cercanos.

La configuración de espejo único enruta todas las solicitudes de Docker Hub a través de un espejo:

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

Añade esto a /etc/docker/daemon.json y reinicia Docker. Todos los comandos docker pull intentarán primero el espejo y, si no está disponible, recurrirán a Docker Hub.

Los múltiples espejos proporcionan redundancia:

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

Docker probará los espejos en orden hasta que uno funcione.

La configuración del espejo BuildKit requiere una configuración independiente, ya que BuildKit omite algunos ajustes del demonio:

# buildkitd.toml
debug = true

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

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

Puedes iniciar BuildKit con la configuración personalizada:

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

O bien, utiliza la configuración de espejo en línea de BuildKit:

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

Por último, prueba la configuración del espejo creando una imagen que se extraiga de Docker Hub:

FROM python:3.13-slim
RUN pip install requests

docker build --progress=plain .

La bandera ` --progress=plain ` muestra qué registro contacta realmente BuildKit. Deberías ver las URL de tus espejos en el resultado de la compilación.

¡Eso es todo!

¿Gestionas configuraciones complejas de proxy con varios contenedores? Docker Compose simplifica la creación de redes y la detección de servicios.

Refuerzo de la seguridad

Las configuraciones de proxy abren nuevas posibilidades de ataque que requieren una atención especial. A continuación se explica cómo bloquear el acceso al socket de Docker y proteger las credenciales del proxy para que no queden expuestas.

Proxy de socket Docker

Exponer directamente el socket de Docker supone un riesgo enorme para la seguridad.

El socket Docker (/var/run/docker.sock) proporciona acceso de nivel raíz a todo el sistema host. Cualquier proceso que pueda escribir en este socket puede generar contenedores con acceso al sistema de archivos del host, escalar privilegios o romper por completo el aislamiento del contenedor.

El montaje directo en el enchufe es peligroso:

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

Este patrón aparece en configuraciones Docker-in-Docker y canalizaciones CI/CD, pero es una pesadilla para la seguridad. Un contenedor comprometido puede controlar todo el demonio Docker.

Los servicios de proxy de socket crean una capa intermediaria más segura. Filtran las llamadas a la API de Docker y restringen lo que los contenedores pueden hacer realmente.

Utiliza el docker-socket-proxy de Tecnativa:

# 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"

El proxy solo expone puntos finales específicos de la API de Docker. Establece las variables de entorno en 1 para las operaciones permitidas y en 0 para las bloqueadas.

Tus aplicaciones se conectan al proxy en lugar de al socket sin procesar:

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

A continuación, se incluyen algunas estrategias adicionales para reforzar los sockets:

• Ejecuta el proxy de socket en un segmento de red independiente.
• Usar autenticación TLS entre los clientes y el proxy
• Supervisa los registros del proxy del socket en busca de llamadas API sospechosas.
• Rota las credenciales de acceso al proxy con regularidad.

Gestión de credenciales

Las credenciales de proxy en URL de texto sin formato aparecen en todas partes: registros, listas de procesos, volcados de entorno.

Nunca incluyas credenciales en las URL proxy:

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

Cualquier persona con acceso a ps aux o a volcados de variables de entorno puede ver tu contraseña de proxy. Esto incluye registros de aplicaciones, inspección de contenedores y herramientas de supervisión del sistema.

En su lugar, utiliza archivos de autenticación:

# 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

Configura tu servidor proxy para leer las credenciales del archivo o utiliza sistemas de autenticación externos.

Los proxies TLS cifran todo el tráfico proxy, incluidos los intercambios de autenticación:

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

Configura tu servidor proxy con los certificados TLS adecuados, ya sean de una CA o certificados autofirmados distribuidos a los equipos cliente.

La autenticación basada en certificados elimina por completo las contraseñas:

# 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

El proxy valida los certificados de cliente en lugar de las combinaciones de nombre de usuario y contraseña. Los certificados pueden revocarse individualmente si se ven comprometidos.

La gestión de secretos de Kubernetes mantiene las credenciales proxy fuera de las imágenes de contenedores:

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

Los secretos permanecen cifrados en reposo y se insertan en tiempo de ejecución sin aparecer en las capas de la imagen.

Bloquea el acceso a los enchufes y cifra tus credenciales: tu yo futuro te lo agradecerá.

¿Estás buscando alternativas a Docker para configurar tu proxy? Compara Docker y Podman para elegir la herramienta de contenedorización adecuada.

Solución de problemas comunes

Los problemas de proxy se manifiestan como tiempos de espera agotados, fallos de conexión y errores de compilación misteriosos que funcionan correctamente fuera de tu red. A continuación, se presenta un enfoque sistemático para diagnosticar y solucionar los problemas más comunes del proxy de Docker.

Enfoque diagnóstico estructurado

Empieza por lo básico y ve avanzando poco a poco.

Paso 1: Verifica la conectividad del proxy desde el host.

Comprueba si puedes acceder a tu servidor proxy:

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

Si esto falla, la configuración del proxy o el enrutamiento de la red tienen problemas. Ponte en contacto con tu equipo de red antes de solucionar los problemas de Docker.

Paso 2: Comprueba la configuración del proxy del demonio Docker.

Verifica que el demonio lee tu configuración de proxy:

docker info | grep -i proxy

Deberías ver tus URL proxy en la lista. Si faltan, comprueba /etc/docker/daemon.json y reinicia el servicio Docker.

Paso 3: Prueba las operaciones del cliente Docker

Intenta descargar una imagen sencilla:

docker pull hello-world

El éxito significa que la configuración del proxy de tu cliente funciona. El fallo apunta a problemas de proxy a nivel de demonio.

Paso 4: Comprueba la conectividad a nivel de contenedor.

Ejecuta un contenedor y prueba las conexiones salientes:

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())"

Esto aísla si el problema está en las operaciones de Docker o en la red de contenedores.

Problemas comunes y soluciones

Problema: El tiempo de espera de « docker pull » ha expirado.

Verás este error cuando Docker no pueda acceder a registros externos:

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

Comienza por comprobar la conectividad básica para aislar dónde se produce el problema:

# 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

Soluciona este problema resolviendo los problemas de configuración del DNS y del proxy:

• Añadir servidores DNS a /etc/docker/daemon.json

• Configurar NO_PROXY para servidores DNS internos

• Comprueba si el proxy admite el método HTTPS CONNECT.

Problema: La instalación del paquete falla durante la compilación.

Los gestores de paquetes dentro de los contenedores no pueden acceder a los repositorios y muestran errores como este:

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

Prueba la conectividad del gestor de paquetes directamente en un contenedor temporal:

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

La salida detallada muestra exactamente dónde falla la conexión.

Soluciona esto configurando los gestores de paquetes para que utilicen tu proxy:

• Configura los ajustes del proxy del gestor de paquetes en Dockerfile.
• Pasar argumentos de compilación proxy a la compilación de Docker
• Comprueba si el proxy bloquea los dominios del repositorio de paquetes.

Problema: BuildKit ignora la configuración del proxy.

BuildKit utiliza un manejo de proxies diferente al del generador heredado, lo que provoca errores como este:

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

Comprueba si el problema es específico de BuildKit verificando la configuración de tu generador:

# Check BuildKit configuration
docker buildx inspect

# Build with legacy builder
DOCKER_BUILDKIT=0 docker build .

Si el generador heredado funciona, tienes un problema de configuración del proxy BuildKit.

Soluciona los problemas de proxy de BuildKit con estos métodos:

• Configura los ajustes de proxy específicos de BuildKit en buildkitd.toml
• Utiliza --build-arg para pasar variables proxy de forma explícita.
• Desactivar BuildKit para compilaciones sensibles al proxy

Problema: El contenedor no puede acceder a servicios externos.

Tu aplicación dentro del contenedor no se conecta a las API externas:

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

Depura esto probando la conectividad desde dentro del contenedor:

# 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

Esto muestra si las variables proxy están presentes y si el intento de conexión se realiza correctamente.

Resuelve los problemas de conectividad del contenedor asegurándote de que la configuración del proxy sea correcta:

• Pasar variables de entorno proxy en tiempo de ejecución
• Configurar los ajustes de proxy específicos de la aplicación
• Añadir destino a la lista NO_PROXY

Análisis de registros y pruebas de conectividad

Los registros del demonio Docker revelan toda la historia de las negociaciones y los fallos del proxy.

En sistemas basados en systemd, utiliza journalctl para seguir los registros del servicio Docker en tiempo real:

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

Para sistemas que utilizan archivos de registro tradicionales, comprueba directamente el registro de Docker:

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

Busca patrones específicos relacionados con el proxy en los registros. Los errores de conexión rechazada indican que no se puede acceder al servidor proxy. Los errores de autenticación aparecen como mensajes «407 Proxy Authentication Required» (Se requiere autenticación de proxy). Los errores de tiempo de espera sugieren problemas de enrutamiento de red o sobrecarga del servidor proxy.

Las pruebas a nivel de contenedor con curl y wget te proporcionan información detallada sobre el comportamiento del proxy.

Prueba las conexiones HTTP a través de tu proxy para ver exactamente qué sucede durante el intercambio de datos:

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

La salida detallada muestra la resolución DNS, el establecimiento de la conexión proxy y el flujo real de la solicitud HTTP. Verás líneas como «Conectado a proxy.company.com» seguidas de «CONNECT httpbin.org:80» si el túnel proxy funciona correctamente.

Las conexiones HTTPS requieren que el proxy admita el método CONNECT:

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

Busca «CONNECT httpbin.org:443 HTTP/1.1» en la salida. Si ves «Método no permitido» o errores similares, tu proxy no admite túneles HTTPS.

Prueba la autenticación incrustando las credenciales en la URL del proxy:

# 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

Los errores de autenticación aparecen como respuestas «407 Proxy Authentication Required» (Se requiere autenticación de proxy). Si la autenticación se realiza correctamente, se procede directamente a la solicitud de destino.

La depuración a nivel de red con tcpdump captura los paquetes reales entre Docker y tu servidor proxy.

Ejecuta tcpdump para ver todo el tráfico que fluye hacia tu proxy:

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

Esta captura de paquetes sin procesar muestra los intentos de conexión, la transferencia de datos y la terminación de la conexión. Busca el establecimiento de una conexión TCP (paquetes SYN/ACK) seguido de tráfico HTTP. Los tiempos de espera de conexión aparecen como paquetes SYN repetidos sin respuesta.

Las pruebas de resolución DNS elimina una fuente habitual de confusión con los proxies.

Muchos problemas de proxy son en realidad problemas de DNS disfrazados. Prueba la resolución DNS dentro de los contenedores:

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

Si esto falla, el contenedor no puede resolver nombres de dominio en absoluto. Intenta utilizar un servidor DNS público para aislar el problema:

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

Los entornos corporativos suelen tener servidores DNS que solo funcionan desde dentro de la red. Es posible que tu proxy también deba gestionar solicitudes DNS, además del tráfico HTTP, o que debas configurar contenedores con servidores DNS específicos que funcionen a través de tu proxy.

Trabaja cada capa de forma sistemática y encontrarás la causa raíz.

¿Buscas opciones que puedan gestionar los proxies de otra manera? Tenemos una guía sobre alternativas a Docker para que puedas explorar el panorama completo actual de herramientas de contenedorización en 2025.

Conclusión

La configuración del proxy de Docker no solo consiste en descargar imágenes, sino también en crear aplicaciones contenedorizadas fiables y seguras en entornos empresariales.

Te he mostrado cómo configurar los ajustes de proxy en cuatro capas diferentes: operaciones del cliente, procesos daemon, tiempo de ejecución del contenedor y operaciones de tiempo de compilación. Cada capa tiene una finalidad específica y requiere su propio enfoque de configuración, desde archivos JSON y variables de entorno hasta ajustes del gestor de paquetes y configuraciones de BuildKit. Una estrategia de proxy por capas te protege de los puntos únicos de fallo.

¿Quieres profundizar en Docker, la contenedorización y la seguridad ? Echa un vistazo a nuestra lista de cursos seleccionados:

• Introducción a Docker
• Docker intermedio
• Conceptos de contenedorización y virtualización
• Contenedorización y virtualización con Docker y Kubernetes
• Conceptos de DevOps
• Introducción a Kubernetes