Update InPlacePodVerticalScaling docs for v1.33 beta (#50290)

* Update InPlacePodVerticalScaling docs for v1.33 beta

* Add reference to subresources for updating pods in pods doc

* Document allocation_manager checkpoint files

* Cross-reference resource resizing from CPU & memory assignment tasks

* Add note about resizing to the downward API reference

* Update VPA in-place resizing section

* Update _index.md

* Update downward-api.md

* Update InPlacePodVerticalScaling.md

* Update kubelet-files.md

* Update resize-container-resources.md

* Update autoscaling.md

---------

Co-authored-by: Qiming Teng <[email protected]>

Author: tallclair

content/en/docs/concepts/workloads/autoscaling.md

@@ -71,21 +71,19 @@ At the moment, the VPA can operate in four different modes:
 {{< table caption="Different modes of the VPA" >}}
 Mode | Description
 :----|:-----------
-`Auto` | Currently, `Recreate` might change to in-place updates in the future
+`Auto` | Currently `Recreate`. This might change to in-place updates in the future.
 `Recreate` | The VPA assigns resource requests on pod creation as well as updates them on existing pods by evicting them when the requested resources differ significantly from the new recommendation
 `Initial` | The VPA only assigns resource requests on pod creation and never changes them later.
 `Off` | The VPA does not automatically change the resource requirements of the pods. The recommendations are calculated and can be inspected in the VPA object.
 {{< /table >}}
 
-#### Requirements for in-place resizing
+#### In-place pod vertical scaling
 
 {{< feature-state feature_gate_name="InPlacePodVerticalScaling" >}}
 
-Resizing a workload in-place **without** restarting the {{< glossary_tooltip text="Pods" term_id="pod" >}}
-or its {{< glossary_tooltip text="Containers" term_id="container" >}} requires Kubernetes version 1.27 or later.
-Additionally, the `InPlaceVerticalScaling` feature gate needs to be enabled.
-
-{{< feature-gate-description name="InPlacePodVerticalScaling" >}}
+As of Kubernetes {{< skew currentVersion >}}, VPA does not support resizing pods in-place,
+but this integration is being worked on.
+For manually resizing pods in-place, see [Resize Container Resources In-Place](/docs/tasks/configure-pod-container/resize-container-resources/).
 
 ### Autoscaling based on cluster size
 
@@ -102,9 +100,9 @@ If the number of replicas should stay the same, you can scale your workloads ver
 the [_Cluster Proportional Vertical Autoscaler_](https://github.com/kubernetes-sigs/cluster-proportional-vertical-autoscaler).
 The project is **currently in beta** and can be found on GitHub.
 
-While the Cluster Proportional Autoscaler scales the number of replicas of a workload, the Cluster Proportional Vertical Autoscaler
-adjusts the resource requests for a workload (for example a Deployment or DaemonSet) based on the number of nodes and/or cores
-in the cluster.
+While the Cluster Proportional Autoscaler scales the number of replicas of a workload,
+the Cluster Proportional Vertical Autoscaler adjusts the resource requests for a workload
+(for example a Deployment or DaemonSet) based on the number of nodes and/or cores in the cluster.
 
 ### Event driven Autoscaling
 
@@ -121,8 +119,8 @@ Another strategy for scaling your workloads is to **schedule** the scaling opera
 reduce resource consumption during off-peak hours.
 
 Similar to event driven autoscaling, such behavior can be achieved using KEDA in conjunction with
-its [`Cron` scaler](https://keda.sh/docs/latest/scalers/cron/). The `Cron` scaler allows you to define schedules
-(and time zones) for scaling your workloads in or out.
+its [`Cron` scaler](https://keda.sh/docs/latest/scalers/cron/).
+The `Cron` scaler allows you to define schedules (and time zones) for scaling your workloads in or out.
 
 ## Scaling cluster infrastructure
 

content/en/docs/concepts/workloads/pods/_index.md

@@ -245,6 +245,21 @@ have some limitations:
   1. updating the field from a positive number to a smaller, non-negative
      number.
 
+### Pod subresources
+
+The above update rules apply to regular pod updates, but other pod fields can be updated through _subresources_.
+
+- **Resize:** The `resize` subresource allows container resources (`spec.containers[*].resources`) to be updated.
+  See [Resize Container Resources](#resize-container-resources) for more details.
+- **Ephemeral Containers:** The `ephemeralContainers` subresource allows
+  {{< glossary_tooltip text="ephemeral containers" term_id="ephemeral-container" >}}
+  to be added to a Pod.
+  See [Ephemeral Containers](/docs/concepts/workloads/pods/ephemeral-containers/) for more details.
+- **Status:** The `status` subresource allows the pod status to be updated.
+  This is typically only used by the Kubelet and other system controllers.
+- **Binding:** The `binding` subresource allows setting the pod's `spec.nodeName` via a `Binding` request.
+  This is typically only used by the {{< glossary_tooltip text="scheduler" term_id="kube-scheduler" >}}.
+
 ## Resource sharing and communication
 
 Pods enable data sharing and communication among their constituent
@@ -325,7 +340,8 @@ using the kubelet to supervise the individual [control plane components](/docs/c
 The kubelet automatically tries to create a {{< glossary_tooltip text="mirror Pod" term_id="mirror-pod" >}}
 on the Kubernetes API server for each static Pod.
 This means that the Pods running on a node are visible on the API server,
-but cannot be controlled from there. See the guide [Create static Pods](/docs/tasks/configure-pod-container/static-pod) for more information.
+but cannot be controlled from there. See the guide [Create static Pods](/docs/tasks/configure-pod-container/static-pod)
+for more information.
 
 {{< note >}}
 The `spec` of a static Pod cannot refer to other API objects
@@ -387,7 +403,8 @@ shut down.
 
 ## Container probes
 
-A _probe_ is a diagnostic performed periodically by the kubelet on a container. To perform a diagnostic, the kubelet can invoke different actions:
+A _probe_ is a diagnostic performed periodically by the kubelet on a container.
+To perform a diagnostic, the kubelet can invoke different actions:
 
 - `ExecAction` (performed with the help of the container runtime)
 - `TCPSocketAction` (checked directly by the kubelet)
@@ -401,14 +418,18 @@ in the Pod Lifecycle documentation.
 * Learn about the [lifecycle of a Pod](/docs/concepts/workloads/pods/pod-lifecycle/).
 * Learn about [RuntimeClass](/docs/concepts/containers/runtime-class/) and how you can use it to
   configure different Pods with different container runtime configurations.
-* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how you can use it to manage application availability during disruptions.
+* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/)
+  and how you can use it to manage application availability during disruptions.
 * Pod is a top-level resource in the Kubernetes REST API.
   The {{< api-reference page="workload-resources/pod-v1" >}}
   object definition describes the object in detail.
 * [The Distributed System Toolkit: Patterns for Composite Containers](/blog/2015/06/the-distributed-system-toolkit-patterns/) explains common layouts for Pods with more than one container.
 * Read about [Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
 
-To understand the context for why Kubernetes wraps a common Pod API in other resources (such as {{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}} or {{< glossary_tooltip text="Deployments" term_id="deployment" >}}), you can read about the prior art, including:
+To understand the context for why Kubernetes wraps a common Pod API in other resources
+(such as {{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}} or
+{{< glossary_tooltip text="Deployments" term_id="deployment" >}}),
+you can read about the prior art, including:
 
 * [Aurora](https://aurora.apache.org/documentation/latest/reference/configuration/#job-schema)
 * [Borg](https://research.google/pubs/large-scale-cluster-management-at-google-with-borg/)

content/en/docs/concepts/workloads/pods/downward-api.md

@@ -99,6 +99,15 @@ These container-level fields allow you to provide information about
 [requests and limits](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
 for resources such as CPU and memory.
 
+{{< note >}}
+{{< feature-state feature_gate_name="InPlacePodVerticalScaling" >}}
+Container CPU and memory resources can be resized while the container is running.
+If this happens, a downward API volume will be updated,
+but environment variables will not be updated unless the container restarts.
+See [Resize CPU and Memory Resources assigned to Containers](/docs/tasks/configure-pod-container/resize-container-resources/)
+for more details.
+{{< /note >}}
+
 
 `resource: limits.cpu`
 : A container's CPU limit

content/en/docs/reference/command-line-tools-reference/feature-gates/InPlacePodVerticalScaling.md

@@ -9,5 +9,9 @@ stages:
   - stage: alpha
     defaultValue: false
     fromVersion: "1.27"
+    toVersion: "1.32"
+  - stage: beta
+    defaultValue: true
+    fromVersion: "1.33"
 ---
 Enables in-place Pod vertical scaling.

content/en/docs/reference/node/kubelet-files.md

@@ -27,14 +27,16 @@ On Linux nodes, the kubelet also relies on reading cgroups and various system fi
 On Windows nodes, the kubelet collects metrics via a different mechanism that does not rely on
 paths.
 
-There are also a few other files that are used by the kubelet as well as kubelet communicates using local Unix-domain sockets. Some are sockets that the
+There are also a few other files that are used by the kubelet as well,
+as kubelet communicates using local Unix-domain sockets. Some are sockets that the
 kubelet listens on, and for other sockets the kubelet discovers them and then connects
 as a client.
 
 {{< note >}}
 
 This page lists paths as Linux paths, which map to the Windows paths by adding a root disk
-`C:\` in place of `/` (unless specified otherwise). For example, `/var/lib/kubelet/device-plugins` maps to `C:\var\lib\kubelet\device-plugins`.
+`C:\` in place of `/` (unless specified otherwise).
+For example, `/var/lib/kubelet/device-plugins` maps to `C:\var\lib\kubelet\device-plugins`.
 
 {{< /note >}}
 
@@ -85,18 +87,25 @@ Names of files:
 ### Checkpoint file for device manager {#device-manager-state}
 
 Device manager creates checkpoints in the same directory with socket files: `/var/lib/kubelet/device-plugins/`.
-The name of a checkpoint file is `kubelet_internal_checkpoint` for [Device Manager](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-integration-with-the-topology-manager)
+The name of a checkpoint file is `kubelet_internal_checkpoint` for
+[Device Manager](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-integration-with-the-topology-manager)
 
-### Pod status checkpoint storage {#pod-status-manager-state}
+### Pod resource checkpoints
 
 {{< feature-state feature_gate_name="InPlacePodVerticalScaling" >}}
 
-If your cluster has  
-[in-place Pod vertical scaling](/docs/concepts/workloads/autoscaling/#in-place-resizing)  
-enabled ([feature gate](/docs/reference/command-line-tools-reference/feature-gates/)  
-name `InPlacePodVerticalScaling`), then the kubelet stores a local record of allocated Pod resources.
+If a node has enabled the `InPlacePodVerticalScaling`[feature gate](/docs/reference/command-line-tools-reference/feature-gates/),
+the kubelet stores a local record of _allocated_ and _actuated_ Pod resources.
+See [Resize CPU and Memory Resources assigned to Containers](/docs/tasks/configure-pod-container/resize-container-resources/)
+for more details on how these records are used.
 
-The file name is `pod_status_manager_state` within the kubelet base directory
+Names of files:
+
+- `allocated_pods_state` records the resources allocated to each pod running on the node
+- `actuated_pods_state` records the resources that have been accepted by the runtime
+  for each pod pod running on the node
+
+The files are located within the kubelet base directory
 (`/var/lib/kubelet` by default on Linux; configurable using `--root-dir`).
 
 ### Container runtime
@@ -131,7 +140,8 @@ device manager, or storage plugins, and then attempts to connect
 to these sockets. The directory that the kubelet looks in is `plugins_registry` within the kubelet base
 directory, so on a typical Linux node this means `/var/lib/kubelet/plugins_registry`.
 
-Note, for the device plugins there are two alternative registration mechanisms. Only one should be used for a given plugin.
+Note, for the device plugins there are two alternative registration mechanisms
+Only one should be used for a given plugin.
 
 The types of plugins that can place socket files into that directory are:
 

content/en/docs/tasks/configure-pod-container/assign-cpu-resource.md

@@ -261,6 +261,8 @@ kubectl delete namespace cpu-example
 
 * [Configure Quality of Service for Pods](/docs/tasks/configure-pod-container/quality-service-pod/)
 
+* [Resize CPU and Memory Resources assigned to Containers](/docs/tasks/configure-pod-container/resize-container-resources/)
+
 ### For cluster administrators
 
 * [Configure Default Memory Requests and Limits for a Namespace](/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/)

content/en/docs/tasks/configure-pod-container/assign-memory-resource.md

@@ -344,6 +344,8 @@ kubectl delete namespace mem-example
 
 * [Configure Quality of Service for Pods](/docs/tasks/configure-pod-container/quality-service-pod/)
 
+* [Resize CPU and Memory Resources assigned to Containers](/docs/tasks/configure-pod-container/resize-container-resources/)
+
 ### For cluster administrators
 
 * [Configure Default Memory Requests and Limits for a Namespace](/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/)