Merge remote-tracking branch 'duglin/SplitCreate' into tk/restore-hoo…

…k-lifecycle

Restore hook language removed by create/start split with 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").

[1]: opencontainers#395
     Subject: Run post-stop hooks before the container sandbox is deleted.
[2]: opencontainers#483 (comment)
     Subject: *: Remove hooks

* duglin/SplitCreate:
  Split create and start

Signed-off-by: W. Trevor King <[email protected]>

config.md

@@ -252,24 +252,19 @@ Hook paths are absolute and are executed from the host's filesystem in the [runt
 
 ### Prestart
 
-The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
-They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
+The pre-start hooks MUST be called [after the container has been created but before the user supplied command is executed](runtime.md#lifecycle).
+They provide an opportunity to customize the container.
 In Linux, for e.g., the network namespace could be configured in this hook.
 
-If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
-
 ### Poststart
 
-The post-start hooks are called after the user process is started.
+The post-start hooks are called [after the user process is started](runtime#lifecycle).
 For example this hook can notify user that real process is spawned.
 
-If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
-
 ### Poststop
 
-The post-stop hooks are called after the container process is stopped.
+The post-stop hooks are called [after the container is deleted](runtime#lifecycle).
 Cleanup or debugging could be performed in such a hook.
-If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
 
 ### Example
 

runtime.md

@@ -34,28 +34,36 @@ See [Query State](#query-state) for information on retrieving the state of a con
 
 ## Lifecycle
 The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
-
-1. OCI compliant runtime is invoked with a reference to the location of the bundle.
-   How this reference is passed to the runtime is an implementation detail.
+1. OCI compliant runtime's `create` command is invoked with a reference to the location of the bundle and a unique identifier.
+   How these references are passed to the runtime is an implementation detail.
 2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
-   Any updates to `config.json` after container is running MUST not affect the container.
-3. The prestart hooks MUST be invoked by the runtime.
-   If any prestart hook fails, then the container MUST be stopped and the lifecycle continues at step 7.
-4. The user specified process MUST be executed in the container.
-5. The poststart hooks MUST be invoked by the runtime.
-   If any poststart hook fails, then the container MUST be stopped and the lifecycle continues at step 7.
-6. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
-   The container MAY also error out, exit or crash.
-7. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
-8. The poststop hooks MUST be invoked by the runtime and errors, if any, SHOULD be logged.
-
-Note: The lifecycle is a WIP and it will evolve as we have more use cases and more information on the viability of a separate create phase.
+   While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified code (from [`process`](config.md#process-configuration) MUST NOT be run at this time.
+   Any updates to `config.json` after this step MUST NOT affect the container.
+3. Once the container is created additional actions MAY be performed based on the features the runtime chooses to support.
+  However, some actions might only be available based on the current state of the container (e.g. only available while it is started).
+4. Runtime's `start` command is invoked with the unique identifier of the container.
+5. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime.
+   If any prestart hook fails, the runtime MUST generate an error, stop the container, and continue the lifecycle at step 10.
+6. The runtime MUST run the user-specified code, as specified by [`process`](config.md#process-configuration).
+7. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime.
+   If any poststart hook fails, the runtime MUST log a warning, but the remaining hooks and lifecycle continue as if the hook had succeeded.
+8. The container's process is stopped.
+   This MAY happen due to them erroring out, exiting, crashing or the runtime's `kill` operation being invoked.
+9. Runtime's `delete` command is invoked with the unique identifier of the container.
+10. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
+11. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime.
+    If any poststop hook fails, the runtime MUST log a warning, but the remaining hooks and lifecycle continue as if the hook had succeeded.
 
 ## Errors
 
 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.
 
+## 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.
+
 ## Operations
 
 OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
@@ -67,36 +75,50 @@ Note: these operations are not specifying any command-line APIs, and the paramen
 `state <container-id>`
 
 This operation MUST generate an error if it is not provided the ID of a container.
+Attempting to query a container that does not exist MUST generate an error.
 This operation MUST return the state of a container as specified in the [State](#state) section.
 
-### Start
+### Create
 
-`start <container-id> <path-to-bundle>`
+`create <container-id> <path-to-bundle>`
 
 This operation MUST generate an error 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.
-Using the data in `config.json`, that are in the bundle's directory, this operation MUST create a new container.
-This includes creating the relevant namespaces, resource limits, etc and configuring the appropriate capabilities for the container.
-A new process within the scope of the container MUST be created as specified by the `config.json` file otherwise an error MUST be generated.
+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 and a new container MUST not be created.
+Using the data in [`config.json`](config.md), this operation MUST create a new container.
+This means that all of the resources associated with the container MUST be created, however, the user-specified process MUST NOT be run at this time.
 
 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)).
-If the runtime does not perform initial validation and triggers an error due to an invalid or incompatible configuration, it MUST generate an error and jump to cleanup ([step 7](#lifecycle)).
-Runtime callers who are interested in pre-start validation can run [bundle-validation tools](implementations.md#testing--tools) before invoking the start operation.
+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.
+
+### Start
+`start <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
+Attempting to start a container that does not exist MUST generate an error.
+Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
+This operation MUST run the user-specified code as specified by [`process`](config.md#process-configuration).
+If the runtime fails to run the code as specified, an error MUST be generated.
 
-Attempting to start an already running container MUST have no effect on the container and MUST generate an error.
+### Kill
+`kill <container-id> <signal>`
 
-### Stop
+This operation MUST generate an error 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.
+This operation MUST send the specified signal to the process in the container.
 
-`stop <container-id>`
+### Delete
+`delete <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.
+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.
+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.
 
-## Hooks
 
+## Hooks
 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.