containerd 2.x 接入 Harbor 私有仓库：避坑配置全指南

本文将指导你如何在 containerd 2.x 版本中配置容器镜像仓库，以 Harbor 仓库的配置为例。

如今，不少操作系统在安装 containerd 时，若未明确指定，默认会采用 2.x 版本。其配置镜像仓库的方式与 1.x 版本有所不同。如果你的 containerd 仍是 1.x 版本，可以参考我之前的文章进行配置：

《快速配置 Containerd 镜像加速（附最新可用加速地址）》

接下来，我们将演示如何在 containerd 2.x 版本中配置镜像仓库，这里以 Harbor 仓库为例。

1. 配置结构

containerd 2.x 版本的所有镜像仓库配置均位于 /etc/containerd/certs.d/ 目录下。

其配置结构如下：

• 一个 registry 域名对应一个目录
• 一个目录内包含一个 hosts.toml 文件
• 在 hosts.toml 文件中定义：服务器地址、认证信息、以及是否跳过证书验证

2. 配置实战

首先，确认你的 containerd 是否为 2.x 版本：

[root@k8s-master ~]# containerd --version
containerd containerd.io v2.2.0 1c4457e00facac03ce1d75f7b6777a7a851e5c41

创建对应的配置目录：

mkdir -p /etc/containerd/certs.d/harbor.liyb.com

目录名称必须与镜像操作中使用的 registry 地址完全一致。如果没有使用域名，直接使用 IP 地址作为目录名也是可以的。

创建 hosts.toml 配置文件：

vi /etc/containerd/certs.d/harbor.liyb.com/hosts.toml

添加以下配置内容：

server = "https://harbor.liyb.com"

[host."https://harbor.liyb.com"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true

  [host."https://harbor.liyb.com".auth]
    username = "admin"
    password = "Harbor12345"

由于我使用的是自签名证书，因此设置了跳过验证 (skip_verify = true)。如果你使用的是企业级有效证书，则无需设置此项，只需将 CA 证书文件放入 /etc/containerd/certs.d/harbor.liyb.com/ 目录即可。

接下来，需要去主配置文件 config.toml 中确认 config_path 的配置路径：

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

containerd 2.x 版本通常默认开启此配置，但在生产环境中务必进行检查确认。

3. 验证方式

可以使用 nerdctl 命令行工具进行验证：

nerdctl pull harbor.liyb.com/prod/nginx:1.27

也可以在 Kubernetes 节点上使用 crictl 验证：

crictl pull harbor.liyb.com/prod/nginx:1.27

请注意，镜像名称必须显式包含完整的 registry 地址。

4. 最容易踩的几个坑

hosts.toml 配置不生效 → 目录名称写错（域名或端口不一致）。

HTTP 仓库拉不下来 → 忘了写 http:// 协议头。

K8s Pod 拉不到镜像 → Image 字段没写 registry 地址。

误以为 daemon.json 生效 → containerd 不读取 Docker 的配置。