别再只改 /etc/docker/daemon.json 了！K8s 1.28 拉取 Harbor 镜像，关键在 containerd 的 config.toml

从Docker到ContainerdK8s 1.28拉取Harbor镜像的完整指南当你在Kubernetes 1.28集群中配置了Docker的insecure-registries却发现Pod依然无法从HTTP协议的Harbor仓库拉取镜像时这篇文章正是为你准备的。随着K8s 1.24版本后彻底转向containerd作为默认容器运行时传统的Docker配置方式已不再适用。本文将带你深入理解containerd的配置机制避开那些过时的教程陷阱。1. 为什么Docker配置不再有效许多从早期Kubernetes版本迁移过来的用户遇到镜像拉取问题时第一反应就是修改/etc/docker/daemon.json文件。这种惯性思维在K8s 1.24环境中反而会成为解决问题的障碍。关键变化点K8s 1.24起默认使用containerd而非Docker作为容器运行时containerd有自己独立的配置体系位于/etc/containerd/config.tomlDocker的insecure-registries配置对containerd完全无效我曾在一个生产环境升级项目中花了整整两天时间排查为什么按照K8s拉取Harbor镜像的教程操作后仍然报错最终发现所有教程都是基于Docker环境的。这个教训让我深刻认识到理解底层运行时变更的重要性。2. Containerd核心配置解析containerd的配置文件采用TOML格式相比Docker的JSON配置它提供了更细粒度的控制选项。我们需要重点关注两个关键配置段2.1 镜像仓库镜像配置[plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.harbor.example.com] endpoint [http://harbor.example.com]这个配置段定义了仓库镜像相当于Docker中的镜像加速器概念。对于自建Harbor仓库我们需要明确指定HTTP协议的endpoint。2.2 仓库安全配置[plugins.io.containerd.grpc.v1.cri.registry.configs] [plugins.io.containerd.grpc.v1.cri.registry.configs.harbor.example.com] [plugins.io.containerd.grpc.v1.cri.registry.configs.harbor.example.com.tls] insecure_skip_verify true对于使用HTTP协议或自签名证书的Harbor仓库必须设置insecure_skip_verify为true否则containerd会拒绝连接。常见配置错误对比表错误配置正确配置导致的问题只修改daemon.json修改config.tomlK8s完全忽略Docker配置使用https endpoint明确指定http协议不匹配导致连接失败全局insecure配置针对特定仓库配置安全策略过于宽松3. 实战配置步骤让我们通过一个完整的示例演示如何为HTTP协议的Harbor仓库配置containerd。3.1 生成默认配置文件如果系统中没有现成的config.toml可以先生成默认配置sudo mkdir -p /etc/containerd containerd config default | sudo tee /etc/containerd/config.toml3.2 编辑配置文件使用vim或其他编辑器打开配置文件sudo vi /etc/containerd/config.toml找到或添加以下内容假设Harbor地址为192.168.2.142:8800[plugins.io.containerd.grpc.v1.cri.registry] [plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.192.168.2.142:8800] endpoint [http://192.168.2.142:8800] [plugins.io.containerd.grpc.v1.cri.registry.configs] [plugins.io.containerd.grpc.v1.cri.registry.configs.192.168.2.142:8800] [plugins.io.containerd.grpc.v1.cri.registry.configs.192.168.2.142:8800.tls] insecure_skip_verify true提示配置中的仓库地址必须与Pod中使用的镜像地址完全一致包括端口号3.3 应用配置变更修改完成后需要重启containerd服务使配置生效sudo systemctl restart containerd验证服务状态sudo systemctl status containerd4. 多节点环境配置策略在生产环境中K8s集群通常包含多个节点每个节点都需要相同的containerd配置。以下是几种高效的配置同步方法4.1 使用SCP命令手动复制scp /etc/containerd/config.toml node1:/etc/containerd/ scp /etc/containerd/config.toml node2:/etc/containerd/4.2 使用Ansible批量部署创建playbook文件sync_containerd.yaml:- hosts: k8s_nodes tasks: - name: Copy containerd config copy: src: /etc/containerd/config.toml dest: /etc/containerd/config.toml owner: root group: root mode: 0644 notify: restart containerd handlers: - name: restart containerd systemd: name: containerd state: restarted执行playbook:ansible-playbook -i inventory sync_containerd.yaml5. Containerd实用命令指南熟悉containerd的命令行工具对日常运维至关重要。以下是常用命令与Docker命令的对比5.1 镜像管理功能Docker命令Containerd命令拉取镜像docker pullctr images pull列出镜像docker imagesctr images ls删除镜像docker rmictr images rm拉取Harbor镜像示例ctr images pull --plain-http --user admin:Harbor12345 192.168.2.142:8800/test/flaskweb:v1.0.05.2 命名空间管理containerd支持多命名空间隔离K8s使用的默认命名空间是k8s.io。查看k8s使用的镜像ctr -n k8s.io images ls5.3 使用nerdctlnerdctl提供了更接近Docker的使用体验nerdctl --namespace k8s.io ps -a nerdctl --namespace k8s.io logs container-id6. 排查镜像拉取问题当Pod出现ImagePullBackOff错误时可以按照以下步骤排查检查Pod描述获取详细错误信息kubectl describe pod pod-name确认containerd配置是否正确sudo cat /etc/containerd/config.toml | grep -A10 registry尝试手动拉取镜像ctr images pull --plain-http image-url检查containerd日志journalctl -u containerd -n 50 --no-pager常见错误及解决方案x509证书错误确认config.toml中配置了insecure_skip_verify true协议不匹配确保镜像URL和endpoint使用相同协议(http/https)认证失败为私有仓库配置imagePullSecrets7. 安全最佳实践虽然HTTP协议在测试环境中可以工作但生产环境强烈建议为Harbor配置HTTPS证书使用imagePullSecrets管理认证信息限制insecure-registries的使用范围定期审计containerd配置创建imagePullSecret示例kubectl create secret docker-registry harbor-creds \ --docker-serverharbor.example.com \ --docker-usernameadmin \ --docker-passwordHarbor12345在Pod中引用spec: containers: - name: myapp image: harbor.example.com/test/flaskweb:v1.0.0 imagePullSecrets: - name: harbor-creds从Docker到containerd的转变代表着Kubernetes容器运行时架构的演进。理解这些底层变化才能避免被过时的教程误导。在实际操作中我发现最稳妥的方式是直接查阅对应版本的官方文档而不是依赖第三方教程。当你在凌晨三点还在为镜像拉取失败而苦恼时这份containerd配置指南或许能为你节省数小时的调试时间。