웹 서버 컨테이너에서 curl http://db:5432를 실행했는데 연결이 안 됩니다. 같은 호스트에서 두 컨테이너를 실행했는데도 서로 찾지 못하는 상황입니다. 컨테이너는 기본적으로 격리된 네트워크 네임스페이스를 가지기 때문에, 어떤 네트워크 드라이버를 통해 연결하느냐에 따라 통신 방식이 완전히 달라집니다. 기본 브릿지(docker0)는 IP 주소로만 통신 가능하고, 사용자 정의 네트워크는 이름으로 통신 가능합니다. Host 모드는 격리를 포기하고 최고 성능을 택하며, None은 네트워크를 완전히 차단합니다. 이 ConceptBlock에서는 Docker가 제공하는 세 가지 기본 네트워크 드라이버와 각각의 동작 방식을 다룹니다.

Docker는 컨테이너 간 통신 방식에 따라 세 가지 핵심 네트워크 드라이버를 제공합니다.

확대

브릿지(Bridge) 네트워크

브릿지 네트워크는 Docker의 기본 네트워크 모드입니다. Docker를 설치하면 docker0라는 가상 브릿지 인터페이스가 자동 생성되고, 별도 설정 없이 실행한 모든 컨테이너는 이 브릿지에 연결됩니다. 호스트의 물리 네트워크 위에 Docker가 만든 가상 스위치로 이해하면 됩니다. 아래 구조를 보면 컨테이너들이 호스트와 분리된 사설 IP 대역에서 동작한다는 것이 명확해집니다.

호스트 머신의 인터페이스 구성은 다음과 같습니다.

• eth0 — 물리 네트워크 (192.168.1.100)
• docker0 — 가상 브릿지 (172.17.0.1)
  • container-A (172.17.0.2)
  • container-B (172.17.0.3)

컨테이너들은 172.17.0.x 대역의 사설 IP를 받아서 서로 통신할 수 있습니다. 단, 기본 브릿지(docker0)에는 내장 DNS가 없습니다. 이것이 핵심 제약사항입니다.

Host 네트워크

--network host 옵션을 사용하면 컨테이너가 호스트의 네트워크 네임스페이스를 그대로 사용합니다. 가상 네트워크 인터페이스가 없으므로 포트 매핑(-p)도 불필요합니다.

# 실습 디렉토리 준비
mkdir -p /tmp/docker/part3/exam_10 && cd /tmp/docker/part3/exam_10

# Host 모드로 nginx 실행 — 호스트의 80포트를 직접 사용
docker run --network host nginx

장점: NAT 오버헤드 없이 최고의 네트워크 성능 단점: 포트 충돌 위험, 컨테이너 격리 약화, macOS/Windows에서 미지원

None 네트워크

--network none은 루프백(127.0.0.1) 외 모든 네트워크 인터페이스를 비활성화합니다. 완전한 네트워크 격리가 필요한 보안 작업이나 배치 처리에 사용합니다.

# 네트워크 없는 완전 격리 컨테이너
docker run --network none alpine sh -c "echo '외부 접근 불가'"

현재 네트워크 목록 확인

docker network ls
# NETWORK ID     NAME      DRIVER    SCOPE
# abc123def456   bridge    bridge    local   ← 기본 docker0
# xyz789uvw012   host      host      local
# 111aaa222bbb   none      null      local

docker run -p 8080:80 nginx 한 줄이면 컨테이너가 자기 IP를 받고, 밖으로 인터넷도 나가고, 호스트 8080으로 들어온 요청도 받습니다. 이 짧은 순간에 리눅스 커널에서는 network namespace 생성 → veth 쌍 연결 → IP 할당 → 나갈 때 SNAT → 들어올 때 DNAT가 순서대로 엮입니다. 이 흐름을 알면 "컨테이너가 왜 IP를 못 받지", "왜 컨테이너에서 인터넷이 안 되지", "왜 -p 를 줬는데 접속이 안 되지"를 단계로 좁혀 진단할 수 있습니다. 컨테이너 네트워크는 마법이 아니라 아래 5단계의 결과입니다.

