Add launch index in flavor.Prepare call (#443)

Signed-off-by: David Chung <[email protected]>

Author: David Chung

cmd/cli/flavor.go

@@ -13,6 +13,7 @@ import (
 	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/group"
 	"github.com/docker/infrakit/pkg/spi/instance"
 	"github.com/docker/infrakit/pkg/types"
 	"github.com/spf13/cobra"
@@ -53,6 +54,9 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 
 	logicalIDs := []string{}
 	groupSize := uint(0)
+	groupID := ""
+	groupSequence := uint(0)
+
 	addAllocationMethodFlags := func(cmd *cobra.Command) {
 		cmd.Flags().StringSliceVar(
 			&logicalIDs,
@@ -65,7 +69,6 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 			0,
 			"Group Size to use as the Allocation method")
 	}
-
 	allocationMethodFromFlags := func() group_types.AllocationMethod {
 		ids := []instance.LogicalID{}
 		for _, id := range logicalIDs {
@@ -78,6 +81,23 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 		}
 	}
 
+	indexFlags := func(cmd *cobra.Command) {
+		cmd.Flags().StringVar(
+			&groupID,
+			"index-group",
+			"",
+			"ID of the group")
+		cmd.Flags().UintVar(
+			&groupSequence,
+			"index-sequence",
+			0,
+			"Sequence number within the group")
+	}
+
+	indexFromFlags := func() group_types.Index {
+		return group_types.Index{Group: group.ID(groupID), Sequence: groupSequence}
+	}
+
 	validate := &cobra.Command{
 		Use:   "validate <flavor configuration file>",
 		Short: "validate a flavor configuration",
@@ -132,7 +152,9 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 			spec, err = flavorPlugin.Prepare(
 				types.AnyBytes(flavorProperties),
 				spec,
-				allocationMethodFromFlags())
+				allocationMethodFromFlags(),
+				indexFromFlags(),
+			)
 			if err == nil {
 				buff, err = json.MarshalIndent(spec, "  ", "  ")
 				if err == nil {
@@ -143,6 +165,7 @@ func flavorPluginCommand(plugins func() discovery.Plugins) *cobra.Command {
 		},
 	}
 	addAllocationMethodFlags(prepare)
+	indexFlags(prepare)
 	cmd.AddCommand(prepare)
 
 	healthy := &cobra.Command{

docs/plugins/flavor.md

@@ -1,6 +1,6 @@
 # Flavor plugin API
 
-<!-- SOURCE-CHECKSUM pkg/spi/flavor/* 76aecf22acb4af73f36857bb2fad861896ae0b62 -->
+<!-- SOURCE-CHECKSUM pkg/spi/flavor/* e27841cf1ead137533b608b3ccc90ab72596532a -->
 
 ## API
 
@@ -52,6 +52,10 @@ may add, remove, or modify any fields in the Instance `Spec` by returning the de
   "Allocation": {
     "Size": 1,
     "LogicalIDs": ["logical_id_1"]
+  },
+  "Index" : {
+    "Group" : "workers",
+    "Sequence" : 100
   }
 }
 ```
@@ -60,6 +64,7 @@ Parameters:
 - `Properties`: A JSON object representing the Flavor.  The schema is defined by the Flavor plugin in use.
 - `Spec`: The [Spec](types.md#instance-spec) of the Instance being prepared.
 - `Allocation`: An [Allocation](types.md#allocation)
+- `Index`: an [Index](types.md#index)
 
 #### Response
 ```json

docs/plugins/types.md

@@ -13,6 +13,17 @@ Fields:
 - `Size`: An integer, the number of instances to maintain in the Group.
 - `LogicalIDs`: An array of strings, the logical identifeirs to maintain in the group.
 
+# Index
+Index is a context object that is used to denote the instance's relationship with respect to the group it belongs.
+An Index has two fields: a group ID and a sequence number.  The group ID is the identifier of the group, while the
+sequence number represents the order in which the instance is created with respect to the group.  So for a group of
+size N, the sequence number will be 0, 1, 2, ... N-1.  This can be used by the flavor plugin to determine which one
+of the instances, as represented by a fixed set of nodes (e.g. pets, or stateful nodes), the current instance is.
+In cases where provisioning instances where IP addresses cannot be assigned upfront, this provides a mechanism for
+looking up which IP address a particular node represents if given a list of IP addresses as a result of instance
+creations for this group.  A similar concept can be found in AWS Autoscaling group's Launch index.
+
+
 # Group ID
 A globally-unique string identifier for an Group.
 

examples/flavor/combo/flavor.go

@@ -136,7 +136,8 @@ func mergeSpecs(initial instance.Spec, specs []instance.Spec) (instance.Spec, er
 
 func (f flavorCombo) Prepare(flavor *types.Any,
 	inst instance.Spec,
-	allocation group_types.AllocationMethod) (instance.Spec, error) {
+	allocation group_types.AllocationMethod,
+	index group_types.Index) (instance.Spec, error) {
 
 	combo := Spec{}
 	err := flavor.Decode(&combo)
@@ -154,7 +155,7 @@ func (f flavorCombo) Prepare(flavor *types.Any,
 			return inst, err
 		}
 
-		flavorOutput, err := plugin.Prepare(pluginSpec.Properties, clone, allocation)
+		flavorOutput, err := plugin.Prepare(pluginSpec.Properties, clone, allocation, index)
 		if err != nil {
 			return inst, err
 		}

examples/flavor/combo/flavor_test.go

@@ -6,9 +6,10 @@ import (
 
 	mock_flavor "github.com/docker/infrakit/pkg/mock/spi/flavor"
 	"github.com/docker/infrakit/pkg/plugin"
-	"github.com/docker/infrakit/pkg/plugin/group"
+	group_plugin "github.com/docker/infrakit/pkg/plugin/group"
 	group_types "github.com/docker/infrakit/pkg/plugin/group/types"
 	"github.com/docker/infrakit/pkg/spi/flavor"
+	"github.com/docker/infrakit/pkg/spi/group"
 	"github.com/docker/infrakit/pkg/spi/instance"
 	"github.com/docker/infrakit/pkg/types"
 	"github.com/golang/mock/gomock"
@@ -28,7 +29,7 @@ var inst = instance.Spec{
 	Attachments: []instance.Attachment{{ID: "att1", Type: "nic"}},
 }
 
-func pluginLookup(plugins map[string]flavor.Plugin) group.FlavorPluginLookup {
+func pluginLookup(plugins map[string]flavor.Plugin) group_plugin.FlavorPluginLookup {
 	return func(key plugin.Name) (flavor.Plugin, error) {
 		plugin, has := plugins[key.String()]
 		if has {
@@ -63,24 +64,24 @@ func TestMergeBehavior(t *testing.T) {
 	}`)
 
 	allocation := group_types.AllocationMethod{Size: 1}
-
-	a.EXPECT().Prepare(types.AnyString(`{"a": "1"}`), inst, allocation).Return(instance.Spec{
+	index := group_types.Index{Group: group.ID("group"), Sequence: 0}
+	a.EXPECT().Prepare(types.AnyString(`{"a": "1"}`), inst, allocation, index).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(types.AnyString(`{"b": "2"}`), inst, allocation).Return(instance.Spec{
+	b.EXPECT().Prepare(types.AnyString(`{"b": "2"}`), inst, allocation, index).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, group_types.AllocationMethod{Size: 1})
+	result, err := combo.Prepare(flavorProperties, inst, group_types.AllocationMethod{Size: 1}, index)
 	require.NoError(t, err)
 
 	expected := instance.Spec{
@@ -127,24 +128,24 @@ func TestMergeNoLogicalID(t *testing.T) {
 	}`)
 
 	allocation := group_types.AllocationMethod{Size: 1}
-
-	a.EXPECT().Prepare(types.AnyString(`{"a": "1"}`), inst, allocation).Return(instance.Spec{
+	index := group_types.Index{Group: group.ID("group"), Sequence: 0}
+	a.EXPECT().Prepare(types.AnyString(`{"a": "1"}`), inst, allocation, index).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(types.AnyString(`{"b": "2"}`), inst, allocation).Return(instance.Spec{
+	b.EXPECT().Prepare(types.AnyString(`{"b": "2"}`), inst, allocation, index).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, group_types.AllocationMethod{Size: 1})
+	result, err := combo.Prepare(flavorProperties, inst, group_types.AllocationMethod{Size: 1}, index)
 	require.NoError(t, err)
 
 	expected := instance.Spec{

examples/flavor/swarm/flavor.go

@@ -210,7 +210,8 @@ func (s *baseFlavor) Healthy(flavorProperties *types.Any, inst instance.Descript
 }
 
 func (s *baseFlavor) prepare(role string, flavorProperties *types.Any, instanceSpec instance.Spec,
-	allocation group_types.AllocationMethod) (instance.Spec, error) {
+	allocation group_types.AllocationMethod,
+	index group_types.Index) (instance.Spec, error) {
 
 	spec := Spec{}
 
@@ -269,6 +270,7 @@ func (s *baseFlavor) prepare(role string, flavorProperties *types.Any, instanceS
 			flavorSpec:   spec,
 			instanceSpec: instanceSpec,
 			allocation:   allocation,
+			index:        index,
 			swarmStatus:  swarmStatus,
 			nodeInfo:     node,
 			link:         *link,
@@ -407,6 +409,7 @@ type templateContext struct {
 	flavorSpec   Spec
 	instanceSpec instance.Spec
 	allocation   group_types.AllocationMethod
+	index        group_types.Index
 	swarmStatus  *swarm.Swarm
 	nodeInfo     *swarm.Node
 	link         types.Link
@@ -446,6 +449,13 @@ func (c *templateContext) Funcs() []template.Function {
 				return c.allocation
 			},
 		},
+		{
+			Name:        "INDEX",
+			Description: []string{"The launch index of this instance. Contains the group ID and the sequence number of instance."},
+			Func: func() interface{} {
+				return c.index
+			},
+		},
 		{
 			Name:        "INFRAKIT_LABELS",
 			Description: []string{"The Docker engine labels to be applied for linking the Docker engine to this instance."},

examples/flavor/swarm/flavor_test.go

@@ -11,6 +11,7 @@ import (
 	mock_client "github.com/docker/infrakit/pkg/mock/docker/docker/client"
 	group_types "github.com/docker/infrakit/pkg/plugin/group/types"
 	"github.com/docker/infrakit/pkg/spi/flavor"
+	"github.com/docker/infrakit/pkg/spi/group"
 	"github.com/docker/infrakit/pkg/spi/instance"
 	"github.com/docker/infrakit/pkg/template"
 	"github.com/docker/infrakit/pkg/types"
@@ -117,10 +118,12 @@ func TestWorker(t *testing.T) {
 	client.EXPECT().NodeInspectWithRaw(gomock.Any(), nodeID).Return(nodeInfo, nil, nil).AnyTimes()
 	client.EXPECT().Close().AnyTimes()
 
+	index := group_types.Index{Group: group.ID("group"), Sequence: 0}
 	details, err := flavorImpl.Prepare(
 		types.AnyString(`{}`),
 		instance.Spec{Tags: map[string]string{"a": "b"}},
-		group_types.AllocationMethod{Size: 5})
+		group_types.AllocationMethod{Size: 5},
+		index)
 	require.NoError(t, err)
 	require.Equal(t, "b", details.Tags["a"])
 
@@ -188,11 +191,13 @@ func TestManager(t *testing.T) {
 	client.EXPECT().NodeInspectWithRaw(gomock.Any(), nodeID).Return(nodeInfo, nil, nil).AnyTimes()
 	client.EXPECT().Close().AnyTimes()
 
+	index := group_types.Index{Group: group.ID("group"), Sequence: 0}
 	id := instance.LogicalID("127.0.0.1")
 	details, err := flavorImpl.Prepare(
 		types.AnyString(`{"Attachments": {"127.0.0.1": [{"ID": "a", "Type": "gpu"}]}}`),
 		instance.Spec{Tags: map[string]string{"a": "b"}, LogicalID: &id},
-		group_types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1"}})
+		group_types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1"}},
+		index)
 	require.NoError(t, err)
 	require.Equal(t, "b", details.Tags["a"])
 
@@ -208,11 +213,13 @@ func TestManager(t *testing.T) {
 	require.Contains(t, details.Init, associationID)
 
 	// another instance -- note that this id is not the first in the allocation list of logical ids.
+	index = group_types.Index{Group: group.ID("group"), Sequence: 1}
 	id = instance.LogicalID("172.200.100.2")
 	details, err = flavorImpl.Prepare(
 		types.AnyString(`{"Attachments": {"172.200.100.2": [{"ID": "a", "Type": "gpu"}]}}`),
 		instance.Spec{Tags: map[string]string{"a": "b"}, LogicalID: &id},
-		group_types.AllocationMethod{LogicalIDs: []instance.LogicalID{"172.200.100.1", "172.200.100.2"}})
+		group_types.AllocationMethod{LogicalIDs: []instance.LogicalID{"172.200.100.1", "172.200.100.2"}},
+		index)
 	require.NoError(t, err)
 
 	require.Contains(t, details.Init, swarmInfo.JoinTokens.Manager)
@@ -239,3 +246,50 @@ func TestManager(t *testing.T) {
 
 	close(managerStop)
 }
+
+func TestTemplateFunctions(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	managerStop := make(chan struct{})
+
+	client := mock_client.NewMockAPIClientCloser(ctrl)
+
+	flavorImpl := NewManagerFlavor(plugins, func(Spec) (docker.APIClientCloser, error) {
+		return client, nil
+	}, templ(DefaultManagerInitScriptTemplate), managerStop)
+
+	swarmInfo := swarm.Swarm{
+		ClusterInfo: swarm.ClusterInfo{ID: "ClusterUUID"},
+		JoinTokens: swarm.JoinTokens{
+			Manager: "ManagerToken",
+			Worker:  "WorkerToken",
+		},
+	}
+
+	client.EXPECT().SwarmInspect(gomock.Any()).Return(swarmInfo, nil).AnyTimes()
+	client.EXPECT().Info(gomock.Any()).Return(infoResponse, nil).AnyTimes()
+	nodeInfo := swarm.Node{ManagerStatus: &swarm.ManagerStatus{Addr: "1.2.3.4"}}
+	client.EXPECT().NodeInspectWithRaw(gomock.Any(), nodeID).Return(nodeInfo, nil, nil).AnyTimes()
+	client.EXPECT().Close().AnyTimes()
+
+	initTemplate := `{{/* totally not useful init script just for test*/}}{{ INDEX.Group }},{{ INDEX.Sequence }}`
+
+	properties := types.AnyString(`
+{
+ "Attachments": {"127.0.0.1": [{"ID": "a", "Type": "gpu"}]},
+ "InitScriptTemplateURL" : "str://` + initTemplate + `"
+}
+`)
+
+	index := group_types.Index{Group: group.ID("group"), Sequence: 100}
+	id := instance.LogicalID("127.0.0.1")
+	details, err := flavorImpl.Prepare(properties,
+		instance.Spec{Tags: map[string]string{"a": "b"}, LogicalID: &id},
+		group_types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1"}},
+		index)
+	require.NoError(t, err)
+	require.Equal(t, fmt.Sprintf("%v,%v", index.Group, index.Sequence), details.Init)
+
+	close(managerStop)
+}

examples/flavor/swarm/manager.go

@@ -55,6 +55,7 @@ func (s *ManagerFlavor) Validate(flavorProperties *types.Any, allocation group_t
 
 // Prepare sets up the provisioner / instance plugin's spec based on information about the swarm to join.
 func (s *ManagerFlavor) Prepare(flavorProperties *types.Any,
-	instanceSpec instance.Spec, allocation group_types.AllocationMethod) (instance.Spec, error) {
-	return s.baseFlavor.prepare("manager", flavorProperties, instanceSpec, allocation)
+	instanceSpec instance.Spec, allocation group_types.AllocationMethod,
+	index group_types.Index) (instance.Spec, error) {
+	return s.baseFlavor.prepare("manager", flavorProperties, instanceSpec, allocation, index)
 }

examples/flavor/swarm/worker.go

@@ -33,8 +33,9 @@ type WorkerFlavor struct {
 
 // Prepare sets up the provisioner / instance plugin's spec based on information about the swarm to join.
 func (s *WorkerFlavor) Prepare(flavorProperties *types.Any, instanceSpec instance.Spec,
-	allocation group_types.AllocationMethod) (instance.Spec, error) {
-	return s.baseFlavor.prepare("worker", flavorProperties, instanceSpec, allocation)
+	allocation group_types.AllocationMethod,
+	index group_types.Index) (instance.Spec, error) {
+	return s.baseFlavor.prepare("worker", flavorProperties, instanceSpec, allocation, index)
 }
 
 // Drain in the case of worker will force a node removal in the swarm.

examples/flavor/vanilla/flavor.go

@@ -44,7 +44,8 @@ func (f vanillaFlavor) Drain(flavorProperties *types.Any, inst instance.Descript
 
 func (f vanillaFlavor) Prepare(flavor *types.Any,
 	instance instance.Spec,
-	allocation group_types.AllocationMethod) (instance.Spec, error) {
+	allocation group_types.AllocationMethod,
+	index group_types.Index) (instance.Spec, error) {
 
 	s := Spec{}
 	err := flavor.Decode(&s)