Add existing ECS instances to a node pool as ACK worker nodes - Container Service for Kubernetes

Add existing ECS instances as worker nodes or re-add removed nodes to reuse compute resources without disrupting workloads.

ACK supports auto and manual modes for adding nodes. Billing method and instance type stay unchanged after you add an instance.

Item

Auto mode

Manual mode

OS reset

Resets and initializes the OS based on the node pool configuration.

The system disk is released and its data is lost.
Manual snapshots of the system disk are retained. The retention of automatic snapshots depends on whether the Delete Automatic Snapshots While Releasing Disk setting is enabled.

To configure this setting, log on to the ECS console and see Set the 'Delete Automatic Snapshots While Releasing Disk' attribute.
The data disk is retained and its data is preserved, but the disk ID changes.

Preserves the original OS for greater flexibility.

Use cases

You want the instance configuration to match the node pool for standardized management.

You need to preserve the instance OS or specific configurations.

Limitations

Ensure your environment and instances meet these requirements.

Category	Item	Description
Instance and node pool	Cluster node quota	Cluster nodes cannot exceed the quota. To increase the quota, go to Quota Center. The default node quota for an ACK Basic cluster is 10.
	Instance ownership	The instance and cluster must be in the same Alibaba Cloud account, region, and VPC. Otherwise, migrate the instance or create an instance or cluster that meets the requirements. You cannot add an ECS instance from the other end of a VPC peering connection.
	Cluster ownership	You cannot add an instance that belongs to another ACK cluster. First remove the node from the original cluster, then add it to the new cluster.
	Scaling group (ESS) ownership	You cannot add an instance that belongs to another scaling group. First remove it from the scaling group.
	Node pool type	You cannot add existing nodes to a Auto Mode node pool. You cannot add existing nodes to a node pool that has auto scaling enabled. After you add an existing node, you cannot enable auto scaling for that node pool.
	Operating system	Swap must be disabled on the operating system. In manual mode, you cannot add instances that run Windows or ContainerOS. See Operating systems.
	Instance type	The instance must not be an unsupported ECS instance type. For ECS Bare Metal GPU instances (ECS instance families ebmgn7 and ebmgn7e), automatic Multi-Instance GPU (MIG) cleanup is not supported. When you add such an instance, its MIG settings are reset. This reset may take a long time and cause automatic node addition to fail. For troubleshooting, see What do I do if I fail to add a bare metal instance node?.
Network	API Server access	The instance IP address must be on the API Server access whitelist. Otherwise, the node cannot communicate with the control plane. See Configure access control for the API Server.
	Security group	Type consistency: The instance security group type (basic or enterprise) must match the node pool. Rule compatibility: The instance security group must allow access to the API Server internal endpoint on port 6443, and its rules must not conflict with the cluster or node pool security group rules. Find the API Server internal endpoint on the Basic Information tab of the Cluster Information page. Quota: An instance cannot join more security groups than the security group quota allows. To change an instance security group type or add an instance to the node pool security group in advance, see Associate a security group with an instance (primary ENI). To increase the security group quota, see View or increase ECS quotas.
	Terway - Maximum pods	The maximum number of pods the instance supports must meet these requirements: The maximum pods supported in different elastic network interface (ENI) modes depends on the maximum ENIs the instance type supports. To calculate this limit, see How to calculate the pod quota for a node. For shared ENI mode, the maximum supported pods must exceed 10. For exclusive ENI mode, the maximum supported pods must exceed 5. If the requirement is not met, upgrade or downgrade node resources or purchase a new instance.
	Terway - vSwitch configuration	If the instance and node pool are in different availability zones, update the Terway vSwitch configuration. Otherwise, Terway allocates pod IP addresses from the primary ENI vSwitch, which can cause pod IP allocation errors. See Modify pod vSwitches.
	Terway - ENI	When you add the instance, its bound ENIs are retained, and pod IP addresses are allocated from the vSwitches associated with these ENIs. Ensure the instance has only one primary ENI. If a pod IP address does not belong to a configured vSwitch, remove the node from the cluster, delete all secondary ENIs, and add the node back.
	Terway - Worker RAM role	The instance must be bound to the node pool Worker RAM role to prevent permission issues that could cause incorrect MaxPod calculation. On the Node Pools page, click a node pool name to view its Worker RAM role on the Basic Information tab. To grant the RAM role, see Grant a RAM role to an ECS instance.
	Terway - IPv6 dual-stack	If IPv6 dual-stack is enabled for the cluster, assign an IPv6 address to the instance primary ENI. See IPv6 communication.
	Flannel	Custom route entries in the cluster VPC system route table cannot exceed the route table quota. To increase the quota, go to Quota Center.

Usage notes

Data backup: Before you begin, create a manual snapshot of the system and data disks to prevent data loss.

To ensure sufficient snapshot quota, delete unnecessary manual and automatic snapshots to avoid creation failures.
Instance release and billing: For node pools without expected node count enabled, instances added to the node pool are not released when you delete the cluster or node pool. You must manually remove the nodes. Monitor ECS billing to avoid unexpected charges.

Procedure

Time required: Node addition, including system disk replacement (auto mode only) and node initialization, takes about 5 minutes. Actual time varies based on network conditions, OS image size, and other factors.

Adding an existing node does not affect existing cluster nodes or applications. Do not initialize an ECS instance that already runs services as a worker node to avoid compatibility issues.

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Nodes > Node Pools.
On the Node Pools page, find the target node pool, click in the Actions column, and then click Add Existing Node.

If the target ECS instance is not in the server list, it does not meet the requirements for cluster addition. Select Show Unavailable Instances to view unavailable ECS instances and the reasons. See Limitations and Usage notes.
Read the on-screen notes and select a method for adding the node.

