Migrate container runtime from Docker to containerd¶

Available since 2.28.4 (Cluster releases 17.3.4 and 16.3.4)

Caution

Due to the known issue 49678, the HostOSConfiguration object may not work as expected after migration to containerd. For details, see the issue description.

Migration of container runtime from Docker to containerd is implemented for existing management and managed clusters. The use of containerd allows for better Kubernetes performance and component update without pod restart when applying fixes for CVEs.

Note

On greenfield deployments, containerd is the default container runtime since Container Cloud 2.29.0 and MOSK 25.1. Before that, Docker remains the default option.

Precautions¶

Before the container runtime mirgation, consider the following precautions:

The migration involves machine cordoning and draining.
Cluster update is not allowed during migration to prevent machines from running different container runtimes. However, you can still scale clusters and replace nodes as required.
The migration is mandatory during the scope of Container Cloud 2.29.x. Otherwise, the management cluster update to Container Cloud 2.30.0 will be blocked.

Note

If you have not upgraded the operating system distribution on your machines to Jammy yet, Mirantis recommends migrating machines from Docker to containerd on managed clusters together with distribution upgrade to minimize the maintenance window.

In this case, ensure that all cluster machines are updated at once during the same maintenance window to prevent machines from running different container runtimes.

Upgrade container runtime between releases¶

The following procedure applies to both management and managed clusters.

Verify that the managed cluster is updated to the Cluster release 17.3.4 or later as described in Cluster update.

Note

Management clusters must be updated to the Cluster release 16.3.4 or later.
Verify that the managed cluster distribution is upgraded to Ubuntu Jammy as described in Upgrade an operating system distribution.
Open the required Machine object for editing.

You can schedule more than one machine for migration at the same time. In this case, the process is automatically orchestrated without service interruption.
In the metadata.annotations section, add the following annotation to trigger migration to containerd runtime:
```
apiVersion: cluster.k8s.io/v1alpha1
kind: Machine
metadata:
  name: example-machine
  namespace: example-ns
  annotations:
    kaas.mirantis.com/preferred-container-runtime: containerd
```
The machine will be cordoned and drained, and container runtime will be migrated.

For description of the Machine object fields, see Container Cloud API Reference: Machine object.
Once migration is completed, verify that ContainerRuntimeContainerd condition is true in status.providerStatus.

For description of the the Machine object status fields, see Container Cloud API Reference: Machine object status.
Repeat the procedure with the remaining machines.

Caution

If an emergency related to containerd occurs on workloads before migration is complete on all machines, you can temporarily roll back containerd to Docker. Use the procedure above by changing the kaas.mirantis.com/preferred-container-runtime annotation from containerd to docker.