Change your container runtime from docker to containerd

Your clusters use a container runtime to create and run Kubernetes Pods. Before version 1.13 of Anthos clusters on bare metal, your container runtime could be either Docker Engine or containerd. However, your container runtime can only be containerd starting from version 1.13 of Anthos clusters on bare metal.

If your clusters use Docker Engine as the container runtime, you should change that container runtime to containerd. This page explains how to set your container runtime to containerd.

You specify the container runtime by setting the value of the containerRuntime field in the cluster configuration file. However, just setting or changing the value of this field isn't sufficient - you have to then create a new cluster or upgrade an existing cluster for the change to take effect. In other words, you can only change your container runtime when you create a new cluster or when you upgrade an existing cluster.

Kubernetes 1.24 ends support of Docker Engine

The dockershim component in Kubernetes enables cluster nodes to use the Docker Engine container runtime. However, Kubernetes 1.24 removed the dockershim component. Since Anthos clusters on bare metal version 1.13 will run on Kubernetes 1.24, version 1.13 and higher clusters can no longer use Docker Engine as a container runtime.

When upgrading or creating clusters, note the following container runtime rules:

You must use containerd for version 1.13 clusters and higher.
You can't create version 1.12 clusters that use the Docker Engine container runtime.
You can upgrade a 1.11 cluster that uses Docker Engine to a 1.12 cluster that uses Docker Engine. However, we strongly recommend that you switch to containerd before upgrading.

The Docker installation that you use in development to create images is unrelated to the Docker Engine container runtime inside your Kubernetes cluster. You can still use Docker to create images and build application containers. Those containers will still work inside your cluster.

You must continue to install Docker on your admin workstation because the bmctl command requires Docker for operations, such as cluster creation. This use of Docker is also unaffected by the dockershim deprecation.

For detailed instructions on how to change your container runtime from docker to containerd, see the following sections.

Before you begin

Keep in mind that when upgrading a cluster, you must upgrade the admin cluster before you upgrade user clusters.
Ensure your deployment supports containerd version 1.4.6 or later. Anthos clusters on bare metal installs this version over any previously installed version of containerd.
Ensure Anthos clusters on bare metal can install the following files:
- Binary files
  - /usr/bin/containerd
  - /usr/bin/containerd-shim
  - /usr/bin/containerd-shim-runc-v1
  - /usr/bin/containerd-shim-runc-v2
  - /usr/bin/crictl
  - /usr/bin/ctr
  - /usr/local/sbin/runc
- Configuration files
  - /etc/crictl.yaml
  - /etc/systemd/system/containerd.service
  - /etc/containerd/config.toml
  - /etc/containerd/certs.d/
  - /etc/systemd/system/containerd.service.d/09-proxy.conf This file is only installed if you configure an HTTP proxy.
Ensure Anthos clusters on bare metal can install the following certificate on your nodes: /etc/containerd/certs.d/

Set `containerd` as the container runtime for a new cluster

If the spec.nodeConfig section of your cluster configuration file is empty or not set, the container runtime of the cluster is automatically set to containerd when a new cluster is created.

However, if you want to explicitly set containerd as the container runtime for a new cluster, set the containerRuntime field to containerd in the spec.nodeConfig section of the cluster configuration file. After doing so, your cluster configuration should look something like this:

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
spec:
  nodeConfig:
    containerRuntime: containerd

When you use this cluster configuration file to create a new cluster, the container runtime will be containerd.

Change container runtime from `docker` to `containerd` when upgrading a cluster

To change your container runtime from docker to containerd when upgrading a cluster, complete the following steps:

Change the containerRuntime field from docker to containerd in the spec.nodeConfig section of the cluster configuration file. After doing so, your cluster configuration should look something like this:
```
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
spec:
  nodeConfig:
    containerRuntime: containerd
```
Run the following command to upgrade your cluster:
```
bmctl upgrade cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
```
Replace the following:
- CLUSTER_NAME with the name of the cluster you want to update.
- ADMIN_KUBECONFIG with the path of the admin cluster's kubeconfig file.

Check the status of the container runtime

To check the status of the container runtime, run the following command:

systemctl status containerd

Change container runtime from `containerd` to `docker` when upgrading a cluster

You can use either container runtime when upgrading from Anthos clusters on bare metal version 1.11 to 1.12. However, we strongly recommend that you use containerd because the Docker Engine container runtime isn't supported for version 1.13.0 and higher.