From b226a02706f7e541539e444a1f1354c077e63f3d Mon Sep 17 00:00:00 2001 From: Kornilios Kourtis Date: Wed, 18 Sep 2024 11:50:53 +0200 Subject: [PATCH] docs: add sections for configuring rthooks Signed-off-by: Kornilios Kourtis --- .../en/docs/installation/runtime-hooks.md | 57 ++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/docs/content/en/docs/installation/runtime-hooks.md b/docs/content/en/docs/installation/runtime-hooks.md index 453a4df10a7..b694e3fb26a 100644 --- a/docs/content/en/docs/installation/runtime-hooks.md +++ b/docs/content/en/docs/installation/runtime-hooks.md @@ -124,7 +124,7 @@ tetragon-operator-664ddc8957-9lmd2 1/1 Running 0 2m42s tetragon-rthooks-m24xr 1/1 Running 0 2m42s ``` -### Test Runtime hooks +### Test Runtime Hooks Start a pod: ```shell @@ -140,3 +140,58 @@ Output: ```json {"time":"2024-07-01T10:57:21.435689144Z","level":"INFO","msg":"hook request to agent succeeded","hook":"create-container","start-time":"2024-07-01T10:57:21.433755984Z","req-cgroups":"/kubepods/besteffort/podd4e74de2-0db8-4143-ae55-695b2489c727/crio-828977b42e3149b502b31708778d0c057efbce038af80d0882ed3e0cb0ff8796","req-rootdir":"/run/containers/storage/overlay-containers/828977b42e3149b502b31708778d0c057efbce038af80d0882ed3e0cb0ff8796/userdata","req-containerName":"test"} ``` + +## Configuring Runtime Hooks installation + +### Installation directory (`installDir`) + +For tetragon runtime hooks to work, a binary (`tetragon-oci-hook`) needs to be installed on the +host. This happens by the runtime hooks. This binary is installed in `/opt/tetragon` by default. + +In some systems, however, the `/opt` directory is mounted read-only. This will result in +errors such as: + +``` +Warning FailedMount 8s (x5 over 15s) kubelet MountVolume.SetUp failed for volume "oci-hook-install-path" : mkdir /opt/tetragon: read-only file system (6 results) [48/6775] +``` + +You can use the `rthooks.installDir` helm variable to select a different location. For example: + +``` +--set rthooks.installDir=/run/tetragon +``` + + +### Failure check (`failAllowNamespaces`) + +By default, `tetragon-oci-hook` logs information to `/opt/tetragon/tetragon-oci-hook.log`. +Inspecting this file we get the following messages. + +```json +{"time":"2024-03-05T15:18:52.669044463Z","level":"WARN","msg":"hook request to the agent failed","hook":"create-container","start-time":"2024-03-05T15:18:42.667916779Z","req-cgroups":"/kubepods/besteffort/pod43ec7f32-3c9f-429f-a01c-fbaafff9f8e1/crio-1d18fd58f0879f6152a1c421f8f1e0987845394ee17001a16bee2df441c112f3","req-rootdir":"/run/containers/storage/overlay-containers/1d18fd58f0879f6152a1c421f8f1e0987845394ee17001a16bee2df441c112f3/userdata","err":"connecting to agent (context deadline exceeded) failed: unix:///var/run/cilium/tetragon/tetragon.sock"} +{"time":"2024-03-05T15:18:52.66912411Z","level":"INFO","msg":"failCheck determined that we should not fail this container, even if there was an error","hook":"create-container","start-time":"2024-03-05T15:18:42.667916779Z"} +{"time":"2024-03-05T15:18:53.01093915Z","level":"WARN","msg":"hook request to the agent failed","hook":"create-container","start-time":"2024-03-05T15:18:43.01005032Z","req-cgroups":"/kubepods/burstable/pod60f971e6-ac38-4aa0-b2d3-549333b2c803/crio-c0bf4e38bfa4ed5c58dd314d505f8b6a0f513d2f2de4dc4aa86a55c7c3e963ab","req-rootdir":"/run/containers/storage/overlay-containers/c0bf4e38bfa4ed5c58dd314d505f8b6a0f513d2f2de4dc4aa86a55c7c3e963ab/userdata","err":"connecting to agent (context deadline exceeded) failed: unix:///var/run/cilium/tetragon/tetragon.sock"} +{"time":"2024-03-05T15:18:53.010999098Z","level":"INFO","msg":"failCheck determined that we should not fail this container, even if there was an error","hook":"create-container","start-time":"2024-03-05T15:18:43.01005032Z"} +{"time":"2024-03-05T15:19:04.034580703Z","level":"WARN","msg":"hook request to the agent failed","hook":"create-container","start-time":"2024-03-05T15:18:54.033449685Z","req-cgroups":"/kubepods/besteffort/pod43ec7f32-3c9f-429f-a01c-fbaafff9f8e1/crio-d95e61f118557afdf3713362b9034231fee9bd7033fc8e7cc17d1efccac6f54f","req-rootdir":"/run/containers/storage/overlay-containers/d95e61f118557afdf3713362b9034231fee9bd7033fc8e7cc17d1efccac6f54f/userdata","err":"connecting to agent (context deadline exceeded) failed: unix:///var/run/cilium/tetragon/tetragon.sock"} +{"time":"2024-03-05T15:19:04.03463995Z","level":"INFO","msg":"failCheck determined that we should not fail this container, even if there was an error","hook":"create-container","start-time":"2024-03-05T15:18:54.033449685Z"} +``` + +To understand these messages, consider what `tetragon-oci-hook` should do if it +cannot contact the Tetragon agent. + +You may want to stop certain workloads from running. For other workloads (for example, the +tetragon pod itself) you probably want to do the opposite and let the them start. To this end, +`tetragon-oci-hook` checks the container annotations, and by default does not fail a container if it +belongs in the same namespace as Tetragon. The previous messages concern the tetragon containers +(`tetragon-operator` and `tetragon`) and they indicate that the choice was made not to fail this +container from starting. + +Furthermore, users may specify additional namespaces where the container will not fail if the +tetragon agent cannot be contacted via the `rthooks.failAllowNamespaces` option. + +For example: +```yaml +rthooks: + enabled: true + failAllowNamespaces: namespace1,namespace2 +```