From 7c9acf6c3e570a7ec4ab8bbb20a3e78f7e82ead1 Mon Sep 17 00:00:00 2001 From: John Howard Date: Fri, 12 May 2017 18:35:07 -0700 Subject: [PATCH] Clarify root path Signed-off-by: John Howard --- bundle.md | 13 +++++++++---- config.md | 13 +++++++++---- schema/config-schema.json | 3 --- specs-go/config.go | 2 +- 4 files changed, 19 insertions(+), 12 deletions(-) diff --git a/bundle.md b/bundle.md index 6a496d5a7..8ce6adc0c 100644 --- a/bundle.md +++ b/bundle.md @@ -8,17 +8,22 @@ See also [MacOS application bundles][macos_bundle] for a similar use of the term The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local filesystem so that it can be consumed by a compliant runtime. A Standard Container bundle contains all the information needed to load and run a container. -This MUST include the following artifacts: +This includes the following artifacts: 1. `config.json`: contains configuration data. This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`. See [`config.json`](config.md) for more details. 2. A directory representing the root filesystem of the container. -While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`. -This directory MUST be referenced by [`root`](config.md#root) within the `config.json` file. + While the name of this directory may be arbitrary, users should consider using a conventional name, such as `rootfs`. -While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle. + On Windows, for Windows Server containers, this directory is REQUIRED. For Hyper-V containers, it MUST be omitted. + + On all other platforms, this field is REQUIRED. + + If set, this directory MUST be referenced by [`root`](config.md#root) within the `config.json` file. + +When supplied, while these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle. In other words, a tar archive of a *bundle* will have these artifacts at the root of the archive, not nested within a top-level directory. [macos_bundle]: https://en.wikipedia.org/wiki/Bundle_%28macOS%29 diff --git a/config.md b/config.md index 5e19709c0..7a9efcc5c 100644 --- a/config.md +++ b/config.md @@ -28,10 +28,15 @@ For example, if a configuration is compliant with version 1.1 of this specificat **`root`** (object, REQUIRED) specifies the container's root filesystem. -* **`path`** (string, REQUIRED) 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 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`. - A directory MUST exist at the path declared by the field. +* **`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 Windows, for Windows Server Containers, this field is REQUIRED. For Hyper-V Containers, this field MUST be omitted. + + On all other platforms, this field is REQUIRED. + + 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. * **`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 diff --git a/schema/config-schema.json b/schema/config-schema.json index 5f2f6cae1..e37918b71 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -59,9 +59,6 @@ "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", diff --git a/specs-go/config.go b/specs-go/config.go index f2016b04b..98c10f909 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -96,7 +96,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"` + Path string `json:"path,omitempty"` // Readonly makes the root filesystem for the container readonly before the process is executed. Readonly bool `json:"readonly,omitempty"` }