From a8d2c50697e047f5161d670a6e38df24b332c935 Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Fri, 24 Oct 2025 12:46:03 +0100 Subject: [PATCH] Describe default-address-pools, and --subnet prefix-len option Signed-off-by: Rob Murray --- content/manuals/engine/daemon/ipv6.md | 37 ++++------- content/manuals/engine/network/_index.md | 81 ++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 26 deletions(-) diff --git a/content/manuals/engine/daemon/ipv6.md b/content/manuals/engine/daemon/ipv6.md index 1ed5ca00b058..57c7dd30b1a0 100644 --- a/content/manuals/engine/daemon/ipv6.md +++ b/content/manuals/engine/daemon/ipv6.md @@ -126,42 +126,24 @@ will be used when IPv6 is enabled. These `/64` subnets include a 40-bit Global ID based on the Docker Engine's randomly generated ID, to give a high probability of uniqueness. +The built-in default address pool configuration is shown in [Subnet allocation](../network/_index.md#subnet-allocation). +It does not include any IPv6 pools. + To use different pools of IPv6 subnets for dynamic address allocation, you must manually configure address pools of the daemon to include: - The default IPv4 address pools - One or more IPv6 pools of your own -The default address pool configuration is: - -```json -{ - "default-address-pools": [ - { "base": "172.17.0.0/16", "size": 16 }, - { "base": "172.18.0.0/16", "size": 16 }, - { "base": "172.19.0.0/16", "size": 16 }, - { "base": "172.20.0.0/14", "size": 16 }, - { "base": "172.24.0.0/14", "size": 16 }, - { "base": "172.28.0.0/14", "size": 16 }, - { "base": "192.168.0.0/16", "size": 20 } - ] -} -``` - -The following example shows a valid configuration with the default values and -an IPv6 pool. The IPv6 pool in the example provides up to 256 IPv6 subnets of -size `/64`, from an IPv6 pool of prefix length `/56`. +The following example shows a valid configuration with IPv4 and IPv6 pools, +both pools provide 256 subnets. IPv4 subnets with prefix length `/24` will +be allocated from a `/16` pool. IPv6 subnets with prefix length `/64` will +be allocated from a `/56` pool. ```json { "default-address-pools": [ - { "base": "172.17.0.0/16", "size": 16 }, - { "base": "172.18.0.0/16", "size": 16 }, - { "base": "172.19.0.0/16", "size": 16 }, - { "base": "172.20.0.0/14", "size": 16 }, - { "base": "172.24.0.0/14", "size": 16 }, - { "base": "172.28.0.0/14", "size": 16 }, - { "base": "192.168.0.0/16", "size": 20 }, + { "base": "172.17.0.0/16", "size": 24 }, { "base": "2001:db8::/56", "size": 64 } ] } @@ -176,6 +158,9 @@ size `/64`, from an IPv6 pool of prefix length `/56`. > The default IPv4 pools are from the private address range, > similar to the default IPv6 [ULA][wikipedia-ipv6-ula] networks. +See [Subnet allocation](../network/_index.md#subnet-allocation) for more information about +`default-address-pools`. + [wikipedia-ipv6-reserved]: https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv6 [wikipedia-ipv6-ula]: https://en.wikipedia.org/wiki/Unique_local_address diff --git a/content/manuals/engine/network/_index.md b/content/manuals/engine/network/_index.md index 1f24cc14ea0d..5bb8369bdce0 100644 --- a/content/manuals/engine/network/_index.md +++ b/content/manuals/engine/network/_index.md @@ -172,6 +172,87 @@ You can override the hostname using `--hostname`. When connecting to an existing network using `docker network connect`, you can use the `--alias` flag to specify an additional network alias for the container on that network. +### Subnet allocation + +Docker networks can use either explicitly configured subnets or automatically allocated ones from default pools. + +#### Explicit subnet configuration + +You can specify exact subnets when creating a network: + +```console +$ docker network create --ipv6 --subnet 192.0.2.0/24 --subnet 2001:db8::/64 mynet +``` + +#### Automatic subnet allocation + +When no `--subnet` option is provided, Docker automatically selects a subnet from predefined "default address pools". +These pools can be configured in `/etc/docker/daemon.json`. Docker's built-in default is equivalent to: + +```json +{ + "default-address-pools": [ + {"base":"172.17.0.0/16","size":16}, + {"base":"172.18.0.0/16","size":16}, + {"base":"172.19.0.0/16","size":16}, + {"base":"172.20.0.0/14","size":16}, + {"base":"172.24.0.0/14","size":16}, + {"base":"172.28.0.0/14","size":16}, + {"base":"192.168.0.0/16","size":20} + ] +} +``` + +- `base`: The subnet that can be allocated from. +- `size`: The prefix length used for each allocated subnet. + +When an IPv6 subnet is required and there are no IPv6 addresses in `default-address-pools`, Docker allocates +subnets from a Unique Local Address (ULA) prefix. To use specific IPv6 subnets instead, add them to your +`default-address-pools`. See [Dynamic IPv6 subnet allocation](../daemon/ipv6.md#dynamic-ipv6-subnet-allocation) +for more information. + +Docker attempts to avoid address prefixes already in use on the host. However, you may need to customize +`default-address-pools` to prevent routing conflicts in some network environments. + +The default pools use large subnets, which limits the number of networks you can create. You can divide base +subnets into smaller pools to support more networks. + +For example, this configuration allows Docker to create 256 networks from `172.17.0.0/16`. +Docker will allocate subnets `172.17.0.0/24`, `172.17.1.0/24`, and so on, up to `172.17.255.0/24`: + +```json +{ + "default-address-pools": [ + {"base": "172.17.0.0/16", "size": 24} + ] +} +``` + +You can also request a subnet with a specific prefix length from the default pools by using unspecified +addresses in the `--subnet` option: + +```console +$ docker network create --ipv6 --subnet ::/56 --subnet 0.0.0.0/24 mynet +6686a6746b17228f5052528113ddad0e6d68e2e3905d648e336b33409f2d3b64 +$ docker network inspect mynet -f '{{json .IPAM.Config}}' | jq . +[ + { + "Subnet": "172.19.0.0/24", + "Gateway": "172.19.0.1" + }, + { + "Subnet": "fdd3:6f80:972c::/56", + "Gateway": "fdd3:6f80:972c::1" + } +] +``` + +> [!NOTE] +> +> Support for unspecified addresses in `--subnet` was introduced in Docker 29.0.0. +> If Docker is downgraded to an older version, networks created in this way will become unusable. +> They can be removed and re-created, or will function again if the daemon is restored to 29.0.0 or later. + ## DNS services Containers use the same DNS servers as the host by default, but you can