From 5b36f2c18489bda16af4d95e2f67f8d5405e3177 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Fri, 1 Apr 2016 08:42:13 -0700 Subject: [PATCH] Split create and start Signed-off-by: Doug Davis --- runtime.md | 70 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 31 deletions(-) diff --git a/runtime.md b/runtime.md index 47d4adda3..3790b963c 100644 --- a/runtime.md +++ b/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 ` +`create ` 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 ` -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 ` +### Run +`run ` 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 ` + +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.