config: Add Windows Devices to Schema

Signed-off-by: Craig Wilhite <[email protected]>

This adds Windows Device support to the OCI runtime-spec: code, JSON
schema and markdown documentation. This is a first step in our approach
to lighting up access to host devices for Windows Server containers.

Devices in Windows implement any number of interface class GUIDs. By
configuring a container with a device interface class GUID, we will
plug all devices on the host that implement the interface class GUID
into the device namespace of the container.

While this approach does not allow for the speciication of a single,
particular device, our schema definition is defined to be flexible;
we interpret the 'id' of the device passed in based upon the 'id_type'.

Author: cwilhit

config-windows.md

@@ -19,6 +19,34 @@ The Windows container specification uses APIs provided by the Windows Host Compu
     }
 ```
 
+## <a name="configWindowsDevices" />Devices
+
+**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
+
+Each entry has the following structure:
+
+* **`id`** *(string, REQUIRED)* - specifies the device which the runtime MUST make available in the container.
+* **`id_type`** *(string, REQUIRED)* - tells the runtime how to interpret `id`. Today, Windows only supports a value of `class`, which identifies `id` as a [device interface class GUID][interfaceGUID].
+
+[interfaceGUID]: https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes
+
+### Example
+
+```json
+    "windows": {
+        "devices": [
+            {
+                "id": "24E552D7-6523-47F7-A647-D3465BF1F5CA",
+                "id_type": "class"
+            },
+            {
+                "id": "5175d334-c371-4806-b3ba-71fd53c9258d",
+                "id_type": "class"
+            }
+        ]
+    }
+```
+
 ## <a name="configWindowsResources" />Resources
 
 You can configure a container's resource limits via the OPTIONAL `resources` field of the Windows configuration.

schema/README.md

@@ -13,6 +13,7 @@ The layout of the files is as follows:
 * [state-schema.json](state-schema.json) - the primary entrypoint for the [state JSON](../runtime.md#state) schema
 * [defs.json](defs.json) - definitions for general types
 * [defs-linux.json](defs-linux.json) - definitions for Linux-specific types
+* [defs-windows.json](defs-windows.json) - definitions for Windows-specific types
 * [validate.go](validate.go) - validation utility source code
 
 

schema/config-windows.json

@@ -10,6 +10,12 @@
                 },
                 "minItems": 1
             },
+            "devices": {
+                "type": "array",
+                "items": {
+                    "$ref": "defs-windows.json#/definitions/Device"
+                }
+            },
             "resources": {
                 "type": "object",
                 "properties": {

schema/defs-windows.json

@@ -0,0 +1,22 @@
+{
+    "definitions": {
+        "Device": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "id_type": {
+                    "type": "string",
+                    "enum": [
+                        "class"
+                    ]
+                }
+            },
+            "required": [
+                "id",
+                "id_type"
+            ]
+        }
+    }
+}

specs-go/config.go

@@ -433,6 +433,8 @@ type SolarisAnet struct {
 type Windows struct {
 	// LayerFolders contains a list of absolute paths to directories containing image layers.
 	LayerFolders []string `json:"layerFolders"`
+	// Devices are a list of interface class GUIDs for which device objects need to be mapped into the container.
+	Devices []WindowsDevice `json:"devices,omitempty"`
 	// Resources contains information for handling resource constraints for the container.
 	Resources *WindowsResources `json:"resources,omitempty"`
 	// CredentialSpec contains a JSON object describing a group Managed Service Account (gMSA) specification.
@@ -447,6 +449,14 @@ type Windows struct {
 	Network *WindowsNetwork `json:"network,omitempty"`
 }
 
+// WindowsDevice represents information about a host device to be mapped into the container.
+type WindowsDevice struct {
+	// Device identifier: interface class GUID, etc.
+	Id string `json:"id"`
+	// Device identifier type: "class", etc.
+	IdType string `json:"id_type"`
+}
+
 // WindowsResources has container runtime resource constraints for containers running on Windows.
 type WindowsResources struct {
 	// Memory restriction configuration.