Docs

Volcengine Kubernetes Engine

Node pool

Configuring Kubelet parameters for node pools

You can specify the Kubelet parameters to manage the behavior of nodes. VKE allows you to specify the Kubelet parameters of nodes in the console. This topic describes how to specify Kubelet parameters of nodes.

tip

VKE allows you to specify only common Kubelet parameters in the console. For details, see the following content. If you need to specify other parameters, see Custom cluster Kubelet parameters.

Limits

When you upgrade a cluster, the rules for changing and retaining Kubelet parameters are as follows:

Kubelet parameters configured through the method described in this topic will not change.

Feature Gate parameters incompatible with the target version may be cleaned up. For example, when you upgrade to v1.28 or later, the QoSResourceManager parameter will be automatically cleaned up.

The default node pool does not support custom Kubelet parameters.

After you specify Kubelet parameters for a node pool, if you choose to apply the specified parameters to existing nodes for which Kubelet parameters are already specified, the configurations of the same parameters will be overwritten by the node pool configurations.

Supported Kubelet parameters

You can specify the custom Kubelet parameters described in the following table.

warning

Modifying topology-manager-policy, topology-manager-scope, and QoSResourceManager will restart Kubelet, and the resource allocation of pods will be recalculated based on the modified policy. In this case, running pods may restart or even fail to receive any resources. Proceed with caution.

Field	Default value	Description
cpu-manager-policy	none	The CPU manager policy. Valid values: none: The policy is the default policy. static: This policy allows pods with specific resource characteristics on the node to be granted enhanced CPU affinity and exclusivity.
eviction-hard	imagefs.available < 15% memory.available < 300Mi nodefs.available < 10% nodefs.inodesFree < 5%	A set of hard eviction thresholds that trigger pod eviction. For detailed parameter descriptions, see the official documentation.
fail-swap-on	true	Specifies whether kubelet can run when swap is enabled on the node. Valid values: true: Prevents kubelet from running when swap is enabled on the node. This is the default protection mechanism in Kubernetes. Swap can interfere with precise memory limit control. As a result, containers may use more memory than expected, affecting the accuracy of Pod scheduling and out-of-memory (OOM) detection. false: Allows kubelet to run when swap is enabled on the node. This option applies when strict memory isolation is not required or when Kubernetes must run on existing nodes with swap configured.
feature-gates	-	The feature gates, which are a set of key-value pairs that describe Kubernetes features. For detailed descriptions, see the Feature gate list section of this topic. warning The feature gate takes effect only in clusters of the following versions: v1.24.15-vke.13 ≤ Cluster version < v1.26 v1.26.10-vke.13 ≤ Cluster version < v1.28
image-gc-high-threshold-percent	85	The threshold for triggering image garbage collection. When disk utilization exceeds this value, garbage collection will be triggered. Unused images will be cleaned up to release disk space. The value is an integer. Valid values: 0 to 100. Unit: percentage. Note When specifying this parameter, make sure that image-gc-low-threshold-percent is less than image-gc-high-threshold-percent. Even if only one of the parameters is modified, the system validates it against the default value or the original configuration of the other parameter. You can set this parameter to 100. However, this value triggers cleanup only when disk usage reaches 100%. This value is extremely conservative and not recommended in production environments.
image-gc-low-threshold-percent	80	The threshold for stopping Image garbage collection. During image garbage collection, collection stops when disk usage falls below this percentage. The value is an integer. Valid values: 0 to 100. Unit: percentage. warning When specifying this parameter, make sure that image-gc-low-threshold-percent is less than image-gc-high-threshold-percent. Even if only one of the parameters is modified, the system validates it against the default value or the original configuration of the other parameter. You can set this parameter to 0. However, this value stops cleanup only after disk usage reaches 0%, which is almost impossible and has no practical value.
image-maximum-gc-age	0s	The maximum retention duration for unused images before they are garbage collected. Images that have remained unused for longer than this period will be cleaned up during the next garbage collection cycle. The value is a string. It supports time units, such as 30m and 168h. The default value is 0s, which indicates that images are not cleaned up based on time limits and are garbage collected only based on disk utilization (image-gc-high-threshold-percent). warning When this parameter is not set to 0s, it must be greater than image-minimum-gc-age. This parameter is supported only in clusters running on Kubernetes v1.30 or later.
image-minimum-gc-age	2m	The minimum retention duration for unused images before they are garbage collected. During this time, the image will not be garbage collected even if disk utilization exceeds the garbage collection threshold. The value is a string. It supports time units, such as 2m and 30m. This parameter prevents a newly pulled image from being garbage collected immediately. This keeps the image available during the window between the pull and container startup. tip Do not set a value that is too high. Otherwise, newly downloaded images that are not used in the short term cannot be cleaned up in time when disk space is tight. This potentially increases disk pressure.
kube-api-burst	100	The maximum burst requests sent to the API server per second. Enter an integer from 1 to 1000. The default value is 100. warning The value of this parameter must be greater than or equal to the value of the kube-api-qps parameter.
kube-api-qps	50	The number of QPS for communication with the API server. The value is an integer. Valid values: 1 to 500. The default value is 50.
kube-reserved	For information about the system default resource reservation policies, see Node resource reservation policies.	The system reserved resources of Kubernetes. You can specify the amount of reserved CPU and memory resources. If kube-reserved is not specified, the system will use the default value to configure resource reservation.
system-reserved	For information about the system default resource reservation policies, see Node resource reservation policies.	The system-reserved resources of VKE. You can specify the amount of reserved CPU and memory resources. If system-reserved is not specified, the system will use the default value to configure resource reservation.
max-pods	110	The maximum number of pods supported by the node.
pod-max-pids	-1	This parameter limits the maximum number of process IDs (PIDs) that all containers in a single Pod can use. This prevents a single Pod from creating excess processes and exhausting the PID resources of the node. The value is an integer. Valid values: -1 or a positive integer. Unit: count. When the value is set to -1, it indicates that the number of PIDs that a single Pod can use is not limited. tip This configuration only limits the number of PIDs that a single Pod can use. The actual number of PIDs available to a Pod is also affected by the PID limit of the node kernel and the PID usage of other processes on the node. We do not recommend setting the value to -1. We recommend setting the value based on the PID capacity of the node, the number of processes required by each Pod, and the number of Pods the node can run. This prevents a single Pod from exhausting the PID resources of the node. In addition, do not set a value that is too low. Otherwise, the Pod cannot create processes as expected.
registry-burst	10	The maximum number of images concurrently pulled from CR. The value is an integer. Valid values: 1 to 100. The value must be greater than or equal to the value of the registry-qps parameter.
registry-qps	5	The QPS threshold for a cluster pulling images from Container Registry (CR). The value is an integer. Valid values: 1 to 50.
serialize-image-pulls	false	Specify whether to serially pull images. Valid values: true: Serially pull images. false: (Default) Pull images in parallel to accelerate pod startup.
topology-manager-policy	none	The topology management policy. Valid values: none: The topology management policy is disabled by default. restricted: Kubelet accepts only pods that achieve optimal non-uniform memory access (NUMA) alignment on the requested resources. best-effort: Kubelet preferentially selects pods that achieve NUMA alignment on CPU and device resources. single-numa-node: Kubelet allows only pods that are aligned to the same NUMA node in terms of CPU and device resources.
topology-manager-scope	container	The resource alignment granularity of the topology management policy. Set the value to container.

