HOWTO · Docker

Linux에서 host.docker.internal을 구성하는 방법

Docker의 host-gateway 매핑으로 Linux에서 host.docker.internal을 구성한 뒤, 컨테이너가 호스트 서비스에 접근하는지 확인하고 문제를 해결하는 방법을 알아봅니다.

이 페이지의 내용

Linux 컨테이너에서 Docker 호스트의 서비스에 연결하려면 host-gateway 값을 지원하는 Docker Engine 환경에서 --add-host=host.docker.internal:host-gateway 옵션을 지정해 컨테이너를 만드세요. 그런 다음 host.docker.internal과 해당 서비스가 수신 대기 중인 포트로 요청을 보내면 됩니다. 이는 컨테이너에서 호스트로 향하는 트래픽입니다. 호스트에서 컨테이너에 접근하는 것은 별개의 작업이며, 일반적으로 -p 8080:80처럼 포트를 게시해 처리합니다.

Linux에서 host.docker.internal이 의미하는 것

host.docker.internal은 컨테이너가 호스트를 가리킬 때 사용할 수 있는 호스트 이름입니다. 셸 명령이 아니며, Linux Docker Engine에서는 컨테이너를 만들 때 이 이름을 매핑해야 할 수 있습니다. 특수 값인 host-gateway를 사용하면 브리지 IP를 추측할 필요 없이 Docker가 해당 Engine 구성에 맞는 게이트웨이 주소를 제공합니다. 이 값의 지원 여부는 Docker Engine 구성에 따라 달라집니다. Docker가 이 값을 거부하면 설치된 Engine 문서를 확인하거나 네트워크에 설정된 호스트 주소를 사용하세요.

이 매핑은 해당 설정을 받은 컨테이너에만 적용됩니다. 호스트에서 서비스를 시작하거나 컨테이너 포트를 게시하지 않으며, 다른 컨테이너 내부에서만 수신 대기 중인 서비스를 호스트에서 사용할 수 있게 해 주지도 않습니다.

Linux 컨테이너에 host.docker.internal 추가하기

컨테이너를 만들 때 docker run 명령에 매핑을 추가하세요.

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

IMAGE와 COMMAND를 필요한 이미지와 프로세스로 바꾸세요. 장시간 실행되는 애플리케이션이라면 서비스 구성에 같은 --add-host 옵션을 추가하고 컨테이너를 다시 만드세요. 이미 실행 중인 컨테이너에는 매핑을 추가할 수 없습니다. 사용자 정의 네트워크에서도 이 옵션을 사용할 수 있지만, 이 호스트 이름을 쓰기 위해 사용자 정의 네트워크가 필요한 것은 아닙니다.

컨테이너에서 호스트 연결 확인하기

컨테이너에서 접근할 수 있는 주소에서 연결을 받도록 호스트에서 서비스를 시작하세요. 임시 HTTP 확인을 하려면 호스트에서 python3 -m http.server 8000 --bind 0.0.0.0을 실행합니다. 0.0.0.0에 바인딩하면 이 테스트 서버가 호스트의 네트워크 인터페이스에서 요청을 받습니다. 호스트 방화벽과 네트워크 노출이 적절한 환경에서만 사용하고, 테스트하는 동안 서버를 계속 실행해 두세요.

매핑을 지정해 테스트 컨테이너를 만들고 같은 포트로 요청을 보내세요. 예를 들어 Docker가 curlimages/curl 이미지를 가져올 수 있다면 docker run --rm --add-host=host.docker.internal:host-gateway curlimages/curl:latest http://host.docker.internal:8000/을 실행합니다. 이 이미지에는 curl이 포함되어 있습니다. 다른 이미지를 쓴다면 적절한 HTTP 클라이언트가 설치되어 있는지 확인하세요. HTTP 디렉터리 목록처럼 서버에서 응답이 오면 이름 확인, 라우팅, 서비스 포트가 함께 작동한다는 뜻입니다. 이 Docker 및 호스트 서비스 확인은 로컬 Docker Engine과 네트워크 구성에 따라 달라지므로, 이 문서의 격리된 코드 실행 환경에서는 실행하지 않았습니다.

연결 실패 문제 해결

  • 이름이 확인되지 않으면 컨테이너를 만들 때 --add-host=host.docker.internal:host-gateway 매핑을 지정했는지, Docker Engine이 host-gateway를 지원하는지 확인하세요. 구성을 변경한 뒤에는 컨테이너를 다시 만드세요.
  • 이름은 확인되지만 요청 시간이 초과되거나 거부되면 호스트 서비스가 실행 중인지, 예상한 포트에서 수신 대기 중인지 확인하세요. 127.0.0.1에만 바인딩된 서비스는 호스트 내부 요청은 받을 수 있어도 컨테이너 네트워크를 통해 들어오는 연결은 거부할 수 있습니다. 컨테이너에서 접근할 수 있는 주소에 바인딩하고 호스트 방화벽으로 접근을 제한하세요.
  • URL에 서비스의 실제 포트를 지정했는지 확인하세요. 컨테이너 요청에 적는 포트는 호스트 서비스 포트입니다. Docker의 -p 옵션은 컨테이너 포트를 게시하는 데 쓰며, 이 방향의 트래픽에는 필요하지 않습니다.
  • 매핑이 있고 호스트에서는 서비스에 접근할 수 있지만 컨테이너에서는 안 된다면 호스트 방화벽 규칙과 Docker Engine 네트워크 구성을 확인하세요. 172.17.0.1이 어디서나 통하는 주소라고 가정하거나 이를 localhost와 같은 주소로 취급하지 마세요. 브리지 주소는 구성에 따라 다릅니다.

자주 묻는 질문

host.docker.internal은 어떤 역할을 하나요? 해당 컨테이너에 이 호스트 이름이 매핑되어 있으면, 컨테이너가 호스트의 서비스에 연결할 때 사용할 이름을 제공합니다.

Linux 설정은 Docker Desktop과 다른가요? 네. 이 문서는 컨테이너를 만들 때 host-gateway 매핑을 추가할 수 있는 Linux Docker Engine을 다룹니다. Docker Desktop은 자체 호스트 네트워킹 동작을 제공하므로, 사용 중인 플랫폼과 Engine에 해당하는 문서를 확인하세요.

사용자 정의 Docker 네트워크가 필요한가요? 아니요. 지원되는 Engine에서는 --add-host 매핑만으로 이 호스트 이름을 사용할 수 있습니다. 격리나 서비스 검색 같은 다른 요구 사항이 있다면 사용자 정의 네트워크가 유용할 수 있습니다.

연결을 어떻게 테스트하나요? 컨테이너에서 접근할 수 있는 인터페이스와 포트에서 호스트 서비스를 실행한 다음, 매핑을 지정해 만든 컨테이너에서 http://host.docker.internal:PORT/로 요청하세요. 컨테이너 이미지에 curl 같은 HTTP 클라이언트가 있고 호스트 방화벽이 해당 트래픽을 허용하는지 확인하세요.