지니제스트 테크 블로그 배너
지니제스트Tech Archive
Docker8분 소요

Docker Pool overlaps 에러 해결

•
지지니제스트
•조회 4

docker compose up에서 Pool overlaps with other one on this address space가 날 때 겹치는 Docker 네트워크를 찾는 방법과, 자동 할당된 Docker 서브넷이 사내망이나 VPN 경로를 가로채는 문제를 daemon.json의 bip와 default-address-pools로 막는 설정, 적용 순서를 정리했습니다.

Docker Pool overlaps 에러 해결

docker compose up을 했더니 네트워크를 만드는 단계에서 바로 멈추는 경우가 있습니다.

TEXT
✘ Network infra_default  Error
Error response from daemon: Pool overlaps with other one on this address space

이 오류는 새로 만들려는 Docker 네트워크의 서브넷이 이미 있는 다른 Docker 네트워크의 주소 범위와 겹친다는 뜻입니다. 비슷한 시기에 같이 겪는 문제가 하나 더 있습니다. 오류 없이 만들어진 Docker 네트워크가 사내망이나 VPN 대역과 겹쳐서, 호스트에서 사내 서버로 가는 접속이 끊기는 경우입니다. 원인과 해결책이 거의 같아서 함께 정리했습니다.

daemon.json의 bip와 default-address-pools, Compose 서브넷 설정의 적용 대상을 비교한 표
Docker 대역 설정 비교

어떤 네트워크와 겹치는지 찾기

Docker 네트워크마다 쓰고 있는 서브넷을 한 번에 봅니다.

BASH
docker network inspect $(docker network ls -q) \
  --format '{{.Name}}: {{range .IPAM.Config}}{{.Subnet}} {{end}}'
TEXT
bridge: 172.17.0.0/16
infra_backend: 172.18.0.0/16
monitoring_default: 172.20.0.0/16
old-project_default: 10.10.0.0/24

이 오류가 가장 자주 나는 경우는 Compose 파일에 서브넷을 직접 적어 둔 경우입니다. 예를 들어 새 프로젝트에 subnet: 172.20.0.0/16을 적었는데 다른 프로젝트가 자동 할당으로 이미 172.20.0.0/16을 쓰고 있으면 충돌합니다. 지운 줄 알았던 예전 프로젝트의 네트워크가 남아 있는 경우도 많습니다.

BASH
# 컨테이너가 하나도 연결되지 않은 네트워크 정리
docker network prune

Docker가 서브넷을 고르는 방식

서브넷을 지정하지 않고 네트워크를 만들면 Docker는 기본 주소 풀에서 다음 빈 대역을 꺼내 씁니다. 기본 풀은 이렇게 생겼습니다.

  • 172.17.0.0/16부터 172.31.0.0/16까지 /16 단위로 하나씩 (기본 docker0가 172.17.0.0/16)
  • 그다음 192.168.0.0/16을 /20 단위로 나눠서

네트워크 하나가 /16, 즉 주소 6만 5천 개를 통째로 가져가기 때문에 Compose 프로젝트가 열댓 개만 돼도 172.16.0.0/12 대역이 거의 다 찹니다. 그 뒤로는 192.168.x.x로 넘어가는데, 가정용 공유기나 사무실 LAN과 겹치기 쉬운 대역입니다.

Docker는 네트워크를 만들 때 호스트의 현재 경로와 겹치는 대역은 피하려고 합니다. 하지만 그 판단은 만드는 순간에만 합니다. VPN이 꺼져 있을 때 만든 네트워크가 VPN이 내려 주는 172.20.0.0/16 경로와 같은 대역을 잡았다면, 나중에 VPN을 켰을 때 그 대역으로 가는 패킷이 VPN이 아니라 Docker 브리지로 갑니다. 사내 서버 접속이 안 되는데 Docker를 내리면 되는 이상한 증상은 대부분 이 경우입니다.

BASH
# 사내 서버 IP가 어느 인터페이스로 나가는지 확인
ip route get 172.20.5.10

결과에 dev br-xxxxxxxx가 나오면 Docker 브리지가 경로를 가로채고 있는 것입니다.


daemon.json으로 Docker 전용 대역 정하기

근본적인 해결은 Docker가 쓸 대역을 사내망, VPN, 집 공유기 어디와도 겹치지 않는 곳으로 정해 두는 것입니다. 회사 네트워크는 10.0.0.0/8을 넓게 쓰는 곳도 많으니, 정하기 전에 네트워크 담당자에게 비어 있는 대역을 확인하는 게 좋습니다.

