Help Center/ Cloud Container Engine/ API Reference (Ally Region)/ APIs/ Node Management/ Migrating a Node In Place

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

Migrating a Node In Place

Function

This API is used to migrate a node in place from a specified cluster to another cluster.

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

Constraints

The cluster version must be v1.30.14-r100, v1.31.14-r60, v1.32.13-r30, v1.33.12-r10, v1.34.8-r10, v1.35.5-r10, or v1.36.2-r0 or later.
The version of the CCE Container Storage (Everest) add-on must be 2.5.80 or later.
Nodes can be migrated in place only between clusters of the same type within the same project and under the same tenant. Both the cluster type and node type must be identical.
The cluster versions, including minor versions, must be identical for in-place node migration.
A node cannot be migrated in place between CCE Turbo and CCE standard clusters. The network types of the clusters must be identical.
A node cannot be migrated in place between DeC and non-DeC clusters.
IPv6 clusters do not support in-place node migration.
Only nodes in the default node pool can be migrated in place. Nodes in custom node pools cannot be migrated in place.
In-place migration of a hypernode is not supported.
In-place migration of a node in a distributed cluster is not supported.
Nodes in clusters in different subnets of the same VPC cannot be migrated in place.
A node to be migrated in place cannot be configured with additional network interfaces. It can only have one primary network interface.
In-place migration of physical machine nodes (BMSs and BMSs in the shared resource pool) depends on whether the related models support hot VPC network switchover. For details, contact the corresponding service personnel.
A node to be migrated in place must be in the running state.
During in-place migration, container resources on the node are forcibly cleaned up. It is advised to drain the node and migrate workloads to other nodes before performing the migration. Migration should be performed during off-peak hours to minimize service impact.
During in-place migration, data of the container runtime, kubelet, persistent storage volumes, and ephemeral storage volumes configured on the node will be cleaned up. If there is any data that needs to be retained, back it up to another node or storage system in advance.
Ensure that the CCE Container Storage (Everest) add-on is running properly and the pod of everest-csi-controller is not on the node to be migrated in place.
In-place node migration does not clean up OS logs or user component information. You need to manually clean up them.
If the system disk is used for system component storage, the time required for the node migration increases significantly as the amount of data increases.
If multiple storage disks are attached to the node, the time required for the node migration increases as the number of disks increases.
After the cluster where the pay-per-use node to be migrated in place is deleted or the node itself is deleted, the corresponding ECS or BMS resources will also be deleted. If you want to keep the resources, remove the node from the cluster in advance.
If a node uses Docker as the container runtime, the in-place migration takes longer than when containerd is used. Therefore, containerd is preferred as the container runtime.
During the in-place node migration, ensure that the disk directory to be unmounted on the node is not manually occupied. Otherwise, the migration will fail. The directories include /mnt/paas, /var/lib/docker, /var/lib/containerd, and the directory to which the data disk to be cleaned up is mounted.
After the in-place node migration, the labels and taints configured for the node will not be inherited. You need to reconfigure them after the node is migrated to a new cluster.
Unexpected risks may occur during the operation. Back up data beforehand.
During the operation, the original cluster node is in the deleting state, and the destination cluster node is in the installing state.

Calling Method

For details, see Calling APIs.

URI

POST /api/v3/projects/{project_id}/clusters/{cluster_id}/nodes/operation/in-place-migrateto/{target_cluster_id}

**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
target_cluster_id	Yes	String	Definition Cluster ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI. Constraints N/A Range N/A 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
apiVersion	No	String	Definition: API version Constraints: The value is fixed and cannot be changed. Range: N/A Default Value: v3
kind	No	String	Definition: API type Constraints: The value is fixed and cannot be changed. Range: N/A Default Value: InPlaceMigrateNodesTask
spec	Yes	InPlaceMigratetoNodesSpec object	Definition: Configuration information Constraints: N/A
status	No	TaskStatus object	Definition: Task status Constraints: N/A

**Table 4** InPlaceMigratetoNodesSpec
Parameter	Mandatory	Type	Description
nodes	Yes	Array of InplaceMigrateNodeItem objects	Definition: List of nodes to be migrated in place Constraints: N/A
dataDiskCleanUpOption	No	DataDiskCleanUpOption object	Definition: Disk processing parameters during in-place node migration Constraints: N/A
extendParam	No	InPlaceMigrateNodeExtendParam object	Definition: Extended parameters for in-place node migration Constraints: N/A

**Table 5** InplaceMigrateNodeItem
Parameter	Mandatory	Type	Description
uid	Yes	String	Definition: Node ID. For details about how to obtain the node ID, see How to Obtain Parameters in the API URI. Constraints: N/A Range: N/A Default Value: N/A

