Merge pull request moby#50917 from corhere/ipam-allocation-info-localscope

api, daemon: report IPAM status for local-scope networks

Author: corhere

api/swagger.yaml

@@ -2574,6 +2574,21 @@ definitions:
             type: ServiceInfo
             hints:
               nullable: false
+      Status:
+        description: >
+          provides runtime information about the network
+          such as the number of allocated IPs.
+        $ref: "#/definitions/NetworkStatus"
+
+  NetworkStatus:
+    description: >
+      provides runtime information about the network
+      such as the number of allocated IPs.
+    type: "object"
+    x-go-name: Status
+    properties:
+      IPAM:
+        $ref: "#/definitions/IPAMStatus"
 
   ServiceInfo:
     x-nullable: false
@@ -2685,6 +2700,46 @@ definitions:
         additionalProperties:
           type: "string"
 
+  IPAMStatus:
+    type: "object"
+    x-nullable: false
+    x-omitempty: false
+    properties:
+      Subnets:
+        type: "object"
+        additionalProperties:
+          $ref: "#/definitions/SubnetStatus"
+        example:
+          "172.16.0.0/16":
+            IPsInUse: 3
+            DynamicIPsAvailable: 65533
+          "2001:db8:abcd:0012::0/96":
+            IPsInUse: 5
+            DynamicIPsAvailable: 4294967291
+        x-go-type:
+          type: SubnetStatuses
+          kind: map
+
+  SubnetStatus:
+    type: "object"
+    x-nullable: false
+    x-omitempty: false
+    properties:
+      IPsInUse:
+        description: >
+          Number of IP addresses in the subnet that are in use or reserved and
+          are therefore unavailable for allocation, saturating at 2<sup>64</sup> - 1.
+        type: integer
+        format: uint64
+        x-omitempty: false
+      DynamicIPsAvailable:
+        description: >
+          Number of IP addresses within the network's IPRange for the subnet
+          that are available for allocation, saturating at 2<sup>64</sup> - 1.
+        type: integer
+        format: uint64
+        x-omitempty: false
+
   EndpointResource:
     type: "object"
     description: >

api/types/network/inspect.go

@@ -22,6 +22,8 @@ type IPAMConfig struct {
 	AuxAddress map[string]string `json:"AuxiliaryAddresses,omitempty"`
 }
 
