Upgrade an operating system distribution

Available since MCC 2.24.0 (14.0.0)

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 since Container Cloud 2.24.0 (Cluster release 14.0.0) as part of cluster update and requires machines reboot. The upgrade workflow is as follows:

  1. The distribution ID value is taken from the id field of the distribution from the allowedDistributions list in the spec of the ClusterRelease object.

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

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

Correlation between cluster updates and upgrade to Ubuntu 22.04

Management cluster version

MOSK cluster version

Default Ubuntu version

Key impact

Action required

2.28.5
24.3.0
24.3.1
24.3.2

22.04

No impact

  • Management cluster nodes are automatically upgraded to Ubuntu 22.04 during cluster upgrade to Container Cloud 2.27.0 (Cluster release 16.2.0)

  • Strongly recommended to upgrade Ubuntu on all MOSK cluster nodes. 0

2.29

25.1

22.04

MOSK cluster requires Ubuntu 22.04. Upgrade to 25.1 is blocked unless all cluster nodes are running on Ubuntu 22.04.

Upgrade all MOSK cluster nodes to Ubuntu 22.04 to unblock the MOSK cluster update to 25.1. 0

2.29.1

24.3.3

22.04

Management cluster update to 2.29.1 is blocked unless all nodes present in your deployment are running on Ubuntu 22.04.

Upgrade all nodes to Ubuntu 22.04 to unblock your management cluster update. 0
0(1,2,3)

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.

Caution

After the major cluster update, make sure to change the postponeDistributionUpdate parameter back to false unless you want to postpone new OS distribution upgrades.

Note

If you want to migrate container runtime on cluster machines from Docker to containerd and have not upgraded the OS distribution to Jammy yet, Mirantis recommends combining both procedures to minimize the maintenance window. In this case, ensure that all cluster machines are updated during one maintenance window to prevent machines from running different container runtimes.

Container runtime migration to containerd is available since Container Cloud 2.28.4 (Cluster releases 17.3.4 and 16.3.4). For details, see Migrate container runtime from Docker to containerd.

To upgrade an OS distribution on MOSK between releases:

Caution

A machine reboot occurs automatically during distribution update.

  1. Open the required Machine object for editing.

  2. In spec:providerSpec:value:distribution, set the required ID of the new OS version. For example, ubuntu/jammy.

    For description of the Machine object fields, see Container Cloud documentation: API Reference.

    The machine reboot occurs automatically after completion of deployment phases.

  3. 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 Container Cloud documentation: API Reference.

  4. Repeat the procedure with the remaining machines.

  5. Optional. Available since Container Cloud 2.28.4 (Cluster releases 17.3.4 and 16.3.4). Upgrade container runtime from Docker to containerd together with distribution upgrade as described in Migrate container runtime from Docker to containerd to minimize the size of maintenance window.

    Note

    Container runtime migration becomes mandatory in the scope of Container Cloud 2.29.x. Otherwise, the management cluster update to Container Cloud 2.30.0 will be blocked.

See also

Cluster update