Outdated Kubernetes versions may have security and stability issues. When a new Kubernetes version is supported by ACK Edge, we recommend that you upgrade your ACK Edge clusters to this version. This ensures a secure and stable environment for your clusters and allows you to benefit from the new features provided by the new version. ACK Edge uses in-place upgrades to upgrade ACK Edge clusters. This topic describes the procedure and considerations for updating ACK Edge clusters.
Why ACK Edge clusters need upgrades
Reduced security and stability risks: Security and stability vulnerabilities are patched in new versions. Using outdated Kubernetes clusters may pose security and stability risks to your business.
Improved technical support and customer service: ACK Edge no longer releases security patches or repairs for outdated Kubernetes versions. In addition, ACK Edge does not guarantee the quality of technical support for outdated Kubernetes versions. You can enjoy improved technical support and customer service when using new Kubernetes versions.
New features: ACK Edge releases new versions with enhanced features and optimizations, delivering a smoother development and operational experience.
Usage notes
ACK Edge clusters support cluster upgrades between versions from 1.18 to 1.24. However, you can upgrade from the current Kubernetes version only to the next version. You cannot roll back an ACK Edge cluster to an earlier Kubernetes version.
For example, to upgrade the Kubernetes version of an ACK Edge cluster from 1.18 to 1.22, you must first upgrade the cluster to 1.20, and then upgrade the cluster to 1.22.
NoteYou can upgrade your ACK Edge clusters from Kubernetes 1.26 to later versions. To upgrade from Kubernetes 1.26 to 1.30, submit a ticket to apply to be added to a whitelist.
In an ACK Edge cluster, edge node pools and the control plane can differ by at most two minor versions. For example, if the control plane runs Kubernetes 1.22, the edge node pools must run at least Kubernetes 1.20. Otherwise, the cluster may not work as expected.
Upgrade procedure, methods, and duration
Upgrade procedure
Preparations
Log on to the ACK console. On the Clusters page, select the ACK Edge cluster that you want to upgrade and check the current Kubernetes version of the cluster and the new version available in the Version column.
Read the release notes for the Kubernetes versions supported by ACK Edge clusters to learn about the features of different Kubernetes versions. For more information, see Release notes for ACK Edge of Kubernetes 1.30.
Upgrade the cluster
Your cluster must pass a precheck before you can update the control plane and on-cloud node pools of the cluster. If issues are reported in the precheck results, you must fix the issues before you start the update.
Control plane update: Rolling updates are used to update control plane components, such as kube-apiserver, kube-controller-manager, and kube-scheduler.
On-cloud node pool update: When you update an on-cloud node pool, you need to update the kubelet and the container runtime of the node pool. Node pools are updated in batches:
Node pools are updated one after one. Only one node pool is updated at a time.
Nodes in a node pool are updated in batches. The first batch includes one node. The number of nodes increases by the power of two in subsequent batches. The batch update policy still applies after you resume a paused update. You can specify the maximum batch size on the Node Pool Upgrade page. We recommend that you set the maximum batch size to 10.
Edge node pool update: You need to run update commands on all nodes one after one in each edge node pool.
Update duration
It requires about 5 minutes to update the control plane of an ACK Edge cluster.
Nodes in an on-cloud node pool are updated in batches. Each batch update requires about 5 minutes.
For an edge node pool, you need to run update commands on all nodes in the node pool. Therefore, the duration of an edge node pool update varies based on the number of nodes in the node pool.
Verify the update
Check whether the Kubernetes version of the cluster is updated, whether the node pools run as expected, and whether the business in the cluster runs as expected.
Procedure
Step 1: Update the control plane
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose .
On the Upgrade Cluster page, set Destination Version and click Precheck to detect potential risks in the update.
After the precheck is completed, you can view the precheck results in the Pre-check Results section.
If no issue is displayed, it indicates that the cluster passes the precheck. You can start the update.
If issues are displayed, the cluster can still run as expected and the cluster status does not change. You can fix the issues based on the suggestions that are provided by the console. For more information, see Cluster check items and suggestions on how to fix cluster issues.
NoteIf your cluster runs Kubernetes 1.20 or later, the precheck checks whether deprecated APIs are used in your cluster. The precheck result is for reference only and does not determine whether the cluster is updatable. For more information, see Deprecated APIs.
After your cluster passes the precheck, click Start Update and follow the on-screen instructions to update the control plane.
You can view the update history in the upper-right corner of the Upgrade Cluster page.
After the update is complete, you can go to the Clusters page and check the Kubernetes version of your cluster to check whether the control plane is updated. When you add new nodes after the control plane is updated, the new nodes use the new Kubernetes version.
Step 2: Update on-cloud node pools
After you update the control plane, we recommend that you update on-cloud node pools at the earliest opportunity during off-peak hours. When you update an on-cloud node pool, you need to update the kubelet and container runtime of the node pool. For more information about how to update an on-cloud node pool and the update notes, see Update an on-cloud node pool.
Step 3: Update edge node pools
Make sure that the control plane is updated.
An edge node pool is considered updated only when all nodes in the node pool are updated.
Update operations when the runtime is Docker
To upgrade the Kubernetes version of an ACK Edge cluster to 1.24, you must change the container runtime from Docker to containerd if the cluster includes nodes that use the Docker runtime. Kubernetes 1.24 does not support the Docker runtime. You can complete the update by using the following methods.
(Recommended) Create a new node pool that uses the containerd runtime and perform rolling migration: Create a new node pool, set the runtime to containerd, and expand the number of nodes. Gradually migrate all applications to the new node pool by setting the old node pool to unschedulable or by changing the node pool scheduling method specified in the workloads (use labels), and then take the old node pool offline. For information about how to create a node pool, see Edge node pool management. For information about how to set a node to unschedulable, see Node draining and scheduling status.
In-place update: Change the runtime of the node from containerd to Docker. Drain the node before the update. All containers on the node will restart during the update.
Drain the node.
Run the following command on all nodes one at a time in the edge node pool:
export REGION="" INTERCONNECT_MODE="" TARGET_CLUSTER_VERSION=""; export ARCH=$(uname -m | awk '{print ($1 == "x86_64") ? "amd64" : (($1 == "aarch64") ? "arm64" : "amd64")}') INTERNAL=$( [ "$INTERCONNECT_MODE" = "private" ] && echo "-internal" || echo "" ); wget http://aliacs-k8s-${REGION}.oss-${REGION}${INTERNAL}.aliyuncs.com/public/pkg/run/attach/${TARGET_CLUSTER_VERSION}/${ARCH}/edgeadm -O edgeadm; chmod u+x edgeadm;./edgeadm upgrade --interconnect-mode=${INTERCONNECT_MODE} --region=${REGION}The following table describes the parameters.
Parameter
Description
Example
TARGET_CLUSTER_VERSION
The new Kubernetes version.
NoteSet the value to the Kubernetes version of the updated control plane.
1.24.6-aliyunedge.1
For more information about the Kubernetes versions supported by ACK Edge clusters, see Release notes for supported Kubernetes versions.
REGION
The region ID of the cluster.
cn-hangzhou
For more information about the regions supported by ACK Edge clusters, see Supported regions.
INTERCONNECT_MODE
The network type of connections to the node.
basic: public network.
private: Express Connect circuits.
basic
The following output indicates that the node is updated.
Update operations when the runtime is not Docker
Run the following command on all nodes one at a time in the edge node pool:
export REGION="" INTERCONNECT_MODE="" TARGET_CLUSTER_VERSION=""; export ARCH=$(uname -m | awk '{print ($1 == "x86_64") ? "amd64" : (($1 == "aarch64") ? "arm64" : "amd64")}') INTERNAL=$( [ "$INTERCONNECT_MODE" = "private" ] && echo "-internal" || echo "" ); wget http://aliacs-k8s-${REGION}.oss-${REGION}${INTERNAL}.aliyuncs.com/public/pkg/run/attach/${TARGET_CLUSTER_VERSION}/${ARCH}/edgeadm -O edgeadm; chmod u+x edgeadm;./edgeadm upgrade --interconnect-mode=${INTERCONNECT_MODE} --region=${REGION}The following table describes the parameters.
Parameter | Description | Example |
TARGET_CLUSTER_VERSION | The new Kubernetes version. Note Set the value to the Kubernetes version of the updated control plane. | 1.24.6-aliyunedge.1 For more information about the Kubernetes versions supported by ACK Edge clusters, see Release notes for supported Kubernetes versions. |
REGION | The region ID of the cluster. | cn-hangzhou For more information about the regions supported by ACK Edge clusters, see Supported regions. |
INTERCONNECT_MODE | The network type of connections to the node.
| basic |
The following output indicates that the node is updated.
FAQ
Does ACK Edge force cluster upgrades if I do not upgrade my clusters?
No, it doesn't. An ACK Edge cluster can only be manually upgraded. If you choose not to upgrade, your cluster will remain on the original Kubernetes version. We strongly recommend upgrading promptly to access comprehensive features and technical support.
What do I do if I fail to upgrade an edge node?
When you upgrade the edge node pool, if the success message This node has been upgraded successfully is not returned, refer to What do I do if an edge node fails to be upgraded when I upgrade an ACK Edge cluster?
Reference
If your cluster fails a precheck before an upgrade, refer to Cluster check items and suggestions on how to fix cluster issues.