도커 네트워크 기초 정리｜컨테이너끼리 통신하는 법 3가지
브리지부터 커스텀 네트워크까지, 컨테이너 통신의 원리를 한 번에
- 도커 네트워크는 기본적으로 브리지·호스트·오버레이·none 네 가지 드라이버로 나뉩니다.
- 같은 커스텀 브리지 네트워크에 있으면 컨테이너끼리 이름(DNS)만으로 통신할 수 있습니다.
- 기본 브리지 네트워크는 이름 기반 DNS를 지원하지 않아 자주 오해가 생깁니다.
- docker network create/connect 명령어만 알면 대부분의 통신 문제를 해결할 수 있습니다.
- 통신 실패의 절반은 네트워크가 아니라 포트·컨테이너명 오타 문제입니다.
도커 네트워크 설정을 건드린 적도 없는데, 컨테이너 A에서 컨테이너 B로 요청이 안 갈 때가 있습니다.
로그를 봐도 에러는 “connection refused”뿐이라 뭐부터 봐야 할지 막막해집니다.
사실 이런 문제는 대부분 도커 네트워크의 동작 원리를 정확히 몰라서 생깁니다. 컨테이너는 기본적으로 서로 격리돼 있고, 같은 네트워크에 있어야만 이름으로 찾을 수 있기 때문입니다.
이 글에서는 브리지·호스트 네트워크의 차이부터 컨테이너끼리 실제로 통신하게 만드는 방법, 그리고 실무에서 자주 막히는 지점까지 순서대로 정리합니다.
도커 네트워크란? 컨테이너 통신의 기본 원리
도커 네트워크는 컨테이너들이 서로 통신할 수 있게 해주는 가상의 통신 레이어입니다. 리눅스 커널의 네임스페이스와 브리지 기능을 이용해 만들어집니다.
도커를 설치하면 자동으로 bridge, host, none 세 가지 기본 네트워크가 생깁니다. 특별히 지정하지 않으면 컨테이너는 기본 브리지 네트워크에 붙습니다.
여기서 중요한 원칙이 있습니다. 도커는 기본적으로 각 컨테이너를 격리된 존재로 취급합니다. 같은 네트워크에 속해 있어야만 서로를 인식하고 트래픽을 주고받을 수 있습니다.
도커 네트워크는 실제 물리 네트워크가 아니라 리눅스 브리지 인터페이스(예: docker0)로 구현됩니다. 컨테이너가 생성될 때마다 가상 이더넷 페어(veth pair)가 만들어져 브리지에 연결되는 방식입니다. 이 구조를 알면 “왜 컨테이너 IP가 재시작할 때마다 바뀌는지”도 자연스럽게 이해됩니다.
예를 들어 docker run -d --name web nginx로 컨테이너를 띄우면, 이 컨테이너는 172.17.0.x 대역의 IP를 자동으로 할당받습니다. 이 IP는 컨테이너를 재시작하면 바뀔 수 있어 직접 참조는 권장되지 않습니다.
실무에서 자주 하는 실수는 이 IP를 코드에 하드코딩하는 것입니다. 컨테이너가 재생성되면 IP가 바뀌어 연결이 끊기기 때문에, 이름 기반 통신을 쓰는 게 정석입니다.
도커 네트워크 종류 – 브리지, 호스트, 오버레이 차이
도커 네트워크는 용도에 따라 드라이버가 나뉩니다. 어떤 드라이버를 쓰느냐에 따라 컨테이너가 서로를 보는 방식이 완전히 달라집니다.
브리지는 가장 기본이 되는 드라이버입니다. 한 호스트 안에서 컨테이너 여러 개가 통신해야 할 때 씁니다. 기본 브리지와 사용자 정의 브리지는 동작이 다릅니다.
호스트 네트워크는 컨테이너와 호스트의 네트워크 스택을 아예 공유합니다. 격리가 사라지는 대신 성능 손실이 거의 없습니다.
실제 서비스 규모별로 보면 선택이 명확해집니다. 컨테이너 2~3개짜리 소규모 프로젝트는 사용자 정의 브리지 하나면 충분합니다.
여러 서버에 걸친 클러스터를 운영한다면 오버레이 네트워크가 필요합니다. Docker Swarm이나 Kubernetes 환경에서 주로 쓰입니다.
도커 네트워크 드라이버를 고를 때는 “컨테이너가 몇 대 호스트에 걸쳐 있는가”부터 확인하세요. 한 대면 브리지, 여러 대면 오버레이입니다. host는 성능이 급할 때만 예외적으로 씁니다.
컨테이너끼리 통신하는 법 – 같은 네트워크로 연결하기
컨테이너끼리 통신하는 법의 핵심은 딱 하나입니다. 같은 사용자 정의 네트워크에 두 컨테이너를 모두 연결하는 것입니다.
기본 브리지 네트워크는 이름 기반 DNS를 지원하지 않습니다. 그래서 docker network create로 커스텀 네트워크를 만들어 쓰는 게 표준 방식입니다.
예를 들어 docker network create app-net으로 네트워크를 만들고, docker run --network app-net --name db mysql처럼 컨테이너를 붙입니다. 다른 컨테이너도 같은 네트워크에 연결하면, 서로 db, web 같은 컨테이너 이름으로 접근할 수 있습니다.
즉 애플리케이션 컨테이너 안에서 데이터베이스 접속 주소를 IP 대신 db:3306처럼 컨테이너 이름으로 쓰면 됩니다. 이게 바로 도커의 내장 DNS 기능입니다.
포트 노출도 헷갈리는 부분입니다. 같은 네트워크 안 컨테이너끼리는 -p 옵션 없이도 컨테이너가 리슨 중인 포트로 바로 접근됩니다. -p는 호스트 외부에 열 때만 필요합니다.
가장 흔한 실수는 서로 다른 네트워크에 있는 컨테이너끼리 이름으로 통신하려는 경우입니다. 네트워크가 다르면 이름 조회 자체가 실패합니다.
docker network inspect [네트워크명]으로 두 컨테이너가 실제로 같은 네트워크에 있는지부터 확인하세요.docker-compose를 쓴다면 더 간단합니다. 같은 compose 파일 안의 서비스들은 기본적으로 하나의 네트워크에 자동으로 묶여 서로 서비스 이름으로 통신할 수 있습니다.
docker network 명령어로 직접 만들고 관리하기
네트워크 원리를 알았다면 실제로 다뤄볼 차례입니다. 도커 네트워크 관리는 몇 개 명령어만 익히면 충분합니다.
가장 먼저 알아야 할 건 docker network create입니다. 기본값은 브리지 드라이버이며, --driver 옵션으로 다른 타입을 지정할 수 있습니다.
이미 실행 중인 컨테이너를 다른 네트워크에 추가로 붙이고 싶다면 docker network connect를 쓰면 됩니다. 컨테이너를 재시작하지 않아도 즉시 적용됩니다.
특히 docker network inspect는 문제 진단의 시작점입니다. 어떤 컨테이너가 어떤 IP로 이 네트워크에 붙어 있는지 JSON 형태로 전부 보여줍니다.
불필요한 네트워크가 계속 쌓이는 것도 흔한 문제입니다. 테스트용으로 만든 네트워크를 지우지 않고 방치하면 docker network ls 결과가 지저분해집니다.
네트워크를 정리할 때는
docker network prune 전에 docker network ls로 목록을 먼저 확인하세요. 실행 중인 컨테이너가 물려 있는 네트워크는 자동으로 제외되지만, 습관적으로 확인하면 실수를 줄일 수 있습니다.도커 네트워크 통신 안 될 때 자주 하는 실수
도커 네트워크 설정을 제대로 했는데도 통신이 안 되는 경우가 있습니다. 대부분 원인은 몇 가지로 압축됩니다.
첫 번째는 서로 다른 네트워크에 컨테이너가 나뉘어 있는 경우입니다. compose 파일이 여러 개거나 프로젝트명이 다르면 의도치 않게 네트워크가 분리됩니다.
두 번째는 포트 번호 혼동입니다. 컨테이너 내부 포트와 호스트에 노출한 포트를 헷갈려서 잘못된 주소로 접속을 시도하는 경우가 많습니다.
세 번째는 방화벽이나 보안 그룹입니다. 클라우드 환경에서는 도커 네트워크 자체는 정상인데, 호스트 레벨의 iptables나 보안 그룹이 트래픽을 막는 경우도 흔합니다.
네 번째는 애플리케이션이 localhost에만 바인딩된 경우입니다. 컨테이너 안에서 127.0.0.1로만 리슨하면 같은 네트워크의 다른 컨테이너에서도 접근할 수 없습니다. 0.0.0.0으로 바인딩해야 합니다.
문제를 진단할 때는
docker exec -it [컨테이너] ping [다른컨테이너명]부터 시도해보세요. 이름 조회 자체가 실패하면 네트워크 분리 문제고, 이름은 통과하는데 특정 포트만 막히면 애플리케이션 바인딩이나 방화벽 문제일 가능성이 큽니다.기본 브리지 네트워크에서는 컨테이너 이름으로 통신이 안 되는 게 정상입니다. 실수가 아니라 도커의 기본 사양이므로, 반드시 사용자 정의 네트워크를 만들어 사용하세요.
자주 묻는 질문
기본 브리지는 이름 기반 DNS를 지원하지 않아 IP로만 접근해야 합니다. 사용자 정의 브리지는 컨테이너 이름으로 서로를 찾을 수 있어 실무에서는 항상 후자를 권장합니다.
가능합니다. docker network connect로 실행 중인 컨테이너를 추가 네트워크에 붙일 수 있고, 한 컨테이너가 여러 네트워크에 동시에 속할 수 있습니다.
compose는 프로젝트별로 기본 네트워크를 자동 생성해줍니다. 다만 여러 compose 프로젝트 간 통신이 필요하면 외부 네트워크를 따로 정의해 연결해야 합니다.
사용자 정의 브리지 네트워크에서는 --ip 옵션으로 고정 IP를 지정할 수 있습니다. 다만 이름 기반 통신이 가능하다면 굳이 고정할 필요는 없습니다.
컨테이너와 호스트의 포트가 그대로 겹치기 때문에 포트 충돌이 발생하기 쉽고, 네트워크 격리가 사라져 보안 측면에서도 불리합니다.
📖 핵심 용어 미니 사전
본문에 나온 용어가 낯설다면 아래에서 먼저 확인해보세요.
한 호스트 안에서 컨테이너끼리 통신하게 해주는 기본 네트워크 드라이버입니다.
컨테이너와 브리지를 연결하는 가상 이더넷 인터페이스 쌍입니다.
여러 대의 도커 호스트를 하나의 네트워크처럼 묶어주는 드라이버입니다.
같은 네트워크 내 컨테이너 이름을 IP로 자동 변환해주는 도커의 기능입니다.
🔗 공식 자료
📖 출처
Docker 공식 문서 – Networking overview, Network drivers, docker network CLI 레퍼런스, Compose 네트워크 설정 가이드를 참고했습니다.
도커 네트워크의 핵심은 “같은 네트워크에 있어야 이름으로 통신 가능하다”는 원칙 하나입니다. 기본 브리지 대신 사용자 정의 네트워크를 만들어 쓰면 컨테이너끼리 통신하는 법이 훨씬 단순해집니다.
