You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: runtime.md
+31-18Lines changed: 31 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,8 +13,6 @@ The state of a container MUST include, at least, the following propeties:
13
13
***`id`**: (string) is the container's ID.
14
14
This MUST be unique across all containers on this host.
15
15
There is no requirement that it be unique across hosts.
16
-
The ID is provided in the state because hooks will be executed with the state as the payload.
17
-
This allows the hooks to perform cleanup and teardown logic after the runtime destroys its own state.
18
16
***`pid`**: (int) is the ID of the main process within the container, as seen by the host.
19
17
***`bundlePath`**: (string) is the absolute path to the container's bundle directory.
20
18
This is provided so that consumers can find the container's configuration and root filesystem on the host.
@@ -37,17 +35,22 @@ The lifecycle describes the timeline of events that happen from when a container
37
35
38
36
1. OCI compliant runtime's `create` command is invoked with a reference to the location of the bundle and a unique identifier.
39
37
How these references are passed to the runtime is an implementation detail.
40
-
2. The container's runtime environment (namespaces, mounts, etc.) MUST be created according to the configuration in [`config.json`](config.md).
38
+
1. The container's runtime environment (namespaces, mounts, etc.) MUST be created according to the configuration in [`config.json`](config.md).
41
39
If a new PID namespace is requested in the [`config.json`](config.md), a PID namespace MUST created at this time.
42
-
However, the user-specified code (from ['process'](config.md#process-configuration) MUST NOT be executed at this time.
40
+
However, the user-specified code (from [`process`](config.md#process-configuration) MUST NOT be run at this time.
43
41
With the exception of the user-specified process, any updates to `config.json` after container is created MUST NOT affect the container.
44
-
3. Runtime's `start` command is invoked with the unique identifier of the container.
45
-
The runtime MUST create and start the user-specified code, as specified by [`process`](config.md#process-configuration), in the container's PID namespace.
46
-
Any updates to the user-specified code in ['process'](config.md#process-configuration) after this point MUST NOT have any effect on the container.
47
-
4. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
48
-
The container MAY also error out, exit or crash.
49
-
5. Irrespective of how the user defined process stops (i.e. PID 1 exits), once the PID namespace is deleted the container MUST be destroyed by undoing the steps performed during create phase (step 2).
50
-
For clarity, all namespaces that were created in step 2 MUST be deleted.
42
+
1. Once the container is created additional actions MAY be performed based on the features the runtiem chooses to support.
43
+
However, some actions might only be available based on the current state of the container (e.g. only available while it is started).
44
+
1. Runtime's `start` command is invoked with the unique identifier of the container.
45
+
The runtime MUST run the user-specified code, as specified by [`process`](config.md#process-configuration), in the container's PID namespace.
46
+
Any updates to the user-specified code in [`process`](config.md#process-configuration) after this point MUST NOT have any effect on the container.
47
+
1. The container's processes are stopped.
48
+
This MAY happen due to them erroring out, exiting or crashing.
49
+
The runtime's `stop` operation MAY also be used to stop the processes running within the container.
50
+
1. Runtime's `delete` command is invoked with the identifier of the container.
51
+
The container MUST be destroyed by undoing the steps performed during create phase (step 2).
52
+
For clarity, the runtime MUST make a best-effort attempt to delete all resources that were create in step 2.
53
+
The phrase "best-effort" is to allow for situations where some other processes, or container, is "holding on" to a resource and the runtime is therefore unable to delete it.
51
54
52
55
## Operations
53
56
@@ -72,16 +75,17 @@ In particular, the state MUST be serialized as JSON.
72
75
73
76
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.
74
77
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 and a new container MUST not be created.
75
-
Using the data in [`config.json`](config.md), that is in the root of the bundle's directory, this operation MUST create a new container.
76
-
This includes creating, or entering, the namespaces specified in the [`config.json`](config.md), resource limits, etc and configuring the appropriate capabilities for the container.
77
-
If the `config.json` specifies that a PID namespace is to be created then one MUST be created, but the user-specified code within that namespace MUST NOT be created at this time.
78
+
Using the data in [`config.json`](config.md), this operation MUST create a new container.
79
+
This includes creating, or entering, the namespaces specified in the [`config.json`](config.md), resource limits, etc. and configuring the appropriate capabilities for the container.
80
+
If the `config.json` specifies that a PID namespace is to be created then one MUST be created, but the user-specified code within that namespace MUST NOT be run at this time.
78
81
In some implementations this means that a temporary process is created in the PID namespace but it pauses until the `start` operation is invoked before replacing the process with the user-specified code.
79
82
80
83
### Start
81
84
`start <container-id>`
82
85
83
86
This operation MUST generate an error if it is not provided the container ID.
84
-
This operation MUST create, and start, the user-specified code as specified by the [`process`](config.md#process-configuration) file otherwise an error MUST be generated and no process MUST be started.
87
+
Attempting to start a container that does not exist MUST generate an error.
88
+
This operation MUST run the user-specified code as specified by the [`process`](config.md#process-configuration) otherwise an error MUST be generated and no process MUST be started.
85
89
This process MUST be run in the PID namespace associated with the container.
86
90
87
91
Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
@@ -90,18 +94,27 @@ Attempting to start an already started container MUST have no effect on the cont
90
94
`run <container-id>`
91
95
92
96
This operation MUST generate an error if it is not provided the container ID.
97
+
Attempting to run a container that does not exist MUST generate an error.
93
98
This operation MUST invoke the `create` operation, and if there are no errors, then invoke the `start` operation.
94
99
The implementation MAY immediately execute `start` without any pause after `create` completes.
95
100
For example if the implementation used a temporary process to implement `create`, it need not do this in the implementation of `run`.
96
101
102
+
### Stop
103
+
`stop <container-id>`
104
+
105
+
This operation MUST generate an error if it is not provided the container ID.
106
+
Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.
107
+
This operation MUST stop all of the processes running within the scope of the container.
108
+
This operation MUST NOT delete any resources associated with the container, except for the PID namespace.
109
+
97
110
### Delete
98
111
99
112
`delete <container-id>`
100
113
101
114
This operation MUST generate an error if it is not provided the container ID.
102
-
Attempting to delete a container that is not running, or that does not exist, MUST have no effect on the container and MUST generate an error.
103
-
This operation MUST stop and delete a running container.
104
-
Stopping a container MUST stop all of the processes running within the scope of the container.
115
+
Attempting to delete a container that does not exist MUST generate an error.
116
+
If the container is running then this operation MUST first stop it, per the `stop` operation defined above.
117
+
If the stopping of the container fails then the container MUST NOT be deleted and an error MUST be generated.
105
118
Deleting a container MUST delete the namespaces, and resources, that were created during the `create` step.
106
119
Note that namespaces associated with the container but not created by this container MUST NOT be deleted.
107
120
Once a container is deleted, its `id` MAY be used by subsequent containers.
0 commit comments