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 <[email protected]>

Author: Doug Davis

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.