diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 557126e94692..2568d216b8e6 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2641,6 +2641,8 @@ Topics: File: nodes-pods-autoscaling - Name: Automatically adjust pod resource levels with the vertical pod autoscaler File: nodes-pods-vertical-autoscaler + - Name: Manually adjust pod resource levels + File: nodes-pods-adjust-resources-in-place - Name: Providing sensitive data to pods by using secrets File: nodes-pods-secrets - Name: Providing sensitive data to pods by using an external secrets store diff --git a/modules/nodes-pods-adjust-resources-in-place-about.adoc b/modules/nodes-pods-adjust-resources-in-place-about.adoc new file mode 100644 index 000000000000..d1e4e11d4e00 --- /dev/null +++ b/modules/nodes-pods-adjust-resources-in-place-about.adoc @@ -0,0 +1,125 @@ +// Module included in the following assemblies: +// +// * nodes/pods/nodes-pods-adjust-resources-in-place.adoc + +:_mod-docs-content-type: REFERENCE +[id="nodes-pods-adjust-resources-in-place-about_{context}"] += About in-place pod resizing + +In-place pod resizing allows you to change the CPU and memory resources for containers within a running pod without application disruption. The standard methods for changing pod CPU and memory resources cause the pod to be re-created, potentially causing disruption. In-place pod resizing allows you to scale pod resources up or down without suffering the downtime or state loss associated with a pod restart. + +When using in-place pod resizing to change CPU or memory resources, you can control whether a pod is restarted by configuring a resize policy in the pod specification. The following example resize policy requires a pod restart upon changing the memory resources, but prevents a restart for CPU resource changes. + +.Example resource policy +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: resize-demo +spec: + securityContext: + runAsNonRoot: true + seccompProfile: + type: RuntimeDefault + containers: + - name: pause +# ... + resizePolicy: <1> + - resourceName: cpu + restartPolicy: NotRequired + - resourceName: memory + restartPolicy: RestartContainer +---- +<1> Specifies a resize policy. + +[NOTE] +==== +Memory limits cannot be decreased unless the resize policy for `memory` is `RestartContainer`. +==== + +You cannot add or modify a resize policy to an existing pod, but you can add or edit the policy in the pod's owner object, such as a deployment, if the pod has an owner object. + +Using in-place pod resizing requires that you use the `--subresource resize` flag when editing a pod in the {oc-first}, as shown in the following examples: + +.Example commands +[source,terminal] +---- +$ oc edit pod --subresource resize +---- + +[source,terminal] +---- +$ apply -f .yaml --subresource resize +---- + +[source,terminal] +---- +$ patch pod --subresource resize --patch \ + '{"spec":{"containers":[{"name":"pause", "resources":{"requests":{"cpu":"800m"}, "limits":{"cpu":"800m"}}}]}}' +---- + +Because you need to use the `--subresource resize` flag with a resize policy, you cannot edit the pod resources in the {product-title} web console. + +If the resize policy is `NotRequired` and you change the request or limits, the pod is not restarted. + +[source,terminal] +---- +$ oc get pods +---- + +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +resize-pod 1/1 Running 0 5s +---- + +If the resize policy is `RestartContainer` and you change the request or limits, the pod is restarted. + +[source,terminal] +---- +$ oc get pods +---- + +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +resize-pod 1/1 Running 1 (5s ago) 5s +---- + +After making the resource changes, the pod status conditions indicate the state of a resize request by using the following messages: + +* `PodResizeInProgress`: The kubelet is able to allocate the requested resources and the change is being applied. +* `PodResizePending`: The kubelet cannot immediately make the change for one of the following reasons: +** `Infeasible`: The requested resize cannot be executed on the current node. For example, requesting more resources than the node has available would result in an `Infeasible` condition. +** `Deferred`: The requested resize 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. +* `Error`: The kubelet is experiencing an error during the resource allocation and reports the reason for the error in the message field. + +.Example status for an infeasible change +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: resize-demo +# ... +status: + conditions: + - lastProbeTime: "2025-09-03T15:00:50Z" + lastTransitionTime: "2025-09-03T15:00:50Z" + message: 'Node didn''t have enough capacity: cpu, requested: 1000000, capacity: + 3500' + reason: Infeasible + status: "True" + type: PodResizePending +---- + +Note the following limitations: + +* In-place pod resizing is not supported for non-restartable init containers and ephemeral containers. +* In-place pod resizing is not allowed if the changes violate other pod mutability constraints, such as the pod QoS class. +* Pods managed by a static `cpuManagerPolicy` or `memoryManagerPolicy` parameter cannot be resized with in-place pod resizing. +* Pods utilizing swap memory must use the `RestartContainer` policy for memory requests with in-place pod resizing. +// Above Notes taken from https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/#limitations diff --git a/modules/nodes-pods-adjust-resources-in-place-configuring.adoc b/modules/nodes-pods-adjust-resources-in-place-configuring.adoc new file mode 100644 index 000000000000..d47602f94410 --- /dev/null +++ b/modules/nodes-pods-adjust-resources-in-place-configuring.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// +// * nodes/pods/nodes-pods-adjust-resources-in-place.adoc + +:_mod-docs-content-type: PROCEDURE +[id="nodes-pods-adjust-resources-in-place-configuring_{context}"] += Configuring in-place pod resizing + +In-place pod resizing requires that you add a resize policy to a pod specification. + +You cannot add or modify a resize policy in an existing pod, but you can add or edit the policy in the pod's owner object, such as a deployment, if the pod has an owner object. + +.Procedure + +. Create a pod spec with a resize policy or add a resize policy to the owner object of an existing pod: + +.. Create a YAML file similar to the following example: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: resize-pod +spec: +# ... + containers: + - name: pause + resizePolicy: <1> + - resourceName: cpu + restartPolicy: NotRequired + - resourceName: memory + restartPolicy: RestartContainer +# ... +---- +<1> Specifies a resize policy. For CPU and/or memory resources specify one of the following values: ++ +* `NotRequired`: Apply any resource changes without restarting the pod. This is the default when using a resize policy. +* `RestartContainer`: Apply any resource changes and restart the pod. + +.. Create the object by running a command similar to the following: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- + +.Verification + +* Check that the resize policy is applied by modifying the CPU or memory requests or limits by running a command similar to the following. You must include the `--subresource resize` flag. If the pod has a owner object, such as a deployment, you must edit the owner object. ++ +[source,terminal] +---- +$ oc edit pod --subresource resize +---- ++ +If the policy is applied, the pod responds as expected. ++ +[source,terminal] +---- +$ oc get pods +---- ++ +If the resize policy is `NotRequired`, the pod is not restarted. ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +resize-pod 1/1 Running 0 5s +---- ++ +If the resize policy is `RestartContainer`, the pod is restarted. ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +resize-pod 1/1 Running 1 (5s ago) 5s +---- diff --git a/nodes/pods/nodes-pods-adjust-resources-in-place.adoc b/nodes/pods/nodes-pods-adjust-resources-in-place.adoc new file mode 100644 index 000000000000..a1e80003742b --- /dev/null +++ b/nodes/pods/nodes-pods-adjust-resources-in-place.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +:context: nodes-pods-adjust-resources-in-place +[id="nodes-pods-adjust-resources-in-place"] += Adjust pod resource levels without pod disruption +include::_attributes/common-attributes.adoc[] + +toc::[] + +You can change the CPU or memory resource requests and limits assigned to a container without re-creating or restarting the pod by using _in-place pod resizing_. + +include::modules/nodes-pods-adjust-resources-in-place-about.adoc[leveloffset=+1] + +include::modules/nodes-pods-adjust-resources-in-place-configuring.adoc[leveloffset=+1] + +[role="_additional-resources"] +== Additional resources +* xref:../../nodes/pods/nodes-pods-using.adoc#nodes-pods-understanding-requests-limits_nodes-pods-using-ssy[Understanding resource requests and limits]