Add sticky container IPs across stop/start

[vsarunas]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Currently upon a container stop/start, the IP address will always be incremented, even if there is free IP addresses available. This can sometimes cause issues with other software running inside the container where the IPs are always changing and require reconfiguration/handling.

The PR adds simple best attempt to restore the previous IP addresses allocated if the network still has available IPs, essentially giving static IPs under normal use. Upon network IP exhaustion, a starting container takes an IP from a stopped container.

Sticky

container run -d --name stick alpine sleep infinity

Will show the same IP persisted:

container list
ID     IMAGE                            OS     ARCH   STATE    IP               CPUS  MEMORY   STARTED
stick  docker.io/library/alpine:latest  linux  arm64  running  192.168.64.3/24  4     1024 MB  2026-06-17T11:24:31Z

container stop stick && container start stick

container list
ID     IMAGE                            OS     ARCH   STATE    IP               CPUS  MEMORY   STARTED
stick  docker.io/library/alpine:latest  linux  arm64  running  192.168.64.3/24  4     1024 MB  2026-06-17T11:24:51Z

Same can be done with start order, IP will be preserved:

for n in s1 s2 s3; do container run -d --name $n alpine sleep infinity; done
for n in s1 s2 s3; do container stop $n; done
for n in s3 s1 s2; do container start $n; done

Pool exhaustion and re-claim

Add a small network:

container network create --subnet 192.168.210.0/29 tiny

4 containers will be created:

for i in 1 2 3 4 5 6 7; do
  container run -d --name t$i --network tiny -m 256m alpine sleep infinity
done

Cannot allocate more once exhausted:

Error: failed to bootstrap container (cause: "internalError: "failed to bootstrap container t5 (cause: "invalidState: "network tiny (192.168.210.0/29) has no free IP addresses"")"")

The IP can be re-allocated from a stopped container on exhaustion and a new container can be now started:

container stop t1
container run -d --name t5 --network tiny -m 256m alpine sleep infinity

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

[vsarunas]

@jglogan, could you have a look?

I originally started with a mix of this and static allocation similar to #751, but this has various edge cases on verifying the IP requested against stopped and running containers, but this gives majority of the benefit.