diff --git a/libnetwork/controller.go b/libnetwork/controller.go index be9b726a28..c1aa6bb9e1 100644 --- a/libnetwork/controller.go +++ b/libnetwork/controller.go @@ -121,7 +121,8 @@ type driverData struct { } type ipamData struct { - driver ipamapi.Ipam + driver ipamapi.Ipam + capability *ipamapi.Capability // default address spaces are provided by ipam driver at registration time defaultLocalAddressSpace, defaultGlobalAddressSpace string } @@ -306,7 +307,7 @@ func (c *controller) RegisterDriver(networkType string, driver driverapi.Driver, return nil } -func (c *controller) RegisterIpamDriver(name string, driver ipamapi.Ipam) error { +func (c *controller) registerIpamDriver(name string, driver ipamapi.Ipam, caps *ipamapi.Capability) error { if !config.IsValidName(name) { return ErrInvalidName(name) } @@ -322,7 +323,7 @@ func (c *controller) RegisterIpamDriver(name string, driver ipamapi.Ipam) error return types.InternalErrorf("ipam driver %q failed to return default address spaces: %v", name, err) } c.Lock() - c.ipamDrivers[name] = &ipamData{driver: driver, defaultLocalAddressSpace: locAS, defaultGlobalAddressSpace: glbAS} + c.ipamDrivers[name] = &ipamData{driver: driver, defaultLocalAddressSpace: locAS, defaultGlobalAddressSpace: glbAS, capability: caps} c.Unlock() log.Debugf("Registering ipam driver: %q", name) @@ -330,6 +331,14 @@ func (c *controller) RegisterIpamDriver(name string, driver ipamapi.Ipam) error return nil } +func (c *controller) RegisterIpamDriver(name string, driver ipamapi.Ipam) error { + return c.registerIpamDriver(name, driver, &ipamapi.Capability{}) +} + +func (c *controller) RegisterIpamDriverWithCapabilities(name string, driver ipamapi.Ipam, caps *ipamapi.Capability) error { + return c.registerIpamDriver(name, driver, caps) +} + // NewNetwork creates a new network of the specified network type. The options // are network specific and modeled in a generic way. func (c *controller) NewNetwork(networkType, name string, options ...NetworkOption) (Network, error) { diff --git a/libnetwork/docs/ipam.md b/libnetwork/docs/ipam.md index e0b74f0c66..d66e5fc0f1 100644 --- a/libnetwork/docs/ipam.md +++ b/libnetwork/docs/ipam.md @@ -15,7 +15,7 @@ Communication protocol is the same as the remote network driver. ## Handshake -During driver registration, libnetwork will query the remote driver about the default local and global address spaces strings. +During driver registration, libnetwork will query the remote driver about the default local and global address spaces strings, and about the driver capabilities. More detailed information can be found in the respective section in this document. ## Datastore Requirements @@ -249,3 +249,27 @@ Where: * `PoolID` is the pool identifier * `Address` is the IP address to release + + +### GetCapabilities + +During the driver registration, libnetwork will query the driver about its capabilities. It is not mandatory for the driver to support this URL endpoint. If driver does not support it, registration will succeed with empty capabilities automatically added to the internal driver handle. + +During registration, the remote driver will receive a POST message to the URL `/IpamDriver.GetCapabilities` with no payload. The driver's response should have the form: + + + { + "RequiresMACAddress": bool + } + + + +## Capabilities + +Capabilities are requirements, features the remote ipam driver can express during registration with libnetwork. +As of now libnetwork accepts the following capabilities: + +### RequiresMACAddress + +It is a boolean value which tells libnetwork whether the ipam driver needs to know the interface MAC address in order to properly process the `RequestAddress()` call. +If true, on `CreateEndpoint()` request, libnetwork will generate a random MAC address for the endpoint (if an explicit MAC address was not already provided by the user) and pass it to `RequestAddress()` when requesting the IP address inside the options map. The key will be the `netlabel.MacAddress` constant: `"com.docker.network.endpoint.macaddress"`. \ No newline at end of file diff --git a/libnetwork/endpoint.go b/libnetwork/endpoint.go index 524287fc8f..d5f38c51a2 100644 --- a/libnetwork/endpoint.go +++ b/libnetwork/endpoint.go @@ -748,11 +748,8 @@ func (ep *endpoint) DataScope() string { return ep.getNetwork().DataScope() } -func (ep *endpoint) assignAddress(assignIPv4, assignIPv6 bool) error { - var ( - ipam ipamapi.Ipam - err error - ) +func (ep *endpoint) assignAddress(ipam ipamapi.Ipam, assignIPv4, assignIPv6 bool) error { + var err error n := ep.getNetwork() if n.Type() == "host" || n.Type() == "null" { @@ -761,11 +758,6 @@ func (ep *endpoint) assignAddress(assignIPv4, assignIPv6 bool) error { log.Debugf("Assigning addresses for endpoint %s's interface on network %s", ep.Name(), n.Name()) - ipam, err = n.getController().getIpamDriver(n.ipamType) - if err != nil { - return err - } - if assignIPv4 { if err = ep.assignAddressVersion(4, ipam); err != nil { return err diff --git a/libnetwork/ipamapi/contract.go b/libnetwork/ipamapi/contract.go index 5323c4f7df..5d561d81df 100644 --- a/libnetwork/ipamapi/contract.go +++ b/libnetwork/ipamapi/contract.go @@ -22,8 +22,10 @@ const ( // Callback provides a Callback interface for registering an IPAM instance into LibNetwork type Callback interface { - // RegisterDriver provides a way for Remote drivers to dynamically register new NetworkType and associate with a ipam instance + // RegisterIpamDriver provides a way for Remote drivers to dynamically register with libnetwork RegisterIpamDriver(name string, driver Ipam) error + // RegisterIpamDriverWithCapabilities provides a way for Remote drivers to dynamically register with libnetwork and specify cpaabilities + RegisterIpamDriverWithCapabilities(name string, driver Ipam, capability *Capability) error } /************** @@ -70,3 +72,8 @@ type Ipam interface { // Release the address from the specified pool ID ReleaseAddress(string, net.IP) error } + +// Capability represents the requirements and capabilities of the IPAM driver +type Capability struct { + RequiresMACAddress bool +} diff --git a/libnetwork/ipams/remote/api/api.go b/libnetwork/ipams/remote/api/api.go index b8d21fdc6b..e357630cbb 100644 --- a/libnetwork/ipams/remote/api/api.go +++ b/libnetwork/ipams/remote/api/api.go @@ -2,6 +2,8 @@ // messages between libnetwork and the remote ipam plugin package api +import "github.com/docker/libnetwork/ipamapi" + // Response is the basic response structure used in all responses type Response struct { Error string @@ -17,6 +19,17 @@ func (r *Response) GetError() string { return r.Error } +// GetCapabilityResponse is the response of GetCapability request +type GetCapabilityResponse struct { + Response + RequiresMACAddress bool +} + +// ToCapability converts the capability response into the internal ipam driver capaility structure +func (capRes GetCapabilityResponse) ToCapability() *ipamapi.Capability { + return &ipamapi.Capability{RequiresMACAddress: capRes.RequiresMACAddress} +} + // GetAddressSpacesResponse is the response to the ``get default address spaces`` request message type GetAddressSpacesResponse struct { Response diff --git a/libnetwork/ipams/remote/remote.go b/libnetwork/ipams/remote/remote.go index 3aefd430ab..581a9c8871 100644 --- a/libnetwork/ipams/remote/remote.go +++ b/libnetwork/ipams/remote/remote.go @@ -30,8 +30,17 @@ func newAllocator(name string, client *plugins.Client) ipamapi.Ipam { // Init registers a remote ipam when its plugin is activated func Init(cb ipamapi.Callback, l, g interface{}) error { plugins.Handle(ipamapi.PluginEndpointType, func(name string, client *plugins.Client) { - if err := cb.RegisterIpamDriver(name, newAllocator(name, client)); err != nil { - log.Errorf("error registering remote ipam %s due to %v", name, err) + a := newAllocator(name, client) + if cps, err := a.(*allocator).getCapabilities(); err == nil { + if err := cb.RegisterIpamDriverWithCapabilities(name, a, cps); err != nil { + log.Errorf("error registering remote ipam driver %s due to %v", name, err) + } + } else { + log.Infof("remote ipam driver %s does not support capabilities", name) + log.Debug(err) + if err := cb.RegisterIpamDriver(name, a); err != nil { + log.Errorf("error registering remote ipam driver %s due to %v", name, err) + } } }) return nil @@ -49,6 +58,14 @@ func (a *allocator) call(methodName string, arg interface{}, retVal PluginRespon return nil } +func (a *allocator) getCapabilities() (*ipamapi.Capability, error) { + var res api.GetCapabilityResponse + if err := a.call("GetCapabilities", nil, &res); err != nil { + return nil, err + } + return res.ToCapability(), nil +} + // GetDefaultAddressSpaces returns the local and global default address spaces func (a *allocator) GetDefaultAddressSpaces() (string, string, error) { res := &api.GetAddressSpacesResponse{} diff --git a/libnetwork/ipams/remote/remote_test.go b/libnetwork/ipams/remote/remote_test.go index 06dc32fc02..f30b459bcd 100644 --- a/libnetwork/ipams/remote/remote_test.go +++ b/libnetwork/ipams/remote/remote_test.go @@ -61,6 +61,53 @@ func setupPlugin(t *testing.T, name string, mux *http.ServeMux) func() { } } +func TestGetCapabilities(t *testing.T) { + var plugin = "test-ipam-driver-capabilities" + + mux := http.NewServeMux() + defer setupPlugin(t, plugin, mux)() + + handle(t, mux, "GetCapabilities", func(msg map[string]interface{}) interface{} { + return map[string]interface{}{ + "RequiresMACAddress": true, + } + }) + + p, err := plugins.Get(plugin, ipamapi.PluginEndpointType) + if err != nil { + t.Fatal(err) + } + + d := newAllocator(plugin, p.Client) + + caps, err := d.(*allocator).getCapabilities() + if err != nil { + t.Fatal(err) + } + + if !caps.RequiresMACAddress { + t.Fatalf("Unexpected capability: %v", caps) + } +} + +func TestGetCapabilitiesFromLegacyDriver(t *testing.T) { + var plugin = "test-ipam-legacy-driver" + + mux := http.NewServeMux() + defer setupPlugin(t, plugin, mux)() + + p, err := plugins.Get(plugin, ipamapi.PluginEndpointType) + if err != nil { + t.Fatal(err) + } + + d := newAllocator(plugin, p.Client) + + if _, err := d.(*allocator).getCapabilities(); err == nil { + t.Fatalf("Expected error, but got Success %v", err) + } +} + func TestGetDefaultAddressSpaces(t *testing.T) { var plugin = "test-ipam-driver-addr-spaces" diff --git a/libnetwork/libnetwork_internal_test.go b/libnetwork/libnetwork_internal_test.go index 7eb259f258..c504c4c478 100644 --- a/libnetwork/libnetwork_internal_test.go +++ b/libnetwork/libnetwork_internal_test.go @@ -34,6 +34,30 @@ func TestDriverRegistration(t *testing.T) { } } +func TestIpamDriverRegistration(t *testing.T) { + c, err := New() + if err != nil { + t.Fatal(err) + } + defer c.Stop() + + err = c.(*controller).RegisterIpamDriver("", nil) + if err == nil { + t.Fatalf("Expected failure, but suceeded") + } + if _, ok := err.(types.BadRequestError); !ok { + t.Fatalf("Failed for unexpected reason: %v", err) + } + + err = c.(*controller).RegisterIpamDriver(ipamapi.DefaultIPAM, nil) + if err == nil { + t.Fatalf("Expected failure, but suceeded") + } + if _, ok := err.(types.ForbiddenError); !ok { + t.Fatalf("Failed for unexpected reason: %v", err) + } +} + func TestNetworkMarshalling(t *testing.T) { n := &network{ name: "Miao", diff --git a/libnetwork/network.go b/libnetwork/network.go index be4ab70505..95460c4bd6 100644 --- a/libnetwork/network.go +++ b/libnetwork/network.go @@ -16,6 +16,7 @@ import ( "github.com/docker/libnetwork/etchosts" "github.com/docker/libnetwork/ipamapi" "github.com/docker/libnetwork/netlabel" + "github.com/docker/libnetwork/netutils" "github.com/docker/libnetwork/options" "github.com/docker/libnetwork/types" ) @@ -678,7 +679,22 @@ func (n *network) CreateEndpoint(name string, options ...EndpointOption) (Endpoi } } - if err = ep.assignAddress(true, !n.postIPv6); err != nil { + ipam, err := n.getController().getIPAM(n.ipamType) + if err != nil { + return nil, err + } + + if ipam.capability.RequiresMACAddress { + if ep.iface.mac == nil { + ep.iface.mac = netutils.GenerateRandomMAC() + } + if ep.ipamOptions == nil { + ep.ipamOptions = make(map[string]string) + } + ep.ipamOptions[netlabel.MacAddress] = ep.iface.mac.String() + } + + if err = ep.assignAddress(ipam.driver, true, !n.postIPv6); err != nil { return nil, err } defer func() { @@ -698,7 +714,7 @@ func (n *network) CreateEndpoint(name string, options ...EndpointOption) (Endpoi } }() - if err = ep.assignAddress(false, n.postIPv6); err != nil { + if err = ep.assignAddress(ipam.driver, false, n.postIPv6); err != nil { return nil, err }