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

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

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

Item

Automatic addition

Manual addition

Operating system 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 will be retained, while the retention of automatic snapshots depends on whether the Release Automatic Snapshots With Disk option is configured.
Log on to the ECS console. For more information, see Set automatic snapshots to be released with disks.
The original data disks are not released, and their data is unaffected. However, the disk IDs will change.

Retains the instance's original operating system for greater flexibility.

Scenarios

Use this method to keep the instance configuration consistent with the node pool for standardized management.

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

Limits

Before you begin, 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 limit. To increase the limit, go to Quota Center. The default node quota for an ACK managed cluster of 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. Otherwise, migrate the instance or create a new instance or cluster that meets the requirements. Adding ECS instances from the other end of a VPC peering connection is not supported.
	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 (ESS) group ownership	You cannot add an instance that already belongs to another scaling group. You must manually remove it from the scaling group and then 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. A node pool to which existing nodes have been added does not support enabling auto scaling later.
	Operating system	The operating system does not support enabling swap. When adding manually, you cannot add instances with Windows or ContainerOS operating systems.
	Instance type	ECS Bare Metal GPU-accelerated instances (ECS instance family ebmgn7, ebmgn7e) do not support automatic MIG cleanup. When you add this type of instance, the existing MIG settings are reset. This reset may take a long time and cause the automatic node addition to fail. For troubleshooting, see What do I do if adding a bare metal instance node fails?.
Network	API Server access	The instance IP address must be in the API Server access whitelist. Otherwise, it 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 that of the node pool. Rule compatibility: The instance security group must allow access to the internal IP address and port 6443 of the API Server. The rules must not conflict with the security group rules of the cluster and node pool. You can view the internal IP address of the API Server on the Basic Information tab of the Cluster Information page. Quota limit: The number of security groups an instance can join cannot 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 supported by the instance must meet the following conditions: The maximum number of pods supported in different Elastic Network Interface (ENI) modes depends on the maximum number of ENIs the instance supports. For the calculation method, see Node pod quota calculation. 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	When the instance and the node pool are in different zones, you must update the Terway vSwitch configuration. Otherwise, Terway will allocate pod IPs from the vSwitch of the node's primary ENI, which may cause pod IP allocation to fail. For specific operations, see Modify pod vSwitches.
	Terway - ENI	When adding the instance, its attached ENIs are retained. Pod IPs will be allocated from the vSwitches associated with these ENIs. Make sure the instance has only one primary network interface card. If any pod IP does not belong to a configured vSwitch, remove the node from the cluster, delete all secondary ENIs except the primary one, and then rejoin 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) for the node. On the Node Pools page, click the node pool name to view its worker RAM role on the Basic Information tab. For more information, see Grant a RAM role to an ECS instance to complete the authorization.
	Terway - IPv6 dual-stack	When the cluster has IPv6 dual-stack enabled, you must assign an IPv6 address to the instance's primary network interface card. 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 begin, create snapshots to back up the instance's system disk and data disks to prevent data loss.
To ensure that you have a sufficient snapshot quota, we recommend that you delete unnecessary manual and automatic snapshots in advance so that you can successfully create new snapshots.
Instance release and billing: If an expected number of nodes is not configured for a node pool, instances added to that node pool are not released when the cluster or node pool is deleted. You must manually remove the nodes. Monitor the ECS billing status to avoid extra charges.

Procedure

Time required: The node addition process involves system disk replacement (for automatic addition only) and node initialization. This process takes about 5 minutes. The actual time may vary depending on network conditions, operating system size, and other factors.

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 has running services as a worker node.

Log on to the ACK console. In the navigation pane on the left, click Clusters.
On the Clusters page, find the cluster to manage and click its name. In the left-side navigation pane, choose Nodes > Node Pools.
On the Node Pool page, click in the Actions column of the target node pool, and then click Add Existing Nodes.
If the target ECS instance is not in the list of servers, the instance does not meet the requirements for being added to the cluster. You can select Show Unavailable Instances to view unavailable ECS instances and the reasons why they are unavailable. For more information, see the Limits and Precautions sections above.
Carefully read the notes on the page, and then select a method for adding the node.

Manually add nodes

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

Set Add Method to Manual. In the list of existing servers, select the ECS instance to add, and then click Next.

On the Configure Instance page, confirm the cluster and instance information. Then, configure the data disk and instance name, and click Next.

