Merge pull request #53354 from lmktfy/20251120_update_vertical_pod_autoscaling_docs

Update VerticalPodAutoscaler concept page

Author: k8s-ci-robot

content/en/docs/concepts/workloads/autoscaling/vertical-pod-autoscale.md

@@ -14,14 +14,15 @@ math: true
 
 <!-- overview -->
 
-In Kubernetes, a _VerticalPodAutoscaler_ automatically updates a workload resource (such as
+In Kubernetes, a _VerticalPodAutoscaler_ automatically updates a workload management {{< glossary_tooltip text="resource" term_id="api-resource" >}} (such as
 a {{< glossary_tooltip text="Deployment" term_id="deployment" >}} or
 {{< glossary_tooltip text="StatefulSet" term_id="statefulset" >}}), with the
-aim of automatically adjusting resource requests and limits to match actual usage.
+aim of automatically adjusting infrastructure {{< glossary_tooltip text="resource" term_id="infrastructure-resource" >}}
+[requests and limits](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) to match actual usage.
 
 Vertical scaling means that the response to increased resource demand is to assign more resources (for example: memory or CPU) 
 to the {{< glossary_tooltip text="Pods" term_id="pod" >}} that are already running for the workload.
-This is also known as "rightsizing" or "autopilot".
+This is also known as _rightsizing_, or sometimes _autopilot_.
 This is different from horizontal scaling, which for Kubernetes would mean deploying more Pods to distribute the load.
 
 If the resource usage decreases, and the Pod resource requests are above optimal levels, 
@@ -53,8 +54,8 @@ graph BT
     admission[VPA Admission Controller]
 
     vpa_cr[VerticalPodAutoscaler CRD]
-    recommender[VPA Recommender]
-    updater[VPA Updater]
+    recommender[VPA recommender]
+    updater[VPA updater]
 
     metrics --> recommender
     recommender -->|Stores Recommendations| vpa_cr
@@ -89,9 +90,10 @@ graph BT
 Figure 1. VerticalPodAutoscaler controls the resource requests and limits of Pods in a Deployment
 
 Kubernetes implements vertical pod autoscaling through multiple cooperating components that run intermittently (it is not a continuous process). The VPA consists of three main components: 
-The Recommender, which analyzes resource usage and provides recommendations.
-The Updater, which updates Pod resource requests either by evicting Pods or modifying them in place.
-And the Admission Controller, which applies recommendations to new or recreated Pods.
+
+* The _recommender*, which analyzes resource usage and provides recommendations.
+* The _updater_, that Pod resource requests either by evicting Pods or modifying them in place.
+* And the VPA _admission controller_ webhook, which applies resource recommendations to new or recreated Pods.
 
 Once during each period, the Recommender queries the resource utilization for Pods targeted by each VerticalPodAutoscaler definition. The Recommender finds the target resource defined by the `targetRef`, then selects the pods based on the target resource's `.spec.selector` labels, and obtains the metrics from the resource metrics API to analyze actual CPU and memory consumption.
 
@@ -108,23 +110,31 @@ Based on this analysis, the Recommender calculates three types of recommendation
 These recommendations are stored in the VerticalPodAutoscaler resource's `.status.recommendation` field.
 
 
-The Updater component monitors the VerticalPodAutoscaler resources and compares current Pod resource requests with the recommendations. When the difference exceeds configured thresholds and the update policy allows it, the Updater can either:
+The _updater_ component monitors the VerticalPodAutoscaler resources and compares current Pod resource requests with the recommendations. When the difference exceeds configured thresholds and the update policy allows it, the updater can either:
+
 - Evict Pods, triggering their recreation with new resource requests (traditional approach)
 - Update Pod resources in place without eviction, when the cluster supports in-place Pod resource updates
 
-The chosen method depends on the configured update mode, cluster capabilities, and the type of resource change needed. In-place updates, when available, avoid Pod disruption but may have limitations on which resources can be modified. The Updater respects PodDisruptionBudgets to minimize service impact.
+The chosen method depends on the configured update mode, cluster capabilities, and the type of resource change needed. In-place updates, when available, avoid Pod disruption but may have limitations on which resources can be modified. The updater respects PodDisruptionBudgets to minimize service impact.
 
-The Admission Controller operates as a mutating webhook that intercepts Pod creation requests. It checks if the Pod is targeted by a VerticalPodAutoscaler and, if so, applies the recommended resource requests and limits before the Pod is created. This ensures new Pods start with appropriately sized resource allocations, whether they're created during initial deployment, after an eviction by the Updater, or due to scaling operations.
+The _admission controller_ operates as a mutating webhook that intercepts Pod creation requests. It
+checks if the Pod is targeted by a VerticalPodAutoscaler and, if so, applies the recommended
+resource requests and limits before the Pod is created. This ensures new Pods start with
+appropriately sized resource allocations, whether they're created during initial deployment,
+after an eviction by the updater, or due to scaling operations.
 
-The VerticalPodAutoscaler requires the Metrics Server to be installed in the cluster. The VPA components fetch metrics from the `metrics.k8s.io` API. The Metrics Server needs to be launched separately as it is not deployed by default in most clusters. For more information about resource metrics, see [Metrics Server](/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-server).
+The VerticalPodAutoscaler requires a metrics source, such as Kubernetes' Metrics Server {{< glossary_tooltip text="add-on" term_id="addons" >}},
+to be installed in the cluster.
+The VPA components fetch metrics from the `metrics.k8s.io` API. The Metrics Server needs to be launched separately as it is not deployed by default in most clusters. For more information about resource metrics, see [Metrics Server](/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/#metrics-server).
 
 ## Update modes
 
-The VerticalPodAutoscaler supports different update modes that control how and when
+A VerticalPodAutoscaler supports different _update modes_ that control how and when
 resource recommendations are applied to your Pods. You configure the update mode using
 the `updateMode` field in the VPA spec under `updatePolicy`:
 
 ```yaml
+---
 apiVersion: autoscaling.k8s.io/v1
 kind: VerticalPodAutoscaler
 metadata:
@@ -138,24 +148,31 @@ spec:
     updateMode: "Recreate"  # Off, Initial, Recreate, InPlaceOrRecreate
 ```
 
-### Off
+### Off {#updateMode-Off}
 
-In `Off` mode, the VPA Recommender still analyzes resource usage and generates recommendations, but these recommendations are not automatically applied to Pods. The recommendations are only stored in the VPA object's status field.
+In the _Off_ update mode, the VPA recommender still analyzes resource usage and generates
+recommendations, but these recommendations are not automatically applied to Pods.
+The recommendations are only stored in the VPA object's `.status` field.
 
-### Initial
+You can use a tool such as `kubectl` to view the `.status` and the recommendations in it.
 
-In `Initial` mode, VPA only sets resource requests when Pods are first created. It does not update resources for already running Pods, even if recommendations change over time.
+### Initial {#updateMode-Initial}
 
-### Recreate
+In _Initial_ mode, VPA only sets resource requests when Pods are first created. It does not update resources for already running Pods, even if recommendations change over time.
 
-In `Recreate` mode, VPA actively manages Pod resources by evicting Pods when their current resource requests differ significantly from recommendations. When a Pod is evicted, the workload controller (Deployment, StatefulSet, etc.) creates a replacement Pod, and the VPA Admission Controller applies the updated resource requests to the new Pod.
+### Recreate {#updateMode-Recreate}
 
-### InPlaceOrRecreate
+In _Recreate_ mode, VPA actively manages Pod resources by evicting Pods when their current
+resource requests differ significantly from recommendations. When a Pod is evicted, the workload
+controller (managing a Deployment, StatefulSet, etc) creates a replacement Pod, and the VPA admission
+controller applies the updated resource requests to the new Pod.
+
+### InPlaceOrRecreate {#updateMode-InPlaceOrRecreate}
 
 In `InPlaceOrRecreate` mode, VPA attempts to update Pod resource requests and limits without restarting the Pod when possible. However, if in-place updates cannot be performed for a particular resource change, VPA falls back to evicting the Pod
 (similar to `Recreate` mode) and allowing the workload controller to create a replacement Pod with updated resources.
 
-### Auto
+### Auto (deprecated) {#updateMode-Auto}
 
 {{< note >}}
 The `Auto` update mode is **deprecated since VPA version 1.4.0**. Use `Recreate` for
@@ -200,15 +217,30 @@ spec:
 
 #### minAllowed and maxAllowed
 
-These fields set boundaries for VPA recommendations. The VPA will never recommend resources below minAllowed or above maxAllowed, even if the actual usage data suggests different values.
+These fields set boundaries for VPA recommendations.
+The VPA will never recommend resources below `minAllowed` or above `maxAllowed`, even if the actual usage data suggests different values.
 
 #### controlledResources
 
-The controlledResources field specifies which resource types VPA should manage for a container. If not specified, VPA manages both CPU and memory by default. You can limit VPA to manage only specific resources.
-Valid resource names include cpu and memory.
+The `controlledResources` field specifies which resource types VPA should manage for a container in a Pod.
+If not specified, VPA manages both CPU and memory by default. You can restrict VPA to manage only specific resources.
+Valid resource names include `cpu` and `memory`.
 
 ### controlledValues
 
-The controlledValues field determines whether VPA controls resource requests, limits, or both:
-- `RequestsAndLimits` (default): VPA sets both requests and limits. The limit is scaled proportionally to the request.
-- `RequestsOnly`: VPA only sets requests, leaving limits unchanged. Limits are respected and can still trigger throttling or OOMKills if usage exceeds them.
+The `controlledValues` field determines whether VPA controls resource requests, limits, or both:
+
+RequestsAndLimits
+: VPA sets both requests and limits. The limit is scaled proportionally to the request. This is the default mode.
+
+RequestsOnly
+: VPA only sets requests, leaving limits unchanged. Limits are respected and can still trigger throttling or out-of-memory kills if usage exceeds them.
+
+See [requests and limits](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) to learn more about those two concepts.
+
+## {{% heading "whatsnext" %}}
+
+If you configure autoscaling in your cluster, you may also want to consider using
+[node autoscaling](/docs/concepts/cluster-administration/node-autoscaling/)
+to ensure you are running the right number of nodes.
+You can also read more about [_horizontal_ Pod autoscaling](/docs/tasks/run-application/horizontal-pod-autoscale/).