Skip to content

Commit c166268

Browse files
author
Renaud Gaubert
committed
Add create-container, create-runtime and start-container hooks
Signed-off-by: Renaud Gaubert <[email protected]>
1 parent 020fda7 commit c166268

File tree

5 files changed

+180
-29
lines changed

5 files changed

+180
-29
lines changed

‎config.md

Lines changed: 118 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -378,40 +378,119 @@ For Windows based systems the user structure has the following fields:
378378
For POSIX platforms, the configuration structure supports `hooks` for configuring custom actions related to the [lifecycle](runtime.md#lifecycle) of the container.
379379

380380
* **`hooks`** (object, OPTIONAL) MAY contain any of the following properties:
381-
* **`prestart`** (array of objects, OPTIONAL) is an array of [pre-start hooks](#prestart).
382-
Entries in the array contain the following properties:
383-
* **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s *path*][ieee-1003.1-2008-functions-exec].
384-
This specification extends the IEEE standard in that **`path`** MUST be absolute.
385-
Runtimes MUST resolve this value in the [runtime namespace](glossary.md#runtime-namespace).
386-
* **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s *argv*][ieee-1003.1-2008-functions-exec].
387-
* **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
388-
* **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook.
389-
If set, `timeout` MUST be greater than zero.
390-
* **`poststart`** (array of objects, OPTIONAL) is an array of [post-start hooks](#poststart).
391-
Entries in the array have the same schema as pre-start entries.
392-
* **`poststop`** (array of objects, OPTIONAL) is an array of [post-stop hooks](#poststop).
393-
Entries in the array have the same schema as pre-start entries.
381+
* **`prestart`** (array of objects, OPTIONAL, **DEPRECATED**) is an array of [`prestart` hooks](#prestart).
382+
* Entries in the array contain the following properties:
383+
* **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s *path*][ieee-1003.1-2008-functions-exec].
384+
This specification extends the IEEE standard in that **`path`** MUST be absolute.
385+
* **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s *argv*][ieee-1003.1-2008-functions-exec].
386+
* **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
387+
* **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook.
388+
If set, `timeout` MUST be greater than zero.
389+
* The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
390+
* The `prestart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
391+
* **`createRuntime`** (array of objects, OPTIONAL) is an array of [`createRuntime` hooks](#createRuntime-hooks).
392+
* Entries in the array contain the following properties (the entries are identical to the entries in the deprecated `prestart` hooks):
393+
* **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s *path*][ieee-1003.1-2008-functions-exec].
394+
This specification extends the IEEE standard in that **`path`** MUST be absolute.
395+
* **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s *argv*][ieee-1003.1-2008-functions-exec].
396+
* **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
397+
* **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook.
398+
If set, `timeout` MUST be greater than zero.
399+
* The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
400+
* The `createRuntime` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
401+
* **`createContainer`** (array of objects, OPTIONAL) is an array of [`createContainer` hooks](#createContainer-hooks).
402+
* Entries in the array have the same schema as `createRuntime` entries.
403+
* The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
404+
* The `createContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
405+
* **`startContainer`** (array of objects, OPTIONAL) is an array of [`startContainer` hooks](#startContainer-hooks).
406+
* Entries in the array have the same schema as `createRuntime` entries.
407+
* The value of `path` MUST resolve in the [container namespace](glossary.md#container-namespace).
408+
* The `startContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
409+
* **`poststart`** (array of objects, OPTIONAL) is an array of [`poststart` hooks](#poststart).
410+
* Entries in the array have the same schema as `createRuntime` entries.
411+
* The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
412+
* The `poststart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
413+
* **`poststop`** (array of objects, OPTIONAL) is an array of [`poststop` hooks](#poststop).
414+
* Entries in the array have the same schema as `createRuntime` entries.
415+
* The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
416+
* The `poststop` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
394417

395418
Hooks allow users to specify programs to run before or after various lifecycle events.
396419
Hooks MUST be called in the listed order.
397-
Hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
398420
The [state](runtime.md#state) of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container.
399421

400422
### <a name="configHooksPrestart" />Prestart
401423

402-
The pre-start hooks MUST be called after the [`start`](runtime.md#start) operation is called but [before the user-specified program command is executed](runtime.md#lifecycle).
424+
The `prestart` hooks MUST be called after the [`start`](runtime.md#start) operation is called but [before the user-specified program command is executed](runtime.md#lifecycle).
403425
On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
404426

427+
Note: `prestart` hooks were deprecated in favor of `createRuntime`, `createContainer` and `startContainer` hooks, which allow more granular hook control during the create and start phase.
428+
429+
The `prestart` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
430+
The `prestart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
431+
432+
### <a name="configHooksCreateRuntime" />CreateRuntime Hooks
433+
434+
The `createRuntime` hooks MUST be called as part of the [`create`](runtime.md#create) operation after the runtime environment has been created (according to the configuration in config.json) but before the `pivot_root` or any equivalent operation has been executed.
435+
436+
The `createRuntime` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
437+
The `createRuntime` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
438+
439+
On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
440+
441+
The definition of `createRuntime` hooks is currently underspecified and hooks authors, should only expect from the runtime that the mount namespace have been created and the mount operations performed. Other operations such as cgroups and SELinux/AppArmor labels might not have been performed by the runtime.
442+
443+
Note: `runc` originally implemented `prestart` hooks contrary to the spec, namely as part of the `create` operation (instead of during the `start` operation). This incorrect implementation actually corresponds to `createRuntime` hooks. For runtimes that implement the deprecated `prestart` hooks as `createRuntime` hooks, `createRuntime` hooks MUST be called after the `prestart` hooks.
444+
445+
### <a name="configHooksCreateContainer" />CreateContainer Hooks
446+
447+
The `createContainer` hooks MUST be called as part of the [`create`](runtime.md#create) operation after the runtime environment has been created (according to the configuration in config.json) but before the `pivot_root` or any equivalent operation has been executed.
448+
The `createContainer` hooks MUST be called after the `createRuntime` hooks.
449+
450+
The `createContainer` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
451+
The `createContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
452+
453+
For example, on Linux this would happen before the `pivot_root` operation is executed but after the mount namespace was created and setup.
454+
455+
The definition of `createContainer` hooks is currently underspecified and hooks authors, should only expect from the runtime that the mount namespace and different mounts will be setup. Other operations such as cgroups and SELinux/AppArmor labels might not have been performed by the runtime.
456+
457+
### <a name="configHooksStartContainer" />StartContainer Hooks
458+
459+
The `startContainer` hooks MUST be called [before the user-specified process is executed](runtime.md#lifecycle) as part of the [`start`](runtime.md#start) operation.
460+
This hook can be used to execute some operations in the container, for example running the `ldconfig` binary on linux before the container process is spawned.
461+
462+
The `startContainer` hooks' path MUST resolve in the [container namespace](glossary.md#container-namespace).
463+
The `startContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
464+
405465
### <a name="configHooksPoststart" />Poststart
406466

407-
The post-start hooks MUST be called [after the user-specified process is executed](runtime.md#lifecycle) but before the [`start`](runtime.md#start) operation returns.
467+
The `poststart` hooks MUST be called [after the user-specified process is executed](runtime.md#lifecycle) but before the [`start`](runtime.md#start) operation returns.
408468
For example, this hook can notify the user that the container process is spawned.
409469

470+
The `poststart` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
471+
The `poststart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
472+
410473
### <a name="configHooksPoststop" />Poststop
411474

412-
The post-stop hooks MUST be called [after the container is deleted](runtime.md#lifecycle) but before the [`delete`](runtime.md#delete) operation returns.
475+
The `poststop` hooks MUST be called [after the container is deleted](runtime.md#lifecycle) but before the [`delete`](runtime.md#delete) operation returns.
413476
Cleanup or debugging functions are examples of such a hook.
414477

478+
The `poststop` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
479+
The `poststop` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
480+
481+
### Summary
482+
483+
See the below table for a summary of hooks and when they are called:
484+
485+
| Name | Namespace | When |
486+
| ----------------------- | --------- | -----------------------------------------------------------------------------------------------------------------------------------|
487+
| `prestart` (Deprecated) | runtime | After the start operation is called but before the user-specified program command is executed. |
488+
| `createRuntime` | runtime | During the create operation, after the runtime environment has been created and before the pivot root or any equivalent operation. |
489+
| `createContainer` | container | During the create operation, after the runtime environment has been created and before the pivot root or any equivalent operation. |
490+
| `startContainer` | container | After the start operation is called but before the user-specified program command is executed. |
491+
| `poststart` | runtime | After the user-specified process is executed but before the start operation returns. |
492+
| `poststop` | runtime | After the container is deleted but before the delete operation returns. |
493+
415494
### Example
416495

417496
```json
@@ -426,6 +505,28 @@ Cleanup or debugging functions are examples of such a hook.
426505
"path": "/usr/bin/setup-network"
427506
}
428507
],
508+
"createRuntime": [
509+
{
510+
"path": "/usr/bin/fix-mounts",
511+
"args": ["fix-mounts", "arg1", "arg2"],
512+
"env": [ "key1=value1"]
513+
},
514+
{
515+
"path": "/usr/bin/setup-network"
516+
}
517+
],
518+
"createContainer": [
519+
{
520+
"path": "/usr/bin/mount-hook",
521+
"args": ["-mount", "arg1", "arg2"],
522+
"env": [ "key1=value1"]
523+
}
524+
],
525+
"startContainer": [
526+
{
527+
"path": "/usr/bin/refresh-ldcache"
528+
}
529+
],
429530
"poststart": [
430531
{
431532
"path": "/usr/bin/notify-start",

‎runtime.md

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -55,18 +55,24 @@ The lifecycle describes the timeline of events that happen from when a container
5555
If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST [generate an error](#errors).
5656
While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified program (from [`process`](config.md#process)) MUST NOT be run at this time.
5757
Any updates to [`config.json`](config.md) after this step MUST NOT affect the container.
58-
3. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container.
59-
4. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime.
60-
If any prestart hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 9.
61-
5. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process).
62-
6. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime.
63-
If any poststart hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded.
64-
7. The container process exits.
58+
3. The [`prestart` hooks](config.md#prestart) MUST be invoked by the runtime.
59+
If any `prestart` hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 12.
60+
4. The [`createRuntime` hooks](config.md#createRuntime-hooks) MUST be invoked by the runtime.
61+
If any `createRuntime` hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 12.
62+
5. The [`createContainer` hooks](config.md#createContainer-hooks) MUST be invoked by the runtime.
63+
If any `createContainer` hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 12.
64+
6. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container.
65+
7. The [`startContainer` hooks](config.md#startContainer-hooks) MUST be invoked by the runtime.
66+
If any `startContainer` hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 12.
67+
8. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process).
68+
9. The [`poststart` hooks](config.md#poststart) MUST be invoked by the runtime.
69+
If any `poststart` hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded.
70+
10. The container process exits.
6571
This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked.
66-
8. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container.
67-
9. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
68-
10. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime.
69-
If any poststop hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded.
72+
11. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container.
73+
12. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
74+
13. The [`poststop` hooks](config.md#poststop) MUST be invoked by the runtime.
75+
If any `poststop` hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded.
7076

7177
## <a name="runtimeErrors" />Errors
7278

‎schema/config-schema.json

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,15 @@
1212
"prestart": {
1313
"$ref": "defs.json#/definitions/ArrayOfHooks"
1414
},
15+
"createRuntime": {
16+
"$ref": "defs.json#/definitions/ArrayOfHooks"
17+
},
18+
"createContainer": {
19+
"$ref": "defs.json#/definitions/ArrayOfHooks"
20+
},
21+
"startContainer": {
22+
"$ref": "defs.json#/definitions/ArrayOfHooks"
23+
},
1524
"poststart": {
1625
"$ref": "defs.json#/definitions/ArrayOfHooks"
1726
},

‎schema/test/config/good/spec-example.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,28 @@
155155
"path": "/usr/bin/setup-network"
156156
}
157157
],
158+
"createRuntime": [
159+
{
160+
"path": "/usr/bin/fix-mounts",
161+
"args": ["fix-mounts", "arg1", "arg2"],
162+
"env": [ "key1=value1"]
163+
},
164+
{
165+
"path": "/usr/bin/setup-network"
166+
}
167+
],
168+
"createContainer": [
169+
{
170+
"path": "/usr/bin/mount-hook",
171+
"args": ["-mount", "arg1", "arg2"],
172+
"env": [ "key1=value1"]
173+
}
174+
],
175+
"startContainer": [
176+
{
177+
"path": "/usr/bin/refresh-ldcache"
178+
}
179+
],
158180
"poststart": [
159181
{
160182
"path": "/usr/bin/notify-start",

0 commit comments

Comments
 (0)