离线部署Kubernetes失败主因是三类资源不匹配:二进制架构错(如ARM服务器误用x86 kubeadm)、镜像tag漏或版本不一致(如etcd 3.5.15-0写成3.5.15)、YAML中仍引用registry.k8s.io等外网地址;须严格统一kubeadm/kubelet/kubectl版本与架构,逐个load校验镜像,本地化所有YAML镜像路径,并显式指定--image-repository等参数。

离线部署 Kubernetes 不是“把镜像和二进制拷过去就能跑”,失败几乎都卡在三类资源不匹配:二进制架构错、镜像 tag 漏或版本不一致、YAML 里写的镜像地址还是 registry.k8s.io。
怎么确认 kubeadm/kubelet/kubectl 版本和架构必须严格一致
ARM 服务器上用 x86 的 kubeadm 直接报 Exec format error;同理,kubelet 和 kubectl 如果混用 v1.32 和 v1.35,kubeadm init 会提示证书签名失败或无法生成 manifest。官方发布页(如 kubernetes-server-linux-arm64.tar.gz)里打包的是整套对应组件,别自己拼凑。
- 查当前系统架构:
uname -m→ 输出aarch64就必须用 arm64 包,x86_64才能用 amd64 - 验证三个二进制版本统一:
kubeadm version -o short、kubelet --version、kubectl version --client --short三者输出必须完全一样,例如v1.35.6 -
chmod +x缺一不可——/usr/bin/kubeadm权限为 644 时,kubeadm init报permission denied不提示具体文件,只卡在 preflight 检查
docker load 镜像前必须先核对镜像列表是否完整
控制平面启动失败,90% 是因为 etcd 或 pause 镜像没 load 进去。kubeadm 不会报“缺哪个镜像”,而是卡在 waiting for etcd to become available 或反复重启 kube-apiserver 容器。
- 先在联网机器上执行:
kubeadm config images list --kubernetes-version=v1.35.6,记下全部 12–15 个镜像名(含registry.k8s.io/etcd:3.5.15-0、registry.k8s.io/pause:3.9等) - 每个镜像必须用
docker pull && docker save -o xxx.tar导出,不能用skopeo copy或ctr images export—— 后两者生成的不是标准 tar,docker load会报invalid format - 离线节点上逐个 load:
docker load -i images/kube-apiserver_v1.35.6.tar,然后docker images | grep kube确认 tag 对得上,别出现<none></none>
calico.yaml 或 flannel.yaml 里的镜像地址必须本地化
YAML 文件里还写着 quay.io/calico/cni:v3.27.2,但你只 load 了 localhost:5000/calico/cni:v3.27.2,kubectl apply 后 Pod 一直 ImagePullBackOff,日志里却只显示 “failed to resolve reference”,根本看不出是地址不对。
- 编辑
calico.yaml前先确认你 load 进来的镜像名:docker images --format "{{.Repository}}:{{.Tag}}" | grep calico - 全局替换 YAML 中所有
quay.io/calico/为你的内网地址,例如harbor.internal/calico/或直接localhost:5000/calico/ - 如果用 Docker Registry 本地仓库,确保
imagePullPolicy: IfNotPresent,否则即使本地有也会去远端拉 - 别漏掉
coredns的 YAML——它默认从registry.k8s.io/coredns/coredns拉,同样要改地址并提前 load
kubeadm init 命令顺序和参数不能省略
很多人以为 kubeadm init 能自动 fallback 到本地镜像,其实它默认仍会尝试连外网校验,没网络就卡住或超时失败。必须显式指定所有依赖项路径和行为。
- 先运行:
kubeadm config images pull --kubernetes-version=v1.35.6 --image-repository=localhost:5000,验证所有 control plane 镜像都能被识别(不报错即成功) - 再执行 init:
kubeadm init --pod-network-cidr=10.244.0.0/16 --image-repository=localhost:5000 --cri-socket=unix:///var/run/containerd/containerd.sock(注意--cri-socket要和实际运行时匹配) - init 成功后,立刻执行:
mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config,否则kubectl get nodes报connection refused
最容易被忽略的是:etcd 镜像版本必须和 kubeadm 声明的完全一致,差一个 patch 号(比如 3.5.15-0 写成 3.5.15)就会导致 init 卡死;还有 calico/node 镜像和 calico/cni 镜像必须同版本,否则 CNI 插件注册失败,Pod 无法分配 IP。


















