Troubleshoot edge node issues-Container Service for Kubernetes(ACK)-阿里云帮助中心

Resolve connection and upgrade failures for edge nodes by matching error messages to causes and fixes.

If your issue is not listed, collect diagnostic information and submit a ticket.

Handle edge node connection failures

If the node connection script fails, match your error message below.

Error message	Cause	Fix
`The os XXX unsupport`	Unsupported OS version.	See Add an edge node for supported OS versions.
`Invalid nodeName`	Invalid node name.	Use a name that: contains only lowercase letters, hyphens (`-`), and periods (`.`); is 1–253 characters long; does not start with `localhost`.
`Node route overlaps with service cidr`	Node route overlaps with the pod CIDR block or Service CIDR block.	Recreate the cluster with pod and Service CIDR blocks that do not overlap with the NameServer address or node route.
`response error msg: TOKEN_EXPIRED`	Expired connection token.	Generate a new connection script. Verify the node's system clock is accurate.
`A node named XXX is already exist in the cluster`	Duplicate node name in the cluster.	Remove the duplicate node, then rerun the connection script.
`error run phase join-node: failed to get cluster info: failed to get cluster-info configmap, Get "https://xx.xxx.xx.xx:6443/api/v1/namespaces/kube-public/configmaps/cluster-info": dial tcp xx.xxx.xx.xx:6443: i/o timeout`	edgeadm could not reach the API server.	edgeadm connects to the API server by IP address. Check whether the access control list (ACL) rules on the Server Load Balancer (SLB) instance fronting the API server block the node's IP address.
`error run phase join-node: Install edge-hub failed: Copy file /tmp/edge-hub to /usr/bin/edge-hub fail: open /usr/bin/edge-hub: text file busy \| 40009 \| 40009`	An edge-hub binary already exists on the node.	Run `edgeadm reset` , then rerun the connection script.
`error run phase post-check: timed out waiting for the condition`	System components failed to start.	1. Download the latest edgeadm, run `edgeadm reset`, and rerun the connection script. 2. Verify the node can reach all required public endpoints — see Configure endpoints and IP routing for edge nodes. 3. If the issue persists, collect diagnostic information and submit a ticket.

Handle edge node upgrade failures

When you update an edge node pool, a successful upgrade returns This node has been upgraded successfully. If not, match your error below.

Error message	Cause	Fix
`edgeadm version xxxx does not match cluster version`	The edgeadm version does not match the cluster version.	1. Verify the control plane is upgraded. 2. Verify `TARGET_CLUSTER_VERSION` is correct.
`node has already been upgraded to xxx`	The node is already at the target version.	If some components were not upgraded, retain the logs and submit a ticket.
`kubelet target version xxxx does not match cluster version xxxx`	The kubelet version does not match the control plane version.	If `kubelet-version` is specified, verify it matches the control plane version. If not, submit a ticket.
`Parameter currentVersion cann't null`	Outdated edgeadm version.	Download the latest edgeadm. Valid upgrade paths: Kubernetes 1.18 → 1.20 and 1.20 → 1.22.
`upgrade kubelet failed at phase install, recover to previous state.` `error run phase upgrade: xxxx`	Upgrade failed; automatic rollback succeeded. Node status unaffected.	Retain the logs and submit a ticket.
`upgrade kubelet failed at phase install, recover to previous state` `recover kubelet failed, err: xxx` `error run phase upgrade: xxxx`	Upgrade and rollback both failed. Node status affected.	Retain the logs and submit a ticket.

Collect node diagnostic information

Run this script on an abnormal edge node to collect diagnostic information.

Log on to the abnormal edge node.

Download the diagnostic script.

curl -o /usr/local/bin/diagnose_edge_node.sh https://aliacs-k8s-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/public/diagnose/diagnose_k8s.sh

Make the script executable.

chmod u+x /usr/local/bin/diagnose_edge_node.sh

Navigate to the script directory.
```
cd /usr/local/bin/
```

Run the diagnostic script.

./diagnose_edge_node.sh

Each run generates a unique archive. Example output:

+ echo 'please get diagnose_1578310147.tar.gz for diagnostics'
please get diagnose_1578310147.tar.gz for diagnostics
+ echo 'Submit the file named diagnose_1578310147.tar.gz to request technical support.'
Submit the file named diagnose_1578310147.tar.gz to request technical support.

Verify the archive exists.
```
ll
```

Attach the .tar.gz file when you submit a ticket.