From ad33f9cd609d68cdbe98753282f65537d0189d0e 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 | 25 +++++++++++++------------ specs-go/config.go | 2 +- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/config.md b/config.md index 3e14718d0..c0d753b66 100644 --- a/config.md +++ b/config.md @@ -239,17 +239,23 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th ## Hooks 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 @@ -301,11 +307,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 This OPTIONAL property contains arbitrary metadata for the container. diff --git a/specs-go/config.go b/specs-go/config.go index 454df6ffb..e299ad4fe 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -19,7 +19,7 @@ type Spec struct { // Mounts profile configuration for adding mounts to the container's filesystem. Mounts []Mount `json:"mounts,omitempty"` // Hooks are the commands run at various lifecycle events of the container. - Hooks Hooks `json:"hooks"` + Hooks Hooks `json:"hooks,omitempty"` // 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"`