Migrate Container Runtime From Docker to Containerd During Upgrade

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.

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.

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.

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.

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"

}'

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.