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

hooks: Example copy-edits (backticks, etc.)

Browse source 
Also move the English before the example, because folks reading this
documentation already speak English and are just learning the JSON
structure.

The 'console' syntax highlighting is because GitHub uses Linguist [1],
and Linguist recognizes 'console' as an alias for ShellSession [2].
I've chosen 'console' because it's shorter than 'ShellSession' and not
interpreter-specific like 'bash session'.

Dan requested the 'Kpod' -> 'podman' change [3].

[1]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting
[2]: https://github.com/github/linguist/blob/v6.0.1/lib/linguist/languages.yml#L4289-L4300
[3]: https://github.com/kubernetes-incubator/cri-o/pull/1355#pullrequestreview-98250057

Signed-off-by: W. Trevor King <wking@tremily.us>
This commit is contained in:
W. Trevor King 2018-02-20 11:15:46 -08:00
parent c80cdedbee
commit 0b08c8437c
1 changed files with 7 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
hooks.md
View file

@ -2,7 +2,7 @@
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. 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]). 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. CRI-O and `podman 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 enabled all hooks, every container would have to execute `oci-systemd-hook`, even if they don't run systemd inside of the container. Performance would also suffer if we exectuted each hook at each stage ([pre-start][], [post-start][], and [post-stop][]). 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 enabled all hooks, every container would have to execute `oci-systemd-hook`, even if they don't run systemd inside of the container. Performance would also suffer if we exectuted each hook at each stage ([pre-start][], [post-start][], and [post-stop][]).
@ -35,8 +35,10 @@ The matching properties (`cmds`, `annotations` and `hasbindmounts`) are orthogon
## Example ## Example
``` The following configuration tells CRI-O to inject `oci-systemd-hook` in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:
cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
```console
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{ {
"cmds": [".*/init$" , ".*/systemd$" ], "cmds": [".*/init$" , ".*/systemd$" ],
"hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook", "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
@ -44,10 +46,9 @@ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
} }
``` ```
In the above example CRI-O will only run the oci-systemd-hook in the prestart and poststop stage, if the command ends with /init or /systemd The following example tells CRI-O to inject `oci-umount --debug` in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.
```console
```
cat /etc/containers/oci/hooks.d/oci-systemd-hook.json cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{ {
"hasbindmounts": true, "hasbindmounts": true,
@ -56,7 +57,6 @@ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
"arguments": [ "--debug" ] "arguments": [ "--debug" ]
} }
``` ```
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.
[JSON]: https://tools.ietf.org/html/rfc8259 [JSON]: https://tools.ietf.org/html/rfc8259
[POSIX-ERE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04 [POSIX-ERE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04