Replace stop with signal/kill and delete

[mikebrow]

The spec currently states in runtime.md:

stop <container-id>

This operation MUST generate an error if it is not provided the container ID. This operation MUST stop
and delete a running container. 

Stopping a container MUST stop all of the processes running within the scope of the container. 

Deleting a container MUST delete the associated namespaces and resources associated with the container. 

Once a container is deleted, its id MAY be used by subsequent containers. 

Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.

In a discussion with @crosbymichael opencontainers/runc#681 it was pointed out that the spec does not explain "how" or what it means to "stop." Suggest changing the spec to remove stop and replace it with the requirement for a signal or kill command, and a delete command.
Thoughts?

[wking]

On Wed, Mar 23, 2016 at 11:44:38AM -0700, Mike Brown wrote:

In a discussion with @crosbymichael it was pointed out that the spec
does not explain "how" or what it means to "stop." Suggest changing
the spec to remove stop and replace it with the requirement for a
signal or kill command, and a delete command.

Previous discussion on what stop would mean in [1,2]. Should we move
this to the list (see also 3)?

 Subject: Definining "container" and "container processes" on Linux
 Date: Thu, 8 Oct 2015 09:47:08 -0700
 Message-ID: <20151008164708.GM28418@odin.tremily.us> 

 Subject: Clarify distinction between ‘stop’ and ‘delete’
 Date: Wed, 23 Mar 2016 11:49:35 -0700
 Message-ID: <20160323184935.GB23066@odin.tremily.us>

[wking]

There was some discussion in today's meeting 1, with the main
concern being “is a signal-based approach portable?”. It looks like
basic signal handling is part of ISO C 2:

The ISO C standard only requires the signal names SIGABRT, SIGFPE,
SIGILL, SIGINT, SIGSEGV, and SIGTERM to be defined.

so an OCI signal command that sends those should be portable to other
systems. However, signal(2) has 3:

The signals SIGKILL and SIGSTOP cannot be caught or ignored.

so I think we want the spec to have a ‘signal’ command (possibly
called ‘kill’ to match POSIX 4) which also supports a an uncatchable
kill (which may be SIGKILL on Linux, but another action for VM-based
containers or other platforms that don't support an uncatchable
SIGKILL). The uncatchable kill is @julz' “forceful stop” 5, which
seems like a cross-platform idea.

I'm not sure how VM-based platforms would handle requests for SIGTERM,
but I'm ok with spec wording that requires the requested ISO C signal
be sent if possible, or an unsupported error be raised if impossible.

I'm not clear enough on Window's containers to know if they also
support sending SIGTERM, etc. into the main container process. But
the worst-case scenario (VM-level support, erroring on anything except
SIGKILL requests) seems like an acceptable lower bar. @RobDolinMS may
be able to add more clarity there.

I think we need to explicitly say which runtime calls trigger which
signals because the non-KILL signals are a mechanism for runtime
callers to communicate with their container process (e.g. SIGTERM says
“please stop gracefully”). If we don't specify which signals a
runtime call sends, it's hard to write portable container images (What
do you listen for to trigger a graceful shutdown? Which container
processes might receive that signal from the runtime?).

[wking]

Done in #384. I think we can close this.

[mikebrow]

Issue has been satisfactorily resolved by removing the stop operation and adding kill (with optional signal values for platforms that have signal support) and delete.

[NetEase-FuXi]

below instructions maybe valid:

runc pause <containerId>
kill <runc container PID>  // PID field from runc list
runc resume <containerId>
#at this time, runc list shows container in stopped
runc delete <containerId>