From 2022e3ec01a47e1aa42bfb806e6bb542c1f3f8c7 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 18 May 2017 11:25:31 -0700 Subject: [PATCH 1/2] config: Bump Hyper-V condition from root.path to root itself Don't require users targetting Hyper-V to set an empty object ("root": {}). This also avoids confusion about whether you can set root.readonly without setting root.path (you can't). Move the relative, absolute, and rootfs bits into a POSIX paragraph, because they don't apply to Windows where the value MUST be a volume GUID path (since 2283e63, Windows: Remove Sandbox, additional tweaks, 2017-05-23, #849). We don't need the "for Windows Server containers" condition on volume GUID paths, because with this commit that condition is already applied at the 'root' level and the Hyper-V case has already been handled there. Signed-off-by: W. Trevor King --- config.md | 20 ++++++++++++-------- schema/config-schema.json | 6 ++++-- specs-go/config.go | 4 ++-- 3 files changed, 18 insertions(+), 12 deletions(-) diff --git a/config.md b/config.md index a886baf10..9be3cd14d 100644 --- a/config.md +++ b/config.md @@ -26,18 +26,22 @@ For all platform-specific configuration values, the scope defined below in the [ ## Root -**`root`** (object, REQUIRED) specifies the container's root filesystem. +**`root`** (object, OPTIONAL) specifies the container's root filesystem. + On Windows, for Windows Server Containers, this field is REQUIRED. + For [Hyper-V Containers](config-windows.md#hyperv), this field MUST NOT be set. -* **`path`** (string, OPTIONAL) Specifies the path to the root filesystem for the container. - The path is either an absolute path or a relative path to the bundle. + On all other platforms, this field is REQUIRED. - * On Windows, for Windows Server Containers, this field is REQUIRED and MUST be specified as a [volume GUID path][naming-a-volume]. - For Hyper-V Containers, this field MUST be omitted. - * On all other platforms, this field is REQUIRED. +* **`path`** (string, REQUIRED) Specifies the path to the root filesystem for the container. + + * On Windows, `path` MUST be a [volume GUID path][naming-a-volume]. + + * On Linux and Solaris, `path` is either an absolute path or a relative path to the bundle. + For example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`. The value SHOULD be the conventional `rootfs`. - * On Linux, for example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`. - If defined, a directory MUST exist at the path declared by the field. + A directory MUST exist at the path declared by the field. + * **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false. * On Windows, this field MUST be omitted or false. diff --git a/schema/config-schema.json b/schema/config-schema.json index 2ba139d95..5a49ba5ec 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -41,6 +41,9 @@ "description": "Configures the container's root filesystem.", "id": "https://opencontainers.org/schema/bundle/root", "type": "object", + "required": [ + "path" + ], "properties": { "path": { "id": "https://opencontainers.org/schema/bundle/root/path", @@ -214,7 +217,6 @@ } }, "required": [ - "ociVersion", - "root" + "ociVersion" ] } diff --git a/specs-go/config.go b/specs-go/config.go index 01c70b447..93cac376c 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -9,7 +9,7 @@ type Spec struct { // Process configures the container process. Process *Process `json:"process,omitempty"` // Root configures the container's root filesystem. - Root Root `json:"root"` + Root *Root `json:"root,omitempty"` // Hostname configures the container's hostname. Hostname string `json:"hostname,omitempty"` // Mounts configures additional mounts (on top of Root). @@ -94,7 +94,7 @@ type User struct { // Root contains information about the container's root filesystem on the host. type Root struct { // Path is the absolute path to the container's root filesystem. - Path string `json:"path,omitempty"` + Path string `json:"path"` // Readonly makes the root filesystem for the container readonly before the process is executed. Readonly bool `json:"readonly,omitempty"` } From 767eeafbb7d5501094b9cca2d680819db050744e Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 1 Jun 2017 14:43:30 -0700 Subject: [PATCH 2/2] config: Use "POSIX" instead of "Linux and Solaris" As requested by Michael [1], this reduces the number of changes required if BSD or some such is added to the config. This change leaves a bit of a gap between the platforms listed in spec.md, since readers have to figure out on their own that the POSIX properties apply to the linux and solaris platforms (and potentially other future platforms). But Michael felt like it's ok to leave that gap, at least for now [2]. I've used "On POSIX platforms" and similar (instead of "On POSIX") because, as Tianon points out [3], there is some space between POSIX-the-spec and platforms which implement it. [1]: https://github.com/opencontainers/runtime-spec/pull/838#discussion_r119729323 [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-06-01-17.41.log.html#l-60 [3]: https://github.com/opencontainers/runtime-spec/pull/838#discussion_r123279055 Signed-off-by: W. Trevor King --- config.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/config.md b/config.md index 9be3cd14d..75796cc96 100644 --- a/config.md +++ b/config.md @@ -36,7 +36,7 @@ For all platform-specific configuration values, the scope defined below in the [ * On Windows, `path` MUST be a [volume GUID path][naming-a-volume]. - * On Linux and Solaris, `path` is either an absolute path or a relative path to the bundle. + * On POSIX platforms, `path` is either an absolute path or a relative path to the bundle. For example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`. The value SHOULD be the conventional `rootfs`. @@ -45,7 +45,7 @@ For all platform-specific configuration values, the scope defined below in the [ * **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false. * On Windows, this field MUST be omitted or false. -### Example (POSIX) +### Example (POSIX platforms) ```json "root": { @@ -94,9 +94,9 @@ For all platform-specific configuration values, the scope defined below in the [ ] ``` -### Linux and Solaris Mounts +### POSIX-platform Mounts -For Linux and Solaris based systems the mounts structure has the following fields: +For POSIX platforms the `mounts` structure has the following fields: * **`type`** (string, OPTIONAL) The type of the filesystem to be mounted. * Linux: filesystem types supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). @@ -195,9 +195,9 @@ For Linux-based systems the process structure supports the following process-spe The user for the process is a platform-specific structure that allows specific control over which user the process runs as. -#### Linux and Solaris User +#### POSIX-platform User -For Linux and Solaris based systems the user structure has the following fields: +For POSIX platforms the `user` structure has the following fields: * **`uid`** (int, REQUIRED) specifies the user ID in the [container namespace](glossary.md#container-namespace). * **`gid`** (int, REQUIRED) specifies the group ID in the [container namespace](glossary.md#container-namespace). @@ -348,9 +348,9 @@ For Windows based systems the user structure has the following fields: } ``` -## Linux and Solaris Hooks +## POSIX-platform Hooks -For Linux- and Solaris-based systems, the configuration structure supports `hooks` for configuring custom actions related to the [lifecycle](runtime.md#lifecycle) of the container. +For POSIX platforms, the configuration structure supports `hooks` for configuring custom actions related to the [lifecycle](runtime.md#lifecycle) of the container. * **`hooks`** (object, OPTIONAL) MAY contain any of the following properties: * **`prestart`** (array of objects, OPTIONAL) is an array of [pre-start hooks](#prestart).