Upgrade an operating system distribution

Caution

Usage of third-party software, which is not part of Mirantis-supported configurations, for example, the use of custom DPDK modules, may block upgrade of an operating system distribution. Users are fully responsible for ensuring the compatibility of such custom components with the latest supported Ubuntu version.

Distribution upgrade of an operating system (OS) is implemented for management and MOSK clusters.

For management clusters, an OS distribution upgrade occurs automatically as part of cluster update and requires machines reboot. The upgrade workflow is as follows:

The distribution ID value is taken from the id field of the distribution from the allowedDistributions list in the spec of the ClusterRelease object.
The distribution that has the default: true value is used during update. This distribution ID is set in the spec:providerSpec:value:distribution field of the Machine object during cluster update.

For MOSK clusters, an in-place OS distribution upgrade should be performed between cluster updates. This scenario implies a machine cordoning, draining, and reboot. Upgrading all nodes at once is not mandatory. You can upgrade them individually or in small batches, depending on time constraints in the maintenance window.

The table below illustrates the correlation between the cluster updates and upgrade to Ubuntu 24.04 to help you effectively plan and perform the upgrade.

Correlation between cluster updates and upgrade to Ubuntu 24.04
Management cluster version	MOSK cluster version	Default Ubuntu version	Key impact	Action required
2.32.0	26.2 26.1	24.04	No impact	The management cluster update to 2.32.0 is blocked if at least one node of any related MOSK 26.1.x cluster is running Ubuntu 22.04.
2.31.0	26.1	24.04	No impact	Strongly recommended to upgrade Ubuntu on all MOSK cluster nodes during the course of the MOSK 26.1.x series. [0]

To upgrade an OS distribution on MOSK between releases:

Note

This procedure applies only to MOSK 26.1 clusters that are still running Ubuntu 22.04, which Mirantis no longer supports.

Caution

A machine reboot occurs automatically during distribution update.

Open the required Machine object for editing.
In spec:providerSpec:value:distribution, set the required ID of the new OS version. For example, ubuntu/noble.

For description of the Machine object fields, see Machine resource.

The machine reboot occurs automatically after completion of deployment phases.
Once the distribution upgrade completes, verify that currentDistribution matches the distribution value previously set in the object spec. For description of the status fields, see Machine status.
Repeat the procedure with the remaining machines.
Strongly recommended. Back up the Kubernetes underlay as described in Create backups of the Kubernetes underlay.

Since the procedure above modifies the cluster configuration, a fresh backup is required to restore the cluster in case further reconfigurations fail.

Important

Because the restoration process is complicated, we strongly recommend contacting Mirantis support for assistance.
Important

If you still decide to restore the Kubernetes underlay from a backup on your own, you must scale down helm-controller on the cluster being restored if the Kubernetes underlay version of the affected cluster after the restore will differ from the Kubernetes underlay version in the ClusterRelease object that is set in Cluster objects in the management cluster:
- If you are restoring k0s on a management cluster: before starting the restore, scale down helm-controller on each affected MOSK cluster. This prevents unintended Ceph and OpenStack downgrades on MOSK clusters after the management cluster is restored.
- If you are restoring MKE on a MOSK cluster: immediately after the restore completes, scale down helm-controller. Because the restore rolls the cluster back to an older release, this prevents it from triggering a premature upgrade of Helm releases.