From ecac3a9e104aaef841579eb7af9a7228e4c3ebd4 Mon Sep 17 00:00:00 2001 From: Yushuo Date: Tue, 27 Dec 2022 17:53:04 +0800 Subject: [PATCH] docs: add design doc for Hooks Fixes: #5787 Signed-off-by: Yushuo --- docs/design/README.md | 1 + docs/design/hooks-handling.md | 62 +++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 docs/design/hooks-handling.md diff --git a/docs/design/README.md b/docs/design/README.md index d2a9414ef..0c732defd 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -11,6 +11,7 @@ Kata Containers design documents: - [Host cgroups](host-cgroups.md) - [Agent systemd cgroup](agent-systemd-cgroup.md) - [`Inotify` support](inotify.md) +- [`Hooks` support](hooks-handling.md) - [Metrics(Kata 2.0)](kata-2-0-metrics.md) - [Design for Kata Containers `Lazyload` ability with `nydus`](kata-nydus-design.md) - [Design for direct-assigned volume](direct-blk-device-assignment.md) diff --git a/docs/design/hooks-handling.md b/docs/design/hooks-handling.md new file mode 100644 index 000000000..9a5edd907 --- /dev/null +++ b/docs/design/hooks-handling.md @@ -0,0 +1,62 @@ +# Kata Containers support for `Hooks` + +## Introduction + +During container's lifecycle, different Hooks can be executed to do custom actions. In Kata Containers, we support two types of Hooks, `OCI Hooks` and `Kata Hooks`. + +### OCI Hooks + +The OCI Spec stipulates six hooks that can be executed at different time points and namespaces, including `Prestart Hooks`, `CreateRuntime Hooks`, `CreateContainer Hooks`, `StartContainer Hooks`, `Poststart Hooks` and `Poststop Hooks`. We support these types of Hooks as compatible as possible in Kata Containers. + +The path and arguments of these hooks will be passed to Kata for execution via `bundle/config.json`. For example: +``` +... +"hooks": { + "prestart": [ + { + "path": "/usr/bin/prestart-hook", + "args": ["prestart-hook", "arg1", "arg2"], + "env": [ "key1=value1"] + } + ], + "createRuntime": [ + { + "path": "/usr/bin/createRuntime-hook", + "args": ["createRuntime-hook", "arg1", "arg2"], + "env": [ "key1=value1"] + } + ] +} +... +``` + +### Kata Hooks + +In Kata, we support another three kinds of hooks executed in guest VM, including `Guest Prestart Hook`, `Guest Poststart Hook`, `Guest Poststop Hook`. + +The executable files for Kata Hooks must be packaged in the *guest rootfs*. The file path to those guest hooks should be specified in the configuration file, and guest hooks must be stored in a subdirectory of `guest_hook_path` according to their hook type. For example: + ++ In configuration file: +``` +guest_hook_path="/usr/share/hooks" +``` ++ In guest rootfs, prestart-hook is stored in `/usr/share/hooks/prestart/prestart-hook`. + +## Execution +The table below summarized when and where those different hooks will be executed in Kata Containers: + +| Hook Name | Hook Type | Hook Path | Exec Place | Exec Time | +|---|---|---|---|---| +| `Prestart(deprecated)` | OCI hook | host runtime namespace | host runtime namespace | After VM is started, before container is created. | +| `CreateRuntime` | OCI hook | host runtime namespace | host runtime namespace | After VM is started, before container is created, after `Prestart` hooks. | +| `CreateContainer` | OCI hook | host runtime namespace | host vmm namespace | After VM is started, before container is created, after `CreateRuntime` hooks. | +| `StartContainer` | OCI hook | guest container namespace | guest container namespace | After container is created, before container is started. | +| `Poststart` | OCI hook | host runtime namespace | host runtime namespace | After container is started, before start operation returns. | +| `Poststop` | OCI hook | host runtime namespace | host runtime namespace | After container is deleted, before delete operation returns. | +| `Guest Prestart` | Kata hook | guest agent namespace | guest agent namespace | During start operation, before container command is executed. | +| `Guest Poststart` | Kata hook | guest agent namespace | guest agent namespace | During start operation, after container command is executed, before start operation returns. | +| `Guest Poststop` | Kata hook | guest agent namespace | guest agent namespace | During delete operation, after container is deleted, before delete operation returns. | + ++ `Hook Path` specifies where hook's path be resolved. ++ `Exec Place` specifies in which namespace those hooks can be executed. ++ `Exec Time` specifies at which time point those hooks can be executed. \ No newline at end of file