+type SubnetStatuses = map[netip.Prefix]SubnetStatus
+
 type ipFamily string
 
 const (

api/types/network/ipam.go

@@ -0,0 +1,75 @@
+package uint128
+
+import (
+	"encoding/binary"
+	"math/bits"
+)
+
+type Uint128 struct{ hi, lo uint64 }
+
+func From16(b [16]byte) Uint128 {
+	return Uint128{
+		hi: binary.BigEndian.Uint64(b[:8]),
+		lo: binary.BigEndian.Uint64(b[8:]),
+	}
+}
+
+func From(x, y uint64) Uint128 {
+	return Uint128{hi: x, lo: y}
+}
+
+func (x Uint128) Add(y Uint128) Uint128 {
+	lo, carry := bits.Add64(x.lo, y.lo, 0)
+	hi, _ := bits.Add64(x.hi, y.hi, carry)
+	return Uint128{hi: hi, lo: lo}
+}
+
+func (x Uint128) Sub(y Uint128) Uint128 {
+	lo, carry := bits.Sub64(x.lo, y.lo, 0)
+	hi, _ := bits.Sub64(x.hi, y.hi, carry)
+	return Uint128{hi: hi, lo: lo}
+}
+
+func (x Uint128) Lsh(n uint) Uint128 {
+	if n > 64 {
+		return Uint128{hi: x.lo << (n - 64)}
+	}
+	return Uint128{
+		hi: x.hi<<n | x.lo>>(64-n),
+		lo: x.lo << n,
+	}
+}
+
+func (x Uint128) Rsh(n uint) Uint128 {
+	if n > 64 {
+		return Uint128{lo: x.hi >> (n - 64)}
+	}
+	return Uint128{
+		hi: x.hi >> n,
+		lo: x.lo>>n | x.hi<<(64-n),
+	}
+}
+
+func (x Uint128) And(y Uint128) Uint128 {
+	return Uint128{hi: x.hi & y.hi, lo: x.lo & y.lo}
+}
+
+func (x Uint128) Not() Uint128 {
+	return Uint128{hi: ^x.hi, lo: ^x.lo}
+}
+
+func (x Uint128) Fill16(a *[16]byte) {
+	binary.BigEndian.PutUint64(a[:8], x.hi)
+	binary.BigEndian.PutUint64(a[8:], x.lo)
+}
+
+func (x Uint128) Uint64() uint64 {
+	return x.lo
+}
+
+func (x Uint128) Uint64Sat() uint64 {
+	if x.hi != 0 {
+		return ^uint64(0)
+	}
+	return x.lo
+}

api/types/network/ipam_status.go

@@ -5,6 +5,7 @@ import (
 	"net"
 	"net/netip"
 
+	"github.com/moby/moby/api/types/network"
 	"github.com/moby/moby/v2/daemon/libnetwork/types"
 )
 
@@ -57,6 +58,12 @@ type Ipam interface {
 	IsBuiltIn() bool
 }
 
+type PoolStatuser interface {
+	Ipam
+	// Status returns the operational status of the specified IPAM pool.
+	PoolStatus(poolID string) (network.SubnetStatus, error)
+}
+
 type PoolRequest struct {
 	// AddressSpace is a mandatory field which denotes which block of pools
 	// should be used to make the allocation. This value is opaque, and only

api/types/network/status.go

@@ -7,7 +7,9 @@ import (
 	"sync"
 
 	"github.com/containerd/log"
+	"github.com/moby/moby/api/types/network"
 	"github.com/moby/moby/v2/daemon/libnetwork/internal/netiputil"
+	"github.com/moby/moby/v2/daemon/libnetwork/internal/uint128"
 	"github.com/moby/moby/v2/daemon/libnetwork/ipamapi"
 	"github.com/moby/moby/v2/daemon/libnetwork/ipamutils"
 	"github.com/moby/moby/v2/daemon/libnetwork/ipbits"
@@ -369,3 +371,24 @@ func (aSpace *addrSpace) releaseAddress(nw, sub netip.Prefix, address netip.Addr
 
 	return p.addrs.Remove(address)
 }
+
+func (aSpace *addrSpace) allocationStatus(nw, ipr netip.Prefix) (network.SubnetStatus, error) {
+	aSpace.mu.Lock()
+	defer aSpace.mu.Unlock()
+
+	if ipr == (netip.Prefix{}) {
+		ipr = nw
+	}
+	p, ok := aSpace.subnets[nw]
+	if !ok {
+		return network.SubnetStatus{}, types.NotFoundErrorf("cannot find address pool for %v", nw)
+	}
+
+	iprcap := uint128.From(0, 1).Lsh(uint(ipr.Addr().BitLen() - ipr.Bits()))
+	ipralloc := uint128.From(p.addrs.AddrsInPrefix(ipr))
+
+	return network.SubnetStatus{
+		IPsInUse:            uint128.From(p.addrs.Len()).Uint64Sat(),
+		DynamicIPsAvailable: iprcap.Sub(ipralloc).Uint64Sat(),
+	}, nil
+}

api/types/network/subnet_status.go

@@ -8,6 +8,7 @@ import (
 	"net/netip"
 
 	"github.com/containerd/log"
+	"github.com/moby/moby/api/types/network"
 	"github.com/moby/moby/v2/daemon/libnetwork/internal/addrset"
 	"github.com/moby/moby/v2/daemon/libnetwork/internal/netiputil"
 	"github.com/moby/moby/v2/daemon/libnetwork/ipamapi"
@@ -23,6 +24,8 @@ const (
 	globalAddressSpace = "GlobalDefault"
 )
 
+var _ ipamapi.PoolStatuser = &Allocator{}
+
 // Register registers the default ipam driver with libnetwork. It takes
 // two optional address pools respectively containing the list of user-defined
 // address pools for 'local' and 'global' address spaces.
@@ -312,6 +315,21 @@ func getAddress(base netip.Prefix, addrSet *addrset.AddrSet, prefAddress netip.A
 	return addr, nil
 }
 
+// PoolStatus returns the operational status of the specified IPAM pool.
+func (a *Allocator) PoolStatus(poolID string) (network.SubnetStatus, error) {
+	k, err := PoolIDFromString(poolID)
+	if err != nil {
+		return network.SubnetStatus{}, types.InvalidParameterErrorf("invalid pool id: %s", poolID)
+	}
+
+	aSpace, err := a.getAddrSpace(k.AddressSpace, k.Is6())
+	if err != nil {
+		return network.SubnetStatus{}, err
+	}
+
+	return aSpace.allocationStatus(k.Subnet, k.ChildSubnet)
+}
+
 // IsBuiltIn returns true for builtin drivers
 func (a *Allocator) IsBuiltIn() bool {
 	return true