干了这么多年运维和云原生相关的事我越来越觉得“离线部署”这件事才是K8s落地里真正难啃的骨头。网上教程不少但大多数是照着kubeadm init一把梭换到纯内网、没有镜像仓库、甚至连系统源都得走离线包的环境里立刻原形毕露。所以我今天想聊的是另一种更底层、也更可控的思路——用二进制方式离线部署一套K8s集群。整个过程不依赖kubeadm不给包管理器填坑的机会每一个组件都清清楚楚摆在你能看到的地方。这篇内容主要写给三类人看一是经常要往客户机房或者涉密内网交付平台的实施工程师二是被公司要求“把集群搬到隔离区”的运维同学三是那种明明有网也偏要手撸一遍、想彻底搞懂K8s组件协作关系的技术控。读完你不仅能搭起来还能搞清楚每一份证书、每一行启动参数背后到底是谁在用它。放心我不会把二进制部署说得高不可攀它其实就是把kubeadm替你做的那些事自己重新做一遍。1. 先搞清楚为什么是“二进制离线”这个组合1.1 三种部署方式的本质区别我见过很多刚接触K8s的同学有个误解以为kubeadm是K8s官方钦定的唯一部署工具。确实无论是测试环境还是生产环境kubeadm都是主流选择。但主流归主流它并不适合所有场景。我们常见的部署方式其实有三条路线第一条是包管理器方式也就是直接用apt或yum安装kubelet、kubeadm、kubectl然后由kubeadm去拉镜像、生成证书、组建集群。这条路在线环境十分钟搞定但它对“在线”的依赖感很强——它需要访问系统软件源还需要容器运行时能从镜像仓库拉取gcr.io上的官方镜像。一旦离线光是解决这两个“依赖源”就得写一堆手工操作那kubeadm就变得既不快也不傻瓜了。第二条是容器化方式比如用RKE、k3s、kind这类工具它们把K8s组件本身也跑成容器。好处是干净、升级方便坏处是又增加了一层镜像依赖离线时要么导入大量镜像包要么自己维护私有仓库。镜像数量一多介质制作和版本管理就成了新的恶梦。第三条就是二进制方式。从K8s官网下载server或node压缩包里面是编译好的可执行文件拷贝到目标机器上就能运行。etcd、apiserver、controller-manager、scheduler、kubelet、kube-proxy这些组件全部以systemd服务或者静态Pod的方式裸跑。没有额外镜像没有包依赖纯粹靠二进制和配置文件说话。对于离线环境来说这套思路省去了大量中间环节只要把软件包离线拷到位剩下全是配置文件的事。1.2 离线环境不是特例而是生产常态很多教程都在互联网畅通的前提下讲得头头是道实际到了现场才发现根本不是那么回事。我在一线遇到的客户环境大致可以分三类完全物理隔离的机房机器上只有操作系统和基础工具连个内网源都是奢望。公司内部网络虽然通但对外访问经过严格白名单容器镜像仓库、第三方源统统不允许访问。有内网私有化仓库但只允许放项目本身的东西不允许放公共基础件安全审计极其严格。这三类场景有个共同点你没法临时变通只能提前备好所有东西。所以掌握二进制离线部署本质上不是为了炫技而是运维手里一张压箱底的底牌。用的时候往往就是最不能出错的时候——交付窗口只给你一次。1.3 二进制部署到底难在哪二进制部署的难点从来不是“下载文件然后运行”这一步而是kubeadm帮你做掉的那些隐藏工作现在都要你自己来做第一是证书体系。K8s内部的每个组件通信都走TLSapi-server要签发给etcd、kubelet、scheduler、controller-manager的客户端证书kubelet又要有一套自己的服务端证书。有一套完整、正确、带SAN的证书体系折腾第一次的人没有不出错的。第二是启动参数。apiserver的启动参数有几十个controller-manager和scheduler也有各自参数。哪些是必须的、哪些是集群通信用的、写错了会有什么表现没有一定经验只能踩坑。第三是组件间的连接关系。apiserver怎么告诉controller-manager“你要去连etcd”、kubelet怎么知道要去注册到哪个apiserver、kube-proxy从哪里拿Service规则。这些连接靠的是各种kubeconfig和启动参数串起来断一环整个系统就瘫痪。但这恰恰也是二进制部署最大的价值一切都显式化、可控化。出了问题你能顺着每一份配置去排查而不需要去猜某个工具在黑盒里做了什么。2. 动手前的资源工程清单、规划与校验2.1 离线介质到底要准备什么离线部署最大的风险不是技术操作而是“到了现场发现少带了一个包”。我习惯把介质清单做成一张表每次开工前逐项打钩。我以一套最常见的主从架构集群为例假设是3台master节点加3台worker节点K8s版本以当下主流的1.28左右为例介质说明必须程度kubernetes-server-linux-amd64.tar.gz包含apiserver、controller-manager、scheduler、kubelet、kube-proxy、kubectl等全部服务端二进制必需etcd-v3.5.x-linux-amd64.tar.gz集群数据存储组件必需cni-plugins-linux-amd64-v1.x.tgzCNI插件包包含flannel等基础插件必需pause:3.9镜像kubelet创建Pod时的基础沙箱容器镜像必需coredns镜像集群内DNS服务必需flannel或calico镜像Pod间网络通信方案按需containerd离线安装包容器运行时含runc等依赖必需cfssl工具包用于签发证书也可以改用openssl推荐你可能注意到为什么下载的是kubernetes-server-linux-amd64.tar.gz而不是node版的因为server包里组件最全包含kubectl等控制端工具node包里没有apiserver。一套介质同时覆盖控制面和数据面最省事。这里有个小小经验所有压缩包下载后一定要顺手记录sha256值。我在一个项目里就吃过版本被替换的亏——镜像介质在多个部门之间转手拷贝最后发现某个机器的etcd二进制和别的机器哈希对不上排查了一整天才意识到是介质在拷贝过程中损坏了。所以下载完之后校验哈希再写进一份和介质放在一起的CHECKSUM.txt里这五分钟永远不会白花。2.2 节点规划与网段设计K8s集群中网络规划做好了能少一半麻烦。我用默认习惯作为例子你可以按环境灵活调整Service网段10.96.0.0/12这是apiserver分配给Service的虚拟IP段外部访问不到但内部必须是私有网段且不要和物理机网段冲突。Pod网段10.244.0.0/16这是容器Pod的IP池同样要保证和其他网段不重叠。节点网段比如192.168.x.0/24也就是你机器真实的物理IP网段。有人问这两个网段选错了会怎样最常见的后果是Service访问不通、Pod跨节点通信失败而且这种问题从现象上很难快速定位因为每个组件单独看都是正常的。所以规划阶段就要画清楚这两个网段和物理网段的关系。etcd这套组件建议和控制面同机部署方便管理也符合生产环境主流做法。如果是更大规模集群才考虑把etcd单独拆出去。2.3 在有网机器上制备介质制备介质这件事强烈建议在能上网的机器上统一完成不要指望到了现场“看看网络能不能通”。具体做法也很简单找一个同架构的Linux机器下载所有需要的tar包和镜像。镜像导出用ctr images pull加ctr images export或者先拉下来再save成tar文件。我把所有文件放在一个固定目录下比如/opt/k8s-offline然后打包传给现场机器。还需要提醒一句离线部署最好把容器镜像在开工前批量导入。到现场以后要么提前搭一个本地镜像服务要么每台节点手动导入。对于3台master加3台worker的规模手动导入完全可以接受。小规模搬镜像比搭仓库快得多真实场景里不需要把什么都做成“企业级”。2.4 主机基础环境预处理介质到位之后要先统一处理操作系统层的东西。我在每一台机器上会做这些准备关闭swap因为kubelet默认不支持swap开启虽然新版本有NodeSwapFeatureGate实验特性但生产环境还是关了稳妥。关闭防火墙或者至少放行K8s相关的端口如6443、2379、2380、10250等。说实话部署期间直接停了最省事部署完了再按安全要求补规则。写入内核模块参数比如net.bridge.bridge-nf-call-iptables1否则iptables转发在K8s网络里可能出问题。确认/etc/hosts里配置了所有节点的主机名与IP映射各节点之间用主机名互相解析证书里也大概率用的主机名。一个容易被忽略的细节是主机名里尽量不要带下划线。某些组件在解析主机名做证书匹配时会因为下划线出问题上线前统一检查一遍样式类似master01、node01是最安全的。3. 集群肚子的第一步etcd集群的二进制部署3.1 为什么一定让etcd先动K8s所有的状态数据——Pod、Service、ConfigMap、Secret、Deployment这些对象——全部保存在etcd里。没有etcdK8s就是一个空壳。所以搭建顺序上etcd必须第一个跑起来后面所有组件都是去读写它。etcd部署最需要注意的是它内部成员之间的通信和投票机制。一套三节点的etcd集群可以容忍一个节点故障。它内部工作用的是贯穿始终的Raft协议每个节点都维护一份完整的数据副本写入需要多数节点确认才算成功。理解这个逻辑你就明白为什么我们总是强调“只挂一台没事两台同时挂就可能丢数据”。我习惯把etcd直接以systemd服务形式跑在master节点上二进制放在/usr/local/bin/etcd数据目录放在/var/lib/etcd。启动参数全放/etc/etcd/etcd.conf.yml方便后续维护。3.2 etcd的证书逻辑不能含糊etcd和K8s其他组件之间用的是TLS双向认证。它的证书体系通常这么设计ca.pem整个集群共用同一个CA所有证书都由它签发。etcd-server.pemetcd对外提供服务的证书SAN里需要包含所有etcd节点的IP和主机名。etcd-peer.pemetcd集群内部节点之间通信用的证书SAN同样要覆盖所有etcd节点。后面apiserver访问etcd时还需要一份apiserver-etcd-client.pem这个由CA单独签给apiserver用。签证书的时候SAN列表是重灾区。很多同学只写了本机IP忘了写主机名和其他节点地址结果启动etcd时成员间握手失败日志里全是remote error: tls: bad certificate。我的做法是把每个节点的IP、主机名、以及可能的VIP地址全部写进SAN宁可多写不可漏写。多写不会带来安全风险漏写才是真麻烦。3.3 etcd配置与启动要点每台etcd节点的配置略有不同尤其是--initial-cluster里的成员列表要和每台机器的参数对齐。下面是一个单节点的配置示例生产环境按这个思路扩展即可name: etcd01>export ETCDCTL_API3 etcdctl --cacert/etc/etcd/pki/ca.pem \ --cert/etc/etcd/pki/etcd-server.pem \ --key/etc/etcd/pki/etcd-server-key.pem \ --endpointshttps://192.168.1.11:2379 \ endpoint health --cluster看到每个节点都返回is healthy这步就算踏实落地了。3.4 接手集群时的那个小教训这里分享一个我踩过的具体坑。有一次我在给一套老集群做二进制迁移直接用旧etcd的数据目录覆盖了新机器上的空目录然后启动时把initial-cluster-state配成了new。结果数据库里没有新节点信息成员之间反复互相踢整个集群的读都开始超时。后来把initial-cluster-state改成existing才恢复正常。所以如果你在已有数据的基础上恢复节点记住initial-cluster-state要写existing如果是在空的机器上做全新部署才用new。这个参数错了etcd会表现得非常“有主见”日志也不会直接告诉你“参数配错”只会让你反复在TLS和网络里猜很伤士气。4. 控制面三件套的部署与串联4.1 kube-apiserver整个集群的交通枢纽所有K8s组件包括kubectl最终都要和apiserver通信。apiserver通过etcd做数据持久化通过认证、鉴权、准入控制三个环节来保证请求安全性。从职责上看它就是整个集群唯一能修改etcd数据的门面。启动参数里比较关键的有这几个--etcd-servershttps://192.168.1.11:2379,https://192.168.1.12:2379,https://192.168.1.13:2379 --service-cluster-ip-range10.96.0.0/12 --service-node-port-range30000-32767 --client-ca-file/etc/kubernetes/pki/ca.pem --tls-cert-file/etc/kubernetes/pki/apiserver.pem --tls-private-key-file/etc/kubernetes/pki/apiserver-key.pem --service-account-key-file/etc/kubernetes/pki/sa.pub --service-account-signing-key-file/etc/kubernetes/pki/sa.key --service-account-issuerhttps://kubernetes.default.svc.cluster.local这里有两处不要写错。一处是service-cluster-ip-range它定义了Service虚拟IP池一定要和网络规划一致后期基本无法在线修改改了要重建一堆东西。另一处是service-account-key-file和service-account-signing-key-file是一对公私钥controller-manager那边用私钥签Tokenapiserver这边用公钥验Token两者必须能对上。我见过有同学走了神把两个文件填成同一个结果ServiceAccount Token全部验证失败整个集群的Pod调度逻辑直接整段崩掉。4.2 kube-controller-manager集群内部的常驻管家controller-manager是个很特殊的存在它本身不直接和用户交互而是在后台维护各种控制循环。比如有节点挂了要监测并标记NotReady有Pod漂移了要重新调度有Deployment期望副本数不匹配要拉起新Pod。它也不会主动找apiserver要数据而是持续通过apiserver观察集群状态然后把自己的修正动作写回apiserver。它在二进制部署里最容易漏的参数是证书签发相关--cluster-signing-cert-file/etc/kubernetes/pki/ca.pem --cluster-signing-key-file/etc/kubernetes/pki/ca-key.pem --service-account-private-key-file/etc/kubernetes/pki/sa.key --root-ca-file/etc/kubernetes/pki/ca.pem尤其是前两个证书文件K8s的Kubelet证书轮换、bootstrap Token的CSR自动批准全靠controller-manager拿着CA去签发。如果这两个参数为空你会发现kubelet那边疯狂请求核准证书却一直没有动静集群节点状态永远NotReady。这种问题在kubeadm的模式下几乎不会出现因为工具帮你配好了切到二进制漏配的概率极高。4.3 kube-scheduler决定Pod去哪住的策略师scheduler的职责很单纯监听新建的Pod选择一个最合适的节点去运行。它需要从apiserver读取节点状态、Pod约束、资源可用量然后做打分。它的启动参数相对少最常见的只有--kubeconfig和--leader-electtrue。在多master架构下--leader-elect必须开否则多个master上的scheduler会同时尝试调度同一条Pod导致调度决策冲突或者重复调度路径一错整个集群的任务排队就乱了。在三master控制面同时部署scheduler时要保证三台机器的启动参数尽量一致。集群里同一时间只有一个scheduler真正干活其余通过etcd的leader选举机制待命。这种“一主多备”的架构对mongod前压力不大但对二进制部署来说最重要的是把三份systemd unit文件写得完全一样避免后面排查时发现“master02和master03的参数不同”这种低级问题。4.4 三件套之间的连接验证三个控制面组件都起来之后可以通过一个小技巧快速确认链路健康。在任意master节点上用admin.conf访问apiserverkubectl --kubeconfig/etc/kubernetes/admin.conf get cs这个命令能看到scheduler和controller-manager的健康状态。不过我要提醒一句get cs输出的是组件自身向apiserver注册的health状态新版K8s中它已经渐渐不常用了。更靠谱的验证是去看apiserver的/healthz端点。拿curl打一下curl -k https://127.0.0.1:6443/healthz返回ok就说明apiserver自己活着。然后去etcd那边查一下集群对象是否正常读写组件是否各自持有正确证书日志中是否有TLS握手失败三件套里面的问题多数时候不是“组件本身坏了”而是“沟通证书不匹配”或者“kubeconfig里的server地址写错”。所以验证时要习惯看日志journalctl -u kube-apiserver -f这种命令应该成为肌肉记忆。5. 工作节点的关键一步kubelet与kube-proxy5.1 kubelet如何带着“密码条”加入集群整个集群里最难加入的部分就是kubelet因为它在集群里既当服务端给apiserver提供信息又当客户端主动向apiserver注册、上报心跳。它的身份认证核心就是bootstrap机制。通俗讲kubelet刚起来时手里有一张“一次性密码条”——bootstrap token文件它拿这个Token到apiserver申请证书然后apiserver里的证书签名控制器controller-manager签好新的客户端证书再交回kubelet。之后kubelet就用签发下来的证书定期与apiserver对话。这个流程避免了手工为每个worker节点单独生成证书并分发的高成本操作。部署时我们要在每台worker节点放两份文件/var/lib/kubelet/bootstrap-kubeconfig /var/lib/kubelet/kubelet-config.yamlbootstrap-kubeconfig的内容大概长这样apiVersion: v1 clusters: - cluster: certificate-authority: /etc/kubernetes/pki/ca.pem server: https://192.168.1.21:6443 name: kubernetes contexts: - context: cluster: kubernetes user: kubelet-bootstrap name: kubelet-bootstrap current-context: kubelet-bootstrap kind: Config users: - name: kubelet-bootstrap user: token: 38f7f1.9b1cd7c2e8b4这里Token是我实际部署中经常用来做演示的格式由随机字符生成有效期建议设置成和集群生命周期一致。如果你使用的是比较新版的K8sbootstrap token通常默认24小时有效不过这不是瓶颈只要集群建好后很快签发完证书token后续自然不再需要。5.2 kube-proxy的两种模式选择kube-proxy负责把Service的虚拟IP转发到后端的Pod。在二进制部署里它有两种主流工作模式iptables模式和ipvs模式。iptables模式是老牌方案实现核心是维护一大批iptables规则。规则多了以后性能会逐步下降但胜在兼容性好只要系统有iptables就能跑。对测试环境和小规模集群这样已经完全够用。ipvs模式用了内核中的IPVS模块它的规则是“表”而不是“链”查找性能高很多适合大规模Service和Pod的场景。但要求内核加载ip_vs相关模块没有加载的话启动后所有负载均衡都不会生效却不会报很明显的错误。我的建议是只要内核参数允许尽量用ipvs模式参数这样写--proxy-modeipvs --ipvs-strict-arpstrue同时提前确认内核模块modprobe ip_vs modprobe ip_vs_rr modprobe ip_vs_wrr modprobe ip_vs_sh modprobe nf_conntrack_ipv4 # 新内核中可能是 nf_conntrack5.3 CNI插件与pause镜像的离线处理kubelet本身不负责Pod网络它只负责启动容器。真正让Pod之间互通、Pod和外部互通的任务交给了CNI插件。离线部署时CNI插件是另一个坑。我常用的方案是flannel因为它的架构最简单二进制也容易离线分发。先把flannel的二进制放进/opt/cni/bin然后把flannel的Pod作为DaemonSet跑起来它会在每台节点上配置cni0和flannel.1这些网络设备。要注意flannel Pod的镜像也需要离线导入到每台节点否则Kubernetes调度时无法自动拉镜像只是节点间网络设备不会真的建起来表面看起来一切正常实际Pod之间完全不通。更隐蔽的一个坑在pause镜像。K8s创建任何Pod之前都会先拉取pause镜像作为沙箱这个镜像默认在gcr.io上。离线环境下必须提前导入并且要让kubelet和containerd知道“pause现在应该用哪个地址”。在kubelet配置文件中设置apiVersion: kubelet.config.k8s.io/v1beta1 kind: KubeletConfiguration podInfraContainerImage: registry.internal/pause:3.9如果不指定这个地址kubelet会老老实实去gcr.io拉镜像离线机器上自然是拉不下来的然后它会以为运行时环境有问题反复重启Pod日志里看起来全是镜像拉取失败很容易让人误以为是网络问题。6. 真正的试炼集群验证与常见风险的排查路径6.1 从零开始验证集群是否真的可用集群部署完成后不能只看节点状态就宣布“上线”。我习惯按下面的检查单从头跑一遍一条都不跳过节点状态kubectl get nodes所有节点必须是NotReady或者Ready至少要等NotReady状态变正常才算数。控制面Podkubectl get pods -n kube-system重点是coredns和flannel是否Running。DNS解析启动一个临时Pod去解析kubernetes.default.svc.cluster.local解析不通说明coredns没接好。Pod网络在任意节点跑一个静态BusyBox Pod再从另一个worker节点ping这个Pod的IP不通就要检查CNI。Service访问创建两个Deployment再建一个Service从集群内访问Service的ClusterIP确认负载均衡生效。NodePort访问在外部节点用NodeIP:NodePort访问服务确认kube-proxy转发链路完整。这个检查单一套下来大概四五分钟但能帮你在“看似正常”和“真正常用”之间划清界限。很多同学栽过的跟头就是get nodes全部Ready就欢呼结果coredns和flannel其实全挂整个集群连基本服务发现都是瘫痪的。6.2 镜像拉取失败离线环境的第一高频事故离线环境里容器镜像拉取失败几乎每天都会碰到。这里有个小经验通过containerd的ctr命令直接操作镜像比通过docker少一层兼容问题因为kubelet官方默认就用containerd。导入镜像的标准做法是ctr -n k8s.io images import coredns.tar ctr -n k8s.io images import pause.tar ctr -n k8s.io images import flannel.tar注意-n k8s.io这个命名空间不能省kubelet创建的容器都归属于k8s.io这个namespace。如果你用默认的default命名空间导入导入了但是没有放进k8s.iokubelet还是拉不到。这是我在多个项目中反复遇到过的情况。镜像导入完成后可以用ctr -n k8s.io images list确认镜像确实存在。如果下一步还想偷懒不搭私有仓库可以直接在每台节点的/etc/hosts里加一行某个内网地址把镜像的完整tag改掉后重新打tag再导入解放一只麻烦的生产链路。6.3 证书过期二进制部署周期里的定时炸弹二进制部署没有kubeadm那种自动轮换控制面证书的机制所以证书过期必须提前列入运维台账。我见过最惨烈的事故就是集群正常运行了一年多某天多个组件的日志同时开始报TLS错误排查半天才发现是apiserver服务端证书过期了。节点还是那个节点Pod还是那些Pod但“集群已经无法再接受任何写请求”。所以我的建议很简单部署完成后立刻写一条命令用于查看证书有效期openssl x509 -in /etc/kubernetes/pki/apiserver.pem -noout -dates把所有证书的有效期记录下来做成一个日历提醒。K8s中CA证书通常签十年而组件证书常签一年不设提醒的话刚好在你最忙的时候爆雷。另外如果你使用了kubelet的证书轮换功能--feature-gatesRotateKubeletServerCertificatetrue要确保controller-manager里的签发参数配好了这个功能才算真正闭合。6.4 kubelet无法注册从CSR到集群层的排查路径如果kubelet启动以后节点一直不Ready第一反应应该是看证书签名请求。执行kubectl get csr如果申请一直处于Pending问题多半出在controller-manager的cluster-signing-cert-file和cluster-signing-key-file没有配置好或者Token对应的身份没有获准创建CSR。如果是Approved状态节点依然NotReady就要去kubelet日志里看具体报错常见是cgroup配置和容器运行时不一致。cgroup-driver是个经典干扰项。如果kubelet用的是systemd而container runtime用的是cgroupfs调度时会直接拒绝Pod创建。二进制部署下因为是自己搭的runtime很容易出现两层设置不一致。处理办法是查一下运行时配置两边统一成同一驱动然后再重启kubelet。7. 收尾我对二进制离线部署的真实体会每次带团队做二进制离线部署我都会提醒一句话这不是一条“怎么省事”的路线而是一条“怎么彻底搞清楚”的路线。kubeadm帮你把组件都藏到静态Pod里看起来方便但出了问题同样难以下手二进制部署把一切摊平在系统层你能看到真实启动命令、真实证书、真实依赖关系这对K8s的长期维护能力是一次质变。我个人在实际操作中比较依赖脚本化来降低重复劳动。每套环境的一等变量IP、主机名、网段都会提前写到一份变量文件里然后生成证书、生成kubeconfig、生成systemd unit都各自写一个独立脚本。这样即使三个月后再扩展一套新集群这些资产直接复用不用从头再记一遍配置逻辑。最后再分享一个小技巧离线部署集群验收通过后别急着解散现场。挑一台新节点把整个流程从零开始跑一遍构建时间记下来放进交付文档里。如果哪一步出现了“只有老手才会顺手跳过”的操作那就是文档该补的地方。真正的交付不是交付集群而是交付一套别人也能完整重演的方法这才是二进制部署这条路线的终极价值。