Version 1.12. This version is no longer supported. For more information, see the version support policy. For information about how to upgrade to version 1.13, see Upgrading Anthos on bare metal in the 1.13 documentation.

Available supported versions: 1.28 | 1.16 | 1.15

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 GKE 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 GKE 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 GKE 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. GKE on Bare Metal installs this version over any previously installed version of containerd.
Ensure GKE 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 GKE 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 GKE 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.

Known issue for containerd

GKE on Bare Metal release 1.12.1 ships with containerd version 1.5.13. This version of containerd requires libseccomp version 2.5 or higher.

If your system doesn't have <libseccomp version 2.5 or higher installed, update it in advance of upgrading existing clusters to version 1.12.1. Otherwise, you may see errors in cplb-update Pods for load balancer nodes, such as the following:

runc did not terminate successfully: runc: symbol lookup error: runc: undefined
symbol: seccomp_notify_respond

To install the latest version of libseccomp in Ubuntu:

Run the following command:
```
sudo apt-get install  libseccomp-dev
```

To install the latest version of libseccomp in RHEL:

Run the following command:
```
sudo dnf -y install libseccomp-devel
```