1. 先搞清楚离线部署的本质不是没网是断了哪些网很多朋友一接到离线部署 Kubernetes这个需求第一反应就是把镜像导出来带进去、把 rpm 包装好拷进去然后 kubeadm init 一把梭。但我在内网机房摸爬滚打几次之后发现离线部署真正的难点从来不是拷贝文件这一步而是你在外网环境里习以为常的那些隐性依赖全部要自己想办法补齐。先说说我最近一次的真实经历。客户环境是某单位的隔离机房物理断网节点总共 5 台操作系统是 CentOS 7.9要求用 kubeadm 部署一套 Kubernetes v1.26.0 集群网络插件用 Calico。听起来很常规是不是但实际做下来光准备工作就花了两天真正踩坑最多的不是 kubeadm 本身而是 Calico 装上去之后 Pod 网络起不来的那一堆破事。1.1 离线环境真正缺的是这四样东西先别急着讨论镜像。在断网机房部署 Kubernetes你需要逐个确认以下四类资源的可达性资源类型外网环境默认可用离线环境的替代方案容器镜像仓库Docker Hub / 云厂商镜像仓库自建 Harbor 或 registry提前同步镜像系统软件源yum / apt 在线源本地 DVD 源或自行制作离线 rpm 包集合域名解析公共 DNS内网 DNS 或直接写 /etc/hosts时间同步NTP 公网服务器内网 NTP 服务器或手动设置大多数人只想到第一项结果进去之后发现yum install 装不了依赖、coredns 解析不了集群内部域名、kubelet 报证书校验失败——每一件都够你折腾半天的。1.2 离线环境下的镜像准备策略镜像这块我推荐的做法是在有外网的机器上装好 skopeo 或 docker先把目标版本 K8s 组件镜像全部 pull 下来再推到内网仓库。具体怎么选型后面单独说。这里要特别提醒一个细节kubeadm 所需的镜像列表可以通过kubeadm config images list查看。拿 v1.26.0 举例默认需要这些镜像registry.k8s.io/kube-apiserver:v1.26.0registry.k8s.io/kube-controller-manager:v1.26.0registry.k8s.io/kube-scheduler:v1.26.0registry.k8s.io/kube-proxy:v1.26.0registry.k8s.io/pause:3.9registry.k8s.io/etcd:3.5.6registry.k8s.io/coredns/coredns:v1.9.3注意第一点不同 K8s 版本对应的 pause、etcd、coredns 版本是固定的你在外网随便 pull 一个 latest 是不行的必须和 kubeadm 要求的版本一致否则 preflight 阶段就会报错。再说第二个细节很多企业内网的镜像仓库是 HTTP 协议的没有 TLS 证书这种情况下你必须在所有节点的/etc/docker/daemon.json或 containerd 的 config.toml 里把这个仓库地址配到 insecure-registries 里否则拉取镜像会报证书错误。这个问题在离线环境里出现的频率极高因为内网运维通常不会给镜像仓库配正式证书。1.3 不只是镜像还要考虑系统依赖包这里插一个我吃过亏的地方。Calico 的 calico-node 组件对内核有一定要求特别是开启 eBPF 数据面的时候内核版本需要 5.7 以上。但很多内网服务器用的还是老内核3.10 或者 4.18导致 calico-node 启动后 Felix 进程报错。如果不打算升级内核老老实实用 VXLAN 模式或者 IPIP 模式别一上来就追新。另外K8s 集群所有节点都需要安装一些基础软件包比如ipset、iptables、conntrack-tools、socat。这几个包在离线环境下经常被忽略。你可以在外网机器上先执行yum install --downloadonly --downloaddir/tmp/k8s-deps ipset iptables conntrack-tools socat把 rpm 包都带进去再用rpm -Uvh *.rpm --nodeps批量装上。提前装好这些能避免后面 kubeadm init 时 preflight 报一堆 FAIL。2. 离线环境的三板斧镜像仓库、安装源、容器运行时这一节我把离线部署的前期准备拆成三块详细讲每一块都有明确的选型和操作步骤。2.1 自建镜像仓库registry 够用harbor 更稳如果集群规模不大、就几台机器用官方 registry:2 就够如果团队有几十号人、要多人共用、还需要镜像同步策略那直接上 Harbor。我推荐直接用 Harbor。原因有几个Harbor 自带 Web UI镜像列表、项目权限管理一目了然支持按项目做复制规则下次有别的离线环境可以直接从这台 Harbor 同步镜像支持 Helm Chart 存储后面要离线部署中间件会省很多事。Harbor 本身也是容器化的在线环境搭好之后把 Harbor 的镜像和数据库一并做成离线包带进内网即可。这里有个小技巧如果你只有一台机器能进内网那这台机器上最好同时跑 Harbor 和 Docker Registry 的反向代理形成唯一镜像入口所有节点都指向它方便管理。配置方面Harbor 默认监听 80 端口内网环境下可以直接用 HTTP。所有节点的容器运行时配置 insecure registry 即可。2.2 镜像导出导入skopeo 比 docker save/load 更推荐很多人惯性使用docker save把镜像打成 tar 包进去再docker load。但有几个弊端docker save 会把镜像的所有层打包文件很大如果镜像本来就在内网仓库里了再 save/load 属于重复劳动对 containerd 环境来说docker save 的 tar 包还得用 ctr 导入格式兼容不够直接。我更推荐用skopeo copy。它的优势在于可以直接在镜像仓库之间拷贝不需要本地 docker daemon支持按需转换格式docker-archive、oci-archive、docker-daemon拷贝过程更可控方便做批量脚本。离线场景的典型操作是这样的外网机器上先把需要镜像全部 pull 下来推到临时目录然后通过skopeo copy docker://registry.k8s.io/pause:3.9 docker://harbor.internal/k8s/pause:3.9这种方式直接推到内网仓库。全程不需要本地 docker速度也更快。2.3 本地 yum 源与 rpm 依赖包K8s 组件本身的安装包kubeadm、kubelet、kubectl可以从阿里云等镜像站下载 rpm 包版本固定后拷贝进内网。但这里需要连同依赖一起处理否则安装时仍然会因为缺依赖而失败。我最常用的办法是在外网干净的 CentOS 7.9 机器上执行yum install --downloadonly --downloaddir/tmp/k8s-rpms kubeadm-1.26.0 kubelet-1.26.0 kubectl-1.26.0然后把/tmp/k8s-rpms整个目录拷贝进内网cd进去后执行rpm -Uvh *.rpm --nodeps这里提醒一下加--nodeps是把双刃剑——它能跳过依赖检查但也可能掩盖缺失的依赖库。如果你的环境里缺 libc.so 之类的系统基础库kubelet 可能装上之后起不来。所以更稳妥的做法是用yum localinstall *.rpm -y让它自动从本地源找依赖如果本地源没有再考虑--nodeps但装完了一定要验证kubelet --version和kubectl version能正常输出版本。2.4 容器运行时containerd 是默认选择Kubernetes 1.24 之后彻底移除 dockershimv1.26.0 默认使用 containerd。所以离线部署这套版本我建议直接上 containerd不要再用 docker 去兼容。containerd 的离线安装也很简单下载containerd-1.7.x-linux-amd64.tar.gz和runc的二进制解压到/usr/local/bin生成 systemd service 文件即可。配置文件/etc/containerd/config.toml里面需要设置sandbox_image harbor.internal/k8s/pause:3.9否则 kubelet 创建 Pod 时会去拉外网 pause 镜像导致失败[plugins.io.containerd.grpc.v1.cri.registry.mirrors]配置内网 Harbor 地址最好把localhost也加进去。这一步没配置好你会遇到经典的Failed to pull image pause:3.9: failed to resolve reference报错而这一般要等 kubelet 创建 Pod 时才暴露出来属于隐藏很深的坑。3. kubeadm init 的 preflight看着是警告实则是离线部署的照妖镜准备工作完成后进入实际部署阶段。kubeadm init 执行后会输出一段日志开头类似[init] using kubernetes version: v1.26.0 [preflight] running pre-flight checks如果你在这个阶段看到连续的[WARNING]甚至[ERROR]先别急着跳过逐个看过去每一个都可能让你后面开机失败。3.1 preflight 到底检查了什么preflight 检查是一组系统环境与资源可用性验证内容包括内核版本与模块overlay、br_netfilter 是否加载swapkubelet 要求关闭 swap否则会 FAIL端口占用6443、10250 等是否被占用容器运行时能否通过 CRI 访问 containerd镜像拉取会尝试拉一个 pause 镜像验证 CRI 配置正确文件系统/var/lib/kubelet 等目录是否存在冲突。离线环境下preflight 最容易翻车的是容器运行时检查那一项。如果你的 containerd config.toml 还没改好crictl info能正常执行但 kubeadm 仍然会报[ERROR CRI]: container runtime is not running。这个检查项的根本逻辑是kubeadm 通过 CRI 插件去和 containerd 通信如果 sandbox_image 配的是外网地址在断网环境里它拉取失败就直接判定运行时不可用。3.2 离线环境下最常碰到的三个 preflight 报错我自己统计了一下给内网机器做 K8s 离线部署preflight 阶段最常出现的是下面三个[ERROR Swap]: running with swap on is not supported——内网服务器很多 Swappiness 没关或者/etc/fstab里 swap 分区没注释掉。处理方式是swapoff -a并且注释/etc/fstab然后重启确认。[ERROR FileContent--proc-sys-net-bridge-bridge-nf-call-iptables]: /proc/sys/net/bridge/bridge-nf-call-iptables contents are not set to 1——这是经典的网络转发问题。两个 sysctl 要配好cat EOF | sudo tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF cat EOF | sudo tee /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 EOF modprobe overlay modprobe br_netfilter sysctl --system[ERROR ImagePull]: failed to pull image ...——这个前面说过就是 containerd 的 sandbox_image 没改或者镜像仓库地址走不通。到这里前面准备的 Harbor 和 pause 镜像就派上用场了。3.3 init 成功后先别急着装 Calicokubeadm init 成功后会生成一串提示包括 kubeconfig 路径、join 命令等。但这个时候集群是裸奔的没有任何 CNI 插件Node 状态会是 NotReady这才是正常的。我习惯在装 Calico 之前先做三件事确认 etcd 是否健康kubectl get --raw/healthz/etcd返回 ok确认 apiserver 是否正常kubectl get --raw/healthz返回 ok在 master 节点crictl ps -a看看 pause 容器有没有正常起来。这三步能帮你把K8s 自身问题和网络插件问题切开。很多朋友一看到 NotReady 就说是 Calico 的问题结果查了半天发现是 containerd 没起来或者镜像配置不对这就是没先做基础验证。4. Calico 部署后 Pod 网络不通我的完整排查过程这里进入全篇的重头戏。Calico 装上去之后 Pod 网络不通是我在离线部署中遇到频率最高、耗时最长的一类问题每个项目几乎都能碰到一两个新花样。我按自己的排查经验把这套过程完整写下来希望能帮大家少走一些弯路。4.1 先给 Problemon 分层是 CNI 层、路由层还是策略层网络不通的时候第一件事不是去翻 Calico 日志而是先搞清楚问题是出在哪个层级。我的判断顺序是这样的先看 Pod 能不能拿到 IP在 Pod 内ip addr再看同一节点上两个 Pod 能不能互通接着看跨节点 Pod 能不能互通最外层是 Service 和 ingress 能不能访问。不同的失败位置指向的根因完全不同现象大概率原因Pod 内没有 eth0 网卡CNI 插件没被调用calico-node 异常同节点 Pod 不通veth 或路由表错乱跨节点 Pod 不通IPIP 模式BGP 邻居没建立、IPIP 封装被防火墙丢弃Pod 能通但 Service 不通kube-proxy 问题、IPVS 规则异常4.2 calico-node CrashLoopBackOff一查一个准的原因我先说一个通用经验kubectl get pods -n kube-system -o wide看 calico-node 的状态如果多个节点都在 CrashLoopBackOff那大概率不是单点问题而是全局性的配置错误。用kubectl logs -n kube-system calico-node-xxxxx看日志最常见的报错是Incorrect IP address or unknown host name: localhost这个报错出现在初始化时。原因基本只有两个一是你拉取的 Calico 版本与 Kubernetes 集群版本不匹配它去找 API Server 的地址时出错二是 Calico 的安装 YAML 里CALICO_K8S_NODE_REF或者etcd_endpoints配置不对。还有另一个高频报错Failed to create veth: operation not permitted这个在离线环境出现的概率特别高原因通常是节点内核没开启需要的模块或者容器运行时权限受限。最直接的解决办法是检查每个节点内核版本确认支持 Calico 需要的特性然后重启 containerd 再循环删除所有 Pod让 calico-node 重新创建 Pod。如果还是不行看是不是 SELinux 拦了/var/lib/calico目录的写入。4.3 BGP 邻居起不来网段冲突和 IPIP 模式如果你的 Calico 用的是 BGP 模式IPIP 或 VXLAN 都依赖 BGP那calico-node进程里的 bird 组件负责建立 BGP 邻居。排查的命令是kubectl exec -n kube-system calico-node-xxxxx -- calicoctl node status常见输出是BGP peer connections state idle或者active。我的经验是BGP neighbor 起不来的原因十有八九是节点网段冲突。举个具体的例子A 节点的内网 IP 是 192.168.1.10B 节点是 192.168.2.10而 Calico 默认的 Pod 网段正好是 192.168.0.0/16。这就和节点所在的物理网段撞车了。当 BGP 协议去学习路由时发现目标网段和自身网段重叠直接拒绝学进来Pod 到 Pod 就死活不通。针对这个问题的解决方案是在 Calico 的安装 YAML 里显式修改CALICO_IPV4POOL_CIDR把它改成一个和物理网络完全隔离的网段比如 10.244.0.0/16 或 172.24.0.0/16。另外提醒一下 IPIP 模式的防火墙问题。IPIP 封装的流量走的是 IP 协议号 4很多内网防火墙对非 TCP/UDP/ICMP 的流量是直接丢弃的。如果你发现同节点 Pod 通、跨节点 Pod 不通先用tcpdump -i eth0 ip proto 4看看有没有封装包在传输。如果被丢弃要么在节点上放行协议号 4要么直接切换 VXLAN 模式VXLAN 走 UDP 4789一般防火墙策略宽松一些。离线环境里我遇到最多的就是这个坑因为好多内网安全策略默认只放行固定端口的 TCP/UDP。4.4 网络策略过于严格导致的假故障最后一个高频问题Calico 默认安装后会自带一个default-deny的全局网络策略吗其实不会。Calico 默认是允许所有流量的。但如果你自己配了 NetworkPolicy 或者装了一些安全组件那就另说了。我记得有一次节点和 Calico 一切正常但业务 Pod 之间就是不通。排查到最后发现是另一个团队部署的默认拒绝所有入站流量的 NetworkPolicy 把业务端口全封了。这种假故障最难查因为所有底层指标都是正常的只有具体应用访问失败。遇到这种情况推荐按这个顺序查# 查看策略 kubectl get networkpolicies -A # 查看某个 Pod 被哪些策略命中 kubectl describe pod pod-name -n namespace如果确实策略问题可以先临时加一条Allow All的策略验证确认通了之后再收敛到最小化规则。这里有个经验在离线环境里团队内部沟通链路比开网络策略文档还重要很多策略加得隐蔽到排查的时候才发现是自己人拦了路。5. 离线部署的实操经验清单前面讲了完整流程和 Calico 排查主链路这一部分我把这些年离线部署 Kubernetes 的经验收敛成一份清单基本都是文档里不会写、但实战中大概率遇到的点。5.1 版本匹配是离线部署的第一原则K8s 集群组件版本、Calico 版本、containerd 版本、内核版本这四个必须提前核对清楚。我建议用下面的对照思路Kubernetes v1.26.0 对应的 kubeadm/kubelet/kubectl 必须同版本不能混Calico 3.25 支持 K8s 1.26再老的版本就不建议了containerd 1.7.x 对 K8s 1.24 支持良好内核建议 5.4 以上否则 Calico 的 eBPF 模式、部分网络策略功能受限。有一个省心的小技巧在离线环境里直接用 kubeadm 默认镜像版本和 Calico 官方推荐的版本组合别追求最新。你是在内网没有升级的条件稳定比新特性更重要。5.2 时间同步是隐形的定时炸弹内网机器一旦和外部 NTP 断联时间会慢慢漂移。Kubernetes 的证书校验对时间敏感kubelet 和 apiserver 之间如果时间差超过一定阈值证书直接校验失败报错通常不直观比如x509: certificate has expired or is not yet valid这时候你查证书有效期会发现证书没问题其实是本机时间不对。解决方法是搭一个内网 NTP 服务所有节点指向它。若无条件至少在部署前date -s手动校准一次并且把timedatectl set-ntp true打开。别小看这个环节我见过一个集群跑了一周之后突然所有节点 NotReady最终原因就是时间漂移。5.3 把后悔药准备好再动手离线环境不像在线环境出问题还能随时从网上拉新版本下来重装。所以我养成一个习惯在进内网之前把整个部署脚本、镜像清单、YAML 文件、rpm 包全部放到一个目录并打成一个 tar 包命名为k8s-offline-bundle.tar.gz带进去之后先在每台节点上解压到统一的/opt/k8s-bundle路径。同时把kubeadm config migrate之后的 kubeadm.yaml、kubectl -n kube-system get cm -o yaml这些关键配置都导出备份。真的遇到配置改坏了至少能回滚到上一个可用状态而不用从头再来。而在 Calico 的排障过程中我也养成了一个习惯每做一次改动就执行一次kubectl apply -f calico.yaml --dry-runclient -o yaml检查语法每重启一次组件就同时抓取calico-node的日志和kubectl get pods -o wide的结果放到同一个时间戳目录下。这样即使过了一整天也能靠时间线还原当时的系统状态不会陷入到底改了什么才变好的这种死循环。最后补充一条离线部署别追求一次成功最后再分享一点我的个人体会。离线环境部署 Kubernetes除非你是纯空闲时间充足、可以慢慢磨的测试环境否则我不建议抱着一次 init 成功、Calico 一条命令搞定的期待去操作。更实际的做法是在进内网之前用虚拟机完整跑一遍流程——从镜像同步、YAML 调整到 Calico 安装把可能要踩的坑先暴露一遍。我每次帮客户做离线部署都会先在本地用 VirtualBox 或 VMware 起三台同一 CentOS 版本的虚拟机完整跑一遍确认所有镜像和配置都没问题再进真实内网操作。这个方法帮我拦下了不下十次到时候才发现少了某个 rpm 包的尴尬。如果你正在准备做类似的离线部署项目我的建议只有一句话把准备工作的时间预估得比正式部署长三倍把 Calico 的排障步骤提前写到自己的笔记里备用。真到现场的时候你会发现省下来的时间远比想象中多。