Skip to content

docs(workloads): add in-place Pod resize guidance #824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yinshuxun wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs(workloads): add in-place Pod resize guidance #824

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa6361a
docs(workloads): add in-place Pod resize guidance
yinshuxun May 27, 2026
029368f
docs(workloads): clarify Pod resize version requirements
yinshuxun May 28, 2026
3e0e69d
docs(workloads): refine in-place resize prerequisites
yinshuxun May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/en/developer/building_application/application_workloads/pod.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ spec:

While Pods are often managed by higher-level controllers, direct kubectl operations on Pods are useful for troubleshooting, inspection, and ad-hoc tasks.

### Adjusting Pod Resources

To update CPU or memory requests and limits for a running Pod through the Kubernetes `resize` subresource, see [Adjust Pod Resource Levels Without Pod Disruption](./resize_pod_resources_in_place.mdx).

### Viewing a Pod

- To list all Pods in the current namespace:
Expand Down
160 changes: 160 additions & 0 deletions ...er/building_application/application_workloads/resize_pod_resources_in_place.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
---
weight: 95
---

# Adjust Pod Resource Levels Without Pod Disruption

Use in-place Pod resizing when you need to adjust CPU or memory requests and limits for a running Pod without recreating the Pod. This task uses the Kubernetes Pod `resize` subresource.

## Prerequisites

Ensure that the target Kubernetes cluster supports the Pod `resize` subresource. Use Kubernetes v1.33 or later with the `InPlacePodVerticalScaling` feature gate enabled on the control plane and nodes. In Kubernetes v1.35, this feature is stable and enabled by default.

## About In-place Pod Resizing

In-place Pod resizing lets you change CPU and memory resource requests and limits for containers in a running Pod. Standard resource changes usually require the Pod to be recreated, which can interrupt applications or lose runtime state. In-place Pod resizing applies supported resource changes through the Kubernetes Pod `resize` subresource.

You can control whether a container restarts during the resize by configuring `resizePolicy` in the Pod specification. For example, you can allow CPU changes without a restart and require a container restart for memory changes.

## Configure In-place Pod Resizing

Configure `resizePolicy` before you resize a running Pod. You cannot add or modify `resizePolicy` on an existing Pod. If the Pod is managed by an owner object, such as a Deployment or StatefulSet, add or update `resizePolicy` in the owner object's Pod template.

```yaml title="deployment-resize-policy.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
name: resize-demo
spec:
selector:
matchLabels:
app: resize-demo
template:
metadata:
labels:
app: resize-demo
spec:
containers:
- name: app
image: nginx:latest
resizePolicy:
- resourceName: cpu
restartPolicy: NotRequired
- resourceName: memory
restartPolicy: RestartContainer
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 512Mi
```

For CPU and memory resources, use one of the following `restartPolicy` values:

| Value | Description |
| --- | --- |
| `NotRequired` | Apply supported resource changes without restarting the container. |
| `RestartContainer` | Apply supported resource changes and restart the container. |

When decreasing memory limits with `NotRequired` or no memory `resizePolicy`, the kubelet applies the change on a best-effort basis and does not guarantee that the container avoids an out-of-memory kill. If current memory usage is higher than the requested limit, the resize can be skipped and remain in progress. Use `RestartContainer` for memory changes when you need more predictable behavior.

## Resize a Running Pod

Use the `resize` subresource when editing Pod resources. Run the commands from a workstation that can access the target cluster.

::: tip
Use `kubectl` v1.32.0 or later, or another API client that supports the Pod `resize` subresource. Older `kubectl` clients might reject `--subresource=resize` with errors such as `invalid subresource value: "resize"` or might not provide the `--subresource` flag for some commands, even when the Kubernetes API server supports `pods/resize`.
:::

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Edit the Pod resources interactively:

```bash
kubectl edit pod <pod_name> -n <namespace> --subresource=resize
```

Apply an updated Pod manifest through the `resize` subresource by using server-side apply:

```bash
kubectl apply --server-side -f <file_name>.yaml --subresource=resize
```

Patch the target container resources directly:

```bash
kubectl patch pod <pod_name> \
-n <namespace> \
--subresource=resize \
--patch '{"spec":{"containers":[{"name":"<container_name>","resources":{"requests":{"cpu":"800m"},"limits":{"cpu":"800m"}}}]}}'
```

Replace `<pod_name>`, `<namespace>`, and `<container_name>` with the target Pod, namespace, and container names.

Because this operation requires the Pod `resize` subresource, use `kubectl` or an API client version that supports the subresource.

## Verify Restart Behavior

Check whether the Pod restarted after the resize:

```bash
kubectl get pods -n <namespace>
```

If `restartPolicy` is `NotRequired` for the changed resource, the Pod should remain running without a container restart.

