📌 host.docker.internal란 도대체 뭘까? (Docker 네트워크 개념과 함께)

Docker를 사용하다 보면 컨테이너에서 호스트(로컬 PC)로 접근해야 하는 경우가 있습니다.

예를 들어, 컨테이너 내부에서 호스트의 데이터베이스(MySQL, PostgreSQL)나 API 서버로 연결할 때,

일반적으로 localhost(127.0.0.1)를 사용하면 접근이 안 되는 경우가 많습니다.

바로 이럴 때 host.docker.internal 이 유용하게 사용됩니다!

하지만 이를 이해하려면 Docker 네트워크의 개념을 먼저 알아야 합니다.

---

1️⃣ Docker 네트워크 구조 개요

Docker 컨테이너의 네트워크는 가상 인터페이스(Virtual Ethernet, veth)와 브릿지(Bridge) 로 구성됩니다.

컨테이너와 host 간의 네트워크 연결을 이해하려면, Docker의 기본 네트워크 구조를 먼저 알아야 합니다.

이 이미지는 Docker 컨테이너가 Bridge 네트워크를 통해 통신하는 방식을 보여줍니다.

---

✅ 1. 기본적인 Docker 네트워크 흐름

Docker의 네트워크 구조는 Host와 컨테이너 간에 가상의 네트워크 인터페이스를 사용하여 통신하는 방식입니다.

📌 Docker 네트워크의 기본 개념

• 도커는 컨테이너에 내부 IP를 순차적으로 할당.
• 내부 IP는 컨테이너를 재시작할 때마다 변경될 수 있음.
• 각 컨테이너는 자체적인 네트워크 인터페이스(eth0)를 가짐.
• 이 eth0 인터페이스는 가상 네트워크 인터페이스(VETH, Virtual Ethernet) 를 통해 연결됨.
• 모든 컨테이너는 docker0 Bridge 네트워크를 통해 통신.
• 컨테이너끼리는 docker0를 통해 서로 통신 가능.
• docker0는 **Host의 실제 네트워크 인터페이스(eth0)와 연결됨.

---

✅ 2. Bridge 네트워크에서 localhost가 안 되는 이유

Docker 컨테이너 내부에서 localhost를 사용하면 "컨테이너 내부"만 참조하기 때문에,

Host 머신의 서비스를 사용하려면 host.docker.internal을 사용해야 합니다.

Bridge 네트워크에서 localhost 사용 시 문제점

❌ localhost:5432를 사용하면 컨테이너 내부의 포트 5432를 찾음 → 호스트의 DB에 연결할 수 없음.

✅ host.docker.internal:5432을 사용하면 컨테이너가 호스트 머신의 포트 5432로 접근 가능합니다.

---

2️⃣ host.docker.internal이란?

host.docker.internal은 Docker 컨테이너에서 호스트(로컬 머신)로 접근할 수 있도록 제공되는 특수한 호스트명입니다.

• 일반적으로 Docker 컨테이너는 독립된 네트워크 환경을 가지므로, 컨테이너 내부에서 호스트의 네트워크 자원(예: 데이터베이스, API 서버 등)에 접근하려면 특정한 방법이 필요합니다.

• localhost를 사용하면 컨테이너 내부의 루프백 주소(127.0.0.1)를 가리키므로, 호스트의 서비스를 직접 호출할 수 없습니다.

• 따라서 Docker는 컨테이너 내부에서 호스트를 가리킬 수 있는 DNS 이름으로 host.docker.internal을 제공합니다.

✅ 즉, 컨테이너 내부에서 host.docker.internal을 사용하면 로컬 머신(호스트)로 연결할 수 있습니다

---

3️⃣ host.docker.internal 사용 예제

✅ 1. 컨테이너에서 로컬 DB(PostgreSQL)에 접속

sh
docker run -e DB_HOST=host.docker.internal -e DB_PORT=5432 my-app

📌 설명:

• DB_HOST=host.docker.internal → 컨테이너에서 로컬 머신의 PostgreSQL에 접속 가능!
• DB_PORT=5432 → 로컬에서 실행 중인 DB 포트 사용

✅ 이제 컨테이너에서 host.docker.internal:5432로 PostgreSQL에 연결할 수 있음.

---

✅ 2. Docker Compose에서 사용하기

version: '3.8'
services:
  my-app:
    image: my-app
    environment:
      - DB_HOST=host.docker.internal
      - DB_PORT=5432

📌 설명:

• DB_HOST를 host.docker.internal로 설정하여 컨테이너가 호스트 머신의 DB에 접근할 수 있도록 함.

  Docker Compose에서 host.docker.internal을 설정하는 방법

이 이미지는 Docker Compose를 활용해 환경 변수를 설정하는 방법을 보여줍니다.

---

4️⃣ Linux에서 host.docker.internal 사용하기

Linux에서는 host.docker.internal이 기본적으로 지원되지 않으므로, 별도로 설정이 필요합니다.

✅ 방법 : -add-host 옵션 사용

docker run --add-host=host.docker.internal:host-gateway -e DB_HOST=host.docker.internal my-app

📌 설명:

• -add-host=host.docker.internal:host-gateway → 컨테이너가 호스트를 인식하도록 설정
• 이후 컨테이너 내부에서 host.docker.internal 사용 가능!

---

5️⃣ 결론

🔹 host.docker.internal은 Docker 컨테이너에서 호스트(로컬 머신)로 접근할 때 사용하는 특수한 호스트명입니다.

🔹 Windows/Mac에서는 기본적으로 지원되며, Linux에서는 수동 설정 필요

🔹 로컬 DB(PostgreSQL, MySQL)나 API 서버에 컨테이너에서 접근할 때 유용

🔹 운영 환경에서는 사용을 피하고, 고정된 네트워크 설정을 권장