Migrate container runtime from Docker to containerd¶

Available since 2.28.4 (Cluster releases 17.3.4 and 16.3.4)

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.

Important

Container runtime migration involves machine cordoning and draining.

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.

Warning

Cluster update is not allowed during migration from Docker to containerd to prevent machines from running different container runtimes. However, you can still scale clusters and replace nodes as required.

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.

To upgrade container runtime between releases:

Note

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.

Note

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.

Note

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.

Note

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.