```text
NAME READY STATUS RESTARTS AGE
resize-pod 1/1 Running 0 5s
```

If `restartPolicy` is `RestartContainer` for the changed resource, the container restarts while the Pod remains running.

```text
NAME READY STATUS RESTARTS AGE
resize-pod 1/1 Running 1 (5s ago) 5s
```

## Check Resize Status

Check the resources currently applied to the running container:

```bash
kubectl get pod <pod_name> \
-n <namespace> \
-o jsonpath='{.status.containerStatuses[?(@.name=="<container_name>")].resources}'
```

Check resize conditions and events:

```bash
kubectl describe pod <pod_name> -n <namespace>
```

Resize conditions include:

- `PodResizeInProgress`: kubelet can allocate the requested resources and is applying the change.
- `PodResizePending`: kubelet cannot apply the change immediately.
- `Infeasible`: The requested resize cannot be executed on the current node.
- `Deferred`: The requested resize is not currently possible, but might become possible later.
- `Error`: kubelet reports an error during resource allocation.
Comment on lines +134 to +140
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Kubernetes Pod resize conditions PodResizeInProgress PodResizePending Infeasible Deferred

💡 Result:

In Kubernetes, the status of in-place Pod resizing is managed through two primary Pod conditions: PodResizePending and PodResizeInProgress [1][2]. This mechanism replaces the older, deprecated status.resize field [1][3]. PodResizePending This condition indicates that the Kubelet has received a request to resize a Pod but cannot immediately grant the resources [3][2]. The reason and message fields provide specific details [3]: 1. Infeasible: The requested resize is impossible to fulfill on the current node [4][3]. This occurs if the node lacks total capacity, the Pod is a static Pod, or the requested configuration (such as certain combinations of swap or static resource manager policies) is not supported [4]. Once marked Infeasible, the Kubelet will not re-evaluate the request [4]. 2. Deferred: The resize is theoretically feasible on the node but cannot be granted at the moment, typically due to temporary resource contention [4][3]. The Kubelet will periodically re-evaluate these requests, prioritizing them based on Pod priority (PriorityClass), Quality of Service (QoS) class, and the duration the request has been in the Deferred state [5][3]. PodResizeInProgress This condition indicates that the Kubelet has accepted the resize request and is in the process of applying the changes [3][2]. It is active whenever the allocated resources differ from the actuated (applied) resources [4]. If an error occurs during the actuation phase, this condition is set with reason: Error, and the message field contains the specific error details [4][3]. Under normal operations, this condition is typically short-lived while the runtime applies the new resource limits [3]. Summary of Key States: - PodResizePending: Kubelet cannot resize now. - Reason: Infeasible (permanent, will not retry) [4][3]. - Reason: Deferred (temporary, will retry) [4][3]. - PodResizeInProgress: Kubelet has accepted and is applying the resize [3][2]. - Reason: Error (actuation failure) [4][3].

Citations:

Fix/verify Error reason placement for Pod resize conditions.