docker run -p 8080:80 nginx
   │
   ① network namespace 생성          (컨테이너에 독립 네트워크 스택: 자체 lo·라우팅표·iptables)
   │
   ② veth 쌍 생성 (가상 랜선 한 쌍)
   │    ├─ 한쪽 끝 → 컨테이너 안 eth0
   │    └─ 다른 끝 → 호스트 docker0 브리지에 꽂힘
   │
   ③ IPAM이 컨테이너 eth0에 IP 할당    (172.17.0.0/16 에서 예: 172.17.0.2)
   │    기본 게이트웨이 = docker0 (172.17.0.1)
   │
   ④ 나가는 트래픽 → iptables MASQUERADE(SNAT)
   │    출발지 IP 172.17.0.2 → 호스트 IP로 바꿔 내보냄 (그래야 응답이 돌아옴)
   │
   ⑤ 들어오는 트래픽(-p 8080:80) → iptables DNAT
   │    호스트:8080 도착 → 목적지를 172.17.0.2:80 으로 바꿔 컨테이너로 전달
   ▼
[컨테이너 nginx가 응답]  → 역방향으로 NAT을 되돌려 클라이언트에 도달

각 단계에서 무슨 일이 일어나고, 막히면 어떤 증상인가:

같은 사용자 정의 네트워크(브리지)에 붙은 컨테이너끼리는 이 브리지를 L2 스위치처럼 거쳐 서로 직접 통신하고, 이때 이름→IP 해석은 각 컨테이너의 /etc/resolv.conf 에 박힌 임베디드 DNS 127.0.0.11 이 처리합니다(기본 bridge 에는 이 DNS가 없어 이름 통신 불가). host/none/bridge의 차이도 결국 ①에서 netns를 어떻게 두느냐의 차이입니다.

정리하면 "컨테이너 통신 성공"은 여러 층이 모두 참이라는 뜻입니다 — netns에 veth가 브리지로 이어졌고(②), IP·게이트웨이가 정상 배정됐고(③), 나갈 땐 SNAT·들어올 땐 DNAT가 걸려 있다(④⑤). 안 될 때는 컨테이너 안에서 ip addr·ip route 로 IP·게이트웨이를, 호스트에서 iptables -t nat -L -n 으로 MASQUERADE·DNAT 규칙을, sysctl net.ipv4.ip_forward 로 포워딩을 확인하면 어느 층에서 끊겼는지 좁혀집니다.

기본 브릿지(docker0)의 가장 큰 단점은 컨테이너 이름으로 통신이 불가능하다는 점입니다. IP는 재시작마다 바뀔 수 있기 때문에, 안정적인 서비스 간 통신을 위해서는 사용자 정의 네트워크를 만들어야 합니다.

사용자 정의 네트워크의 핵심 기능: 내장 DNS

사용자 정의 네트워크에는 Docker가 자동으로 **내장 DNS 서버(127.0.0.11)**를 제공합니다. 이 DNS 서버는 컨테이너 이름을 자동으로 해당 컨테이너의 IP로 변환해줍니다.

확대

사용자 정의 네트워크(my_network)는 내장 DNS 서버(127.0.0.11)를 제공합니다.

• web 컨테이너 (172.20.0.2) → "web" 이름으로 접근 가능
• db 컨테이너 (172.20.0.3) → "db" 이름으로 접근 가능

web 컨테이너 내부에서:

ping db            # → 172.20.0.3으로 자동 해석
curl http://db:5432  # → 동작

기본 브릿지 vs 사용자 정의 네트워크 비교

두 네트워크 타입은 겉으로는 비슷해 보이지만 실무에서 차이가 확연합니다. 기본 브릿지는 테스트용으로는 충분하지만, Docker Compose로 여러 서비스를 연결하는 순간 사용자 정의 네트워크가 필수가 됩니다.

네트워크 생성과 관리 명령어

# 사용자 정의 브릿지 네트워크 생성
docker network create my_net

# 서브넷과 게이트웨이를 명시적으로 지정
docker network create \
  --driver bridge \
  --subnet 172.20.0.0/16 \
  --gateway 172.20.0.1 \
  my_net

# 네트워크 상세 정보 확인
docker network inspect my_net

# 네트워크에 연결된 컨테이너 목록 확인
docker network inspect my_net --format '{{range .Containers}}{{.Name}} {{end}}'

# 사용하지 않는 네트워크 정리

