Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 11 additions & 26 deletions content/manuals/engine/daemon/ipv6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
]
}
Expand All @@ -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

Expand Down
81 changes: 81 additions & 0 deletions content/manuals/engine/network/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
]
}
```
Comment on lines +192 to +204
Copy link
Contributor

@dvdksn dvdksn Oct 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

now we show the default configuration in both content/manuals/engine/daemon/ipv6.md and here. Maybe to avoid drift/duplication we can just have one section in this doc (or the ipv6 one, wherever it is more appropriate) where we show the default config, and cross-reference as needed. Wdyt?

Copy link
Contributor Author

@robmry robmry Oct 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, updated.


- `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
Expand Down