Kubekey离线部署Kubernetes集群时镜像拉取问题解析

问题背景

在使用Kubekey v3.1.7进行Kubernetes 1.31.0版本的离线部署时，用户遇到了镜像拉取失败的问题。具体表现为在Kylin Linux Advanced Server V10 (Sword)操作系统上，虽然离线包制作成功且包含了pause 3.9 arm64镜像，但在实际部署过程中仍出现镜像拉取失败的情况。

技术分析

离线部署的核心组件

Kubekey的离线部署主要涉及两个关键部分：

1. 离线镜像包(artifact) - 包含所有必要的容器镜像
2. 配置文件 - 定义集群的部署参数和镜像仓库配置

常见问题根源

1. 镜像仓库配置缺失：离线部署必须指定一个本地镜像仓库地址，否则kubelet会默认尝试从公共仓库拉取镜像

2. 架构不匹配：虽然制作了arm64架构的离线包，但部署时可能仍尝试拉取amd64架构的镜像

3. 镜像标签不一致：Kubernetes组件期望的镜像版本与离线包中的版本可能存在差异

解决方案

正确配置镜像仓库

在Kubekey的配置文件中必须明确指定本地镜像仓库地址：

registry:
  registryMirrors: []
  insecureRegistries: []
  privateRegistry: "your.local.registry:5000"  # 必须配置此项

验证离线包内容

制作离线包后，应确认包含以下关键镜像：

• pause:3.9 (arm64架构)
• kube-apiserver:v1.31.0
• kube-controller-manager:v1.31.0
• kube-scheduler:v1.31.0
• kube-proxy:v1.31.0

部署前检查

1. 确保所有节点可以访问指定的本地镜像仓库
2. 验证镜像仓库中确实包含所需镜像
3. 检查防火墙设置，确保5000端口(或自定义端口)开放

最佳实践建议

1. 统一架构：确保所有节点和离线包使用相同的CPU架构(本例中为arm64)

2. 版本对齐：Kubernetes组件版本与离线包中的镜像版本必须严格一致

3. 网络准备：离线环境需要预先配置好DNS解析，确保能解析本地镜像仓库地址

4. 存储检查：确认各节点有足够磁盘空间存放镜像

总结

Kubekey离线部署Kubernetes集群时，镜像拉取失败通常是由于镜像仓库配置不当或架构/版本不匹配导致的。通过正确配置本地镜像仓库地址、验证离线包内容以及做好部署前检查，可以避免此类问题的发生。对于arm64架构的环境，需要特别注意所有组件都使用对应的arm64版本镜像。