Change operating system

See Release notes for OS images for supported OS types, image versions, and usage limitations.

Usage notes

• This operation replaces system disks in batches to update the OS. Back up important data from system disks in advance. Data disks are not affected. Perform this operation during off-peak hours.

• When you upgrade by replacing system disk, ACK performs node draining to evict pods to other available nodes, respecting the configured PodDisruptionBudget (PDB). To ensure high availability, use a multi-replica deployment strategy to distribute workloads across multiple nodes. Also, configure a PDB for critical services to control the number of concurrently disrupted pods.

  The default timeout for node draining is 30 minutes. If pod migration does not complete within this time, ACK terminates the upgrade to maintain service stability.

• When you upgrade by replacing system disk, ACK reinitializes the node based on the current node pool configuration, including the logon method, labels, taints, OS image, and container runtime version. Update node pool configurations by editing a node pool. If you modified a node through other means, the upgrade will overwrite these changes.

• If a pod on the node uses a HostPath volume that points to the system disk, the data in the HostPath directory will be lost after an upgrade by replacing system disk.

• If you have made custom changes to your cluster, such as enabling a SWAP partition or modifying kubelet or container runtime configurations through the command line, the upgrade process might fail or overwrite your custom configurations.

• Some ACK operating systems use cgroup v2 by default. Review the cgroup v2 overview for related considerations.

• If you have orphaned nodes (worker nodes not managed by a node pool), migrate them to a node pool.

• In ContainerOS 3.4.0 and later, the system disk is read-only and requires an attached data disk for startup. Follow the procedure below when upgrading to ContainerOS 3.4.0 or later. Other versions are not affected.

  Click to view the detailed procedure

  Choose a plan based on the data disk status of your node pool:

  • Single data disk attached: Follow the Procedure below to upgrade.

  • Multiple data disks attached: Perform a rotation migration. Create a node pool with ContainerOS 3.4 or later and one data disk, then scale out nodes. Gradually migrate applications to the new pool (for example, by disabling scheduling on the old pool or using labels). Decommission the old pool after migration.

  • No data disk attached:

    • Keep the current node pool: Add one data disk to the node pool configuration and scale out new nodes. After the new nodes are running, drain and remove the old nodes.

    • Migrate to a new node pool: Follow the same procedure as for 'Multiple data disks attached'.

  To create or edit a node pool, see Create and manage a node pool. To set a node to unschedulable, see Drain a node and manage its scheduling status. To remove a node, see Remove a node.

• If you customize the GPU driver version by specifying a version number or by using an OSS URL, the OS and driver may become incompatible after the update. See Supported NVIDIA driver versions in ACK to select a compatible driver.

Procedure

To avoid compatibility risks, run a precheck before updating the OS image or changing the OS type.

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

2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Nodes > Node Pools.

3. In the Actions column of the Node Pools list, select > Change Operating System for the target node pool.

4. Click Precheck to scan for potential risks.

   • Normal: Precheck passed. Proceed with the update.

   • Abnormal: Does not affect current cluster operation. Fix reported issues before proceeding.

5. After the precheck passes, configure the following parameters and click Start Replacement.

   Parameter		Description
   Destination version		Target OS image and version.
   Current version		The current OS version.
   Update Node		Nodes to update. Select all or specific nodes.
   Ignore Warnings		Whether to proceed if the precheck reports warnings. For example, a pod uses a hostPath pointing to the system disk.
   Batch Replace	Maximum Number of Nodes per Batch	Maximum nodes updated concurrently per batch.
   	Automatic Pause Policy	Pause policy for the OS replacement process.
   	Interval Between Batches	Interval between batches when Automatic Pause Policy is Do Not Pause. Valid values: 5 to 120 minutes.
   	Auto Snapshot	Create a snapshot for nodes with important data to enable backup and restore. Snapshots incur snapshot fees. Delete unneeded snapshots after the update.

   Important

   Before you change the OS, review the OS image release notes to avoid OS-related compatibility risks.

References

• To upgrade kubelet and container runtime versions, see Upgrade a node pool.

• See Reference: In-place updates and updates by replacing system disks.