Instance + Flavor Plugin SPI Changes (#371)

Signed-off-by: David Chung <david.chung@docker.com>

Author: David Chung

cmd/cli/flavor.go

@@ -10,10 +10,11 @@ import (
 	log "github.com/Sirupsen/logrus"
 	"github.com/docker/infrakit/pkg/discovery"
 	"github.com/docker/infrakit/pkg/plugin"
-	"github.com/docker/infrakit/pkg/plugin/group/types"
+	group_types "github.com/docker/infrakit/pkg/plugin/group/types"
 	flavor_plugin "github.com/docker/infrakit/pkg/rpc/flavor"
 	"github.com/docker/infrakit/pkg/spi/flavor"
 	"github.com/docker/infrakit/pkg/spi/instance"
+	"github.com/docker/infrakit/pkg/types"
 	"github.com/spf13/cobra"
 )
 
@@ -65,13 +66,13 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 			"Group Size to use as the Allocation method")
 	}
 
-	allocationMethodFromFlags := func() types.AllocationMethod {
+	allocationMethodFromFlags := func() group_types.AllocationMethod {
 		ids := []instance.LogicalID{}
 		for _, id := range logicalIDs {
 			ids = append(ids, instance.LogicalID(id))
 		}
 
-		return types.AllocationMethod{
+		return group_types.AllocationMethod{
 			Size:       groupSize,
 			LogicalIDs: ids,
 		}
@@ -94,7 +95,7 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 				os.Exit(1)
 			}
 
-			return flavorPlugin.Validate(json.RawMessage(buff), allocationMethodFromFlags())
+			return flavorPlugin.Validate(types.AnyBytes(buff), allocationMethodFromFlags())
 		},
 	}
 	addAllocationMethodFlags(validate)
@@ -129,7 +130,7 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 			}
 
 			spec, err = flavorPlugin.Prepare(
-				json.RawMessage(flavorProperties),
+				types.AnyBytes(flavorProperties),
 				spec,
 				allocationMethodFromFlags())
 			if err == nil {
@@ -187,7 +188,7 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 			desc.LogicalID = &logical
 		}
 
-		healthy, err := flavorPlugin.Healthy(json.RawMessage(flavorProperties), desc)
+		healthy, err := flavorPlugin.Healthy(types.AnyBytes(flavorProperties), desc)
 		if err == nil {
 			fmt.Printf("%v\n", healthy)
 		}

cmd/cli/instance.go

@@ -13,6 +13,7 @@ import (
 	"github.com/docker/infrakit/pkg/plugin"
 	instance_plugin "github.com/docker/infrakit/pkg/rpc/instance"
 	"github.com/docker/infrakit/pkg/spi/instance"
+	"github.com/docker/infrakit/pkg/types"
 	"github.com/spf13/cobra"
 )
 
@@ -65,7 +66,7 @@ func instancePluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 				os.Exit(1)
 			}
 
-			err = instancePlugin.Validate(json.RawMessage(buff))
+			err = instancePlugin.Validate(types.AnyBytes(buff))
 			if err == nil {
 				fmt.Println("validate:ok")
 			}

docs/plugins/flavor.md

@@ -1,6 +1,6 @@
 # Flavor plugin API
 
