Change your container runtime

Google Distributed Cloud 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 Google Distributed Cloud, you can configure kubelet to use Docker or containerd through the new containerRuntime field. By default, kubelet uses containerd as the container runtime.

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. Google Distributed Cloud installs this version over any previously installed version of containerd.

  • Ensure Google Distributed Cloud 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 Google Distributed Cloud can install the following certificates on your nodes depending on your chosen runtime:

    • For containerd:
      • /etc/docker/certs.d/
      • /etc/containerd/certs.d/
    • For Docker: /etc/docker/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. Google Distributed Cloud supports the following values:

  • containerd
  • docker

If the field is empty or not set, Google Distributed Cloud uses containerd by default. To use Docker, 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: docker

Configure the container runtime when upgrading a cluster

You can configure Google Distributed Cloud 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 Docker

To set your container runtime during an upgrade, set the containerRuntime field in the nodeConfig section under spec in your cluster configuration file. Google Distributed Cloud supports the following values:

  • containerd
  • docker

To use Docker, 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: docker

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

bmctl upgrade cluster

Update your clusters with Docker set as the runtime

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

bmctl update cluster

Reset your clusters that use containerd as the runtime

If you use the default container runtime, 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/

If you are using Docker as your runtime, no cleanup is performed during reset.

Check the status of the runtime

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

systemctl status RUNTIME

Replace RUNTIME with your chosen runtime: containerd or docker.