Skip to content

Commit b669866

Browse files
author
Doug Davis
committed
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]>
1 parent f81d025 commit b669866

1 file changed

Lines changed: 66 additions & 11 deletions

File tree

‎runtime.md‎

Lines changed: 66 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## State
44

5-
Runtime MUST store container metadata on disk so that external tools can consume and act on this information.
5+
An OCI compliant runtime MUST store container metadata on disk so that external tools can consume and act on this information.
66
It is recommended that this data be stored in a temporary filesystem so that it can be removed on a system reboot.
77
On Linux/Unix based systems the metadata MUST be stored under `/run/opencontainer/containers`.
88
For non-Linux/Unix based systems the location of the root metadata directory is currently undefined.
@@ -33,24 +33,79 @@ This is provided so that consumers can find the container's configuration and ro
3333
}
3434
```
3535

36-
## Lifecycle
36+
## Operations
37+
38+
OCI compliant runtimes MUST support the following operations, unless support for the operation can not be supported by the base operating system (kernel) itself.
39+
40+
OPEN: we should consider specifying the options/args for each operation.
41+
For example, checkpoint (for runc) seems to have a lot of params.
3742

3843
### Create
3944

40-
Creates the container: file system, namespaces, cgroups, capabilities.
45+
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.
46+
This includes creating the relevant namespaces, cgroups and configuring the appropriate capabilities for the container.
47+
48+
### Start
49+
50+
This operation MUST start a previously created container.
51+
Starting a container MUST create a new process, as specified by the `config.json` file within the scope of the container.
52+
Attempting to start an already running container MUST have no effect on the container and MUST generate an error.
53+
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.
54+
55+
OPEN: the entire "generate an error" stuff in here is something we should discuss.
56+
My initial thought was that it would be better to generate an error so that the call would know exactly what happened - meaning, did something new take place or was the container already running. If we didn't return an error (or something) then the caller wouldn't know. And they can always ignore errors if they want/need to.
57+
58+
### Stop
59+
60+
This operation MUST stop a running container.
61+
Stopping a container MUST stop all of the processes running within the scope of the container.
62+
Stopping a container MUST NOT delete the associated namespaces or cgroups for the container.
63+
Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.
64+
65+
### Delete
66+
67+
This operation MUST delete a container.
68+
Deleting a container MUST delete the associated namespaces and cgroups for the container.
69+
Deleting a container that is not stopped MUST first stop the container as specified by the `stop` operation.
70+
If the implied `stop` operations fails then the `delete` operation MUST fail.
71+
72+
### Pause
73+
74+
This operation MUST suspend all processes that are running within the container.
75+
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.
76+
77+
### Unpause
78+
79+
This operation MUST resume all processes that were previously paused via the `pause` operation.
80+
If the container is not paused then this operation MUST have no effect on the container and MUST generate an error.
81+
82+
### Exec
83+
84+
This operation MUST create a new process within the scope of the container.
85+
If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
86+
Executing this operation multiple times MUST result in a new process each time.
87+
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.
88+
89+
### Checkpoint
90+
91+
This operation MUST create a checkpoint of a running container.
92+
If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
93+
This specification does not specify how, or to where, the checkpoint data is persisted.
94+
95+
OPEN: can we checkpoint a stopped container?
4196

42-
### Start (process)
97+
OPEN: What's the state of the container afterwards? runc allows for the user to specify it.
4398

44-
Runs a process in a container.
45-
Can be invoked several times.
99+
OPEN: we really should specify where to find the checkpoint info the same way we tell people where the state data is kept.
46100

47-
### Stop (process)
101+
### Restore
48102

49-
Not sure we need that from runc cli.
50-
Process is killed from the outside.
103+
This operation MUST restore a container to a previously created checkpoint state.
104+
This specification does not specify how, or from where, the checkpoint data is provided to the runtime.
51105

52-
This event needs to be captured by runc to run onstop event handlers.
106+
OPEN: what state must the container be in before they can do this?
53107

54108
## Hooks
55109

56-
See [runtime configuration for hooks](./runtime-config.md)
110+
Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
111+
See [runtime configuration for hooks](./runtime-config.md) for more information.

0 commit comments

Comments
 (0)