-<!-- SOURCE-CHECKSUM pkg/spi/flavor/* 921b81c90c2abc7aec298333e1e1cf9c039afca5 -->
+<!-- SOURCE-CHECKSUM pkg/spi/flavor/* 76aecf22acb4af73f36857bb2fad861896ae0b62 -->
 
 ## API
 

docs/plugins/instance.md

@@ -1,6 +1,6 @@
 # Instance plugin API
 
-<!-- SOURCE-CHECKSUM pkg/spi/instance/* 8fc5d1832d0d96d01d8d76ea1137230790fe51fe338393f886f528c3824986fc97cb27410aefd8e2 -->
+<!-- SOURCE-CHECKSUM pkg/spi/instance/* befb47292c2f062637d65e9777d88c322856baf650feb6b527cd3a4242f86d3482b656246051d2ca -->
 
 ## API
 
@@ -80,6 +80,35 @@ Parameters:
 Fields:
 - `OK`: Whether the operation succeeded.
 
+### Method `Instance.Label`
+Labels an instance.  The plugin should add or update the labels given.
+
+#### Request
+```json
+{
+  "Instance": "instance_id",
+  "Labels" : {
+     "label1" : "value1",
+     "label2" : "value2",
+     "label3" : "value3"
+  }
+}
+```
+
+Parameters:
+- `Instance`: An [instance ID](types.md#instance-id).
+- `Labels`: A [map](types.md#instance-tags) of labels or instance tags.
+
+#### Response
+```json
+{
+  "OK": true
+}
+```
+
+Fields:
+- `OK`: Whether the operation succeeded.
+
 ### Method `Instance.DescribeInstances`
 Fetches details about Instances.
 

docs/plugins/types.md

@@ -71,3 +71,5 @@ Instance grouping and metadata.
 ### Logical ID
 A possibly-reused logical identifier for an Instance.
 
+### Labels
+A map or dictionary of key-value pairs that label / tag the instance.  Same as [Instance Tags](#instance-tags)

examples/flavor/combo/flavor.go

@@ -1,18 +1,19 @@
 package main
 
 import (
-	"encoding/json"
 	"errors"
+	"strings"
+
 	"github.com/docker/infrakit/pkg/plugin/group"
-	"github.com/docker/infrakit/pkg/plugin/group/types"
+	group_types "github.com/docker/infrakit/pkg/plugin/group/types"
 	"github.com/docker/infrakit/pkg/spi/flavor"
 	"github.com/docker/infrakit/pkg/spi/instance"
-	"strings"
+	"github.com/docker/infrakit/pkg/types"
 )
 
 // Spec is the model of the plugin Properties.
 type Spec struct {
-	Flavors []types.FlavorPlugin
+	Flavors []group_types.FlavorPlugin
 }
 
 // NewPlugin creates a Flavor Combo plugin that chains multiple flavors in a sequence.  Each flavor
@@ -24,18 +25,18 @@ type flavorCombo struct {
 	flavorPlugins group.FlavorPluginLookup
 }
 
-func (f flavorCombo) Validate(flavorProperties json.RawMessage, allocation types.AllocationMethod) error {
+func (f flavorCombo) Validate(flavorProperties *types.Any, allocation group_types.AllocationMethod) error {
 	s := Spec{}
-	return json.Unmarshal(flavorProperties, &s)
+	return flavorProperties.Decode(&s)
 }
 
-func (f flavorCombo) Healthy(flavorProperties json.RawMessage, inst instance.Description) (flavor.Health, error) {
+func (f flavorCombo) Healthy(flavorProperties *types.Any, inst instance.Description) (flavor.Health, error) {
 	// The overall health of the flavor combination is taken as the 'lowest common demoninator' of the configured
 	// flavors.  Only flavor.Healthy is reported if all flavors report flavor.Healthy.  flavor.Unhealthy or
 	// flavor.UnknownHealth is returned as soon as any Flavor reports that value.
 
 	s := Spec{}
-	if err := json.Unmarshal(flavorProperties, &s); err != nil {
+	if err := flavorProperties.Decode(s); err != nil {
 		return flavor.Unknown, err
 	}
 
@@ -45,7 +46,7 @@ func (f flavorCombo) Healthy(flavorProperties json.RawMessage, inst instance.Des
 			return flavor.Unknown, err
 		}
 
-		health, err := plugin.Healthy(types.RawMessage(pluginSpec.Properties), inst)
+		health, err := plugin.Healthy(pluginSpec.Properties, inst)
 		if err != nil || health != flavor.Healthy {
 			return health, err
 		}
@@ -54,12 +55,12 @@ func (f flavorCombo) Healthy(flavorProperties json.RawMessage, inst instance.Des
 	return flavor.Healthy, nil
 }
 
-func (f flavorCombo) Drain(flavorProperties json.RawMessage, inst instance.Description) error {
+func (f flavorCombo) Drain(flavorProperties *types.Any, inst instance.Description) error {
 	// Draining is attempted on all flavors regardless of errors encountered.  All errors encountered are combined
 	// and returned.
 
 	s := Spec{}
-	if err := json.Unmarshal(flavorProperties, &s); err != nil {
+	if err := flavorProperties.Decode(&s); err != nil {
 		return err
 	}
 
@@ -71,7 +72,7 @@ func (f flavorCombo) Drain(flavorProperties json.RawMessage, inst instance.Descr
 			errs = append(errs, err.Error())
 		}
 
-		if err := plugin.Drain(types.RawMessage(pluginSpec.Properties), inst); err != nil {
+		if err := plugin.Drain(pluginSpec.Properties, inst); err != nil {
 			errs = append(errs, err.Error())
 		}
 	}
@@ -133,13 +134,12 @@ func mergeSpecs(initial instance.Spec, specs []instance.Spec) (instance.Spec, er
 	return result, nil
 }
 
-func (f flavorCombo) Prepare(
-	flavor json.RawMessage,
+func (f flavorCombo) Prepare(flavor *types.Any,
 	inst instance.Spec,
-	allocation types.AllocationMethod) (instance.Spec, error) {
+	allocation group_types.AllocationMethod) (instance.Spec, error) {
 
 	combo := Spec{}
-	err := json.Unmarshal(flavor, &combo)
+	err := flavor.Decode(&combo)
 	if err != nil {
 		return inst, err
 	}
@@ -154,7 +154,7 @@ func (f flavorCombo) Prepare(
 			return inst, err
 		}
 
-		flavorOutput, err := plugin.Prepare(types.RawMessage(pluginSpec.Properties), clone, allocation)
+		flavorOutput, err := plugin.Prepare(pluginSpec.Properties, clone, allocation)
 		if err != nil {
 			return inst, err
 		}

examples/flavor/combo/flavor_test.go

@@ -1,32 +1,27 @@
 package main
 
 import (
-	"encoding/json"
 	"errors"
 	"testing"
 
 	mock_flavor "github.com/docker/infrakit/pkg/mock/spi/flavor"
 	"github.com/docker/infrakit/pkg/plugin"
 	"github.com/docker/infrakit/pkg/plugin/group"
-	"github.com/docker/infrakit/pkg/plugin/group/types"
+	group_types "github.com/docker/infrakit/pkg/plugin/group/types"
 	"github.com/docker/infrakit/pkg/spi/flavor"
 	"github.com/docker/infrakit/pkg/spi/instance"
+	"github.com/docker/infrakit/pkg/types"
 	"github.com/golang/mock/gomock"
 	"github.com/stretchr/testify/require"
 )
 
-func jsonPtr(v string) *json.RawMessage {
-	j := json.RawMessage(v)
-	return &j
-}
-
 func logicalID(v string) *instance.LogicalID {
 	id := instance.LogicalID(v)
 	return &id
 }
 
 var inst = instance.Spec{
-	Properties:  jsonPtr("{}"),
+	Properties:  types.AnyString("{}"),
 	Tags:        map[string]string{},
 	Init:        "",
 	LogicalID:   logicalID("id"),
@@ -54,7 +49,7 @@ func TestMergeBehavior(t *testing.T) {
 
 	combo := NewPlugin(pluginLookup(plugins))
 
-	flavorProperties := json.RawMessage(`{
+	flavorProperties := types.AnyString(`{
 	  "Flavors": [
 	    {
 	      "Plugin": "a",
@@ -67,25 +62,25 @@ func TestMergeBehavior(t *testing.T) {
 	  ]
 	}`)
 
-	allocation := types.AllocationMethod{Size: 1}
+	allocation := group_types.AllocationMethod{Size: 1}
 
-	a.EXPECT().Prepare(json.RawMessage(`{"a": "1"}`), inst, allocation).Return(instance.Spec{
+	a.EXPECT().Prepare(types.AnyString(`{"a": "1"}`), inst, allocation).Return(instance.Spec{
 		Properties:  inst.Properties,
 		Tags:        map[string]string{"a": "1", "c": "4"},
 		Init:        "init data a",
 		LogicalID:   inst.LogicalID,
 		Attachments: []instance.Attachment{{ID: "a", Type: "nic"}},
 	}, nil)
 
-	b.EXPECT().Prepare(json.RawMessage(`{"b": "2"}`), inst, allocation).Return(instance.Spec{
+	b.EXPECT().Prepare(types.AnyString(`{"b": "2"}`), inst, allocation).Return(instance.Spec{
 		Properties:  inst.Properties,
 		Tags:        map[string]string{"b": "2", "c": "5"},
 		Init:        "init data b",
 		LogicalID:   inst.LogicalID,
 		Attachments: []instance.Attachment{{ID: "b", Type: "gpu"}},
 	}, nil)
 
-	result, err := combo.Prepare(flavorProperties, inst, types.AllocationMethod{Size: 1})
+	result, err := combo.Prepare(flavorProperties, inst, group_types.AllocationMethod{Size: 1})
 	require.NoError(t, err)
 
 	expected := instance.Spec{
@@ -102,7 +97,7 @@ func TestMergeNoLogicalID(t *testing.T) {
 	// Tests regression of a bug where a zero value was returned for the LogicalID despite nil being passed.
 
 	inst = instance.Spec{
-		Properties:  jsonPtr("{}"),
+		Properties:  types.AnyString("{}"),
 		Tags:        map[string]string{},
 		Init:        "",
 		Attachments: []instance.Attachment{{ID: "att1", Type: "nic"}},
@@ -118,7 +113,7 @@ func TestMergeNoLogicalID(t *testing.T) {
 
 	combo := NewPlugin(pluginLookup(plugins))
 
-	flavorProperties := json.RawMessage(`{
+	flavorProperties := types.AnyString(`{
 	  "Flavors": [
 	    {
 	      "Plugin": "a",
@@ -131,25 +126,25 @@ func TestMergeNoLogicalID(t *testing.T) {
 	  ]
 	}`)
 
-	allocation := types.AllocationMethod{Size: 1}
+	allocation := group_types.AllocationMethod{Size: 1}
 
-	a.EXPECT().Prepare(json.RawMessage(`{"a": "1"}`), inst, allocation).Return(instance.Spec{
+	a.EXPECT().Prepare(types.AnyString(`{"a": "1"}`), inst, allocation).Return(instance.Spec{
 		Properties:  inst.Properties,
 		Tags:        map[string]string{"a": "1", "c": "4"},
 		Init:        "init data a",
 		LogicalID:   inst.LogicalID,
 		Attachments: []instance.Attachment{{ID: "a", Type: "nic"}},
 	}, nil)
 
-	b.EXPECT().Prepare(json.RawMessage(`{"b": "2"}`), inst, allocation).Return(instance.Spec{
+	b.EXPECT().Prepare(types.AnyString(`{"b": "2"}`), inst, allocation).Return(instance.Spec{
 		Properties:  inst.Properties,
 		Tags:        map[string]string{"b": "2", "c": "5"},
 		Init:        "init data b",
 		LogicalID:   inst.LogicalID,
 		Attachments: []instance.Attachment{{ID: "b", Type: "gpu"}},
 	}, nil)
 
-	result, err := combo.Prepare(flavorProperties, inst, types.AllocationMethod{Size: 1})
+	result, err := combo.Prepare(flavorProperties, inst, group_types.AllocationMethod{Size: 1})
 	require.NoError(t, err)
 
 	expected := instance.Spec{