diff --git a/config-vm.md b/config-vm.md new file mode 100644 index 000000000..eccb11190 --- /dev/null +++ b/config-vm.md @@ -0,0 +1,37 @@ +# Virtual-machine-specific Configuration + +Virtual-machine-based runtimes require additional configuration to that specified in the [default 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 virtual machine. +* **`kernel`** (object, required) specifies details of the kernel to boot the virtual machine with. + +Note that `imagePath` refers to a 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 root filesystem for the virtual machine. +* 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 + +Used by virtual-machine-based runtimes only. + +* **`path`** (string, required) specifies the host path to the kernel used to boot the 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 virtual machine. + +## 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" + }, +} +``` diff --git a/config.md b/config.md index 06801f5dd..9b8207d57 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 runtimes. + +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/schema-vm.json b/schema/schema-vm.json new file mode 100644 index 000000000..b0ddaf396 --- /dev/null +++ b/schema/schema-vm.json @@ -0,0 +1,43 @@ +{ + "vm": { + "description": "configuration for virtual-machine-based runtimes", + "id": "https://opencontainers.org/schema/bundle/vm", + "type": "object", + "required" : [ + "imagePath", + "kernel" + ], + "properties": { + "imagePath": { + "description": "host path to rootfs image on host system which is used for VM-based runtimes", + "id": "https://opencontainers.org/schema/bundle/vm/imagePath", + "type": "string" + }, + "kernel": { + "description": "kernel config used by VM-based runtimes", + "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" + } + } + } + } + } +} diff --git a/specs-go/config.go b/specs-go/config.go index 71c9fa773..d941f0b21 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -18,6 +18,8 @@ type Spec struct { Hooks *Hooks `json:"hooks,omitempty" platform:"linux,solaris"` // Annotations contains arbitrary metadata for the container. Annotations map[string]string `json:"annotations,omitempty"` + // VM specifies configuration for virtual-machine-based runtimes. + VM VM `json:"vm,omitempty"` // Linux is platform-specific configuration for Linux based containers. Linux *Linux `json:"linux,omitempty" platform:"linux"` @@ -27,6 +29,24 @@ type Spec struct { Windows *Windows `json:"windows,omitempty" platform:"windows"` } +// VM contains information for virtual-machine-based runtimes. +type VM struct { + // Kernel specifies kernel-related configuration for virtual-machine-based runtimes. + Kernel VMKernel `json:"kernel"` + // ImagePath is the host path to the root filesystem image on the host which can be used by a virtual-machine-based runtime. + 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"` +} + // Process contains information to start a specific application inside the container. type Process struct { // Terminal creates an interactive terminal for the container.