All Products
Search
Document Center

Container Service for Kubernetes:Manually update ACK clusters

Last Updated:Jan 13, 2025

Outdated cluster versions may have security and stability issues. To ensure business continuity, Container Service for Kubernetes (ACK) uses in-place updates to update ACK clusters. An ACK cluster consists of a control plane and node pools. You can run an update precheck in the ACK console before you update the control plane and node pools of a cluster.

Why ACK clusters need updates

ACK guarantees the stability of the latest three Kubernetes minor versions. For example, ACK discontinues the support for Kubernetes 1.26 when ACK is updated to support the following versions: Kubernetes 1.28, 1.30, and 1.31. In this case, you can no longer create ACK clusters that run Kubernetes 1.26. For more information about how ACK supports Kubernetes versions, see Support for Kubernetes versions.

Security and stability risks exist in outdated Kubernetes versions. After the cluster version expires, you cannot use the latest features, feature patches, or security patches provided by new Kubernetes versions. In addition, you cannot obtain technical support in a timely manner.

We recommend that you update your clusters at the earliest opportunity. This way, you can use the latest features and optimizations, benefit from the latest bug fixes, and enjoy improved technical support.

Important

When you update an ACK cluster, ACK performs a precheck on the cluster. However, ACK does not guarantee that all incompatible features, configurations, and APIs are detected. According to the shared responsibility model, we recommend that you pay attention to the release of Kubernetes versions by checking the documentation, information in the console, and internal messages, and learn about the update notes of the corresponding version before you update the cluster.

Usage notes

  • You can update an ACK cluster from a version only to the next version. You cannot roll back a cluster to an earlier version. If you need to perform consecutive updates for a cluster, check whether the business in the cluster can stably run between updates.

  • Read the Support for Kubernetes versions topic to learn about the version details, deprecated APIs, and usage notes for each Kubernetes version. This helps you avoid compatibility issues caused by feature updates in new Kubernetes versions.

  • Control plane updates do not affect applications in the cluster. When you update a cluster, a rolling update is performed on the API server of the cluster. If an application is strongly reliant on the API server, you need to enable reconnection and connection retry between the application and the API server.

  • Kubernetes 1.24 no longer uses Docker as the built-in container runtime. When you update a cluster from Kubernetes 1.22 to 1.24, you need to change the container runtime from Docker to containerd. For more information, see Migrate the container runtime from Docker to containerd.

  • It requires 5 to 8 minutes to update the control plane of a cluster. Do not perform operations on the cluster during a control plane update.

For more information about the usage notes for kubelet updates and container runtime updates, see Usage notes.

Description

When you update an ACK cluster, you need to update the control plane and node pools of the cluster. The following figure shows the update procedure.

image

Preparations

Read the release notes for the Kubernetes version to which you want to update your cluster to learn about the update notes. This helps you avoid compatibility issues caused by feature updates. We recommend that you perform the update during off-peak hours.

Update the cluster

Your cluster must pass the precheck before you can update the control plane and node pools of the cluster. If issues are reported in the precheck results, you must fix the issues and run the precheck again.

  • Update the control plane

    ACK managed clusters and ACK Serverless clusters

    Rolling updates are used. Update control plane components, including kube-apiserver, kube-controller-manager, and kube-scheduler.

    ACK dedicated clusters

    In-place updates are performed to ensure business continuity and reduce potential risks posed by data migration and configuration modifications. Procedure:

    1. When ACK identifies that the etcd and container runtime in your cluster need to be updated, ACK updates the etcd and container runtime on each master node in sequence.

    2. ACK updates only one master node at a time and displays the ID of the master node.

    3. Update components on master nodes, such as kube-apiserver, kube-controller-manager, kube-scheduler.

    4. Update the kubelet on master nodes.

  • Update node pools

    When you update a node pool, you need to update the kubelet and container runtime. To change the container runtime from Docker to containerd, ACK replaces the system disks of the nodes during the update. This way, the operating system and applications are also updated. We recommend that you back up the data on the system disks of the nodes before you update the cluster. In other scenarios, ACK uses in-place updates to update node pools. For more information, see Update a node pool.

    ACK updates the nodes in your cluster in batches.

    • Multiple node pools are updated one after one.

    • 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. For more information, see Update a 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

You can update the control plane before you update node pools. Before you update the control plane, make sure that the Kubernetes version used by the control plane is the same as the Kubernetes version used by nodes in the cluster. For example, if the control plane uses Kubernetes 1.30 but the nodes in the cluster use Kubernetes 1.28. You must update the Kubernetes used by the nodes to 1.30 before you can update the Kubernetes version used by the control plane to 1.31.

1. Update the control plane

  1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

  2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Operations > Upgrade Cluster.

  3. 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.

      Note

      If 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.

  4. 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.

2. Update node pools

After you update the control plane, we recommend that you update node pools at the earliest opportunity during off-peak hours. When you update a node pool, you need to update the kubelet and container runtime of the node pool. For more information about node pool updates and the update procedure and update notes for node pools, see Update a node pool.

FAQ about cluster updates

How long does it require to update a cluster?

For ACK managed clusters and ACK Serverless clusters, it requires about 5 minutes to update the control plane. For ACK dedicated clusters, ACK needs to update the master nodes one after one. It requires about 8 minutes to update a master node. Nodes in a node pool are updated in batches. It requires about 5 minutes to update a batch.

What do I do if a cluster update fails and the following error is returned: the aliyun service is not running on the instance?

The Cloud Assistant agent becomes unavailable. As a result, the update command fails to be sent to the cluster. Start or stop the Cloud Assistant client. Then, update the cluster again. For more information, see Start, restart, stop, or uninstall the Cloud Assistant agent.

How do I handle the PLEG not healthy error?

The containers or container runtime does not respond. You need to restart the nodes and initiate the update again.

What do I do if the invalid object doesn't have additional properties error is reported during a cluster update?

After the update is completed, you need to update kubectl on your on-premises machine. If you do not update kubectl, the kubectl version may be incompatible with the API server version. As a result, the error message invalid object doesn't have additional properties may appear. For more information about how to install or upgrade kubectl, see Install kubectl.

References