更新节点池中节点的配置，包括 kubelet 和 containerd 参数配置。

请求说明

VKE 已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地域，选择最合适的接入点。

请求方式：POST

请求地址：https://vke.cn-beijing.volcengineapi.com?Action=UpdateNodePoolNodesConfig&Version=2022-05-12

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见公共参数。

参数	类型	是否必选	示例值	描述
Action	String	是	UpdateNodePoolNodesConfig	接口名称。当前 API 的名称为 UpdateNodePoolNodesConfig。
Version	String	是	2022-05-12	接口版本。当前 API 的版本为 2022-05-12。
ClusterId	String	是	cc5silum********	节点池所在集群的 ID。可以调用 ListClusters 接口，获取集群 ID。注意集群必须处于{Running,[Ok]}或{Updating,[Progressing]}状态。可调用 ListClusters 接口获取集群当前的状态。
NodePoolId	String	是	pc51i0m6********	节点池 ID。可以调用 ListNodePools 接口，获取节点池 ID。注意节点池必须处于{Running,[*]}或{Scaling,[Progressing]}状态。可调用 ListNodePools 接口获取节点池当前的状态。
KubeletConfig	Object of NodePoolKubeletConfig	否	-	节点 kubelet 配置。
ContainerdConfig	Object of NodePoolContainerdConfig	否	-	节点 containerd 配置。说明 KubeletConfig和ContainerdConfig必须至少配置一个。
NodeIds	Array of String	否	["nc5t5epmrsf*", "ndao9ti534q5ge6*"]	待同步配置的节点 ID。未配置该字段或传入空列表[]时，表示同步节点池内全部已有节点。
ClientToken	String	是	BC028527-33B9-4990-A633-84E9F9****	用于保证请求幂等性的字符串。该字符串由调用方传入，需保证不同请求之间唯一。ClientToken 对大小写敏感，长度不超过 64 个 ASCII 字符。
SyncPolicy	Object of NodeConfigSyncPolicy	否	-	存量节点配置同步策略。说明未配置该字段时，系统采用渐进式批次策略，同一配置分组内每批节点数按 1、2、4、8 … 逐步增加，达到单批上限10 后，后续批次均按上限执行。

NodePoolKubeletConfig

