Add VM-based runtime configuration details.

Add configuration details for virtual-machine-based runtimes.

Signed-off-by: James O. D. Hunt <[email protected]>

Author: James O. D. Hunt

config-vm.md

@@ -0,0 +1,37 @@
+# Virtual-machine-specific Configuration
+
+Virtual-machine-based runtimes require additional configuration to that specified in the [default spec configuration](config.md).
+
+This optional configuration is specified in a "VM" object:
+
+* **`imagePath`** (string, required) path to file that represents the root filesystem for the virtual machine.
+* **`kernel`** (object, required) specifies details of the kernel to boot the virtual machine with.
+
+Note that `imagePath` refers to a path on the host (outside of the virtual machine).
+This field is distinct from the **`path`** field in the [Root Configuration](config.md#Root-Configuration) section since in the context of a virtual-machine-based runtime:
+
+* **`imagePath`** will represent the root filesystem for the virtual machine.
+* The container root filesystem specified by **`path`** from the [Root Configuration](config.md#Root-Configuration) section will be mounted inside the virtual machine at a location chosen by the virtual-machine-based runtime.
+
+The virtual-machine-based runtime will use these two path fields to arrange for the **`path`** from the [Root Configuration](config.md#Root-Configuration) section to be presented to the process to run as the root filesystem.
+
+## Kernel
+
+Used by virtual-machine-based runtimes only.
+
+* **`path`** (string, required) specifies the path to the kernel used to boot the virtual machine.
+* **`parameters`** (string, optional) specifies a space-separated list of parameters to pass to the kernel.
+* **`initrd`** (string, optional) specifies the path to an initial ramdisk to be used by the virtual machine.
+
+## Example of a fully-populated `VM` object
+
+```json
+"vm": {
+    "imagePath": "path/to/rootfs.img",
+    "kernel": {
+        "path": "path/to/vmlinuz",
+        "parameters": "foo=bar hello world",
+        "initrd": "path/to/initrd.img"
+    },
+}
+```

config.md

@@ -462,6 +462,12 @@ Instead they MUST ignore unknown properties.
 Runtimes that are reading or processing this configuration file MUST generate an error when invalid or unsupported values are encountered.
 Unless support for a valid value is explicitly required, runtimes MAY choose which subset of the valid values it will support.
 
+## VM
+
+VM is an optional object used by virtual-machine-based runtimes.
+
+See [Virtual-machine-specific schema](config-vm.md) for details.
+
 ## Configuration Schema Example
 
 Here is a full example `config.json` for reference.

schema/config-schema.json

@@ -191,6 +191,9 @@
                 }
             }
         },
+        "vm": {
+            "$ref": "schema-vm.json#/vm"
+        },
         "linux": {
             "$ref": "config-linux.json#/linux"
         },

schema/schema-vm.json

@@ -0,0 +1,43 @@
+{
+    "vm": {
+        "description": "configuration for virtual-machine-based runtimes",
+        "id": "https://opencontainers.org/schema/bundle/vm",
+        "type": "object",
+        "required" : [
+            "imagePath",
+            "kernel"
+        ],
+        "properties": {
+            "imagePath": {
+                "description": "path to rootfs image on host system which is used for VM-based runtimes",
+                "id": "https://opencontainers.org/schema/bundle/vm/imagePath",
+                "type": "string"
+            },
+            "kernel": {
+                "description": "kernel config used by VM-based runtimes",
+                "id": "https://opencontainers.org/schema/bundle/vm/kernel",
+                "type": "object",
+                "required": [
+                    "path"
+                ],
+                "properties": {
+                    "path": {
+                        "id": "https://opencontainers.org/schema/bundle/vm/kernel/path",
+                        "description": "path to kernel image",
+                        "type": "string"
+                    },
+                    "parameters": {
+                        "description": "space-separated list of kernel parameters",
+                        "id": "https://opencontainers.org/schema/bundle/vm/kernel/parameters",
+                        "type": "string"
+                    },
+                    "initrd": {
+                        "description": "path to initial ramdisk image",
+                        "id": "https://opencontainers.org/schema/bundle/vm/kernel/initrd",
+                        "type": "string"
+                    }
+                }
+            }
+        }
+    }
+}

specs-go/config.go

@@ -18,6 +18,8 @@ type Spec struct {
 	Hooks *Hooks `json:"hooks,omitempty" platform:"linux,solaris"`
 	// Annotations contains arbitrary metadata for the container.
 	Annotations map[string]string `json:"annotations,omitempty"`
+	// VM specifies configuration for virtual-machine-based runtimes.
+	VM VM `json:"vm,omitempty"`
 
 	// Linux is platform-specific configuration for Linux based containers.
 	Linux *Linux `json:"linux,omitempty" platform:"linux"`
@@ -27,6 +29,24 @@ type Spec struct {
 	Windows *Windows `json:"windows,omitempty" platform:"windows"`
 }
 
+// VM contains information for virtual-machine-based runtimes.
+type VM struct {
+	// Kernel specifies kernel-related configuration for virtual-machine-based runtimes.
+	Kernel Kernel `json:"kernel"`
+	// ImagePath is the path to the root filesystem image on the host which can be used by a virtual-machine-based runtime.
+	ImagePath string `json:"imagePath"`
+}
+
+// Kernel contains information about the kernel to use for a virtual machine.
+type Kernel struct {
+	// Path is the path to the kernel used to boot the virtual machine.
+	Path string `json:"path"`
+	// Parameters specifies parameters to pass to the kernel.
+	Parameters string `json:"parameters,omitempty"`
+	// InitRd is the path to an initial ramdisk to be used by the kernel.
+	InitRd string `json:"initrd,omitempty"`
+}
+
 // Process contains information to start a specific application inside the container.
 type Process struct {
 	// Terminal creates an interactive terminal for the container.