spec/plugins: return interface details and multiple IP addresses to runtime

Updates the spec and plugins to return an array of interfaces and IP details
to the runtime including:

- interface names and MAC addresses configured by the plugin
- whether the interfaces are sandboxed (container/VM) or host (bridge, veth, etc)
- multiple IP addresses configured by IPAM and which interface they
have been assigned to

Returning interface details is useful for runtimes, as well as allowing
more flexible chaining of CNI plugins themselves.  For example, some
meta plugins may need to know the host-side interface to be able to
apply firewall or traffic shaping rules to the container.

plugins/ipam/dhcp/daemon.go

@@ -71,11 +71,12 @@ func (d *DHCP) Allocate(args *skel.CmdArgs, result *current.Result) error {
 
 	d.setLease(args.ContainerID, conf.Name, l)
 
-	result.IP4 = &current.IPConfig{
-		IP:      *ipn,
+	result.IPs = []*current.IPConfig{{
+		Version: "4",
+		Address: *ipn,
 		Gateway: l.Gateway(),
-		Routes:  l.Routes(),
-	}
+	}}
+	result.Routes = l.Routes()
 
 	return nil
 }

plugins/ipam/dhcp/lease.go

@@ -291,7 +291,7 @@ func (l *DHCPLease) Gateway() net.IP {
 	return parseRouter(l.opts)
 }
 
