升级 VKE 集群数据面，即升级节点。

注意事项

节点要升级的目标 Kubernetes 版本不能超过节点所在集群控制面的 Kubernetes 版本。

节点 Kubernetes 升级会影响正在运行的业务，升级过程中可能造成 Pod Prober、Lifecycle Hook 失败，也可能会出现 Pod 原地重启情况。因此在升级前，应检查集群状态是否健康、是否处于业务低峰期，从而判断是否开始进行节点升级。

节点 Kubernetes 升级不支持回滚，请谨慎进行。

如果您在节点上修改过 kubelet、containerd 参数配置，则在升级节点过程中仅保留兼容参数，会移除不兼容参数，在升级节点完成后，需要您再次检查。

将节点升级至 v1.28 及以上版本时，系统会将 kubelet 参数的默认值更新到最新值。详情请参见配置节点池 Kubelet 参数。

更多节点升级注意事项，请参见集群升级操作。

请求说明

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

请求方式：POST

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

调试

API Explorer

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

去调试

请求参数

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

参数	类型	是否必选	示例值	描述
Action	String	是	UpgradeNodePools	接口名称。当前 API 的名称为 UpgradeNodePools。
Version	String	是	2022-05-12	接口版本。当前 API 的版本为 2022-05-12。
ClusterId	String	是	cc8oo******	集群的 ID。可以调用 ListClusters 接口，获取集群 ID。注意待更新的集群必须处于{Running,[*]}状态。可调用 ListClusters接口获取集群当前的状态。
Operation	String	否	Precheck	执行的具体操作，取值： Precheck：（默认值）仅执行升级检查操作。 Upgrade：直接执行升级任务，升级任务会包含一次升级检查，检查通过后继续执行升级操作。
NodePools	Array of UpgradeNodePoolConfig	否	-	待升级的节点所在节点池信息。
IgnorePrecheckWarning	Boolean	否	true	升级检查出现 Warning 时，是否停止升级过程，取值： true：升级检查结果为 Warning 时，不停止升级节点操作。 false：（默认值）升级检查结果为 Warning 时，停止升级节点操作。
Runtime	Object of Runtime	否	-	容器运行时配置。
KubernetesVersion	String	否	v1.36.1-vke.2	节点的 Kubernetes 版本，格式为<Kubernetes 版本>-<VKE 补丁版本>。容器服务已发布的 Kubernetes 版本，请参见 Kubernetes 版本发布记录。
UpgradePolicy	Object of UpgradePolicy	否	-	节点升级分批策略。
ClientToken	String	否	BC028527-33B9-4990-A633-******	用于保证请求幂等性的字符串。该字符串由调用方传入，需保证不同请求之间唯一。ClientToken 对大小写敏感，且最大值不超过 64 个 ASCII 字符。

UpgradeNodePoolConfig

参数	类型	是否必选	示例值	描述
NodeIds	Array of String	否	["nd6ptkl0f9t**", "nd6ptkl0f9t**"]	待升级的节点 ID 列表。可以调用 ListNodes 接口，获取节点 ID。单次调用最多填写 2000 个节点 ID。传入参数值：表示以节点维度升级，将对指定的节点进行升级操作。参数值为空：表示以节点池维度升级，将升级指定节点池下的所有节点。注意节点必须处于{Running,[OK]}状态。可调用 ListNodes接口，获取节点当前的状态。
NodePoolId	String	是	pd6l4v8e****	待升级节点所在节点池 ID。可以调用 ListNodePools 接口，获取节点池 ID。注意节点池必须处于以下任一状态： {Running,[]} {Scaling,[]} 节点池中的节点处于以下状态时，对应的节点升级会被拦截，其余状态节点会完成升级。 {Running,[Unschedulable]} {Updating,[*]} {Failed,[NotReady]} {Failed,[Balance]} 可调用 ListNodePools 接口获取节点池状态，调用 ListNodes接口，获取节点状态。

Runtime

参数	类型	是否必选	示例值	描述
Type	String	否	containerd	容器运行时类型，取值： containerd：（默认值）containerd 运行时。
Version	String	是	v2.1.9-vke.1	容器运行时版本，格式为<scontainerd 版本>-<VKE 补丁版本>。容器服务已发布的 containerd 版本，请参见 containerd 运行时发布记录。

UpgradePolicy

参数	类型	是否必选	示例值	描述
MaxFailed	Integer	否	0	升级过程中允许失败的最大节点数。当失败节点数不超过该设置时，继续升级，超过该值时停止升级。取值范围：[0, 2000] 默认值：0
MaxUnavailable	Integer	否	100	节点池升级时最大并发节点数。取值范围：[0, 20] 默认值：按节点维度升级：10 按节点池维度升级：20

请求示例

返回参数

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

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

返回示例

错误码

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

HTTP 状态码	错误码	错误信息	说明
400	OperationDenied.UpgradeNodesAndNodePools	UpgradeNodePools cannot be performed on both nodes and node pools at the same time.	不允许同时按照节点和节点池维度升级。NodePools 传入多个数组时，若部分数组按节点池维度升级，部分数组按节点维度升级，则会出现该错误码。请更新对应参数值后重试。
400	LimitExceeded.UpgradeNodesNumber	The number of nodes for upgrade exceeds the maximum limit of {{UpgradeNodesMaxNum}}.	升级的节点总数超出限制。单次调用最多支持升级 2000 个节点，请更新相关参数后重试。
400	OperationDenied.ClusterStatus	The action is forbidden due to cluster status {{statusPhase}} and {{statusConditions}}.	指定集群的当前状态不支持该操作。请确认该接口依赖的集群状态后重试。
400	OperationDenied.NodeStatus	The action is forbidden on node {{nodeId}} due to node status {{statusPhase}} and {{statusConditions}}.	当前节点状态下无法执行此操作。请确认该接口依赖的节点状态后重试。
400	OperationDenied.NodePoolStatus	The action is forbidden on node pool {{nodePoolId}} due to node pool status {{statusPhase}} and {{statusConditions}}.	指定节点池的当前状态不支持该操作。请确认该接口依赖的节点池状态后重试。
400	KubernetesVersionMismatch.RuntimeVersion	The specified runtime version {{runtimeVersion}} and kubernetes version {{kubernetesVersion}} are mismatched.	指定的容器运行时版本和集群 Kubernetes 版本不匹配。例如 containerd 2.1.x 版本仅支持在 Kubernetes v1.34 及以上版本集群中使用。请重新指定容器运行时版本后重试。更多信息，请参见 containerd 运行时发布记录。

容器服务