Document the default address pool for local networks

[trapier]

Problem description

The default pool for docker swarm init --default-addr-pool is covered in the swarm documentation:

By default Docker Swarm uses a default address pool 10.0.0.0/8 for global scope (overlay) networks. Every network that does not have a subnet specified will have a subnet sequentially allocated from this pool. In some circumstances it may be desirable to use a different default IP address pool for networks.

Ref: https://docs.docker.com/engine/swarm/swarm-mode/#configuring-default-address-pools

The analogous default for local networks (dockerd --default-address-pool) is not currently represented in the documentation. The defaults are as follows (including swarm global networks as well for reference):

Type	Default Size	Default Pool
global	/24	10.0.0.0/8
local	/16	172.17.0.0/12
local*	/20	192.168.0.0/16

• Local networks are allocated from 172.17.0.0/12, and then 192.168.0.0/16 once 172.17.0.0/12 is exhausted.

Problem location

Filing this in docker.github.io, but it might be best to address by adding a section to https://github.com/docker/cli/blob/master/docs/reference/commandline/dockerd.md.

Project version(s) affected

dockerd --default-address-pool was released with server 18.06 (moby/moby#36396).

Suggestions for a fix

Note the "default" default address pool via a new section on https://github.com/docker/cli/blob/master/docs/reference/commandline/dockerd.md. Adding a section might also present the opportunity to document the CLI syntax:

As [cli] flag (singular)

dockerd --default-address-pool base=10.10.0.0/16,size=24

In daemon.json (plural):

{"default-address-pools":[{"base":"172.80.0.0/16","size":24},{"base":"172.90.0.0/16","size":24}]}

Ref: moby/moby#36396 (comment)

[trapier]

Thanks to @bluikko for pointing out this gap in documentation! moby/moby#29376 (comment)

[ulidtko]

3 years past — and the chances to find the actual default values, this table, are much better on StackOverflow than on https://docs.docker.com 👎

Scope	Default Size	Default Pool	Note
global	/24	10.0.0.0/8	256 size-/24 subnets, i.e. 10.0.[0-255].0/24
local	/16	172.17.0.0/16	1 subnet
local	/16	172.18.0.0/16	1 subnet
local	/16	172.19.0.0/16	1 subnet
local	/16	172.20.0.0/16	1 subnet
local	/16	172.24.0.0/14	4 subnets: 172.{24,25,26,27}.0.0/16
local	/16	172.28.0.0/14	4 subnets: 172.{28,29,30,31}.0.0/16
local*	/20	192.168.0.0/16	16 subnets: 192.168.{0,16,32,64,80,…,240}.0/20

Source: ipamutils/utils.go in docker/libnetwork

[bluikko]

The persistent problem with Docker documentation: seems to be geared towards explaining basics of things for for beginners (or developers not familiar with networking/server administration) and very thin on actual details. Basically it's developers trying to be sysadmins and failing. Results of throwing away decades of system administration experience in the name of "devops".

[bahag-schlachterk]

warning this comment may contain sarcasm
ah wait, there is a solution to shortage on IPv4-Addresses, its called IPv6 and was originally already specified back in 1998.
However as noted by @bluikko: DevOps is sometimes "developers playing Sysadmin and failing" and therefore with the new shiny world of docker and docker swarm we still rely on IPv4, NAT, Masquerading, Portforwarding and all the hell of IPv4 in use today.
See also: moby/moby#32850
So I don't even dare to dream that docker swarm is going to support IPv6 by any (documented) means soon.
end of sarcasm

[docker-robott]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[ulidtko]

@docker-robot no, stop. That people aren't screaming about an issue, doesn't make the issue disappear.

/remove-lifecycle stale

[candlerb]

Erm, something weird here: 172.17.0.0/12 cannot be a valid pool, because the prefix length conflicts with the prefix.

  172       17       0        0
10101100 00010001 00000000 00000000
<-----------><-------------------->
   12 bits       remainder should
   prefix          all be zero

• 172.16.0.0/12 would be valid (this is the entire range of class B blocks defined in RFC1918). With an allocation size of 16, this would allow up to 16 networks to be allocated: 172.16.0.0/16 to 172.31.0.0/16
• 172.17.0.0/16 would be valid - but it only contains a single /16.
• But 172.17.0.0/12 cannot be right

[bahag-schlachterk]

@candlerb: Right! Thanks for spotting this one.
As far as my experience goes your first proposal is the right one for the documentation.

[ulidtko]

Hey @candlerb, you're right.

Just drilled into the source — found this definition:

	localScopeDefaultNetworks            = []*NetworkToSplit{
		{"172.17.0.0/16", 16}, {"172.18.0.0/16", 16}, {"172.19.0.0/16", 16},
		{"172.20.0.0/14", 16}, {"172.24.0.0/14", 16}, {"172.28.0.0/14", 16},
		{"192.168.0.0/16", 20}}
	globalScopeDefaultNetworks = []*NetworkToSplit{{"10.0.0.0/8", 24}}

Applies at least to docker v20.10.12 and likely many more (but probably not all) versions. Verify via the docker/libnetwork commit link in vendor.conf.

I'm updating the table above. Thanks for noting!

@trapier you may want to update the head post as well 🙏

[docker-robott]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[candlerb]

@ulidtko: the table you have provided here still has errors AFAICS.

• one row says "172.20.0.0/16 | 1 subnet" but clearly it's 172.20.0.0/14 (4 subnets) from the source code you quoted.
• the global pool, 10.0.0.0/8 with /24 subnets, would give you 65,536 /24-sized subnets (10.0.0.0/24 to 10.255.255.0/24), unless there's some other constraint that stops allocation beyond 10.0.255.0/24