DevOps 지식 허브
DevOps 지식 허브

Docker 네트워킹 문제 해결: 연결 문제를 효과적으로 해결하기

이 종합적인 문제 해결 가이드를 통해 일반적인 Docker 네트워킹 난관을 헤쳐나가세요. '네트워크를 찾을 수 없음' 오류, 컨테이너 간 통신 실패, 외부 액세스 문제를 진단하고 해결하는 방법을 배우십시오. 이 문서는 Docker 기반 애플리케이션의 원활한 연결을 보장하기 위한 실용적인 디버깅 팁, 명령어 예시 및 모범 사례를 제공합니다.

30 조회수

Docker 네트워킹 문제 해결: 연결 문제 효과적으로 해결하기

Docker 네트워킹은 컨테이너 간 및 외부와의 통신을 가능하게 하는 강력하고 유연한 시스템입니다. 하지만 복잡한 시스템은 때때로 연결 문제를 일으킬 수 있습니다. "네트워크를 찾을 수 없음" 오류가 발생하거나, 컨테이너 간 통신에 어려움을 겪거나, 호스트 또는 외부 네트워크에서 컨테이너에 액세스할 수 없는 경우, 이러한 문제는 개발 및 배포를 중단시킬 수 있습니다. 이 글에서는 일반적인 Docker 네트워킹 문제와 이를 진단하고 해결하기 위한 실용적이고 실행 가능한 단계를 안내하여 애플리케이션이 원활하게 실행되도록 보장합니다.

효과적인 문제 해결을 위해서는 Docker가 네트워킹을 처리하는 방식을 이해하는 것이 중요합니다. 기본적으로 Docker는 동일한 호스트의 컨테이너 간 통신을 허용하는 브리지 네트워크를 생성합니다. 그러나 사용자 정의 네트워크는 더 나은 제어 및 격리를 제공합니다. 문제가 발생하면 종종 잘못된 구성, 잘못된 네트워크 설정 또는 컨테이너, 호스트 및 외부 리소스 간의 트래픽 흐름 방식에 대한 오해 때문입니다.

일반적인 Docker 네트워킹 문제 및 해결 방법

이 섹션에서는 사용자가 Docker에서 가장 자주 겪는 네트워킹 문제와 단계별 해결 방법을 다룹니다.

1. "네트워크를 찾을 수 없음" 오류

이 오류는 일반적으로 존재하지 않거나 철자가 틀린 네트워크에 컨테이너를 연결하려고 할 때 발생합니다. Docker Swarm 또는 Kubernetes를 사용하는 경우 네트워크를 예상 범위에서 사용할 수 없을 때도 발생할 수 있습니다.

문제 진단

  • 사용 가능한 네트워크 나열: 첫 번째 단계는 사용하려는 네트워크가 실제로 존재하는지 확인하는 것입니다. 다음 명령을 사용하십시오:

    bash docker network ls

    그러면 Docker 호스트의 모든 네트워크 목록이 표시됩니다. 사용하려던 네트워크 이름을 찾으십시오.

  • 오타 확인: 명령의 네트워크 이름(예: docker run --network <network-name> ...)이 올바르게 철자되었고 docker network ls의 출력과 일치하는지 확인하십시오.

해결 방법

  • 네트워크 생성: 네트워크가 존재하지 않으면 생성해야 합니다. 간단한 브리지 네트워크의 경우 다음을 사용하십시오:

    bash docker network create <network-name>
    예시:

    bash docker network create my-app-network

  • 올바른 네트워크 이름 사용: 네트워크가 존재하지만 잘못된 이름을 사용하고 있다면 명령에서 수정하십시오.

  • 범위 확인 (Swarm/Kubernetes): 분산 환경에서는 네트워크가 올바른 범위(예: Swarm의 경우 overlay)에서 생성되었는지 확인하십시오. 다른 노드에만 존재하는 네트워크에 컨테이너를 연결하려고 하면 적절하게 생성해야 합니다.

2. 컨테이너 간 통신 실패

동일한 사용자 정의 브리지 네트워크의 컨테이너는 컨테이너 이름을 호스트 이름으로 사용하여 통신할 수 있어야 합니다. 이것이 작동하지 않는다면 여러 요인이 작용할 수 있습니다.

