IPAM allocation statistics¶

Networks expose a Status` field with IPAM (IP Address Management) allocation statistics that you can read from the Engine API or through the CLI with docker network inspect. The counts help you to know how full each configured subnet is before the addresses run out, especially on overlay and other networks where planning address space becomes more difficult as the environment grows.

Statistics reported¶

For each IPv4 subnet on the network, Status.IPAM.Subnets reports:

IPsInUse, the addresses that are currently allocated or reserved for the subnet, including such operational overhead as the gateway, the network address, and the broadcast address where those apply.
DynamicIPsAvailable, the number of addresses that remain available for allocation from the pool.

These values update as containers attach and detach, with allows you to monitor utilization over time and act before exhaustion.

Note

IPAM allocation statistics only apply to IPv4 subnets. IPv6 subnets are not tracked, as typically IPv6 prefix sizes, such as /64, provide such a large space that exhaustion is not a practical concern.

Inspect a network¶

Run the docker network inspect command to inspect a network.

Example, using the default bridge:

$ docker network inspect bridge

Relevant parts of the resulting JSON output:

{
    "Name": "bridge",
    "IPAM": {
        "Driver": "default",
        "Config": [
            {
                "Subnet": "172.17.0.0/16",
                "Gateway": "172.17.0.1"
            }
        ]
    },
    "Status": {
        "IPAM": {
            "Subnets": {
                "172.17.0.0/16": {
                    "IPsInUse": 3,
                    "DynamicIPsAvailable": 65533
                }
            }
        }
    }
}

In this example, the /16 has 65,536 total addresses. Three of these addresses are counted as being in use, for example gateway, reserved network, and broadcast overhead, while 65,533 remain available for dynamic allocation.