离线生产环境的 Kubernetes 自研安装包核心是“可复现的制品链路”,而非简单打包;因 kubeadm init 会动态拉取镜像、生成不可审计证书、忽略节点角色与参数收敛,导致预检失败、配置不一致和静默部署错误。

直接说结论:离线生产环境的 Kubernetes 自研安装包,核心不是“打包”,而是“可复现的制品链路”——必须能脱离联网跳板机、不依赖外部仓库、一次解压即执行,且所有组件版本、镜像、配置、证书生成逻辑全部固化。
为什么不能只用 kubeadm init 加离线镜像?
因为 kubeadm init 默认会动态拉取镜像、自动生成 CA 证书、写死本地路径、忽略节点角色收敛逻辑。在生产离线环境中,这些行为会导致:
-
kubeadm在无网时卡在[preflight] Running pre-flight checks阶段(它仍尝试访问https://dl.k8s.io检查版本) - 证书有效期、SAN 列表、etcd peer 地址全靠运行时推导,无法提前审计或复用
- 没有统一入口控制
kubelet的cgroupDriver、containerRuntimeEndpoint等关键参数,不同节点容易不一致 - Calico/Flannel 的 manifest 里含动态 CIDR 或节点名变量,离线部署时无法替换
kubekey 离线包制作的关键断点控制
kubekey 是目前最适配国产化离线生产的工具,但它的默认离线流程有三个必须干预的断点:
- 必须显式指定
--download-cmd docker或--download-cmd crictl,否则它会在离线节点上尝试调用curl下载镜像(即使已提供images/目录) -
config-sample.yaml中的hosts列表必须提前填入internalAddress和role,不能留空或用占位符;否则kk create cluster会报failed to get host info - 镜像导入必须用
crictl load -i而非docker load,因为生产环境强制使用containerd,且kubekey的preinstall阶段只认crictl输出的镜像列表
示例修正后的打包命令:
./kk create config --with-kubernetes v1.30.6 --with-kubesphere v4.1.2 -f config.yaml # 编辑 config.yaml,确认 hosts 下每个节点都有 internalAddress 和 role ./kk artifact export -f config.yaml -o kubekey-offline.tar.gz --download-cmd crictl
openEuler 22.03-SP4 下必须重写的初始化脚本
openEuler 默认启用 firewalld 和 NetworkManager,而 Kubernetes 要求 iptables 规则直通、br_netfilter 模块预加载。不能靠 kubekey 的默认 preinstall 脚本兜底,必须单独写初始化脚本并嵌入离线包:
- 禁用
firewalld并清空iptables:用systemctl disable firewalld && iptables -F,不能只停服务 - 关闭
NetworkManager对bridge接口的接管:在/etc/NetworkManager/conf.d/99-disable-bridge.conf写[keyfile] unmanaged-devices=interface-name:br-*,interface-name:cni0,interface-name:flannel.1 -
sysctl参数需固化到/etc/sysctl.d/99-k8s.conf,尤其net.bridge.bridge-nf-call-iptables=1必须存在,否则 Calico 的 NetworkPolicy 不生效 - containerd 的
config.toml中plugins."io.containerd.grpc.v1.cri".registry.mirrors必须指向本地仓库(如dockerhub.kubekey.local),不能留空
镜像仓库地址硬编码是最大陷阱
几乎所有离线方案都假设“镜像已导入本地”,但实际部署时,kube-proxy、coredns、calico-node 的 manifest 仍会从 k8s.gcr.io 或 quay.io 拉取——除非你手动改掉所有 YAML 里的 image: 字段。更可靠的做法是:
- 在离线包中内置一个
rewrite-images.sh,用sed -i 's|k8s.gcr.io|dockerhub.kubekey.local|g'批量替换所有 manifest - 把该脚本作为
kubekey的post-install钩子,在cluster.yml中声明:hooks: { postInstall: /opt/kk/rewrite-images.sh } - 确保本地仓库域名
dockerhub.kubekey.local已写入所有节点的/etc/hosts,且证书已信任(否则crictl pull报x509: certificate signed by unknown authority)
真正难的不是打包,是让每一个环节拒绝“运行时猜测”——证书、镜像地址、网络插件 CIDR、节点角色、cgroup 驱动,全得在离线包生成那一刻就定死。否则部署时出的错,不会告诉你哪里没设对,只会静默失败。











