Split create and start

Signed-off-by: Doug Davis <dug@us.ibm.com>

Author: Doug Davis

runtime.md

@@ -34,21 +34,19 @@ 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.
-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 8.
-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 8.
-6. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
+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 (namespaces, mounts, etc.) MUST be created according to the configuration in [`config.json`](config.md).
+   If a new PID namespace is requested in the [`config.json`](config.md), a PID namespace MUST created at this time.
+   However, the user-specified code (from ['process'](config.md#process-configuration) MUST NOT be executed at this time.
+   With the exception of the user-specified process, any updates to `config.json` after container is created MUST NOT affect the container.
+3. Runtime's `start` command is invoked with the unique identifier of the container.
+   The runtime MUST create and start the user-specified code, as specified by [`process`](config.md#process-configuration), in the container's PID namespace.
+   Any updates to the user-specified code in ['process'](config.md#process-configuration) after this point MUST NOT have any effect on the container.
+4. 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, MAY 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.
+5. Irrespective of how the user defined process stops (i.e. PID 1 exits), once the PID namespace is deleted the container MUST be destroyed by undoing the steps performed during create phase (step 2).
+   For clarity, all namespaces that were created in step 2 MUST be deleted.
 
 ## Operations
 
@@ -67,28 +65,43 @@ This operation MUST return the state of a container as specified in the [State](
 In particular, the state MUST be serialized as JSON.
 
 
-### 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), that is in the root of the bundle's directory, this operation MUST create a new container.
+This includes creating, or entering, the namespaces specified in the [`config.json`](config.md), resource limits, etc and configuring the appropriate capabilities for the container.
+If the `config.json` specifies that a PID namespace is to be created then one MUST be created, but the user-specified code within that namespace MUST NOT be created at this time.
+In some implementations this means that a temporary process is created in the PID namespace but it pauses until the `start` operation is invoked before replacing the process with the user-specified code.
+
+### Start
+`start <container-id>`
 
-Attempting to start an already running container MUST have no effect on the container and MUST generate an error.
+This operation MUST generate an error if it is not provided the container ID.
+This operation MUST create, and start, the user-specified code as specified by the [`process`](config.md#process-configuration) file otherwise an error MUST be generated and no process MUST be started.
+This process MUST be run in the PID namespace associated with the container.
 
-### Stop
+Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
 
-`stop <container-id>`
+### Run
+`run <container-id>`
 
 This operation MUST generate an error if it is not provided the container ID.
+This operation MUST invoke the `create` operation, and if there are no errors, followed by the `start` operation.
+
+### Delete
+
+`delete <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
+Attempting to delete a container that is not running, or that does not exist, MUST have no effect on the container and MUST generate an error.
 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.
+Deleting a container MUST delete the namespaces, and resources, that were created during the `create` step.
+Note that namespaces 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 subsequent containers.
-Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.
 
 ### Exec
 
@@ -118,12 +131,7 @@ Example:
     "cwd": "...",
 }
 ```
-This specification does not manadate the name of this JSON file.
+This specification does not mandate the name of this JSON file.
 See the specification of the `config.json` file for the definition of these fields.
 The stopping, or exiting, of these secondary process MUST have no effect on the state of the container.
 In other words, a container (and its PID 1 process) MUST NOT be stopped due to the exiting of a secondary process.
-
-## 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.