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

72 lines
4.7 KiB
Markdown
Raw Normal View History

Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
# OCI Hooks Configuration
hooks: Punt hook documentation to the runtime spec No need to repeat the specification here, just link to the version we generate. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 18:27:37 +00:00
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]).
hooks: Example copy-edits (backticks, etc.) 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>
2018-02-20 19:15:46 +00:00
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.
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
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][]).
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
## Notational Conventions
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
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][rfc2119].
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
## JSON Definition
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
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.
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
Each JSON file should contain an object with the following properties:
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
* **`hook`** (REQUIRED, string) Sets [`path`][spec-hooks] in the injected hook.
* **`arguments`** (OPTIONAL, array of strings) Additional arguments to pass to the hook.
The injected hook's [`args`][spec-hooks] is `hook` with `arguments` 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 configured [`process.args[0]`][spec-process] matches an entry.
Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`annotations`** (OPTIONAL, array of strings) The hook MUST be injected if the configured [`annotations`][spec-annotations] matches an entry.
Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`hasbindmounts`** (OPTIONAL, boolean) The hook MUST be injected if `hasbindmounts` is true and the container is configured to bind-mount host directories into the container.
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
The matching properties (`cmds`, `annotations` and `hasbindmounts`) are orthogonal, and the hook is injected if *any* of those properties match.
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
## Example
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Example copy-edits (backticks, etc.) 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>
2018-02-20 19:15:46 +00:00
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`:
```console
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
{
"cmds": [".*/init$" , ".*/systemd$" ],
"hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
"stages": [ "prestart", "poststop" ]
}
```
hooks: Example copy-edits (backticks, etc.) 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>
2018-02-20 19:15:46 +00:00
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.
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
hooks: Example copy-edits (backticks, etc.) 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>
2018-02-20 19:15:46 +00:00
```console
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
"hasbindmounts": true,
"hook": "/usr/libexec/oci/hooks.d/oci-umount",
"stages": [ "prestart" ]
Allow additional arguments to be passed into hooks If a packager wants to be able to support addititional arguments on his hook this will allow them to setup the configuration with these arguments. For example this would allow a hook developer to add support for a --debug flag to change the level of debugging in his hook. In order to complete this task, I had to vendor in the latest github.com://opencontainers/runtime-tools, which caused me to have to fix a Mount and Capability interface calls Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2018-01-04 15:53:55 +00:00
"arguments": [ "--debug" ]
Add support for oci-hooks to libkpod Add new directory /etc/crio/hooks.d, where packagers can drop a json config file to specify a hook. The json must specify a valid executable to run. The json must also specify which stage(s) to run the hook: prestart, poststart, poststop The json must specify under which criteria the hook should be launched If the container HasBindMounts If the container cmd matches a list of regular expressions If the containers annotations matches a list of regular expressions. If any of these match the the hook will be launched. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2017-08-12 10:29:22 +00:00
}
```
hooks: Punt hook documentation to the runtime spec No need to repeat the specification here, just link to the version we generate. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 18:27:37 +00:00
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
[JSON]: https://tools.ietf.org/html/rfc8259
[POSIX-ERE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04
[post-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststart
[post-stop]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststop
[pre-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#prestart
[rfc2119]: http://tools.ietf.org/html/rfc2119
hooks: Punt hook documentation to the runtime spec No need to repeat the specification here, just link to the version we generate. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 18:27:37 +00:00
[runc]: https://github.com/opencontainers/runc
[runtime-spec]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/spec.md
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
[spec-annotations]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#annotations
hooks: Punt hook documentation to the runtime spec No need to repeat the specification here, just link to the version we generate. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 18:27:37 +00:00
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks
hooks: Use RFC 2119 for the hook configuration specification Make this more like the runtime spec, using the RFC 2119 keywords for both JSON-author and CRI-O requirements. This also clarifies the regular expression language (POSIX EREs), links to a JSON spec, and tightens wording for the various matching criteria. I think the hook-config format could be improved (versioning it, and reusing the runtime-spec hook structure instead of renaming 'path' to 'hook', dropping 'timeout', etc.). But I'm leaving that sort of thing to future work. Signed-off-by: W. Trevor King <wking@tremily.us>
2018-02-20 19:08:16 +00:00
[spec-process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#process
Reference in a new issue Copy permalink