Describe default-address-pools, and --subnet prefix-len option

Signed-off-by: Rob Murray <[email protected]>

Author: robmry

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
 

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