From ea41a146acb535c8dbfd4d7632b37cda5330b864 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 1 Jun 2016 23:10:12 -0700 Subject: [PATCH] *: Remove hooks This drops all instances (outside the ChangeLog) turned up by case-insensitive searches for 'hook'. The desire to drop hooks has been around for a while now [1], but it took a while to land a create/start split. By the time that split did land, dropping hooks was still part of its motivation [2]. Hooks are hard to support robustly [3], and after the create/start split, callers can do whatever they like at those times without having to go through the runtime [4]. There is still a use-case for folks who prefer the old all-in-one UX, but we can support those folks with a higher-level wrapper built on hookless create/start primatives [5]. There was some last-minute discussion of pre-pivot mount propagation needing pre-start hooks [6], but that use case can be addressed by manipulating the mounts array [7]. With those arguments in place, the consensus at today's meeting seemed in favor of removing hooks from the spec [8]. [1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-10-28-17.02.log.html#l-71 if you have a distinct create operation, you can drop the pre-start hooks, which makes a simpler spec [2]: https://github.com/opencontainers/runtime-spec/pull/384 Subject: Split create and start In the topic post: > # Motivating usecases: > > * to simplify the flows/interaction patterns by removing hooks, > but still allow for the same functionality [3]: https://github.com/opencontainers/runtime-spec/pull/265 Subject: runtime-config: Require serial hook execution [4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2016-03-24.log.html#t2016-03-24T18:56:15 mrunalp: How do I run http hooks? I need a binary wrapper to execute http hooks [5]: https://groups.google.com/a/opencontainers.org/d/msg/dev/Y7p6YW8zr4s/OVaAI_WDBAAJ Subject: Re: Hooks and all-in-one operation Date: Wed, 1 Jun 2016 11:49:07 -0700 Message-ID: <20160601184907.GF4149@odin.tremily.us> [6]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-220038190 Subject: Split create and start [7]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-220740126 Subject: Split create and start [8]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-06-01-17.01.log.html#l-83 Signed-off-by: W. Trevor King --- README.md | 7 +-- ROADMAP.md | 8 ---- config.md | 103 --------------------------------------------- runtime.md | 5 --- schema/defs.json | 19 --------- schema/schema.json | 18 +------- specs-go/config.go | 21 --------- 7 files changed, 2 insertions(+), 179 deletions(-) diff --git a/README.md b/README.md index bd21985b6..d4475071a 100644 --- a/README.md +++ b/README.md @@ -34,14 +34,9 @@ To provide context for users the following section gives example use cases for e #### Application Bundle Builders Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container. -The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups). +The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups). Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments. -#### Hook Developers - -[Hook](config.md#hooks) developers can extend the functionality of an OCI-compliant runtime by hooking into a container's lifecycle with an external application. -Example use cases include sophisticated network configuration, volume garbage collection, etc. - #### Runtime Developers Runtime developers can build runtime implementations that run OCI-compliant bundles and container configuration, containing low-level OS and host specific details, on a particular platform. diff --git a/ROADMAP.md b/ROADMAP.md index 89e5a4996..a330137c1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -45,11 +45,3 @@ Systems: * Linux *Owner:* robdolinms as lead coordinator - -### Full Lifecycle Hooks - -Ensure that we have lifecycle hooks in the correct places with full coverage over the container lifecycle. - -Will probably go away with Vish's work on splitting create and start, and if we have exec. - -*Owner:* diff --git a/config.md b/config.md index bd42af426..f97bb9bb6 100644 --- a/config.md +++ b/config.md @@ -235,76 +235,6 @@ _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 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]. - -### Prestart - -The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. -They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. -In Linux, for e.g., the network namespace could be configured in this hook. - -If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. - -### Poststart - -The post-start hooks are called after the user process is started. -For example this hook can notify user that real process is spawned. - -If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. - -### Poststop - -The post-stop hooks are called after the container process is stopped. -Cleanup or debugging could be performed in such a hook. -If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. - -### Example - -```json - "hooks" : { - "prestart": [ - { - "path": "/usr/bin/fix-mounts", - "args": ["fix-mounts", "arg1", "arg2"], - "env": [ "key1=value1"] - }, - { - "path": "/usr/bin/setup-network" - } - ], - "poststart": [ - { - "path": "/usr/bin/notify-start", - "timeout": 5 - } - ], - "poststop": [ - { - "path": "/usr/sbin/cleanup.sh", - "args": ["cleanup.sh", "-f"] - } - ] - } -``` - -`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. @@ -448,39 +378,6 @@ Here is a full example `config.json` for reference. ] } ], - "hooks": { - "prestart": [ - { - "path": "/usr/bin/fix-mounts", - "args": [ - "fix-mounts", - "arg1", - "arg2" - ], - "env": [ - "key1=value1" - ] - }, - { - "path": "/usr/bin/setup-network" - } - ], - "poststart": [ - { - "path": "/usr/bin/notify-start", - "timeout": 5 - } - ], - "poststop": [ - { - "path": "/usr/sbin/cleanup.sh", - "args": [ - "cleanup.sh", - "-f" - ] - } - ] - }, "linux": { "devices": [ { diff --git a/runtime.md b/runtime.md index 386a042a8..6703e4ff2 100644 --- a/runtime.md +++ b/runtime.md @@ -118,8 +118,3 @@ Attempting to delete a container whose process is still running MUST generate an Deleting a container MUST delete the resources that were created during the `create` step. Note that resources associated with the container, but not created by this container, MUST NOT be deleted. Once a container is deleted its ID MAY be used by a subsequent container. - - -## Hooks -Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation. -See [runtime configuration for hooks](./config.md#hooks) for more information. diff --git a/schema/defs.json b/schema/defs.json index a1a9e8777..408e52369 100644 --- a/schema/defs.json +++ b/schema/defs.json @@ -103,25 +103,6 @@ "Env": { "$ref": "#/definitions/ArrayOfStrings" }, - "Hook": { - "properties": { - "path": { - "$ref": "#/definitions/FilePath" - }, - "args": { - "$ref": "#/definitions/ArrayOfStrings" - }, - "env": { - "$ref": "#/definitions/Env" - } - } - }, - "ArrayOfHooks": { - "type": "array", - "items": { - "$ref": "#/definitions/Hook" - } - }, "IDMapping": { "properties": { "hostID": { diff --git a/schema/schema.json b/schema/schema.json index ca0b880de..ee3e977ce 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -9,21 +9,6 @@ "id": "https://opencontainers.org/schema/bundle/ociVersion", "type": "string" }, - "hooks": { - "id": "https://opencontainers.org/schema/bundle/hooks", - "type": "object", - "properties": { - "prestart": { - "$ref": "defs.json#/definitions/ArrayOfHooks" - }, - "poststart": { - "$ref": "defs.json#/definitions/ArrayOfHooks" - }, - "poststop": { - "$ref": "defs.json#/definitions/ArrayOfHooks" - } - } - }, "annotations": { "id": "https://opencontainers.org/schema/bundle/annotations", "oneOf": [ @@ -178,7 +163,6 @@ "process", "root", "hostname", - "mounts", - "hooks" + "mounts" ] } diff --git a/specs-go/config.go b/specs-go/config.go index fdd8f5ce5..217d770aa 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -16,8 +16,6 @@ type Spec struct { Hostname string `json:"hostname,omitempty"` // 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"` // 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"` @@ -94,25 +92,6 @@ type Mount struct { Options []string `json:"options,omitempty"` } -// Hook specifies a command that is run at a particular event in the lifecycle of a container -type Hook struct { - Path string `json:"path"` - Args []string `json:"args,omitempty"` - Env []string `json:"env,omitempty"` - Timeout *int `json:"timeout,omitempty"` -} - -// Hooks for container setup and teardown -type Hooks struct { - // Prestart is a list of hooks to be run before the container process is executed. - // On Linux, they are run after the container namespaces are created. - Prestart []Hook `json:"prestart,omitempty"` - // Poststart is a list of hooks to be run after the container process is started. - Poststart []Hook `json:"poststart,omitempty"` - // Poststop is a list of hooks to be run after the container process exits. - Poststop []Hook `json:"poststop,omitempty"` -} - // Linux contains platform specific configuration for Linux based containers. type Linux struct { // UIDMapping specifies user mappings for supporting user namespaces on Linux.