Your Docker Default Pool Change Does Not Renumber Networks

Changing default-address-pools does not renumber the networks you already have, and expecting it to is how a careful plan turns into a surprise outage. The setting governs automatic allocation for networks created after the daemon restarts with the new configuration. Everything already running keeps the subnet it was given, because that subnet is part of the network's stored definition. The myth is convenient because it suggests one edit fixes every overlap, and the reality is a two-part job: choose a range that is actually free, then migrate the networks that are not.

The myth: one pool change fixes the overlap

The myth has a specific shape. Someone reads that Docker's default pool can be changed, changes it, restarts the daemon, and concludes that the container network no longer collides with the office VPN. The old network is still there, still attached, still holding the address that collides.

What changed is the allocator's future behaviour, which is genuinely useful and genuinely limited. New networks created without an explicit --subnet get carved from the new pool; existing ones were never in that pool to begin with. A restart does not rebuild networks and does not move containers between them. If the symptom persists after the change, the change was real and the diagnosis was incomplete.

Base range and allocated prefix

The configuration has two fields that are easy to confuse. base is the range the allocator carves from, and size is the prefix length of each allocated network, so a base of 10.10.0.0/16 with size 24 hands out /24s inside that /16. Getting the roles backwards produces an allocation pattern you did not intend, usually one enormous network or an exhausted pool.

A pool is a reservation, not a proof. Docker avoids conflicts it can see in the host's routing table, and it cannot see a VPN you have not connected yet.

That limitation is the whole reason to choose deliberately. The ranges to compare against are the ones the host must reach: the office LAN, the corporate VPN's internal subnets, the lab or staging prefixes, and any other container host on the same overlay. Write them down as CIDRs before you touch the daemon, because a list in your head will miss the one that matters. Then pick a base that overlaps none of them, and keep the list with the deployment so the next person does not repeat the exercise from memory.

Inventory before you choose

Inventory what exists first. docker network ls lists the networks, and docker network inspect bridge -f '{{.IPAM.Config}}' prints the subnet a specific one is using. Repeat for every user-defined network, because Compose projects create their own and an explicit --subnet in a compose file bypasses the pool entirely.

That last point is the one that survives the migration. A pool change does not stop a colleague from pinning 172.18.0.0/16 in a compose file, and the conflict returns with a different author.

Migrating what already exists

Migrating existing networks is a separate, supported operation. Each affected network has to be recreated with the new subnet, which means detaching and reattaching the containers that use it, and recreating a network removes its container attachments rather than moving them. Preserve volumes and configuration, and treat the recreation as a deployment rather than a data reset. Do the work in a maintenance window, because the containers on a recreated network restart whether or not you planned for it.

Follow the documented daemon configuration and restart procedure, and coordinate the interruption. On a host with a single daemon, systemctl restart docker restarts containers according to their restart policies, which is a behaviour worth knowing before rather than after.

Then verify the two things the change was supposed to fix. Inspect the new subnet with docker network inspect and confirm it sits inside the chosen base, then check the route to a representative VPN destination with ip route get 10.20.30.40 and confirm it goes where you expect rather than into a bridge. Test service discovery and container-to-container communication too, because a network recreated with different addressing can break name resolution in ways that look like an application bug.

What still breaks afterwards

The durable part is the record. Keep the allocation list, the chosen base and size, and the networks that were recreated in the same place as the deployment.

A range being private does not make it safe to reuse. 10.0.0.0/8 is private and also the most likely thing to already be in use somewhere on the path, which is why the answer is a specific reservation rather than a preference for one block. The Docker network documentation describes automatic subnet allocation and the pool fields. Choose the range from what you must reach, not from what looks tidy.