From f6a2b6bf2b923a148792cc141ec4c27b5889c077 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 19 Nov 2018 09:22:32 -0800 Subject: hooks: Add pre-create hooks for runtime-config manipulation There's been a lot of discussion over in [1] about how to support the NVIDIA folks and others who want to be able to create devices (possibly after having loaded kernel modules) and bind userspace libraries into the container. Currently that's happening in the middle of runc's create-time mount handling before the container pivots to its new root directory with runc's incorrectly-timed prestart hook trigger [2]. With this commit, we extend hooks with a 'precreate' stage to allow trusted parties to manipulate the config JSON before calling the runtime's 'create'. I'm recycling the existing Hook schema from pkg/hooks for this, because we'll want Timeout for reliability and When to avoid the expense of fork/exec when a given hook does not need to make config changes [3]. [1]: https://github.com/opencontainers/runc/pull/1811 [2]: https://github.com/opencontainers/runc/issues/1710 [3]: https://github.com/containers/libpod/issues/1828#issuecomment-439888059 Signed-off-by: W. Trevor King --- docs/libpod.conf.5.md | 4 +++- docs/podman.1.md | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/libpod.conf.5.md b/docs/libpod.conf.5.md index c02d247fb..98eb5bece 100644 --- a/docs/libpod.conf.5.md +++ b/docs/libpod.conf.5.md @@ -37,7 +37,9 @@ libpod to manage containers. For the bind-mount conditions, only mounts explicitly requested by the caller via `--volume` are considered. Bind mounts that libpod inserts by default (e.g. `/dev/shm`) are not considered. - If `hooks_dir` is unset for root callers, Podman and libpod will currently default to `/usr/share/containers/oci/hooks.d` and `/etc/containers/oci/hooks.d` in order of increasing precedence. Using these defaults is deprecated, and callers should migrate to explicitly setting `hooks_dir`. + Podman and libpod currently support an additional `precreate` state which is called before the runtime's `create` operation. Unlike the other stages, which receive the container state on their standard input, `precreate` hooks receive the proposed runtime configuration on their standard input. They may alter that configuration as they see fit, and write the altered form to their standard output. + + **WARNING**: the `precreate` hook lets you do powerful things, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running your container with `precreate` hooks disabled to see if the problem is due to one of your hooks. **static_dir**="" Directory for persistent libpod files (database, etc) diff --git a/docs/podman.1.md b/docs/podman.1.md index bde349e6f..a73ebb55e 100644 --- a/docs/podman.1.md +++ b/docs/podman.1.md @@ -43,6 +43,10 @@ For the bind-mount conditions, only mounts explicitly requested by the caller vi If `--hooks-dir` is unset for root callers, Podman and libpod will currently default to `/usr/share/containers/oci/hooks.d` and `/etc/containers/oci/hooks.d` in order of increasing precedence. Using these defaults is deprecated, and callers should migrate to explicitly setting `--hooks-dir`. +Podman and libpod currently support an additional `precreate` state which is called before the runtime's `create` operation. Unlike the other stages, which receive the container state on their standard input, `precreate` hooks receive the proposed runtime configuration on their standard input. They may alter that configuration as they see fit, and write the altered form to their standard output. + +**WARNING**: the `precreate` hook lets you do powerful things, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running your container with `precreate` hooks disabled to see if the problem is due to one of your hooks. + **--log-level** Log messages above specified level: debug, info, warn, error (default), fatal or panic -- cgit v1.2.3-54-g00ecf