Merge pull request #46964 from chanieljdan/merged-main-dev-1.31

Merged main dev 1.31

Author: k8s-ci-robot

OWNERS_ALIASES

@@ -63,6 +63,7 @@ aliases:
     - salaxander
     - sftim
     - tengqm
+    - Princesso # RT 1.31 Docs Lead
   sig-docs-en-reviews: # PR reviews for English content
     - dipesh-rawat
     - divya-mohan0209
@@ -78,6 +79,7 @@ aliases:
     - shannonxtreme
     - tengqm
     - windsonsea
+    - Princesso # RT 1.31 Docs Lead
   sig-docs-es-owners: # Admins for Spanish content
     - electrocucaracha
     - krol3

content/en/blog/_posts/2023-10-12-bootstrap-an-air-gapped-cluster-with-kubeadm/index.md

@@ -658,7 +658,7 @@ From the air gapped VM, switch into the ~/tmp directory where all of the artifac
 ```bash
 cd ~/tmp
 ```
-Set `$KUBECONFIG` to a file with credentials for the local cluster; also set the the Zarf version:
+Set `$KUBECONFIG` to a file with credentials for the local cluster; also set the Zarf version:
 ```bash
 export KUBECONFIG=/etc/kubernetes/admin.conf
 

content/en/docs/concepts/services-networking/topology-aware-routing.md

@@ -199,7 +199,7 @@ yet cover some relevant and plausible situations.
 
 * Follow the [Connecting Applications with Services](/docs/tutorials/services/connect-applications-service/) tutorial
 * Learn about the
-  [trafficDistribution](/docs/concepts/services-networking/service/#trafic-distribution)
+  [trafficDistribution](/docs/concepts/services-networking/service/#traffic-distribution)
   field, which is closely related to the `service.kubernetes.io/topology-mode`
   annotation and provides flexible options for traffic routing within
   Kubernetes.

content/en/docs/concepts/storage/storage-classes.md

@@ -54,7 +54,7 @@ When a PVC does not specify a `storageClassName`, the default StorageClass is
 used.
 
 If you set the
-[`storageclass.kubernetes.io/is-default-class`](/docs/reference/labels-annotations-taints/#ingressclass-kubernetes-io-is-default-class)
+[`storageclass.kubernetes.io/is-default-class`](/docs/reference/labels-annotations-taints/#storageclass-kubernetes-io-is-default-class)
 annotation to true on more than one StorageClass in your cluster, and you then
 create a PersistentVolumeClaim with no `storageClassName` set, Kubernetes
 uses the most recently created default StorageClass.

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

@@ -511,7 +511,7 @@ processes, and the Pod is then deleted from the
 container runtime's management service is restarted while waiting for processes to terminate, the
 cluster retries from the start including the full original grace period.
 
-An example flow:
+Pod termination flow, illustrated with an example:
 
 1. You use the `kubectl` tool to manually delete a specific Pod, with the default grace period
    (30 seconds).
@@ -530,18 +530,19 @@ An example flow:
 
       If the `preStop` hook is still running after the grace period expires, the kubelet requests
       a small, one-off grace period extension of 2 seconds.
-
-      {{< note >}}
-      If the `preStop` hook needs longer to complete than the default grace period allows,
-      you must modify `terminationGracePeriodSeconds` to suit this.
-      {{< /note >}}
+   {{% note %}}
+   If the `preStop` hook needs longer to complete than the default grace period allows,
+   you must modify `terminationGracePeriodSeconds` to suit this.
+   {{% /note %}}
 
    1. The kubelet triggers the container runtime to send a TERM signal to process 1 inside each
       container.
-      {{< note >}}
-      The containers in the Pod receive the TERM signal at different times and in an arbitrary
-      order. If the order of shutdowns matters, consider using a `preStop` hook to synchronize.
-      {{< /note >}}
+
+      There is [special ordering](#termination-with-sidecars) if the Pod has any
+      {{< glossary_tooltip text="sidecar containers" term_id="sidecar-container" >}} defined.
+      Otherwise, the containers in the Pod receive the TERM signal at different times and in
+      an arbitrary order. If the order of shutdowns matters, consider using a `preStop` hook
+      to synchronize (or switch to using sidecar containers).
 
 1. At the same time as the kubelet is starting graceful shutdown of the Pod, the control plane
    evaluates whether to remove that shutting-down Pod from EndpointSlice (and Endpoints) objects,
@@ -565,38 +566,19 @@ An example flow:
    condition `serving`.  You can find more details on how to implement connections draining in the
    tutorial [Pods And Endpoints Termination Flow](/docs/tutorials/services/pods-and-endpoint-termination-flow/)
 
-{{<note>}}
-If you don't have the `EndpointSliceTerminatingCondition` feature gate enabled
-in your cluster (the gate is on by default from Kubernetes 1.22, and locked to default in 1.26),
-then the Kubernetes control plane removes a Pod from any relevant EndpointSlices as soon as the Pod's
-termination grace period _begins_. The behavior above is described when the
-feature gate `EndpointSliceTerminatingCondition` is enabled.
-{{</note>}}
-
-{{<note>}}
-Beginning with Kubernetes 1.29, if your Pod includes one or more sidecar containers
-(init containers with an Always restart policy), the kubelet will delay sending
-the TERM signal to these sidecar containers until the last main container has fully terminated.
-The sidecar containers will be terminated in the reverse order they are defined in the Pod spec.
-This ensures that sidecar containers continue serving the other containers in the Pod until they are no longer needed.
-
-Note that slow termination of a main container will also delay the termination of the sidecar containers.
-If the grace period expires before the termination process is complete, the Pod may enter emergency termination.
-In this case, all remaining containers in the Pod will be terminated simultaneously with a short grace period.
+   <a id="pod-termination-beyond-grace-period" />
 
-Similarly, if the Pod has a preStop hook that exceeds the termination grace period, emergency termination may occur.
-In general, if you have used preStop hooks to control the termination order without sidecar containers, you can now
-remove them and allow the kubelet to manage sidecar termination automatically.
-{{</note>}}
+1. The kubelet ensures the Pod is shut down and terminated
+   1. When the grace period expires, if there is still any container running in the Pod, the
+      kubelet triggers forcible shutdown.
+      The container runtime sends `SIGKILL` to any processes still running in any container in the Pod.
+      The kubelet also cleans up a hidden `pause` container if that container runtime uses one.
+   1. The kubelet transitions the Pod into a terminal phase (`Failed` or `Succeeded` depending on
+      the end state of its containers).
+   1. The kubelet triggers forcible removal of the Pod object from the API server, by setting grace period
+      to 0 (immediate deletion).
+   1. The API server deletes the Pod's API object, which is then no longer visible from any client.
 
-1. When the grace period expires, the kubelet triggers forcible shutdown. The container runtime sends
-   `SIGKILL` to any processes still running in any container in the Pod.
-   The kubelet also cleans up a hidden `pause` container if that container runtime uses one.
-1. The kubelet transitions the Pod into a terminal phase (`Failed` or `Succeeded` depending on
-   the end state of its containers). This step is guaranteed since version 1.27.
-1. The kubelet triggers forcible removal of Pod object from the API server, by setting grace period
-   to 0 (immediate deletion).
-1. The API server deletes the Pod's API object, which is then no longer visible from any client.
 
 ### Forced Pod termination {#pod-termination-forced}
 
@@ -612,10 +594,8 @@ Setting the grace period to `0` forcibly and immediately deletes the Pod from th
 server. If the Pod was still running on a node, that forcible deletion triggers the kubelet to
 begin immediate cleanup.
 
-{{< note >}}
-You must specify an additional flag `--force` along with `--grace-period=0`
+Using kubectl, You must specify an additional flag `--force` along with `--grace-period=0`
 in order to perform force deletions.
-{{< /note >}}
 
 When a force deletion is performed, the API server does not wait for confirmation
 from the kubelet that the Pod has been terminated on the node it was running on. It
@@ -632,6 +612,24 @@ If you need to force-delete Pods that are part of a StatefulSet, refer to the ta
 documentation for
 [deleting Pods from a StatefulSet](/docs/tasks/run-application/force-delete-stateful-set-pod/).
 
+### Pod shutdown and sidecar containers {##termination-with-sidecars}
+
+If your Pod includes one or more
+[sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/)
+(init containers with an Always restart policy), the kubelet will delay sending
+the TERM signal to these sidecar containers until the last main container has fully terminated.
+The sidecar containers will be terminated in the reverse order they are defined in the Pod spec.
+This ensures that sidecar containers continue serving the other containers in the Pod until they
+are no longer needed.
+
+This means that slow termination of a main container will also delay the termination of the sidecar containers.
+If the grace period expires before the termination process is complete, the Pod may enter [forced termination](#pod-termination-beyond-grace-period).
+In this case, all remaining containers in the Pod will be terminated simultaneously with a short grace period.
+
+Similarly, if the Pod has a `preStop` hook that exceeds the termination grace period, emergency termination may occur.
+In general, if you have used `preStop` hooks to control the termination order without sidecar containers, you can now
+remove them and allow the kubelet to manage sidecar termination automatically.
+
 ### Garbage collection of Pods {#pod-garbage-collection}
 
 For failed Pods, the API objects remain in the cluster's API until a human or

content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md

@@ -385,6 +385,20 @@ for information on how to add members into an existing cluster.
 
 ## Restoring an etcd cluster
 
+{{< caution >}}
+If any API servers are running in your cluster, you should not attempt to
+restore instances of etcd. Instead, follow these steps to restore etcd:
+
+- stop *all* API server instances
+- restore state in all etcd instances
+- restart all API server instances
+
+The Kubernetes project also recommends restarting Kubernetes components (`kube-scheduler`,
+`kube-controller-manager`, `kubelet`) to ensure that they don't rely on some
+stale data. In practice the restore takes a bit of time.  During the
+restoration, critical components will lose leader lock and restart themselves.
+{{< /caution >}}
+
 etcd supports restoring from snapshots that are taken from an etcd process of
 the [major.minor](http://semver.org/) version. Restoring a version from a
 different patch version of etcd is also supported. A restore operation is
@@ -443,42 +457,28 @@ current state. Although the scheduled pods might continue to run, no new pods
 can be scheduled. In such cases, recover the etcd cluster and potentially
 reconfigure Kubernetes API servers to fix the issue.
 
-{{< note >}}
-If any API servers are running in your cluster, you should not attempt to
-restore instances of etcd. Instead, follow these steps to restore etcd:
-
-- stop *all* API server instances
-- restore state in all etcd instances
-- restart all API server instances
-
-We also recommend restarting any components (e.g. `kube-scheduler`,
-`kube-controller-manager`, `kubelet`) to ensure that they don't rely on some
-stale data. Note that in practice, the restore takes a bit of time.  During the
-restoration, critical components will lose leader lock and restart themselves.
-{{< /note >}}
 
 ## Upgrading etcd clusters
 
+{{< caution >}}
+Before you start an upgrade, back up your etcd cluster first.
+{{< /caution >}}
 
-For more details on etcd upgrade, please refer to the [etcd upgrades](https://etcd.io/docs/latest/upgrades/) documentation.
-
-{{< note >}}
-Before you start an upgrade, please back up your etcd cluster first.
-{{< /note >}}
+For details on etcd upgrade, refer to the [etcd upgrades](https://etcd.io/docs/latest/upgrades/) documentation.
 
 ## Maintaining etcd clusters
 
 For more details on etcd maintenance, please refer to the [etcd maintenance](https://etcd.io/docs/latest/op-guide/maintenance/) documentation.
 
+### Cluster defragmentation
+
 {{% thirdparty-content single="true" %}}
 
-{{< note >}}
 Defragmentation is an expensive operation, so it should be executed as infrequently
 as possible. On the other hand, it's also necessary to make sure any etcd member
 will not exceed the storage quota. The Kubernetes project recommends that when
 you perform defragmentation, you use a tool such as [etcd-defrag](https://github.com/ahrtr/etcd-defrag).
 
 You can also run the defragmentation tool as a Kubernetes CronJob, to make sure that
 defragmentation happens regularly. See [`etcd-defrag-cronjob.yaml`](https://github.com/ahrtr/etcd-defrag/blob/main/doc/etcd-defrag-cronjob.yaml)
-for details. 
-{{< /note >}}
+for details.

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md

@@ -873,7 +873,7 @@ with the `response` stanza populated, serialized to JSON.
 If conversion succeeds, a webhook should return a `response` stanza containing the following fields:
 * `uid`, copied from the `request.uid` sent to the webhook
 * `result`, set to `{"status":"Success"}`
-* `convertedObjects`, containing all of the objects from `request.objects`, converted to `request.desiredVersion`
+* `convertedObjects`, containing all of the objects from `request.objects`, converted to `request.desiredAPIVersion`
 
 Example of a minimal successful response from a webhook:
 

content/es/docs/concepts/architecture/leases.md

@@ -24,7 +24,7 @@ Analizando a detalle, cada hearbeat es una solicitud **update** a este objeto `L
 el campo `spec.renewTime` del objeto Lease. El plano de control de Kubernetes utiliza la marca de tiempo de este campo
 para determinar la disponibilidad de este «Nodo».
 
-Ve [Objetos Lease de nodos](/docs/concepts/architecture/nodes/#heartbeats) para más detalles.
+Ve [Objetos Lease de nodos](/docs/concepts/architecture/nodes/#node-heartbeats) para más detalles.
 
 ## Elección del líder