From 22a5ff9fdb24b7b326244b6e7c1a64a361ed5478 Mon Sep 17 00:00:00 2001 From: Andrew Garrett <2rs2ts@users.noreply.github.com> Date: Mon, 24 Aug 2020 12:09:11 -0700 Subject: [PATCH 1/4] Fix ambiguity around behavior of preStop hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When the previous paragraph says that postStart hooks are fired asynchronously, and this paragraph says "the behavior is much the same for preStop hooks," it reads as saying that preStop hooks are fired asynchronously as well–which is not true. It also seems prudent to give a concrete example of how terminationGracePeriodSeconds applies to the total time it takes the preStop hook and the container shutdown to happen. --- .../containers/container-lifecycle-hooks.md | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/content/en/docs/concepts/containers/container-lifecycle-hooks.md b/content/en/docs/concepts/containers/container-lifecycle-hooks.md index 09d5530a29..bc8a010a6d 100644 --- a/content/en/docs/concepts/containers/container-lifecycle-hooks.md +++ b/content/en/docs/concepts/containers/container-lifecycle-hooks.md @@ -38,7 +38,7 @@ No parameters are passed to the handler. This hook is called immediately before a container is terminated due to an API request or management event such as liveness probe failure, preemption, resource contention and others. A call to the preStop hook fails if the container is already in terminated or completed state. It is blocking, meaning it is synchronous, -so it must complete before the call to delete the container can be sent. +so it must complete before the signal to stop the Container can be sent. No parameters are passed to the handler. A more detailed description of the termination behavior can be found in @@ -64,10 +64,20 @@ the Container ENTRYPOINT and hook fire asynchronously. However, if the hook takes too long to run or hangs, the Container cannot reach a `running` state. -The behavior is similar for a `PreStop` hook. -If the hook hangs during execution, -the Pod phase stays in a `Terminating` state and is killed after `terminationGracePeriodSeconds` of pod ends. -If a `PostStart` or `PreStop` hook fails, +`PreStop` hooks are not executed asynchronously from the signal +to stop the Container–they hook must complete its execution before +the signal can be sent. +If a `PreStop` hook hangs during execution, +the Pod phase stays in a `Terminating` state and is killed after its `terminationGracePeriodSeconds` expires. +This grace period applies to the total time it takes for both +the `PreStop` hook to execute and for the Container to stop normally. +If, for example, `terminationGracePeriodSeconds` is 60, and the hook +takes 55 seconds to complete, and the Container takes 10 seconds to stop +normally after receiving the signal, then the Container will be killed +before it can stop normally, since `terminationGracePeriodSeconds` is +less than the total time (55+10) it takes for these two things to happen. + +If either a `PostStart` or `PreStop` hook fails, it kills the Container. Users should make their hook handlers as lightweight as possible. From 13fcd40344729a218a1426ffd72da1954ca31292 Mon Sep 17 00:00:00 2001 From: Andrew Garrett <2rs2ts@users.noreply.github.com> Date: Thu, 27 Aug 2020 09:23:53 -0700 Subject: [PATCH 2/4] lowercase container when it's not an API thing Co-authored-by: Tim Bannister --- .../en/docs/concepts/containers/container-lifecycle-hooks.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/concepts/containers/container-lifecycle-hooks.md b/content/en/docs/concepts/containers/container-lifecycle-hooks.md index bc8a010a6d..f0f8b72413 100644 --- a/content/en/docs/concepts/containers/container-lifecycle-hooks.md +++ b/content/en/docs/concepts/containers/container-lifecycle-hooks.md @@ -38,7 +38,7 @@ No parameters are passed to the handler. This hook is called immediately before a container is terminated due to an API request or management event such as liveness probe failure, preemption, resource contention and others. A call to the preStop hook fails if the container is already in terminated or completed state. It is blocking, meaning it is synchronous, -so it must complete before the signal to stop the Container can be sent. +so it must complete before the signal to stop the container can be sent. No parameters are passed to the handler. A more detailed description of the termination behavior can be found in @@ -131,4 +131,3 @@ Events: * Get hands-on experience [attaching handlers to Container lifecycle events](/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/). - From 8b2e8df3ad059f983a9e9cc0f16fcd9f613d7405 Mon Sep 17 00:00:00 2001 From: Andrew Garrett <2rs2ts@users.noreply.github.com> Date: Thu, 27 Aug 2020 09:24:50 -0700 Subject: [PATCH 3/4] semicolon and s/they/the/ --- .../en/docs/concepts/containers/container-lifecycle-hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/concepts/containers/container-lifecycle-hooks.md b/content/en/docs/concepts/containers/container-lifecycle-hooks.md index f0f8b72413..7df2e3dbbb 100644 --- a/content/en/docs/concepts/containers/container-lifecycle-hooks.md +++ b/content/en/docs/concepts/containers/container-lifecycle-hooks.md @@ -65,7 +65,7 @@ However, if the hook takes too long to run or hangs, the Container cannot reach a `running` state. `PreStop` hooks are not executed asynchronously from the signal -to stop the Container–they hook must complete its execution before +to stop the Container; the hook must complete its execution before the signal can be sent. If a `PreStop` hook hangs during execution, the Pod phase stays in a `Terminating` state and is killed after its `terminationGracePeriodSeconds` expires. From 96a27ce40fc15d765625746367b382b343f76f84 Mon Sep 17 00:00:00 2001 From: Andrew Garrett <2rs2ts@users.noreply.github.com> Date: Fri, 2 Oct 2020 12:31:34 -0700 Subject: [PATCH 4/4] Clean up grammar around the phase section --- .../en/docs/concepts/containers/container-lifecycle-hooks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/containers/container-lifecycle-hooks.md b/content/en/docs/concepts/containers/container-lifecycle-hooks.md index 7df2e3dbbb..b8793eb009 100644 --- a/content/en/docs/concepts/containers/container-lifecycle-hooks.md +++ b/content/en/docs/concepts/containers/container-lifecycle-hooks.md @@ -68,7 +68,8 @@ the Container cannot reach a `running` state. to stop the Container; the hook must complete its execution before the signal can be sent. If a `PreStop` hook hangs during execution, -the Pod phase stays in a `Terminating` state and is killed after its `terminationGracePeriodSeconds` expires. +the Pod's phase will be `Terminating` and remain there until the Pod is +killed after its `terminationGracePeriodSeconds` expires. This grace period applies to the total time it takes for both the `PreStop` hook to execute and for the Container to stop normally. If, for example, `terminationGracePeriodSeconds` is 60, and the hook