containerd-主机目录模式匹配仓库地址与认证信息

注：Containerd >= v1.5.0 必须使用主机目录模式 （传统config.toml直配模式已弃用）

       生产环境必须启用TLS加密认证， 避免 skip_verify = true  降低安全性

 

匹配机制‌

containerd 通过 ‌域名路径映射‌ 动态匹配镜像仓库地址：

1. ‌域名解析规则‌：

   • 拉取镜像时，containerd 解析镜像域名（如 docker.io），自动匹配 /etc/containerd/certs.d/ 下的同名目录。
   • ‌匹配路径‌：镜像域名 → /etc/containerd/certs.d/<域名>/hosts.toml。
   • ‌示例‌：
     • nginx:latest（默认 docker.io/library/nginx）→ 匹配 /etc/containerd/certs.d/docker.io/hosts.toml。
     • harbor.example.com/app:v1 → 匹配 /etc/containerd/certs.d/harbor.example.com/hosts.toml。

2. ‌目录命名要求‌：

   ‌镜像地址‌	‌配置文件路径‌
   docker.io	/etc/containerd/certs.d/docker.io/hosts.toml
   192.168.1.100:5000	/etc/containerd/certs.d/192.168.1.100:5000/hosts.toml
   ‌关键点‌：目录名需与镜像地址的 ‌完整域名或 IP + 端口‌ 严格一致（含端口号）。

---

⚙️ ‌配置步骤‌

1. ‌启用主机目录模式‌

编辑 /etc/containerd/config.toml，添加：

 

[plugins."io.containerd.grpc.v1.cri".registry] config_path = "/etc/containerd/certs.d" # 指定配置根目录

重启服务生效：

 

systemctl restart containerd

 

2. ‌创建仓库配置目录与文件‌

以私有仓库 harbor.example.com 为例：

 

# 创建目录（目录名严格匹配仓库地址） mkdir -p /etc/containerd/certs.d/harbor.example.com # 创建配置文件 touch /etc/containerd/certs.d/harbor.example.com/hosts.toml

 

3. ‌配置 hosts.toml 文件‌

• ‌基础模板（HTTPS 仓库）‌：

   
  server = "https://harbor.example.com" # 仓库主地址 [host."https://harbor.example.com"] # 端点声明 capabilities = ["pull", "push", "resolve"] # 操作权限

   

• ‌增强安全配置（TLS 证书）‌：

   
  [host."https://harbor.example.com"] capabilities = ["pull", "push"] ca = "/path/to/ca.crt" # CA 证书路径 client = [ # 客户端证书（可选） ["/path/to/client.crt", "/path/to/client.key"] ]

   

• ‌HTTP 非安全仓库‌：

   
  [host."http://192.168.1.100:5000"] # 显式声明 http 协议 capabilities = ["pull", "push"] skip_verify = true # 跳过 TLS 验证（生产环境慎用）

   

4. 验证配置效果

#使用 crictl 测试拉取镜像

crictl pull harbor.example.cn/app:v1

 

# 查看containerd 日志排查错误

journalctl -u containerd | grep -i "failed to resolved"

 

关键排查点：

• 目录名是否与镜像余名 严格一致（区分大小写）
• hosts.toml  中 server 地址是否包含协议头部 （https://  或  http://）
• TLS证书文件权限是否可读 （建议 chmod 644 *.crt）

---

⚠️ ‌注意事项‌

1. ‌协议声明强制要求‌：
   • HTTP 仓库必须在 URL 中显式指定 http://，否则默认尝试 HTTPS。
2. ‌调试技巧‌：
   • 拉取失败时，检查日志：journalctl -u containerd --since "5 min ago"，排查 TLS/认证错误。
3. ‌多仓库优先级‌：
   • containerd 优先匹配目录路径，未匹配时回退默认行为（如直连 Docker Hub）。

---

✅ ‌验证配置‌

bashCopy Code

 

# 拉取镜像测试 ctr image pull harbor.example.com/library/nginx:latest # 查看镜像 ctr images ls | grep nginx

‌成功标志‌：镜像拉取无报错，且出现在本地镜像列表613。

‌生产建议‌：

• 优先使用 ‌HTTPS + 证书认证‌ 确保传输安全；
• HTTP 仅限内网测试环境，并设置 skip_verify = true 明确忽略 TLS