Add an existing ECS instance to a node pool as an ACK worker node - Container Service for Kubernetes

You can add existing Elastic Compute Service (ECS) instances to a cluster as worker nodes or add removed worker nodes back to a node pool. This lets you quickly reuse computing resources without interrupting existing services in the cluster.

ACK provides automatic and manual methods to add nodes. The billing method and instance type of an instance remain unchanged after the instance is added.

Item

Automatic addition

Manual addition

OS reset

Resets and initializes the instance's operating system based on the current node pool configuration.

The original system disk is released, and its data is lost.
Manual snapshots of the system disk are retained, but the retention of automatic snapshots depends on whether the Release Automatic Snapshots With Disk option is configured.
Log on to the ECS console and see Set automatic snapshots to be released with disks to configure this setting.
The original data disks are not released. The data on them is not affected, but their disk IDs change.

Keeps the instance's original operating system, which provides more flexibility.

Scenarios

Use this method when you want the instance to match the node pool configuration for standardized management.

Use this method when you need to keep the instance's existing operating system or specific configurations.

Limits

Before you start, make sure that your environment and instance meet the following conditions.

Category	Limit	Description
Instance and node pool	Cluster node quota	The total number of nodes in the cluster cannot exceed the quota. To increase the quota, go to Quota Center. The default node quota for an ACK managed cluster of the Basic Edition is 10.
	Instance ownership	The instance and the cluster must be under the same account, in the same region, and within the same VPC. If not, migrate the instance or create a new instance or cluster that meets these requirements. You cannot add an ECS instance from the other end of a VPC peering connection.
	Cluster ownership	You cannot add an instance that already belongs to another ACK cluster. First, remove the node from the original cluster, and then add it to the new cluster.
	Auto Scaling group (ESS) ownership	You cannot add an instance that already belongs to another scaling group. Manually remove the instance from the scaling group and retry.
	Node pool type	You cannot add existing nodes to an Auto Mode node pool. You cannot add existing nodes to a node pool that has Auto Scaling enabled. After you add an existing node to a node pool, you cannot enable Auto Scaling for that node pool.
	Operating system	The operating system cannot have Swap enabled. When you add a node manually, you cannot add instances that run Windows or ContainerOS.
	Instance type	The instance must not be of an unsupported ECS instance type. For ECS Bare Metal GPU-accelerated instances (instance families ebmgn7 and ebmgn7e), automatic multi-instance GPU (MIG) cleanup is not supported. When you add this type of instance, the existing MIG settings are reset. The reset process may take a long time and cause the automatic addition to fail. For troubleshooting, see What do I do if adding a bare metal instance node fails?.
Network	API Server access	The instance's IP address must be in the API Server access whitelist. Otherwise, the instance cannot communicate with the control plane. For more information, see Configure access control policies for the API Server.
	Security group	Type consistency: The security group type of the instance (basic or advanced security group) must be the same as the node pool's security group type. Rule compatibility: The instance's security group must allow access to the API Server's internal network address and port 6443. Its rules must not conflict with the security group rules of the cluster and node pool. You can view the API Server's internal network address on the Basic Information tab of the Cluster Information page. Quota limit: The number of security groups an instance can join must not exceed the security group quota. To change the instance's security group type or add the instance to the node pool's security group in advance, see Associate a security group with an instance (primary ENI). To increase the security group quota, see View or increase Elastic Compute Service quotas.
	Terway - Maximum pods	The maximum number of pods that the instance supports must meet the following conditions: The maximum number of pods supported in different ENI modes depends on the maximum number of ENIs the instance supports. For the calculation method, see How to calculate the pod quota for a node. Shared ENI mode: The maximum number of supported pods must be greater than 10. Exclusive ENI mode: The maximum number of supported pods must be greater than 5. If these conditions are not met, upgrade or downgrade the node resources or purchase a new instance.
	Terway - vSwitch configuration	If the instance and the node pool are in different zones, you must update the Terway vSwitch configuration. Otherwise, Terway allocates pod IPs from the vSwitch of the node's primary ENI, which may cause pod IP allocation to fail. For more information, see Modify the vSwitch for pods.
	Terway - ENI	When you add an instance, its attached ENIs are retained. Pod IPs are allocated from the vSwitches associated with these ENIs. Make sure the instance has only one primary network interface card (ENI). If a pod IP does not belong to a configured vSwitch, remove the node from the cluster, delete all secondary ENIs, and then add the node back to the cluster.
	Terway - Worker RAM role	The instance to be added must be attached to the node pool's Worker RAM role. This prevents permission issues that could lead to incorrect calculation of the maximum available pods (MaxPod). On the Node Pools page, click the node pool name and view the Worker RAM role on the Overview tab. To grant the RAM role, see Grant a RAM role to an ECS instance.
	Terway - IPv6 dual-stack	If the cluster has IPv6 dual-stack enabled, you must assign an IPv6 address to the instance's primary ENI. For more information, see IPv6 communication.
	Flannel	The number of custom route entries in the system route table of the cluster's VPC cannot exceed the route table quota. To adjust the quota, go to Quota Center.