문제 진단

  • 네트워크 연결 확인: 두 컨테이너가 동일한 사용자 정의 네트워크에 연결되어 있는지 확인하십시오.

    bash docker network inspect <network-name>

    네트워크에 연결된 컨테이너를 보려면 출력의 Containers 섹션을 확인하십시오.

  • 컨테이너 로그 확인: 포트 또는 네트워크 서비스 바인딩과 관련된 오류가 있는지 소스 및 대상 컨테이너의 로그를 검사하십시오.

    bash docker logs <container-name-or-id>

  • 기본 연결 테스트: 컨테이너 이름 또는 IP 주소를 사용하여 한 컨테이너에서 다른 컨테이너로 ping 또는 curl을 사용하십시오.

    • 컨테이너 IP 찾기: docker network inspect를 사용하여 특정 네트워크의 컨테이너 IP 주소를 찾을 수 있습니다.

      bash docker network inspect my-app-network

      대상 컨테이너의 Containers 섹션 아래에 있는 IPv4Address를 찾으십시오.

    • 컨테이너 내에서 명령 실행:

      bash docker exec -it <source-container-name> ping <destination-container-name>
      또는
      bash docker exec -it <source-container-name> curl http://<destination-container-name>:<port>

  • 기본 브리지 네트워크 제한: 기본 bridge 네트워크의 컨테이너는 IP 주소만을 사용하여 통신할 수 있습니다. 이 네트워크에서는 기본적으로 컨테이너 이름의 DNS 확인이 활성화되어 있지 않습니다. 더 나은 격리 및 DNS를 위해 항상 사용자 정의 네트워크를 선호하십시오.

해결 방법

  • 사용자 정의 네트워크 사용: 통신하려는 컨테이너가 동일한 사용자 정의 네트워크(예: bridge, overlay)에 연결되어 있는지 확인하십시오.

    bash docker run --name container1 --network my-app-network ... docker run --name container2 --network my-app-network ...

  • 애플리케이션이 올바르게 수신 대기하는지 확인: 컨테이너 내부의 애플리케이션이 올바른 네트워크 인터페이스(일반적으로 0.0.0.0) 및 포트에서 수신 대기하도록 구성되어 있는지 확인하십시오.

  • 방화벽 규칙: Docker 내부 네트워킹에서는 드물지만, 고급 구성을 수행한 경우 호스트 수준 방화벽이 컨테이너 간 트래픽을 차단하고 있지 않은지 확인하십시오.

3. 외부 액세스 문제 (호스트/인터넷 연결)

컨테이너가 인터넷에 연결할 수 없거나 컨테이너 내부에서 실행되는 서비스가 호스트 머신 또는 외부 네트워크에서 액세스할 수 없는 문제를 포괄하는 광범위한 범주입니다.

문제 진단

  • 컨테이너에서 인터넷으로:

    • 기본 게이트웨이/DNS 확인: 컨테이너에 DNS 및 기본 게이트웨이에 액세스할 수 있는지 확인하십시오. 일반적으로 Docker의 기본 브리지 네트워크에서 처리됩니다.

    • 아웃바운드 연결 테스트: 컨테이너 내부에서 외부 IP 주소로 ping하거나 도메인 이름을 확인하십시오.

      bash docker exec -it <container-name> ping 8.8.8.8 docker exec -it <container-name> ping google.com

  • 호스트에서 컨테이너로:

    • 포트 매핑: 컨테이너를 실행할 때 포트를 올바르게 매핑했는지 확인하십시오. 구문은 -p <host-port>:<container-port>입니다.

      bash docker run -d -p 8080:80 --name my-web-server nginx

      이 명령은 컨테이너 내부의 포트 80을 호스트 머신의 포트 8080에 매핑합니다.

    • 수신 대기 서비스 확인: 컨테이너 내부의 애플리케이션이 실제로 노출된 포트 및 올바른 인터페이스(예: 0.0.0.0 또는 *:port)에서 수신 대기 중인지 확인하십시오.

    • 호스트 방화벽: 호스트 머신의 방화벽이 매핑된 포트로의 트래픽을 차단하고 있을 수 있습니다. iptables, ufw 또는 Windows 방화벽 설정을 확인하십시오.

    • Docker 네트워크 및 IP 주소: 브리지 네트워크의 컨테이너는 자체 IP 주소를 가지고 있음을 이해하십시오. 포트 매핑 없이 호스트에서 직접 액세스하려면 매핑된 포트를 통해 액세스합니다. 포트 매핑 없이 호스트에서 컨테이너 IP에 직접 액세스해야 하는 경우 컨테이너를 호스트 네트워크(--network host)에 배치해야 할 수 있지만, 이는 격리를 줄입니다.

