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 nodes by replacing their disks, ACK drains the nodes. This process evicts pods to other active nodes while respecting the Pod Disruption Budget (PDB). To ensure high availability, deploy workloads with multiple replicas across different nodes. Also, configure a PDB for critical services to control the number of pods that can be disrupted simultaneously.

  The default timeout for draining a node is 30 minutes. If pod migration is not completed within the timeout period, ACK terminates the upgrade to ensure service stability.

• When you upgrade nodes by replacing their disks, ACK reinitializes them based on the current node pool configuration. This includes the logon method, labels, taints, OS image, and runtime version. To update node pool configurations, see Edit a node pool. If you modified nodes in any other way, the upgrade overwrites your changes.

• If a pod on a node references a HostPath that points to the system disk, the data in the HostPath directory will be lost after a disk replacement upgrade.

• If you made configuration changes to the cluster, such as enabling the SWAP partition or modifying kubelet or runtime configurations through command-line operations, the cluster upgrade may fail or your custom configurations may be overwritten.

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