2017-03-02 11:00:53 -08:00
# <a name="runtimeAndLifecycle" />Runtime and Lifecycle
2015-06-05 17:39:27 -07:00
2017-03-02 11:00:53 -08:00
## <a name="runtimeScopeContainer" />Scope of a Container
2015-10-13 10:31:03 -07:00
2017-03-15 22:23:53 -07:00
The entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container.
2015-10-13 10:31:03 -07:00
Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification.
2015-07-29 14:09:30 -07:00
2017-03-02 11:00:53 -08:00
## <a name="runtimeState" />State
2015-10-02 13:21:31 -07:00
2016-06-23 14:29:30 -07:00
The state of a container includes the following properties:
2015-10-02 13:21:31 -07:00
2016-06-23 14:29:30 -07:00
* **`ociVersion` ** (string, REQUIRED) is the OCI specification version used when creating the container.
* **`id` ** (string, REQUIRED) is the container's ID.
2015-10-02 13:21:31 -07:00
This MUST be unique across all containers on this host.
There is no requirement that it be unique across hosts.
2016-06-23 14:29:30 -07:00
* **`status` ** (string, REQUIRED) is the runtime state of the container.
2016-05-26 14:20:00 -07:00
The value MAY be one of:
runtime: Replace "process is stopped" with "process exits"
proc(5) describes the following state entries in proc/[pid]/stat [1]
(for modern kernels):
* R Running
* S Sleeping in an interruptible wait
* D Waiting in uninterruptible disk sleep
* Z Zombie
* T Stopped (on a signal)
* t Tracing stop
* X Dead
and ps(1) has a bit more context [2] (for modern kernels):
* D uninterruptible sleep (usually IO)
* R running or runnable (on run queue)
* S interruptible sleep (waiting for an event to complete)
* T stopped by job control signal
* t stopped by debugger during the tracing
* X dead (should never be seen)
* Z defunct ("zombie") process, terminated but not reaped by its
parent
So I expect "stopped" to mean "process still exists but is paused,
e.g. by SIGSTOP". And I expect "exited" to mean "process has finished
and is either a zombie or dead".
After this commit, 'git grep -i stop' only turns up the "stopped"
state (which I've left alone for backwards compat), some poststop-hook
stuff, a reference in principles.md, a "stoppage" in LICENSE, and some
ChangeLog entries.
Also replace "container's process" with "container process" to match
usage in the rest of the repository. After this commit:
$ git grep -i "container process" | wc -l
20
$ git grep -i "container's process" | wc -l
1
Also reword status entries to avoid "running", which is less precise
in our spec (e.g. it also includes "sleeping", "waiting", ...).
Also removes a "them" leftover from a partial plural -> singular
reroll of be594153 (Split create and start, 2016-04-01, #384).
[1]: http://man7.org/linux/man-pages/man5/proc.5.html
[2]: http://man7.org/linux/man-pages/man1/ps.1.html
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-05-26 22:47:52 -07:00
2016-06-23 14:25:00 -07:00
* `creating` : the container is being created (step 2 in the [lifecycle ](#lifecycle ))
* `created` : the runtime has finished the [create operation ](#create ) (after step 2 in the [lifecycle ](#lifecycle )), and the container process has neither exited nor executed the user-specified program
runtime: Remove "features the runtime chooses to support"
Step 3 of the lifecycle from before this commit had two sentences
which both landed in be594153 (Split create and start, 2016-04-01,
#384). I pushed back a bit on the entry then [1,2], but we seem to be
pretty comfortable with the current "keep all lifecyle entries in a
one-layer enumerated list" approach, so I'm leaving that alone in this
commit. Step 3 isn't really a lifecycle step though, it's more about
clarifying that you can jump around in the lifecycle instead of
hitting all the steps in consecutive order. I'd floated a new
paragraph addressing that jumping, but was unable to form a consensus
around wording, and the jumping is already somewhat covered by the
current list entries (e.g. "The container process exits."). This
commit just drops the old step 3, and Michael will follow up with
wording about jumping [3].
The other sentence from the old step 3 doesn't need replacing, because
the limits are already covered in more detail in the operation
sections themselves. For example, the 'delete' operation has:
Attempting to delete a container that does not exist MUST generate
an error. Attempting to delete a container whose process is still
running MUST generate an error.
I don't see the need to call generic attention to that idea, and
especially do not think that an entry in the lifecycle list is the
right place for such a generic call-out.
[1]: https://github.com/opencontainers/runtime-spec/pull/384#r60939710
[2]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-214418730
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-10-21.03.log.html#l-79
Signed-off-by: W. Trevor King <wking@tremily.us>
2017-03-15 23:03:32 -07:00
* `running` : the container process has executed the user-specified program but has not exited (after step 5 in the [lifecycle ](#lifecycle ))
* `stopped` : the container process has exited (step 7 in the [lifecycle ](#lifecycle ))
2016-05-26 14:20:00 -07:00
2016-11-03 09:33:51 +08:00
Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
2016-06-23 14:29:30 -07:00
* **`pid` ** (int, REQUIRED when `status` is `created` or `running` ) is the ID of the container process, as seen by the host.
2017-02-02 11:50:24 -08:00
* **`bundle` ** (string, REQUIRED) is the absolute path to the container's bundle directory.
2015-10-02 13:21:31 -07:00
This is provided so that consumers can find the container's configuration and root filesystem on the host.
2016-06-23 14:29:30 -07:00
* **`annotations` ** (map, OPTIONAL) contains the list of annotations associated with the container.
2016-06-02 13:21:18 -07:00
If no annotations were provided then this property MAY either be absent or an empty map.
2015-07-29 14:09:30 -07:00
2016-06-23 14:29:30 -07:00
The state MAY include additional properties.
2015-10-13 10:31:03 -07:00
When serialized in JSON, the format MUST adhere to the following pattern:
2016-03-17 01:26:12 +00:00
2015-07-29 14:09:30 -07:00
```json
{
2015-10-13 10:31:03 -07:00
"ociVersion": "0.2.0",
"id": "oci-container1",
2016-05-26 14:20:00 -07:00
"status": "running",
2015-07-29 14:09:30 -07:00
"pid": 4422,
2017-02-02 11:50:24 -08:00
"bundle": "/containers/redis",
2016-06-02 13:21:18 -07:00
"annotations": {
"myKey": "myValue"
}
2015-07-29 14:09:30 -07:00
}
```
2015-10-13 10:31:03 -07:00
See [Query State ](#query-state ) for information on retrieving the state of a container.
2017-03-02 11:00:53 -08:00
## <a name="runtimeLifecycle" />Lifecycle
2015-10-22 15:50:40 -04:00
The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
2016-05-26 23:08:11 -07:00
2016-10-25 20:08:22 +08:00
1. OCI compliant runtime's [`create` ](runtime.md#create ) command is invoked with a reference to the location of the bundle and a unique identifier.
2015-10-13 10:31:03 -07:00
2. The container's runtime environment MUST be created according to the configuration in [`config.json` ](config.md ).
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
If the runtime is unable to create the environment specified in the [`config.json` ](config.md ), it MUST [generate an error ](#errors ).
*: Replace "user-specified code" with "user-specified program"
In [1], I'd proposed replacing our old "user-specified process" with
"user-specified code" to help distinguish between 'create' (cloning
the container process) and 'start' (signaling the container process to
execve or similar the user-specified $STUFF_FROM_THE_process_CONFIG).
That PR was rejected, although the renaming proposed there had already
landed via dd0cd210 (Add a 'status' field to our state struct,
2016-05-26, #462).
This PR attempts to find a common ground between "process" (preferred
by maintainers in #466 [2,3,4], but which I consider incorrect [5])
and "code" (which maintainers found confusing [3,4,6]). The Linux
execve(2) says "program" and unpacks that to "a binary executable, or
a script starting with a [shebang]" [7]. proc(5) documents
/proc/[pid]/exe by talking about "the executed command" [8]. The
POSIX exec docs call this the "process image" and talk about loading
it from the "new process image file" (although they also sprinkle in a
number of “program” references, apparently interchangeably with
“process image”) [9].
POSIX formally defines "command" [11], "executable file" [12], and
"program" [13]. The only reference to "process image" in the
definitions is in the "executable file" entry. The "command"
definition is focused on the shell, the "executable file" definition
is focused on files, and the "program" definition talks about a
"prepared sequence of instructions to the system", so "program" seems
like the best fit.
[1]: https://github.com/opencontainers/runtime-spec/pull/466
Subject: runtime: Replace "user-specified process" with "user-specified code" in 'create'
[2]: https://github.com/opencontainers/runtime-spec/pull/466#r64982402
[3]: https://github.com/opencontainers/runtime-spec/pull/466#issuecomment-223132793
[4]: https://github.com/opencontainers/runtime-spec/pull/466#issuecomment-258563220
[5]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_295
[6]: https://github.com/opencontainers/runtime-spec/pull/466#r64982165
[7]: http://man7.org/linux/man-pages/man2/execve.2.html
[8]: http://man7.org/linux/man-pages/man5/proc.5.html
[9]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html
[10]: https://git.kernel.org/cgit/docs/man-pages/man-pages.git/
[11]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_104
[12]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_154
[13]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_306
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-11-18 02:51:51 -08:00
While the resources requested in the [`config.json` ](config.md ) MUST be created, the user-specified program (from [`process` ](config.md#process )) MUST NOT be run at this time.
2016-10-25 20:08:22 +08:00
Any updates to [`config.json` ](config.md ) after this step MUST NOT affect the container.
runtime: Remove "features the runtime chooses to support"
Step 3 of the lifecycle from before this commit had two sentences
which both landed in be594153 (Split create and start, 2016-04-01,
#384). I pushed back a bit on the entry then [1,2], but we seem to be
pretty comfortable with the current "keep all lifecyle entries in a
one-layer enumerated list" approach, so I'm leaving that alone in this
commit. Step 3 isn't really a lifecycle step though, it's more about
clarifying that you can jump around in the lifecycle instead of
hitting all the steps in consecutive order. I'd floated a new
paragraph addressing that jumping, but was unable to form a consensus
around wording, and the jumping is already somewhat covered by the
current list entries (e.g. "The container process exits."). This
commit just drops the old step 3, and Michael will follow up with
wording about jumping [3].
The other sentence from the old step 3 doesn't need replacing, because
the limits are already covered in more detail in the operation
sections themselves. For example, the 'delete' operation has:
Attempting to delete a container that does not exist MUST generate
an error. Attempting to delete a container whose process is still
running MUST generate an error.
I don't see the need to call generic attention to that idea, and
especially do not think that an entry in the lifecycle list is the
right place for such a generic call-out.
[1]: https://github.com/opencontainers/runtime-spec/pull/384#r60939710
[2]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-214418730
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-10-21.03.log.html#l-79
Signed-off-by: W. Trevor King <wking@tremily.us>
2017-03-15 23:03:32 -07:00
3. Runtime's [`start` ](runtime.md#start ) command is invoked with the unique identifier of the container.
4. The [prestart hooks ](config.md#prestart ) MUST be invoked by the runtime.
If any prestart hook fails, the runtime MUST [generate an error ](#errors ), stop the container, and continue the lifecycle at step 9.
5. The runtime MUST run the user-specified program, as specified by [`process` ](config.md#process ).
6. The [poststart hooks ](config.md#poststart ) MUST be invoked by the runtime.
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
If any poststart hook fails, the runtime MUST [log a warning ](#warnings ), but the remaining hooks and lifecycle continue as if the hook had succeeded.
runtime: Remove "features the runtime chooses to support"
Step 3 of the lifecycle from before this commit had two sentences
which both landed in be594153 (Split create and start, 2016-04-01,
#384). I pushed back a bit on the entry then [1,2], but we seem to be
pretty comfortable with the current "keep all lifecyle entries in a
one-layer enumerated list" approach, so I'm leaving that alone in this
commit. Step 3 isn't really a lifecycle step though, it's more about
clarifying that you can jump around in the lifecycle instead of
hitting all the steps in consecutive order. I'd floated a new
paragraph addressing that jumping, but was unable to form a consensus
around wording, and the jumping is already somewhat covered by the
current list entries (e.g. "The container process exits."). This
commit just drops the old step 3, and Michael will follow up with
wording about jumping [3].
The other sentence from the old step 3 doesn't need replacing, because
the limits are already covered in more detail in the operation
sections themselves. For example, the 'delete' operation has:
Attempting to delete a container that does not exist MUST generate
an error. Attempting to delete a container whose process is still
running MUST generate an error.
I don't see the need to call generic attention to that idea, and
especially do not think that an entry in the lifecycle list is the
right place for such a generic call-out.
[1]: https://github.com/opencontainers/runtime-spec/pull/384#r60939710
[2]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-214418730
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-10-21.03.log.html#l-79
Signed-off-by: W. Trevor King <wking@tremily.us>
2017-03-15 23:03:32 -07:00
7. The container process exits.
runtime: Replace "process is stopped" with "process exits"
proc(5) describes the following state entries in proc/[pid]/stat [1]
(for modern kernels):
* R Running
* S Sleeping in an interruptible wait
* D Waiting in uninterruptible disk sleep
* Z Zombie
* T Stopped (on a signal)
* t Tracing stop
* X Dead
and ps(1) has a bit more context [2] (for modern kernels):
* D uninterruptible sleep (usually IO)
* R running or runnable (on run queue)
* S interruptible sleep (waiting for an event to complete)
* T stopped by job control signal
* t stopped by debugger during the tracing
* X dead (should never be seen)
* Z defunct ("zombie") process, terminated but not reaped by its
parent
So I expect "stopped" to mean "process still exists but is paused,
e.g. by SIGSTOP". And I expect "exited" to mean "process has finished
and is either a zombie or dead".
After this commit, 'git grep -i stop' only turns up the "stopped"
state (which I've left alone for backwards compat), some poststop-hook
stuff, a reference in principles.md, a "stoppage" in LICENSE, and some
ChangeLog entries.
Also replace "container's process" with "container process" to match
usage in the rest of the repository. After this commit:
$ git grep -i "container process" | wc -l
20
$ git grep -i "container's process" | wc -l
1
Also reword status entries to avoid "running", which is less precise
in our spec (e.g. it also includes "sleeping", "waiting", ...).
Also removes a "them" leftover from a partial plural -> singular
reroll of be594153 (Split create and start, 2016-04-01, #384).
[1]: http://man7.org/linux/man-pages/man5/proc.5.html
[2]: http://man7.org/linux/man-pages/man1/ps.1.html
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-05-26 22:47:52 -07:00
This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill` ](runtime.md#kill ) operation being invoked.
runtime: Remove "features the runtime chooses to support"
Step 3 of the lifecycle from before this commit had two sentences
which both landed in be594153 (Split create and start, 2016-04-01,
#384). I pushed back a bit on the entry then [1,2], but we seem to be
pretty comfortable with the current "keep all lifecyle entries in a
one-layer enumerated list" approach, so I'm leaving that alone in this
commit. Step 3 isn't really a lifecycle step though, it's more about
clarifying that you can jump around in the lifecycle instead of
hitting all the steps in consecutive order. I'd floated a new
paragraph addressing that jumping, but was unable to form a consensus
around wording, and the jumping is already somewhat covered by the
current list entries (e.g. "The container process exits."). This
commit just drops the old step 3, and Michael will follow up with
wording about jumping [3].
The other sentence from the old step 3 doesn't need replacing, because
the limits are already covered in more detail in the operation
sections themselves. For example, the 'delete' operation has:
Attempting to delete a container that does not exist MUST generate
an error. Attempting to delete a container whose process is still
running MUST generate an error.
I don't see the need to call generic attention to that idea, and
especially do not think that an entry in the lifecycle list is the
right place for such a generic call-out.
[1]: https://github.com/opencontainers/runtime-spec/pull/384#r60939710
[2]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-214418730
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-10-21.03.log.html#l-79
Signed-off-by: W. Trevor King <wking@tremily.us>
2017-03-15 23:03:32 -07:00
8. Runtime's [`delete` ](runtime.md#delete ) command is invoked with the unique identifier of the container.
9. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
10. The [poststop hooks ](config.md#poststop ) MUST be invoked by the runtime.
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
If any poststop hook fails, the runtime MUST [log a warning ](#warnings ), but the remaining hooks and lifecycle continue as if the hook had succeeded.
2015-08-03 13:52:52 -04:00
2017-03-02 11:00:53 -08:00
## <a name="runtimeErrors" />Errors
2015-10-13 10:31:03 -07:00
In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation.
Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging.
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
## <a name="runtimeWarnings" />Warnings
In cases where the specified operation logs a warning, this specification does not mandate how, or even if, that warning is returned or exposed to the user of an implementation.
Unless otherwise stated, logging a warning does not change the flow of the operation; it MUST continue as if the warning had not been logged.
2017-03-02 11:00:53 -08:00
## <a name="runtimeOperations" />Operations
2016-05-23 15:48:20 +08:00
2017-03-15 23:24:33 -07:00
Unless otherwise stated, runtimes MUST support the following operations.
2016-05-23 15:48:20 +08:00
2016-10-25 16:59:26 +08:00
Note: these operations are not specifying any command-line APIs, and the parameters are inputs for general operations.
2016-05-24 15:12:36 +08:00
2017-03-02 11:00:53 -08:00
### <a name="runtimeQueryState" />Query State
2015-10-13 10:31:03 -07:00
`state <container-id>`
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
This operation MUST [generate an error ](#errors ) if it is not provided the ID of a container.
Attempting to query a container that does not exist MUST [generate an error ](#errors ).
2015-10-13 10:31:03 -07:00
This operation MUST return the state of a container as specified in the [State ](#state ) section.
2017-03-02 11:00:53 -08:00
### <a name="runtimeCreate" />Create
2015-10-13 10:31:03 -07:00
2016-04-01 08:42:13 -07:00
`create <container-id> <path-to-bundle>`
2015-10-13 10:31:03 -07:00
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
This operation MUST [generate an error ](#errors ) if it is not provided a path to the bundle and the container ID to associate with the container.
If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST [generate an error ](#errors ) and a new container MUST NOT be created.
2017-02-27 12:30:24 -08:00
This operation MUST create a new container.
All of the properties configured in [`config.json` ](config.md ) except for [`process` ](config.md#process ) MUST be applied.
[`process.args` ](config.md#process ) MUST NOT be applied until triggered by the [`start` ](#start ) operation.
The remaining `process` properties MAY be applied by this operation.
If the runtime cannot apply a property as specified in the [configuration ](config.md ), it MUST [generate an error ](#errors ) and a new container MUST NOT be created.
2016-05-26 14:20:00 -07:00
2016-05-02 11:33:13 -07:00
The runtime MAY validate `config.json` against this spec, either generically or with respect to the local system capabilities, before creating the container ([step 2 ](#lifecycle )).
2016-04-01 08:42:13 -07:00
Runtime callers who are interested in pre-create validation can run [bundle-validation tools ](implementations.md#testing--tools ) before invoking the create operation.
Any changes made to the [`config.json` ](config.md ) file after this operation will not have an effect on the container.
2017-03-02 11:00:53 -08:00
### <a name="runtimeStart" />Start
2016-04-01 08:42:13 -07:00
`start <container-id>`
2016-05-02 11:33:13 -07:00
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
This operation MUST [generate an error ](#errors ) if it is not provided the container ID.
Attempting to start a container that does not exist MUST [generate an error ](#errors ).
Attempting to start an already started container MUST have no effect on the container and MUST [generate an error ](#errors ).
*: Replace "user-specified code" with "user-specified program"
In [1], I'd proposed replacing our old "user-specified process" with
"user-specified code" to help distinguish between 'create' (cloning
the container process) and 'start' (signaling the container process to
execve or similar the user-specified $STUFF_FROM_THE_process_CONFIG).
That PR was rejected, although the renaming proposed there had already
landed via dd0cd210 (Add a 'status' field to our state struct,
2016-05-26, #462).
This PR attempts to find a common ground between "process" (preferred
by maintainers in #466 [2,3,4], but which I consider incorrect [5])
and "code" (which maintainers found confusing [3,4,6]). The Linux
execve(2) says "program" and unpacks that to "a binary executable, or
a script starting with a [shebang]" [7]. proc(5) documents
/proc/[pid]/exe by talking about "the executed command" [8]. The
POSIX exec docs call this the "process image" and talk about loading
it from the "new process image file" (although they also sprinkle in a
number of “program” references, apparently interchangeably with
“process image”) [9].
POSIX formally defines "command" [11], "executable file" [12], and
"program" [13]. The only reference to "process image" in the
definitions is in the "executable file" entry. The "command"
definition is focused on the shell, the "executable file" definition
is focused on files, and the "program" definition talks about a
"prepared sequence of instructions to the system", so "program" seems
like the best fit.
[1]: https://github.com/opencontainers/runtime-spec/pull/466
Subject: runtime: Replace "user-specified process" with "user-specified code" in 'create'
[2]: https://github.com/opencontainers/runtime-spec/pull/466#r64982402
[3]: https://github.com/opencontainers/runtime-spec/pull/466#issuecomment-223132793
[4]: https://github.com/opencontainers/runtime-spec/pull/466#issuecomment-258563220
[5]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_295
[6]: https://github.com/opencontainers/runtime-spec/pull/466#r64982165
[7]: http://man7.org/linux/man-pages/man2/execve.2.html
[8]: http://man7.org/linux/man-pages/man5/proc.5.html
[9]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html
[10]: https://git.kernel.org/cgit/docs/man-pages/man-pages.git/
[11]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_104
[12]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_154
[13]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_306
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-11-18 02:51:51 -08:00
This operation MUST run the user-specified program as specified by [`process` ](config.md#process ).
config: Make process optional
Since be59415 (Split create and start, 2016-04-01, #384), it's
possible for a container process to never execute user-specified code
(e.g. you can call 'create', 'kill', 'delete' without calling
'start'). For folks who expect to do that, there's no reason to
define process.args.
The only other process property required for all platforms is 'cwd',
but the runtime's idler code isn't specified in sufficient detail for
the configuration author to have an opinion about what its working
directory should be.
On Linux and Solaris, 'user' is also required for 'uid' and 'gid'. My
preferred approach here is to make those optional and define defaults
[1,2]:
If unset, the runtime will not attempt to manipulate the user ID
(e.g. not calling setuid(2) or similar).
But the maintainer consensus is that they want those to be explicitly
required properties [3,4,5]. With the current spec, one option could
be to make process optional (with the idler's working directory
unspecified) for OSes besides Linux and Solaris. On Windows, username
is optional, but that was likely accidental [6].
So an unspecified 'process' would leave process.cwd and process.user
unset. What that means for the implementation-defined container
process between 'create' and 'start' is unclear, but clarifying how
that is handled is a separate issue [7] independent of whether
'process' is optional or not.
[1]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216076069
[2]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/DWdystx5X3A
Subject: Exposing platform defaults
Date: Thu, 14 Jan 2016 15:36:26 -0800
Message-ID: <20160114233625.GN6362@odin.tremily.us>
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-04-17.00.log.html#l-44
[4]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216937010
[5]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216937090
[6]: https://github.com/opencontainers/runtime-spec/issues/618#issuecomment-277105273
[7]: https://github.com/opencontainers/runtime-spec/pull/700
Signed-off-by: W. Trevor King <wking@tremily.us>
2017-02-27 12:19:20 -08:00
This operation MUST generate an error if `process` was not set.
2016-04-01 08:42:13 -07:00
2017-03-02 11:00:53 -08:00
### <a name="runtimeKill" />Kill
2016-04-01 08:42:13 -07:00
`kill <container-id> <signal>`
2015-10-13 10:31:03 -07:00
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
This operation MUST [generate an error ](#errors ) if it is not provided the container ID.
Attempting to send a signal to a container that is not running MUST have no effect on the container and MUST [generate an error ](#errors ).
2016-04-01 08:42:13 -07:00
This operation MUST send the specified signal to the process in the container.
2015-10-13 10:31:03 -07:00
2017-03-02 11:00:53 -08:00
### <a name="runtimeDelete" />Delete
2016-04-01 08:42:13 -07:00
`delete <container-id>`
2015-10-13 10:31:03 -07:00
*: Restore hook lifecycle information removed by create/start split
I expect the lifecycle information was removed accidentally in
be594153 (Split create and start, 2016-04-01, #384), because for a
time it seemed like that PR would also be removing hooks. Putting the
lifecycle information back in, I made some tweaks to adjust to the new
environment, for example:
* Put the pre-start hooks after the 'start' call, but before the meat
of the start call (the container-process exec trigger). Folks who
want a post-create hook can add one with that name. I'd like to
have renamed poststop to post-delete to avoid confusion like [1].
But the motivation for keeping hooks was backwards compatibility [2]
so I've left the name alone.
* Put each "...command is invoked..." lifecycle entry in its own list
entry, to match the 'create' list entry.
* Move the rules about what happens on hook failure into the
lifecycle. This matches pre-split entries like:
If any prestart hook fails, then the container MUST be stopped and
the lifecycle continues at step 7.
and avoids respecifying that information in a second location
(config.md).
* I added the warning section to try and follow post-split's generic
"generates an error" approach while respecting the pre-split desire
to see what failed (we had "then an error including the exit code
and the stderr is returned to the caller" and "then an error is
logged").
* I left the state 'id' context out, since Michael didn't want it [3].
* Make runtime.md references to "generate an error" and "log a
warning" links, so readers have an easier time finding more detail
on that wording.
Where I reference a section, I'm still using the auto-generated anchor
for that header and not the anchors which were added in 41839d7 (Merge
pull request #707 from mrunalp/anchor_tags, 2017-03-03) and similar.
Mrunal suggested that the manually-added anchors were mainly intended
for the validation tooling [4].
[1]: https://github.com/opencontainers/runtime-spec/pull/395
Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422
Subject: *: Remove hooks
[3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480
Subject: Restore hook language removed by create/start split
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-03-03.log.html#t2017-03-03T18:02:12
Signed-off-by: W. Trevor King <wking@tremily.us>
2016-08-17 16:14:40 -07:00
This operation MUST [generate an error ](#errors ) if it is not provided the container ID.
Attempting to delete a container that does not exist MUST [generate an error ](#errors ).
Attempting to delete a container whose process is still running MUST [generate an error ](#errors ).
2016-04-01 08:42:13 -07:00
Deleting a container MUST delete the resources that were created during the `create` step.
Note that resources associated with the container, but not created by this container, MUST NOT be deleted.
Once a container is deleted its ID MAY be used by a subsequent container.
2015-10-13 10:31:03 -07:00
2015-09-09 10:17:06 -04:00
2017-03-02 11:00:53 -08:00
## <a name="runtimeHooks" />Hooks
2015-10-13 10:31:03 -07:00
Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
See [runtime configuration for hooks ](./config.md#hooks ) for more information.
