You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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]: opencontainers/runtime-spec#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]: opencontainers/runc#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 <[email protected]>
Copy file name to clipboardExpand all lines: runtime.md
+74-12Lines changed: 74 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,53 +33,91 @@ For example, POSIX systems define [`LANG` and related environment variables][pos
33
33
34
34
## Commands
35
35
36
-
### start
36
+
### create
37
37
38
-
Start a container from a [bundle directory][bundle].
38
+
[Create][create] a container from a [bundle directory][bundle].
39
39
40
40
**Arguments*
41
41
**`<ID>`* Set the container ID to create.
42
42
**Options*
43
43
**`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory).
44
-
**Standard streams:* The runtime MUST attach its standard streams directly to the container process without inspection.
44
+
**Standard streams:*
45
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
46
+
**stdout:* The handling of stdout is unspecified.
47
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
45
48
**Environment variables*
46
49
**`LISTEN_FDS`:* The number of file descriptors passed.
47
50
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].
48
-
**Exit code:* The runtime MUST exit with the container process's exit code.
51
+
**Exit code:* Zero if the container was successfully created and non-zero on errors.
52
+
53
+
Callers MAY block on this command's successful exit to trigger post-create activity.
49
54
50
55
#### Example
51
56
52
57
```
53
58
# in a bundle directory with a process that echos "hello" and exits 42
59
+
$ test -t 1 && echo 'stdout is a terminal'
60
+
stdout is a terminal
61
+
$ funC create hello-1 <&- >stdout 2>stderr
62
+
$ echo $?
63
+
0
64
+
$ wc stdout
65
+
0 0 0 stdout
54
66
$ funC start hello-1
67
+
$ echo $?
68
+
0
69
+
$ cat stdout
55
70
hello
56
-
71
+
$ block-on-exit-and-collect-exit-code hello-1
57
72
$ echo $?
58
73
42
74
+
$ funC delete hello-1
75
+
$ echo $?
76
+
0
59
77
```
60
78
79
+
#### Container process exit
80
+
81
+
The [example's](#example)`block-on-exit-and-collect-exit-code` is platform-specific and is not specified in this document.
82
+
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.
83
+
84
+
### start
85
+
86
+
[Start][start] the user-specified code from [`process`][process].
87
+
88
+
**Arguments*
89
+
**`<ID>`* The container to start.
90
+
**Standard streams:*
91
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
92
+
**stdout:* The handling of stdout is unspecified.
93
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
94
+
**Exit code:* Zero if the container was successfully started and non-zero on errors.
95
+
96
+
Callers MAY block on this command's successful exit to trigger post-start activity.
97
+
98
+
See [create](#example) for an example.
99
+
61
100
### state
62
101
63
-
Request the container state.
102
+
[Request][state-request] the container [state][state].
64
103
65
104
**Arguments*
66
105
**`<ID>`* The container whose state is being requested.
67
106
**Standard streams:*
68
107
**stdin:* The runtime MUST NOT attempt to read from its stdin.
69
-
**stdout:* The runtime MUST print the state JSON to its stdout.
108
+
**stdout:* The runtime MUST print the [state JSON][state] to its stdout.
70
109
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
71
110
**Exit code:* Zero if the state was successfully written to stdout and non-zero on errors.
72
111
73
112
#### Example
74
113
75
114
```
76
-
# in a bundle directory with a process that sleeps for several seconds
77
-
$ funC start sleeper-1 &
115
+
$ funC create sleeper-1
78
116
$ funC state sleeper-1
79
117
{
80
118
"ociVersion": "1.0.0-rc1",
81
119
"id": "sleeper-1",
82
-
"status": "running",
120
+
"status": "created",
83
121
"pid": 4422,
84
122
"bundlePath": "/containers/sleeper",
85
123
"annotations" {
@@ -113,8 +151,9 @@ $ echo $?
113
151
#### Example
114
152
115
153
```
116
-
# in a bundle directory with a process ignores TERM
117
-
$ funC start sleeper-1 &
154
+
# in a bundle directory where the container process ignores TERM
155
+
$ funC create sleeper-1
156
+
$ funC start sleeper-1
118
157
$ funC kill sleeper-1
119
158
$ echo $?
120
159
0
@@ -123,15 +162,38 @@ $ echo $?
123
162
0
124
163
```
125
164
165
+
### delete
166
+
167
+
[Release](#delete) container resources after the container process has exited.
168
+
169
+
**Arguments*
170
+
**`<ID>`* The container to delete.
171
+
**Standard streams:*
172
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
173
+
**stdout:* The handling of stdout is unspecified.
174
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
175
+
**Exit code:* Zero if the container was successfully deleted and non-zero on errors.
0 commit comments