Updated on 2026-09-08 GMT+08:00

Upgrading a Cluster

Function

This API is used to upgrade a cluster.

  • Cluster upgrade involves many operations on components. You are advised to upgrade your cluster on the CCE console, a more interactive and intuitive way to reduce operational risks.

  • Currently, cluster upgrade APIs are available only upon request.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    cce:cluster:upgrade

    Write

    cluster *

    • g:EnterpriseProjectId

    • g:ResourceTag/<tag-key>

    -

    -

URI

POST /api/v3/projects/{project_id}/clusters/{cluster_id}/operation/upgrade

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Details:

Project ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI.

Constraints:

None

Options:

Project IDs of the account

Default value:

N/A

cluster_id

Yes

String

Details:

Cluster ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI.

Constraints:

None

Options:

Cluster IDs

Default value:

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

metadata

Yes

UpgradeClusterRequestMetadata object

Definition:

Cluster upgrade metadata information

Constraints:

N/A

Range:

N/A

Default Value:

N/A

spec

Yes

UpgradeSpec object

Definition:

Upgrade configuration information. CCE upgrades a cluster based on spec.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

Table 3 UpgradeClusterRequestMetadata

Parameter

Mandatory

Type

Description

apiVersion

Yes

String

Definition:

API version. The value is fixed at v3 and cannot be changed.

Constraints:

The value cannot be changed.

Range:

  • v3

Default Value:

v3

kind

Yes

String

Definition:

API type. The value is fixed at UpgradeTask and cannot be changed.

Constraints:

The value cannot be changed.

Range:

  • UpgradeTask

Default Value:

UpgradeTask

Table 4 UpgradeSpec

Parameter

Mandatory

Type

Description

clusterUpgradeAction

No

ClusterUpgradeAction object

Definition:

Configuration details about a cluster upgrade

Constraints:

N/A

Range:

N/A

Default Value:

N/A

Table 5 ClusterUpgradeAction

Parameter

Mandatory

Type

Description

addons

No

Array of UpgradeAddonConfig objects

Definition:

Add-on configuration list. CCE upgrades the add-ons based on the configuration during the cluster upgrade.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

nodeOrder

No

Map<String,Array<NodePriority>>

Definition:

Upgrade sequence of nodes in a node pool. key indicates the node pool ID. The value for the default node pool is DefaultPool.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

nodePoolOrder

No

Map<String,Integer>

Definition:

Node pool upgrade sequence, in a key-value pair. key indicates the node pool ID. The value for the default node pool is DefaultPool. value indicates the node pool priority. The default value is 0, which indicates the lowest priority. A larger value indicates a higher priority.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

strategy

Yes

UpgradeStrategy object

Definition:

The cluster upgrade policy

Constraints:

N/A

Range:

N/A

Default Value:

N/A

targetVersion

Yes

String

Definition:

Target cluster version, for example, v1.23

Constraints:

You can only upgrade a cluster to a later version. Do not enter a value that is equal to or earlier than the current cluster version.

Range:

Supported cluster versions

Default Value:

N/A

isOnlyUpgrade

No

Boolean

Definition:

Whether to skip the pre-upgrade check in the cluster upgrade process

Constraints:

N/A

Range:

  • false: The pre-upgrade check will be performed during the cluster upgrade.

  • true: The pre-upgrade check will be skipped during the cluster upgrade.

Default Value:

false

agencyName

No

String

Definition

Agency used by a cluster. This agency is used to generate temporary access credentials for components in the cluster. It will be used when resources of other related cloud services are automatically created in the cluster.

If this parameter is not included, the cluster inherits the original configuration. If no original configuration is available, the default CCE agency CCEAutoClusterAgency is automatically used. If this parameter is left blank, the default CCE agency CCEAutoClusterAgency is automatically used.

NOTE:
For details about CCE system agencies, see System Agencies.

Constraints

This parameter is supported only by clusters of v1.28.15-r90, v1.29.15-r50, v1.30.14-r50, v1.31.14-r10, v1.32.9-r10, v1.33.7-r10, v1.34.3-r0, and later versions.

Range

N/A

Default Value

Left blank

Table 6 UpgradeAddonConfig

Parameter

Mandatory

Type

Description

addonTemplateName

Yes

String

Definition:

CCE add-on name

Constraints:

N/A

Range:

Names of the add-ons installed in the cluster.

Default Value:

N/A

operation

Yes

String

Definition:

Action for upgrading an add-on

Constraints:

N/A

Range:

  • patch: The add-on version will be upgraded.

Default Value:

N/A

version

Yes

String

Definition:

Target add-on version

Constraints:

The target add-on version must match the target cluster version.

Range:

N/A

Default Value:

N/A

values

No

Map<String,Object>

Definition:

Add-on parameter list, in key-value pairs

Constraints:

N/A

Range:

N/A

Default Value:

N/A

Table 7 NodePriority

Parameter

Mandatory

Type

Description

nodeSelector

