containerd 2.x 配置Harbor私有镜像仓库详解：与1.x版本的核心区别

在最新的操作系统中，默认安装的 containerd 通常已是 2.x 版本。与 1.x 版本相比，其配置私有镜像仓库（如 Harbor）的方法有显著变化。如果你的环境仍在使用 containerd 1.x，可以参考旧文进行配置。

本文将详细演示如何在 containerd 2.x 中正确配置 Harbor 私有镜像仓库。

1 配置结构

在 containerd 2.x 版本中，所有镜像仓库的配置都集中存放在 /etc/containerd/certs.d/ 目录下。

核心配置逻辑：

• 一个仓库地址对应一个目录：例如 harbor.example.com
• 一个目录对应一个配置文件：即该目录下的 hosts.toml 文件
• 在 hosts.toml 中定义：服务器地址、认证信息以及是否跳过 TLS 验证等

2 配置实战

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

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

确认版本后，开始配置。以 Harbor 地址 harbor.liyb.com 为例。

第一步：创建对应的配置目录
目录名称必须与你在拉取/推送镜像时使用的仓库地址（域名或IP）完全一致。

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

第二步：创建并编辑 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：此设置跳过了 TLS 证书验证，适用于使用自签名证书的 Harbor 环境。
• 若你的 Harbor 使用的是受信任的 CA 签发的证书，不应设置 skip_verify，而需将对应的 CA 证书文件（如 ca.crt）放置于 /etc/containerd/certs.d/harbor.liyb.com/ 目录下。

第三步：确认主配置（通常无需修改）
containerd 2.x 默认已启用上述配置路径，但生产环境建议检查主配置文件 /etc/containerd/config.toml 以确保无误：

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

3 验证配置

配置完成后，可以通过以下两种方式验证。

使用 nerdctl 拉取镜像：

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

在 Kubernetes 节点上使用 crictl 拉取镜像：

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

关键提示：镜像名称必须完整包含仓库地址（如 harbor.liyb.com/prod/nginx:1.27），这是使用 containerd 作为容器运行时时的常见要求。

4 常见问题与排查要点

在配置过程中，以下几个是最容易导致失败的“坑”：

1. hosts.toml 配置不生效

   • 原因：/etc/containerd/certs.d/ 下创建的目录名错误。必须与 docker pull/push 或 Pod 中 image 字段使用的仓库地址完全一致（包括端口号，如果有）。

2. 无法拉取 HTTP 协议的仓库镜像

   • 原因：在 hosts.toml 的 server 和 host 配置中，地址必须明确指定协议，例如 server = "http://my-registry:5000"。如果仓库未启用 HTTPS，却配置了 https://，会导致连接失败。

3. Kubernetes Pod 拉取镜像失败

   • 原因：Pod 定义中 spec.containers[].image 字段未使用带仓库地址的全路径镜像名。例如，必须写 harbor.liyb.com/nginx:latest，而不能只写 nginx:latest。

4. 误以为 Docker 的 daemon.json 对 containerd 生效

   • 关键区别：containerd 不读取 Docker 的配置文件 (/etc/docker/daemon.json)。所有仓库配置均需按照上述方法在 /etc/containerd/certs.d/ 目录下进行，这是在向 Kubernetes 集群部署应用时需要特别注意的一点。

正确理解并区分 containerd 2.x 的配置方式，是保障容器化应用，特别是在 云原生 环境中顺畅交付的关键一步。