github.com/kaisenlinux/docker.io@v0.0.0-20230510090727-ea55db55fac7/libnetwork/ipamapi/contract.go (about)

     1  // Package ipamapi specifies the contract the IPAM service (built-in or remote) needs to satisfy.
     2  package ipamapi
     3  
     4  import (
     5  	"net"
     6  
     7  	"github.com/docker/docker/pkg/plugingetter"
     8  	"github.com/docker/libnetwork/discoverapi"
     9  	"github.com/docker/libnetwork/types"
    10  )
    11  
    12  /********************
    13   * IPAM plugin types
    14   ********************/
    15  
    16  const (
    17  	// DefaultIPAM is the name of the built-in default ipam driver
    18  	DefaultIPAM = "default"
    19  	// NullIPAM is the name of the built-in null ipam driver
    20  	NullIPAM = "null"
    21  	// PluginEndpointType represents the Endpoint Type used by Plugin system
    22  	PluginEndpointType = "IpamDriver"
    23  	// RequestAddressType represents the Address Type used when requesting an address
    24  	RequestAddressType = "RequestAddressType"
    25  )
    26  
    27  // Callback provides a Callback interface for registering an IPAM instance into LibNetwork
    28  type Callback interface {
    29  	// GetPluginGetter returns the pluginv2 getter.
    30  	GetPluginGetter() plugingetter.PluginGetter
    31  	// RegisterIpamDriver provides a way for Remote drivers to dynamically register with libnetwork
    32  	RegisterIpamDriver(name string, driver Ipam) error
    33  	// RegisterIpamDriverWithCapabilities provides a way for Remote drivers to dynamically register with libnetwork and specify capabilities
    34  	RegisterIpamDriverWithCapabilities(name string, driver Ipam, capability *Capability) error
    35  }
    36  
    37  /**************
    38   * IPAM Errors
    39   **************/
    40  
    41  // Well-known errors returned by IPAM
    42  var (
    43  	ErrIpamInternalError   = types.InternalErrorf("IPAM Internal Error")
    44  	ErrInvalidAddressSpace = types.BadRequestErrorf("Invalid Address Space")
    45  	ErrInvalidPool         = types.BadRequestErrorf("Invalid Address Pool")
    46  	ErrInvalidSubPool      = types.BadRequestErrorf("Invalid Address SubPool")
    47  	ErrInvalidRequest      = types.BadRequestErrorf("Invalid Request")
    48  	ErrPoolNotFound        = types.BadRequestErrorf("Address Pool not found")
    49  	ErrOverlapPool         = types.ForbiddenErrorf("Address pool overlaps with existing pool on this address space")
    50  	ErrNoAvailablePool     = types.NoServiceErrorf("No available pool")
    51  	ErrNoAvailableIPs      = types.NoServiceErrorf("No available addresses on this pool")
    52  	ErrNoIPReturned        = types.NoServiceErrorf("No address returned")
    53  	ErrIPAlreadyAllocated  = types.ForbiddenErrorf("Address already in use")
    54  	ErrIPOutOfRange        = types.BadRequestErrorf("Requested address is out of range")
    55  	ErrPoolOverlap         = types.ForbiddenErrorf("Pool overlaps with other one on this address space")
    56  	ErrBadPool             = types.BadRequestErrorf("Address space does not contain specified address pool")
    57  )
    58  
    59  /*******************************
    60   * IPAM Service Interface
    61   *******************************/
    62  
    63  // Ipam represents the interface the IPAM service plugins must implement
    64  // in order to allow injection/modification of IPAM database.
    65  type Ipam interface {
    66  	discoverapi.Discover
    67  
    68  	// GetDefaultAddressSpaces returns the default local and global address spaces for this ipam
    69  	GetDefaultAddressSpaces() (string, string, error)
    70  	// RequestPool returns an address pool along with its unique id. Address space is a mandatory field
    71  	// which denotes a set of non-overlapping pools. pool describes the pool of addresses in CIDR notation.
    72  	// subpool indicates a smaller range of addresses from the pool, for now it is specified in CIDR notation.
    73  	// Both pool and subpool are non mandatory fields. When they are not specified, Ipam driver may choose to
    74  	// return a self chosen pool for this request. In such case the v6 flag needs to be set appropriately so
    75  	// that the driver would return the expected ip version pool.
    76  	RequestPool(addressSpace, pool, subPool string, options map[string]string, v6 bool) (string, *net.IPNet, map[string]string, error)
    77  	// ReleasePool releases the address pool identified by the passed id
    78  	ReleasePool(poolID string) error
    79  	// Request address from the specified pool ID. Input options or required IP can be passed.
    80  	RequestAddress(string, net.IP, map[string]string) (*net.IPNet, map[string]string, error)
    81  	// Release the address from the specified pool ID
    82  	ReleaseAddress(string, net.IP) error
    83  
    84  	//IsBuiltIn returns true if it is a built-in driver.
    85  	IsBuiltIn() bool
    86  }
    87  
    88  // Capability represents the requirements and capabilities of the IPAM driver
    89  type Capability struct {
    90  	// Whether on address request, libnetwork must
    91  	// specify the endpoint MAC address
    92  	RequiresMACAddress bool
    93  	// Whether of daemon start, libnetwork must replay the pool
    94  	// request and the address request for current local networks
    95  	RequiresRequestReplay bool
    96  }