From 62dfd5c5219b6047b4fcd484c957f6eb017e975a Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 17 Dec 2015 07:38:23 -0800 Subject: [PATCH] start: Add a --state option This gives us an easy way to share state JSON (because sometimes the PID is insufficient, e.g. on Linux you may need externalFds for efficient checkpointing [1,2]) [3]. Possible alternatives for transmitting state information, and why I feel this approach is superior: * Writing a state file from a pre-start hook [4]. This is pretty close to the --state option, but the --state option allows callers to recover the JSON via a named pipe like /dev/fd/3. That sort of direct connection would be trickier to setup with a hook-based approach. Pre-start and post-stop hooks may still be the best solution for (de)registering a container with a monitoring service, but that's not quite the same application. * Writing a state file to a global directory [5]. Atomic changes, change-monitoring, garbage collection, and ownership/access issues on a global directory are all hard to get right (or have ambiguous values of "right") [6]. * Requiring runtimes to maintain an internal registry of containers they launch [7]. This gives runtimes more flexibility than having a single, global directory. But ownership/access issues are still difficult (if one unprivileged user registers a container, can another unprivileged user see that entry? What elevated permissions would you need to see that entry? To remove that entry?). And the easiest way to get atomic changes and garbage-collection is by registering with a daemon, while not requiring a daemon is currently the #1 feature listed on [8]. In the event that any of those arguments seem leaky, callers that prefer a different approach can easily use hooks (without setting --state) or write wrappers that use a named pipe approach like (--state /dev/fd/3) to collect the JSON and then write it to their preferred registry. So the --state approach seems easy for the runtime to implement reliably, and also compatible with any of the suggested alternatives. The converse is not true; requiring a write to a global or per-runtime registry is not compatible with use-cases that prefer the anonymity of not writing the state at all (which is possible just by leaving off the --state option). [1]: https://github.com/opencontainers/specs/pull/87#discussion_r38185498 [2]: https://groups.google.com/a/opencontainers.org/d/msg/dev/z25xQsF3pHA/ixyeTrxyFwAJ Subject: Re: Drop /run/opencontainer entirely? Date: Fri, 4 Sep 2015 21:30:24 -0700 Message-ID: <20150905043024.GB25638@odin.tremily.us> [3]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/W1RVyCXCCQAJ Subject: Re: removal of /run/opencontainer/containers, add --state? Date: Tue, 8 Dec 2015 15:49:57 -0800 Message-ID: <20151208234957.GK2767@odin.tremily.us> [4]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/GQs0zkRHBwAJ Subject: Re: removal of /run/opencontainer/containers Date: Mon, 30 Nov 2015 13:55:40 -0800 Message-ID: <20151130215540.GF23595@odin.tremily.us> [5]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime.md#state [6]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/JRm4auylBQAJ Subject: removal of /run/opencontainer/containers Date: Wed, 25 Nov 2015 14:29:35 +0000 Message-ID: [7]: https://groups.google.com/a/opencontainers.org/d/msg/dev/q6TYqVZOcX8/wHYucS-rBQAJ Subject: Re: removal of /run/opencontainer/containers Date: Wed, 25 Nov 2015 08:06:10 -0800 Message-ID: [8]: http://runc.io/ Embeddable Containers are started as a child process of runC and can be embedded into various other systems without having to run a Docker daemon. Signed-off-by: W. Trevor King --- runtime.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/runtime.md b/runtime.md index d56042e..b1ad453 100644 --- a/runtime.md +++ b/runtime.md @@ -52,6 +52,8 @@ Start a container from a bundle directory. * *`--id `* Set the container ID when creating or joining a container. If not set, the runtime is free to pick any ID that is not already in use. * *`--bundle `* Override the path to the bundle directory (defaults to the current working directory). + * *`--state `* The runtime MUST write the state JSON to this path (creating a new file or truncating a previous file as necessary). + The path may not support seeking (e.g. `/dev/fd/3`). * *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection. * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. @@ -61,11 +63,18 @@ Start a container from a bundle directory. Example: ```sh # in a bundle directory with a process that echos "hello" and exits 42 -$ funC start --id hello-1 +$ funC start --id hello-1 --state hello.json hello $ echo $? 42 +$ cat hello.json +{ + "version": "0.1.0", + "id": "hello-1", + "pid": 4422, + "root": "/var/lib/oci/hello" +} ``` [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02