Yes

NodeSelector object

Definition:

Node label selector, which selects a batch of nodes

Constraints:

It applies only to node labels.

Range:

N/A

Default Value:

N/A

priority

Yes

Integer

Definition:

Priority of the current batch of nodes. A larger value indicates a higher priority.

Constraints:

N/A

Range:

Non-negative integer

Default Value:

0

Table 8 NodeSelector

Parameter

Mandatory

Type

Description

key

Yes

String

Definition:

Label key

Constraints:

N/A

Range:

N/A

Default Value:

N/A

value

No

Array of strings

Definition:

Label value list

Constraints:

N/A

Range:

N/A

Default Value:

N/A

operator

Yes

String

Definition:

Logical operator of labels

Constraints:

N/A

Range:

  • in: The value is in the list.

  • notin: The value is not in the list.

  • exists: The label exists.

  • !: The label does not exist.

  • gt: greater than

  • lt: less than

Default Value:

N/A

Table 9 UpgradeStrategy

Parameter

Mandatory

Type

Description

type

Yes

String

Definition:

Upgrade policy type

Constraints:

Currently, only inPlaceRollingUpdate is supported.

Range:

  • inPlaceRollingUpdate: in-place upgrade

Default Value:

N/A

inPlaceRollingUpdate

No

InPlaceRollingUpdate object

Definition:

Detailed configuration of an in-place upgrade policy

Constraints:

This parameter is mandatory when the in-place upgrade policy type is specified.

Range:

N/A

Default Value:

N/A

Table 10 InPlaceRollingUpdate

Parameter

Mandatory

Type

Description

userDefinedStep

No

Integer

Details:

Maximum number of nodes to be upgraded in a batch. Node pools will be upgraded in sequence. Nodes in node pools will be upgraded in batches. One node is upgraded in the first batch, two nodes in the second batch, and the number of nodes to be upgraded in each subsequent batch increases by a power of 2 until the maximum number of nodes to be upgraded in each batch is reached. The next cluster is upgraded after the previous one is upgraded.

Constraints:

None

Options:

1 to 60

Default value:

20

scope

No

String

Definition:

Scope of the node upgrade batch

Constraints:

N/A

Range:

  • Cluster: If the scope is set to a cluster, the upgrade batch will remain unchanged throughout the entire upgrade.

  • NodePool: If the scope is set to node pools, the upgrade batch will be reset for each individual node pool.

Default Value:

Cluster

Response Parameters

Status code: 200

Table 11 Response body parameters

Parameter

Type

Description

metadata

UpgradeCluserResponseMetadata object

Definition:

Upgrade task metadata

Range:

N/A

spec

UpgradeResponseSpec object

Definition:

Upgrade configurations

Range:

N/A

Table 12 UpgradeCluserResponseMetadata

Parameter

Type

Description

uid

String

Definition:

Upgrade task ID. You can obtain the progress by calling the API for obtaining cluster upgrade task details.

Range:

N/A

Table 13 UpgradeResponseSpec

Parameter

Type

Description

clusterUpgradeAction

ClusterUpgradeResponseAction object

Definition:

Cluster upgrade configurations

Range:

N/A

Table 14 ClusterUpgradeResponseAction

Parameter

Type

Description

version

String

Definition:

Current cluster version

Range:

N/A

targetVersion

String

Definition:

Target cluster version, for example, v1.23

Range:

N/A

targetPlatformVersion

String

Definition:

Platform version of the target cluster. This is an internal version of the cluster version and cannot be specified.

Range:

N/A

strategy

UpgradeStrategyResponse object

Definition:

Upgrade policies

Range:

N/A

config

Object

Definition:

Cluster configurations specified during an upgrade

Range:

N/A

Table 15 UpgradeStrategyResponse

Parameter

Type

Description

type

String

Definition:

Upgrade policy type. Only inPlaceRollingUpdate (in-place upgrade) is supported.

Range:

  • inPlaceRollingUpdate: in-place upgrade

inPlaceRollingUpdate

InPlaceRollingUpdateResponse object

Definition:

Detailed configuration of an in-place upgrade policy

Range:

N/A

Table 16 InPlaceRollingUpdateResponse

Parameter

Type

Description

userDefinedStep

Integer

Definition:

Maximum number of nodes to be upgraded in a batch

Range:

N/A

scope

String

Definition:

Scope of the node upgrade batch

Range:

N/A

Example Requests

Upgrade the cluster to v1.23 and set the node upgrade step to 20.

POST /api/v3/projects/{project_id}/clusters/{cluster_id}/operation/upgrade

{
  "metadata" : {
    "apiVersion" : "v3",
    "kind" : "UpgradeTask"
  },
  "spec" : {
    "clusterUpgradeAction" : {
      "strategy" : {
        "type" : "inPlaceRollingUpdate",
        "inPlaceRollingUpdate" : {
          "userDefinedStep" : 20
        }
      },
      "targetVersion" : "v1.23"
    }
  }
}