参数	类型	是否必选	示例值	描述
FeatureGates	Object of FeatureGates	否	-	特性门控，即描述 Kubernetes 特性的一组键值对。
TopologyManagerScope	String	否	container	拓扑管理策略的资源粒度，取值： container：表示资源对齐粒度为容器级。
TopologyManagerPolicy	String	否	none	拓扑管理策略，取值： none：（默认）禁用拓扑管理策略。 restricted：kubelet 仅接受在所请求资源上实现最佳 NUMA（Non-Uniform Memory Access，非一致存储访问结构）的 Pod。 best-effort：kubelet 会优先选择在 CPU 和设备资源上实现 NUMA 的 Pod。 single-numa-node：kubelet 仅允许在同一个节点的 CPU 和设备资源上实现 NUMA 的 Pod。
MaxPods	Integer	否	110	节点支持的最大 Pod 数量，默认值为 110。
KubeApiQps	Integer	否	50	与 APIServer 通信的每秒查询个数。取值范围为 1～500。默认值为 50。
KubeApiBurst	Integer	否	100	每秒发送到 APIServer 的突发请求数量上限。取值范围为 1～1000。默认值为 100。说明该值必须大于等于KubeApiQps参数的值。
EvictionHard	Array of EvictionHard	否	-	触发 Pod 驱逐操作的一组硬性门限。详细参数解释，请参见官方文档。如果希望显式地禁用，可以在任意资源上将其阈值设置为 0% 或 100%。默认值如下： memory.available: "300Mi" nodefs.available: "10%" nodefs.inodesFree: "5%" imagefs.available: "15%"
KubeReserved	Array of ComputeResource	否	-	节点预留给 Kubernetes 系统组件的资源。默认按照节点预留资源策略中默认值的一半进行资源预留。
SystemReserved	Array of ComputeResource	否	-	节点预留给操作系统的资源。默认按照节点预留资源策略中默认值的一半进行资源预留。
RegistryPullQps	Integer	否	5	集群从镜像仓库拉取镜像的 QPS 阈值。取值范围为 1～50。默认值为 5。
RegistryBurst	Integer	否	10	集群从镜像仓库拉取镜像的突发阈值。取值范围为 1～100。默认值为 10。说明仅当RegistryPullQps已配置时，才需要配置本参数，且取值必须大于等于RegistryPullQps参数的值。
SerializeImagePulls	Boolean	否	true	是否串行拉取镜像，取值： true：串行拉取镜像。 false：（默认值）并行拉取镜像，能够提高 Pod 启动速度。
CpuManagerPolicy	String	否	none	CPU 管理器策略。取值： none：默认策略。 static：允许为节点上具有某些资源特征的 Pod 赋予更强的 CPU 亲和性和独占性。
FailSwapOn	Boolean	否	false	当节点开启了 Swap 交换分区时，是否允许运行 kubelet。取值： true：（默认值）禁止节点在开启 Swap 的情况下运行 kubelet。这是 Kubernetes 的默认保护机制。由于 Swap 会干扰内存限制（memory limit）的精确控制，导致容器实际占用的内存超出预期，进而影响 Pod 调度和 OOM 判断的准确性。 false：允许节点在开启 Swap 的情况下运行 kubelet。适用于对内存隔离要求不严格或需要在已有 Swap 配置的存量节点上运行 Kubernetes 的场景。
PodPidsLimit	Integer	否	4096	限制单个 Pod 内所有容器可使用的进程 ID（PID）数量上限，避免单个 Pod 创建过多进程而耗尽节点的 PID 资源。取值范围为 -1 或正整数。单位为个。当取值为 -1 时，表示不限制单个 Pod 可使用的 PID 数量。说明该配置仅限制单个 Pod 的 PID 使用量，Pod 实际可用的 PID 数量还会受到节点内核 PID 上限及节点上其他进程 PID 使用情况的影响。不建议将该参数设置为 -1。建议结合节点的 PID 容量、单个 Pod 的进程规模及节点可运行的 Pod 数量合理设置，避免单个 Pod 耗尽节点 PID 资源；同时避免设置过小，导致 Pod 无法正常创建进程。
ImageMaximumGcAge	String	否	24h	未使用镜像被垃圾回收前的最长保留时长。超过该时间未被使用的镜像，在下次垃圾回收时将被清理。 Kubernetes duration 字符串格式，支持时间单位，例如 48h、168h。默认值为 0s，表示不按时间限制清理镜像，仅依据磁盘使用率（ImageGcHighThresholdPercent）触发回收。注意当该参数配置为非 0 取值时，必须大于ImageMinimumGcAge。仅 Kubernetes v1.30 及以上版本集群，支持配置该参数。
ImageMinimumGcAge	String	否	5m	未使用镜像被垃圾回收前的最短保留时长。在该时间内，镜像不会被垃圾回收，即使磁盘使用率已超过回收阈值。 Kubernetes duration 字符串格式，支持时间单位，例如 2m、30m。默认值为 2m。该参数可防止刚拉取的镜像被立即回收，保障镜像拉取与容器启动之间的时间窗口。说明该值不宜设置过大，否则在磁盘紧张时无法及时清理新近下载但短期未使用的镜像，可能加剧磁盘压力。
ImageGcLowThresholdPercent	Integer	否	80	镜像垃圾回收停止阈值。在镜像垃圾回收执行过程中，当磁盘使用率降到该百分比以下时，停止回收。取值范围为 0～100。默认值为 80。单位为百分比。注意配置该参数时，需保证ImageGcLowThresholdPercent小于ImageGcHighThresholdPercent。即使仅修改其中一个参数，系统也会结合另一个参数的默认值或原有配置进行校验。实际配置时，该参数允许配置为 0，但这意味着系统要把磁盘清理到 0% 才会停止，几乎不可能达到，不具备实际意义。
ImageGcHighThresholdPercent	Integer	否	85	镜像垃圾回收触发阈值。当磁盘使用率超过该值时，将触发垃圾回收，清理未使用的镜像以释放磁盘空间。取值范围为 0～100。默认值为 85。单位为百分比。注意配置该参数时，需保证ImageGcLowThresholdPercent小于ImageGcHighThresholdPercent。即使仅修改其中一个参数，系统也会结合另一个参数的默认值或原有配置进行校验。实际配置时，该参数允许配置为 100，但这意味着磁盘使用率为 100% 才会触发清理，属于极端保守，生产环境不推荐。

FeatureGates

参数	类型	是否必选	示例值	描述
QoSResourceManager	Boolean	否	false	是否启用 QoS 资源管理器，用于支持微拓扑调度。取值： true：启用 QoS 资源管理器。 false：（默认）不启用 QoS 资源管理器。说明该配置仅支持在以下版本的集群中使用： v1.24.15-vke.13 ≤ 集群版本 < v1.26 v1.26.10-vke.13 ≤ 集群版本 < v1.28
InPlacePodVerticalScaling	Boolean	否	true	是否开启 Pod 垂直伸缩功能，取值： true：开启 false：关闭注意该配置仅支持在如下版本集群中使用，其余版本集群不支持配置，否则报错： v1.28.3-vke.17 ≤ 集群版本 < v1.36

