vbatts/cri-o
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

hooks: Punt hook documentation to the runtime spec

Browse source 
No need to repeat the specification here, just link to the version we
generate.

Signed-off-by: W. Trevor King <wking@tremily.us>
This commit is contained in:
W. Trevor King 2018-02-20 10:27:37 -08:00
parent 37f136562b
commit 72afb41544
1 changed files with 9 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
hooks.md
View file

@ -1,45 +1,14 @@
# OCI Hooks Configuration
[The OCI Runtime Specification defines POSIX-platform Hooks:](
https://github.com/opencontainers/runtime-spec/blob/master/config.md#posix-platform-hooks)
## POSIX-platform Hooks
For POSIX platforms, the configuration structure supports hooks for configuring custom actions related to the life cycle of the container.
hooks (object, OPTIONAL) MAY contain any of the following properties:
* prestart (array of objects, OPTIONAL) is an array of pre-start hooks. Entries in the array contain the following properties:
* path (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 execv's path][ieee-1003.1-2008-functions-exec]. This specification extends the IEEE standard in that path MUST be absolute.
* args (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 execv's argv][ieee-1003.1-2008-functions-exec].
* env (array of strings, OPTIONAL) with the same semantics as IEEE Std 1003.1-2008's environ.
* timeout (int, OPTIONAL) is the number of seconds before aborting the hook. If set, timeout MUST be greater than zero.
* poststart (array of objects, OPTIONAL) is an array of post-start hooks. Entries in the array have the same schema as pre-start entries.
* poststop (array of objects, OPTIONAL) is an array of post-stop hooks. Entries in the array have the same schema as pre-start entries.
Hooks allow users to specify programs to run before or after various lifecycle events. Hooks MUST be called in the listed order. The state of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container.
### Prestart
The Prestart hooks MUST be called after the start operation is called but before the user-specified program command is executed. On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
### Poststart
The post-start hooks MUST be called after the user-specified process is executed but before the start operation returns. For example, this hook can notify the user that the container process is spawned.
### Poststop
The post-stop hooks MUST be called after the container is deleted but before the delete operation returns. Cleanup or debugging functions are examples of such a hook.
## CRI-O configuration files for automatically enabling Hooks
The way you enable the hooks above is by editing the OCI Specification to add your hook before running the oci runtime, like runc. But this is what CRI-O and `Kpod create` do for you, so we wanted a way for developers to drop configuration files onto the system, so that their hooks would be able to be plugged in.
For POSIX platforms, the [OCI runtime configuration][runtime-spec] supports [hooks][spec-hooks] for configuring custom actions related to the life cycle of the container.
The way you enable the hooks above is by editing the OCI runtime configuration before running the OCI runtime (e.g. [`runc`][runc]).
CRI-O and `Kpod create` create the OCI configuration for you, and this documentation allows developers to configure CRI-O to set their intended hooks.
One problem with hooks is that the runtime actually stalls execution of the container before running the hooks and stalls completion of the container, until all hooks complete. This can cause some performance issues. Also a lot of hooks just check if certain configuration is set and then exit early, without doing anything. For example the [oci-systemd-hook](https://github.com/projectatomic/oci-systemd-hook) only executes if the command is `init` or `systemd`, otherwise it just exits. This means if we automatically enable all hooks, every container will have to execute oci-systemd-hook, even if they don't run systemd inside of the container. Also since there are three stages, prestart, poststart, poststop each hook gets executed three times.
### Json Definition
## Json Definition
We decided to add a json file for hook builders which allows them to tell CRI-O when to run the hook and in which stage.
CRI-O reads all json files in /usr/share/containers/oci/hooks.d/*.json and /etc/containers/oci/hooks.d and sets up the specified hooks to run. If the same name is in both directories, the one in /etc/containers/oci/hooks.d takes precedence.
@ -66,7 +35,7 @@ type HookParams struct {
| hasbindmounts | Tells CRI-O to run the hook if the container has bind mounts from the host into the container | Optional |
| arguments | Additional arguments to append to the hook command when executing it. For example --debug | Optional |
### Example
## Example
```
@ -91,3 +60,7 @@ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
}
```
In this example the oci-umount will only be run during the prestart phase if the container has volume/bind mounts from the host into the container, it will also execute oci-umount with the --debug argument.
[runc]: https://github.com/opencontainers/runc
[runtime-spec]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/spec.md
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks