Skip to content

Commit 7117ede

Browse files
author
Doug Davis
committed
Expand on the definition of our ops
Signed-off-by: Doug Davis <dug@us.ibm.com>
1 parent 608cb7b commit 7117ede

File tree

1 file changed

+100
-30
lines changed

1 file changed

+100
-30
lines changed

‎runtime.md‎

Lines changed: 100 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,15 @@
11
# Runtime and Lifecycle
22

3-
## State
3+
## Scope of a Container
4+
5+
Barring access control concerns, the entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container.
6+
Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification.
47

5-
Runtime MUST store container metadata on disk so that external tools can consume and act on this information.
6-
It is recommended that this data be stored in a temporary filesystem so that it can be removed on a system reboot.
7-
On Linux/Unix based systems the metadata MUST be stored under `/run/opencontainer/containers`.
8-
For non-Linux/Unix based systems the location of the root metadata directory is currently undefined.
9-
Within that directory there MUST be one directory for each container created, where the name of the directory MUST be the ID of the container.
10-
For example: for a Linux container with an ID of `173975398351`, there will be a corresponding directory: `/run/opencontainer/containers/173975398351`.
11-
Within each container's directory, there MUST be a JSON encoded file called `state.json` that contains the runtime state of the container.
12-
For example: `/run/opencontainer/containers/173975398351/state.json`.
8+
## State
139

14-
The `state.json` file MUST contain all of the following properties:
10+
The state of a container MUST include, at least, the following propeties:
1511

16-
* **`version`**: (string) is the OCF specification version used when creating the container.
12+
* **`ociVersion`**: (string) is the OCI specification version used when creating the container.
1713
* **`id`**: (string) is the container's ID.
1814
This MUST be unique across all containers on this host.
1915
There is no requirement that it be unique across hosts.
@@ -23,37 +19,111 @@ This allows the hooks to perform cleanup and teardown logic after the runtime de
2319
* **`bundlePath`**: (string) is the absolute path to the container's bundle directory.
2420
This is provided so that consumers can find the container's configuration and root filesystem on the host.
2521

26-
*Example*
27-
22+
When serialized in JSON, the format MUST adhere to the following pattern:
2823
```json
2924
{
30-
"version": "0.2.0",
31-
"id": "oc-container",
25+
"ociVersion": "0.2.0",
26+
"id": "oci-container1",
3227
"pid": 4422,
3328
"bundlePath": "/containers/redis"
3429
}
3530
```
3631

32+
See [Query State](#query-state) for information on retrieving the state of a container.
33+
3734
## Lifecycle
3835
The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
3936

40-
1. OCI compliant runtime is invoked by passing the bundle path as argument.
41-
2. The container's runtime environment is created according to the configuration in [`config.json`](config.md).
42-
Any updates to `config.json` after container is running do not affect the container.
43-
3. The container's state.json file is written to the filesystem.
44-
4. The prestart hooks are invoked by the runtime.
45-
If any prestart hook fails, then the container is stopped and the lifecycle continues at step 8.
46-
5. The user specified process is executed in the container.
47-
6. The poststart hooks are invoked by the runtime.
48-
If any poststart hook fails, then the container is stopped and the lifecycle continues at step 8.
49-
7. Additional actions such as pausing the container, resuming the container or signaling the container may be performed using the runtime interface.
50-
The container could also error out or crash.
51-
8. The container is destroyed by undoing the steps performed during create phase (step 2).
52-
9. The poststop hooks are invoked by the runtime and errors, if any, are logged.
53-
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.
37+
1. OCI compliant runtime is invoked with a reference to the location of the bundle.
38+
How this reference is passed to the runtime is an implementation detail.
39+
2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
40+
Any updates to `config.json` after container is running MUST not affect the container.
41+
3. The prestart hooks MUST be invoked by the runtime.
42+
If any prestart hook fails, then the container MUST be stopped and the lifecycle continues at step 8.
43+
4. The user specified process MUST be executed in the container.
44+
5. The poststart hooks MUST be invoked by the runtime.
45+
If any poststart hook fails, then the container MUST be stopped and the lifecycle continues at step 8.
46+
6. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
47+
The container MAY also error out, exit or crash.
48+
7. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
49+
8. The poststop hooks MUST be invoked by the runtime and errors, if any, MAY be logged.
5450

5551
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.
5652

53+
## Operations
54+
55+
OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
56+
57+
### Errors
58+
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.
59+
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.
60+
61+
### Query State
62+
63+
`state <container-id>`
64+
65+
This operation MUST generate an error if it is not provided the ID of a container.
66+
This operation MUST return the state of a container as specified in the [State](#state) section.
67+
In particular, the state MUST be serialized as JSON.
68+
69+
70+
### Start
71+
72+
`start <container-id> <path-to-bundle>`
73+
74+
This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
75+
If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error.
76+
Using the data in `config.json`, that are in the bundle's directory, this operation MUST create a new container.
77+
This includes creating the relevant namespaces, resource limits, etc and configuring the appropriate capabilities for the container.
78+
A new process within the scope of the container MUST be created as specified by the `config.json` file otherwise an error MUST be generated.
79+
80+
Attempting to start an already running container MUST have no effect on the container and MUST generate an error.
81+
82+
### Stop
83+
84+
`stop <container-id>`
85+
86+
This operation MUST generate an error if it is not provided the container ID.
87+
This operation MUST stop and delete a running container.
88+
Stopping a container MUST stop all of the processes running within the scope of the container.
89+
Deleting a container MUST delete the associated namespaces and resources associated with the container.
90+
Once a container is deleted, its `id` MAY be used by subsequent containers.
91+
Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.
92+
93+
### Exec
94+
95+
`exec <container-id> <path-to-json>`
96+
97+
This operation MUST generate an error if it is not provided the container ID and a path to the JSON describing the process to start.
98+
The JSON describing the new process MUST adhere to the [Process configuration](config.md#process-configuration) definition.
99+
This operation MUST create a new process within the scope of the container.
100+
If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
101+
Executing this operation multiple times MUST result in a new process each time.
102+
Example:
103+
```
104+
{
105+
"terminal": true,
106+
"user": {
107+
"uid": 0,
108+
"gid": 0,
109+
"additionalGids": null
110+
},
111+
"args": [
112+
"/bin/sleep",
113+
"60"
114+
],
115+
"env": [
116+
"version=1.0"
117+
],
118+
"cwd": "...",
119+
}
120+
```
121+
This specification does not manadate the name of this JSON file.
122+
See the specification of the `config.json` file for the definition of these fields.
123+
The stopping, or exiting, of these secondary process MUST have no effect on the state of the container.
124+
In other words, a container (and its PID 1 process) MUST NOT be stopped due to the exiting of a secondary process.
125+
57126
## Hooks
58127

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

0 commit comments

Comments
 (0)