KubeKey离线部署K8s集群，containerd死活拉不了私有镜像？手把手教你搞定证书认证
KubeKey离线部署K8s集群：彻底解决containerd私有镜像拉取认证问题
在离线环境中使用KubeKey部署Kubernetes集群时，containerd运行时无法拉取私有镜像仓库中的镜像是一个常见痛点。特别是当私有仓库使用自签名证书时，反复出现的x509: certificate signed by unknown authority错误会让部署流程陷入停滞。本文将深入解析问题根源，并提供一套完整的解决方案。
1. 问题诊断与根源分析
当执行kk create cluster命令时，如果遇到类似以下的错误日志，表明containerd无法验证私有镜像仓库的TLS证书：
E0528 12:13:49.009936 1166 remote_image.go:180] "PullImage from image service failed" err="rpc error: code = Unknown desc = failed to pull and unpack image \"dockerhub.kubekey.local/kubesphereio/pause:3.9\": failed to resolve reference \"dockerhub.kubekey.local/kubesphereio/pause:3.9\": failed to do request: Head \"https://dockerhub.kubekey.local/v2/kubesphereio/pause/manifests/3.9\": tls: failed to verify certificate: x509: certificate signed by unknown authority"关键诊断步骤：
手动验证仓库可访问性：
curl -vk https://dockerhub.kubekey.local/v2/观察输出中的证书验证结果：
* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.检查containerd日志：
sudo journalctl -u containerd -f重点关注包含
tls: failed to verify certificate的错误条目直接使用crictl测试：
sudo crictl pull dockerhub.kubekey.local/kubesphereio/pause:3.9
问题本质：containerd默认要求严格的TLS证书验证，而自签名证书不在系统信任链中。这与Docker的行为不同，Docker可以通过insecure-registries配置更简单地绕过证书验证。
2. containerd证书信任机制详解
containerd处理镜像拉取的证书验证涉及多个配置层级：
| 配置层级 | 作用域 | 关键参数 | 持久性 |
|---|---|---|---|
| 全局系统证书 | 所有HTTPS请求 | /etc/ssl/certs | 高 |
| containerd主配置 | 所有registry请求 | config.toml中的registry配置 | 中 |
| 单次命令参数 | 当前命令 | --plain-http标志 | 低 |
证书查找路径：
- 首先检查
/etc/containerd/certs.d/<registry>/下的CA证书 - 然后检查系统默认证书存储(
/etc/ssl/certs) - 最后根据
config.toml中的insecure_skip_verify设置决定是否跳过验证
注意：containerd v1.5+版本开始，推荐使用
config_path替代直接配置，但大多数生产环境仍使用传统配置方式。
3. 完整解决方案：配置containerd信任私有仓库
3.1 方法一：跳过特定仓库的TLS验证（推荐）
这是最常用的解决方案，具体操作步骤如下：
编辑containerd主配置文件：
sudo vim /etc/containerd/config.toml在
[plugins."io.containerd.grpc.v1.cri".registry]部分添加以下内容：[plugins."io.containerd.grpc.v1.cri".registry.mirrors."dockerhub.kubekey.local"] endpoint = ["https://dockerhub.kubekey.local"] [plugins."io.containerd.grpc.v1.cri".registry.configs."dockerhub.kubekey.local".tls] insecure_skip_verify = true完全重启containerd服务：
sudo systemctl stop containerd sudo rm -f /run/containerd/containerd.sock sudo systemctl start containerd验证配置是否生效：
sudo crictl info | jq .config.registry应该能看到类似输出：
{ "configs": { "dockerhub.kubekey.local": { "tls": { "insecure_skip_verify": true } } } }
3.2 方法二：添加CA证书到系统信任链（更安全）
如果希望保持TLS验证但信任自签名证书，可以：
获取私有仓库的CA证书，保存到：
sudo mkdir -p /etc/containerd/certs.d/dockerhub.kubekey.local sudo cp harbor-ca.crt /etc/containerd/certs.d/dockerhub.kubekey.local/ca.crt或者添加到系统证书库：
sudo cp harbor-ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates无需设置
insecure_skip_verify，直接重启containerd
3.3 方法三：临时解决方案（仅测试用）
对于快速测试，可以使用ctr命令直接跳过验证：
sudo ctr --address /run/containerd/containerd.sock images pull \ --plain-http \ dockerhub.kubekey.local/kubesphereio/pause:3.9警告：此方法不会持久化配置，仅适用于临时测试，生产环境请使用前两种方法。
4. KubeKey集成与验证
完成containerd配置后，需要确保KubeKey能够正确使用这些设置：
检查
config.yaml中的相关配置：registry: privateRegistry: "dockerhub.kubekey.local" insecureRegistries: ["dockerhub.kubekey.local"] skipTLSVerify: true重新运行集群部署命令：
./kk create cluster -f config-sample.yaml -a kubesphere.tar.gz --with-local-storage验证节点上的镜像是否正常拉取：
sudo crictl images
常见问题排查表：
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 配置修改后仍报证书错误 | 配置未生效 | 彻底重启containerd并删除旧socket |
| 部分节点可以拉取，部分不行 | 配置未同步到所有节点 | 确保所有节点containerd配置一致 |
| 能拉取镜像但无法创建Pod | 镜像路径不正确 | 检查privateRegistry和namespaceOverride配置 |
5. 高级配置与最佳实践
5.1 多仓库配置示例
对于需要访问多个私有仓库的环境，config.toml可以这样配置：
[plugins."io.containerd.grpc.v1.cri".registry] config_path = "" [plugins."io.containerd.grpc.v1.cri".registry.mirrors] [plugins."io.containerd.grpc.v1.cri".registry.mirrors."dockerhub.kubekey.local"] endpoint = ["https://dockerhub.kubekey.local"] [plugins."io.containerd.grpc.v1.cri".registry.mirrors."internal.registry.com"] endpoint = ["https://internal.registry.com"] [plugins."io.containerd.grpc.v1.cri".registry.configs] [plugins."io.containerd.grpc.v1.cri".registry.configs."dockerhub.kubekey.local".tls] insecure_skip_verify = true [plugins."io.containerd.grpc.v1.cri".registry.configs."internal.registry.com".auth] username = "admin" password = "Harbor12345"5.2 配置持久化技巧
为避免升级或重置后配置丢失，建议：
备份原始配置：
sudo cp /etc/containerd/config.toml /etc/containerd/config.toml.bak创建配置片段：
sudo mkdir -p /etc/containerd/conf.d sudo vim /etc/containerd/conf.d/registry.conf在主配置中添加：
imports = ["/etc/containerd/conf.d/*.conf"]
5.3 性能优化建议
对于大型离线环境：
配置本地镜像缓存：
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."dockerhub.kubekey.local"] endpoint = ["https://dockerhub.kubekey.local", "http://localhost:5000"]调整并行下载数：
[plugins."io.containerd.grpc.v1.cri"] max_concurrent_downloads = 5
在实际项目中，我发现最稳妥的做法是在部署前先在所有节点上预加载必要的镜像，这可以避免部署过程中的网络问题。使用ctr images import命令可以批量导入离线镜像包，比依赖集群部署时的拉取更可靠。