EvictionHard

参数	类型	是否必选	示例值	描述
Key	String	是	memory.available	硬性门限名称。取值： memory.available nodefs.available nodefs.inodesFree imagefs.available
Value	String	是	1Gi	硬性门限值。支持整数形式或百分比形式：整数形式：表示资源的具体门限值，单位为字节，例如 100Mi。百分比形式：表示资源的门限值占比，取值范围为 0%～100%，例如 20%。如果希望显式地禁用，可以在任意资源上将其阈值设置为 0% 或 100%。

ComputeResource

参数	类型	是否必选	示例值	描述
Name	String	是	cpu	资源名称，取值为 cpu 或 memory。
Quantity	String	是	1G	指定资源的资源量。当资源为 cpu 时，取值示例为 200m。当资源为 memory 时，取值示例为 1G。

NodePoolContainerdConfig

参数	类型	是否必选	示例值	描述
ConcurrentLayerFetchBuffer	Integer	否	512	并发分块拉取单个镜像层时使用的缓冲区大小。取值范围为 0 或正整数，单位为 Byte。当取值为 0 时，表示关闭单个镜像并发分块拉取功能。说明仅 containerd 为 v2.1.0 及以上版本时，支持配置该参数。
MaxConcurrentUnpacks	Integer	否	8	containerd 同时解压镜像层的最大数量。默认值为 1。仅在UseLocalImagePull配置为false时生效。说明仅 containerd 为 v2.3.0 及以上版本时，支持配置该参数。
MaxConcurrentDownloads	Integer	否	10	containerd 单次拉取镜像时可并发下载的镜像层最大数量。默认值为 3。未配置时，系统使用默认值。说明仅 containerd 为 v2.1.0 及以上版本时，支持配置该参数。
UseLocalImagePull	Boolean	否	true	containerd 的镜像拉取模式。取值： true：（默认值）使用本地客户端拉取镜像。 false：使用 Transfer Service 拉取镜像。说明仅 containerd 为 v2.1.0 及以上版本时，支持配置该参数。

NodeConfigSyncPolicy

参数	类型	是否必选	示例值	描述
MaxFailed	Integer	否	10	节点配置同步过程中，允许出现的最大失败节点数（状态为失败或未知的节点均计入）。取值范围 0～2000。默认值为 0，表示第一批次完成后发现失败则停止。
PausePolicy	String	否	NotPause	节点配置同步过程中的自动暂停策略。取值： FirstBatch：第一批完成后暂停，适合先小范围验证。 EveryBatch：每批完成后均暂停，适合高风险变更逐批确认。 NotPause：（默认值）全部批次连续执行。
MaxParallelism	Integer	否	10	每批次最多同时执行同步的节点数量。取值范围 1～10。默认值为 10。
BatchIntervalMinutes	Integer	否	0	相邻两批次之间的等待时间。取值范围 0～120，单位为分钟。默认值为 0。说明仅 PausePolicy 配置为 NotPause 时生效。

请求示例

返回参数

本接口返回参数如下表所示，公共返回参数请参见返回结果。

参数	类型	示例值	描述
TaskId	String	tcax******	任务 ID。

返回示例

错误码

本接口错误码如下表所示，公共错误码请参见公共错误码。

HTTP 状态码	错误码	错误信息	说明
400	InvalidParameter.{{parameter}}	The specified parameter {{parameter}} is invalid.	请求参数不合法，包括参数类型错误、长度不合法、枚举值不合法、不满足正则规则等。例如InvalidParameter.MaxPods、InvalidParameter.KubeApiQps。
400	OperationDenied.ClusterStatus	The action is forbidden due to cluster status {{statusPhase}} and {{statusConditions}}.	指定集群的当前状态不支持该操作。请确认该接口依赖的集群状态后重试。
400	OperationDenied.NodePoolStatus	The action is forbidden on node pool {{nodePoolId}} due to node pool status {{statusPhase}} and {{statusConditions}}.	指定节点池的当前状态不支持该操作。请确认该接口依赖的节点池状态后重试。
400	OperationDenied.NodeStatus	The action is forbidden on node {{nodeId}} due to node status {{statusPhase}} and {{statusConditions}}.	当前节点状态下无法执行此操作。请确认该接口依赖的节点状态后重试。
400	NotSupported.{{parameter}}	The specified {{resourceType}} {{resourceContent}} is not supported.	指定的资源不支持安装。请调用 ListSupportedAddons 接口，确认可安装组件列表后重试。

容器服务