ACK Edge clusters support adding physical and virtual machines from different environments as edge nodes — including Elastic Compute Service (ECS) instances from other regions, on-premises IDC servers, nodes from other cloud providers, and servers deployed in factories, retail outlets, vehicles, and ships.
This topic describes how to add an existing node to an edge node pool in an ACK Edge cluster.
Prerequisites
Before you begin, make sure that:
An ACK Edge cluster is already created
The cluster has a sufficient node quota. To request a quota increase, go to the Quota Center. For quota limits, see Quotas and limits
The node's security group is configured to allow access to the required domain names. For details, see Domain name and IP routing configuration for edge node access
The node runs a supported operating system
Supported operating systems
| System architecture | OS version | Kernel version | ACK Edge cluster version |
|---|---|---|---|
| AMD64/x86_64 | Anolis7.9, Anolis8.6 | 4.19.X | ≥ 1.16.9-aliyunedge.1 |
| AMD64/x86_64 | Alibaba Cloud Linux 2.1903 | 4.19.X | ≥ 1.20.11-aliyunedge.1 |
| AMD64/x86_64 | Alibaba Cloud Linux 3 | 5.10.X | ≥ 1.20.11-aliyunedge.1 |
| AMD64/x86_64 | CentOS 7.4, 7.5, 7.6, 7.7, 7.8, and 7.9 | 3.10.X | 1.12.6-aliyunedge.1 ≤ version ≤ 1.30.7-aliyun.1 |
| AMD64/x86_64 | CentOS 8.0, CentOS 8.2 | 4.18.X | 1.18.8-aliyunedge.1 ≤ version ≤ 1.30.7-aliyun.1 |
| AMD64/x86_64 | Ubuntu 16.04 | 4.4.X | 1.18.8-aliyunedge.1 ≤ version ≤ 1.30.7-aliyun.1 |
| AMD64/x86_64 | Ubuntu 18.04 | 4.15.X | 1.12.6-aliyunedge.1 ≤ version ≤ 1.30.7-aliyun.1 |
| AMD64/x86_64 | Ubuntu 18.04 | 5.4.X | ≥ 1.16.9-aliyunedge.1 |
| AMD64/x86_64 | Ubuntu 18.04 | 5.11.X | ≥ 1.18.8-aliyunedge.1 |
| AMD64/x86_64 | Ubuntu 20.04 | 5.4.X | ≥ 1.18.8-aliyunedge.1 |
| AMD64/x86_64 | Ubuntu 20.04 and Ubuntu 22.04 | 5.15.X | ≥ 1.26.3-aliyun.1 |
| AMD64/x86_64 | Ubuntu 24.04 | 6.8.X | ≥ 1.30.7-aliyun.1 |
| AMD64/x86_64 | Red Hat Enterprise Linux 8.8, Red Hat Enterprise Linux 8.10 | 4.18.X | 1.26.3-aliyun.1 ≤ version ≤ 1.30.7-aliyun.1 |
| AMD64/x86_64 | Kylin V10 | 4.19.X | ≥ 1.26.3-aliyun.1 |
| AMD64/x86_64 | UnionTech OS Server 20 | 4.19.X | ≥ 1.26.3-aliyun.1 |
| AMD64/x86_64 | Red Hat Enterprise Linux 9.3 | 5.14.X | ≥ 1.30.7-aliyun.1 |
| Arm64 | CentOS 8.0 | 4.19.X | ≥ 1.14.8-aliyunedge.1 |
| Arm64 | Ubuntu 18.04 | 4.9.X | 1.14.8-aliyunedge.1 ≤ version ≤ 1.30.7-aliyun.1 |
| Arm64 | Ubuntu 18.04 | 4.19.X | ≥ 1.14.8-aliyunedge.1 |
| Arm64 | Ubuntu 20.04 | 5.10.X | ≥ 1.22.15-aliyunedge.1 |
To add a GPU node, see Add a GPU node.
Add an edge node
The steps differ by cluster version. Use the section that matches your cluster.
Clusters running Kubernetes 1.26 or later
Log on to the ACK console and click Clusters in the left-side navigation pane.
On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose Nodes > Node Pools.
On the Node Pools page, find the target node pool and click  > Add Existing Node in the Actions column.
On the Add Existing Node page, configure the cloud-edge communication parameters and advanced options.
If the console parameters don't meet your requirements, edit the edgeadm parameters directly in the generated script. See the edgeadm parameter reference below.
Cloud-edge communication configuration
Parameter Description Token validity period How long the generated script remains valid. Default: 1 hour. Set to 0 hours for a script that never expires — useful when adding nodes in batches over an extended period. Enable silent mode Default: Yes. In silent mode, edgeadm automatically answers all prompts with yes(for example, when asked whether to reinstall an existing runtime). Set to No to review and confirm each prompt manually.Advanced options
Parameter Description Node labels Labels to apply to the node. If a label key conflicts with a label set on the node pool, the node pool label takes precedence. Taints Taints to apply to the node. Annotations Annotations to apply to the node. If an annotation key conflicts with an annotation set on the node pool, the node pool annotation takes precedence. Automatic synchronize time When enabled, edgeadm automatically synchronizes the system clock on the node. Node network port The name of the network interface card (NIC) that kubelet uses to get the node IP and that flannel uses for container networking. Leave blank to use the NIC associated with the default route. The component is downloaded from The source for system component images. Default: public network. Selecting private network requires the node to be connected to a leased line node pool. Runtime working directory The working directory for the container runtime. Takes effect only when manageRuntimeis set totrue. Default for containerd:/var/lib/containerd.
Click OK. On the submission result page, click Copy, paste the script onto your edge node, and run it. If the following result is returned, the edge node is added to the cluster.
Clusters running Kubernetes earlier than 1.26
Log on to the ACK console and click Clusters in the left-side navigation pane.
On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose Nodes > Node Pools.
On the Node Pools page, find the target node pool and click More
> Add Existing Node in the Actions column.On the Add Node page, the Manual mode is selected by default. Manual mode supports ECS instances, ENS instances, and edge nodes. Click Next Step to go to the Instance Information page and configure the node access settings.
Script validity period defaults to 1 hour. Set it to 0 hours for a script that never expires — useful when adding nodes in batches over an extended period.
Click Next Step. On the Complete page, click Copy, paste the script onto your edge node, and run it. If the following result is returned, the edge node is added to the cluster.
edgeadm parameter reference
If the console options don't cover your scenario, modify the edgeadm parameters directly in the generated script. The table below lists all available parameters.
| Parameter | Required | Console equivalent | Default | Description |
|---|---|---|---|---|
quiet | No | Enable silent mode | true | Controls whether edgeadm automatically answers all prompts with yes. Set to false to review and confirm each prompt — note that this may pause or interrupt the node join process. |
manageRuntime | No | N/A | true | Controls whether edgeadm detects and installs the container runtime. Set to false if you have already installed the runtime on the node. |
nodeNameOverride | No | N/A | "" | The node name. "" uses the hostname. "XXX" sets the name to XXX. "*" generates a random 6-character string. "*.XXX" generates a random 6-character string with the XXX suffix. |
allowedClusterAddons | No | N/A | ["kube-proxy","flannel","coredns"] | The components to install on the node. |
gpuVersion | No | N/A | "" | Specifies the GPU model when adding a GPU-accelerated node. For supported GPU models, see GPU models. For ACK Edge clusters 1.26 and later, NVIDIA GPU models are auto-detected — this parameter is not required. |
labels | No | Node labels | {} | Labels to apply to the node. If a label key conflicts with a label on the node pool, the node pool label takes precedence. |
annotations | No | Annotations | {} | Annotations to apply to the node. If an annotation key conflicts with an annotation on the node pool, the node pool annotation takes precedence. |
taints | No | Taints | [] | Taints to apply to the node. |
nodeIface | No | N/A | "" | The NIC that kubelet uses to get the node IP and that flannel uses for container networking. When left blank, kubelet checks /etc/hosts for a record matching the hostname first, then falls back to the NIC in the default route. Flannel also uses the default route NIC. |
runtimeRootDir | No | Runtime working directory | "" | The working directory for the container runtime. Takes effect only when manageRuntime is true. Docker default: /var/lib/docker. containerd default: /var/lib/containerd. |
imageRepoType | No | The component is downloaded from | "" | The source for system component images. "" auto-selects: leased line node pool nodes use the internal network; regular node pool nodes use the public network. public forces public network. private forces internal network and requires a leased line node pool. |
selfHostNtpServer | No | Automatic synchronize time | false | Controls time synchronization. false: edgeadm automatically syncs the system clock. true: time has already been synchronized manually; skip auto-sync. |
flannelIface | No | Node network port | "" | The NIC name for flannel. Not recommended — use nodeIface instead. Defaults to the NIC in the node's default route. |
enableIptables | No | N/A | false | Controls whether edgehub enables iptables optimization. Deprecated after version 1.22. |
What's next
If the node fails to join, see Diagnose edge node problems.
To remove a node you no longer need, see Remove edge nodes.
To keep workloads running on the node when the cloud-edge network is disconnected, see Configure edge node autonomy.