Docker container networking - NAT and port publishing

Alert

이 글은 Claude Code의 도움을 받아 작성되었습니다

TL;DR

• 컨테이너는 자신만의 격리된 네트워크 세계에 있어 호스트의 NIC를 직접 쓰지 못함
• bridge 네트워크는 도커가 호스트 안에 만드는 소프트웨어 스위치, veth pair로 컨테이너와 연결
• 아웃바운드는 출발지 IP를 호스트 IP로 바꾸는 NAT(masquerade)로 인터넷에 나감
• 인바운드는 기본 차단, -p 8080:80로 포트를 열어야 DNAT 규칙이 생겨 외부에서 도달
• 컨테이너 앱은 127.0.0.1이 아니라 0.0.0.0에 바인딩해야 포워딩된 트래픽을 받음

Source

---

1. 왜 헷갈리는가

도커를 쓰다 보면 자주 겪는 두 가지 상황이 있다.

• 컨테이너 안에서는 apt update나 외부 API 호출이 잘 되는데,
• 정작 브라우저에서 localhost:80으로 컨테이너에 접속하면 아무 응답이 없다.

둘 다 같은 네트워크 문제처럼 보인다. 하지만 도커는 나가는 트래픽(아웃바운드)과 들어오는 트래픽(인바운드)을 완전히 다르게 다룬다. 이 둘만 떼어 놓고 보면 도커 네트워킹 질문의 절반은 저절로 풀린다.

Docker 네트워크는 드라이버 종류와 계층 구조를 다룬다. 이 글은 그 대신 패킷이 실제로 어떤 길을 따라 흐르는지를 파고든다.

---

2. 기본 개념 - 컨테이너는 격리된 네트워크에 산다

컨테이너의 네트워크 세계

컨테이너는 자기만의 작은 네트워크 세계 안에 격리된 채 돌아간다. 그래서 호스트 머신(여기서는 노트북)의 실제 네트워크 카드(NIC)를 직접 건드리지 못한다. 그럼 이 격리된 컨테이너를 어떻게 NIC까지 이어 줄까. 이게 풀어야 할 문제다.

용어: 호스트 머신

도커 컨테이너를 실행하는 시스템을 말한다. 이 글에서는 노트북을 호스트로 가정한다. 호스트의 NIC가 인터넷과의 실제 송수신을 담당한다.

bridge 네트워크 = 소프트웨어 스위치

도커는 컨테이너를 기본으로 bridge 네트워크에 올린다. bridge 네트워크는 도커가 호스트 안에 슬쩍 만들어 두는 소프트웨어 스위치, 즉 스위치 역할을 하는 가상 장치다.

• 새로 띄우는 컨테이너는 모두 이 스위치에 꽂힌다.
• 같은 스위치(같은 사설 네트워크)에 있으므로 컨테이너끼리는 내부 IP로 직접 통신할 수 있다. 포트 게시도, 변환도 필요 없다.
• bridge 네트워크는 여러 개 만들 수 있다. 같은 bridge에 있는 컨테이너끼리는 통신되지만, 다른 bridge라면 기본적으로 통신되지 않는다. 굳이 통신시키려면 컨테이너를 양쪽 네트워크에 모두 연결하면 된다.

veth pair - 가상 네트워크 케이블

컨테이너를 스위치에 연결하기 위해 도커는 veth pair(가상 이더넷 페어)를 만든다. 양 끝이 있는 가상 랜선이라고 보면 된다.

• 한쪽 끝은 컨테이너 안으로 들어간다. 이 연결점이 컨테이너 네트워크 인터페이스다. 컨테이너 입장에서는 그냥 평범한 네트워크 인터페이스로 보이고, 보통 eth0라고 부른다.
• 다른 쪽 끝은 도커 bridge 네트워크에 연결된다.

패킷의 전체 경로는 다음과 같다.

컨테이너 앱
  → 컨테이너 네트워크 인터페이스 (eth0)
  → veth (가상 랜선)
  → 도커 bridge 네트워크
  → 호스트
  → 호스트의 실제 NIC
  → 인터넷

사설 IP 할당

bridge에 연결된 컨테이너는 사설 IP를 받는다.

대상	예시 IP	설명
노트북(호스트)	192.168.1.10	실제 네트워크의 IP
컨테이너	172.17.0.2	도커 내부 사설 IP
bridge 자체	172.17.0.1	게이트웨이 역할

bridge는 게이트웨이 역할을 한다. 컨테이너가 호스트로 나가려면 모든 패킷을 이 문으로 내보내야 한다. (사설 IP와 공인 IP의 차이가 여기서 핵심으로 작용한다.)

---

3. 첫 번째 여정 - 컨테이너가 인터넷으로 나갈 때 (아웃바운드)

컨테이너 안의 Nginx가 패키지를 내려받거나 외부 API를 호출한다고 하자. 패킷은 eth0 → veth → bridge → 호스트 순으로 흘러간다. 그런데 여기서 문제가 하나 터진다.

