Skip to content

Commit 3e939f0

Browse files
James O. D. HuntSamuel Ortiz
James O. D. Hunt
authored and
Samuel Ortiz
committed
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>
1 parent fa4b36a commit 3e939f0

7 files changed

Lines changed: 183 additions & 0 deletions

File tree

‎config-vm.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# <a name="VirtualMachineSpecificContainerConfiguration" /> Virtual-machine-specific Container Configuration
2+
3+
This section describes the schema for the [virtual-machine-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
4+
The virtual-machine container specification provides additional configuration for the hypervisor, kernel, and image.
5+
6+
## <a name="HypervisorObject" /> Hypervisor Object
7+
8+
**`hypervisor`** (object, OPTIONAL) specifies details of the hypervisor that manages the container virtual machine.
9+
* **`path`** (string, REQUIRED) path to the hypervisor binary that manages the container virtual machine.
10+
This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace).
11+
* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the hypervisor.
12+
13+
### Example
14+
15+
```json
16+
"hypervisor": {
17+
"path": "/path/to/vmm",
18+
"parameters": ["opts1=foo", "opts2=bar"]
19+
}
20+
```
21+
22+
## <a name="KernelObject" /> Kernel Object
23+
24+
**`kernel`** (object, REQUIRED) specifies details of the kernel to boot the container virtual machine with.
25+
* **`path`** (string, REQUIRED) path to the kernel used to boot the container virtual machine.
26+
This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace).
27+
* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the kernel.
28+
* **`initrd`** (string, OPTIONAL) path to an initial ramdisk to be used by the container virtual machine.
29+
This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace).
30+
31+
### Example
32+
33+
```json
34+
"kernel": {
35+
"path": "/path/to/vmlinuz",
36+
"parameters": ["foo=bar", "hello world"],
37+
"initrd": "/path/to/initrd.img"
38+
}
39+
```
40+
41+
## <a name="ImageObject" /> Image Object
42+
43+
**`image`** (object, OPTIONAL) specifies details of the image that contains the root filesystem for the container virtual machine.
44+
* **`path`** (string, REQUIRED) path to the container virtual machine root image.
45+
This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace).
46+
* **`type`** (string, REQUIRED) type of the container virtual machine root image. The following disk image formats are supported:
47+
* **`raw`** raw disk image format. Unset values for `type` will default to that format.
48+
* **`qcow2`** QEMU image format.
49+
* **`qcow`** Old QEMU image format.
50+
* **`vdi`** VirtualBox 1.1 compatible image format.
51+
* **`vmdk`** VMware compatible image format.
52+
* **`vhd`** Virtual Hard Disk image format.
53+
54+
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.
55+
56+
### Example
57+
58+
```json
59+
"image": {
60+
"path": "/path/to/vm/rootfs.img",
61+
"type": "raw"
62+
}
63+
```

‎config.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,8 @@ For Windows based systems the user structure has the following fields:
349349
This MUST be set if the target platform of this spec is `windows`.
350350
* **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md).
351351
This MAY be set if the target platform of this spec is `solaris`.
352+
* **`vm`** (object, OPTIONAL) [Virtual-machine-specific configuration](config-vm.md).
353+
This MAY be set if the target platform and architecture of this spec support hardware virtualization.
352354

353355
### Example (Linux)
354356

‎schema/config-schema.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,9 @@
163163
},
164164
"windows": {
165165
"$ref": "config-windows.json#/windows"
166+
},
167+
"vm": {
168+
"$ref": "config-vm.json#/vm"
166169
}
167170
},
168171
"required": [

‎schema/config-vm.json‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{
2+
"vm": {
3+
"description": "configuration for virtual-machine-based containers",
4+
"type": "object",
5+
"required": [
6+
"kernel"
7+
],
8+
"properties": {
9+
"hypervisor": {
10+
"description": "hypervisor config used by VM-based containers",
11+
"type": "object",
12+
"required": [
13+
"path"
14+
],
15+
"properties": {
16+
"path": {
17+
"$ref": "defs.json#/definitions/FilePath"
18+
},
19+
"parameters": {
20+
"$ref": "defs.json#/definitions/ArrayOfStrings"
21+
}
22+
}
23+
},
24+
"kernel": {
25+
"description": "kernel config used by VM-based containers",
26+
"type": "object",
27+
"required": [
28+
"path"
29+
],
30+
"properties": {
31+
"path": {
32+
"$ref": "defs.json#/definitions/FilePath"
33+
},
34+
"parameters": {
35+
"$ref": "defs.json#/definitions/ArrayOfStrings"
36+
},
37+
"initrd": {
38+
"$ref": "defs.json#/definitions/FilePath"
39+
}
40+
}
41+
},
42+
"image": {
43+
"description": "root image config used by VM-based containers",
44+
"type": "object",
45+
"required": [
46+
"path",
47+
"type"
48+
],
49+
"properties": {
50+
"path": {
51+
"$ref": "defs.json#/definitions/FilePath"
52+
},
53+
"type": {
54+
"$ref": "defs-vm.json#/definitions/RootImageType"
55+
}
56+
}
57+
}
58+
}
59+
}
60+
}

‎schema/defs-vm.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"definitions": {
3+
"RootImageType": {
4+
"type": "string",
5+
"enum": [
6+
"raw",
7+
"qcow2",
8+
"qcow",
9+
"vdi",
10+
"vmdk",
11+
"vhd"
12+
]
13+
}
14+
}
15+
}

