Update pod lifecycle docs (#54177)

* Add kubelet details to pod lifecycle docs

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Add section for kubelet implementation details

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Add more detail including a deep link

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Match style guide

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Rewrap

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Another rewrap

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Better tooltip location suggestion

Co-authored-by: Tim Bannister <193443691+lmktfy@users.noreply.github.com>

* Move medium-level information to node reference page

Signed-off-by: lauralorenz <lauralorenz@google.com>

* Break up complex sentence

Signed-off-by: Laura Lorenz <lauralorenz@google.com>

* Simplify link name

Signed-off-by: Laura Lorenz <lauralorenz@google.com>

* Remove deep link and fix formatting

Signed-off-by: Laura Lorenz <lauralorenz@google.com>

* Kick netlify

Signed-off-by: Laura Lorenz <lauralorenz@google.com>

---------

Signed-off-by: lauralorenz <lauralorenz@google.com>
Signed-off-by: Laura Lorenz <lauralorenz@google.com>
Co-authored-by: Tim Bannister <193443691+lmktfy@users.noreply.github.com>

Author: lauralorenz

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

@@ -12,6 +12,10 @@ in the `Pending` [phase](#pod-phase), moving through `Running` if at least one
 of its primary containers starts OK, and then through either the `Succeeded` or
 `Failed` phases depending on whether any container in the Pod terminated in failure.
 
+While a Pod runs, the kubelet manages containers and translates the Pod's spec
+for the container runtime. The kubelet also manages executing
+[probes](#container-probes) that track the health of your application.
+
 Like individual application containers, Pods are considered to be relatively
 ephemeral (rather than durable) entities. Pods are created, assigned a unique
 ID ([UID](/docs/concepts/overview/working-with-objects/names/#uids)), and scheduled
@@ -25,10 +29,14 @@ plane marks the Pods for removal after a timeout period.
 
 ## Pod lifetime
 
-Whilst a Pod is running, the kubelet is able to restart containers to handle some
-kind of faults. Within a Pod, Kubernetes tracks different container
+Whilst a Pod is running, the kubelet is able to restart containers to handle
+some kind of faults. Within a Pod, Kubernetes tracks different container
 [states](#container-states) and determines what action to take to make the Pod
-healthy again.
+healthy again. This is done in a [polling
+loop](/docs/reference/node/kubelet-sync-loop/) that periodically reconciles the
+desired state (a Pod spec) with the actual state of the running containers.
+Because of this polling mechanism, the status seen in the API (like `kubectl get
+pod`) might have a slight delay compared to the instant reality on the node.
 
 In the Kubernetes API, Pods have both a specification and an actual status. The
 status for a Pod object consists of a set of [Pod conditions](#pod-conditions).
@@ -129,11 +137,16 @@ A Pod is granted a term to terminate gracefully, which defaults to 30 seconds.
 You can use the flag `--force` to [terminate a Pod by force](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination-forced).
 {{< /note >}}
 
-Since Kubernetes 1.27, the kubelet transitions deleted Pods, except for
-[static Pods](/docs/tasks/configure-pod-container/static-pod/) and
-[force-deleted Pods](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination-forced)
-without a finalizer, to a terminal phase (`Failed` or `Succeeded` depending on
-the exit statuses of the pod containers) before their deletion from the API server.
+Since Kubernetes 1.27, the kubelet transitions deleted Pods to a terminal phase
+(`Failed` or `Succeeded` depending on the exit statuses of the pod containers)
+before their deletion from the API server, with two exceptions:
+
+* [static Pods](/docs/tasks/configure-pod-container/static-pod/) (which are
+managed directly by the kubelet and represented by {{< glossary_tooltip
+text="mirror Pods" term_id="mirror-pod" >}}) 
+*  [force-deleted
+Pods](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination-forced)
+without a finalizer
 
 If a node dies or is disconnected from the rest of the cluster, Kubernetes
 applies a policy for setting the `phase` of all Pods on the lost node to Failed.

content/en/docs/reference/node/_index.md

@@ -6,7 +6,10 @@ no_list: true
 
 This section contains the following reference topics about nodes:
 
+* the kubelet's [sync loop](/docs/reference/node/kubelet-sync-loop/)
+
 * the kubelet's [checkpoint API](/docs/reference/node/kubelet-checkpoint-api/)
+
 * a list of [Articles on dockershim Removal and on Using CRI-compatible Runtimes](/docs/reference/node/topics-on-dockershim-and-cri-compatible-runtimes/)
 
 * [Kubelet Device Manager API Versions](/docs/reference/node/device-plugin-api-versions)

content/en/docs/reference/node/kubelet-sync-loop.md

@@ -0,0 +1,33 @@
+---
+content_type: "reference"
+title: Kubelet Sync Loop
+weight: 42
+---
+
+The [kubelet](/docs/reference/command-line-tools-reference/kubelet/) is the
+primary "node agent" that creates and watches Pods on each node. The `kubelet`
+runs a sync loop that periodically reconciles the desired state (a Pod spec)
+with the actual state of the running containers.
+
+1.  **Sync Loop**: The Sync Loop queues work (aggregated from many sources) for
+    the Pods assigned to its node (where `nodeName` matches the node). Over the
+    course of each loop, subprocesses called pod workers will attempt to
+    reconcile the desired state of these Pods against the current state of the
+    running containers.
+2. **Sync Pod**: The majority of the `kubelet` logic is stored in a suite of
+   functions within the `podSyncer` interface, including the `SyncPod` function
+   and its variants (like `SyncTerminatingPod` and `SyncTerminatedPod`). During
+   each Sync Loop, a relevant `podSyncer` function will be executed for each Pod
+   in an attempt to drive its state on the node toward the desired state.
+3. **{{< glossary_tooltip term_id="cri" text="Container Runtime Interface" >}}
+   (CRI)**: To actually run the containers, the `kubelet` uses the CRI to talk
+    to a container runtime (like containerd or CRI-O). The `kubelet` acts as the
+    client, instructing the runtime to create a "pod sandbox" and then
+    create/start the individual containers defined in the Pod spec.
+4.  **PLEG (Pod Lifecycle Event Generator)**: The `kubelet` needs to know when
+    containers start, stop, or fail. It relies on a component called PLEG to
+    periodically poll the runtime for the standard state of all containers. PLEG
+    generates events that wake up the Sync Loop to update the Pod status.
+
+Because of this polling mechanism, the status seen in the API (like `kubectl get
+pod`) might have a slight delay compared to the instant reality on the node.