Change your container runtime

GKE on Bare Metal adds the optional containerRuntime configuration field to the cluster configuration file. Use this field to configure the container runtime that cluster nodes use to schedule containers for Kubernetes pods.

You can have kubelet call the Container Runtime Interface directly. This option allows you to decouple kubelet from Docker by removing the need for the Docker daemon.

This change is needed due to Kubernetes' goals to deprecate the use of the Docker daemon and make containerd the default. Kubernetes plans to send warnings starting with Kubernetes version 1.20 and finalize the deprecation by version 1.24.This change aligns with the planned change to make containerd the default for GKE.

In GKE on Bare Metal, you can configure kubelet to use Docker or containerd through the new containerRuntime field.

Before you begin

  • Identify what container runtime you want your clusters to use. You can only change the value of the container runtime field when upgrading or installing a cluster.

  • 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 which are installed for both runtimes:

    • 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 certificates on your nodes depending on your chosen runtime:

    • For Docker: /etc/docker/certs.d/
    • For containerd:
      • /etc/docker/certs.d/
      • /etc/containerd/certs.d/

Configure the container runtime for a new cluster

To set your container runtime for a new cluster, set the containerRuntime field in the nodeConfig section under spec in your cluster configuration file. GKE on Bare Metal supports the following values:

  • docker
  • containerd

If the field is empty or not set, GKE on Bare Metal uses docker by default. To use containerd, the entry in your configuration should look similar to the following example:

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

Configure the container runtime when upgrading a cluster

You can configure GKE on Bare Metal to use a different container runtime when you upgrade. You can only change the value of the container runtime field when upgrading or installing a cluster.

Requirements

  • Upgrade admin clusters before user clusters
  • Set the value of the containerRuntime field in your configuration file before upgrading your clusters.

Change the runtime to containerd

To set your container runtime during an upgrade, set the containerRuntime field in the nodeConfig section under spec in your cluster configuration file. GKE on Bare Metal supports the following values:

  • docker
  • containerd

To use containerd, change your configuration file to look like the following example:

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

To set the container runtime of the cluster nodes to containerd as part of their upgrade, run the following command to upgrade your clusters:

bmctl upgrade cluster

Updating your clusters with containerd set as the runtime

If you set the container runtime to containerd, the following command updates the image registry certificates in /etc/containerd/certs.d/

bmctl update cluster

Resetting your clusters with containerd set as the runtime

If you set the container runtime to containerd, the following command doesn't delete configurations, binary files, or directories:

bmctl reset cluster

During reset the containerd service continues to run, but the containers that Kubernetes scheduled are stopped and removed from the containerd runtime.

Delete the following binary files and directories to complete the reset:

  • /etc/crictl.yaml
  • /etc/systemd/system/containerd.service
  • /etc/systemd/system/containerd.service.d/
  • /etc/containerd/config.toml
  • /etc/containerd/certs.d/

Check the status of the containerd runtime

To check the status of the containerd as part of the machine health check, run the following command:

systemctl status containerd