Add a Type field to Attachments (#316)

Signed-off-by: Bill Farner <[email protected]>

Author: wfarner

docs/plugins/instance.md

@@ -1,6 +1,6 @@
 # Instance plugin API
 
-<!-- SOURCE-CHECKSUM pkg/spi/instance/* 0c778e96cbeb32043532709412e15e6cc86778d7153c65b1d7422b9f0b5901c89362666bfdd75de7 -->
+<!-- SOURCE-CHECKSUM pkg/spi/instance/* 0c778e96cbeb32043532709412e15e6cc86778d7338393f886f528c3824986fc97cb27410aefd8e2 -->
 
 ## API
 
@@ -39,7 +39,7 @@ Provisions a new instance.
     "Tags": {"tag_key": "tag_value"},
     "Init": "",
     "LogicalID": "logical_id",
-    "Attachments": ["attachment_id"]
+    "Attachments": [{"ID": "attachment_id", "Type": "block-device"}]
   }
 }
 ```

docs/plugins/types.md

@@ -33,8 +33,11 @@ Fields:
 - `Properties`: A JSON object representing the Group.  The schema is defined by the Group plugin in use.
 
 ### Instance Attachment
-An identifier for an external entity associated with an Instance.  The meaning of Attachments and handling of Attachment
-IDs is defined by the Instance plugin.
+An external entity associated with an Instance.  The meaning of an Attachment is defined by the Instance plugin.
+
+Fields:
+- `ID`: A unique identifier for the Attachment
+- `Type`: An identifier for the kind of attachment.
 
 
 ### Instance Description

pkg/example/flavor/combo/flavor_test.go

@@ -28,7 +28,7 @@ var inst = instance.Spec{
 	Tags:        map[string]string{},
 	Init:        "",
 	LogicalID:   logicalID("id"),
-	Attachments: []instance.Attachment{"att1"},
+	Attachments: []instance.Attachment{{ID: "att1", Type: "nic"}},
 }
 
 func pluginLookup(plugins map[string]flavor.Plugin) group.FlavorPluginLookup {
@@ -72,15 +72,15 @@ func TestMergeBehavior(t *testing.T) {
 		Tags:        map[string]string{"a": "1", "c": "4"},
 		Init:        "init data a",
 		LogicalID:   inst.LogicalID,
-		Attachments: []instance.Attachment{"a"},
+		Attachments: []instance.Attachment{{ID: "a", Type: "nic"}},
 	}, nil)
 
 	b.EXPECT().Prepare(json.RawMessage(`{"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{"b"},
+		Attachments: []instance.Attachment{{ID: "b", Type: "gpu"}},
 	}, nil)
 
 	result, err := combo.Prepare(flavorProperties, inst, types.AllocationMethod{Size: 1})
@@ -91,7 +91,7 @@ func TestMergeBehavior(t *testing.T) {
 		Tags:        map[string]string{"a": "1", "b": "2", "c": "5"},
 		Init:        "init data a\ninit data b",
 		LogicalID:   inst.LogicalID,
-		Attachments: []instance.Attachment{"att1", "a", "b"},
+		Attachments: []instance.Attachment{{ID: "att1", Type: "nic"}, {ID: "a", Type: "nic"}, {ID: "b", Type: "gpu"}},
 	}
 	require.Equal(t, expected, result)
 }
@@ -103,7 +103,7 @@ func TestMergeNoLogicalID(t *testing.T) {
 		Properties:  jsonPtr("{}"),
 		Tags:        map[string]string{},
 		Init:        "",
-		Attachments: []instance.Attachment{"att1"},
+		Attachments: []instance.Attachment{{ID: "att1", Type: "nic"}},
 	}
 
 	ctrl := gomock.NewController(t)
@@ -136,15 +136,15 @@ func TestMergeNoLogicalID(t *testing.T) {
 		Tags:        map[string]string{"a": "1", "c": "4"},
 		Init:        "init data a",
 		LogicalID:   inst.LogicalID,
-		Attachments: []instance.Attachment{"a"},
+		Attachments: []instance.Attachment{{ID: "a", Type: "nic"}},
 	}, nil)
 
 	b.EXPECT().Prepare(json.RawMessage(`{"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{"b"},
+		Attachments: []instance.Attachment{{ID: "b", Type: "gpu"}},
 	}, nil)
 
 	result, err := combo.Prepare(flavorProperties, inst, types.AllocationMethod{Size: 1})
@@ -155,7 +155,7 @@ func TestMergeNoLogicalID(t *testing.T) {
 		Tags:        map[string]string{"a": "1", "b": "2", "c": "5"},
 		Init:        "init data a\ninit data b",
 		LogicalID:   inst.LogicalID,
-		Attachments: []instance.Attachment{"att1", "a", "b"},
+		Attachments: []instance.Attachment{{ID: "att1", Type: "nic"}, {ID: "a", Type: "nic"}, {ID: "b", Type: "gpu"}},
 	}
 	require.Equal(t, expected, result)
 }

pkg/example/flavor/swarm/flavor.go

@@ -20,8 +20,9 @@ import (
 type nodeType string
 
 const (
-	worker  nodeType = "worker"
-	manager nodeType = "manager"
+	worker        nodeType = "worker"
+	manager       nodeType = "manager"
+	ebsAttachment string   = "ebs"
 )
 
 // NewSwarmFlavor creates a flavor.Plugin that creates manager and worker nodes connected in a swarm.
@@ -61,14 +62,33 @@ func validateIDsAndAttachments(logicalIDs []instance.LogicalID, attachments map[
 		}
 	}
 
+	// Only EBS attachments are supported.
+	for _, atts := range attachments {
+		for _, attachment := range atts {
+			if attachment.Type == "" {
+				return fmt.Errorf(
+					"Attachment Type %s must be specified for '%s'",
+					ebsAttachment,
+					attachment.ID)
+			}
+
+			if attachment.Type != ebsAttachment {
+				return fmt.Errorf(
+					"Invalid attachment Type '%s', only %s is supported",
+					attachment.Type,
+					ebsAttachment)
+			}
+		}
+	}
+
 	// Each attachment may only be used once.
-	allAttachments := map[instance.Attachment]bool{}
-	for _, att := range attachments {
-		for _, attachment := range att {
-			if _, exists := allAttachments[attachment]; exists {
-				return fmt.Errorf("Attachment %v specified more than once", attachment)
+	allAttachmentIDs := map[string]bool{}
+	for _, atts := range attachments {
+		for _, attachment := range atts {
+			if _, exists := allAttachmentIDs[attachment.ID]; exists {
+				return fmt.Errorf("Attachment %v specified more than once", attachment.ID)
 			}
-			allAttachments[attachment] = true
+			allAttachmentIDs[attachment.ID] = true
 		}
 	}
 
@@ -100,7 +120,7 @@ func (s swarmFlavor) Validate(flavorProperties json.RawMessage, allocation types
 	if properties.Type == manager {
 		for _, id := range allocation.LogicalIDs {
 			if att, exists := properties.Attachments[id]; !exists || len(att) == 0 {
-				log.Warnf("LogicalID %s has no attachments, which is needed for durability")
+				log.Warnf("LogicalID %s has no attachments, which is needed for durability", id)
 			}
 		}
 	}

pkg/example/flavor/swarm/flavor_test.go

@@ -33,7 +33,7 @@ func TestValidate(t *testing.T) {
 		json.RawMessage(`{
 			"Type": "manager",
 			"DockerRestartCommand": "systemctl restart docker",
-			"Attachments": {"127.0.0.1": ["a", "b"]}}`),
+			"Attachments": {"127.0.0.1": [{"ID": "a", "Type": "ebs"}, {"ID": "b", "Type": "ebs"}]}}`),
 		types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1"}}))
 
 	require.Error(t, swarmFlavor.Validate(json.RawMessage(`{"type": "other"}`), types.AllocationMethod{Size: 5}))
@@ -50,10 +50,20 @@ func TestValidate(t *testing.T) {
 		json.RawMessage(`{
 			"Type": "manager",
 			"DockerRestartCommand": "systemctl restart docker",
-			"Attachments": {"127.0.0.1": ["a"], "127.0.0.2": ["a"]}}`),
+			"Attachments": {"127.0.0.1": [{"ID": "a", "Type": "ebs"}], "127.0.0.2": [{"ID": "a", "Type": "ebs"}]}}`),
 		types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1", "127.0.0.2", "127.0.0.3"}})
 	require.Error(t, err)
 	require.Equal(t, "Attachment a specified more than once", err.Error())
+
+	// Unsupported Attachment Type.
+	err = swarmFlavor.Validate(
+		json.RawMessage(`{
+			"Type": "manager",
+			"DockerRestartCommand": "systemctl restart docker",
+			"Attachments": {"127.0.0.1": [{"ID": "a", "Type": "keyboard"}]}}`),
+		types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1"}})
+	require.Error(t, err)
+	require.Equal(t, "Invalid attachment Type 'keyboard', only ebs is supported", err.Error())
 }
 
 func TestWorker(t *testing.T) {
@@ -142,7 +152,7 @@ func TestManager(t *testing.T) {
 
 	id := instance.LogicalID("127.0.0.1")
 	details, err := flavorImpl.Prepare(
-		json.RawMessage(`{"Type": "manager", "Attachments": {"127.0.0.1": ["a"]}}`),
+		json.RawMessage(`{"Type": "manager", "Attachments": {"127.0.0.1": [{"ID": "a", "Type": "gpu"}]}}`),
 		instance.Spec{Tags: map[string]string{"a": "b"}, LogicalID: &id},
 		types.AllocationMethod{LogicalIDs: []instance.LogicalID{"127.0.0.1"}})
 	require.NoError(t, err)
@@ -157,7 +167,7 @@ func TestManager(t *testing.T) {
 	require.NotContains(t, details.Init, swarmInfo.JoinTokens.Worker)
 	require.Contains(t, details.Init, nodeInfo.ManagerStatus.Addr)
 
-	require.Equal(t, []instance.Attachment{"a"}, details.Attachments)
+	require.Equal(t, []instance.Attachment{{ID: "a", Type: "gpu"}}, details.Attachments)
 
 	// An instance with no association information is considered unhealthy.
 	health, err := flavorImpl.Healthy(json.RawMessage("{}"), instance.Description{})

pkg/spi/instance/types.go

@@ -18,13 +18,29 @@ type Description struct {
 type LogicalID string
 
 // Attachment is an identifier for a resource to attach to an instance.
-type Attachment string
+type Attachment struct {
+	// ID is the unique identifier for the attachment.
+	ID string
+
+	// Type is the kind of attachment.  This allows multiple attachments of different types, with the supported
+	// types defined by the plugin.
+	Type string
+}
 
 // Spec is a specification of an instance to be provisioned
 type Spec struct {
-	Properties  *json.RawMessage
-	Tags        map[string]string
-	Init        string
-	LogicalID   *LogicalID
+	// Properties is the opaque instance plugin configuration.
+	Properties *json.RawMessage
+
+	// Tags are metadata that describes an instance.
+	Tags map[string]string
+
+	// Init is the boot script to execute when the instance is created.
+	Init string
+
+	// LogicalID is the logical identifier assigned to this instance, which may be absent.
+	LogicalID *LogicalID
+
+	// Attachments are instructions for external entities that should be attached to the instance.
 	Attachments []Attachment
 }