[Docker] 컨테이너에서 호스트 PC 서비스 접근하기: host.docker.internal

Docker 컨테이너에서 호스트 PC 서비스 접근하기: host.docker.internal의 필요성

문제 상황

Docker 컨테이너 내부에서 실행 중인 애플리케이션이 호스트 PC에서 실행 중인 다른 서비스에 접근해야 하는 경우가 있습니다.구체적인 예시:

• Docker 컨테이너에서 실행 중인 management_app 

• 호스트 PC에서 실행 중인 Ollama 서비스 (http://localhost:11434)

• 컨테이너 내부에서 Ollama API를 호출해야 하는 상황

왜 localhost가 작동하지 않는가?

# ❌ 이렇게 하면 작동하지 않음
http://localhost:11434/v1/chat/completions

 

이유:

1. 네트워크 격리: Docker 컨테이너는 자체 네트워크 네임스페이스를 가짐

1. localhost의 의미: 컨테이너 내부에서 localhost는 컨테이너 자신을 의미

1. 포트 매핑의 한계: ports: "8001:8001"은 호스트 → 컨테이너 방향의 매핑

해결 방법: host.docker.internal

# ✅ 올바른 접근 방법
http://host.docker.internal:11434/v1/chat/completions

 

host.docker.internal의 역할:

• Docker가 제공하는 특별한 DNS 이름

• 컨테이너에서 호스트 PC의 IP 주소를 자동으로 해석

• 호스트 PC의 모든 서비스에 접근 가능

네트워크 구조 비교

 

 

호스트 PC (172.17.0.1)

├── Ollama 서비스 (포트 11434)

└── Docker Engine

    └── Bridge 네트워크 (172.17.0.0/16)

        └── management_app 컨테이너 (172.17.0.2)

 

 

실제 사용 예시

docker-compose-debug-mode.yml 설정:

 

 

 

 

management_app:

  container_name: management_app

  ports:

    - "9090:9090"  # 호스트:컨테이너 포트 매핑

  # host.docker.internal을 통해 호스트 서비스 접근

 

 

컨테이너 내부 코드:

 

 

# 호스트 PC의 Ollama 서비스에 접근

ollama_url = "http://host.docker.internal:11434/v1/chat/completions"

response = requests.post(ollama_url, json=payload)

 

 

대안 방법들

1. 호스트 IP 직접 사용 (.py)
    

    

    

    

      http://172.17.0.1:11434/v1/chat/completions

    

    
2. 호스트 네트워크 모드 (.yaml)
    

    

    

    

      network_mode: host  # 컨테이너가 호스트 네트워크를 직접 사용

    

    
3. extra_hosts 설정 (.yaml)
    

    

    

    

      extra_hosts:

        - "host.docker.internal:host-gateway"

    

    

언제 host.docker.internal이 필요한가?

✅ 필요한 경우:

• 컨테이너에서 호스트 PC의 개발 도구 접근 (Ollama, 데이터베이스 등)

• 로컬 개발 환경에서의 서비스 간 통신

• 디버깅 및 테스트 목적

❌ 불필요한 경우:

• 모든 서비스가 Docker 컨테이너로 실행되는 경우

• 프로덕션 환경

• 컨테이너 간 통신

결론

host.docker.internal은 Docker의 네트워크 격리 특성 때문에 발생하는 문제를 해결하는 핵심 도구입니다. 특히 로컬 개발 환경에서 컨테이너와 호스트 PC 간의 서비스 통신이 필요할 때 필수적이며, 이를 통해 Docker의 장점(격리성)을 유지하면서도 호스트 리소스에 접근할 수 있습니다.