Upgrade the VKE cluster data plane, i.e., upgrade the nodes.

Considerations

The target Kubernetes version to which the node is upgraded cannot exceed the Kubernetes version of the cluster's control plane where the node resides.

Kubernetes node upgrades can affect running applications. During the upgrade, pod probers and lifecycle hooks may fail, and in-place restarts of pods may occur. Therefore, before the upgrade, you need to check whether the cluster is in a healthy state and whether applications are at off-peak hours. This helps you determine whether to start upgrading nodes.

You cannot roll back the upgrade of the node Kubernetes version. Proceed with caution.

If you have modified the kubelet or containerd parameter configuration on the nodes, only compatible parameters will be retained during the node upgrade, and incompatible parameters will be removed. After the nodes are upgraded, you need to check the configuration again.

When upgrading nodes to v1.28 or later, the system will update the default values of kubelet parameters to the latest values. For details, see Configuring Kubelet parameters for node pools.

For more precautions regarding node upgrades, see Cluster upgrade operations.

Request description

VKE has deployed services in multiple regions globally to provide a stable and low-latency access experience. You can refer to the Service addresses topic and select the most suitable access point based on the region where your business is located.

Request method: POST

Request URL: https://vke.cn-beijing.volcengineapi.com?Action=UpgradeNodePools&Version=2022-05-12

Debugging

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameter

The following table describes the API request parameters. You also need to provide public parameters when calling this API. For details about public request parameters, see Public parameters.

Parameter	Type	Required	Sample value	Description
Action	String	Yes	UpgradeNodePools	The API name. The current API name is UpgradeNodePools.
Version	String	Yes	2022-05-12	The API version. The current version of the API is 2022-05-12.
ClusterId	String	Yes	cc8oo******	Cluster ID. You can call the ListClusters API to obtain cluster IDs. Note The cluster to be updated must be in the {Running,[*]} state. You can call the ListClusters API to view the current status of the cluster.
Operation	String	No	Precheck	The specific operation to be performed. Valid values: Precheck: (Default value) Only perform the upgrade precheck operation. Upgrade: Directly execute the upgrade task. The upgrade task includes a precheck, and after the check passes, the upgrade operation continues.
NodePools	Array of UpgradeNodePoolConfig	No	-	Information about the node pool where the nodes to be upgraded reside.
IgnorePrecheckWarning	Boolean	No	true	Whether to stop the upgrade process when a Warning occurs during the upgrade precheck. Valid values: true: When the upgrade precheck result is Warning, the node upgrade operation will not be stopped. false: (Default value) When the upgrade precheck result is Warning, the node upgrade operation will be stopped.
Runtime	Object of Runtime	No	-	Container runtime configuration.
KubernetesVersion	String	No	v1.36.1-vke.2	The Kubernetes version of the node, in the format <Kubernetes version>-<VKE patch version>. For the release notes for Kubernetes versions supported by VKE, see Kubernetes version release notes.
UpgradePolicy	Object of UpgradePolicy	No	-	The batching policy for node upgrades.
ClientToken	String	No	BC028527-33B9-4990-A633-******	A string used to ensure the idempotency of the request. This string is passed in by the caller and must be unique across different requests. ClientToken is case-sensitive and can consist of 64 ASCII characters at most.

UpgradeNodePoolConfig

Parameter	Type	Required	Sample value	Description
NodeIds	Array of String	No	["nd6ptkl0f9t**", "nd6ptkl0f9t**"]	List of node IDs to be upgraded. You can call the ListNodes API to obtain the node ID. A single call can include at most 2000 node IDs. Pass a parameter value: It indicates a node-level upgrade, and the specified nodes will be upgraded. Parameter value is empty: It indicates a node pool-level upgrade, and all nodes under the specified node pool will be upgraded. Note The nodes must be in the {Running,[OK]} status. You can call the ListNodes API to obtain the current status of nodes.
NodePoolId	String	Yes	pd6l4v8e****	The ID of the node pool where the nodes to be upgraded reside. You can call the ListNodePools API to obtain node pool IDs. Note The node pool must be in one of the following states: {Running,[]} {Scaling,[]} When nodes in the node pool are in the following statuses, the corresponding node upgrades will be blocked. Nodes in other statuses will complete the upgrade. {Running,[Unschedulable]} {Updating,[*]} {Failed,[NotReady]} {Failed,[Balance]} You can call the ListNodePools API to obtain the node pool status, and call the ListNodes API to obtain the node status.

Runtime

Parameter	Type	Required	Sample value	Description
Type	String	No	containerd	Container runtime type. Values: containerd: (Default) The containerd runtime.
Version	String	Yes	v2.1.9-vke.1	Container runtime version, in the format <scontainerd Version>-<VKE patch Version>. For a list of containerd versions for VKE, see the containerd release notes.

UpgradePolicy

Parameter	Type	Required	Sample value	Description
MaxFailed	Integer	No	0	The maximum number of node failures allowed during the upgrade process. If the number of failed nodes does not exceed this setting, the upgrade continues. If it exceeds this value, the upgrade stops. Value range: [0, 2000] Default value: 0
MaxUnavailable	Integer	No	100	The maximum number of concurrent nodes during a node pool upgrade. Value range: [0, 20] Default value: For node-level upgrade: 10 For node pool-level upgrade: 20

Sample requests

Response parameter

The following table contains the response parameters of this API. See Response results for details about public response parameters.

Parameter	Type	Sample value	Description
TaskId	String	tdaa4i21v7p3****	Task ID.

Sample responses

Error code

The error codes for this API are listed in the table below. For public error codes, see Public error codes.

HTTP status code	Error code	Error message	Description
400	OperationDenied.UpgradeNodesAndNodePools	UpgradeNodePools cannot be performed on both nodes and node pools at the same time.	Upgrading at both the node level and the node pool level is not allowed. When multiple arrays are passed in NodePools, if some arrays are upgraded at the node pool level and some at the node level, this error code will appear. Please update the corresponding parameter values and try again.
400	LimitExceeded.UpgradeNodesNumber	The number of nodes for upgrade exceeds the maximum limit of {{UpgradeNodesMaxNum}}.	The total number of nodes to be upgraded exceeds the limit. A single call supports upgrading at most 2000 nodes. Please update the relevant parameters and try again.
400	OperationDenied.ClusterStatus	The action is forbidden due to cluster status {{statusPhase}} and {{statusConditions}}.	The current status of the specified cluster does not support this operation. Confirm the required cluster status for this API and try again.
400	OperationDenied.NodeStatus	The action is forbidden on node {{nodeId}} due to node status {{statusPhase}} and {{statusConditions}}.	The current node status does not support this operation. Please confirm the required node status for this API and try again.
400	OperationDenied.NodePoolStatus	The action is forbidden on node pool {{nodePoolId}} due to node pool status {{statusPhase}} and {{statusConditions}}.	The current status of the specified node pool does not support this operation. Please confirm the required node pool status for this API and try again.
400	KubernetesVersionMismatch.RuntimeVersion	The specified runtime version {{runtimeVersion}} and Kubernetes version {{kubernetesVersion}} are mismatched.	The specified container runtime version does not match the cluster Kubernetes version. For example, containerd 2.1.x is only supported in clusters with Kubernetes v1.34 or later. Specify another container runtime version and try again later. For more information, see the containerd release notes.

Volcengine Kubernetes Engine