Skip to content

Commit

Permalink
Expand on the definition of our ops
Browse files Browse the repository at this point in the history
There are a few "OPEN" question in the doc that I'd like to brainstorm on.

Signed-off-by: Doug Davis <dug@us.ibm.com>
  • Loading branch information
Doug Davis committed Jan 4, 2016
1 parent 4060e6c commit 7a5b1f9
Showing 1 changed file with 72 additions and 2 deletions.
74 changes: 72 additions & 2 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

0 comments on commit 7a5b1f9

Please sign in to comment.