config: Add VM-based container configuration section

This adds a section to describe VM based container configurations to be
used by OCI runtimes using hardware virtualization to provide another
layer of isolation.

As part of this section we define 3 entries:

- A virtual machine root image opbject. This is the guest image that
  contains the virtual machine root filesystem. The container image will
  be mounted on top of that filesystem.

- A virtual machine kernel object. This is the kernel that will boot
  inside the virtual machine. The object describes the host kernel image
  path, additional parameters and an optional guest initrd for the
  kernel to use.

- A virtual machine hypervisor object. This is the hypervisor that will
  manage the container virtual machine from the host. The object
  describe a hypervisor binary path and some additional parameters.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
Signed-off-by: Samuel Ortiz <sameo@linux.intel.com>

config-vm.md

@@ -0,0 +1,51 @@
+# <a name="VirtualMachineSpecificContainerConfiguration" /> Virtual-machine-specific Container Configuration
+
+Virtual-machine-based containers require additional configuration to that specified in the [base spec configuration](config.md).
+
+This **optional** configuration is specified in a "VM" object:
+
+* **`hypervisor`** (object, OPTIONAL) specifies details of the hypervisor that manages the container virtual machine.
+* **`kernel`** (object, REQUIRED) specifies details of the kernel to boot the container virtual machine with.
+* **`image`** (object, OPTIONAL) specifies details of the image that contains the root filesystem for the container virtual machine.
+
+## <a name="HypervisorObject" /> Hypervisor Object
+
+Used by virtual-machine-based runtimes only.
+
+* **`path`** (string, REQUIRED) specifies the host path to the hypervisor used to manage the container virtual machine.
+* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the hypervisor.
+
+## <a name="KernelObject" /> Kernel Object
+
+Used by virtual-machine-based runtimes only.
+
+* **`path`** (string, REQUIRED) specifies the host path to the kernel used to boot the container virtual machine. This is an absolute path on the host.
+* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the kernel.
+* **`initrd`** (string, OPTIONAL) specifies the host path to an initial ramdisk to be used by the container virtual machine.
+
+## <a name="ImageObject" /> Image Object
+
+Used by virtual-machine-based runtimes only.
+
+* **`path`** (string, REQUIRED) specifies the absolute host path to the container virtual machine root image. This image contains the root filesystem that the virtual machine **`kernel`** will boot into, not to be confused with the container root filesystem itself. The latter, as 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.
+
+
+## <a name="FullyPopulatedVMExample" /> Example of a fully-populated `VM` object
+
+```json
+"vm": {
+    "hypervisor": {
+        "path": "/path/to/vmm",
+        "parameters": ["opts1=foo", "opts2=bar"]
+    },
+    "kernel": {
+        "path": "/path/to/vmlinuz",
+        "parameters": ["foo=bar", "hello world"],
+        "initrd": "/path/to/initrd.img"
+    },
+    "image": {
+        "path": "/path/to/vm/rootfs.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.
 
+## <a name="VirtualMachine" />VM
+
+VM is an optional object used by virtual-machine-based containers.
+
+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/config-vm.json

@@ -0,0 +1,66 @@
+{
+    "vm": {
+        "description": "configuration for virtual-machine-based containers",
+        "id": "https://opencontainers.org/schema/bundle/vm",
+        "type": "object",
+        "required" : [
+            "kernel",
+        ],
+        "properties": {
+	    "hypervisor": {
+                "description": "hypervisor config used by VM-based containers",
+                "id": "https://opencontainers.org/schema/bundle/vm/hypervisor",
+                "type": "object",
+                "required": [
+                    "path"
+                ],
+                "properties": {
+                    "path": {
+	                "id": "https://opencontainers.org/schema/bundle/vm/hypervisor/path",
+                        "$ref": "defs.json#/definitions/FilePath"
+                    },
+                    "parameters": {
+                        "id": "https://opencontainers.org/schema/bundle/vm/hypervisor/parameters",
+			"$ref": "defs.json#/definitions/ArrayOfStrings"
+                    }
+                }
+            },
+	    "kernel": {
+                "description": "kernel config used by VM-based containers",
+                "id": "https://opencontainers.org/schema/bundle/vm/kernel",
+                "type": "object",
+                "required": [
+                    "path"
+                ],
+                "properties": {
+                    "path": {
+                        "id": "https://opencontainers.org/schema/bundle/vm/kernel/path",
+                        "$ref": "defs.json#/definitions/FilePath"
+                    },
+                    "parameters": {
+                        "id": "https://opencontainers.org/schema/bundle/vm/kernel/parameters",
+			"$ref": "defs.json#/definitions/ArrayOfStrings"
+                    },
+                    "initrd": {
+                        "id": "https://opencontainers.org/schema/bundle/vm/kernel/initrd",
+                        "$ref": "defs.json#/definitions/FilePath"
+                    }
+                }
+	    },
+	    "image": {
+                "description": "root image config used by VM-based containers",
+                "id": "https://opencontainers.org/schema/bundle/vm/image",
+                "type": "object",
+                "required": [
+                    "path"
+                ],
+                "properties": {
+                    "path": {
+                        "id": "https://opencontainers.org/schema/bundle/vm/image/path",
+                        "$ref": "defs.json#/definitions/FilePath"
+                    }
+                }
+            }
+        }
+    }
+}

specs-go/config.go

@@ -25,6 +25,8 @@ type Spec struct {
 	Solaris *Solaris `json:"solaris,omitempty" platform:"solaris"`
 	// Windows is platform-specific configuration for Windows based containers.
 	Windows *Windows `json:"windows,omitempty" platform:"windows"`
+	// VM specifies configuration for virtual-machine-based containers.
+	VM VM `json:"vm,omitempty"`
 }
 
 // Process contains information to start a specific application inside the container.
@@ -487,6 +489,40 @@ type WindowsHyperV struct {
 	UtilityVMPath string `json:"utilityVMPath,omitempty"`
 }
 
+// VM contains information for virtual-machine-based containers.
+type VM struct {
+	// Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers.
+	Hypervisor VMHypervisor `json:"hypervisor"`
+	// Kernel specifies kernel-related configuration for virtual-machine-based containers.
+	Kernel VMKernel `json:"kernel"`
+	// Image specifies guest image related configuration for virtual-machine-based containers.
+	Image VMImage `json:"image"`
+}
+
+// VMHypervisor contains information about the hypervisor to use for a virtual machine.
+type VMHypervisor struct {
+	// Path is the host path to the hypervisor used to manage the virtual machine.
+	Path string `json:"path"`
+	// Parameters specifies parameters to pass to the hypervisor.
+	Parameters string `json:"parameters,omitempty"`
+}
+
+// VMKernel contains information about the kernel to use for a virtual machine.
+type VMKernel struct {
+	// Path is the host 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 host path to an initial ramdisk to be used by the kernel.
+	InitRD string `json:"initrd,omitempty"`
+}
+
+// VMImage contains information about the virtual machine root image.
+type VMImage struct {
+	// Path is the host path to the root image that the VM kernel would boot into.
+	Path string `json:"path"`
+}
+
 // LinuxSeccomp represents syscall restrictions
 type LinuxSeccomp struct {
 	DefaultAction LinuxSeccompAction `json:"defaultAction"`