컨테이너에서 인터넷은 되는데 사내 서버 하나로만 연결이 안 된다는 증상은 DNS나 포트 문제가 아니라 서브넷이 겹쳐 라우팅이 어긋난 경우가 많습니다. 사용자 정의 네트워크의 IP 대역이 어디서 오는지 알아야 보입니다.

• 서브넷은 자동으로 할당됩니다: docker network create에 --subnet을 주지 않으면, Docker는 기본 주소 풀(default-address-pools, 대개 172.17.0.0/16부터 172.31, 그 뒤 192.168 대역)에서 안 쓰는 대역을 하나 떼어 줍니다.
• 사내망과 겹치면 라우팅이 샙니다: 자동으로 잡힌 이 대역이 회사 사내망이나 VPN 대역과 겹치면, 컨테이너의 라우팅 테이블에서 그 대역이 로컬 브릿지(eth0) 로 향합니다. 그래서 같은 대역의 진짜 사내 서버로 나가야 할 패킷이 브릿지 안에서 맴돌고, 실제 게이트웨이로 못 나갑니다.
• 호스트는 멀쩡한데 컨테이너만 막힙니다: 호스트의 라우팅은 그대로라 호스트에서는 사내 서버에 잘 붙습니다. 오직 겹치는 대역에 놓인 컨테이너만 그 목적지를 못 봅니다. 인터넷(다른 대역)은 정상이라 원인 짐작이 더 어렵습니다.
• 대역을 비켜 주면 됩니다: daemon.json의 default-address-pools를 사내망과 안 겹치는 대역으로 지정하거나, 문제 네트워크를 --subnet으로 겹치지 않게 다시 만듭니다.

컨테이너 네트워크를 설계할 때 어떤 사설 대역을 쓰는지를 사내망과 대조하는 것이, 나중의 특정 목적지만 안 되는 사고를 막습니다.

두 컨테이너가 같은 Compose 파일에 있는데 서로 통신이 안 됩니다. 에러 로그에는 "Connection refused" 또는 "No such host"가 뜹니다. 네트워크 문제는 원인이 여러 개일 수 있어서 무작정 설정을 바꾸면 오히려 혼란이 커집니다. 컨테이너가 같은 네트워크에 속해 있는지, DNS가 이름을 올바르게 해석하는지, 포트가 실제로 열려 있는지 순서대로 좁혀 나가야 빠르게 찾을 수 있습니다. 이 ConceptBlock에서는 컨테이너 간 통신 문제를 5단계로 진단하는 방법을 다룹니다.

확대

단계별 진단 절차

컨테이너 간 통신 문제는 대부분 이 5단계 절차로 원인을 찾을 수 있습니다.

Step 1: 두 컨테이너가 같은 네트워크에 있는지 확인

# 네트워크 상세 정보 확인 — Containers 섹션에 두 컨테이너 모두 있어야 함
docker network inspect my_net

# 출력 예시
{
  "Name": "my_net",
  "Containers": {
    "abc123": { "Name": "web", "IPv4Address": "172.20.0.2/16" },
    "def456": { "Name": "db",  "IPv4Address": "172.20.0.3/16" }
  }
}

# 특정 컨테이너가 속한 네트워크 목록 확인
docker inspect web --format '{{json .NetworkSettings.Networks}}' | python3 -m json.tool

Step 2: 컨테이너 내부에서 DNS 해석 테스트

# nslookup으로 이름 → IP 변환 테스트
docker exec web nslookup db
# Server:    127.0.0.11    ← Docker 내장 DNS
# Address:   127.0.0.11#53
# Name:      db
# Address:   172.20.0.3    ← 정상 해석됨

# ping으로 연결 확인
docker exec web ping -c 3 db

# Alpine 기반 이미지는 nslookup 대신 nslookup 패키지 설치 필요
# docker exec -it web sh
# / # nslookup db || apk add --no-cache bind-tools

Step 3: 포트 연결 테스트

# nc(netcat)으로 TCP 포트 열림 확인
docker exec web nc -zv db 5432
# Connection to db 5432 port [tcp/postgresql] succeeded!

# wget으로 HTTP 응답 확인
docker exec web wget -qO- http://api:8080/health

# curl 사용 시
docker exec web curl -s http://api:8080/health

