Containerd 2.3.3 镜像拉取技巧指南
一、问题诊断
1.1 检查当前配置
# 查看镜像加速配置cat/etc/containerd/certs.d/registry.k8s.io/hosts.toml# 查看 containerd 配置containerd config dump|grep-A10registry# 测试拉取镜像（会失败）ctr images pull --hosts-dir /etc/containerd/certs.d registry.k8s.io/pause:3.10.2
1.2 错误原因
- 阿里云镜像仓库中不存在
pause:3.10.2这个标签 - 配置的镜像加速地址缺少该版本镜像
二、解决方案
方案一：使用 DaoCloud 镜像加速器（推荐）
2.1.1 配置 hosts.toml
# 创建配置目录（如果不存在）mkdir-p/etc/containerd/certs.d/registry.k8s.io# 写入新配置cat>/etc/containerd/certs.d/registry.k8s.io/hosts.toml<<'EOF' server = "https://registry.k8s.io" [host."https://k8s.m.daocloud.io"] capabilities = ["pull", "resolve"] EOF
2.1.2 重启 containerd
systemctl restart containerd
2.1.3 验证配置
# 查看配置是否正确cat/etc/containerd/certs.d/registry.k8s.io/hosts.toml# 测试拉取镜像ctr images pull --hosts-dir /etc/containerd/certs.d registry.k8s.io/pause:3.10.2
2.1.4 镜像管理命令
# 查看已拉取的镜像ctr imagesls# 查看镜像详情ctr imagesls-q# 删除镜像ctr imagesrmregistry.k8s.io/pause:3.10.2
方案二：配置代理拉取
2.2.1 创建 systemd drop-in 配置
# 创建配置目录mkdir-p/etc/systemd/system/containerd.service.d# 配置代理cat>/etc/systemd/system/containerd.service.d/proxy.conf<<'EOF' [Service] Environment="HTTP_PROXY=http://192.168.1.225:7890" Environment="HTTPS_PROXY=http://192.168.1.225:7890" Environment="ALL_PROXY=http://192.168.1.225:7890" Environment="NO_PROXY=localhost,127.0.0.1,192.168.1.0/24,10.96.0.0/12,10.244.0.0/16" EOF
2.2.2 重启服务
# 重载 systemdsystemctl daemon-reload# 重启 containerdsystemctl restart containerd
2.2.3 验证代理配置
# 查看代理环境变量是否生效systemctl show containerd--property=Environment# 测试拉取镜像ctr images pull registry.k8s.io/pause:3.10.2
2.2.4 移除代理配置（如需取消）
rm-f/etc/systemd/system/containerd.service.d/proxy.conf systemctl daemon-reload systemctl restart containerd
三、Kubernetes 相关镜像操作
3.1 kubeadm 所需镜像列表
# 查看 kubeadm 需要的镜像kubeadm config images list# 使用 kubeadm 拉取镜像（自动使用 containerd 配置）kubeadm config images pull
3.2 批量拉取 Kubernetes 核心镜像
# 定义镜像列表images=("registry.k8s.io/kube-apiserver:v1.28.0""registry.k8s.io/kube-controller-manager:v1.28.0""registry.k8s.io/kube-scheduler:v1.28.0""registry.k8s.io/kube-proxy:v1.28.0""registry.k8s.io/pause:3.9""registry.k8s.io/etcd:3.5.9-0""registry.k8s.io/coredns/coredns:v1.10.1")# 批量拉取forimagein"${images[@]}";doctr images pull --hosts-dir /etc/containerd/certs.d"$image"done
四、常用 containerd 镜像管理命令
4.1 基础命令
# 拉取镜像ctr images pull docker.io/library/nginx:latest# 带加速器拉取ctr images pull --hosts-dir /etc/containerd/certs.d registry.k8s.io/pause:3.10.2# 列出所有镜像ctr imagesls# 列出镜像（只显示名称和标签）ctr imagesls-q# 删除镜像ctr imagesrm<image-name># 删除所有未使用的镜像ctr images prune
4.2 镜像标签操作
# 给镜像打标签ctr images tag source-image:tag target-image:tag# 示例：给 pause 镜像打标签ctr images tag registry.k8s.io/pause:3.10.2 k8s.gcr.io/pause:3.10.2
4.3 镜像导入导出
# 导出镜像为 tar 文件ctr imagesexportpause.tar registry.k8s.io/pause:3.10.2# 导入镜像ctr imagesimportpause.tar# 导出所有镜像ctr imagesexport--allimages-all.tar
五、调试与故障排查
5.1 查看 containerd 日志
# 查看实时日志journalctl-ucontainerd-f# 查看最近100行日志journalctl-ucontainerd-n100# 查看特定时间段的日志journalctl-ucontainerd--since"2026-07-21 10:00:00"--until"2026-07-21 11:00:00"
5.2 检查配置语法
# 验证 containerd 配置containerd config dump>/tmp/containerd-config.yaml# 检查配置是否正确containerd--config/etc/containerd/config.toml--version
5.3 镜像拉取失败诊断
# 使用 --debug 模式拉取ctr images pull--debug--hosts-dir /etc/containerd/certs.d registry.k8s.io/pause:3.10.2# 检查镜像仓库连通性curl-Ihttps://registry.k8s.io/v2/curl-Ihttps://k8s.m.daocloud.io/v2/# 查看镜像仓库的认证信息ls-la/etc/containerd/certs.d/
六、多节点批量执行脚本
6.1 使用 ansible 批量配置
# ansible playbook: containerd-mirror.yml-hosts:k8s_nodesbecome:yestasks:-name:Create certs.d directoryfile:path:/etc/containerd/certs.d/registry.k8s.iostate:directorymode:'0755'-name:Configure registry mirrorcopy:dest:/etc/containerd/certs.d/registry.k8s.io/hosts.tomlcontent:|server = "https://registry.k8s.io" [host."https://k8s.m.daocloud.io"] capabilities = ["pull", "resolve"]-name:Restart containerdsystemd:name:containerdstate:restarteddaemon_reload:yes
6.2 使用 shell 脚本批量执行
#!/bin/bash# 批量配置所有节点nodes=("master1""master2""worker1""worker2")fornodein"${nodes[@]}";dossh"$node""bash -s"<<'EOF' cat > /etc/containerd/certs.d/registry.k8s.io/hosts.toml <<'EOL' server = "https://registry.k8s.io" [host."https://k8s.m.daocloud.io"] capabilities = ["pull", "resolve"] EOL systemctl restart containerd echo "Node $(hostname) configured successfully" EOFdone
七、最佳实践建议
- 镜像加速器选择：优先使用 DaoCloud（https://k8s.m.daocloud.io）或中科大镜像源
- 配置备份：修改配置文件前做好备份
cp /etc/containerd/config.toml /etc/containerd/config.toml.bak - 版本兼容性：确保 containerd 版本与 Kubernetes 版本兼容
- 网络策略：如使用代理，确保 NO_PROXY 包含集群内部网络范围
- 监控日志：定期检查 containerd 日志，及时发现镜像拉取问题
八、快速参考命令汇总
# 查看 containerd 版本containerd--version# 查看当前镜像列表ctr imagesls# 拉取镜像（使用加速器）ctr images pull --hosts-dir /etc/containerd/certs.d registry.k8s.io/pause:3.10.2# 重启 containerdsystemctl restart containerd# 查看 containerd 状态systemctl status containerd# 查看镜像加速配置cat/etc/containerd/certs.d/registry.k8s.io/hosts.toml# 清理未使用的镜像ctr images prune# 查看 containerd 日志journalctl-ucontainerd-f