JSON
{
  "bip": "10.200.0.1/24",
  "default-address-pools": [
    { "base": "10.201.0.0/16", "size": 24 }
  ]
}
  • bip: 기본 docker0 브리지의 주소입니다. 네트워크를 따로 지정하지 않은 docker run 컨테이너가 여기에 붙습니다.
  • default-address-pools: Compose와 docker network create가 서브넷을 자동으로 고를 때 쓰는 풀입니다. 위 설정이면 10.201.0.0/24, 10.201.1.0/24처럼 /24씩 잘라서 최대 256개 네트워크를 만들 수 있습니다.

둘은 적용 대상이 다르므로 함께 바꿔야 합니다. bip만 바꾸면 Compose 네트워크는 여전히 172.x를 쓰고, 풀만 바꾸면 docker0가 172.17.0.0/16에 남습니다.

/etc/docker/daemon.json에 이미 다른 설정(로그 옵션 등)이 있다면 같은 JSON 객체 안에 항목을 추가합니다. 파일 문법이 틀리면 Docker 데몬이 아예 시작하지 않으니 저장 전에 python3 -m json.tool /etc/docker/daemon.json으로 확인해 두면 안전합니다.


적용 순서

daemon.json을 바꿔도 이미 만들어진 네트워크의 서브넷은 그대로입니다. 네트워크 정보는 Docker가 따로 저장해 두고 재시작 후에도 다시 씁니다. 그래서 네트워크를 지우고 다시 만들어야 새 풀이 적용됩니다.

BASH
# 1. 각 Compose 프로젝트 내리기 (네트워크도 같이 삭제됨)
docker compose down

# 2. 남은 사용자 정의 네트워크 정리
docker network prune

# 3. 데몬 재시작
sudo systemctl restart docker

# 4. 다시 올리기
docker compose up -d

적용됐는지 확인합니다.

BASH
ip -4 addr show docker0
docker network inspect infra_default --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
ip route | grep -E 'docker0|br-'

docker0가 10.200.0.1/24이고, 새 Compose 네트워크가 10.201.x.0/24로 잡혀 있으면 됩니다. 마지막으로 앞에서 했던 ip route get <사내 서버 IP>를 다시 실행해 Docker 브리지가 아닌 원래 인터페이스로 나가는지 봅니다.


Compose 파일에 서브넷을 직접 적을 때

고정 IP가 필요한 경우처럼 서브넷을 직접 적어야 한다면, 자동 할당 풀(10.201.0.0/16)과 겹치지 않는 대역을 씁니다.

YAML
services:
  database:
    image: postgres:17-alpine
    networks:
      backend:
        ipv4_address: 10.205.10.5

networks:
  backend:
    ipam:
      config:
        - subnet: 10.205.10.0/24

자동 할당 풀 안의 대역을 직접 적으면 Docker가 이미 그 대역을 다른 네트워크에 줬을 때 Pool overlaps가 그대로 다시 납니다. 고정 대역용과 자동 할당용 범위를 나눠 두는 게 핵심입니다.


자주 받는 질문

Q. size는 얼마로 잡아야 하나요?

base보다 작게 잘라야 여러 네트워크가 나옵니다. base가 /16인데 size도 16이면 네트워크를 딱 하나밖에 못 만들고, 두 번째부터는 풀이 바닥났다는 오류가 납니다. Compose 프로젝트 하나에 컨테이너가 수십 개를 넘는 일은 드물어서 보통 /24(주소 254개)면 충분합니다.

Q. 컨테이너를 내리지 않고 대역을 바꿀 수 있나요?

새 네트워크를 만들어 docker network connect로 붙이고 기존 네트워크를 disconnect하는 방법은 있습니다. 다만 컨테이너 IP가 바뀌므로 그 IP로 맺어져 있던 연결은 끊기고, Compose가 관리하는 네트워크라면 다음 docker compose up 때 원래 설정으로 돌아갑니다. 결국 Compose 파일과 daemon.json을 고친 뒤 짧은 재시작 시간을 잡는 편이 깔끔합니다.

Q. Docker Desktop에서도 같은 설정이 되나요?

설정 > Docker Engine 화면에서 같은 JSON을 편집할 수 있습니다. 다만 Docker Desktop의 컨테이너는 가상 머신 안에서 돌아가서 호스트 경로와 직접 겹치는 일은 리눅스보다 드뭅니다. Docker Desktop이 내부적으로 쓰는 대역 자체가 사내망과 겹친다면 설정 > Resources > Network의 Docker subnet 항목을 확인합니다.


참고 자료