Skip to content

Commit

Permalink
*: Remove hooks
Browse files Browse the repository at this point in the history 
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
     <wking> if you have a distinct create operation, you can drop the
       pre-start hooks, which makes a simpler spec
[2]: #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]: #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
     <vishh> 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: <[email protected]>
[6]: #384 (comment)
     Subject: Split create and start
[7]: #384 (comment)
     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 <[email protected]>
  • Loading branch information
@wking
wking committed Jun 2, 2016
1 parent f0e14cd commit ea41a14
Show file tree
Hide file tree
Showing 7 changed files with 2 additions and 179 deletions.
7 changes: 1 addition & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 0 additions & 8 deletions ROADMAP.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:*
103 changes: 0 additions & 103 deletions config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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": [
{
Expand Down
5 changes: 0 additions & 5 deletions runtime.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
19 changes: 0 additions & 19 deletions schema/defs.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
18 changes: 1 addition & 17 deletions schema/schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down Expand Up @@ -178,7 +163,6 @@
"process",
"root",
"hostname",
"mounts",
"hooks"
"mounts"
]
}
21 changes: 0 additions & 21 deletions specs-go/config.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"`

Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit ea41a14

Please sign in to comment.