简介基于麒麟V10操作系统与ARM64架构CPU的一键离线部署工具面向信创内网环境的运维和实施人员解决无外网条件下Kubernetes容器集群初始化难、依赖组件版本匹配复杂的问题。整套工具封装为88个文件类型涵盖shell脚本、rpm安装包、yaml配置模板、service服务文件以及containerd、kubeadm、kubectl等关键二进制组件压缩包整体大小约621MB支持一键部署、集群检查、集群移除并支持worker节点的一键扩容和缩容。工具适配单机、一主多从、三主多从三种部署架构内置证书有效期长达99年并预先集成Calico网络、kube-lb负载均衡和Nginx入口等配置模板在完全离线环境中也能快速拉起高可用生产级集群。目前已有289人学习下载适合需要在内网批量交付或复现Kubernetes环境的运维工程师参考使用能显著降低信创环境下的交付门槛与排错成本提升集群交付效率。1. 麒麟 V10ARM64 离线高可用 K8S 1.26.15一键部署工具到底解决什么基于 Kylin V10 ARM64 架构 CPU containerd 一键离线部署容器版 K8S 1.26.15 高可用集群工具很多信创交付工程师看到这个标题的第一反应是终于不用再手搓四十条命令了。这类工具解决的核心问题很明确——在完全没外网的内网环境里面对三台麒麟 V10或 SP1/SP2的鲲鹏、飞腾机器要把 kubeadm 拉起一套三个 master、N 个 worker 的高可用集群镜像怎么传、rpm 依赖怎么装、VIP 怎么配、证书怎么续全部压到一个入口脚本里完成。适合正在做国产化平台交付、K8S 运维迁移的人也适合刚接触信创环境但要独立交付集群的工程师。这篇文章不依赖某个仓库源码按这类工具最常见的形态把物料准备、运行初始化、HA 配置和踩坑路径讲清楚。2. 攒离线物料包ARM64 镜像清单、rpm 内网源与四类文件2.1 离线包里的四类物料二进制、镜像、rpm 和模板真正到内网交付过的人都知道离线包的成败不在脚本写得多漂亮而在物料全不全。一个能复用的离线交付包通常拆成四个目录分别是二进制、容器镜像、rpm 依赖、配置模板。二进制指的是 kubeadm、kubelet、kubectl 三个主程序注意版本必须精确锁在 1.26.15并且是 linux/arm64 平台。很多人在这栽过从 x86 的机器下载了 amd64 的 kubelet 拷过去文件也能执行但 kubelet 一跑起来各种参数不识别、健康检查失败最后查二进制平台才发现问题。镜像目录是离线包的大头包含控制面镜像和网络插件镜像。控制面镜像由 kubeadm 固定清单决定包括 kube-apiserver、kube-controller-manager、kube-scheduler、kube-proxy、etcd、coredns、pause 这几个。网络插件如果选 Calico还得带 calico/node、calico/cni、calico/kube-controllers 等这是另一个容易漏的类别。rpm 目录解决系统依赖。kubelet 跑起来强依赖 conntrack、socat、ebtables、ipset、iptables 等命令containerd 又依赖 libseccomp。很多交付现场连 kernel 版本都不一样所以靠谱的离线包会把装 runtime 和装 K8S 的 rpm 全部打进 rpm 目录到现场做本地 yum 源。配置模板则是直接复用而不是全靠手改的部分比如 /etc/crictl.yaml、kubeadm-init.yaml、haproxy.cfg、keepalived.conf。工具化设计上我一般建议入口脚本按install.sh 21 | tee /var/log/k8s-offline-install.log方式留全程日志并且每个子步骤单独写脚本用 marker 文件标记完成状态后面第 3 章会展开。2.2 在 ARM64 机器上用 kubeadm 拉全 1.26.15 镜像并导出 tar离线镜像的攒法最常见、最不容易翻车的方式是找一台能联网的 ARM64 机器先写 kubeadm-init.yaml用kubeadm config images list拿到目标版本的精确镜像清单再逐张拉取、一起导出成 tar。# 先把集群初始化配置写好这里只为了取镜像清单 kubeadm config images list --configkubeadm-init.yaml /tmp/image-list.txt # 逐张拉取镜像错一张都补拉 while read img; do ctr -n k8s.io images pull $img || echo pull failed: $img done /tmp/image-list.txt # 检查是否拉全 ctr -n k8s.io images ls -q | grep -E (apiserver|controller-manager|scheduler|proxy|etcd|coredns|pause) # 导出整个 k8s.io 命名空间下的镜像输出单文件 tar ctr -n k8s.io images export /opt/offline/k8s-images.tar $(ctr -n k8s.io images ls -q)这段逻辑说明几个关键点。第一拉镜像务必在 ARM64 原生机器上执行不要在 x86 上拉完再传否则 manifest 平台不匹配后面章节专门讲。第二这里用的是 containerd 的 ctr 而不是 docker因为目标运行时就是 containerd别混用工具链。第三ctr images export后面直接展开命名空间全部镜像输出 tar 会很大属正常建议按节点数算好磁盘空间。镜像清单里的详细 tag以本机kubeadm config images list输出为准etcd 一般落在 3.5.xcoredns 落在 1.9.xpause 在 1.26 系默认是 3.9。网络插件镜像用同样方式拉取命名为 calico-images.tar放进 images 目录即可。2.3 把 rpm 目录变成离线 yum 源createrepo 三步离线 rpm 源是很多人忽略的细节。直接把 rpm 丢到服务器上再yum install ./xxx.rpm能解决单包安装但装 kubeadm 时它会拉依赖依赖一旦不在本机就只能报错。因此要先把 rpm 目录做成标准 yum 源。# 第一步对 rpm 目录生成仓库元数据 createrepo -v /opt/offline/rpm # 第二步写一个 offline.repo优先级放在最前面 cat /etc/yum.repos.d/offline.repo EOF [offline] nameoffline repository baseurlfile:///opt/offline/rpm enabled1 gpgcheck0 EOF # 第三步刷新缓存后直接安装 yum clean all yum makecache yum install -y containerd.io kubeadm-1.26.15 kubelet-1.26.15 kubectl-1.26.15这里参数重点在enabled1和gpgcheck0。gpgcheck0是很多安全评审会挑的点但离线内网环境下没有官方源可验通常先关掉保证交付后续做基线加固时再补校验如果打包时把 GPG key 一并放入并开启gpgcheck1更稳妥但复杂度高一些。createrepo生成 repodata 目录后不要移动 rpm 目录否则元数据路径失效。另外注意 Kylin V10 自带的 bash 环境默认是 4.xcreaterepo 命令若没预装打包机上的离线 rpm 目录里要包含 createrepo 的依赖包。3. containerd 运行时初始化cgroup 驱动、sandbox_image 与 ctr 导入3.1 containerd config.toml 的三个必改参数containerd 装好后直接启动并不能用于 K8S至少有三个参数必须改。用默认配置生成后逐一确认。# 生成默认配置骨架 containerd config default /etc/containerd/config.toml # 把 CRI 的 cgroup 驱动改成 systemd sed -i s/SystemdCgroup false/SystemdCgroup true/ /etc/containerd/config.toml # 把沙箱镜像改成内网可导入的 pause 镜像 sed -i s#sandbox_image registry.k8s.io/pause:3.9#sandbox_image registry.k8s.io/pause:3.9# /etc/containerd/config.toml # 启动并验证 systemctl enable --now containerd crictl versioncgroup 驱动不一致是集群初始化和节点运行时最常见的翻车源头。kubelet 默认用 systemd cgroup 驱动containerd 默认的是 cgroupfs两边不一致时kubelet 健康检查会过不了pod 沙箱刚创建就被杀。如果你不用 sed 而用文本编辑器改定位到plugins.io.containerd.grpc.v1.cri段下的SystemdCgroup字段确认值是 true。sandbox_image 也就是 pause 镜像它的作用是给每个 pod 提供网络和 pid 命名空间底座。离线下这个镜像必须预先导入并且 tag 要和 kubeadm 期望一致。第 2 章已提1.26.15 默认是 pause:3.9但最稳的确认方式是看kubeadm config images list的输出。很多人分不清 containerd、docker、K8S 三者关系这里就一句话1.26 版本的 K8S 已经移除了 dockershimkubelet 直接通过 CRI 和 containerd 通信所以离线包完全不需要 dockerdocker 装进来反而多个守护进程占资源。3.2 ctr 导入必须带 k8s.io 命名空间否则 kubelet 永远找不到镜像ctr 导入镜像时命名空间是玄学也是新手翻车最狠的一处。kubelet 通过 containerd 的 CRI 插件工作默认使用k8s.io命名空间而 ctr 默认操作的却是default命名空间。所以如果你直接执行下面第一条命令后面 kubelet 会一直报拉取镜像失败明明本地有镜像却不用特别憋屈。# 错误示范会把镜像导入到 default 命名空间 ctr images import /opt/offline/k8s-images.tar # 正确做法显式指定 k8s.io 命名空间 ctr -n k8s.io images import /opt/offline/k8s-images.tar # 验证用 crictl 看的是 kubelet 视角的镜像列表 crictl images参数-n k8s.io是关键crictl images则是验证手段。crictl 的配置文件/etc/crictl.yaml也要在离线包模板里带上至少三行内容runtime-endpoint: unix:///run/containerd/containerd.sock、image-endpoint: unix:///run/containerd/containerd.sock、timeout: 10。没有这个文件时 crictl 会尝试连 docker socket报错后让人误以为 containerd 没起来。导入 tar 文件时如果报no matching image多是 tar 本身损坏或导出时命名空间搞错了重新在打包机导出即可。导入过程对磁盘 IO 要求高建议在目标节点目录预留足空间。3.3 一键脚本的幂等设计失败后能断点续跑「一键部署」这个词看着简单实际工程里最难的是失败重跑。内网交付现场网络差、机器配置参差脚本跑到一半断了是常事如果脚本没有幂等设计就会反复 kubeadm init 导致/etc/kubernetes/残留旧证书越跑越烂。我见过这类工具的标准做法是阶段 marker。#!/usr/bin/env bash set -euo pipefail BASE_DIR/opt/offline MARK_DIR${BASE_DIR}/.markers mkdir -p $MARK_DIR run_step() { local step_name$1 local marker_file$MARK_DIR/$step_name.done if [ -f $marker_file ]; then echo skip: $step_name return 0 fi echo run: $step_name bash $BASE_DIR/scripts/${step_name}.sh touch $marker_file } run_step 01-prepare run_step 02-containerd run_step 03-k8s-init run_step 04-joinrun_step函数里先看 marker 文件失败时当前脚本退出修复问题后重新执行入口脚本已经完成的步骤直接跳过。这个设计带来的好处是kubeadm init不重复执行containerd 配置不重复覆盖证书目录不会因为二次 init 产生冲突。注意 marker 文件必须在该步骤全部命令成功且经过自检后才 touch宁可多验证一步不要省。这套脚本结构里我习惯把每个步骤脚本都加上set -e同时把节点角色信息放到conf/node-info.env这样同一套包既能初始化第一个 master也能在其他节点上只执行 join 步骤。4. 高可用集群初始化与节点加入VIP、kubeadm init 和两种 join4.1 keepalivedhaproxy 搭建 apiserver 接入 VIP高可用方案选型上对内网信创环境最常见的组合是 keepalived haproxy。三个 master 节点各装一个 haproxy监听 6443 端口后端指向三台 master 的 6443keepalived 在三个 haproxy 之上再虚拟出一个 VIP作为 kubeadm 的 controlPlaneEndpoint。这样 apiserver 的接入地址始终是 VIP单台 master 挂掉不影响控制面访问。# 每台 master 部署后端列表写全三台 listen k8s-apiserver bind 0.0.0.0:6443 mode tcp option tcplog balance roundrobin server master-1 10.10.1.11:6443 check inter 3s fall 3 rise 2 server master-2 10.10.1.12:6443 check inter 3s fall 3 rise 2 server master-3 10.10.1.13:6443 check inter 3s fall 3 rise 2bind 0.0.0.0:6443会让 haproxy 本机也监听 6443但 kubelet 在 master 节点上访问的 6443 是给 apiserver 的这里存在一个细节冲突。常见做法是 haproxy 监听一个独立端口如 16443再用 keepalived 的 VIP 把 6443 流量引到各节点 haproxy但这个架构链路长。更直接的方案是 haproxy 直接用 6443保证后端 apiserver 也监听 6443传输模式 tcp 纯四层转发不做任何 HTTP 解析。keepalived 主节点配置如下priority 决定谁持有 VIP。vrrp_instance VI_K8S { state MASTER interface ens3 virtual_router_id 50 priority 100 advert_int 1 unicast_src_ip 10.10.1.11 unicast_peer { 10.10.1.12 10.10.1.13 } virtual_ipaddress { 10.10.1.100/24 dev ens3 } }interface必须改成实际网卡名鲲鹏服务器上常见是 enp 开头或 bond 网卡不要照抄 ens3。unicast_peer是内网里规避组播不通的稳妥写法很多物理机交换机禁组播靠这个字段点对点通信。virtual_ipaddress里的dev ens3限定了 VIP 落在哪块网卡多网卡机器上必须指定。4.2 kubeadm init 配置controlPlaneEndpoint 与 podSubnet 的写法物料和运行时就绪后第一个 master 节点执行 init。不要直接跑一长串命令行参数配置文件方式更可控也方便离线包复用。# kubeadm-init.yaml apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: 1.26.15 controlPlaneEndpoint: 10.10.1.100:6443 imageRepository: registry.k8s.io networking: podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 --- apiVersion: kubelet.config.k8s.io/v1beta1 kind: KubeletConfiguration cgroupDriver: systemdcontrolPlaneEndpoint写的是 VIP:6443而不是本机 IP。kubernetesVersion必须精确到补丁版本kubeadm 会按这个版本去本地镜像列表里找对应 tag。imageRepository保持registry.k8s.io不动因为离线包导入时保持的是这个原始路径如果你在打包阶段改写成了内网 harbor 地址这里要同步改前后不一致会触发拉取失败。podSubnet的选择要跟网络插件对应。用 Flannel 常见 10.244.0.0/16用 Calico 默认则是 192.168.0.0/16。这两个网段将来直接决定 pod IP 分配上线后很难改选定后所有节点的 CNI 配置都要对齐。kubeadm init --configkubeadm-init.yaml --upload-certs | tee /tmp/kubeadm-init.log--upload-certs是关键参数它会把控制面证书加密上传到集群后续追加 master 节点时要靠它生成 certificate key这一步日志要妥善保存。init 完成后按日志提示拷贝 kubeconfigmkdir -p $HOME/.kube cp /etc/kubernetes/admin.conf $HOME/.kube/config kubectl get nodes如果这里kubectl get nodes能看到 master 节点但状态 NotReady别急着排查先装 CNI。CNI 装完节点才会 Ready。4.3 追加 master 和 workercontrol-plane join 与普通 join 的区别高可用集群的最小规模是三个 master所以 join 要分成两种形态。追加 master 的 join 命令由 init 日志给出典型如下。kubeadm join 10.10.1.100:6443 --token xxxxx \ --discovery-token-ca-cert-hash sha256:xxxx \ --control-plane --certificate-key xxxx追加 worker 则是同一段前面的部分去掉两个参数。kubeadm join 10.10.1.100:6443 --token xxxxx \ --discovery-token-ca-cert-hash sha256:xxxx--control-plane告诉 kubeadm 这是第三个 master会多执行控制面组件部署和 etcd 扩展。--certificate-key对应 init 时的--upload-certs没有了它 master join 会要求手动把证书拷贝过去。另外注意 token 默认有效期只有 24 小时离线交付节奏慢时就容易踩这个坑。超时后用kubeadm token create --print-join-command重新生成certificate-key 也要重新获取。master 追加完成后可以用kubectl get nodes看到三台 master 都在且kubectl get pods -n kube-system里没有 CrashLoopBackOff。如果第三台 master 的 etcd 一直起不来多半是证书 key 错了或 etcd 数据目录残留清掉/var/lib/etcd再重新 join 最直接。5. 离线部署翻车排查4 个高频问题与定位清单5.1 ctr 导入了镜像kubelet 仍报拉取失败现象kubeadm init 执行到一半kubelet 日志里反复出现Failed to pull image registry.k8s.io/pause:3.9但你在本机用ctr images ls能看到 pause 镜像。原因镜像被导入了default命名空间而 kubelet 走 CRI 查的是k8s.io。解决用crictl images看 kubelet 视角如果列表为空说明命名空间错了重新执行ctr -n k8s.io images import /opt/offline/k8s-images.tar。这类工具里导入脚本必须硬编码-n k8s.io不能依赖默认值。5.2 kubeadm init 卡在 the apiserver is not healthy after 4m0.00747357s现象init 日志里出现[kubelet-check] The HTTP call equal to http://localhost:10248/healthz failed并伴随the apiserver is not healthy after 4m0.00747357s。这一步主要不是 apiserver 本身的问题而是 kubelet 健康检查不过。原因按出现频率排pause 沙箱镜像缺失或 tag 不匹配导致所有静态 Pod 起不来containerd 的 SystemdCgroup 和 kubelet 不一致本机 6443 端口被安全策略挡住。解决顺序先看沙箱crictl ps -a | grep pause如果没输出回第 3 章确认命名空间导入。再看journalctl -u kubelet --since 5 minutes ago里的最后 20 行如果提到sandbox image ... not found把 pause:3.9 重新导入如果提到Failed to start CRI改 SystemdCgroup 后重启 containerd。最后检查systemctl status firewalld麒麟 V10 在某些模板里默认开启 firewalld6443 被 drop 时表现为健康检查超时临时systemctl stop firewalld测一下即可定位。5.3 ARM64 节点装进了 x86 架构镜像manifest unknown现象ctr images import成功ctr images ls也看得到镜像但容器一直创建失败事件报manifest unknown或failed to resolve reference ... not found。原因拉镜像的打包机是 x86导出的镜像平台是 amd64ARM64 节点识别到 manifest 里没有 linux/arm64 入口就拒绝使用。解决换一台 ARM64 打包机重新拉取导出或者用支持跨架构拉取的 skopeo 显式指定 archarm64导出后做一次crictl pull registry.k8s.io/pause:3.9验证节点能拉到再跑集群初始化。交付包的 README 里我会刻意写上「离线包在 ARM64 环境生成禁止跨架构拷贝镜像目录」这一条。5.4 节点 join 成功但 NotReadyCNI 镜像与 podSubnet 冲突现象kubectl get nodes显示节点 NotReadykubectl get pods -n kube-system里 coredns 一直 Pendingcalico-node Pod 处于 CrashLoopBackOff。原因主要有两类第一离线包里根本没有包含 CNI 镜像kubelet 的 pod 网卡创建失败第二podSubnet 写的是 10.244.0.0/16但 Calico 默认 IP 池也是它两者一般能对上真正容易乱的是多网卡机器上 Calico 自动探测到 VIP 所在网卡导致 BGP 和隧道全部错乱。解决先确认crictl images | grep calico输出是否完整缺镜像就把 calico-images.tar 导入如果镜像齐全查看kubectl logs -n kube-system calico-node-xxxx定位到报错后在 calico 安装 yaml 的环境变量里加IP_AUTODETECTION_METHODinterfaceens.*把 VIP 所在网卡排除掉再滚动重启 calico 节点 Pod。NotReady 状态里还有一种特殊情况是 node 本身资源不足kubelet 启动后压力过大被驱逐kubectl describe node xxx能看到对应的压力条件。6. 上线前最后两件事VIP 故障切换验证与证书续期演练6.1 不停机验证 VIP 漂移与 apiserver 探活集群交付不等于验收通过。我会在三个 master 节点分别确认 VIP 归属然后用一个循环请求观察 VIP 切换时集群控制面是否短暂中断。# 在任意一台能访问 VIP 的机器上执行 while true; do curl -sk -o /dev/null -w %{http_code}\n https://10.10.1.100:6443/healthz sleep 1 done另开一个窗口在 VIP 当前所在的 master 上执行systemctl stop keepalived观察上面循环里 healthz 的返回。正常情况会断几个请求VIP 漂移到下一台 master 后恢复 200。这里如果出现长时间中断问题多在 haproxy 后端check参数没生效haproxy 不摘除故障节点导致流量打到坏后端。6.2 kubeadm certs renew all 之后的静态 Pod 重启细节K8S 1.26.15 的证书默认一年到期生产集群上线前我会把续期流程完整演练一遍。核心命令只有两个坑在续期后静态 Pod 不会自动重启。# 续期所有证书 kubeadm certs renew all # 查看到期时间验证续期成功 kubeadm certs check-expiration续期生成的证书是新的但运行中的 apiserver、controller-manager 等静态 Pod 还持有旧证书文件的内存副本。最稳的做法是把/etc/kubernetes/manifests/下的 yaml 文件临时移走等 kubelet 清理掉旧容器后再移回来触发用新证书重建。mkdir -p /tmp/manifests-backup mv /etc/kubernetes/manifests/*.yaml /tmp/manifests-backup/ sleep 5 mv /tmp/manifests-backup/*.yaml /etc/kubernetes/manifests/这个技巧我每次做证书维护都用比 crictl stop 一个个容器要干净。整个操作期间保持一个已认证的 kubectl 窗口重启完确认kubectl get nodes和kubectl get pods -n kube-system全部恢复。离线工具的最后一公里往往不是脚本本身而是这些验收细节希望帮到你。本文还有配套的精品资源点击获取