From f2cc9fdb608399d4341267de67d4cfef53170ce4 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 2 Aug 2016 23:32:43 -0700 Subject: [PATCH 1/9] config: Update 'OpenContainer specification' wording Catch up with the spec title from faad7e0f (README: title rename, 2016-04-04, #365). Also make the Go comment consistent with the Markdown spec (no need to maintain two phrasings for the same idea). The only difference between the phrasings is now some shuffling at the beginning to start off with the property name (to keep godoc happy). The JSON Schema entry (in defs.json) is different too, because it has to apply to both the configuration and state JSON, so mentioning "bundle" makes less sense than mentioning "document". Signed-off-by: W. Trevor King --- config.md | 4 ++-- schema/defs.json | 2 +- specs-go/config.go | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/config.md b/config.md index 1a551435c..a3f3ab277 100644 --- a/config.md +++ b/config.md @@ -10,8 +10,8 @@ Below is a detailed description of each field defined in the configuration forma ## Specification version -* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OpenContainer specification with which the bundle complies. -The OpenContainer spec follows semantic versioning and retains forward and backward compatibility within major versions. +* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies. +The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions. For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series. ### Example diff --git a/schema/defs.json b/schema/defs.json index 329031848..176cb8f24 100644 --- a/schema/defs.json +++ b/schema/defs.json @@ -1,5 +1,5 @@ { - "description": "Definitions used throughout the OpenContainer Specification", + "description": "Definitions used throughout the Open Container Runtime Specification", "definitions": { "int8": { "type": "integer", diff --git a/specs-go/config.go b/specs-go/config.go index b2ac75eb4..7e1bdf4a6 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -4,7 +4,7 @@ import "os" // Spec is the base configuration for the container. type Spec struct { - // Version is the version of the specification that is supported. + // Version of the Open Container Runtime Specification with which the bundle complies. Version string `json:"ociVersion"` // Platform is the host information for OS and Arch. Platform Platform `json:"platform"` From 57fc2ca54c8a4afca53c520d8d4a3e24d5c12764 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 2 Aug 2016 23:37:47 -0700 Subject: [PATCH 2/9] config: Consistent Markdown/Go wording for 'platform' Don't mention OS and Arch, since they're covered by the list (in Markdown) and Platform struct (in Go). This gives us one less place to update if we ever change the schema for the platform object. Signed-off-by: W. Trevor King --- config.md | 2 ++ specs-go/config.go | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/config.md b/config.md index a3f3ab277..19ef4ccb9 100644 --- a/config.md +++ b/config.md @@ -200,6 +200,8 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th ## Platform +**`platform`** specifies the configuration's target platform. + * **`os`** (string, required) specifies the operating system family this image targets. The runtime MUST generate an error if it does not support the configured **`os`**. Bundles SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`$GOOS`][go-environment]. diff --git a/specs-go/config.go b/specs-go/config.go index 7e1bdf4a6..cb4cae811 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -6,7 +6,7 @@ import "os" type Spec struct { // Version of the Open Container Runtime Specification with which the bundle complies. Version string `json:"ociVersion"` - // Platform is the host information for OS and Arch. + // Platform specifies the configuration's target platform. Platform Platform `json:"platform"` // Process is the container's main process. Process Process `json:"process"` From fc103cf515bc7361b24731189ca79c728e949305 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 2 Aug 2016 23:45:11 -0700 Subject: [PATCH 3/9] config: Consistent Markdown/Go wording for 'process' I've dropped "main process" because "container process" is currently a much more popular way of identifying that process in this specification. Before this commit: $ git grep -i 'main process' | wc -l 4 $ git grep -i 'container process' | wc -l 13 I've also added our usual: (, ) to the Markdown so folks can see that this is a required object. Signed-off-by: W. Trevor King --- config.md | 2 ++ specs-go/config.go | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/config.md b/config.md index 19ef4ccb9..0d334347c 100644 --- a/config.md +++ b/config.md @@ -90,6 +90,8 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se ## Process configuration +**`process`** (object, required) configures the container process. + * **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process, defaults to false. * **`cwd`** (string, required) is the working directory that will be set for the executable. This value MUST be an absolute path. diff --git a/specs-go/config.go b/specs-go/config.go index cb4cae811..4d5a9488f 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -8,7 +8,7 @@ type Spec struct { Version string `json:"ociVersion"` // Platform specifies the configuration's target platform. Platform Platform `json:"platform"` - // Process is the container's main process. + // Process configures the container process. Process Process `json:"process"` // Root is the root information for the container's filesystem. Root Root `json:"root"` From 9500be84703a6daf9167e796534d0b925c6585a4 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 2 Aug 2016 23:49:50 -0700 Subject: [PATCH 4/9] Replace "container's main process" with "container process" We use both forms, but the latter was more popular. Before this branch: $ git grep -i 'container process' origin/master | wc -l 13 $ git grep -i 'main process' origin/master | wc -l 4 Also fix "process id" -> "process ID" in one of the lines I touched, to match fork(2) [1]. [1]: http://man7.org/linux/man-pages/man2/fork.2.html Signed-off-by: W. Trevor King --- runtime.md | 2 +- specs-go/config.go | 4 ++-- specs-go/state.go | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/runtime.md b/runtime.md index 01bdb9d5d..90e383fdd 100644 --- a/runtime.md +++ b/runtime.md @@ -20,7 +20,7 @@ The value MAY be one of: * `stopped` : the container has been created and the user-specified code has been executed but is no longer running Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above. -* **`pid`**: (int) is the ID of the main process within the container, as seen by the host. +* **`pid`**: (int) is the ID of the container process, as seen by the host. * **`bundlePath`**: (string) is the absolute path to the container's bundle directory. This is provided so that consumers can find the container's configuration and root filesystem on the host. * **`annotations`**: (map) contains the list of annotations associated with the container. diff --git a/specs-go/config.go b/specs-go/config.go index 4d5a9488f..abbeb2667 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -53,8 +53,8 @@ type Process struct { SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"` } -// User specifies Linux/Solaris specific user and group information for the container's -// main process. +// User specifies Linux/Solaris specific user and group information +// for the container process. type User struct { // UID is the user id. (this field is platform dependent) UID uint32 `json:"uid" platform:"linux,solaris"` diff --git a/specs-go/state.go b/specs-go/state.go index 445f8c5c0..ad31b893b 100644 --- a/specs-go/state.go +++ b/specs-go/state.go @@ -8,7 +8,7 @@ type State struct { ID string `json:"id"` // Status is the runtime state of the container. Status string `json:"status"` - // Pid is the process id for the container's main process. + // Pid is the process ID for the container process. Pid int `json:"pid"` // BundlePath is the path to the container's bundle directory. BundlePath string `json:"bundlePath"` From d7b88775471a55a20242fa114f771f66bf3bd431 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 2 Aug 2016 23:53:32 -0700 Subject: [PATCH 5/9] config: Consistent Markdown/Go/JSON-Schema wording for 'root' I've also added our usual: (, ) to the Markdown so folks can see that this is a required object. Signed-off-by: W. Trevor King --- config.md | 2 +- schema/config-schema.json | 2 +- specs-go/config.go | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/config.md b/config.md index 0d334347c..0c5ecd8c7 100644 --- a/config.md +++ b/config.md @@ -22,7 +22,7 @@ For example, if an implementation is compliant with version 1.0.1 of the spec, i ## Root Configuration -Each container has exactly one *root filesystem*, specified in the *root* object: +**`root`** (object, required) configures the container's root filesystem. * **`path`** (string, required) Specifies the path to the root filesystem for the container. A directory MUST exist at the path declared by the field. diff --git a/schema/config-schema.json b/schema/config-schema.json index 351901ad0..76f8ea114 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -56,7 +56,7 @@ } }, "root": { - "description": "The path to the root filesystem for the container.", + "description": "Configures the container's root filesystem.", "id": "https://opencontainers.org/schema/bundle/root", "type": "object", "properties": { diff --git a/specs-go/config.go b/specs-go/config.go index abbeb2667..6a9323125 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -10,7 +10,7 @@ type Spec struct { Platform Platform `json:"platform"` // Process configures the container process. Process Process `json:"process"` - // Root is the root information for the container's filesystem. + // Root configures the container's root filesystem. Root Root `json:"root"` // Hostname is the container's host name. Hostname string `json:"hostname,omitempty"` From 1a8611644f7b35ef842c499bc9015be0a70b8fb1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 2 Aug 2016 23:55:22 -0700 Subject: [PATCH 6/9] config: Consistent Markdown/Go wording for 'hostname' I've changed the old "as it is accessible to ..." to the more compact "as seen by ..." language from the old Markdown version, although I don't think it's strictly necessary. The original "accessbile to" language is from 77d44b10 (Update runtime.md, 2015-06-16), which actually looked fairly similar to the language I'm using here. That commit's "hostname for the container" lanuage went away in 7ac41c69 (config.md: reformat into a standard style, 2015-06-30), although that commit made too many changes to motivate them all at that level. I've left that language out of the Go comment, because truncating for compact Go comments is fine (the Markdown entry is canonical, and the Go comment is just to provide some minimal context). Signed-off-by: W. Trevor King --- config.md | 2 +- specs-go/config.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/config.md b/config.md index 0c5ecd8c7..d637682de 100644 --- a/config.md +++ b/config.md @@ -191,7 +191,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th ## Hostname -* **`hostname`** (string, optional) as it is accessible to processes running inside. +* **`hostname`** (string, optional) configures the container's hostname as seen by processes running inside the container. On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace]. ### Example diff --git a/specs-go/config.go b/specs-go/config.go index 6a9323125..66f075d6c 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -12,7 +12,7 @@ type Spec struct { Process Process `json:"process"` // Root configures the container's root filesystem. Root Root `json:"root"` - // Hostname is the container's host name. + // Hostname configures the container's hostname. Hostname string `json:"hostname,omitempty"` // Mounts profile configuration for adding mounts to the container's filesystem. Mounts []Mount `json:"mounts,omitempty"` From ad81edca26656f89ea600407091cbfe6d4072497 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 3 Aug 2016 00:04:20 -0700 Subject: [PATCH 7/9] config: Consistent Markdown/Go wording for 'mounts' I've replaced the old MAY with our usual (, ) to get the property name first, since that translates more directly into a Go comment that godoc will like. Signed-off-by: W. Trevor King --- config.md | 2 +- specs-go/config.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/config.md b/config.md index d637682de..0f43347a6 100644 --- a/config.md +++ b/config.md @@ -39,7 +39,7 @@ For example, if an implementation is compliant with version 1.0.1 of the spec, i ## Mounts -You MAY add array of mount points inside container as `mounts`. +**`mounts`** (array, optional) configures additional mounts (on top of [`root`](#root-configuration)). The runtime MUST mount entries in the listed order. The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html). diff --git a/specs-go/config.go b/specs-go/config.go index 66f075d6c..5bbd66d46 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -14,7 +14,7 @@ type Spec struct { Root Root `json:"root"` // Hostname configures the container's hostname. Hostname string `json:"hostname,omitempty"` - // Mounts profile configuration for adding mounts to the container's filesystem. + // Mounts configures additional mounts (on top of Root). Mounts []Mount `json:"mounts,omitempty"` // Hooks are the commands run at various lifecycle events of the container. Hooks Hooks `json:"hooks"` From 9837b6b7250d7b9bdabdebc95e1324ace6a07db9 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 3 Aug 2016 00:12:39 -0700 Subject: [PATCH 8/9] config: Consistent Markdown/Go wording for 'hooks' The new wording isn't particularly close to either of the old wordings, but it reads more clearly to me. I've also added our usual: (, ) to the Markdown so folks can see that this is an optional object (although see [1] for a more complete version). [1]: https://github.com/opencontainers/runtime-spec/pull/427 Subject: config: Explicitly list 'hooks' as optional Signed-off-by: W. Trevor King --- config.md | 1 + specs-go/config.go | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/config.md b/config.md index 0f43347a6..d6e8000e3 100644 --- a/config.md +++ b/config.md @@ -251,6 +251,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th ## Hooks +**`hooks`** (object, optional) configures callbacks for container lifecycle events. Lifecycle hooks allow custom events for different points in a container's runtime. Presently there are `Prestart`, `Poststart` and `Poststop`. diff --git a/specs-go/config.go b/specs-go/config.go index 5bbd66d46..f4c6b28fc 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -16,7 +16,7 @@ type Spec struct { Hostname string `json:"hostname,omitempty"` // Mounts configures additional mounts (on top of Root). Mounts []Mount `json:"mounts,omitempty"` - // Hooks are the commands run at various lifecycle events of the container. + // Hooks configures callbacks for container lifecycle events. Hooks Hooks `json:"hooks"` // Annotations is an unstructured key value map that may be set by external tools to store and retrieve arbitrary metadata. Annotations map[string]string `json:"annotations,omitempty"` From 7477fa519fc86a80aeafdfab2562edc9ed1448b7 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 3 Aug 2016 00:18:07 -0700 Subject: [PATCH 9/9] config: config: Consistent Markdown/Go wording for 'annotations' I've replaced the old OPTIONAL with our usual: (, ) to get the property name first, since that translates more directly into a Go comment that godoc will like. The new Go comment is much shorter, dropping "unstructured" (because the Markdown says "structured or unstructured") and "set by external tools..." (because *everything* in the configuration JSON is set by external-to-the-runtime tools). Signed-off-by: W. Trevor King --- config.md | 2 +- specs-go/config.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/config.md b/config.md index d6e8000e3..8d2d746d3 100644 --- a/config.md +++ b/config.md @@ -322,7 +322,7 @@ The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://g ## Annotations -This OPTIONAL property contains arbitrary metadata for the container. +**`annotations`** (object, optional) contains arbitrary metadata for the container. This information MAY be structured or unstructured. Annotations are key-value maps. diff --git a/specs-go/config.go b/specs-go/config.go index f4c6b28fc..3b5eeda41 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -18,7 +18,7 @@ type Spec struct { Mounts []Mount `json:"mounts,omitempty"` // Hooks configures callbacks for container lifecycle events. Hooks Hooks `json:"hooks"` - // Annotations is an unstructured key value map that may be set by external tools to store and retrieve arbitrary metadata. + // Annotations contains arbitrary metadata for the container. Annotations map[string]string `json:"annotations,omitempty"` // Linux is platform specific configuration for Linux based containers.