Skip to content

Commit 5c983f8

Browse files
author
Tim Bannister
committed
Give sidecars and Pod termination a subheading
That way, the docs can link to it.
1 parent 6fd7cae commit 5c983f8

File tree

1 file changed

+30
-31
lines changed

1 file changed

+30
-31
lines changed

content/en/docs/concepts/workloads/pods/pod-lifecycle.md

Lines changed: 30 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -538,7 +538,7 @@ An example flow:
538538
1. The kubelet triggers the container runtime to send a TERM signal to process 1 inside each
539539
container.
540540

541-
There is special ordering if the Pod has any
541+
There is [special ordering](#termination-with-sidecars) if the Pod has any
542542
{{< glossary_tooltip text="sidecar containers" term_id="sidecar-container" >}} defined.
543543
Otherwise, the containers in the Pod receive the TERM signal at different times and in
544544
an arbitrary order. If the order of shutdowns matters, consider using a `preStop` hook
@@ -566,38 +566,19 @@ An example flow:
566566
condition `serving`. You can find more details on how to implement connections draining in the
567567
tutorial [Pods And Endpoints Termination Flow](/docs/tutorials/services/pods-and-endpoint-termination-flow/)
568568

569-
{{<note>}}
570-
If you don't have the `EndpointSliceTerminatingCondition` feature gate enabled
571-
in your cluster (the gate is on by default from Kubernetes 1.22, and locked to default in 1.26),
572-
then the Kubernetes control plane removes a Pod from any relevant EndpointSlices as soon as the Pod's
573-
termination grace period _begins_. The behavior above is described when the
574-
feature gate `EndpointSliceTerminatingCondition` is enabled.
575-
{{</note>}}
569+
<a id="pod-termination-beyond-grace-period" />
576570

577-
{{<note>}}
578-
Beginning with Kubernetes 1.29, if your Pod includes one or more sidecar containers
579-
(init containers with an Always restart policy), the kubelet will delay sending
580-
the TERM signal to these sidecar containers until the last main container has fully terminated.
581-
The sidecar containers will be terminated in the reverse order they are defined in the Pod spec.
582-
This ensures that sidecar containers continue serving the other containers in the Pod until they are no longer needed.
583-
584-
Note that slow termination of a main container will also delay the termination of the sidecar containers.
585-
If the grace period expires before the termination process is complete, the Pod may enter emergency termination.
586-
In this case, all remaining containers in the Pod will be terminated simultaneously with a short grace period.
587-
588-
Similarly, if the Pod has a preStop hook that exceeds the termination grace period, emergency termination may occur.
589-
In general, if you have used preStop hooks to control the termination order without sidecar containers, you can now
590-
remove them and allow the kubelet to manage sidecar termination automatically.
591-
{{</note>}}
571+
1. The kubelet ensures the Pod is shut down and terminated
572+
1. When the grace period expires, if there is still any container running in the Pod, the
573+
kubelet triggers forcible shutdown.
574+
The container runtime sends `SIGKILL` to any processes still running in any container in the Pod.
575+
The kubelet also cleans up a hidden `pause` container if that container runtime uses one.
576+
1. The kubelet transitions the Pod into a terminal phase (`Failed` or `Succeeded` depending on
577+
the end state of its containers).
578+
1. The kubelet triggers forcible removal of the Pod object from the API server, by setting grace period
579+
to 0 (immediate deletion).
580+
1. The API server deletes the Pod's API object, which is then no longer visible from any client.
592581

593-
1. When the grace period expires, the kubelet triggers forcible shutdown. The container runtime sends
594-
`SIGKILL` to any processes still running in any container in the Pod.
595-
The kubelet also cleans up a hidden `pause` container if that container runtime uses one.
596-
1. The kubelet transitions the Pod into a terminal phase (`Failed` or `Succeeded` depending on
597-
the end state of its containers). This step is guaranteed since version 1.27.
598-
1. The kubelet triggers forcible removal of Pod object from the API server, by setting grace period
599-
to 0 (immediate deletion).
600-
1. The API server deletes the Pod's API object, which is then no longer visible from any client.
601582

602583
### Forced Pod termination {#pod-termination-forced}
603584

@@ -633,6 +614,24 @@ If you need to force-delete Pods that are part of a StatefulSet, refer to the ta
633614
documentation for
634615
[deleting Pods from a StatefulSet](/docs/tasks/run-application/force-delete-stateful-set-pod/).
635616

617+
### Pod shutdown and sidecar containers {##termination-with-sidecars}
618+
619+
If your Pod includes one or more
620+
[sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/)
621+
(init containers with an Always restart policy), the kubelet will delay sending
622+
the TERM signal to these sidecar containers until the last main container has fully terminated.
623+
The sidecar containers will be terminated in the reverse order they are defined in the Pod spec.
624+
This ensures that sidecar containers continue serving the other containers in the Pod until they
625+
are no longer needed.
626+
627+
This means that slow termination of a main container will also delay the termination of the sidecar containers.
628+
If the grace period expires before the termination process is complete, the Pod may enter [forced termination](#pod-termination-beyond-grace-period).
629+
In this case, all remaining containers in the Pod will be terminated simultaneously with a short grace period.
630+
631+
Similarly, if the Pod has a `preStop` hook that exceeds the termination grace period, emergency termination may occur.
632+
In general, if you have used `preStop` hooks to control the termination order without sidecar containers, you can now
633+
remove them and allow the kubelet to manage sidecar termination automatically.
634+
636635
### Garbage collection of Pods {#pod-garbage-collection}
637636

638637
For failed Pods, the API objects remain in the cluster's API until a human or

0 commit comments

Comments
 (0)