From e01b694281ba619ec9f3a30e677c35d34eecc13a Mon Sep 17 00:00:00 2001 From: Craig Wilhite Date: Wed, 20 Jun 2018 13:32:06 -0700 Subject: [PATCH 1/3] config: Add Windows Devices to Schema Signed-off-by: Craig Wilhite 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'. --- config-windows.md | 28 ++++++++++++++++++++++++++++ schema/README.md | 1 + schema/config-windows.json | 6 ++++++ schema/defs-windows.json | 22 ++++++++++++++++++++++ specs-go/config.go | 10 ++++++++++ 5 files changed, 67 insertions(+) create mode 100644 schema/defs-windows.json diff --git a/config-windows.md b/config-windows.md index a2e5e5339..a40662f9c 100644 --- a/config-windows.md +++ b/config-windows.md @@ -19,6 +19,34 @@ The Windows container specification uses APIs provided by the Windows Host Compu } ``` +## 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" + } + ] + } +``` + ## Resources You can configure a container's resource limits via the OPTIONAL `resources` field of the Windows configuration. diff --git a/schema/README.md b/schema/README.md index 95f3c549e..fecc46741 100644 --- a/schema/README.md +++ b/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 diff --git a/schema/config-windows.json b/schema/config-windows.json index 04d2cfa1a..264cf2746 100644 --- a/schema/config-windows.json +++ b/schema/config-windows.json @@ -10,6 +10,12 @@ }, "minItems": 1 }, + "devices": { + "type": "array", + "items": { + "$ref": "defs-windows.json#/definitions/Device" + } + }, "resources": { "type": "object", "properties": { diff --git a/schema/defs-windows.json b/schema/defs-windows.json new file mode 100644 index 000000000..7ce00df0c --- /dev/null +++ b/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" + ] + } + } +} diff --git a/specs-go/config.go b/specs-go/config.go index c9e848db6..1bce349b1 100644 --- a/specs-go/config.go +++ b/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. From da8adc9528f705127e27e71bccd6df9c0bfd9cf9 Mon Sep 17 00:00:00 2001 From: Craig Wilhite Date: Mon, 2 Jul 2018 09:59:35 -0700 Subject: [PATCH 2/3] incorporating edits from JTerry's feedback Signed-off-by: Craig Wilhite --- specs-go/config.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs-go/config.go b/specs-go/config.go index 1bce349b1..8de39b923 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -433,7 +433,7 @@ 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 are the list of devices 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"` @@ -452,9 +452,9 @@ type Windows struct { // 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"` + ID string `json:"id"` // Device identifier type: "class", etc. - IdType string `json:"id_type"` + IDType string `json:"id_type"` } // WindowsResources has container runtime resource constraints for containers running on Windows. From 65fac2bf185a2ac335fd7a119104e0c05bcf6ac6 Mon Sep 17 00:00:00 2001 From: Craig Wilhite Date: Tue, 10 Jul 2018 14:00:50 -0700 Subject: [PATCH 3/3] Fix camelCasing on idType to align with other Windows spec conventions Signed-off-by: Craig Wilhite --- config-windows.md | 6 +++--- schema/defs-windows.json | 4 ++-- specs-go/config.go | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/config-windows.md b/config-windows.md index a40662f9c..5e9ea3b1c 100644 --- a/config-windows.md +++ b/config-windows.md @@ -26,7 +26,7 @@ The Windows container specification uses APIs provided by the Windows Host Compu 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]. +* **`idType`** *(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 @@ -37,11 +37,11 @@ Each entry has the following structure: "devices": [ { "id": "24E552D7-6523-47F7-A647-D3465BF1F5CA", - "id_type": "class" + "idType": "class" }, { "id": "5175d334-c371-4806-b3ba-71fd53c9258d", - "id_type": "class" + "idType": "class" } ] } diff --git a/schema/defs-windows.json b/schema/defs-windows.json index 7ce00df0c..63e0ac309 100644 --- a/schema/defs-windows.json +++ b/schema/defs-windows.json @@ -6,7 +6,7 @@ "id": { "type": "string" }, - "id_type": { + "idType": { "type": "string", "enum": [ "class" @@ -15,7 +15,7 @@ }, "required": [ "id", - "id_type" + "idType" ] } } diff --git a/specs-go/config.go b/specs-go/config.go index 8de39b923..7781c5361 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -454,7 +454,7 @@ type WindowsDevice struct { // Device identifier: interface class GUID, etc. ID string `json:"id"` // Device identifier type: "class", etc. - IDType string `json:"id_type"` + IDType string `json:"idType"` } // WindowsResources has container runtime resource constraints for containers running on Windows.