‎spec.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Platforms defined by this specification are:
1616
* `linux`: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
1717
* `solaris`: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
1818
* `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
19+
* `vm`: [runtime.md](runtime.md), [config.md](config.md), and [config-vm.md](config-vm.md).
1920

2021
# <a name="ociRuntimeSpecTOC" />Table of Contents
2122

@@ -29,6 +30,7 @@ Platforms defined by this specification are:
2930
- [Linux-specific Configuration](config-linux.md)
3031
- [Solaris-specific Configuration](config-solaris.md)
3132
- [Windows-specific Configuration](config-windows.md)
33+
- [Virtual-Machine-specific Configuration](config-vm.md)
3234
- [Glossary](glossary.md)
3335

3436
# <a name="ociRuntimeSpecNotationalConventions" />Notational Conventions

‎specs-go/config.go‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ type Spec struct {
2525
Solaris *Solaris `json:"solaris,omitempty" platform:"solaris"`
2626
// Windows is platform-specific configuration for Windows based containers.
2727
Windows *Windows `json:"windows,omitempty" platform:"windows"`
28+
// VM specifies configuration for virtual-machine-based containers.
29+
VM *VM `json:"vm,omitempty" platform:"vm"`
2830
}
2931

3032
// Process contains information to start a specific application inside the container.
@@ -499,6 +501,42 @@ type WindowsHyperV struct {
499501
UtilityVMPath string `json:"utilityVMPath,omitempty"`
500502
}
501503

504+
// VM contains information for virtual-machine-based containers.
505+
type VM struct {
506+
// Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers.
507+
Hypervisor VMHypervisor `json:"hypervisor,omitempty"`
508+
// Kernel specifies kernel-related configuration for virtual-machine-based containers.
509+
Kernel VMKernel `json:"kernel"`
510+
// Image specifies guest image related configuration for virtual-machine-based containers.
511+
Image VMImage `json:"image,omitempty"`
512+
}
513+
514+
// VMHypervisor contains information about the hypervisor to use for a virtual machine.
515+
type VMHypervisor struct {
516+
// Path is the host path to the hypervisor used to manage the virtual machine.
517+
Path string `json:"path"`
518+
// Parameters specifies parameters to pass to the hypervisor.
519+
Parameters string `json:"parameters,omitempty"`
520+
}
521+
522+
// VMKernel contains information about the kernel to use for a virtual machine.
523+
type VMKernel struct {
524+
// Path is the host path to the kernel used to boot the virtual machine.
525+
Path string `json:"path"`
526+
// Parameters specifies parameters to pass to the kernel.
527+
Parameters string `json:"parameters,omitempty"`
528+
// InitRD is the host path to an initial ramdisk to be used by the kernel.
529+
InitRD string `json:"initrd,omitempty"`
530+
}
531+
532+
// VMImage contains information about the virtual machine root image.
533+
type VMImage struct {
534+
// Path is the host path to the root image that the VM kernel would boot into.
535+
Path string `json:"path"`
536+
// Type is the root image format type (e.g. "qcow2", "raw", "vhd", etc).
537+
Type string `json:"type"`
538+
}
539+
502540
// LinuxSeccomp represents syscall restrictions
503541
type LinuxSeccomp struct {
504542
DefaultAction LinuxSeccompAction `json:"defaultAction"`

0 commit comments

Comments
 (0)