Manual add

Obtain an installation command and run it on the target instance. You can add only one ECS instance at a time.

Set Method to Manual. Select the ECS instance to add from the existing cloud servers list, and click Next.

On the Specify Instance Information page, confirm the cluster and instance details. Configure the data disk and instance name, then click Next.

Parameter	Description
Data Disk	Specifies whether to store container and image data on a data disk, separating the system disk from data disks for improved stability. If the ECS instance has an attached data disk and the last data disk file system is not initialized, ACK automatically formats the last data disk as ext4. The disk stores data exclusively in /var/lib/containerd or /var/lib/docker (default container runtime directories) and /var/lib/kubelet (default kubelet directory). Important Formatting erases existing data on the data disk. Create a snapshot to back up your data first. If you store containers and images on a data disk, only ext4 and xfs file systems are supported. If the ECS instance has no attached data disk, ACK does not 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 based on custom node naming rules.

On the Complete page, copy the node join command generated by ACK, then click Finish.
Log on to the ECS console. In the left-side navigation pane, choose Instances & Images > Instance. Select the cluster region and target instance.
Click Connect for the target instance and select a remote connection method.
Enter and run the script you copied in step 3 to configure and add the instance to the cluster.

After the script succeeds, a success message appears. In the node list, wait for the new node status to change to Ready.
```
Worker node joined successfully
+ exit_code=0
+ set +x
```

Auto add

Add instances automatically from the console.

Set Method to Auto. Select the ECS instances to add from the existing cloud servers list, and click Next.

On the Specify Instance Information page, confirm the cluster and instance details. Configure the data disk and instance name, then click Next.

Parameter	Description
Data Disk	Specifies whether to store container and image data on a data disk, separating the system disk from data disks for improved stability. If the ECS instance has an attached data disk and the last data disk file system is not initialized, ACK automatically formats the last data disk as ext4. The disk stores data exclusively in /var/lib/containerd or /var/lib/docker (default container runtime directories) and /var/lib/kubelet (default kubelet directory). Important Formatting erases existing data on the data disk. Create a snapshot to back up your data first. If you store containers and images on a data disk, only ext4 and xfs file systems are supported. If the ECS instance has no attached data disk, ACK does not attach a new data disk, regardless of whether you select this option.
Logon method and password	If the node pool Logon Type 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 based on custom node naming rules.

In the dialog box, read the notes and click OK.

After the node is added, wait for it to initialize in the node list until its status changes to Ready.

FAQ

Does adding nodes affect workloads?

Adding an existing node in manual or auto mode does not affect existing cluster workloads.

How does instance scaling affect workloads?

Upgrading or downgrading an ECS instance can change the instance type, public bandwidth billing method, public bandwidth, or data disk billing method. See Overview of instance configuration changes. The impact varies based on the upgrade or downgrade method.

Operations that do not require a restart: The impact depends on your scenario.
Operations that require an ECS instance restart: Operations such as upgrading or downgrading the instance type cause service disruptions. Before such an operation, such as upgrading or downgrading node resources, check the current workload to determine whether you need redundant nodes to take over pods. Then drain the node to upgrade or downgrade and remove it from the scaling group and ACK cluster. See Remove nodes.

After the upgrade or downgrade completes, add the node back to the cluster by following this topic.

Can I use different instance types?

Yes. ACK lets you manage nodes of multiple instance types in the same node pool, preventing scale-out failures caused by instance type unavailability or insufficient inventory. Before you add an ECS instance, ensure its instance type is in the node pool instance type list. Follow these steps:

Edit or create a node pool and configure the required node instance types. See Create and manage a node pool.
Drain and remove the target node. Do not release the ECS instance. See Remove nodes.
Add ECS instances of different instance types to the node pool by following the Limitations and Procedure sections in this topic.

How to move nodes between clusters?

ACK does not support moving nodes directly between clusters. Add an existing node instead. Follow these steps:

Drain and remove the target node from the source cluster. Do not release the ECS instance. See Remove nodes.
Add the target ECS instance to a node pool in the destination cluster by following the Limitations and Procedure sections in this topic.

Can I add a node with an EOL OS?

Manual mode: You can add an existing instance that runs an unsupported OS to a node pool, but ensure the instance OS version is compatible with the current cluster version. See Operating systems.

For example, CentOS 7 and Alibaba Cloud Linux 2 are supported only in clusters of version 1.30 and earlier.
Auto mode: ACK initializes the instance using the OS image specified in the node pool configuration.

Is user data overwritten when adding nodes?

Whether the original instance user data is overwritten depends on the addition method.

Auto mode: ACK initializes the system disk, overwriting the instance original user data with the user data configured for the node pool.
Manual mode: The original instance user data is not overwritten. After the instance joins the node pool, it continues to use its original user data.

How to fix node addition timeouts?

Check network connectivity between the node and the API Server CLB. First verify that the security group meets the requirements. For security group limitations when adding an existing node, see Limitations. For other network connectivity issues, see Network management FAQ.

Does adding a node change the expected count?

Yes. After you add an existing node, the Expected Nodes count increases by the number of nodes added. For example, if Expected Nodes is set to 5 and you add one ECS instance, the count becomes 6.

References

Besides the console, add ECS instances to an ACK cluster by calling an API operation (Obtain the script for adding existing nodes to a node pool) or running a CLI command (Add existing ECS instances).
Older clusters created before the node pool feature may contain free nodes (nodes not in any node pool). Migrate them to a node pool for centralized management. See Migrate free nodes to a node pool.
If a node, pod, or another component is not working as expected, troubleshoot the issue. See Troubleshoot node exceptions, Troubleshoot pod exceptions, and FAQ about nodes and node pools.