diff --git a/config-vm.md b/config-vm.md new file mode 100644 index 000000000..ff551d317 --- /dev/null +++ b/config-vm.md @@ -0,0 +1,68 @@ +# 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). +* **`format`** (string, REQUIRED) format of the container virtual machine root image. Commonly supported formats are: + * **`raw`** [raw disk image format][raw-image-format]. Unset values for `format` will default to that format. + * **`qcow2`** [QEMU image format][qcow2-image-format]. + * **`vdi`** [VirtualBox 1.1 compatible image format][vdi-image-format]. + * **`vmdk`** [VMware compatible image format][vmdk-image-format]. + * **`vhd`** [Virtual Hard Disk image format][vhd-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", + "format": "raw" + } +``` + +[raw-image-format]: https://en.wikipedia.org/wiki/IMG_(file_format) +[qcow2-image-format]: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qcow2.txt;hb=HEAD +[vdi-image-format]: https://forensicswiki.org/wiki/Virtual_Disk_Image_(VDI) +[vmdk-image-format]: http://www.vmware.com/app/vmdk/?src=vmdk +[vhd-image-format]: https://github.com/libyal/libvhdi/blob/master/documentation/Virtual%20Hard%20Disk%20(VHD)%20image%20format.asciidoc diff --git a/config.md b/config.md index 333b98300..21b18e805 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..6b1fb4baf --- /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", + "format" + ], + "properties": { + "path": { + "$ref": "defs.json#/definitions/FilePath" + }, + "format": { + "$ref": "defs-vm.json#/definitions/RootImageFormat" + } + } + } + } + } +} diff --git a/schema/defs-vm.json b/schema/defs-vm.json new file mode 100644 index 000000000..4dae91506 --- /dev/null +++ b/schema/defs-vm.json @@ -0,0 +1,14 @@ +{ + "definitions": { + "RootImageFormat": { + "type": "string", + "enum": [ + "raw", + "qcow2", + "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 ad265bf2c..c9e848db6 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"` + // Format is the root image format type (e.g. "qcow2", "raw", "vhd", etc). + Format string `json:"format"` +} + // LinuxSeccomp represents syscall restrictions type LinuxSeccomp struct { DefaultAction LinuxSeccompAction `json:"defaultAction"`