docker: driver failed programming external connectivity (iptables)

안녕하세요, BlueByte입니다. docker run -p가 갑자기 포트 게시를 거부하고, 최근에 방화벽을 건드렸다면 원인이 아주 분명합니다. 겁먹지 않으셔도 됩니다 — 오류를 읽고, 무슨 일이 있었는지 확인하고, 사라진 것을 다시 세운 뒤, 다음 방화벽 reload가 이걸 또 지우지 않게 하는 순서로 하나씩 짚어보겠습니다.

이 오류가 실제로 말하는 것

포트 게시가 이렇게 실패합니다:

docker: Error response from daemon: driver failed programming external
connectivity on endpoint web: (iptables failed: iptables -t nat -A DOCKER ...
No chain/target/match by that name)

Failed to program NAT chain: ... No chain/target/match by that name나, docker compose up에선 그냥 driver failed programming external connectivity로도 나옵니다. 마지막 줄만 보시면 됩니다 — 데몬이 NAT 규칙을 추가하려는데 의존하는 DOCKER 체인이 없는 것입니다. 이미지·컴포즈 파일·포트 번호는 멀쩡합니다. 망가진 건 Docker 아래에 깔린 호스트의 방화벽 상태입니다.

방화벽 reload가 DOCKER 체인을 지우는 이유

Docker는 포트를 게시한 컨테이너를 띄울 때 nat 테이블에 DOCKER 체인과 컨테이너별 규칙을 만듭니다. 무언가가 실행 중인 데몬 밑에서 그 체인을 지운 겁니다. 흔한 범인은 이렇습니다.

• 방화벽 reload — firewall-cmd --reload, ufw enable/reload, netfilter-persistent — 가 자체 설정으로 룰셋을 다시 만들었는데 거기엔 Docker 체인이 없음.
• --noflush 없는 수동 iptables-restore — 테이블 전체를 교체하며 Docker 체인까지 가져감.
• 주기적으로 iptables를 flush하는 하드닝 도구나 cron 작업.

체인이 정말 사라졌는지 먼저 확인하기

추측할 필요 없습니다. 직접 확인해 보면 됩니다:

sudo iptables -t nat -L DOCKER -n

No chain/target/match by that name이면 지워진 게 맞습니다. 무엇이 지웠는지는 iptables를 다시 쓰는 서비스와 최근 실행 시각으로 찾습니다:

systemctl status firewalld ufw netfilter-persistent
sudo journalctl -u firewalld --since "15 min ago"

깨진 시점이 reload나 재부팅과 맞아떨어지면 그게 원인입니다.

데몬을 재시작해 규칙을 다시 세우기

Docker를 재시작하면 체인과 컨테이너별 규칙이 다시 만들어집니다. 외울 것도 없습니다 — 명령 하나면 됩니다:

sudo systemctl restart docker
sudo iptables -t nat -L DOCKER -n   # 체인과 규칙이 돌아옴

그다음 reload가 또 지우지 않게 합니다. firewalld 호스트라면 firewalld와 Docker 통합을 함께 켜 두세요 — Docker는 firewalld를 통해 규칙을 넣으므로, reload가 규칙을 버리지 않고 다시 적용합니다:

sudo firewall-cmd --reload
sudo iptables -t nat -L DOCKER -n   # 여전히 존재

iptables-restore로 스크립트화한다면 --noflush를 붙여 테이블 전체 교체 대신 덧붙이게 하세요.

실제 사례: 오후 2시의 reload

방화벽 규칙을 하나 손보고 reload한 뒤로 모든 docker run -p가 실패한다고 합시다. iptables -t nat -L DOCKER -n이 "No chain/target/match by that name"을 반환하고, journalctl -u firewalld에는 실패가 시작되기 2분 전 reload가 찍혀 있습니다. 이게 지문입니다 — reload가 체인을 flush한 것이죠. sudo systemctl restart docker로 체인을 다시 만들면 같은 iptables 명령이 이제 체인을 보여주고, 컨테이너가 정상 게시됩니다. 다음 firewalld reload에도 체인은 살아남습니다 — Docker가 firewalld를 우회하지 않고 통해서 규칙을 등록했기 때문입니다.

고친 뒤 끝까지 되는지 보기

규칙이 맞아 보이는 것에서 그치지 말고, 실제로 되는지 확인합니다:

docker run --rm -p 8080:80 nginx:alpine
curl -sSI http://localhost:8080 | head -1   # HTTP/1.1 200 OK

200 응답과 iptables -t nat -L DOCKER -n의 규칙이 함께 보이면 해결이 유지된 것입니다.

다시 겪지 않으려면

부팅 시 방화벽이 Docker보다 먼저 뜨게 유닛 순서를 잡거나, firewalld가 통합을 담당하게 해 reload가 체인을 벗기지 않게 하세요. 자주 reload하는 호스트라면 nat 테이블에 대해 맨 iptables -F나 범위 없는 iptables-restore를 피하고, flush를 자기 체인으로 한정하세요.

"port is already allocated"와의 구분

Bind for 0.0.0.0:8080 failed: port is already allocated는 반대 경우입니다 — 체인은 멀쩡한데 다른 컨테이너가 이미 포트를 쥔 것이죠. 그리고 /etc/docker/daemon.json의 "iptables": false는 게시 포트 연결을 통째로 꺼서 이 오류를 잠재우는 것뿐이라, 외부에서 컨테이너에 닿을 수 없게 됩니다. 모든 NAT 규칙을 직접 관리하는 게 아니라면 iptables 관리는 켜 두세요. 다음에 방화벽을 만진 직후 포트 게시가 실패하면, DOCKER 체인부터 확인해 보세요 — 거의 항상 이 문제입니다.