解决k8s集群中containerd运行时拉取HTTP私有Harbor镜像的配置难题

1. 为什么需要配置HTTP私有Harbor镜像拉取最近在帮客户部署Kubernetes集群时遇到了一个典型问题使用containerd作为容器运行时无法从内网HTTP协议的Harbor私有仓库拉取镜像。这个问题其实很常见特别是很多企业内网环境中出于各种考虑没有配置HTTPS证书。当Pod尝试拉取镜像时containerd默认会尝试HTTPS连接于是就会出现类似这样的报错Failed to pull image harbor.company.com/library/nginx:latest: failed to pull and unpack image... connection refused这里的关键点在于containerd作为新一代容器运行时对安全性要求更高默认只允许HTTPS连接。而很多内网环境中的Harbor仓库为了简化部署往往只配置了HTTP协议。这种安全性和便利性之间的矛盾就是我们今天要解决的核心问题。2. 配置前的准备工作2.1 环境检查在开始修改配置前建议先确认几个关键信息Kubernetes版本不同版本的k8s对containerd的支持可能略有差异containerd版本可以通过containerd --version查看Harbor仓库地址确认是域名还是IP是否需要端口号网络连通性确保k8s节点能够ping通Harbor仓库我最近处理的一个案例中客户使用的是Kubernetes v1.28.2containerd 1.6.33Harbor 2.7.0内网地址http://harbor.devops.icu2.2 理解containerd的registry配置机制containerd处理镜像拉取的逻辑是这样的首先检查/etc/containerd/config.toml中的registry配置然后会查找config_path指定的目录下的仓库配置对于每个仓库会读取对应的hosts.toml文件这种模块化的设计让我们可以灵活地为不同仓库配置不同的访问策略而不需要修改主配置文件。3. 详细配置步骤3.1 修改containerd主配置文件首先需要编辑containerd的主配置文件通常位于/etc/containerd/config.toml。找到[plugins.io.containerd.grpc.v1.cri.registry]部分添加或修改以下内容[plugins.io.containerd.grpc.v1.cri.registry] config_path /etc/containerd/registry_config这个config_path指定了containerd查找仓库配置的目录你可以根据实际情况修改路径。我习惯放在/etc/containerd下这样所有containerd相关的配置都集中管理。3.2 创建registry配置目录接下来创建配置目录和必要的子目录结构mkdir -p /etc/containerd/registry_config/harbor.devops.icu这里有几个关键点需要注意目录名称应该与你的Harbor仓库地址完全一致包括端口号如果使用IP地址目录名也要用IP确保containerd进程有权限读取这些目录3.3 配置hosts.toml文件在刚创建的目录下新建hosts.toml文件这是containerd读取仓库配置的关键文件。对于HTTP协议的Harbor仓库配置如下server http://harbor.devops.icu [host.http://harbor.devops.icu] capabilities [pull, resolve, push] skip_verify true这个配置有几个重要参数capabilities定义允许的操作通常包含pull(拉取)、resolve(解析)和push(推送)skip_verify跳过TLS验证这对HTTP连接是必须的server指定仓库的基础地址4. 验证配置效果4.1 重启containerd服务配置修改完成后需要重启containerd服务使更改生效systemctl restart containerd建议在重启后检查服务状态确保containerd正常启动systemctl status containerd4.2 测试镜像拉取现在可以通过创建一个测试Pod来验证配置是否生效。创建一个简单的DeploymentapiVersion: apps/v1 kind: Deployment metadata: name: nginx-test spec: replicas: 1 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: harbor.devops.icu/library/nginx:latest如果Pod能够正常启动并且通过kubectl describe pod查看事件中没有镜像拉取错误说明配置成功。5. 常见问题排查5.1 仍然出现HTTPS连接错误如果配置后仍然看到尝试HTTPS连接的报错可能是以下原因hosts.toml文件路径或名称不正确containerd没有正确加载配置缓存了旧的配置信息解决方法确认hosts.toml文件路径完全匹配仓库地址检查containerd日志journalctl -u containerd -f尝试完全重启containerdsystemctl daemon-reload systemctl restart containerd5.2 ctr命令拉取镜像失败需要注意的是这个配置只影响k8s通过containerd拉取镜像的行为。如果直接使用ctr命令仍然需要添加--plain-http参数ctr image pull --plain-http harbor.devops.icu/library/nginx:latest这是因为ctr命令是containerd的直接客户端不经过CRI接口所以需要单独指定HTTP协议。6. 安全注意事项虽然HTTP协议在内网环境中使用很方便但还是建议在生产环境中配置HTTPS。HTTP协议存在以下风险中间人攻击流量可能被窃听或篡改镜像篡改风险攻击者可能替换镜像内容认证信息泄露Basic认证信息以明文传输如果暂时无法部署HTTPS至少应该限制Harbor仓库的网络访问只允许k8s节点访问使用复杂的认证信息定期审计镜像内容7. 高级配置技巧7.1 多仓库配置如果你的环境中有多个Harbor仓库可以轻松扩展这个配置。只需要在registry_config目录下为每个仓库创建对应的子目录和hosts.toml文件即可。例如同时配置dev和prod两个Harbor仓库/etc/containerd/registry_config/ ├── harbor-dev.company.com │ └── hosts.toml └── harbor-prod.company.com └── hosts.toml7.2 认证配置如果Harbor仓库需要认证可以在hosts.toml中添加认证信息[host.http://harbor.devops.icu] capabilities [pull, resolve, push] skip_verify true [host.http://harbor.devops.icu.header] Authorization [Basic BASE64_ENCODED_CREDENTIALS]其中BASE64_ENCODED_CREDENTIALS是username:password的base64编码结果。7.3 镜像缓存配置对于性能要求高的环境可以配置containerd的镜像缓存。在config.toml中添加[plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.harbor.devops.icu] endpoint [http://harbor.devops.icu]这个配置可以加速频繁拉取的镜像的访问速度。