问题处理-containerd拉取镜像失败，containerd镜像加速

问题描述

k8s环境常见containerd和docker作为运行时。
受限中国地区网络限制，使用时大多需要配置加速。
受限部分机房无海外宽带，只能配置代理服务器或单独的镜像加速。
k8s环境中，需要给所有物理节点配置加速。

说明

本方法适用于发布时间2021年至2025年的所有containerd版本，后续新版本未知，以参考资料描述为准。

本文不涉及docker加速，关于docker加速请直接访问以下资源。

shell 复制代码

https://1ms.run/  
https://docker.xuanyuan.me/

参考资料

github.com/containerd/...

github.com/containerd/...

github.com/containerd/...

help.aliyun.com/zh/acr/user...

操作流程

查询环境

假设我不知道当前k8s环境用的什么容器运行时。

bash 复制代码

root@master:~# kubectl get node -A -o wide

NAME     STATUS   ROLES                  AGE    VERSION    INTERNAL-IP    EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION      CONTAINER-RUNTIME

master   Ready    control-plane,worker   132d   v1.24.17   192.168.0.8    <none>        Ubuntu 22.04.1 LTS   5.15.0-43-generic   containerd://1.7.13

node1    Ready    worker                 132d   v1.24.17   192.168.0.9    <none>        Ubuntu 22.04.1 LTS   5.15.0-43-generic   containerd://1.7.25

node2    Ready    worker                 132d   v1.24.17   192.168.0.10   <none>        Ubuntu 22.04.1 LTS   5.15.0-43-generic   containerd://1.7.25

查询到runtime是containerd。从2021年开始，containerd推荐采用方法2配置。方法1也可用。

方法1：配置单个条目加速

此方法适合低版本containerd。

若加速失败，需手动替换新的加速地址。

备份配置文件

bash 复制代码

cp /etc/containerd/config.toml /etc/containerd/config.toml.bak

编辑配置文件

bash 复制代码

vim /etc/containerd/config.toml

关键配置,其他配置不改动，"docker.io"是被加速地址，"https://docker.1ms.run"是提供加速的地址。

bash 复制代码

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
       endpoint = ["https://docker.1ms.run"]

重启生效

bash 复制代码

root@master:~# systemctl restart containerd.service && systemctl status containerd.service

(推荐)方法2：配置专属文件加速

适合新版本containerd，2021年以后下载的containerd均可使用。

此方法不能与方法1混用。混用会导致镜像服务异常。

全新配置

备份配置文件

bash 复制代码

cp /etc/containerd/config.toml /etc/containerd/config.toml.bak

编辑配置文件

bash 复制代码

vim /etc/containerd/config.toml

关键配置。

bash 复制代码

[plugins."io.containerd.grpc.v1.cri".registry]

   config_path = "/etc/containerd/certs.d"

配置专用加速目录

bash 复制代码

root@node2:~# cd /etc/containerd/certs.d

root@node2:/etc/containerd/certs.d# ll

total 16

drwxr-xr-x 4 root root 4096 Jun 16 16:07 ./

drwxr-xr-x 3 root root 4096 Jun 23 10:36 ../

drwxr-xr-x 2 root root 4096 Jun 16 16:08 192.168.0.17:5000/

drwxr-xr-x 2 root root 4096 Mar  7 13:26 harbor.cmp.local/

root@node2:/etc/containerd/certs.d# mkdir docker.io

root@node2:/etc/containerd/certs.d# cd docker.io/

root@node2:/etc/containerd/certs.d/docker.io# vim hosts.toml

root@node2:/etc/containerd/certs.d/docker.io# ll

total 12

drwxr-xr-x 2 root root 4096 Jun 23 10:39 ./

drwxr-xr-x 5 root root 4096 Jun 23 10:37 ../

-rw-r--r-- 1 root root  103 Jun 23 10:39 hosts.toml

修改配置文件

bash 复制代码

root@node2:/etc/containerd/certs.d/docker.io# cat hosts.toml

