From beb7adb71febe3223c3f1fd50b4c07c58f5f0722 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 29 Nov 2016 11:00:34 +0000 Subject: [PATCH] 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 filesystem path. This is the guest image that will be the container host root filesystem inside the virtual machine. - 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 Signed-off-by: Samuel Ortiz --- config-vm.md | 49 ++++++++++++++++++++++++++++++ config.md | 6 ++++ schema/config-schema.json | 3 ++ schema/config-vm.json | 64 +++++++++++++++++++++++++++++++++++++++ specs-go/config.go | 31 +++++++++++++++++++ 5 files changed, 153 insertions(+) create mode 100644 config-vm.md create mode 100644 schema/config-vm.json diff --git a/config-vm.md b/config-vm.md new file mode 100644 index 000000000..0824abfba --- /dev/null +++ b/config-vm.md @@ -0,0 +1,49 @@ +# 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: + +* **`imagePath`** (string, REQUIRED) host path to file that represents the root filesystem for the container virtual machine. +* **`kernel`** (object, REQUIRED) specifies details of the kernel to boot the container virtual machine with. +* **`hypervisor`** (object, REQUIRED) specifies details of the hypervisor that manages the container virtual machine. + +Note that `imagePath` refers to an absolute 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 host path to the container virtual machine root filesystem. This is the root filesystem that the virtual machine **`kernel`** will boot into. +* 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 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. +* **`parameters`** (string, OPTIONAL) specifies a space-separated list 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. + +## 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`** (string, OPTIONAL) specifies a space-separated list of parameters to pass to the hypervisor. + +## 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" + }, + "hypervisor": { + "path": "/path/to/vmm", + "parameters": "opts=foo", + }, +} +``` diff --git a/config.md b/config.md index 06801f5dd..27d41e25c 100644 --- a/config.md +++ b/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 containers. + +See [Virtual-machine-specific schema](config-vm.md) for details. + ## Configuration Schema Example Here is a full example `config.json` for reference. diff --git a/schema/config-schema.json b/schema/config-schema.json index 8fe1896de..41c0842f7 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -191,6 +191,9 @@ } } }, + "vm": { + "$ref": "schema-vm.json#/vm" + }, "linux": { "$ref": "config-linux.json#/linux" }, diff --git a/schema/config-vm.json b/schema/config-vm.json new file mode 100644 index 000000000..339be8708 --- /dev/null +++ b/schema/config-vm.json @@ -0,0 +1,64 @@ +{ + "vm": { + "description": "configuration for virtual-machine-based containers", + "id": "https://opencontainers.org/schema/bundle/vm", + "type": "object", + "required" : [ + "imagePath", + "kernel", + "hypervisor" + ], + "properties": { + "imagePath": { + "description": "host path to rootfs image on host system which is used for VM-based containers", + "id": "https://opencontainers.org/schema/bundle/vm/imagePath", + "type": "string" + }, + "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", + "description": "host 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": "host path to initial ramdisk image", + "id": "https://opencontainers.org/schema/bundle/vm/kernel/initrd", + "type": "string" + } + } + }, + "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", + "description": "host path to hypervisor binary", + "type": "string" + }, + "parameters": { + "description": "space-separated list of hypervisor parameters", + "id": "https://opencontainers.org/schema/bundle/vm/hypervisor/parameters", + "type": "string" + } + } + } + } + } +} diff --git a/specs-go/config.go b/specs-go/config.go index 71c9fa773..8918a2cc3 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"` } // Process contains information to start a specific application inside the container. @@ -487,6 +489,35 @@ type WindowsHyperV struct { UtilityVMPath string `json:"utilityVMPath,omitempty"` } +// VM contains information for virtual-machine-based containers. +type VM struct { + // Kernel specifies kernel-related configuration for virtual-machine-based containers. + Kernel VMKernel `json:"kernel"` + // Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers. + Hypervisor VMHypervisor `json:"hypervisor"` + // ImagePath is the host path to the root filesystem image on the host which can be used by a virtual-machine-based container. + ImagePath string `json:"imagePath"` +} + +// 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"` +} + +// 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"` +} + + // LinuxSeccomp represents syscall restrictions type LinuxSeccomp struct { DefaultAction LinuxSeccompAction `json:"defaultAction"`