diff --git a/config-vm.md b/config-vm.md new file mode 100644 index 000000000..5e2a4d827 --- /dev/null +++ b/config-vm.md @@ -0,0 +1,63 @@ +# Virtual-machine-specific Container Configuration + +This section describes the schema for the [virtual-machine-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md). +The virtual-machine container specification provides additional configuration for the hypervisor, kernel, and image. + +## Hypervisor Object + +**`hypervisor`** (object, OPTIONAL) specifies details of the hypervisor that manages the container virtual machine. +* **`path`** (string, REQUIRED) path to the hypervisor binary that manages the container virtual machine. + This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace). +* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the hypervisor. + +### Example + +```json + "hypervisor": { + "path": "/path/to/vmm", + "parameters": ["opts1=foo", "opts2=bar"] + } +``` + +## Kernel Object + +**`kernel`** (object, REQUIRED) specifies details of the kernel to boot the container virtual machine with. +* **`path`** (string, REQUIRED) path to the kernel used to boot the container virtual machine. + This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace). +* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the kernel. +* **`initrd`** (string, OPTIONAL) path to an initial ramdisk to be used by the container virtual machine. + This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace). + +### Example + +```json + "kernel": { + "path": "/path/to/vmlinuz", + "parameters": ["foo=bar", "hello world"], + "initrd": "/path/to/initrd.img" + } +``` + +## Image Object + +**`image`** (object, OPTIONAL) specifies details of the image that contains the root filesystem for the container virtual machine. +* **`path`** (string, REQUIRED) path to the container virtual machine root image. + This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace). +* **`type`** (string, REQUIRED) type of the container virtual machine root image. The following disk image formats are supported: + * **`raw`** raw disk image format. Unset values for `type` will default to that format. + * **`qcow2`** QEMU image format. + * **`qcow`** Old QEMU image format. + * **`vdi`** VirtualBox 1.1 compatible image format. + * **`vmdk`** VMware compatible image format. + * **`vhd`** Virtual Hard Disk image format. + + 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. + +### Example + +```json + "image": { + "path": "/path/to/vm/rootfs.img", + "type": "raw" + } +``` diff --git a/config.md b/config.md index 06801f5dd..87039d256 100644 --- a/config.md +++ b/config.md @@ -349,6 +349,8 @@ For Windows based systems the user structure has the following fields: This MUST be set if the target platform of this spec is `windows`. * **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md). This MAY be set if the target platform of this spec is `solaris`. +* **`vm`** (object, OPTIONAL) [Virtual-machine-specific configuration](config-vm.md). + This MAY be set if the target platform and architecture of this spec support hardware virtualization. ### Example (Linux) diff --git a/schema/config-schema.json b/schema/config-schema.json index 9ef6ec2e0..f90bd4b7d 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -163,6 +163,9 @@ }, "windows": { "$ref": "config-windows.json#/windows" + }, + "vm": { + "$ref": "config-vm.json#/vm" } }, "required": [ diff --git a/schema/config-vm.json b/schema/config-vm.json new file mode 100644 index 000000000..09f764c27 --- /dev/null +++ b/schema/config-vm.json @@ -0,0 +1,60 @@ +{ + "vm": { + "description": "configuration for virtual-machine-based containers", + "type": "object", + "required": [ + "kernel" + ], + "properties": { + "hypervisor": { + "description": "hypervisor config used by VM-based containers", + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "$ref": "defs.json#/definitions/FilePath" + }, + "parameters": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + } + } + }, + "kernel": { + "description": "kernel config used by VM-based containers", + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "$ref": "defs.json#/definitions/FilePath" + }, + "parameters": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, + "initrd": { + "$ref": "defs.json#/definitions/FilePath" + } + } + }, + "image": { + "description": "root image config used by VM-based containers", + "type": "object", + "required": [ + "path", + "type" + ], + "properties": { + "path": { + "$ref": "defs.json#/definitions/FilePath" + }, + "type": { + "$ref": "defs-vm.json#/definitions/RootImageType" + } + } + } + } + } +} diff --git a/schema/defs-vm.json b/schema/defs-vm.json new file mode 100644 index 000000000..2e3971271 --- /dev/null +++ b/schema/defs-vm.json @@ -0,0 +1,15 @@ +{ + "definitions": { + "RootImageType": { + "type": "string", + "enum": [ + "raw", + "qcow2", + "qcow", + "vdi", + "vmdk", + "vhd" + ] + } + } +} diff --git a/spec.md b/spec.md index 8bbe2203d..684713adb 100644 --- a/spec.md +++ b/spec.md @@ -16,6 +16,7 @@ Platforms defined by this specification are: * `linux`: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md). * `solaris`: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md). * `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md). +* `vm`: [runtime.md](runtime.md), [config.md](config.md), and [config-vm.md](config-vm.md). # Table of Contents @@ -29,6 +30,7 @@ Platforms defined by this specification are: - [Linux-specific Configuration](config-linux.md) - [Solaris-specific Configuration](config-solaris.md) - [Windows-specific Configuration](config-windows.md) + - [Virtual-Machine-specific Configuration](config-vm.md) - [Glossary](glossary.md) # Notational Conventions diff --git a/specs-go/config.go b/specs-go/config.go index 841eacb2d..9c034c1f1 100644 --- a/specs-go/config.go +++ b/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" platform:"vm"` } // Process contains information to start a specific application inside the container. @@ -499,6 +501,42 @@ 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,omitempty"` + // 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,omitempty"` +} + +// 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"` + // Type is the root image format type (e.g. "qcow2", "raw", "vhd", etc). + Type string `json:"type"` +} + // LinuxSeccomp represents syscall restrictions type LinuxSeccomp struct { DefaultAction LinuxSeccompAction `json:"defaultAction"`