server = "https://docker.io"

[host."https://docker.xuanyuan.me"]
  capabilities = ["pull", "resolve"]

[host."https://docker.1ms.run"]
  capabilities = ["pull", "resolve"]

https://docker.io是被加速的镜像仓库地址。
https://docker.xuanyuan.me和https://docker.1ms.run是提供加速服务的地址。一个被加速地址，可以配置多个加速地址。
"pull", "resolve"表示对仓库的可操作权限，若是私有仓库或公有云仓库，可配置push权限。

重启生效

bash 复制代码

root@node2:/etc/containerd/certs.d/docker.io# systemctl restart containerd.service && systemctl status containerd.service

改造

若原配置文件使用方法1配置的加速，现期望使用方法2，需改造方法1的配置文件。备份配置文件

bash 复制代码

cp /etc/containerd/config.toml /etc/containerd/config.toml.bak

编辑配置文件

bash 复制代码

vim /etc/containerd/config.toml

原文件关键配置

bash 复制代码

 [plugins."io.containerd.grpc.v1.cri".registry]
      config_path = ""

      [plugins."io.containerd.grpc.v1.cri".registry.auths]

      [plugins."io.containerd.grpc.v1.cri".registry.configs]
        [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]
          ca_file = "/etc/containerd/certs.d/harbor.cmp.local/server.crt"

      [plugins."io.containerd.grpc.v1.cri".registry.headers]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
        [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
          endpoint = ["https://docker.1ms.run"]
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.cmp.local"]
           endpoint=["https://harbor.cmp.local"]

修改后关键配置，其他不改动，除非有需求。可直接删除注释的行，也可仅注释。

bash 复制代码

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

      [plugins."io.containerd.grpc.v1.cri".registry.auths]

      [plugins."io.containerd.grpc.v1.cri".registry.configs]
      #    [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]
       #     ca_file = "/etc/containerd/certs.d/harbor.cmp.local/server.crt"

      [plugins."io.containerd.grpc.v1.cri".registry.headers]

      [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
        #   [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
         #         endpoint = ["https://docker.1ms.run"]
          # [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.cmp.local"]
           #  endpoint=["https://harbor.cmp.local"]

原配置的[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]，表示对"docker.io"进行加速，在下述目录，需创建目录docker.io。如果自己有多个类似条目，就配置多个目录。

bash 复制代码

root@master:/etc/containerd/certs.d# ll
total 20
drwxr-xr-x 5 root root 4096 Jun 23 11:24 ./
drwxr-xr-x 3 root root 4096 Jun 23 13:48 ../
drwxr-xr-x 2 root root 4096 May 22 14:04 dockerhub.kubekey.local/
drwxr-xr-x 2 root root 4096 Jun 23 11:25 docker.io/
drwxr-xr-x 2 root root 4096 May 22 14:04 harbor.cmp.local/

配置加速

bash 复制代码

root@master:/etc/containerd/certs.d# cd docker.io/
root@master:/etc/containerd/certs.d/docker.io# ll
total 12
drwxr-xr-x 2 root root 4096 Jun 23 11:25 ./
drwxr-xr-x 5 root root 4096 Jun 23 11:24 ../
-rw-r--r-- 1 root root  357 Jun 23 11:25 hosts.toml
root@master:/etc/containerd/certs.d/docker.io# cat hosts.toml 
server = "https://docker.io"

[host."https://docker.xuanyuan.me"]
  capabilities = ["pull", "resolve"]

[host."https://https://docker.1ms.run"]
  capabilities = ["pull", "resolve"]

原配置里的harbor.cmp.local，参考下述配置，原配置的[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]，提到了crt文件的路径。

bash 复制代码

root@master:/etc/containerd/certs.d# cd harbor.cmp.local/
root@master:/etc/containerd/certs.d/harbor.cmp.local# ll
total 12
drwxr-xr-x 2 root root 4096 May 22 14:04 ./
drwxr-xr-x 5 root root 4096 Jun 23 11:24 ../
-rw-r--r-- 1 root root 1862 May 22 14:04 server.crt
root@master:/etc/containerd/certs.d/harbor.cmp.local# vim hosts.toml
root@master:/etc/containerd/certs.d/harbor.cmp.local# cat hosts.toml 
server = "https://harbor.cmp.local"

[host."https://harbor.cmp.local"]
  ca = "/etc/containerd/certs.d/harbor.cmp.local/server.crt"

重启生效

bash 复制代码

root@node2:/etc/containerd/certs.d/docker.io# systemctl restart containerd.service && systemctl status containerd.service

测试验证

拉取镜像验证加速效果。

bash 复制代码

root@master:/etc/containerd/certs.d/docker.io# crictl images | grep python
docker.io/apache/airflow                                                      2.8.4-python3.9                b5417559a64d9       395MB
docker.m.daocloud.io/apache/airflow                                           2.8.4-python3.9                b5417559a64d9       395MB
docker.io/library/python                                                      3-alpine                       f3abd857d733d       16.8MB
docker.xuanyuan.me/python                                                     3-alpine                       f3abd857d733d       16.8MB
root@master:/etc/containerd/certs.d/docker.io# crictl pull python:3.14.0b3-slim


Image is up to date for sha256:14033a58a41fa3929e3a7ce05904f8a412df5c1738acde0e0ac89ff47e779407
root@master:/etc/containerd/certs.d/docker.io# 
root@master:/etc/containerd/certs.d/docker.io# 
root@master:/etc/containerd/certs.d/docker.io# crictl images | grep python
docker.io/apache/airflow                                                      2.8.4-python3.9                b5417559a64d9       395MB
docker.m.daocloud.io/apache/airflow                                           2.8.4-python3.9                b5417559a64d9       395MB
docker.io/library/python                                                      3-alpine                       f3abd857d733d       16.8MB
docker.xuanyuan.me/python                                                     3-alpine                       f3abd857d733d       16.8MB
docker.io/library/python                                                      3.14.0b3-slim                  14033a58a41fa       44.7MB

特殊问题1：配置文件错误

若出现crictl使用异常，大多是配置加速后，因配置文件写错，导致服务启动，状态显示running，实际服务异常，并且有以下报错，

bash 复制代码

root@node2:/etc/containerd/certs.d/docker.io# crictl images
FATA[0000] validate service connection: validate CRI v1 image API for endpoint "unix:///run/containerd/containerd.sock": rpc error: code = Unimplemented desc = unknown service runtime.v1.ImageService

这是配置文件冲突导致的异常。

编辑配置文件

bash 复制代码

root@node2:/etc/containerd/certs.d/docker.io# vim /etc/containerd/config.toml

关键配置，其他配置不改动。在配置文件发现类似以下的配置，需要注释或者删除。其中， [plugins."io.containerd.grpc.v1.cri".registry.mirrors,[plugins."io.containerd.grpc.v1.cri".registry.configs]及其下面附属的配置需注释或删除。这些配置会导致镜像仓库配置冲突失效。

bash 复制代码

[plugins."io.containerd.grpc.v1.cri".registry.configs]

        #  [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]

         #   ca_file = "/etc/containerd/certs.d/harbor.cmp.local/server.crt"

      [plugins."io.containerd.grpc.v1.cri".registry.headers]

      [plugins."io.containerd.grpc.v1.cri".registry.mirrors]

          # [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]

           #  endpoint = ["https://docker.1ms.run"]

          # [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.cmp.local"]

           #  endpoint=["https://harbor.cmp.local"]

特殊问题2：加速通道异常

若出现拉取镜像异常的提示，应优先更换加速通道，或在其他测试环境验证加速通道是否可用。例如频繁拉取镜像导致加速通道拉黑了你的设备IP。你拉取镜像的访问量过大，导致镜像仓库触发网络安全防护。

其他

若有其他异常，可邮件联系zhuyifei.ruichuang@gmail.com