Step 4: 컨테이너 네트워크 인터페이스 확인

# 컨테이너 내부 네트워크 인터페이스
docker exec web ip addr show
# eth0: 172.20.0.2/16  ← 컨테이너 IP

# 라우팅 테이블 확인
docker exec web ip route
# default via 172.20.0.1 dev eth0  ← 게이트웨이

자주 발생하는 네트워크 문제

기본 bridge vs 사용자 정의 network 한 눈에 비교

# 기본 bridge (docker0): 이름으로 통신 불가
docker run -d --name app1 nginx
docker run -d --name app2 nginx
docker exec app1 ping app2   # ❌ 실패! IP 직접 입력해야 함

# 사용자 정의 network: 이름으로 통신 가능
docker network create mynet
docker run -d --name app1 --network mynet nginx
docker run -d --name app2 --network mynet nginx
docker exec app1 ping app2   # ✅ 성공! 이름으로 통신됨

docker-compose.yml에 networks를 한 번도 선언하지 않았는데 서비스 이름으로 통신이 됩니다. 왜 그럴까요? Compose는 프로젝트마다 자동으로 기본 네트워크를 만들고 모든 서비스를 거기에 붙입니다. 이 동작을 모르면 "Compose에서는 됐는데 왜 docker run으로 따로 뜬 컨테이너와는 통신이 안 되지?"라는 혼동이 생깁니다. 자동 생성 네트워크의 이름 규칙과 서비스 간 연결 방식을 이해하면, 다중 Compose 프로젝트를 연결하거나 외부 컨테이너를 편입하는 고급 패턴도 자연스럽게 납득됩니다. 이 ConceptBlock에서는 Compose가 네트워크를 자동으로 구성하는 원리를 다룹니다.

확대

Compose가 네트워크를 자동으로 만드는 이유

docker-compose.yml에 networks를 명시하지 않아도 서비스 간 통신이 되는 이유가 있습니다. Compose는 프로젝트마다 프로젝트명_default 네트워크를 자동으로 만들고 모든 서비스를 여기에 연결합니다.

# myapp 디렉토리에서 docker compose up 실행
cd ~/myapp && docker compose up -d

# 자동 생성된 네트워크 확인
docker network ls
# NETWORK ID     NAME            DRIVER
# abc123def456   myapp_default   bridge   ← 자동 생성됨
#                ↑ 디렉토리명이 프로젝트명이 됨

이 네트워크 안에서 서비스 이름이 곧 DNS 이름이 됩니다.

# 네트워크를 명시하지 않아도 서비스 이름으로 통신 가능
services:
  web:
    image: myapp
    environment:
      - DB_HOST=db   # 'db' = 서비스 이름 = DNS 이름

  db:
    image: postgres:16-alpine

여러 Compose 스택 간 네트워크 공유

서로 다른 docker-compose.yml 파일로 실행한 서비스들이 통신해야 할 때, external network를 사용합니다.

# 1. 공유 네트워크 먼저 생성
docker network create shared-net

# stack-a/compose.yml
networks:
  shared-net:
    external: true   # 외부에서 이미 만든 네트워크 사용

services:
  api:
    image: my-api
    networks:
      - shared-net
      - default        # stack-a 내부 통신용

# stack-b/compose.yml
networks:
  shared-net:
    external: true

services:
  frontend:
    image: my-frontend
    networks:
      - shared-net   # api 서비스에 접근 가능

docker compose -f stack-a/compose.yml up -d
docker compose -f stack-b/compose.yml up -d

# frontend에서 api로 통신 가능
docker exec stack-b-frontend-1 curl http://api:8080/health

네트워크 격리 전략

services:
  web:
    networks:
      - frontend   # 외부와 통신
      - backend    # DB와 통신

  db:
    networks:
      - backend    # backend에만 존재 → 외부 직접 접근 불가
      # frontend 네트워크 없음 → web을 통해서만 접근 가능

  redis:
    networks:
      - backend

networks:
  frontend:    # 외부 트래픽 용
  backend:     # 내부 서비스 전용 (DB, 캐시 등)

이렇게 네트워크를 분리하면 DB와 캐시는 web 서비스를 통해서만 접근 가능하여 보안이 강화됩니다.