Feature gate list

Feature gate	Default value	Description
QoSResourceManager	false	Specify whether to enable quality of service (QoS) Resource Manager to support micro-topology scheduling. Valid values: true: Enable QoS Resource Manager. false: (Default) Disable QoS Resource Manager.

Specify custom Kubelet parameters

Specify parameters during cluster creation

You can specify custom Kubelet parameters when you create a cluster.

Specify custom Kubelet parameters in the Advanced settings section of the Node pool configuration step. For more configurations, see Creating clusters.

Specify parameters during node pool creation

You can create new node pools in the cluster and specify custom Kubelet parameters.

Specify custom Kubelet parameters in the Advanced settings section of the Node pool configuration step. For more configurations, see Creating node pools.

Specify custom Kubelet parameters of existing node pools

You can specify custom Kubelet parameters for existing node pools in the cluster.

On the Node pool page, find the target node pool and click ... > Kubelet configs in the Actions column to specify custom Kubelet parameters. For more configurations, see Managing node pools.

Apply the new configurations to existing nodes

tip

When you add custom Kubelet parameters to an existing node pool, the configurations only take effect on new nodes and do not apply to existing nodes by default. If you need the configurations to take effect on existing nodes, you need to perform the operations described in this section.

When you apply custom Kubelet parameters to existing nodes for which Kubelet parameters are already specified, the configurations of the same parameters will be overwritten by the node pool configurations.

On the Node pool page, click the name of the target node pool to go to the node pool details page.

Click the Kubelet configs tab and click Existing node config synchronization. Custom parameters will be synchronized to existing nodes after a secondary confirmation.

After parameters are synchronized, you can view the result and details of the synchronization task in the Job log list section.

View custom Kubelet parameters

In the left navigation bar, click Cluster. Click the name of the target cluster to go to the cluster management page.

In the left navigation bar of the cluster management page, click Nodes > Node pool.

Click the name of the target node pool. On the page that appears, click the Kubelet configs tab to view the Kubelet parameter configurations for the node pool.

tip

You can also click Edit to update the Kubelet parameters for the node pool.

Last updated: 2026.10.10 17:41:56