Example Responses

Status code: 200

Cluster upgrade requested.

{
  "metadata" : {
    "uid" : "976a33e2-f545-11ed-87af-0255ac1002c2"
  },
  "spec" : {
    "clusterUpgradeAction" : {
      "version" : "v1.19.16-r20",
      "targetVersion" : "v1.23.8-r0",
      "targetPlatformVersion" : "cce.10",
      "strategy" : {
        "type" : "inPlaceRollingUpdate",
        "inPlaceRollingUpdate" : {
          "userDefinedStep" : 20
        }
      },
      "config" : { }
    }
  }
}

SDK Sample Code

The SDK sample code is as follows.

Upgrade the cluster to v1.23 and set the node upgrade step to 20.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.cce.v3.region.CceRegion;
import com.huaweicloud.sdk.cce.v3.*;
import com.huaweicloud.sdk.cce.v3.model.*;


public class UpgradeClusterSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        CceClient client = CceClient.newBuilder()
                .withCredential(auth)
                .withRegion(CceRegion.valueOf("<YOUR REGION>"))
                .build();
        UpgradeClusterRequest request = new UpgradeClusterRequest();
        request.withClusterId("{cluster_id}");
        UpgradeClusterRequestBody body = new UpgradeClusterRequestBody();
        InPlaceRollingUpdate inPlaceRollingUpdateStrategy = new InPlaceRollingUpdate();
        inPlaceRollingUpdateStrategy.withUserDefinedStep(20);
        UpgradeStrategy strategyClusterUpgradeAction = new UpgradeStrategy();
        strategyClusterUpgradeAction.withType("inPlaceRollingUpdate")
            .withInPlaceRollingUpdate(inPlaceRollingUpdateStrategy);
        ClusterUpgradeAction clusterUpgradeActionSpec = new ClusterUpgradeAction();
        clusterUpgradeActionSpec.withStrategy(strategyClusterUpgradeAction)
            .withTargetVersion("v1.23");
        UpgradeSpec specbody = new UpgradeSpec();
        specbody.withClusterUpgradeAction(clusterUpgradeActionSpec);
        UpgradeClusterRequestMetadata metadatabody = new UpgradeClusterRequestMetadata();
        metadatabody.withApiVersion("v3")
            .withKind("UpgradeTask");
        body.withSpec(specbody);
        body.withMetadata(metadatabody);
        request.withBody(body);
        try {
            UpgradeClusterResponse response = client.upgradeCluster(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}

Upgrade the cluster to v1.23 and set the node upgrade step to 20.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkcce.v3.region.cce_region import CceRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkcce.v3 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = CceClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(CceRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = UpgradeClusterRequest()
        request.cluster_id = "{cluster_id}"
        inPlaceRollingUpdateStrategy = InPlaceRollingUpdate(
            user_defined_step=20
        )
        strategyClusterUpgradeAction = UpgradeStrategy(
            type="inPlaceRollingUpdate",
            in_place_rolling_update=inPlaceRollingUpdateStrategy
        )
        clusterUpgradeActionSpec = ClusterUpgradeAction(
            strategy=strategyClusterUpgradeAction,
            target_version="v1.23"
        )
        specbody = UpgradeSpec(
            cluster_upgrade_action=clusterUpgradeActionSpec
        )
        metadatabody = UpgradeClusterRequestMetadata(
            api_version="v3",
            kind="UpgradeTask"
        )
        request.body = UpgradeClusterRequestBody(
            spec=specbody,
            metadata=metadatabody
        )
        response = client.upgrade_cluster(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

Upgrade the cluster to v1.23 and set the node upgrade step to 20.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    cce "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := cce.CceClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := cce.NewCceClient(hcClient)

    request := &model.UpgradeClusterRequest{}
	request.ClusterId = "{cluster_id}"
	userDefinedStepInPlaceRollingUpdate:= int32(20)
	inPlaceRollingUpdateStrategy := &model.InPlaceRollingUpdate{
		UserDefinedStep: &userDefinedStepInPlaceRollingUpdate,
	}
	strategyClusterUpgradeAction := &model.UpgradeStrategy{
		Type: "inPlaceRollingUpdate",
		InPlaceRollingUpdate: inPlaceRollingUpdateStrategy,
	}
	clusterUpgradeActionSpec := &model.ClusterUpgradeAction{
		Strategy: strategyClusterUpgradeAction,
		TargetVersion: "v1.23",
	}
	specbody := &model.UpgradeSpec{
		ClusterUpgradeAction: clusterUpgradeActionSpec,
	}
	metadatabody := &model.UpgradeClusterRequestMetadata{
		ApiVersion: "v3",
		Kind: "UpgradeTask",
	}
	request.Body = &model.UpgradeClusterRequestBody{
		Spec: specbody,
		Metadata: metadatabody,
	}
	response, err := client.UpgradeCluster(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

Cluster upgrade requested.

Error Codes

See Error Codes.