Migrate Container Runtime From Docker To Containerd

Introduction

In this article, we discuss how to migrate an existing cluster's container runtime from Docker to containerd. Kubernetes is in the process of deprecating Dockershim as a container runtime. Kubernetes has scheduled the total depreciation and removal of Dockershim container runtime in Kubernetes v1.24. Docker format container images will continue to work in your cluster with all runtimes and do not need to be changed.

Container runtime can only be changed as part of an upgrade

The runtime in use by an existing cluster can only be changed as part of a cluster upgrade.

Should you have any issues with migrating to containerd, reach out to our support team for more information.

Upgrade Requirements

The following requirements must be met before migrating a cluster from Docker to containerd.

Kubernetes Version

To migrate to containerd, the Kubernetes cluster must be running version 1.20 and upgrading to 1.21. Or running 1.21 and upgrading to any newer version, patch, or minor.

Ubuntu

There are no new requirements for Platform9 Managed Kubernetes clusters running on Ubuntu OS.

CentOS

We observed multiple issues when configuring devicemapper on CentOS with containerd. Due to these issues, Platform9 no longer supports devicemapper on CentOS for containerd.

The replacement of devicemapper is overlayfs which defaults to overlay2 (if available) with containerd on CentOS, similar to Ubuntu.

Migrate from devicemapper to overlayfs

To be able to migrate to overlayfs on CentOS, with following requirements must be met -

• kernel version >= 3.10.0-514

• If the underlying file system is xfs, then d_type=true must be enabled. To check if d_type=true is enabled, run the following command.

xfs_info <mount point>
## If the output shows ftype=1 then d_type is enabled

SAMPLE OUTPUT
xfs_info /
meta-data=/dev/vda1              isize=512    agcount=51, agsize=524224 blks
         =                       sectsz=512   attr=2, projid32bit=1
         =                       crc=1        finobt=0 spinodes=0
data     =                       bsize=4096   blocks=26214139, imaxpct=25
         =                       sunit=0      swidth=0 blks
naming   =version 2              bsize=4096   ascii-ci=0 ftype=1
log      =internal               bsize=4096   blocks=2560, version=2
         =                       sectsz=512   sunit=0 blks, lazy-count=1
realtime =none                   extsz=4096   blocks=0, rtextents=0

To create a xfs file system with `d_type=true -` run the following command.

Bash

mkfs -t xfs -n ftype=1 /PATH/TO/DEVICE

Info

The XFS filesystems must be created with the -n ftype=1 option enabled for use as an overlay. With the rootfs and any file systems created during system installation, set the --mkfsoptions=-n ftype=1 parameters in the Anaconda kickstart. When creating a new file system after the installation, run the command mkfs -t xfs -n ftype=1 /PATH/TO/DEVICE.

Determine if an existing file system supports overlay

To determine whether an existing file system is eligible for use as an overlay, run this command.

Bash

xfs_info /PATH/TO/DEVICE | grep ftype

This will show if the ftype=1 option is enabled. See reference in Chapter 21 in the File Systems Red Hat Enterprise Linux 7 | Red Hat Customer Portal.

Migrate to containerd

During a cluster upgrade, all containers are stopped, creating an opportunity at that point to change the container runtime. To migrate to containerd, you need to specify containerd as the container runtime during a cluster upgrade. The container runtime can only be changed for clusters running 1.20 upgrading to 1.21, or 1.21 clusters upgrading to 1.21.x and later.

Upgrade using the Web App

During the cluster upgrade process, eligible clusters (1.20 and newer) will display a new dropdown menu option to select containerd as the container runtime within the “Select a Container Runtime” card. To migrate, select the containerd option from the menu and then proceed as usual with the upgrade. During the cluster upgrade, all containers will be replaced with containers running within containerd.

API Upgrade

When upgrading the cluster using the upgrade API process, it allows passing the container runtime in the request body.

API

curl -X POST \
  'https://<du fqdn>/qbert/v4/<keystone project ID>/clusters/<cluster UUID>/upgrade?type=minor' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: <keystone token>' \
  -H 'cache-control: no-cache' \
  -d '{
	"containerRuntime": "containerd"
}'

Warning

The update can only be run as part of a cluster upgrade. This runtime will fail if an attempt is made to modify the container runtime via the edit cluster API. Additionally, we do not support migrating the runtime from containerd back to docker.

Backward Compatibility

Docker will remain the default container runtime until 1.23. When creating a new cluster, users can choose the type of container runtime to be used.