Precautions

Data backup: Before you start, create snapshots to back up the system disk and data disks of the instance to prevent data loss.
To ensure that you have a sufficient snapshot quota, delete any unneeded manual and automatic snapshots before you create new ones.
Instance release and billing: If you add an instance to a node pool that does not automatically manage the number of nodes, the instance is not automatically released when you delete the cluster or node pool. You must remove the nodes manually. Monitor the ECS billing status to avoid incurring extra charges.

Procedure

Time required: The node addition process involves replacing the system disk (for automatic addition only) and initializing the node. This process takes about 5 minutes. The actual time may vary based on factors such as network conditions and operating system size.

Adding an existing node does not affect existing nodes and applications in the cluster. To avoid compatibility issues, do not initialize an ECS instance that is already running services as a worker node.

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, find the cluster to manage and click its name. In the left navigation pane, choose Nodes > Node Pools.
On the Node Pools page, click in the Actions column of the target node pool, and then click Add Existing Node.
If the destination ECS instance is not in the list of cloud servers, it does not meet the conditions to be added to the cluster. You can select Show Unavailable Instances to view the unavailable ECS instances and the reasons why they are unavailable. For more information about the reasons, see the Limits and Precautions sections in this topic.
Read the on-screen precautions carefully, and then select a method to add the node.

Add a node manually

This method requires you to obtain an installation command and run it on the instance. You can add only one ECS instance at a time.

Set Method to Manual, select the ECS instance to add from the list of existing cloud servers, and then click Next Step.

On the Specify Instance Information page, confirm the cluster and instance information as prompted. Configure the data disk and instance name, and then click Next Step. Follow the on-screen instructions to complete the process.

Configuration item	Description
Data Disk	Specifies whether to store container and image data on a data disk. This separates the system disk from data disks and improves stability. If the ECS instance already has a data disk attached, and the file system of the last data disk is not initialized, ACK automatically formats the last data disk to the ext4 file system. This disk is then used exclusively for /var/lib/containerd or /var/lib/docker (the default data directory for the container runtime) and /var/lib/kubelet (the default data directory for the kubelet component). Important The original data on the formatted data disk will be lost. Create a snapshot to back up the data first. If you want to store containers and images on a data disk, only the ext4 and xfs file systems are supported. If the ECS instance does not have a data disk attached, ACK will not automatically attach a new data disk, regardless of whether you select this option.
Retain Instance Name	Enabled: Uses the instance name as the node name. Disabled: ACK renames the node according to the rule specified for custom node names.

On the Complete page, copy the node access command that ACK automatically generates for later use, and then click Done.
Log on to the ECS console. In the navigation pane on the left, click Instances & Images > Instances. Select the region where the cluster is located, and then select the destination instance.
Click Connect for the destination instance. Select a remote connection method and connect to the ECS instance.
Follow the on-screen instructions to run the script that you copied in step 3. This automatically configures the instance and adds it to the cluster.
After the script runs successfully, a message is displayed to indicate that the node is added. Wait for the node to initialize. The status of the node changes to Ready in the node list after the node is initialized.

Add a node automatically

You can add an instance automatically from the console.

Set Method to Auto, select the ECS instances that you want to add from the list of existing cloud servers, and then click Next Step.

On the Specify Instance Information page, confirm the cluster and instance information as prompted. Configure the data disk and instance name, and then click Next Step.

Configuration item	Description
Data Disk	Specifies whether to store container and image data on a data disk. This separates the system disk from data disks and improves stability. If the ECS instance already has a data disk attached, and the file system of the last data disk is not initialized, ACK automatically formats the last data disk to the ext4 file system. This disk is then used exclusively for /var/lib/containerd or /var/lib/docker (the default data directory for the container runtime) and /var/lib/kubelet (the default data directory for the kubelet component). Important The original data on the formatted data disk will be lost. Create a snapshot to back up the data first. If you want to store containers and images on a data disk, only the ext4 and xfs file systems are supported. If the ECS instance does not have a data disk attached, ACK will not automatically attach a new data disk, regardless of whether you select this option.
Logon method and password	If the Logon Type for the node pool is set to Password, reset the instance password.
Retain Instance Name	Enabled: Uses the instance name as the node name. Disabled: ACK renames the node according to the rule specified for custom node names.