패킷의 출발지 주소는 172.17.0.2인데, 이건 노트북 안에서만 통하는 사설 IP다. 이대로 인터넷에 내보내면 응답이 돌아올 곳이 없다. 인터넷의 어떤 라우터도 172.17.0.2가 어디인지 모르니까.

NAT (masquerade)

그래서 호스트가 나서서 NAT(Network Address Translation)를 해 준다. 도커는 뒤에서 iptables 규칙을 걸어 패킷의 출발지 주소를 바꿔 쓴다.

나갈 때:  출발지 172.17.0.2  →  192.168.1.10 (호스트의 실제 IP)

• 패킷이 호스트를 떠나는 순간, 사설 IP 172.17.0.2가 호스트의 실제 IP 192.168.1.10으로 바뀌고 실제 NIC를 통해 인터넷으로 빠져나간다.
• 인터넷 쪽에서 보면 트래픽이 노트북에서 곧장 온 것처럼 보인다. 컨테이너는 그림자도 안 비친다.
• 응답이 192.168.1.10으로 돌아오면, 호스트는 “이건 그 컨테이너 거였지” 하고 목적지를 다시 172.17.0.2로 바꿔 bridge → veth → eth0로 전달한다.

덕분에 컨테이너는 자기 공인 주소 하나 없이도 인터넷 전체에 닿을 수 있다.

---

4. 두 번째 여정 - 외부에서 컨테이너로 들어올 때 (인바운드)

다들 여기서 막힌다. Nginx가 포트 80에서 멀쩡히 돌고 있는데, 브라우저에서 localhost:80이나 노트북 IP로 접속하면 응답이 없다.

이유는 간단하다.

• 컨테이너 IP 172.17.0.2는 사설 주소라 노트북 밖에서는 직접 닿을 수 없다.
• 게다가 호스트는 기본 상태에서 컨테이너로 아무것도 넘겨주지 않는다. Nginx는 귀를 열고 있지만, 외부에서 그 사설 네트워크로 들어갈 문 자체가 없다.

포트 게시 (port publishing)

그래서 문을 직접 열어 줘야 한다. 컨테이너를 띄울 때 -p 플래그를 붙인다.

docker run -p 8080:80 nginx

도커에게 “노트북의 8080 포트로 들어오는 트래픽을 컨테이너 내부의 80 포트로 보내라”고 지시하는 셈이다. 그러면 도커는 또 다른 NAT 규칙(DNAT, 목적지 주소 변환)을 하나 더 써 둔다.

들어올 때:  목적지 노트북:8080  →  172.17.0.2:80

이제 8080으로 들어온 요청은 목적지가 172.17.0.2:80으로 바뀐 뒤 bridge → eth0를 거쳐 Nginx까지 닿는다.

0.0.0.0 바인딩 함정

컨테이너 안의 앱은 반드시 모든 주소(0.0.0.0)에서 수신해야 한다. 127.0.0.1에만 바인딩되어 있으면, 포워딩된 트래픽이 벽에 부딪혀 포트를 게시했어도 connection refused가 난다. “포트를 열었는데 왜 안 되지?”의 흔한 원인이다.

---

5. 두 규칙으로 정리

호스트가 뒤에서 챙기는 NAT 규칙은 결국 두 가지로 좁혀진다.

방향	변환 대상	효과
아웃바운드	출발지 IP 재작성 (masquerade)	컨테이너가 호스트 신원을 빌려 인터넷과 통신
인바운드	목적지 IP 재작성 (DNAT)	명시적으로 게시한 포트에 한해 외부 → 컨테이너 도달

컨테이너는 실제 NIC를 절대 직접 건드리지 않는다. 호스트가 중간에 끼어 양방향을 통째로 번역해 준다.

트러블슈팅 휴리스틱

이 흐름이 머릿속에 한 번 그려지면 문제 진단이 부쩍 빨라진다.

• 컨테이너는 인터넷에 나가는데, 외부에서 컨테이너에 못 들어간다 → 포트 게시(-p)를 빠뜨림
• 같은 bridge의 두 컨테이너는 통신되는데 세 번째만 안 된다 → 그 컨테이너만 다른 네트워크에 있음
• 포트를 게시했는데도 connection refused → 앱이 127.0.0.1에만 바인딩됨 (0.0.0.0 필요)

---

6. 관련 노트

• Docker 네트워크 - bridge/overlay/macvlan 등 드라이버 종류와 계층 구조, macOS와 Linux 차이. 이 글의 NAT/포트 게시 흐름과 상호 보완
• 8. IP 주소 - 사설 IP와 공인 IP, NAT의 배경
• 6. 스위치 - bridge 네트워크가 흉내 내는 데이터 링크 계층 스위치
• Dockerfile, Docker 명령어 - -p 등 컨테이너 실행 옵션