From 72e80600eb94bfd933316e44d4aa437f3ead0456 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 29 Nov 2016 11:00:34 +0000 Subject: [PATCH 1/4] Add VM-based runtime configuration details. Add configuration details for virtual-machine-based runtimes. Signed-off-by: James O. D. Hunt --- config-vm.md | 37 +++++++++++++++++++++++++++++++++ config.md | 6 ++++++ schema/config-schema.json | 3 +++ schema/schema-vm.json | 43 +++++++++++++++++++++++++++++++++++++++ specs-go/config.go | 20 ++++++++++++++++++ 5 files changed, 109 insertions(+) create mode 100644 config-vm.md create mode 100644 schema/schema-vm.json diff --git a/config-vm.md b/config-vm.md new file mode 100644 index 000000000..1fd590d08 --- /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) 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 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 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 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..2a698962f --- /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": "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": "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": "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..da9cc2afd 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 Kernel `json:"kernel"` + // ImagePath is the path to the root filesystem image on the host which can be used by a virtual-machine-based runtime. + ImagePath string `json:"imagePath"` +} + +// Kernel contains information about the kernel to use for a virtual machine. +type Kernel struct { + // Path is the 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 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. From 177157d8c356f36098142528a73b0e3694fd3135 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 29 Nov 2016 12:09:00 +0000 Subject: [PATCH 2/4] Clarify path details for VM-based runtime configuration. All paths specified in the configuration for virtual-machine-based runtimes are host-side. Signed-off-by: James O. D. Hunt --- config-vm.md | 8 ++++---- schema/schema-vm.json | 6 +++--- specs-go/config.go | 6 +++--- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/config-vm.md b/config-vm.md index 1fd590d08..eccb11190 100644 --- a/config-vm.md +++ b/config-vm.md @@ -4,13 +4,13 @@ Virtual-machine-based runtimes require additional configuration to that specifie This optional configuration is specified in a "VM" object: -* **`imagePath`** (string, required) path to file that represents the root filesystem for the virtual machine. +* **`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 root filesystem for the virtual machine. +* **`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. @@ -19,9 +19,9 @@ The virtual-machine-based runtime will use these two path fields to arrange for Used by virtual-machine-based runtimes only. -* **`path`** (string, required) specifies the path to the kernel used to boot the virtual machine. +* **`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 path to an initial ramdisk to be used by the virtual machine. +* **`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 diff --git a/schema/schema-vm.json b/schema/schema-vm.json index 2a698962f..b0ddaf396 100644 --- a/schema/schema-vm.json +++ b/schema/schema-vm.json @@ -9,7 +9,7 @@ ], "properties": { "imagePath": { - "description": "path to rootfs image on host system which is used for VM-based runtimes", + "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" }, @@ -23,7 +23,7 @@ "properties": { "path": { "id": "https://opencontainers.org/schema/bundle/vm/kernel/path", - "description": "path to kernel image", + "description": "host path to kernel image", "type": "string" }, "parameters": { @@ -32,7 +32,7 @@ "type": "string" }, "initrd": { - "description": "path to initial ramdisk image", + "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 da9cc2afd..716eebe2a 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -33,17 +33,17 @@ type Spec struct { type VM struct { // Kernel specifies kernel-related configuration for virtual-machine-based runtimes. Kernel Kernel `json:"kernel"` - // ImagePath is the path to the root filesystem image on the host which can be used by a virtual-machine-based runtime. + // 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"` } // Kernel contains information about the kernel to use for a virtual machine. type Kernel struct { - // Path is the path to the kernel used to boot the virtual machine. + // 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 path to an initial ramdisk to be used by the kernel. + // InitRd is the host path to an initial ramdisk to be used by the kernel. InitRd string `json:"initrd,omitempty"` } From 89ed60a9e3d504f9bef27e959d600be903cf6509 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 29 Nov 2016 12:11:06 +0000 Subject: [PATCH 3/4] Rename Kernel type to VMKernel for clarity. Signed-off-by: James O. D. Hunt --- specs-go/config.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs-go/config.go b/specs-go/config.go index 716eebe2a..fe3b7ae50 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -32,13 +32,13 @@ type Spec struct { // VM contains information for virtual-machine-based runtimes. type VM struct { // Kernel specifies kernel-related configuration for virtual-machine-based runtimes. - Kernel Kernel `json:"kernel"` + 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"` } -// Kernel contains information about the kernel to use for a virtual machine. -type Kernel struct { +// 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. From fe42b992c16b0fa0ad6e693cab9acef7e9f203f0 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Tue, 29 Nov 2016 12:11:45 +0000 Subject: [PATCH 4/4] Rename InitRd to InitRD for consistency. Signed-off-by: James O. D. Hunt --- specs-go/config.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs-go/config.go b/specs-go/config.go index fe3b7ae50..d941f0b21 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -43,8 +43,8 @@ type VMKernel struct { 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"` + // 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.