In the dialog box that appears, read the precautions carefully, and then click Confirm.
After the instance is added, wait for the node to initialize. The status of the node changes to Ready in the node list after the node is initialized.

FAQ

Does adding existing nodes affect existing services in the cluster?

No. Adding an existing node, whether manually or automatically, does not affect existing services in the cluster.

After an ECS instance is added to a cluster, will upgrading or downgrading the ECS instance affect cluster services?

Upgrading or downgrading an ECS instance usually involves actions such as changing the instance type, changing the billing method for public bandwidth, modifying the public bandwidth, or changing the billing method for data disks. For more information, see Overview of instance configuration changes. The impact of these operations on an ECS instance varies.

Operations that do not require a restart: The impact on your services depends on your specific business requirements.
Operations that require an ECS instance restart: Operations such as upgrading or downgrading the instance type cause disruptive changes to your services. Before you perform such operations (for example, upgrade or downgrade node resources), assess your current workload. You can scale out redundant nodes to handle application pods. Then, drain the node that you want to change and remove it from the scaling group and the ACK cluster. For more information, see Remove a node.
After the upgrade or downgrade is complete, follow the instructions in this topic to add the node back to the cluster.

Can I add existing nodes of different instance types to an ACK cluster?

Yes. ACK lets you manage nodes of multiple instance types in the same node pool. This helps prevent node scale-out failures that are caused by unavailable or out-of-stock instance types. Before you add an ECS instance, make sure that the instance type of the ECS instance is included in the list of instance types that are supported by the node pool. Follow these steps.

Edit or create a node pool and configure the required node specifications. For more information, see Create and manage a node pool.
Remove and drain the target node. Do not release the ECS instance when you remove the node. For more information, see Remove a node.
Follow the instructions in the Limits and Procedure sections of this topic to add ECS instances of different specifications to the node pool.

How do I move a node across ACK clusters?

ACK does not allow you to directly move nodes across clusters. However, you can move a node by removing it from the source cluster and then adding it to the destination cluster. Follow these steps.

Remove and drain the target node from the source cluster. Do not release the ECS instance when you remove the node. For more information, see Remove a node.
Follow the instructions in the Limits and Procedure sections of this topic to add the target ECS instance to a node pool in the destination cluster.

Can an ECS instance with an ACK EOL operating system be added to a node pool?

Manual addition: You can manually add an existing instance that runs an unsupported operating system to a node pool. However, make sure that the OS version of the instance is compatible with the current cluster version. For more information, see OS images.
For example, CentOS 7 and Alibaba Cloud Linux 2 are supported only in clusters that run Kubernetes 1.30 or earlier.
Automatic addition: Yes. ACK uses the operating system image specified in the node pool configuration to initialize the instance.

When you add an existing node, is its custom User Data overwritten by the User Data of the node pool?

Whether the User Data of the original instance is overwritten depends on the addition method.

Automatic addition: ACK initializes the system disk. The User Data of the original instance is overwritten by the User Data configuration of the node pool.
Manual addition: The User Data of the original instance is not overwritten. After the instance is added to the node pool, the instance continues to use its original User Data.

What do I do if a timeout error occurs after I add an existing node?

Check whether the node can connect to the network of the API Server Classic Load Balancer (CLB) instance. First, check whether the security group meets the requirements. For more information about the security group limits for adding an existing node, see the Limits section in this topic. For more information about how to troubleshoot other network connectivity issues, see Network management FAQ.

Does the desired number of nodes in the node pool change automatically after I add an existing node?

After you add an existing node, the desired number of nodes automatically increases by the number of nodes added. For example, if the Expected Nodes for a node pool is 5 and you add one ECS instance to the node pool, the Expected Nodes for the node pool automatically changes to 6.

References

In addition to the console, you can add an ECS instance to an ACK cluster by calling the OpenAPI or using the command-line interface (CLI). For more information, see Query scripts for adding existing nodes to a cluster node pool and Add an existing ECS instance.
Older clusters that were created before the node pool feature was available may have stray nodes. Stray nodes are cluster nodes that do not belong to any node pool. You can manage these nodes in a node pool. For more information, see Migrate stray nodes to a node pool.
If a node, pod, or other component is abnormal, see Troubleshoot abnormal nodes, Pod troubleshooting, and Node and node pool FAQ to troubleshoot the issue.