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>
4.7 KiB
OCI Hooks Configuration
For POSIX platforms, the OCI runtime configuration supports 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
).
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 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).
Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119.
JSON Definition
CRI-O reads all JSON files in /usr/share/containers/oci/hooks.d/*.json
and /etc/containers/oci/hooks.d/*.json
to load hook configuration.
If the same file is in both directories, the one in /etc/containers/oci/hooks.d
takes precedence.
Each JSON file should contain an object with the following properties:
hook
(REQUIRED, string) Setspath
in the injected hook.arguments
(OPTIONAL, array of strings) Additional arguments to pass to the hook. The injected hook'sargs
ishook
witharguments
appended.stages
(REQUIRED, array of strings) Stages when the hook MUST be injected. Entries MUST be chosen from:prestart
, to inject pre-start.poststart
, to inject post-start.poststop
, to inject post-stop.
cmds
(OPTIONAL, array of strings) The hook MUST be injected if the configuredprocess.args[0]
matches an entry. Entries MUST be POSIX extended regular expressions.annotations
(OPTIONAL, array of strings) The hook MUST be injected if the configuredannotations
matches an entry. Entries MUST be POSIX extended regular expressions.hasbindmounts
(OPTIONAL, boolean) The hook MUST be injected ifhasbindmounts
is true and the container is configured to bind-mount host directories into the container.
The matching properties (cmds
, annotations
and hasbindmounts
) are orthogonal, and the hook is injected if any of those properties match.
Example
The following configuration tells CRI-O to inject oci-systemd-hook
in the pre-start and post-stop stages if process.args[0]
ends with /init
or /systemd
:
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
"cmds": [".*/init$" , ".*/systemd$" ],
"hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
"stages": [ "prestart", "poststop" ]
}
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.
cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
"hasbindmounts": true,
"hook": "/usr/libexec/oci/hooks.d/oci-umount",
"stages": [ "prestart" ]
"arguments": [ "--debug" ]
}