해결 방법

  • 컨테이너에서 인터넷으로:

    • 작동하는 네트워크 보장: 사용자 정의 네트워크를 사용하는 경우 인터넷 액세스를 제공하도록 구성되었는지 확인하십시오 (일반적으로 호스트의 네트워크 설정을 상속하여).
    • Docker 데몬 구성 확인: 때로는 Docker 데몬의 네트워크 구성(예: daemon.json)의 문제가 아웃바운드 연결에 영향을 미칠 수 있습니다.
    • 프록시 설정: 호스트 네트워크에서 프록시가 필요한 경우 Docker가 프록시를 사용하도록 구성되었는지 확인하십시오.

  • 호스트에서 컨테이너로:

    • 올바른 포트 매핑: docker run -p 플래그를 다시 확인하십시오.

    • localhost 또는 호스트 IP를 통해 액세스: localhost:<host-port> 또는 <your-host-ip>:<host-port>를 사용하여 호스트 머신에서 서비스에 액세스하십시오.

      위의 nginx 예시의 경우 브라우저에서 http://localhost:8080으로 이동합니다.

    • 내부 수신 대기 확인: docker exec -it <container-name> netstat -tulnp 또는 유사한 명령을 사용하여 컨테이너 내부에서 애플리케이션이 예상 포트에서 수신 대기 중인지 확인하십시오.

    • 충돌하는 호스트 포트 해제: 호스트의 다른 애플리케이션이 매핑하려는 <host-port>를 이미 사용하고 있지 않은지 확인하십시오.

고급 디버깅 기술

기본 단계로 문제가 해결되지 않으면 이러한 고급 기술을 고려하십시오.

1. docker network inspect 광범위하게 사용

이 명령은 네트워크 구성, 서브넷, 게이트웨이 및 IP 주소가 있는 연결된 컨테이너를 포함한 네트워크에 대한 자세한 정보를 제공합니다. 네트워크 토폴로지를 이해하기 위해 자유롭게 사용하십시오.

docker network inspect bridge
docker network inspect host
docker network inspect my-custom-network

2. 컨테이너 네트워크 인터페이스 검사

컨테이너에 연결하여 네트워크 인터페이스를 검사하여 구성 방법을 확인하십시오.

# 실행 중인 컨테이너 안으로 쉘 가져오기
docker exec -it <container-name> /bin/bash

# 컨테이너 안에서:
# 네트워크 인터페이스 나열
ifconfig -a
# 또는 ip addr

# 라우팅 테이블 확인
route -n
# 또는 ip route

# DNS 확인 구성 확인
cat /etc/resolv.conf

3. tcpdump를 패킷 분석에 활용

심층 분석을 위해 컨테이너 내부(먼저 설치해야 할 수 있습니다: apt update && apt install -y tcpdump 또는 apk add tcpdump) 또는 Docker 호스트에서 tcpdump를 실행하여 네트워크 트래픽을 캡처하고 패킷이 삭제되거나 잘못 라우팅되는 위치를 분석할 수 있습니다.

  • 호스트에서 트래픽 캡처 (루트/sudo 필요):

    bash sudo tcpdump -i <interface> -nn -s0 port <port_number>
    <interface>를 호스트의 네트워크 인터페이스(예: eth0, docker0)로, <port_number>를 조사 중인 포트로 바꾸십시오.

4. Docker의 내장 ping 및 traceroute

많은 공식 Docker 이미지에는 ping 및 traceroute가 포함되어 있습니다. 포함되어 있지 않은 경우 설치하거나 nicolaka/netshoot와 같이 네트워크 디버깅을 위해 특별히 설계된 이미지를 사용할 수 있습니다.

  • nicolaka/netshoot 사용:

    bash docker run --rm -it nicolaka/netshoot

    내부에 들어가면 ping, traceroute, dig, curl, tcpdump와 같은 도구를 사용하여 다양한 대상으로 연결을 테스트할 수 있습니다.

Docker 네트워킹 모범 사례

  • 사용자 정의 네트워크 사용: 기본 bridge 네트워크보다 사용자 정의 브리지 네트워크를 생성하고 사용하는 것을 항상 선호하십시오. 더 나은 격리, 컨테이너 이름으로 DNS 확인, 쉬운 관리를 제공합니다.
  • 네트워크 모드 이해: 다양한 네트워크 모드(bridge, host, none, overlay)를 인지하고 애플리케이션의 요구 사항 및 보안 요구 사항에 가장 적합한 것을 선택하십시오.
  • 포트 명시적으로 매핑: 컨테이너 서비스를 호스트 또는 외부 네트워크에 노출할 때 명시적인 포트 매핑(-p)을 사용하십시오.
  • 네트워크 설정 문서화: 특히 복잡한 다중 컨테이너 애플리케이션의 경우 사용자 정의 네트워크 구성을 추적하십시오.
  • 간단하게 시작: 문제 해결 시 가장 간단한 네트워크 구성을 시작으로 점차 복잡성을 더하십시오.

결론

Docker 네트워킹 문제 해결은 어렵게 보일 수 있지만, 문제를 체계적으로 접근하고 사용 가능한 도구를 활용하면 대부분의 연결 문제를 효과적으로 해결할 수 있습니다. 네트워크 개념 이해, docker network ls 및 docker network inspect와 같은 명령 활용, 컨테이너 구성 확인이 중요합니다. 이 가이드에 설명된 진단 단계와 모범 사례를 따르면 Docker화된 애플리케이션이 내부적으로나 외부적으로 원활하게 통신하도록 보장할 수 있습니다.