docs/command-line-interface: Add Runtime CLI Spec #321
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Julian Friedman <[email protected]>
To match the specs convention [1]. [1]: https://github.com/opencontainers/specs/blob/v0.1.1/README.md#markdown-style Signed-off-by: W. Trevor King <[email protected]>
Otherwise they're rendered as a single paragraph. Signed-off-by: W. Trevor King <[email protected]>
See [1]. 'sh' keyword comes from [2], and seemed more explicit to the POSIX semantics than 'shell'. [1]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting [2]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml Signed-off-by: W. Trevor King <[email protected]>
It's pretty clear that the header describes the rest of the file's contents without the colon ;). Signed-off-by: W. Trevor King <[email protected]>
I think that's the possessive form of 'process' ;). Signed-off-by: W. Trevor King <[email protected]>
To give space for more detail about the streams. I'm not sure what platform-agnostic language for this should look like, but on POSIX I'm expecting just exec'ing the application process and inheriting the file descriptors. Signed-off-by: W. Trevor King <[email protected]>
Signed-off-by: W. Trevor King <[email protected]>
Catch up with [1]. [1]: opencontainers/runtime-spec#88 Signed-off-by: W. Trevor King <[email protected]>
Use GNU-style long options to avoid ambiguous, one-character options in the spec, while still allowing the runtime to support one-character options with packing. Signed-off-by: W. Trevor King <[email protected]>
Let folks do whatever they want as long as they don't clobber our command namespace. Signed-off-by: W. Trevor King <[email protected]>
Make it easy for a caller to report which runtime they're using. Signed-off-by: W. Trevor King <[email protected]>
Give the user a consistent way to pick their container ID. For example, they may want to use: --id $(dirname "$PWD") or they may want to use: --id $(uuidgen) or they may want to leave ID generation to the runtime. Signed-off-by: W. Trevor King <[email protected]>
You shouldn't need these for any other operations. Signed-off-by: W. Trevor King <[email protected]>
Signed-off-by: W. Trevor King <[email protected]>
Mostly for stopping them, but also useful for any number of signals (e.g. many applications use HUP to reload their configuration). Signed-off-by: W. Trevor King <[email protected]>
On IRC just now: 10:56 < crosbymichael> if the main process dies in the container, all other process are killed ... 10:58 < julz> crosbymichael: Im assuming what you mean is you kill everything in the cgroup -> everything in the container dies? 10:58 < crosbymichael> julz: yes, that is how its implemented ... 10:59 < crosbymichael> julz: we actually freeze first, send the KILL, then unfreeze so we don't have races We don't have lifecycle docs for that yet, but once we do, we can update this to link to them. Signed-off-by: W. Trevor King <[email protected]>
These are useful for checkpointing, since getting a consistent checkpoint of a running container is hard ;). This doesn't handle the checkpoints themselves though, which are currently not specified. Checkpoint behavior will look something like: $ funC pause --wait container-id $ checkpoint ... $ funC resume container-id Signed-off-by: W. Trevor King <[email protected]>
This landed in runC with [1], but the bundle-author <-> runtime specs explicitly avoid talking about how this is set (since the bundle-author doesn't care about the runtime-caller <-> runtime interface) [2]. However, *this* spec is about the runtime-caller <-> runtime interface, so we need to document it here. I've left LISTEN_PID [3,4] out, since I don't see how the runtime-caller would choose anything other than 1 for its value. It seems like something that a process would have to set for itself (because guessing the PID of a child before spawning it seems racy ;). In any event, the runC implementation seems to set this to 1 regardless of what systemd passes to it [4]. I've borrowed Shishir's wording for the example [4]. [1]: opencontainers/runc#231 [2]: opencontainers/runtime-spec#113 (comment) [3]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [4]: opencontainers/runc#231 (comment) Signed-off-by: W. Trevor King <[email protected]>
Signed-off-by: Michael Crosby <[email protected]> Cherry-picked from [1]. [1]: opencontainers/runtime-spec@84707b0 Signed-off-by: W. Trevor King <[email protected]>
See https://github.com/blog/1184-contributing-guidelines Also strip some trailing whitespace. Signed-off-by: W. Trevor King <[email protected]>
Signed-off-by: W. Trevor King <[email protected]>
Without this, "may contain any Unicode characters" seemed too
ambiguous.
I wish there were cleaner references for the {language}.{encoding}
locales like en_US.UTF-8 and UTF-8. But [1,2] seems too glib, and I
can't find a more targetted UTF-8 link than just dropping folks into a
Unicode chapter (which is what [1] does):
The Unicode Standard, Version 6.0, §3.9 D92, §3.10 D95 (2011)
With the current v8.0 (2015-06-17), it's still §3.9 D92 and §3.10 D95.
The TR35 link is for:
In addition, POSIX locales may also specify the character encoding,
which requires the data to be transformed into that target encoding.
and the POSIX §6.2 link is for:
In other locales, the presence, meaning, and representation of any
additional characters are locale-specific.
[1]: https://en.wikipedia.org/wiki/UTF-8
[2]: https://en.wikipedia.org/wiki/Locale#POSIX_platforms
Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Jesse Butler <[email protected]>
The other commands have the following layout:
### {command name}
{one-line description}
* *Options:* ...
...
* *Exit code:* ...
{additional notes}
{example}
so its good to follow that pattern for 'version'.
This commit also removes a dangling "The version" which snuck in with
ffa124c (Add a 'version' command, 2015-09-14).
Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>
With: $ sed -i 's/[[:space:]]*$//' * Signed-off-by: W. Trevor King <[email protected]> Reviewed-by: Mike Brown <[email protected]>
All of these require state information to be shared between funC invocations (to map from a container ID to the cgroups/namespaces/etc.), and after today's meeting we may be backing away from that [1,2]. Even if we keep a requirement for sharing state between funC invocations, we don't want to specify these IPC-requiring commands until we have more clarity on that requirement in the spec. On systems like Solaris, the kernel maintains a registry of container IDs directly, so they don't need an external registry [3]. But without a consensus around the minimal amount of inter-process state sharing, we don't want to require container ID → state lookups in the command-line spec. Once we have more clarity on a minimal required mechanism (e.g. Julz's --state-file [4,5,6]), we can add them back in with an API that all runtimes can easily support (although runtimes are of course free to provide more convenient APIs as additional extensions). Pause, resume, and signal are still in the current lifecycle pull request [7], but I've requested they be removed until we have more clarity around the basic lifecycle [8]. [1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-12-02-18.01.html [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-12-02-18.01.log.html#l-79 [3]: wking/oci-command-line-api#3 (comment) [4]: wking/oci-command-line-api#3 (comment) [5]: wking/oci-command-line-api#3 (comment) [6]: wking/oci-command-line-api#3 (comment) [7]: mrunalp/specs@bd549a2#diff-b84a8d65d8ed53f4794cd2db7e8ea731R48 [8]: https://github.com/opencontainers/specs/pull/231/files#r45532412 Signed-off-by: W. Trevor King <[email protected]> Reviewed-by: Mike Brown <[email protected]> Reviewed-by: Jesse Butler <[email protected]> Reviewed-by: Julian Friedman <[email protected]>
This makes everything consistent with the version command's:
Print the runtime version and exit.
And follows the practice recommended by Python's PEP 257 [1]:
The docstring is a phrase ending in a period. It prescribes the
function or method's effect as a command ("Do this", "Return that"),
not as a description; e.g. don't write "Returns the pathname ...".
[1]: https://www.python.org/dev/peps/pep-0257/#one-line-docstrings
Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>
The reference landed in the initial 3f0aafb (Add initial command line spec, 2015-09-02) in the operations section. In f3a1c08 (Shift config.json and runtime.json into the 'start' section, 2015-09-15) they moved to the 'start' command section, because other commands don't need them. But we talk about them in start's options section since 9d97d39 (Add --config and --runtime options, 2015-09-14), so there's no need for this command-scoped reference. Signed-off-by: W. Trevor King <[email protected]> Reviewed-by: Mike Brown <[email protected]>
While reviewing the `global options` section in `runtime.md`, it seemed additional clarity was needed for the `command` and `global options` requirements. Discussed and worked on wording with @wking via private IRC. Also adds uppercase RFC 2119 words for this section. With regard to the statement `Command names MUST not start with hyphens,` the rationale behind this decision is to "distinguish unrecognized commands from unrecognized options, and because we are "requiring runtimes to fail-fast for unrecognized commands" [1,2]. `[1]` https://github.com/wking/oci-command-line-api/pull/8/files#r46898167 `[2]` wking/oci-command-line-api@527f3c6#commitcomment-14835617 Signed-off-by: Mike Brown <[email protected]> Reviewed-by: W. Trevor King <[email protected]>
Personally I prefer a single config file [1]. I want folks to be able to pipe their config into the 'funC start' command (e.g. via a /dev/fd/3 pseudo-filesystem path) [2], and I have a working example that supports this without difficulty [3]. But since [4] landed on 2015-11-16, runC has replaced their --config-file and --runtime-file flags with --bundle, and the current goal of this repository is "keeping as much similarity with the existing runC command-line as possible", not "makes sense to Trevor" ;). [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <[email protected]> [2]: opencontainers/runc#202 [3]: https://github.com/wking/ccon/tree/8ab5b535b5eca1a62e12b5e865735e24f1e1666d#configuration [4]: opencontainers/runc#373 Signed-off-by: W. Trevor King <[email protected]> Reviewed-by: Mike Brown <[email protected]>
wking
force-pushed
the
command-line-api
branch
from
afdf059 to
6d8cfe2
Compare
Contributor
Author
Closed
Member
|
LGTM |
Contributor
|
@wking Can you squash the commits before merge? |
wking
changed the title
Contributor
Author
|
On Wed, Mar 15, 2017 at 04:08:28PM -0700, Mrunal Patel wrote:
@wking Can you squash the commits before merge?
I'd still rather have the maintainers do the squash if they want
things squashed (GitHub should give you a button for it [1], and you
can do it from the command line with ‘git merge --squash …’), because
it makes ‘git blame …’ pretty useless [2].
I've just pushed 6d8cfe2 → 7eaa0b8 adding the JSON Schema and removing
the WIP prefix.
I'm not aware or (or maybe just don't remember ;) any other issues
with the current content floated in 7eaa0b8 outside of the “the Unix
socket bits will probably not work on non-POSIX systems”. Ping
@RobDolinMS again on that score.
[1]: https://github.com/blog/2141-squash-your-commits
[2]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-02-10.log.html#t2017-02-10T00:23:41
|
Contributor
Author
mrunalp
reviewed
Mar 17, 2017
schema/socket-terminal-request.json
Outdated
| @@ -0,0 +1,24 @@ | |||
| { | |||
| "description": "Open Container Runtime Socket Teminal Request Schema", | |||
Contributor
Author
…ket messages Even though there aren't many new types, these are fairly different from the rest of the runtime-tools code, and a separate package lets folks pull in only the code they need (assuming they are sophisticated enough to grab only a subset of the Git repository). Mrunal approved the JSON Schema landing under schema/ [1]. [1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-03-15-21.02.log.html#l-122 Signed-off-by: W. Trevor King <[email protected]>
Catching up with erratum 499 [1]. [1]: https://www.rfc-editor.org/errata_search.php?rfc=2119&eid=499 Signed-off-by: W. Trevor King <[email protected]>
|
LGTM |
Member
|
LGTM and I'll squash the commits while merging it. |
wking
added a commit
to wking/ocitools-v2
that referenced
this pull request
Jan 11, 2018
Make docs/, which landed in 7a4cb36 (docs/command-line-interface: Add Runtime CLI Spec, 2018-01-09, opencontainers#321), more discoverable. Also document the 'RUNTIME' option.
wking
added a commit
to wking/ocitools-v2
that referenced
this pull request
Jan 11, 2018
Make docs/, which landed in 7a4cb36 (docs/command-line-interface: Add Runtime CLI Spec, 2018-01-09, opencontainers#321), more discoverable. Also document the 'RUNTIME' option. Signed-off-by: W. Trevor King <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Transferred from opencontainers/runtime-spec#513 as discussed in yesterday's meeting. @mrunalp gave me some pointers on how he wanted this landed here and here.
I'm not squashing this down into a single commit, because it's a lot easier for me to manage revisions if I keep a branch in the stand-alone repository. I would encourage reviewers (CC @RobDolinMS and @stevvooe, who expressed an interest in reviewing this stuff) to file issues/PRs against that repository so this PR doesn't get bogged down into the same morass as the runtime-spec PR; this PR would get updated to pull those in as I land the sub-PRs in the stand-alone repo. @mrunalp thinks we might end up squashing this just before merging, and how that goes is clearly up to the runtime-tools maintainers, but squashing (if it happens at all) should be after substantive review settles.
The WIP tag in the summary is because I'm still not sure where runtime-tools maintainers want the JSON Schema from the runtime-spec PR.
@mrunalp was also open to some compliance language, but I haven't figured that out yet because the pattern set in RFC 2616 (which runtime-spec followed) wasn't even repeated by RFC 7230 (which obsoleted RFC 2616). I need some time to compare the differences in the RFC wording before I can float appropriate wording for the command line API.