How to configure containerd to use a registry mirror?

Question

If a system (e.g., a kubernetes node) is using containerd, how do I configure it to pull container images from a registry mirror instead of docker.io?

Answer 1

The answer seems to depend on version, but for 1.6+:

First, ensure that /etc/containerd/config.toml sets:

plugins."io.containerd.grpc.v1.cri".registry.config_path = "/etc/containerd/certs.d"

Second, create /etc/containerd/certs.d/docker.io/hosts.toml (and intervening directories as necessary) with content:

server = "https://registry-1.docker.io"  # default after trying hosts
host."https://my-local-mirror".capabilities = ["pull", "resolve"]

(May need to restart containerd after modifying the first file? systemctl restart containerd Updates to the second path should be detected without restart.)

Note that earlier version 1.4 (e.g., in amazon-eks-ami up until a couple months ago) used a quite different method to configure the mirror.

---

If these changes are being automated, such as in a launch template user data script, the commands could be as follows. Note the escaping of quotation marks, and which side of the pipe needs extra privileges.

sudo mkdir -p /etc/containerd/certs.d/docker.io
echo 'plugins."io.containerd.grpc.v1.cri".registry.config_path = "/etc/containerd/certs.d"' | sudo tee -a /etc/containerd/config.toml
printf 'server = "https://registry-1.docker.io"\nhost."http://my-local-mirror".capabilities = ["pull", "resolve"]\n' | sudo tee /etc/containerd/certs.d/docker.io/hosts.toml
sudo systemctl restart containerd

---

For more recent installations, may not need to modify config.toml (i.e. if default already set appropriately). Also, may not need to use sudo depending on where these commands are run from (such as in a launch template, for AWS EC2).