From 920757baa07518cb14a2add01ec2cc02654dd287 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Tue, 13 Oct 2015 10:31:03 -0700 Subject: [PATCH] Expand on the definition of our ops There are a few "OPEN" question in the doc that I'd like to brainstorm on. Signed-off-by: Doug Davis --- runtime.md | 94 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 78 insertions(+), 16 deletions(-) diff --git a/runtime.md b/runtime.md index 090f9ea1e..2d8ca8666 100644 --- a/runtime.md +++ b/runtime.md @@ -2,7 +2,7 @@ ## State -Runtime MUST store container metadata on disk so that external tools can consume and act on this information. +An OCI compliant runtime MUST store container metadata on disk so that external tools can consume and act on this information. It is recommended that this data be stored in a temporary filesystem so that it can be removed on a system reboot. On Linux/Unix based systems the metadata MUST be stored under `/run/opencontainer/containers`. For non-Linux/Unix based systems the location of the root metadata directory is currently undefined. @@ -37,23 +37,85 @@ This is provided so that consumers can find the container's configuration and ro ## 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 by passing the bundle path as argument. -2. The container's runtime environment is created according to the configuration in `config.json` and `runtime.json`. - Any updates to `config.json` or `runtime.json` after container is running do not affect the container. -3. The container's state.json file is written to the filesystem. -4. The prestart hooks are invoked by the runtime. - If any prestart hook fails, then the container is stopped and the lifecycle continues at step 8. -5. The user specified process is executed in the container. -6. The poststart hooks are invoked by the runtime. - If any poststart hook fails, then the container is stopped and the lifecycle continues at step 8. -7. Additional actions such as pausing the container, resuming the container or signaling the container may be performed using the runtime interface. - The container could also error out or crash. -8. The container is destroyed by undoing the steps performed during create phase (step 2). -9. The poststop hooks are invoked by the runtime and errors, if any, are logged. -10. The state.json file associated with the container is removed and the return code of the container's user specified process is returned or logged. +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` and `runtime.json`. + Any updates to `config.json` or `runtime.json` after container is running MUST not affect the container. +3. The container's `state.json` file MUST be written to the filesystem. +4. 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. +5. The user specified process MUST be executed in the container. +6. 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. +7. 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. +8. The container MUST be destroyed by undoing the steps performed during create phase (step 2). +9. The poststop hooks MUST be invoked by the runtime and errors, if any, MAY be logged. +10. The `state.json` file associated with the container MUST be removed and the return code of the container's user specified process MUST be returned or 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. +## Operations + +OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system. + +### 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. + +### Start + +Using the `config.json` and `runtime.json` files, along with the filesystem path referenced in the `config.json`, this operation MUST create a new container. +This includes creating the relevant namespaces, cgroups and configuring the appropriate capabilities for the container. +A new process in the container's PID namespace MUST be created as specified by the `config.json` file. +Attempting to start an already running container MUST have no effect on the container and MUST generate an error. + +### Stop + +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 cgroups for the container. +Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error. + +### Pause + +This operation MUST suspend all processes that are running within the container. +If the container is not running, either stopped or aleady paused, then this operation MUST have no effect on the container and MUST generate an error. + +### Unpause + +This operation MUST resume all processes that were previously paused via the `pause` operation. +If the container is not paused then this operation MUST have no effect on the container and MUST generate an error. + +### Exec + +This operation MUST create a new process within the scope of the container. +If the container is not running then this operation MUST have no effect on the container and MUST generate an error. +Executing this operation multiple times MUST result in a new process each time. +Unlike the container's main process which is specified in the `config.json` file, this specification does not define how the `exec` process is defined. +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. + +### Checkpoint + +This operation MUST create a checkpoint of a running container. +If the container is not running then this operation MUST have no effect on the container and MUST generate an error. +This specification does not specify how, or to where, the checkpoint data is persisted. + +OPEN: can we checkpoint a stopped container? + +OPEN: What's the state of the container afterwards? runc allows for the user to specify it. + +OPEN: we really should specify where to find the checkpoint info the same way we tell people where the state data is kept. + +### Restore + +This operation MUST restore a container to a previously created checkpoint state. +This specification does not specify how, or from where, the checkpoint data is provided to the runtime. + +OPEN: what state must the container be in before they can do this? + ## Hooks -See [runtime configuration for hooks](./runtime-config.md) +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](./runtime-config.md) for more information.