feat(network): support --aux-address on network create

[mayur-tolexo]

Part of #5012.
Docker's network create reserves auxiliary addresses so IPAM never hands them out to containers. nerdctl had no equivalent.

host-local has no exclude list, but it allocates across every range in a set, so each reserved IP is carved out by splitting the subnet range around it. The reserved name=IP pairs are matched to the subnet that contains them (so dual-stack picks the right family), rejected when they hit the network or gateway address or fall outside every subnet, and recorded so network inspect reports AuxiliaryAddresses the same way Docker does.

[mayur-tolexo]

Checked --aux-address against Docker 29.4.0 to make sure the behaviour and output line up. Reserved addresses show up in network inspect the same way, an aux-address that matches no subnet or lands on the network/gateway address is rejected the same way, and dual-stack keeps each family's aux-address on the right subnet.

Docker:

$ docker network create --subnet 10.50.0.0/24 --aux-address host1=10.50.0.5 --aux-address host2=10.50.0.6 auxnet
$ docker network inspect auxnet --format '{{json .IPAM.Config}}'
[{"Subnet":"10.50.0.0/24","Gateway":"10.50.0.1","AuxiliaryAddresses":{"host1":"10.50.0.5","host2":"10.50.0.6"}}]

$ docker network create --subnet 10.51.0.0/24 --aux-address bad=192.168.9.9 badnet
no matching subnet for aux-address 192.168.9.9

$ docker network create --subnet 10.52.0.0/24 --gateway 10.52.0.1 --aux-address g=10.52.0.1 gwnet
Error response from daemon: failed to allocate secondary ip address (g:10.52.0.1): Address already in use

$ docker network create --ipv6 --subnet 10.55.0.0/24 --aux-address v4=10.55.0.9 --subnet fd00:55::/64 --aux-address v6=fd00:55::9 dualaux
$ docker network inspect dualaux --format '{{json .IPAM.Config}}'
[{"Subnet":"10.55.0.0/24","Gateway":"10.55.0.1","AuxiliaryAddresses":{"v4":"10.55.0.9"}},{"Subnet":"fd00:55::/64","Gateway":"fd00:55::1","AuxiliaryAddresses":{"v6":"fd00:55::9"}}]

nerdctl with this PR:

$ nerdctl network create --subnet 10.50.0.0/24 --aux-address host1=10.50.0.5 --aux-address host2=10.50.0.6 auxnet
$ nerdctl network inspect auxnet --format '{{json .IPAM.Config}}'
[{"Subnet":"10.50.0.0/24","Gateway":"10.50.0.1","AuxiliaryAddresses":{"host1":"10.50.0.5","host2":"10.50.0.6"}}]

$ nerdctl network create --subnet 10.51.0.0/24 --aux-address bad=192.168.9.9 badnet
level=fatal msg="no matching subnet for aux-address 192.168.9.9"

$ nerdctl network create --subnet 10.52.0.0/24 --gateway 10.52.0.1 --aux-address g=10.52.0.1 gwnet
level=fatal msg="failed to allocate secondary ip address (g:10.52.0.1): Address already in use"

$ nerdctl network create --ipv6 --subnet 10.55.0.0/24 --aux-address v4=10.55.0.9 --subnet fd00:55::/64 --aux-address v6=fd00:55::9 dualaux
$ nerdctl network inspect dualaux --format '{{json .IPAM.Config}}'
[{"Subnet":"10.55.0.0/24","Gateway":"10.55.0.1","AuxiliaryAddresses":{"v4":"10.55.0.9"}},{"Subnet":"fd00:55::/64","Gateway":"fd00:55::1","AuxiliaryAddresses":{"v6":"fd00:55::9"}}]

host-local has no exclude list, so the reservation is enforced by splitting the range around each reserved IP; those addresses are then never handed out. With --aux-address host1=10.50.0.5 --aux-address host2=10.50.0.9 the generated host-local ranges skip .5 and .9:

rangeStart 10.50.0.1   rangeEnd 10.50.0.4
rangeStart 10.50.0.6   rangeEnd 10.50.0.8
rangeStart 10.50.0.10  rangeEnd 10.50.0.254

[mayur-tolexo]

cc @AkihiroSuda — rebased on latest main and green, could you take a look when you get a chance?

[AkihiroSuda]

Doesn't seem implemented in CNI
https://github.com/containernetworking/plugins/blob/v1.9.1/plugins/ipam/host-local/backend/allocator/config.go#L68

nerdctl-specific information could be stored in NerdctlLabels
https://github.com/search?q=repo%3Acontainerd%2Fnerdctl+NerdctlLabels&type=code

[AkihiroSuda]

Found a similar bug

• nerdctl network create --ip-range injects a non-existent property ipRange to CNI IPAM config #5068

[AkihiroSuda]

#5041 (comment)