From 60148f0fc04f8e60166d6381e26c0dcaa3d86b47 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 22 Jun 2016 12:36:52 -0700 Subject: [PATCH] runtime: Add a 'state' command Partially catch up with opencontainers/runtime-spec@7117ede7 (Expand on the definition of our ops, 2015-10-13, opencontainers/runtime-spec#225, v0.4.0). The state example is adapted from the current release [1], but we defer the actual definition of that JSON to runtime-spec. The encoding for the output JSON (and all standard-stream activity) is covered by the "Character encodings" section. In cases where the runtime ignores the SHOULD (still technically compliant), RFC 7159 makes encoding detection reasonably straightforward [2]. The obsolete RFC 4627 has some hints as well [3] (although these were dropped in RFC 7518 [4], probably as a result of removing the constraint that "JSON text" be an object or array [4]). The hints should still apply to the state output, because we know it will be an object. If that ends up being too dicey and we want to certify runtimes that do not respect their operating-system conventions, we can add an --encoding option later. [1]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc1/runtime.md#state [2]: https://tools.ietf.org/html/rfc7159#section-8.1 [3]: https://tools.ietf.org/html/rfc4627#section-3 [4]: https://tools.ietf.org/html/rfc7158#appendix-A Which is currently identical to 7519. Signed-off-by: W. Trevor King --- runtime.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/runtime.md b/runtime.md index 7c85e00..09d2694 100644 --- a/runtime.md +++ b/runtime.md @@ -70,6 +70,38 @@ $ echo $? 42 ``` +### state + +Request the container 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. + * *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 --id sleeper-1 & +$ funC state sleeper-1 +{ + "ociVersion": "1.0.0-rc1", + "id": "sleeper-1", + "status": "running", + "pid": 4422, + "bundlePath": "/containers/sleeper", + "annotations" { + "myKey": "myValue" + } +} +$ echo $? +0 +``` + [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