**Table 6** DataDiskCleanUpOption
Parameter	Mandatory	Type	Description
enable	No	Boolean	Definition: Whether to clean up data disks except the system disk on a node during in-place node migration Constraints: N/A Range: false: Data disks except the system disk on the node are not cleaned up during in-place node migration. true: Data disks except the system disk on the node are cleaned up during in-place node migration. Default Value: false
onFailure	No	String	Definition: The processing policy when the data disks of a node fail to be cleaned up during in-place node migration Constraints: N/A Range: ignore: If the data disks fail to be cleaned up, the system ignores the error and continues the operation. abort: If the data disks fail to be cleaned up, the system stops the operation immediately and reports an error. Default Value: ignore

**Table 7** InPlaceMigrateNodeExtendParam
Parameter	Mandatory	Type	Description
alpha.cce/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
alpha.cce/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 to a node before the post-installation script has completed execution during in-place node migration. 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** TaskStatus
Parameter	Mandatory	Type	Description
jobID	No	String	Definition Job ID, which is used by the caller to query the job progress. For details about how to obtain the value, see How to Obtain Parameters in the API URI. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 9** Response body parameters
Parameter	Type	Description
apiVersion	String	Definition: API version Range: N/A v3
kind	String	Definition: API type Range: N/A
spec	InPlaceMigratetoNodesSpec object	Definition: Configuration information
status	TaskStatus object	Definition: Task status

**Table 10** InPlaceMigratetoNodesSpec
Parameter	Type	Description
nodes	Array of InplaceMigrateNodeItem objects	Definition: List of nodes to be migrated in place
dataDiskCleanUpOption	DataDiskCleanUpOption object	Definition: Disk processing parameters during in-place node migration
extendParam	InPlaceMigrateNodeExtendParam object	Definition: Extended parameters for in-place node migration

**Table 11** InplaceMigrateNodeItem
Parameter	Type	Description
uid	String	Definition: Node ID. For details about how to obtain the node ID, see How to Obtain Parameters in the API URI. Range: N/A

**Table 12** DataDiskCleanUpOption
Parameter	Type	Description
enable	Boolean	Definition: Whether to clean up data disks except the system disk on a node during in-place node migration Range: false: Data disks except the system disk on the node are not cleaned up during in-place node migration. true: Data disks except the system disk on the node are cleaned up during in-place node migration. false
onFailure	String	Definition: The processing policy when the data disks of a node fail to be cleaned up during in-place node migration Range: ignore: If the data disks fail to be cleaned up, the system ignores the error and continues the operation. abort: If the data disks fail to be cleaned up, the system stops the operation immediately and reports an error. ignore

**Table 13** InPlaceMigrateNodeExtendParam
Parameter	Type	Description
alpha.cce/preInstall	String	Definition: Pre-installation script Range: N/A
alpha.cce/postInstall	String	Definition: Post-installation script Range: N/A
waitPostInstallFinish	Boolean	Definition: Whether pods can be scheduled to a node before the post-installation script has completed execution during in-place node migration. 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. 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. false

**Table 14** TaskStatus
Parameter	Type	Description
jobID	String	Definition Job ID, which is used by the caller to query the job progress. For details about how to obtain the value, see How to Obtain Parameters in the API URI. Range N/A

Example Requests

Migrate a node in place to another cluster.

POST /api/v3/projects/{project_id}/clusters/{cluster_id}/nodes/operation/in-place-migrateto/{target_cluster_id}

{
  "spec" : {
    "dataDiskCleanUpOption" : {
      "enable" : true,
      "onFailure" : "ignore"
    },
    "nodes" : [ {
      "uid" : "d30a28c2-8402-11f1-be5d-0255ac1000f3"
    } ],
    "extendParam" : {
      "waitPostInstallFinish" : false,
      "alpha.cce/preInstall" : "",
      "alpha.cce/postInstall" : ""
    }
  }
}

Example Responses

Status code: 200

{
  "kind" : "InPlaceMigrateNodesTask",
  "apiVersion" : "v3",
  "spec" : {
    "nodes" : [ {
      "uid" : "d30a28c2-8402-11f1-be5d-0255ac1000f3"
    } ],
    "dataDiskCleanUpOption" : {
      "enable" : true,
      "onFailure" : "ignore"
    },
    "extendParam" : { }
  },
  "status" : {
    "jobID" : "3f01b88d-8403-11f1-be5d-0255ac1000f3"
  }
}

Status Codes

Status Code	Description
200	The job for migrating the node in place from a specified cluster to another cluster has been issued.

Error Codes

See Error Codes.

Parent topic: Node Management

Previous topic: Migrating a Node

Next topic: Migrating a Node to a Custom Node Pool