Help Center/ Cloud Container Engine/ API Reference (Ally Region)/ APIs/ Node Pool Management/ Synchronizing Node Configurations in a Node Pool
Updated on 2026-09-30 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Synchronizing Node Configurations in a Node Pool

Function

This API is used to synchronize the configurations of existing nodes in a node pool.

The URL for cluster management is in the format of https://Endpoint/uri, where uri specifies the resource path for API access.

Calling Method

For details, see Calling APIs.

URI

POST /api/v3/projects/{project_id}/clusters/{cluster_id}/nodepools/{nodepool_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

nodepool_id

Yes

String

Definition:

The node pool selected to be synchronized or upgraded

Constraints:

N/A

Range:

  • Node pool ID: Synchronize the configuration of a specified node pool. For details about how to obtain the node pool ID, see How to Obtain Parameters in the API URI.

  • DefaultPool: Upgrade the configuration of the default node pool.

Default Value:

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Definition:

Type (or format) of the request body. The default value is application/json. Other values of this field will be provided for specific APIs, if any.

Constraints:

GET requests are not validated.

Range:

N/A

Default Value:

N/A

X-Auth-Token

Yes

String

Details:

Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. For details, see Obtaining a User Token.

Constraints:

None

Options:

N/A

Default value:

N/A
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

kind

No

String

Definition:

API type

Constraints:

The value cannot be changed.

Range:

N/A

Default Value:

NodePool

apiVersion

No

String

Definition:

API version

Constraints:

The value cannot be changed.

Range:

N/A

Default Value:

v3

metadata

No

NodePoolMetadata object

Metadata of a node pool

spec

Yes

UpgradeNodePoolSpec object

Definition

Parameters in the request for synchronizing nodes in a node pool

Constraints

N/A
Table 4 NodePoolMetadata

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

Node pool name

Constraints

You are not allowed to create node pools named DefaultPool.

Range

Enter 1 to 63 characters starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed.

Default Value

N/A

uid

No

String

Details:

UID of a node pool

Constraints:

The value is automatically generated after the object is created. A user-defined value will not take effect.

Options:

N/A

Default value:

N/A

annotations

No

Map<String,String>

Details:

Annotations of a node pool in key-value pairs

Constraints:

This parameter is used only for query and cannot be input through a request. Entered data of this parameter is invalid.

updateTimestamp

No

String

Details:

Time when a node pool was updated

Constraints:

The value is automatically recorded when a node pool is updated and cannot be specified.

Options:

N/A

Default value:

N/A

creationTimestamp

No

String

Details:

Time when a node pool was created

Constraints:

The value is automatically recorded when a node pool is created and cannot be specified.

Options:

N/A

Default value:

N/A

resourceVersion

No

Integer

Definition

Timestamp of the last update time of a node pool

Constraints

The value is automatically recorded when a node pool is created and cannot be specified.

Range

N/A

Default Value

N/A
Table 5 UpgradeNodePoolSpec

Parameter

Mandatory

Type

Description

maxUnavailable

Yes

Integer

Definition

The maximum number of nodes to be synchronized at a time. It also specifies the maximum number of unavailable nodes during node upgrades. When a node is reset for synchronization, the node is unavailable. Set this parameter to a proper value to prevent pod scheduling failures caused by a large number of unavailable nodes in the cluster.

Constraints

N/A

Range

1 to 20

Default Value

N/A

nodeIDs

No

Array of strings

Definition

List of node IDs selected in the node pool to be synchronized. For details about how to obtain the IDs, see How to Obtain Parameters in the API URI.

Constraints

N/A

Range

N/A

Default Value

N/A

nodePoolID

Yes

String

Definition

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

Constraints

N/A

Range

N/A

Default Value

N/A

nodeTemplate

No

UpgradeNodePoolSpecNodeTemplate object

Definition

Template parameters for synchronizing a node pool

Constraints

N/A

Range

N/A

Default Value

N/A
Table 6 UpgradeNodePoolSpecNodeTemplate

Parameter

Mandatory

Type

Description

lifeCycle

Yes

NodeLifecycleConfig object

Definition:

Customized node lifecycle configuration

Constraints:

This parameter is valid only when nodePoolID is set to DefaultPool. During the synchronization of a custom node pool, the node pool configuration prevails.

login

Yes

Login object

Details:

Node login mode. Either a key pair or password must be used for login.

Constraints:

None

volumeConfig

No

VolumeConfig object

Definition:

Disk configuration in the node pool synchronization scenario

Constraints:

N/A
Table 7 NodeLifecycleConfig

Parameter

Mandatory

Type

Description

preInstall

No

String

Definition

Pre-installation script.

Constraints

The characters of both the pre-installation and post-installation scripts are centrally calculated, and the total number of characters after transcoding cannot exceed 10,240.

The input value must be encoded using Base64. The method is as follows:

echo -n "*<content-to-be-encoded>*" | base64

Range

N/A

Default Value

N/A

postInstall

No

String

Definition

Post-installation script.

Constraints

The characters of both the pre-installation and post-installation scripts are centrally calculated, and the total number of characters after transcoding cannot exceed 10,240.

The input value must be encoded using Base64. The method is as follows:

echo -n "*<content-to-be-encoded>*" | base64

Range

N/A

Default Value

N/A

waitPostInstallFinish

No

Boolean

Definition

Whether pods can be scheduled onto a node before the post-installation script has completed execution during operations such as node reset, management, and batch reset. If the node belongs to a node pool, the node pool settings apply. If this parameter is not specified or is set to false, pods can be scheduled to an available node after the Kubernetes node is ready. If this parameter is set to true, pods can be scheduled to an available node only after the Kubernetes node is ready and the post-installation script has been executed.

Constraints

N/A

Range

  • false: Pods can be scheduled to an available node after the Kubernetes node is ready.

  • true: Pods can be scheduled to an available node only after the Kubernetes node is ready and the post-installation script has been executed.

Default Value

false
Table 8 Login

Parameter

Mandatory

Type

Description

sshKey

No

String

Details:

Name of the key pair used for login

Constraints:

None

Options:

N/A

Default value:

N/A

userPassword

No

UserPassword object

Definition:

Password used for node login

Constraints:

N/A

Range:

N/A

Default Value:

N/A

removeUserPassword

No

Boolean

Definition

Whether to remove the password login setting of a node pool during the node pool update

Constraints

This parameter is supported only during node pool updates. If it is set to true, no user password can be specified.

Range

N/A

Default Value

false

removeSSHKey

No

Boolean

Definition

Whether to remove the key pair login setting of a node pool during the node pool update

Constraints

This parameter is supported only during node pool updates. If it is set to true, no SSH key can be specified.

Range

N/A

Default Value

false
Table 9 UserPassword

Parameter

Mandatory

Type

Description

username

No

String

Details:

Login account. The default value is root.

Constraints:

None

Options:

N/A

Default value:

root

password

Yes

String

Details:

Login password. If a username and password are used when a node is created, this field is shielded in the response body.

Constraints:

The password field must be salted during node creation. For details, see Adding a Salt in the password Field When Creating a Node.

Options:

A password must:

  • Contain 8 to 26 characters.

  • Contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?

  • Not contain the username or the username spelled backwards.

Default value:

N/A
Table 10 VolumeConfig

Parameter

Mandatory

Type

Description

volumeResetPolicy

No

String

Definition:

Disk data retention policy when a node is reset.

If this parameter is not present or left blank, reset_managed_volumes is used by default to clear data disks managed by CCE.

Constraints:

When a custom volume is retained, the advanced settings for mounting it to a specified directory or using it as a persistent volume cannot be modified.

Range:

  • reset_managed_volumes: Clear data disks managed by CCE.

  • retain_custom_volumes: retains user-defined volumes (including volumes mounted to specified directories and volumes used as local persistent volumes). The cluster version must be v1.29.15-r90, v1.30.14-r90, v1.31.14-r50, v1.32.13-r20, v1.33.12-r0, v1.34.8-r0, v1.35.5-r0, v1.36.1-r10, or later.

Default Value:

reset_managed_volumes

Response Parameters

Status code: 200

Table 11 Response body parameters

Parameter

Type

Description

jobid

String

Definition:

Specifies the job ID returned after the job is successfully delivered. You can use this ID to query the job execution status.

Range:

N/A

Example Requests

  • Synchronize the node configurations in an on-premises node pool.

    {
  "spec" : {
    "maxUnavailable" : 1,
    "nodeIDs" : [ "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "bbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbb" ],
    "nodePoolID" : "cccccccc-cccc-cccc-cccc-cccccccccccc"
  }
}

  • Synchronize the node configurations in the default node pool.

    {
  "spec" : {
    "maxUnavailable" : 1,
    "nodeIDs" : [ "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "bbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbb" ],
    "nodePoolID" : "DefaultPool",
    "nodeTemplate" : {
      "lifeCycle" : {
        "preInstall" : "ZWNobyAx",
        "postInstall" : "ZWNobyAx"
      },
      "login" : {
        "userPassword" : {
          "password" : "xxxxx",
          "username" : "root"
        }
      }
    }
  }
}

Example Responses

Status code: 200

{
  "jobid" : "7b9a1695-ab29-11ef-a522-0255ac101231"
}

Status Codes

Status Code

Description

200

The job information is obtained.

Error Codes

See Error Codes.

Parent topic: Node Pool Management