Kubernetes in-place Pod resizing documents PodResizePending with reasons Infeasible and Deferred, while Error is associated with PodResizeInProgress when actuation fails. Update the doc snippet so Error is under PodResizeInProgress (or add an explicit citation if Error can also apply to PodResizePending).

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/en/developer/building_application/application_workloads/resize_pod_resources_in_place.mdx`
around lines 128 - 134, The doc incorrectly places the `Error` reason under
`PodResizePending`; update the snippet so `Error` is listed under
`PodResizeInProgress` (or add an explicit citation if you verify `Error` can
also appear under `PodResizePending`); specifically modify the bullets around
`PodResizeInProgress` and `PodResizePending` to show `Infeasible` and `Deferred`
as reasons for `PodResizePending` and move `Error` into the
`PodResizeInProgress` section (referencing the condition names
`PodResizeInProgress`, `PodResizePending`, and the reasons `Infeasible`,
`Deferred`, `Error`).


## Limitations

- Only CPU and memory requests and limits can be resized.
- In-place Pod resizing is not supported for non-restartable init containers or ephemeral containers.
- The resize must not violate other Pod mutability constraints, such as changing the Pod QoS class.
- Pods managed by static `cpuManagerPolicy` or `memoryManagerPolicy` cannot be resized in place.
- Pods that use swap memory must use `RestartContainer` for memory requests.
Comment on lines +147 to +148
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Kubernetes in-place Pod resize cpuManagerPolicy memoryManagerPolicy swap memory limitations

💡 Result:

Kubernetes in-place Pod resize (CPU/memory) behavior with cpuManagerPolicy, memoryManagerPolicy, and swap is constrained as follows. 1) What “in-place Pod resize” can change - Kubernetes supports in-place resizing of CPU and memory resources for running Pods (Pod vertical scaling). Pod-level aggregate CPU/memory in spec.resources can be updated in place without requiring a restart; container-level resizePolicy still governs whether the specific container is restarted for the resource change. [1] 2) cpuManagerPolicy (CPU Manager static policy) limitations - In-place resize is not supported for Guaranteed Pods when CPU Manager policy is set to static. This is explicitly called out by the in-place resize KEP logic via a “guaranteed_pod_cpu_manager_static_policy” condition. [2] - Practical implication: if you run Guaranteed pods (i.e., meet Guaranteed QoS conditions) with cpuManagerPolicy=static, Kubernetes will mark the resize as infeasible rather than trying to update cpusets live. [2][3] 3) memoryManagerPolicy (Memory Manager static policy) limitations - In-place resize is not supported for Guaranteed Pods when Memory Manager static policy is configured. This is explicitly called out via “guaranteed_pod_memory_manager_static_policy” condition. [2] - Practical implication: if you run Guaranteed pods with memoryManagerPolicy=Static, Kubelet will treat resize requests as unsupported/infeasible for those pods. [2][4] 4) Swap limitations for in-place resize - Kubernetes explicitly limits memory resizing for Pods that use swap: Pods utilizing swap memory cannot resize memory requests unless the memory resizePolicy restartPolicy is RestartContainer. [5] - If swap is enabled/used in the pod/container, in-place memory resize without a container restart is not allowed because swap settings (cgroup memory.swap.max) must be recalculated/aligned with updated memory requests. [6][5] 5) ResizePolicy details that drive restarts - Container spec.containers[*].resizePolicy controls restart behavior per resource type. - resizePolicy restartPolicy NotRequired applies the resource change without restarting the container. [5] - resizePolicy restartPolicy RestartContainer restarts the container when applying the new resource values (often required for memory). [5] - If both CPU and memory are being resized and memory’s policy requires a restart, the container will be restarted. [7] 6) Memory limit decrease behavior (additional relevant limitation) - For memory limit decreases, Kubernetes enforces that memory limits cannot be decreased unless the memory resize policy is RestartContainer. (So NotRequired is not sufficient for shrinking memory limits.) [8] Bottom line / quick matrix - cpuManagerPolicy=static + Guaranteed pod: in-place resize is not supported. [2] - memoryManagerPolicy=Static + Guaranteed pod: in-place resize is not supported. [2] - swap enabled (Pod “utilizing swap”): memory resize requires memory resizePolicy restartPolicy=RestartContainer (can’t be done purely in-place). [5] - Otherwise: container resizePolicy determines whether CPU/memory changes are applied live or via container restart. [1][5]

Citations:

Update the wording to match Kubernetes’ exact conditions for in-place resize (CPU/memory managers + swap)

  • For cpuManagerPolicy=static / memoryManagerPolicy=Static, Kubernetes does not support in-place Pod CPU/memory resize for Guaranteed Pods.
  • If the Pod/container is using swap memory, Kubernetes requires resizePolicy: { restartPolicy: RestartContainer } for the memory resize (so memory changes aren’t applied purely in-place).

docs/en/developer/building_application/application_workloads/resize_pod_resources_in_place.mdx (lines 141-142)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/en/developer/building_application/application_workloads/resize_pod_resources_in_place.mdx`
around lines 141 - 142, Replace the two bullets with precise Kubernetes
conditions: state that Kubernetes does NOT support in-place CPU/memory resize
for Guaranteed Pods when cpuManagerPolicy=static or memoryManagerPolicy=Static
(mention both keys exactly: cpuManagerPolicy=static and
memoryManagerPolicy=Static and the term "Guaranteed Pods"), and note that if a
Pod/container is using swap memory then memory resize requires specifying
resizePolicy: { restartPolicy: RestartContainer } so the memory change is not
applied purely in-place (include the exact field name resizePolicy and
restartPolicy value RestartContainer).

- ResourceQuota, LimitRange, and admission policies can still reject the resize request.

::: note
Because this operation requires the Pod `resize` subresource, it might not be available through web console resource editing. Use `kubectl` or an API client version that supports the `resize` subresource.
:::

## Additional Resources

- [Pods](./pod.mdx)
- [Resource Units](../concepts/unit.mdx)
- [Configuring VerticalPodAutoscaler (VPA)](../operation_maintaining/add_vpa.mdx)
- [Pod API Reference](../../../apis/kubernetes_apis/workload/pod.mdx)
18 changes: 12 additions & 6 deletions docs/en/developer/building_application/operation_maintaining/add_vpa.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ The VPA provides resource recommendations based on historical usage patterns, al

> **Important**: When manually applying VPA recommendations, pod recreation will occur, which can cause temporary disruption to your application. Consider applying recommendations during maintenance windows for production workloads.

