From b2816711f887a633c4fe21682739894cbde4d60b Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 6 May 2016 08:48:36 -0700 Subject: [PATCH] config: Explicitly list 'hooks' as optional And make it omitempty, otherwise: $ ocitools generate --template <(echo '{}') $ cat config.json | jq -S . { "hooks": {}, ... } To provide space for the type information and 'optional', I've shuffled the hook docs to follow our usual: * **`{property}`** ({type}, {when-needed}) {notes} format. I've kept the separate event-trigger sections (e.g. "### Prestart") since they go into more detail on the timing, purpose, and exit handling for the different events (and that seemed like too much information to put into the nested lists). I've replaced the Go reference from 48049d2 (Clarify the semantics of hook elements, 2015-11-25, #255) with POSIX references (following the new process docs) to address pushback against referencing Go [1,2] in favor of POSIX links [3]. Rob Dolin had suggested "platform-appropriate" wording [4], but it seems like Visual Studio 2015 supports execv [5], and providing an explicit "platform-appropriate" wiggle seems like it's adding useless complication. [1]: https://github.com/opencontainers/runtime-spec/pull/427#discussion_r62362761 [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-46 [3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-52 [4]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54 [5]: https://msdn.microsoft.com/en-us/library/886kc0as.aspx Signed-off-by: W. Trevor King --- config.md | 26 +++++++++++++------------- schema/config-schema.json | 3 +-- specs-go/config.go | 2 +- 3 files changed, 15 insertions(+), 16 deletions(-) diff --git a/config.md b/config.md index bcc263862..1dc7c9d55 100644 --- a/config.md +++ b/config.md @@ -287,19 +287,24 @@ For Windows based systems the user structure has the following fields: ## 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`. -* [`Prestart`](#prestart) is a list of hooks to be run before the container process is executed -* [`Poststart`](#poststart) is a list of hooks to be run immediately after the container process is started -* [`Poststop`](#poststop) is a list of hooks to be run after the container process exits +* **`hooks`** (object, OPTIONAL) MAY contain any of the following properties: + * **`prestart`** (array, OPTIONAL) is an array of [pre-start hooks](#prestart). + Entries in the array contain the following properties: + * **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2001 `execv`'s *path*][ieee-1003.1-2001-xsh-exec]. + This specification extends the IEEE standard in that **`path`** MUST be absolute. + * **`args`** (array of strings, REQUIRED) with the same semantics as [IEEE Std 1003.1-2001 `execv`'s *argv*][ieee-1003.1-2001-xsh-exec]. + * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001's `environ`][ieee-1003.1-2001-xbd-c8.1]. + * **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook. + * **`poststart`** (array, OPTIONAL) is an array of [post-start hooks](#poststart). + Entries in the array have the same schema as pre-start entries. + * **`poststop`** (array, OPTIONAL) is an array of [post-stop hooks](#poststop). + Entries in the array have the same schema as pre-start entries. Hooks allow one to run code before/after various lifecycle events of the container. Hooks MUST be called in the listed order. -The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. - -Hook paths are absolute and are executed from the host's filesystem in the [runtime namespace][runtime-namespace]. +The [state](runtime.md#state) of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. ### Prestart @@ -351,11 +356,6 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin } ``` -`path` is REQUIRED for a hook. -`args` and `env` are OPTIONAL. -`timeout` is the number of seconds before aborting the hook. -The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://golang.org/pkg/os/exec/#Cmd). - ## Annotations **`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container. diff --git a/schema/config-schema.json b/schema/config-schema.json index 95113a800..9bae9ad18 100644 --- a/schema/config-schema.json +++ b/schema/config-schema.json @@ -171,7 +171,6 @@ "platform", "process", "root", - "mounts", - "hooks" + "mounts" ] } diff --git a/specs-go/config.go b/specs-go/config.go index 222ab6797..7c1df6e3a 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -17,7 +17,7 @@ type Spec struct { // Mounts configures additional mounts (on top of Root). Mounts []Mount `json:"mounts,omitempty"` // Hooks configures callbacks for container lifecycle events. - Hooks Hooks `json:"hooks"` + Hooks *Hooks `json:"hooks,omitempty"` // Annotations contains arbitrary metadata for the container. Annotations map[string]string `json:"annotations,omitempty"`