From 6f99cc3d973d24d2a5ba4d520da22c65ad452f82 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:43:17 -0800 Subject: [PATCH] runtime: Split 'create' and 'start' (and add 'delete') Catch up with opencontainers/runtime-spec@be594153 (Split create and start, 2016-04-01, opencontainers/runtime-spec#384). One benefit of the early-exit 'create' is that the exit code does not conflate container process exits with "failed to setup the sandbox" exits. We can take advantage of that and use non-zero 'create' exits to allow stderr writing (so the runtime can log errors while dying without having to successfully connect to syslog or some such). I still likes the long-running 'create' API because it makes collecting the exit code easier. I've proposed an 'event' operation [1] which would provide a convenient created trigger. With 'event' in place, we don't need the 'create' process exit to serve as that trigger, and could have a long-running 'create' that collects the container process exit code using the portable waitid() family. But the consensus after the 2016-07-13 meeting was to table that while we land docs for the runC API [2], and runC has an early-exit create [3]. The "Callers MAY block..." wording is going to be hard to enforce, but with the runC model, clients rely on the command exits to trigger post-create and post-start activity. The longer the runtime hangs around after completing its action, the laggier those triggers will be. The "MUST NOT attempt to read from its stdin" means a generic caller can safely exec the command with a closed or null stdin, and not have to worry about the command blocking or crashing because of that. The stdout spec for start/delete is more lenient, because runtimes are unlikely to change their behavior because they are unable to write to stdout. If this assumption proves troublesome, we may have to tighten it up later. The ptrace idea in this commit is from Mrunal [4]. [1]: https://github.com/opencontainers/runtime-spec/pull/508 Subject: runtime: Add an 'event' operation for subscribing to pushes [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-07-13-17.03.log.html#l-15 [3]: https://github.com/opencontainers/runc/pull/827 Summary: Implement create and start [4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2016-07-13.log.html#t2016-07-13T18:58:54 Signed-off-by: W. Trevor King --- runtime.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 12 deletions(-) diff --git a/runtime.md b/runtime.md index e4ca399..496bf0b 100644 --- a/runtime.md +++ b/runtime.md @@ -33,53 +33,91 @@ For example, POSIX systems define [`LANG` and related environment variables][pos ## Commands -### start +### create -Start a container from a [bundle directory][bundle]. +[Create][create] a container from a [bundle directory][bundle]. * *Arguments* * *``* Set the container ID to create. * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). -* *Standard streams:* The runtime MUST attach its standard streams directly to the container process without inspection. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. -* *Exit code:* The runtime MUST exit with the container process's exit code. +* *Exit code:* Zero if the container was successfully created and non-zero on errors. + +Callers MAY block on this command's successful exit to trigger post-create activity. #### Example ``` # in a bundle directory with a process that echos "hello" and exits 42 +$ test -t 1 && echo 'stdout is a terminal' +stdout is a terminal +$ funC create hello-1 <&- >stdout 2>stderr +$ echo $? +0 +$ wc stdout +0 0 0 stdout $ funC start hello-1 +$ echo $? +0 +$ cat stdout hello - +$ block-on-exit-and-collect-exit-code hello-1 $ echo $? 42 +$ funC delete hello-1 +$ echo $? +0 ``` +#### Container process exit + +The [example's](#example) `block-on-exit-and-collect-exit-code` is platform-specific and is not specified in this document. +On Linux, it might involve an ancestor process which had set [`PR_SET_CHILD_SUBREAPER`][prctl.2] and collected the container PID [from the state][state], or a process that was [ptracing][ptrace.2] the container process for [`exit_group`][exit_group.2], although both of those race against the container process exiting before the watcher is monitoring. + +### start + +[Start][start] the user-specified code from [`process`][process]. + +* *Arguments* + * *``* The container to start. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. +* *Exit code:* Zero if the container was successfully started and non-zero on errors. + +Callers MAY block on this command's successful exit to trigger post-start activity. + +See [create](#example) for an example. + ### state -Request the container state. +[Request][state-request] the container [state][state]. * *Arguments* * *``* The container whose state is being requested. * *Standard streams:* * *stdin:* The runtime MUST NOT attempt to read from its stdin. - * *stdout:* The runtime MUST print the state JSON to its stdout. + * *stdout:* The runtime MUST print the [state JSON][state] to its stdout. * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. * *Exit code:* Zero if the state was successfully written to stdout and non-zero on errors. #### Example ``` -# in a bundle directory with a process that sleeps for several seconds -$ funC start sleeper-1 & +$ funC create sleeper-1 $ funC state sleeper-1 { "ociVersion": "1.0.0-rc1", "id": "sleeper-1", - "status": "running", + "status": "created", "pid": 4422, "bundlePath": "/containers/sleeper", "annotations" { @@ -113,8 +151,9 @@ $ echo $? #### Example ``` -# in a bundle directory with a process ignores TERM -$ funC start sleeper-1 & +# in a bundle directory where the container process ignores TERM +$ funC create sleeper-1 +$ funC start sleeper-1 $ funC kill sleeper-1 $ echo $? 0 @@ -123,15 +162,38 @@ $ echo $? 0 ``` +### delete + +[Release](#delete) container resources after the container process has exited. + +* *Arguments* + * *``* The container to delete. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. +* *Exit code:* Zero if the container was successfully deleted and non-zero on errors. + +See [create](#example) for an example. + [bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/bundle.md +[create]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#create +[delete]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#delete +[exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html [kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#kill [kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html +[process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#process [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 [posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 [posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup [posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03 +[prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html +[ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html [semver]: http://semver.org/spec/v2.0.0.html [standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors +[start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#start +[state]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#state +[state-request]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#query-state [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf