ACK Lingjun clusters support Kubernetes upgrades from version 1.20 to 1.22 using in-place updates. You can upgrade the entire cluster in one operation, or upgrade the control plane and node pools separately.
How it works
An ACK Lingjun cluster upgrade follows these steps:
-
Run a precheck. ACK scans the cluster for compatibility issues before any changes are made. Fix all reported issues before proceeding.
-
Upgrade the control plane. ACK updates kube-apiserver, kube-controller-manager, and kube-scheduler. Kubernetes components such as kube-proxy are also updated. New nodes added after this step run the new Kubernetes version.
-
Upgrade node pools. ACK updates kubelet and the container runtime on existing nodes in batches. Multiple node pools are upgraded one at a time.
-
Verify. Confirm the cluster version, node pool status, and application health.
Prerequisites
Before you begin, ensure that you have:
-
Access to the ACK console
-
Read the release notes for the Kubernetes version to which you want to upgrade your cluster
-
Read the release notes for the target Kubernetes version:
-
Reviewed support for Kubernetes versions in ACK Lingjun
Usage notes
Kubernetes version compatibility
Before upgrading, check the Version column on the Container Service for Kubernetes consoleClusters page in the ACK console to confirm your current Kubernetes version. If your Helm charts use deprecated API resources, update those manifests before upgrading. For details on deprecated APIs, see Deprecated APIs and the corresponding release notes.
For clusters running Kubernetes 1.20 or later, the precheck also scans for deprecated API usage. The result is informational — it does not block the upgrade.
Feature-specific considerations
If your cluster uses any of the following features, review the considerations before upgrading.
| Feature | What happens during upgrade | Action required |
|---|---|---|
| FlexVolume | Object Storage Service (OSS) volumes mounted by FlexVolume 1.11.2.5 or earlier are remounted. | Recreate pods that use OSS volumes after the upgrade. Migrate from FlexVolume to CSI when possible. See Migrate from FlexVolume to CSI. |
| Auto scaling | Cluster Autoscaler is automatically updated to the latest version. | Verify that Cluster Autoscaler is running the expected version. See Auto scaling of nodes. |
| Resource reservation | After upgrading to Kubernetes 1.18, ACK automatically configures resource reservation. If node resource usage is high, evicted pods may fail to be rescheduled. | Reserve at least 50% of CPU and 70% of memory on each node before upgrading. See Resource reservation policy. |
LoadBalancer with externalTrafficPolicy: Local |
Traffic is only forwarded to node-local pods. If application pods are on other nodes, they become unreachable. | Check whether externalTrafficPolicy: Local is set on any Server Load Balancer (SLB) instance. See What to do if the cluster cannot access the SLB IP address. |
| API server-dependent applications | The API server may be briefly interrupted during the control plane upgrade. Applications that use list-and-watch operations are affected. | Configure your application to automatically retry watch operations on disconnection. Applications that do not access the API server are not affected. |
| kubectl | After the upgrade, kubectl on your local machine may be incompatible with the new API server version, causing invalid object doesn't have additional properties errors. |
Update kubectl after the cluster upgrade. See Install kubectl. |
Custom configuration considerations
| Item | Consideration |
|---|---|
| Network | The upgrade uses yum to download packages. If your cluster uses a custom network configuration, verify that yum works correctly by running yum makecache. |
| OS image | Custom OS images are not validated by ACK. Upgrade success is not guaranteed for clusters using custom OS images. |
| Other custom configurations | Swap partitions, kubelet settings modified via CLI, or other non-standard configurations may cause the upgrade to fail or those settings to be lost. |
Upgrade the cluster
ACK runs a precheck before each upgrade, but the precheck cannot guarantee that all incompatible APIs, features, or configurations are identified. Under the shared responsibility model, review all relevant release notes and upgrade guidance before proceeding.
Perform the upgrade during off-peak hours to minimize business impact.
Step 1: Upgrade the control plane
-
Log on to the ACK console. In the left-side navigation pane, click Clusters.
-
On the Clusters page, click the name of the cluster you want to upgrade. In the left-side pane, choose Operations > Upgrade Cluster.
-
On the Upgrade Cluster page, set Destination Version and click Precheck. After the precheck completes, review the results in the Pre-check Results section:
-
No issues: The cluster passed the precheck. Proceed to the next step.
-
Issues found: The cluster continues to run normally. Fix the reported issues based on the console suggestions, then run the precheck again. See Cluster check items and how to fix them.
-
-
Click Start Update and follow the on-screen instructions. View upgrade history in the upper-right corner of the Upgrade Cluster page. After the control plane upgrade completes, go to the Clusters page and verify the Kubernetes version in the Version column.
What ACK does during the control plane upgrade:
-
Updates control plane components: kube-apiserver, kube-controller-manager, and kube-scheduler.
-
Updates Kubernetes components such as kube-proxy.
Step 2: Upgrade node pools
After the control plane is upgraded, upgrade existing node pools at the earliest opportunity. Nodes in a pool that have not been upgraded still run the previous Kubernetes version.
See Update a node pool and Update a Lingjun node pool for detailed steps.
What ACK does during a node pool upgrade:
-
Updates kubelet and the container runtime on each node.
-
Docker to containerd migration: If you are switching the container runtime from Docker to containerd, ACK replaces the system disk of each node — which also updates the OS and reinstalls applications. Back up any data on system disks before starting this type of upgrade.
-
In all other scenarios, ACK performs in-place updates.
Batch update rules:
-
Multiple node pools are upgraded one at a time.
-
Within a node pool, nodes are upgraded in batches: 1 node in the first batch, then doubling in each subsequent batch (1 → 2 → 4 → 8...).
-
Set the maximum batch size on the Node Pool Upgrade page. A maximum batch size of 10 is recommended.
-
The batching policy continues to apply after you resume a paused upgrade.
Verify the upgrade
After both phases complete, confirm the following:
-
The Version column on the Clusters page shows the new Kubernetes version.
-
All node pools are running and healthy.
-
Application workloads in the cluster are functioning as expected.
-
Confirm the kubelet version on upgraded nodes to verify the node pool upgrade is complete.
Troubleshooting
Upgrade fails with "the aliyun service is not running on the instance"
The Cloud Assistant agent is unavailable, so the upgrade command cannot be sent to the node. Start or restart the Cloud Assistant client, then retry the upgrade. See Start, restart, stop, or uninstall the Cloud Assistant agent.
PLEG not healthy error
The container or container runtime on the node is not responding. Restart the affected nodes, then initiate the upgrade again.