-func (l *DHCPLease) Routes() []types.Route {
+func (l *DHCPLease) Routes() []*types.Route {
 	routes := parseRoutes(l.opts)
 	return append(routes, parseCIDRRoutes(l.opts)...)
 }

plugins/ipam/dhcp/main.go

@@ -21,6 +21,7 @@ import (
 	"path/filepath"
 
 	"github.com/containernetworking/cni/pkg/skel"
+	"github.com/containernetworking/cni/pkg/types"
 	"github.com/containernetworking/cni/pkg/types/current"
 	"github.com/containernetworking/cni/pkg/version"
 )
@@ -31,16 +32,24 @@ func main() {
 	if len(os.Args) > 1 && os.Args[1] == "daemon" {
 		runDaemon()
 	} else {
-		skel.PluginMain(cmdAdd, cmdDel, version.Legacy)
+		skel.PluginMain(cmdAdd, cmdDel, version.All)
 	}
 }
 
 func cmdAdd(args *skel.CmdArgs) error {
+	// Plugin must return result in same version as specified in netconf
+	versionDecoder := &version.ConfigDecoder{}
+	confVersion, err := versionDecoder.Decode(args.StdinData)
+	if err != nil {
+		return err
+	}
+
 	result := &current.Result{}
 	if err := rpcCall("DHCP.Allocate", args, result); err != nil {
 		return err
 	}
-	return result.Print()
+
+	return types.PrintResult(result, confVersion)
 }
 
 func cmdDel(args *skel.CmdArgs) error {

plugins/ipam/dhcp/options.go

@@ -40,17 +40,17 @@ func classfulSubnet(sn net.IP) net.IPNet {
 	}
 }
 
-func parseRoutes(opts dhcp4.Options) []types.Route {
+func parseRoutes(opts dhcp4.Options) []*types.Route {
 	// StaticRoutes format: pairs of:
 	// Dest = 4 bytes; Classful IP subnet
 	// Router = 4 bytes; IP address of router
 
-	routes := []types.Route{}
+	routes := []*types.Route{}
 	if opt, ok := opts[dhcp4.OptionStaticRoute]; ok {
 		for len(opt) >= 8 {
 			sn := opt[0:4]
 			r := opt[4:8]
-			rt := types.Route{
+			rt := &types.Route{
 				Dst: classfulSubnet(sn),
 				GW:  r,
 			}
@@ -62,10 +62,10 @@ func parseRoutes(opts dhcp4.Options) []types.Route {
 	return routes
 }
 
-func parseCIDRRoutes(opts dhcp4.Options) []types.Route {
+func parseCIDRRoutes(opts dhcp4.Options) []*types.Route {
 	// See RFC4332 for format (http://tools.ietf.org/html/rfc3442)
 
-	routes := []types.Route{}
+	routes := []*types.Route{}
 	if opt, ok := opts[dhcp4.OptionClasslessRouteFormat]; ok {
 		for len(opt) >= 5 {
 			width := int(opt[0])
@@ -89,7 +89,7 @@ func parseCIDRRoutes(opts dhcp4.Options) []types.Route {
 
 			gw := net.IP(opt[octets+1 : octets+5])
 
-			rt := types.Route{
+			rt := &types.Route{
 				Dst: net.IPNet{
 					IP:   net.IP(sn),
 					Mask: net.CIDRMask(width, 32),

plugins/ipam/dhcp/options_test.go

@@ -22,16 +22,16 @@ import (
 	"github.com/d2g/dhcp4"
 )
 
-func validateRoutes(t *testing.T, routes []types.Route) {
-	expected := []types.Route{
-		types.Route{
+func validateRoutes(t *testing.T, routes []*types.Route) {
+	expected := []*types.Route{
+		&types.Route{
 			Dst: net.IPNet{
 				IP:   net.IPv4(10, 0, 0, 0),
 				Mask: net.CIDRMask(8, 32),
 			},
 			GW: net.IPv4(10, 1, 2, 3),
 		},
-		types.Route{
+		&types.Route{
 			Dst: net.IPNet{
 				IP:   net.IPv4(192, 168, 1, 0),
 				Mask: net.CIDRMask(24, 32),

plugins/ipam/host-local/backend/allocator/allocator.go

@@ -20,6 +20,7 @@ import (
 	"net"
 
 	"github.com/containernetworking/cni/pkg/ip"
+	"github.com/containernetworking/cni/pkg/types"
 	"github.com/containernetworking/cni/pkg/types/current"
 	"github.com/containernetworking/cni/plugins/ipam/host-local/backend"
 )
@@ -129,7 +130,7 @@ func validateRangeIP(ip net.IP, ipnet *net.IPNet, start net.IP, end net.IP) erro
 }
 
 // Returns newly allocated IP along with its config
-func (a *IPAllocator) Get(id string) (*current.IPConfig, error) {
+func (a *IPAllocator) Get(id string) (*current.IPConfig, []*types.Route, error) {
 	a.store.Lock()
 	defer a.store.Unlock()
 
@@ -145,7 +146,7 @@ func (a *IPAllocator) Get(id string) (*current.IPConfig, error) {
 
 	if requestedIP != nil {
 		if gw != nil && gw.Equal(a.conf.Args.IP) {
-			return nil, fmt.Errorf("requested IP must differ gateway IP")
+			return nil, nil, fmt.Errorf("requested IP must differ gateway IP")
 		}
 
 		subnet := net.IPNet{
@@ -154,22 +155,24 @@ func (a *IPAllocator) Get(id string) (*current.IPConfig, error) {
 		}
 		err := validateRangeIP(requestedIP, &subnet, a.start, a.end)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 
 		reserved, err := a.store.Reserve(id, requestedIP)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 
 		if reserved {
-			return &current.IPConfig{
-				IP:      net.IPNet{IP: requestedIP, Mask: a.conf.Subnet.Mask},
+			ipConfig := &current.IPConfig{
+				Version: "4",
+				Address: net.IPNet{IP: requestedIP, Mask: a.conf.Subnet.Mask},
 				Gateway: gw,
-				Routes:  a.conf.Routes,
-			}, nil
+			}
+			routes := convertRoutesToCurrent(a.conf.Routes)
+			return ipConfig, routes, nil
 		}
-		return nil, fmt.Errorf("requested IP address %q is not available in network: %s", requestedIP, a.conf.Name)
+		return nil, nil, fmt.Errorf("requested IP address %q is not available in network: %s", requestedIP, a.conf.Name)
 	}
 
 	startIP, endIP := a.getSearchRange()
@@ -181,21 +184,23 @@ func (a *IPAllocator) Get(id string) (*current.IPConfig, error) {
 
 		reserved, err := a.store.Reserve(id, cur)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 		if reserved {
-			return &current.IPConfig{
-				IP:      net.IPNet{IP: cur, Mask: a.conf.Subnet.Mask},
+			ipConfig := &current.IPConfig{
+				Version: "4",
+				Address: net.IPNet{IP: cur, Mask: a.conf.Subnet.Mask},
 				Gateway: gw,
-				Routes:  a.conf.Routes,
-			}, nil
+			}
+			routes := convertRoutesToCurrent(a.conf.Routes)
+			return ipConfig, routes, nil
 		}
 		// break here to complete the loop
 		if cur.Equal(endIP) {
 			break
 		}
 	}
-	return nil, fmt.Errorf("no IP addresses available in network: %s", a.conf.Name)
+	return nil, nil, fmt.Errorf("no IP addresses available in network: %s", a.conf.Name)
 }
 
 // Releases all IPs allocated for the container with given ID

plugins/ipam/host-local/backend/allocator/allocator_test.go

@@ -31,10 +31,10 @@ type AllocatorTestCase struct {
 	lastIP       string
 }
 
-func (t AllocatorTestCase) run() (*current.IPConfig, error) {
+func (t AllocatorTestCase) run() (*current.IPConfig, []*types.Route, error) {
 	subnet, err := types.ParseCIDR(t.subnet)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	conf := IPAMConfig{
@@ -45,14 +45,14 @@ func (t AllocatorTestCase) run() (*current.IPConfig, error) {
 	store := fakestore.NewFakeStore(t.ipmap, net.ParseIP(t.lastIP))
 	alloc, err := NewIPAllocator(&conf, store)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
-	res, err := alloc.Get("ID")
+	res, routes, err := alloc.Get("ID")
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
-	return res, nil
+	return res, routes, nil
 }
 
 var _ = Describe("host-local ip allocator", func() {
@@ -129,9 +129,9 @@ var _ = Describe("host-local ip allocator", func() {
 			}
 
 			for _, tc := range testCases {
-				res, err := tc.run()
+				res, _, err := tc.run()
 				Expect(err).ToNot(HaveOccurred())
-				Expect(res.IP.IP.String()).To(Equal(tc.expectResult))
+				Expect(res.Address.IP.String()).To(Equal(tc.expectResult))
 			}
 		})
 
@@ -149,14 +149,14 @@ var _ = Describe("host-local ip allocator", func() {
 			Expect(err).ToNot(HaveOccurred())
 
 			for i := 1; i < 254; i++ {
-				res, err := alloc.Get("ID")
+				res, _, err := alloc.Get("ID")
 				Expect(err).ToNot(HaveOccurred())
 				// i+1 because the gateway address is skipped
 				s := fmt.Sprintf("192.168.1.%d/24", i+1)
-				Expect(s).To(Equal(res.IP.String()))
+				Expect(s).To(Equal(res.Address.String()))
 			}
 
-			_, err = alloc.Get("ID")
+			_, _, err = alloc.Get("ID")
 			Expect(err).To(HaveOccurred())
 		})
 
@@ -174,13 +174,13 @@ var _ = Describe("host-local ip allocator", func() {
 			alloc, err := NewIPAllocator(&conf, store)
 			Expect(err).ToNot(HaveOccurred())
 
-			res, err := alloc.Get("ID")
+			res, _, err := alloc.Get("ID")
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.IP.String()).To(Equal("192.168.1.10/24"))
+			Expect(res.Address.String()).To(Equal("192.168.1.10/24"))
 
-			res, err = alloc.Get("ID")
+			res, _, err = alloc.Get("ID")
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.IP.String()).To(Equal("192.168.1.11/24"))
+			Expect(res.Address.String()).To(Equal("192.168.1.11/24"))
 		})
 
 		It("should allocate RangeEnd but not past RangeEnd", func() {
@@ -198,13 +198,13 @@ var _ = Describe("host-local ip allocator", func() {
 			Expect(err).ToNot(HaveOccurred())
 
 			for i := 1; i < 5; i++ {
-				res, err := alloc.Get("ID")
+				res, _, err := alloc.Get("ID")
 				Expect(err).ToNot(HaveOccurred())
 				// i+1 because the gateway address is skipped
-				Expect(res.IP.String()).To(Equal(fmt.Sprintf("192.168.1.%d/24", i+1)))
+				Expect(res.Address.String()).To(Equal(fmt.Sprintf("192.168.1.%d/24", i+1)))
 			}
 
-			_, err = alloc.Get("ID")
+			_, _, err = alloc.Get("ID")
 			Expect(err).To(HaveOccurred())
 		})
 
@@ -222,9 +222,9 @@ var _ = Describe("host-local ip allocator", func() {
 				}
 				store := fakestore.NewFakeStore(ipmap, nil)
 				alloc, _ := NewIPAllocator(&conf, store)
-				res, err := alloc.Get("ID")
+				res, _, err := alloc.Get("ID")
 				Expect(err).ToNot(HaveOccurred())
-				Expect(res.IP.IP.String()).To(Equal(requestedIP.String()))
+				Expect(res.Address.IP.String()).To(Equal(requestedIP.String()))
 			})
 
 			It("must return an error when the requested IP is after RangeEnd", func() {
@@ -240,7 +240,7 @@ var _ = Describe("host-local ip allocator", func() {
 				}
 				store := fakestore.NewFakeStore(ipmap, nil)
 				alloc, _ := NewIPAllocator(&conf, store)
-				_, err = alloc.Get("ID")
+				_, _, err = alloc.Get("ID")
 				Expect(err).To(HaveOccurred())
 			})
 
@@ -257,7 +257,7 @@ var _ = Describe("host-local ip allocator", func() {
 				}
 				store := fakestore.NewFakeStore(ipmap, nil)
 				alloc, _ := NewIPAllocator(&conf, store)
-				_, err = alloc.Get("ID")
+				_, _, err = alloc.Get("ID")
 				Expect(err).To(HaveOccurred())
 			})
 		})
@@ -332,7 +332,7 @@ var _ = Describe("host-local ip allocator", func() {
 				},
 			}
 			for _, tc := range testCases {
-				_, err := tc.run()
+				_, _, err := tc.run()
 				Expect(err).To(MatchError("no IP addresses available in network: test"))
 			}
 		})

plugins/ipam/host-local/backend/allocator/config.go

@@ -42,31 +42,43 @@ type IPAMArgs struct {
 }
 
 type Net struct {
-	Name string      `json:"name"`
-	IPAM *IPAMConfig `json:"ipam"`
+	Name       string      `json:"name"`
+	CNIVersion string      `json:"cniVersion"`
+	IPAM       *IPAMConfig `json:"ipam"`
 }
 
 // NewIPAMConfig creates a NetworkConfig from the given network name.
-func LoadIPAMConfig(bytes []byte, args string) (*IPAMConfig, error) {
+func LoadIPAMConfig(bytes []byte, args string) (*IPAMConfig, string, error) {
 	n := Net{}
 	if err := json.Unmarshal(bytes, &n); err != nil {
-		return nil, err
+		return nil, "", err
 	}
 
 	if args != "" {
 		n.IPAM.Args = &IPAMArgs{}
 		err := types.LoadArgs(args, n.IPAM.Args)
 		if err != nil {
-			return nil, err
+			return nil, "", err
 		}
 	}
 
 	if n.IPAM == nil {
-		return nil, fmt.Errorf("IPAM config missing 'ipam' key")
+		return nil, "", fmt.Errorf("IPAM config missing 'ipam' key")
 	}
 
 	// Copy net name into IPAM so not to drag Net struct around
 	n.IPAM.Name = n.Name
 
-	return n.IPAM, nil
+	return n.IPAM, n.CNIVersion, nil
+}
+
+func convertRoutesToCurrent(routes []types.Route) []*types.Route {
+	var currentRoutes []*types.Route
+	for _, r := range routes {
+		currentRoutes = append(currentRoutes, &types.Route{
+			Dst: r.Dst,
+			GW:  r.GW,
+		})
+	}
+	return currentRoutes
 }

plugins/ipam/host-local/host_local_test.go

@@ -20,10 +20,12 @@ import (
 	"net"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"github.com/containernetworking/cni/pkg/skel"
 	"github.com/containernetworking/cni/pkg/testutils"
 	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/types/020"
 	"github.com/containernetworking/cni/pkg/types/current"
 
 	. "github.com/onsi/ginkgo"
@@ -43,7 +45,7 @@ var _ = Describe("host-local Operations", func() {
 		Expect(err).NotTo(HaveOccurred())
 
 		conf := fmt.Sprintf(`{
-    "cniVersion": "0.2.0",
+    "cniVersion": "0.3.0",
     "name": "mynet",
     "type": "ipvlan",
     "master": "foo0",
@@ -63,19 +65,83 @@ var _ = Describe("host-local Operations", func() {
 		}
 
 		// Allocate the IP
-		r, _, err := testutils.CmdAddWithResult(nspath, ifname, []byte(conf), func() error {
+		r, raw, err := testutils.CmdAddWithResult(nspath, ifname, []byte(conf), func() error {
 			return cmdAdd(args)
 		})
 		Expect(err).NotTo(HaveOccurred())
+		Expect(strings.Index(string(raw), "\"version\":")).Should(BeNumerically(">", 0))
 
 		result, err := current.GetResult(r)
 		Expect(err).NotTo(HaveOccurred())
 
+		expectedAddress, err := types.ParseCIDR("10.1.2.2/24")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(len(result.IPs)).To(Equal(1))
+		expectedAddress.IP = expectedAddress.IP.To16()
+		Expect(result.IPs[0].Address).To(Equal(*expectedAddress))
+		Expect(result.IPs[0].Gateway).To(Equal(net.ParseIP("10.1.2.1")))
+
+		ipFilePath := filepath.Join(tmpDir, "mynet", "10.1.2.2")
+		contents, err := ioutil.ReadFile(ipFilePath)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(string(contents)).To(Equal("dummy"))
+
+		lastFilePath := filepath.Join(tmpDir, "mynet", "last_reserved_ip")
+		contents, err = ioutil.ReadFile(lastFilePath)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(string(contents)).To(Equal("10.1.2.2"))
+
+		// Release the IP
+		err = testutils.CmdDelWithResult(nspath, ifname, func() error {
+			return cmdDel(args)
+		})
+		Expect(err).NotTo(HaveOccurred())
+
+		_, err = os.Stat(ipFilePath)
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("allocates and releases an address with ADD/DEL and 0.1.0 config", func() {
+		const ifname string = "eth0"
+		const nspath string = "/some/where"
+
+		tmpDir, err := ioutil.TempDir("", "host_local_artifacts")
+		Expect(err).NotTo(HaveOccurred())
+		defer os.RemoveAll(tmpDir)
+
+		conf := fmt.Sprintf(`{
+    "cniVersion": "0.1.0",
+    "name": "mynet",
+    "type": "ipvlan",
+    "master": "foo0",
+    "ipam": {
+        "type": "host-local",
+        "subnet": "10.1.2.0/24",
+        "dataDir": "%s"
+    }
+}`, tmpDir)
+
+		args := &skel.CmdArgs{
+			ContainerID: "dummy",
+			Netns:       nspath,
+			IfName:      ifname,
+			StdinData:   []byte(conf),
+		}
+
+		// Allocate the IP
+		r, raw, err := testutils.CmdAddWithResult(nspath, ifname, []byte(conf), func() error {
+			return cmdAdd(args)
+		})
+		Expect(err).NotTo(HaveOccurred())
+		Expect(strings.Index(string(raw), "\"ip4\":")).Should(BeNumerically(">", 0))
+
+		result, err := types020.GetResult(r)
+		Expect(err).NotTo(HaveOccurred())
+
 		expectedAddress, err := types.ParseCIDR("10.1.2.2/24")
 		Expect(err).NotTo(HaveOccurred())
 		expectedAddress.IP = expectedAddress.IP.To16()
 		Expect(result.IP4.IP).To(Equal(*expectedAddress))
-
 		Expect(result.IP4.Gateway).To(Equal(net.ParseIP("10.1.2.1")))
 
 		ipFilePath := filepath.Join(tmpDir, "mynet", "10.1.2.2")
@@ -136,7 +202,7 @@ var _ = Describe("host-local Operations", func() {
 		result, err := current.GetResult(r)
 		Expect(err).NotTo(HaveOccurred())
 
-		ipFilePath := filepath.Join(tmpDir, "mynet", result.IP4.IP.IP.String())
+		ipFilePath := filepath.Join(tmpDir, "mynet", result.IPs[0].Address.IP.String())
 		contents, err := ioutil.ReadFile(ipFilePath)
 		Expect(err).NotTo(HaveOccurred())
 		Expect(string(contents)).To(Equal("dummy"))

plugins/ipam/host-local/main.go

@@ -19,28 +19,29 @@ import (
 	"github.com/containernetworking/cni/plugins/ipam/host-local/backend/disk"
 
 	"github.com/containernetworking/cni/pkg/skel"
+	"github.com/containernetworking/cni/pkg/types"
 	"github.com/containernetworking/cni/pkg/types/current"
 	"github.com/containernetworking/cni/pkg/version"
 )
 
 func main() {
-	skel.PluginMain(cmdAdd, cmdDel, version.Legacy)
+	skel.PluginMain(cmdAdd, cmdDel, version.All)
 }
 
 func cmdAdd(args *skel.CmdArgs) error {
-	ipamConf, err := allocator.LoadIPAMConfig(args.StdinData, args.Args)
+	ipamConf, confVersion, err := allocator.LoadIPAMConfig(args.StdinData, args.Args)
 	if err != nil {
 		return err
 	}
 
-	r := &current.Result{}
+	result := &current.Result{}
 
 	if ipamConf.ResolvConf != "" {
 		dns, err := parseResolvConf(ipamConf.ResolvConf)
 		if err != nil {
 			return err
 		}
-		r.DNS = *dns
+		result.DNS = *dns
 	}
 
 	store, err := disk.New(ipamConf.Name, ipamConf.DataDir)
@@ -54,16 +55,18 @@ func cmdAdd(args *skel.CmdArgs) error {
 		return err
 	}
 
-	r.IP4, err = allocator.Get(args.ContainerID)
+	ipConf, routes, err := allocator.Get(args.ContainerID)
 	if err != nil {
 		return err
 	}
+	result.IPs = []*current.IPConfig{ipConf}
+	result.Routes = routes
 
-	return r.Print()
+	return types.PrintResult(result, confVersion)
 }
 
 func cmdDel(args *skel.CmdArgs) error {
-	ipamConf, err := allocator.LoadIPAMConfig(args.StdinData, args.Args)
+	ipamConf, _, err := allocator.LoadIPAMConfig(args.StdinData, args.Args)
 	if err != nil {
 		return err
 	}