From 7a5b1f97d699f63bde8938b62662ad18b5793307 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 | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 72 insertions(+), 2 deletions(-) diff --git a/runtime.md b/runtime.md index 090f9ea1e..454a00e95 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. @@ -54,6 +54,76 @@ The lifecycle describes the timeline of events that happen from when a container 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 support for the operation can not be supported by the base operating system (kernel) itself. + +### 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. + +### Create + +Using the `config.json` and `runtime.json` files, along with the file system 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. + +### Start + +This operation MUST start a previously created container. +Starting a container MUST create a new process, as specified by the `config.json` file within the scope of the container. +Attempting to start an already running container MUST have no effect on the container and MUST generate an error. +Starting a stopped container, one that had been previously be running, MUST create a new process, as specified by the `config.json` file, within the scope of the container. + +### Stop + +This operation MUST stop a running container. +Stopping a container MUST stop all of the processes running within the scope of the container. +Stopping a container MUST NOT delete the associated namespaces or 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. + +### Delete + +This operation MUST delete a container. +Deleting a container MUST delete the associated namespaces and cgroups for the container. +Deleting a container that is not stopped 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. + +### 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.