Parameter	Description
Mount Data Disk	Specifies whether to store container and image data on a data disk. This separates the system disk from the data disk to improve stability. If the ECS instance 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 Data on the formatted data disk will be lost. Create a snapshot to back up the data beforehand. 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 one, regardless of whether this option is selected.
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 Add Complete page, copy the node access command that is automatically generated by ACK, 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 target instance.
Click Remote Connection for the target instance. Select a remote connection method to access the ECS remote connection interface.
Follow the on-screen instructions to enter and run the script that you copied in step 3. This script automatically configures the instance and adds it to the cluster.
After the script runs, a success message is displayed. In the node list, wait for the node to complete initialization. Its status changes to Ready when the process is complete.

Automatically add nodes

You can automatically add an instance from the console interface.

Set Add Method to Automatic. In the list of existing servers, select the desired ECS server, and then click Next.

On the Configure Instance page, confirm the cluster and instance information. Then, configure the data disk and instance name, and click Next.

Parameter	Description
Mount Data Disk	Specifies whether to store container and image data on a data disk. This separates the system disk from the data disk to improve stability. If the ECS instance 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 Data on the formatted data disk will be lost. Create a snapshot to back up the data beforehand. 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 one, regardless of whether this option is selected.
Logon Method and Password	When the Logon Method for the node pool is set to Set Password, you must reconfigure 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, carefully read the notes, and then click OK.
After the node is added, wait for it to complete initialization. Its status changes to Ready in the node list when the process is complete.

FAQ

Will adding existing nodes affect existing workloads in the cluster?

No, it will not. 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?

Yes, it might. Upgrading or downgrading an ECS instance usually involves actions such as modifying 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 upgrade or downgrade. The impact of different upgrade or downgrade methods on the ECS instance varies.

Operations that do not require a restart: The impact on services depends on your specific business requirements.
Operations that require an ECS instance restart: Operations such as upgrading or downgrading the instance type disrupt your services. Before you perform such operations (Upgrade or downgrade node resources), we recommend that you assess your current workload, scale out redundant nodes to handle application pods, and then drain the node that you plan to upgrade or downgrade and remove it from the scaling group and the ACK cluster. For more information about the operations, see Remove a node.
After the upgrade or downgrade is complete, add the node back to the cluster as described in this topic.

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

Yes, you can. ACK lets you manage nodes of multiple instance types in the same node pool. This prevents node scale-out failures in the node pool that occur because instance types are unavailable or the inventory is insufficient. Before you add an ECS instance, make sure its instance type is included in the node pool's list of instance types. 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.
Drain and remove the target node. Do not release the ECS instance at the same time. For more information, see Remove a node.
Add the ECS instances of different instance types to the node pool. For more information, see the Limits and Procedure sections in this topic.

How do I move a node across ACK clusters?

ACK does not support moving nodes directly between clusters. However, you can move a node by removing it from the source cluster and then adding it as an existing node to the destination cluster. Follow these steps:

Drain and remove the target node. Do not release the ECS instance at the same time. For more information, see Remove a node.
Add the target ECS instance to the new node pool. For more information, see the Limits and Procedure sections in this topic.

Can an ECS instance be added to a node pool if its operating system has reached end of life (EOL) in ACK?

Manual addition: You can manually add an existing instance running an unsupported operating system to a node pool. However, you must ensure that the instance's operating system version is compatible with the current cluster version. For more information, see Operating systems.
For example, CentOS 7 and Alibaba Cloud Linux 2 are only supported in clusters of version 1.30 and earlier.
Automatic addition: Yes, it can. ACK initializes the instance using the operating system image specified in the node pool configuration.

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

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

Automatic addition: ACK initializes the system disk, which overwrites the instance's original User Data with the default User Data configuration from the node pool.
Manual addition: The original instance's User Data is not overwritten. After the node joins the node pool, it continues to use its original User Data.

What should I do if I get a timeout error after adding an existing node?

Check whether the node can connect to the API Server over the CLB network. First, check whether the security group meets the requirements. For more information about security group limits when you add an existing node, see the Limits section above. For other network connectivity issues, see Network management FAQ.

Does the expected number of nodes in a node pool change automatically after an existing node is added?

Yes, it does. After an existing node is added, the expected number of nodes automatically increases by the number of nodes that were added. For example, if the Expected Number Of Nodes for a node pool is set to 5 and you add one ECS instance to the node pool, the Expected Number Of Nodes for the node pool automatically changes to 6.

References

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