From f0835e91c7f6f4e7962ec9051b630d97f290cafa Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 17 Aug 2016 16:14:40 -0700 Subject: [PATCH] *: Restore hook lifecycle information removed by create/start split I expect the lifecycle information was removed accidentally in be594153 (Split create and start, 2016-04-01, #384), because for a time it seemed like that PR would also be removing hooks. Putting the lifecycle information back in, I made some tweaks to adjust to the new environment, for example: * Put the pre-start hooks after the 'start' call, but before the meat of the start call (the container-process exec trigger). Folks who want a post-create hook can add one with that name. I'd like to have renamed poststop to post-delete to avoid confusion like [1]. But the motivation for keeping hooks was backwards compatibility [2] so I've left the name alone. * Put each "...command is invoked..." lifecycle entry in its own list entry, to match the 'create' list entry. * Move the rules about what happens on hook failure into the lifecycle. This matches pre-split entries like: If any prestart hook fails, then the container MUST be stopped and the lifecycle continues at step 7. and avoids respecifying that information in a second location (config.md). * I added the warning section to try and follow post-split's generic "generates an error" approach while respecting the pre-split desire to see what failed (we had "then an error including the exit code and the stderr is returned to the caller" and "then an error is logged"). * I left the state 'id' context out, since Michael didn't want it [3]. [1]: https://github.com/opencontainers/runtime-spec/pull/395 Subject: Run post-stop hooks before the container sandbox is deleted. [2]: https://github.com/opencontainers/runtime-spec/pull/483#issuecomment-240568422 Subject: *: Remove hooks [3]: https://github.com/opencontainers/runtime-spec/pull/532#discussion_r99232480 Subject: Restore hook language removed by create/start split Signed-off-by: W. Trevor King --- config.md | 13 ++++--------- runtime.md | 19 +++++++++++++++---- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/config.md b/config.md index 8925318e1..cb1491ff1 100644 --- a/config.md +++ b/config.md @@ -339,24 +339,19 @@ The [state](runtime.md#state) of the container is passed to the hooks over stdin ### Prestart -The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. -They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. +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). +They provide an opportunity to customize the container. In Linux, for e.g., the network namespace could be configured in this hook. -If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. - ### Poststart -The post-start hooks are called after the user process is started. +The post-start hooks MUST be called [after the user-specified process is executed](runtime#lifecycle) but before the [`start`](runtime.md#start) operation returns. For example this hook can notify user that real process is spawned. -If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. - ### Poststop -The post-stop hooks are called after the container process is stopped. +The post-stop hooks MUST be called [after the container is deleted](runtime#lifecycle) but before the [`delete`](runtime.md#delete) operation returns. Cleanup or debugging could be performed in such a hook. -If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. ### Example diff --git a/runtime.md b/runtime.md index 1e4903a9d..597a81cd5 100644 --- a/runtime.md +++ b/runtime.md @@ -57,17 +57,28 @@ The lifecycle describes the timeline of events that happen from when a container 3. Once the container is created additional actions MAY be performed based on the features the runtime chooses to support. However, some actions might only be available based on the current state of the container (e.g. only available while it is started). 4. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container. - The runtime MUST run the user-specified program, as specified by [`process`](config.md#process). -5. The container process exits. +5. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime. + If any prestart hook fails, the runtime MUST generate an error, stop the container, and continue the lifecycle at step 10. +6. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process). +7. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime. + If any poststart hook fails, the runtime MUST log a warning, but the remaining hooks and lifecycle continue as if the hook had succeeded. +8. The container process exits. This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked. -6. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. - The container MUST be destroyed by undoing the steps performed during create phase (step 2). +9. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. +10. The container MUST be destroyed by undoing the steps performed during create phase (step 2). +11. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime. + If any poststop hook fails, the runtime MUST log a warning, but the remaining hooks and lifecycle continue as if the hook had succeeded. ## 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. +## Warnings + +In cases where the specified operation logs a warning, this specification does not mandate how, or even if, that warning is returned or exposed to the user of an implementation. +Unless otherwise stated, logging a warning does not change the flow of the operation; it MUST continue as if the warning had not been logged. + ## Operations OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.