::: info
VPA recommendations and in-place Pod resizing solve different parts of resource management. VPA recommends or applies resource values based on observed usage. In-place Pod resizing is a Kubernetes mechanism for updating CPU or memory resources of a running Pod through the Pod `resize` subresource. Some VPA versions support `InPlaceOrRecreate`, where VPA can try to apply recommendations through in-place Pod resizing and fall back to Pod recreation when an in-place update is not possible. This mode requires Kubernetes in-place Pod resizing support, VPA components that enable the `InPlaceOrRecreate` feature, and a VPA CRD that accepts this `updateMode` value. For manual runtime adjustments and `resizePolicy` behavior, see [Adjust Pod Resource Levels Without Pod Disruption](../application_workloads/resize_pod_resources_in_place.mdx).
:::

## Prerequisites
Before using VPA, ensure the following:
- The **Alauda Container Platform Vertical Pod Autoscaler** cluster plugin is installed in your cluster.
Expand Down Expand Up @@ -93,10 +97,11 @@ You can create a VerticalPodAutoscaler using the command line interface by defin
5. Specify the type of object.
6. The target resource to which the VPA applies
7. Update policy that defines how VPA applies recommendations. The updateMode can be:
- Auto: Automatically sets resource requests when creating pods and updates current pods to recommended resource requests. Currently equivalent to "Recreate". This mode may cause application downtime. Once in-place pod resource updates are supported, "Auto" mode will adopt this update mechanism.
- Recreate: Automatically sets resource requests when creating pods and evicts current pods to update to recommended resource requests. Will not use in-place updates.
- Initial: Only sets resource requests when creating pods, no modifications afterward.
- Off: Does not automatically modify pod resource requests, only provides recommendations in the VPA object.
- Initial: Only sets resource requests when creating pods, no modifications afterward.
- Recreate: Automatically sets resource requests when creating pods and evicts current pods to update to recommended resource requests. Will not use in-place updates.
- Auto: Automatically sets resource requests when creating pods and updates current pods to recommended resource requests. Currently equivalent to "Recreate" and may cause application downtime.
- InPlaceOrRecreate: Available only when the cluster supports in-place Pod resizing, the VPA components enable the `InPlaceOrRecreate` feature, and the VPA CRD accepts this value. VPA first attempts to apply recommendations by using in-place Pod resizing, then falls back to Pod recreation when the in-place update cannot be applied. Container `resizePolicy` settings can determine whether a container restarts during the resize.
8. Resource policy that can set specific strategies for different containers. For example, setting a container's mode to "Auto" means it will calculate recommendations for that container, while "Off" means it won't calculate recommendations.
9. Apply policy to all containers in the pod.
10. Set the mode to Auto or Off. Auto means recommendations will be generated for this container, Off means no recommendations will be generated.
Expand Down Expand Up @@ -163,9 +168,10 @@ You can create a VerticalPodAutoscaler using the command line interface by defin
#### Update Policy Options

- `updateMode: "Off"` - VPA only provides recommendations without automatically applying them. You can manually apply these recommendations as needed.
- `updateMode: "Auto"` - Automatically sets resource requests when creating pods and updates current pods to recommended values. Currently equivalent to "Recreate".
- `updateMode: "Recreate"` - Automatically sets resource requests when creating pods and evicts current pods to update to recommended values.
- `updateMode: "Initial"` - Only sets resource requests when creating pods, no modifications afterward.
- `updateMode: "Recreate"` - Automatically sets resource requests when creating pods and evicts current pods to update to recommended values.
- `updateMode: "Auto"` - Automatically sets resource requests when creating pods and updates current pods to recommended values. Currently equivalent to "Recreate".
- `updateMode: "InPlaceOrRecreate"` - Available only when the cluster supports in-place Pod resizing, the VPA components enable the `InPlaceOrRecreate` feature, and the VPA CRD accepts this value. VPA first attempts to apply recommendations by using in-place Pod resizing, then falls back to Pod recreation when the in-place update cannot be applied. Container `resizePolicy` settings can determine whether a container restarts during the resize.
- `minReplicas: <number>` - Minimum number of replicas. Ensures this minimum number of pods remain available when the Updater evicts pods. Must be greater than 0.

#### Container Policy Options
Expand All @@ -177,7 +183,7 @@ You can create a VerticalPodAutoscaler using the command line interface by defin
**Notes**:

- VPA recommendations are based on historical usage data, so it may take several days of pod operation before recommendations become accurate.
- Pod recreation will occur when VPA recommendations are applied in Auto mode, which can cause temporary disruption to your application.
- Pod recreation will occur when VPA recommendations are applied in Auto or Recreate mode, which can cause temporary disruption to your application. If your VPA plugin supports InPlaceOrRecreate mode, in-place updates can still fall back to Pod recreation when the requested resize cannot be applied in place.

## Follow-Up Actions

Expand Down