From 4d2be9e23ba78cbfbb3cbdf0a8987adfbdb1f019 Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Tue, 11 Nov 2025 17:48:30 -0500 Subject: [PATCH 1/2] OSDOCS 17247 Document InPlaceOrRecreate feature in Vertical Pod Autoscaler --- ...-pods-vertical-autoscaler-configuring.adoc | 4 ++-- ...s-vertical-autoscaler-custom-resource.adoc | 2 +- ...-pods-vertical-autoscaler-using-about.adoc | 22 ++++++++++--------- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/modules/nodes-pods-vertical-autoscaler-configuring.adoc b/modules/nodes-pods-vertical-autoscaler-configuring.adoc index 262ee02d4cd4..367c73e3d721 100644 --- a/modules/nodes-pods-vertical-autoscaler-configuring.adoc +++ b/modules/nodes-pods-vertical-autoscaler-configuring.adoc @@ -36,7 +36,7 @@ spec: kind: Deployment <1> name: frontend <2> updatePolicy: - updateMode: "Auto" <3> + updateMode: "InPlaceOrRecreate" <3> resourcePolicy: <4> containerPolicies: - containerName: my-opt-sidecar @@ -47,7 +47,7 @@ spec: <1> Specify the type of workload object you want this VPA to manage: `Deployment`, `StatefulSet`, `Job`, `DaemonSet`, `ReplicaSet`, or `ReplicationController`. <2> Specify the name of an existing workload object you want this VPA to manage. <3> Specify the VPA mode: -* `Auto` to automatically apply the recommended resources on pods associated with the controller. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests. +* `InPlaceOrRecreate` to automatically apply the recommended resources on pods associated with the workload object. The VPA attempts to update the workload object with the new resource requests without re-creating the pod. If the VPA is unable to update the object in place, the VPA re-creates it. * `Recreate` to automatically apply the recommended resources on pods associated with the workload object. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests. Use the `Recreate` mode rarely, only if you need to ensure that the pods restart whenever the resource request changes. * `Initial` to automatically apply the recommended resources to newly-created pods associated with the workload object. The VPA does not update the pods as it learns new resource recommendations. * `Off` to only generate resource recommendations for the pods associated with the workload object. The VPA does not update the pods as it learns new resource recommendations and does not apply the recommendations to new pods. diff --git a/modules/nodes-pods-vertical-autoscaler-custom-resource.adoc b/modules/nodes-pods-vertical-autoscaler-custom-resource.adoc index 4ea068367790..4119d6ffc148 100644 --- a/modules/nodes-pods-vertical-autoscaler-custom-resource.adoc +++ b/modules/nodes-pods-vertical-autoscaler-custom-resource.adoc @@ -89,5 +89,5 @@ spec: kind: ScalablePod name: scalable-cr updatePolicy: - updateMode: "Auto" + updateMode: "InPlaceOrRecreate" ---- diff --git a/modules/nodes-pods-vertical-autoscaler-using-about.adoc b/modules/nodes-pods-vertical-autoscaler-using-about.adoc index d88d6606f522..20d291e8abb3 100644 --- a/modules/nodes-pods-vertical-autoscaler-using-about.adoc +++ b/modules/nodes-pods-vertical-autoscaler-using-about.adoc @@ -10,7 +10,8 @@ To use the Vertical Pod Autoscaler Operator (VPA), you create a VPA custom resou You use the VPA CR to associate a workload object and specify the mode that the VPA operates in: -* The `Auto` and `Recreate` modes automatically apply the VPA CPU and memory recommendations throughout the pod lifetime. The VPA deletes any pods in the project that are out of alignment with its recommendations. When redeployed by the workload object, the VPA updates the new pods with its recommendations. +* The `InPlaceOrRecreate` mode automatically applies the VPA CPU and memory recommendations throughout the pod lifetime. When any pod in the project is out of alignment with the VPA recommendations, the VPA attempts to apply updates in-place. If it is not able to update the pods in-place, the VPA deletes the pod. When redeployed by the workload object, the VPA updates the new pods with its recommendations. +* The `Recreate` mode automatically applies the VPA CPU and memory recommendations throughout the pod lifetime. The VPA deletes any pods in the project that are out of alignment with its recommendations. When redeployed by the workload object, the VPA updates the new pods with its recommendations. Use the `Recreate` mode rarely, only if you need to ensure that the pods restart whenever the resource request changes. * The `Initial` mode automatically applies VPA recommendations only at pod creation. * The `Off` mode only provides recommended resource limits and requests. You can then manually apply the recommendations. The `Off` mode does not update pods. @@ -128,16 +129,16 @@ spec: [id="nodes-pods-vertical-autoscaler-using-auto_{context}"] == Automatically applying VPA recommendations -To use the VPA to automatically update pods, create a VPA CR for a specific workload object with `updateMode` set to `Auto` or `Recreate`. +To use the VPA to automatically update pods, create a VPA CR for a specific workload object with `updateMode` set to `InPlaceOrRecreate` or `Recreate`. -When the pods are created for the workload object, the VPA constantly monitors the containers to analyze their CPU and memory needs. The VPA deletes any pods that do not meet the VPA recommendations for CPU and memory. When redeployed, the pods use the new resource limits and requests based on the VPA recommendations, honoring any pod disruption budget set for your applications. The recommendations are added to the `status` field of the VPA CR for reference. +When the pods are created for the workload object, the VPA constantly monitors the containers to analyze their CPU and memory needs. The VPA updates any pods that do not meet the VPA recommendations for CPU and memory to use the new resource limits and requests based on the VPA recommendations, honoring any pod disruption budget set for your applications. The recommendations are added to the `status` field of the VPA CR for reference. [NOTE] ==== By default, workload objects must specify a minimum of two replicas in order for the VPA to automatically delete their pods. Workload objects that specify fewer replicas than this minimum are not deleted. If you manually delete these pods, when the workload object redeploys the pods, the VPA does update the new pods with its recommendations. You can change this minimum by modifying the `VerticalPodAutoscalerController` object as shown in _Changing the VPA minimum value_. ==== -.Example VPA CR for the `Auto` mode +.Example VPA CR for the `InPlaceOrRecreate` or `Recreate` mode [source,yaml] ---- apiVersion: autoscaling.k8s.io/v1 @@ -150,13 +151,14 @@ spec: kind: Deployment <1> name: frontend <2> updatePolicy: - updateMode: "Auto" <3> + updateMode: "InPlaceOrRecreate" <3> ---- <1> The type of workload object you want this VPA CR to manage. <2> The name of the workload object you want this VPA CR to manage. -<3> Set the mode to `Auto` or `Recreate`: -* `Auto`. The VPA assigns resource requests on pod creation and updates the existing pods by terminating them when the requested resources differ significantly from the new recommendation. -* `Recreate`. The VPA assigns resource requests on pod creation and updates the existing pods by terminating them when the requested resources differ significantly from the new recommendation. Use this mode rarely, only if you need to ensure that when the resource request changes the pods restart. +<3> Set the mode to `InPlaceOrRecreate` or `Recreate`: ++ +* `InPlaceOrRecreate`. The VPA attempts to update the workload object with the new resource requests without re-creating the pod. If the VPA is unable to update the object in place, the VPA re-creates it. +* `Recreate`. The VPA assigns resource requests on pod creation and updates the existing pods by terminating them. Use this mode rarely, only if you need to ensure that when the resource request changes the pods restart. [NOTE] ==== @@ -258,7 +260,7 @@ spec: kind: Deployment <1> name: frontend <2> updatePolicy: - updateMode: "Auto" <3> + updateMode: "InPlaceOrRecreate" <3> resourcePolicy: <4> containerPolicies: - containerName: my-opt-sidecar @@ -266,7 +268,7 @@ spec: ---- <1> The type of workload object you want this VPA CR to manage. <2> The name of the workload object you want this VPA CR to manage. -<3> Set the mode to `Auto`, `Recreate`, `Initial`, or `Off`. Use the `Recreate` mode rarely, only if you need to ensure that when the resource request changes the pods restart. +<3> Set the mode to `InPlaceOrRecreate`, `Recreate`, `Initial`, or `Off`. Use the `Recreate` mode rarely, only if you need to ensure that when the resource request changes the pods restart. <4> Specify the containers that you do not want updated by the VPA and set the `mode` to `Off`. For example, a pod has two containers, the same resource requests and limits: From 5e9eb0d87effd25db19857f92dccf823933db23b Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Tue, 11 Nov 2025 18:24:48 -0500 Subject: [PATCH 2/2] Updates --- ...odes-pods-vertical-autoscaler-using-about.adoc | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/modules/nodes-pods-vertical-autoscaler-using-about.adoc b/modules/nodes-pods-vertical-autoscaler-using-about.adoc index 20d291e8abb3..8491bfebe7f9 100644 --- a/modules/nodes-pods-vertical-autoscaler-using-about.adoc +++ b/modules/nodes-pods-vertical-autoscaler-using-about.adoc @@ -15,6 +15,16 @@ You use the VPA CR to associate a workload object and specify the mode that the * The `Initial` mode automatically applies VPA recommendations only at pod creation. * The `Off` mode only provides recommended resource limits and requests. You can then manually apply the recommendations. The `Off` mode does not update pods. +When using the `InPlaceOrRecreate` mode, the following conditions might cause the in-place update to fail, resulting in pod re-creation. + +* The in-place update is infeasible. For example, requesting more resources than the node has available would result in an `Infeasible` condition. +* The resource update is deferred for more than five minutes. In this situation, the requested update is currently not possible, but might become possible at a later time. For example, if another pod is removed from the node, the requested resources might become available. The kubelet retries the resize when conditions on the node change. +* The resource update is in progress for more than 1 hour. +* The resource update would cause a change in pod QoS class. +* The resource update decreases memory for a pod that is configured with the `NotRequired` resize policy. + +For more information on in-place updates, see "About in-place pod resizing". + You can also use the CR to opt-out certain containers from VPA evaluation and updates. For example, a pod has the following limits and requests: @@ -93,6 +103,11 @@ The output shows the recommended resources, `target`, the minimum recommended re The VPA uses the `lowerBound` and `upperBound` values to determine if a pod needs updating. If a pod has resource requests less than the `lowerBound` values or more than the `upperBound` values, the VPA terminates and recreates the pod with the `target` values. +[role="_additional-resources"] +.Additional resources + +* xref:../../nodes/pods/nodes-pods-adjust-resources-in-place.adoc#nodes-pods-adjust-resources-in-place-about_nodes-pods-adjust-resources-in-place[Adjust pod resource levels without pod disruption] + [id="nodes-pods-vertical-autoscaler-using-one-pod_{context}"] == Changing the VPA minimum value