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 errrpc 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直接重启containerd3.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 Harbor123455.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命令可以批量导入离线镜像包比依赖集群部署时的拉取更可靠。