HOWTO · Docker

Cómo configurar host.docker.internal en Linux

Configura host.docker.internal en Linux con la asignación host-gateway de Docker y luego verifica y soluciona el acceso de un contenedor a un servicio del host.

En esta página

Para conectar desde un contenedor Linux con un servicio del host de Docker, crea el contenedor con --add-host=host.docker.internal:host-gateway en una instalación de Docker Engine compatible con el valor host-gateway. Después, envía la solicitud a host.docker.internal y al puerto en el que escucha el servicio. Este tráfico va del contenedor al host; acceder a un contenedor desde el host es una tarea distinta, que suele resolverse publicando un puerto, por ejemplo, con -p 8080:80.

Qué significa host.docker.internal en Linux

host.docker.internal es un nombre de host que un contenedor puede usar para dirigirse al host. No es un comando de shell y, en Docker Engine para Linux, puede ser necesario asignarle una dirección al crear el contenedor. El valor especial host-gateway permite que Docker proporcione la dirección de la puerta de enlace correspondiente a esa configuración de Engine, sin que tengas que adivinar la IP del puente. La compatibilidad con este valor depende de la instalación de Docker Engine; si Docker lo rechaza, consulta la documentación del Engine instalado o usa la dirección del host configurada para tu red.

La asignación solo afecta al contenedor que la recibe. No inicia un servicio en el host, no publica un puerto del contenedor ni permite acceder desde el host a un servicio que solo escucha dentro de otro contenedor.

Añadir host.docker.internal a un contenedor Linux

Añade la asignación al comando docker run al crear el contenedor:

docker run --rm -it --add-host=host.docker.internal:host-gateway IMAGE COMMAND

Sustituye IMAGE y COMMAND por la imagen y el proceso que necesites. Para una aplicación de larga duración, añade la misma opción --add-host a la configuración del servicio y vuelve a crear el contenedor; no se puede añadir una asignación a un contenedor que ya está en ejecución. También puedes usar esta opción con una red definida por el usuario, pero no necesitas una red personalizada solo para usar este nombre de host.

Verificar la conectividad con el host desde el contenedor

Inicia en el host un servicio que acepte conexiones en una dirección accesible desde el contenedor. Para hacer una prueba HTTP temporal, ejecuta python3 -m http.server 8000 --bind 0.0.0.0 en el host. Al enlazarse a 0.0.0.0, este servidor de prueba escucha en las interfaces de red del host; úsalo solo si el cortafuegos del host y la exposición de la red son adecuados. Mantén el servidor en ejecución mientras haces la prueba.

Crea un contenedor de prueba con la asignación y solicita el mismo puerto. Por ejemplo, si Docker puede descargar la imagen curlimages/curl, ejecuta docker run --rm --add-host=host.docker.internal:host-gateway curlimages/curl:latest http://host.docker.internal:8000/. Esta imagen incluye curl; si usas otra, comprueba que tenga instalado un cliente HTTP adecuado. Una respuesta del servidor, como un listado de directorios HTTP, confirma que la resolución del nombre, el enrutamiento y el puerto del servicio funcionan en conjunto. Esta comprobación depende de tu Docker Engine y tu red locales, por lo que el ejecutor de código aislado de este artículo no la ejecuta.

Solucionar problemas de conexión

  • Si no se resuelve el nombre, confirma que el contenedor se creó con la asignación --add-host=host.docker.internal:host-gateway y que Docker Engine admite host-gateway. Si cambias la configuración, vuelve a crear el contenedor.
  • Si el nombre se resuelve, pero la solicitud agota el tiempo de espera o se rechaza, confirma que el servicio del host esté en ejecución y escuche en el puerto esperado. Un servicio enlazado solo a 127.0.0.1 puede aceptar solicitudes locales del host y rechazar las que llegan desde la red del contenedor; configúralo para que escuche en una dirección accesible y limita el acceso con el cortafuegos del host.
  • Comprueba que la URL use el puerto real del servicio. El puerto de la solicitud desde el contenedor es el puerto del servicio en el host; la opción -p de Docker sirve para publicar un puerto del contenedor y no hace falta para este sentido del tráfico.
  • Si la asignación está presente y el servicio es accesible desde el host, pero no desde el contenedor, revisa las reglas del cortafuegos del host y la configuración de red de Docker Engine. No des por hecho que 172.17.0.1 sea una dirección universal ni la trates como localhost; las direcciones del puente varían según la configuración.

Preguntas frecuentes

¿Para qué sirve host.docker.internal? Proporciona al contenedor un nombre de host para conectarse a un servicio del host, siempre que ese nombre esté asignado para el contenedor.

¿La configuración en Linux es distinta de la de Docker Desktop? Sí. Este artículo trata sobre Docker Engine en Linux, donde puedes añadir la asignación host-gateway al crear el contenedor. Docker Desktop ofrece su propio comportamiento de red para el host; consulta la documentación correspondiente a la plataforma y al Engine que estés usando.

¿Necesito una red de Docker personalizada? No. En un Engine compatible, la asignación --add-host basta para este nombre de host. Una red personalizada puede ser útil para otras necesidades de aislamiento o descubrimiento de servicios.

¿Cómo puedo probar la conexión? Inicia un servicio en el host en una interfaz y un puerto accesibles y, desde un contenedor creado con la asignación, solicita http://host.docker.internal:PORT/. Comprueba que la imagen del contenedor incluya un cliente HTTP, como curl, y que el cortafuegos del host permita el tráfico.