From 6085b5d3aa618c4fa082e9fbfea824731631b5ee Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Tue, 30 Jan 2018 15:41:53 -0800 Subject: [PATCH] Doc guidance to only use 256 IPs per overlay Signed-off-by: Misty Stanley-Jones --- docs/reference/commandline/network_create.md | 25 +++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md index ae8da1d59b..5717231036 100644 --- a/docs/reference/commandline/network_create.md +++ b/docs/reference/commandline/network_create.md @@ -92,6 +92,18 @@ Network names must be unique. The Docker daemon attempts to identify naming conflicts but this is not guaranteed. It is the user's responsibility to avoid name conflicts. +### Overlay network limitations + +You should create overlay networks with `/24` blocks (the default), which limits +you to 256 IP addresses, when you create networks using the default VIP-based +endpoint-mode. This recommendation addresses +[limitations with swarm mode](https://github.com/moby/moby/issues/30820). If you +need more than 256 IP addresses, do not increase the IP block size. You can +either use `dnsrr` endpoint mode with an external load balancer, or use multiple +smaller overlay networks. See +[Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery) +for more information about different endpoint modes. + ## Examples ### Connect containers @@ -141,15 +153,16 @@ $ docker network create \ If you omit the `--gateway` flag the Engine selects one for you from inside a preferred pool. For `overlay` networks and for network driver plugins that -support it you can create multiple subnetworks. +support it you can create multiple subnetworks. This example uses two `/25` +subnet mask to adhere to the current guidance of not having more than 256 IPs in +a single overlay network. Each of the subnetworks has 126 usable addresses. ```bash $ docker network create -d overlay \ - --subnet=192.168.0.0/16 \ - --subnet=192.170.0.0/16 \ - --gateway=192.168.0.100 \ - --gateway=192.170.0.100 \ - --ip-range=192.168.1.0/24 \ + --subnet=192.168.1.0/25 \ + --subnet=192.170.2.0/25 \ + --gateway=192.168.1.100 \ + --gateway=192.170.2.100 \ --aux-address="my-router=192.168.1.5" --aux-address="my-switch=192.168.1.6" \ --aux-address="my-printer=192.170.1.5" --aux-address="my-nas=192.170.1.6" \ my-multihost-network