简介面向具备Linux和容器基础的技术人员这份文档系统梳理了使用Rancher部署Kubernetes集群的完整路径从服务器准备、节点角色划分Control Plane、Worker、Etcd到Rancher Server两种安装方式测试环境Docker快速启动与生产环境高可用部署再到集群创建、节点注册命令调整、kubectl验证等关键环节。包体为单个docx文档约19KB内容紧凑、步骤明确。目前已有540人学习适合需要快速搭建生产级K8s环境或了解Rancher管理逻辑的运维与开发人员。文档不仅包含详细的部署命令和参数说明还覆盖常见故障排查如节点无法加入集群、网络插件异常以及扩展操作添加新节点、升级集群、备份恢复可直接作为实操参考手册帮助读者少踩坑、高效完成集群交付。1. 用 Rancher 部署 K8s先把“图形界面”这个预期放一边我最早接触 Rancher是接到一个需要同时交付三套 K8s 集群的活。手动执行 kubeadm 不是不行但每套集群都要处理证书过期、etcd 备份、组件版本对齐、节点故障转移这些重复劳动三套就是三倍工作量而且每一套都可能踩一遍同样的坑。Rancher 的思路是把“部署 K8s”变成“管理 K8s 的一种状态”你在界面上声明集群期望的版本、节点角色和数量它负责把 cluster 编排到目标状态承载这些任务的组件是 agent 和 controller浏览器里的 UI 只是控制面的一层皮。这篇笔记覆盖从准备工作、Rancher Server 启动、自定义集群与导入集群两条路径到集群管理里必调的参数、证书轮换和运维避坑最后落到版本升级、快照恢复和节点扩缩容。适合两种读者一种是刚接下 K8s 集群交付任务的运维另一种是手里已经有多套集群、想用统一入口做管理的平台工程师。如果你只是想看 k8s 部署教程级别的入门内容这篇也能跟但重点在生产怎么落地。2. 动手前先过三关节点规划、系统参数与私有镜像仓库在打开 Rancher 的浏览器页面之前有三件事必须做完节点怎么分角色、系统参数改没改、节点能不能稳定拉到需要的镜像。这三件事决定集群是一次性拉起还是你半夜被 etcd 告警叫醒。2.1 节点角色划分etcd、controlplane 与 worker 不要混成一道菜Rancher 创建自定义集群时每个节点需要勾选角色标签角色是etcd、controlplane、worker的组合。很多人第一次搭 K8s 集群习惯把所有角色勾在同一台机器上测试环境能跑生产环境就是给自己埋雷。etcd 承担整个集群的状态存储WAL 写入和快照对磁盘 IO 极其敏感controlplane 上的 apiserver 是每次kubectl请求的入口worker 才跑业务 pod。三者职责不同故障域也不同。我给的参考规划如下角色最低数量建议配置承担的工作etcd3必须奇数4C8GSSD独立节点保存集群全部状态强一致写入IO 敏感controlplane2 起步4C8Gapiserver、scheduler、controller-managerworker按业务冗余8C16G 起步承载业务 pod可水平扩展Rancher Server测试 1 台生产独立虚拟 IP4C8G 起步集群编排入口与 UI有一个反直觉的点Rancher Server 宕机不会让下游 K8s 集群停止调度业务流量照常走你只是暂时丢了管理入口。真正让集群瘫痪的是 etcd 和控制面同时出问题。所以 Rancher Server 优先用独立节点别和下游集群的 etcd 混部否则一次宿主机故障同时带走管理面和集群状态谁都救不了。主机名唯一性也是老生常谈但反复出现的坑。Rancher 把节点注册进集群时节点的主机名会被写进证书和 kubelet 配置两台主机名相同的节点会导致 agent 串线、证书校验失败。我一般在每个节点上先做一遍# 每个节点都要有唯一主机名比如 k8s-etcd-01 / k8s-cp-01 / k8s-worker-04 hostnamectl set-hostname k8s-worker-04 # 写进 /etc/hosts保证所有节点能互相解析 cat /etc/hosts EOF 10.10.0.11 k8s-etcd-01 10.10.0.12 k8s-etcd-02 10.10.0.13 k8s-etcd-03 10.10.0.21 k8s-cp-01 10.10.0.22 k8s-cp-02 10.10.0.31 k8s-worker-01 EOFhostnamectl set-hostname只改运行时主机名重启后仍然生效但你要确认发行版没有额外的 cloud-init 逻辑覆盖它比如云镜像上经常被回写。/etc/hosts里的内网解析主要给 etcd 节点之间的互访用也避免某些组件走 DNS 解析出问题时连不上 peer。这一套做完再往后走后面少很多排查时间。2.2 内核转发、Swap 与时间同步最容易被跳过的系统参数kubelet 和 CNI 组件对内核参数有默认要求Rancher 生成的节点注册命令不会替你改这些。最常见的两个坑是net.bridge.bridge-nf-call-iptables没开导致 NodePort 和 Service 访问异常以及节点 Swap 没关导致 kubelet 判定失败。我每次装节点都会先执行下面这段# 关闭 swapkubelet 默认要求 swap 关闭或显式配置 --fail-swap-onfalse swapoff -a sed -i / swap /s/^/#/ /etc/fstab # 内核转发与桥接流量规则K8s 网络不通多半是这里没配 cat /etc/sysctl.d/99-k8s.conf EOF net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 vm.swappiness 0 vm.overcommit_memory 1 EOF modprobe br_netfilter sysctl --system逐参数说明bridge-nf-call-iptables让经过 Linux 网桥的流量能被 kube-proxy 的 iptables 规则处理Pod 间通信和 Service 转发依赖它ip_forward是 Pod 访问集群外部网络的必要条件vm.swappiness 0配合关闭 swap防止内存回收把进程拖到不可用vm.overcommit_memory 1是很多部署手册会忽略的它让内核总是允许内存超卖避免某些节点因为预估 commit 不足直接 OOM。modprobe br_netfilter是加载桥接过滤模块重启后内核不会自动加载所以最好在/etc/modules-load.d/里写一行br_netfilter做持久化。时间同步单独拿出来说因为 K8s 和 Rancher 的证书校验强依赖时间节点时间偏差超过五分钟你会看到各种x509: certificate has expired or is not yet valid和 TLS 握手失败。这个问题排查起来很费时间因为现象长得像证书配置错误。yum install -y chrony systemctl enable --now chronyd chronyc sources -vchronyc sources -v输出里能看到同步源和偏移量^*开头表示当前使用的同步源处于正常状态。注意 Rancher Server 所在节点也要同步它管理和签发下游证书时间漂移会让新生成的证书在客户端校验时直接无效。2.3 容器运行时与私有镜像仓库先把最关键的镜像备好Rancher 的节点注册流程本质上是在目标节点上启动一个rancher-agent容器由这个容器拉起 kubelet、etcd 和其余组件镜像。换句话说节点必须能拉取 Rancher 相关镜像。网络环境不理想时这一步最容易卡住。我的经验是提前准备一个私有镜像仓库把rancher/rancher-agent、rancher/rancher、rancher/mirrored-pause以及目标 K8s 版本对应的组件镜像全部同步进去然后让节点上的容器运行时统一走私有仓库。容器运行时选择上Rancher 2.x 同时支持 Docker 和 containerd。自定义集群默认可以用 Docker 运行时注册但如果你用的是 containerd需要提前修改配置。以 containerd 为例在/etc/containerd/config.toml里加镜像 endpointversion 2 [plugins.io.containerd.grpc.v1.cri.registry] [plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.docker.io] endpoint [https://registry.internal.example.com]这里的endpoint指向你的私有仓库或代理仓库地址。containerd 解析镜像时会把 docker.io 的请求转发到这个 endpoint而不是直接访问公网。逻辑上是这五步节点 agent 请求镜像 → containerd 查 endpoint → 私有仓库响应 → 组件容器启动 → 节点注册完成。只要 endpoint 可达整个流程就跟外网完全无关。私有仓库要做好认证。建议在/etc/containerd/config.toml同级目录下配置hosts.toml或在 Docker 环境用docker login提前登录。这里有个常见翻车点镜像同步完了但节点上的容器运行时没有配置认证agent 容器还是拉取失败。日志里会报unauthorized和网络不通是两回事别混在一起排查。3. 部署 Rancher Server 与创建第一个工作集群准备工作做完开始正式部署。这一章先起 Rancher Server再走一遍“自定义集群”和“导入已有集群”两条路径。前者适合从零搭建后者适合把手里已有的 kubeadm 集群纳入管理。3.1 用 docker run 快速拉起单节点 Rancher Server测试环境我一般用 Docker 直接跑一个单节点 Rancher Server生产环境可以用 Helm 在 K8s 里部署高可用形态。单节点形态足够跑通完整链路也方便演示。启动命令如下docker run -d --name rancher-server \ --restartunless-stopped \ -p 443:443 \ -p 80:80 \ -v /data/rancher:/var/lib/rancher \ rancher/rancher:v2.8.5参数说明-v /data/rancher:/var/lib/rancher是 Rancher 的数据目录里面包含它自己维护的集群状态、证书和配置。不挂这个卷容器重启后一切归零后面你创建的所有集群记录全部丢失。-p 443:443必须暴露Rancher 的 Web 管理面走 HTTPS80 端口用于跳转和 Lets Encrypt 校验如果不需要申请公网证书可以去掉但保留更稳妥。镜像 tag 我用v2.8.5举例实际安装时要以你选择的稳定版本为准尤其是下游集群要用的 K8s 版本必须落在 Rancher 的兼容矩阵内后面避坑章节会细说。启动后等一两分钟拉取日志里的初始密码docker logs rancher-server 21 | grep Bootstrap Password新版本 Rancher 在首次访问https://server-ip时会要求设置管理员密码。如果你用了新版本日志里的 Bootstrap Password 就是初始凭据如果日志里没有这行直接访问 UI 页面也会提示你先初始化。这一步完成后Rancher Server 就是你的管理入口。3.2 在 UI 里创建自定义集群节点角色怎么勾选登录 Rancher UI 后选择“创建集群”然后选“自定义”或者“现有节点”。这里要填集群名称然后在节点池配置里勾选角色。UI 会生成一段docker run注册命令复制到目标节点上执行。注册命令长这样sudo docker run -d --privileged --restartunless-stopped \ --nethost \ -v /etc/kubernetes:/etc/kubernetes \ -v /var/run:/var/run \ rancher/rancher-agent:v2.8.5 \ --server https://rancher.example.com \ --token xxxxxxx \ --etcd --controlplane --worker逐项解释--privileged是 agent 容器操作节点网络和挂载时需要的权限--nethost让 agent 直接使用宿主机网络命名空间避免容器内 NAT 带来的端口映射问题-v /etc/kubernetes:/etc/kubernetes把 kubelet 和组件配置持久化在宿主机节点重启后配置不丢-v /var/run:/var/run让 agent 能看到宿主机运行时 socket。末尾的--etcd --controlplane --worker决定这个节点承担的角色可以多选但生产环境每个角色最好独立成节点。复制命令前先确认一件事--server这个地址必须是所有要加入集群的节点都能访问到的。如果节点和 Rancher Server 之间有防火墙443 端口不通agent 容器会起来但集群会一直卡在 provisioning 状态。执行完注册命令后回 UI 看集群状态。正常情况下节点会从 “provisioning” 走到 “active”整个过程 10 到 20 分钟取决于镜像拉取速度和机器配置。创建完成后下载 kubeconfig 文件kubectl --kubeconfigxxxxx.yaml get nodes能看到所有节点 Ready集群就交付了。这里顺带提一句 k8s 常用命令日常我基本只依赖kubectl get nodes、kubectl get pods -A、kubectl describe node、kubectl logs这四个其他的边用边查。3.3 把已有 K8s 集群导入 Rancher一条 kubectl apply 搞定如果你手里已有用 kubeadm 或 K3s 搭好的集群完全没必要重建Rancher 支持直接导入。操作路径是“创建集群 → 导入已有集群”UI 会生成一个 YAML 文件下载后到目标集群上执行kubectl apply -f import-cluster.yaml这个文件做的事就是在目标集群的cattle-system命名空间里创建一套 agent 和相关 RBAC 资源。执行后观察 agent 是否正常起来kubectl get pods -n cattle-system -w重点看cattle-cluster-agent的状态。如果是 Running 且没有频繁重启回到 Rancher UI集群会在几分钟内变为 active。导入路径不会动现有集群里运行的任何业务负载只是在集群里多部署一层管理组件风险很小。唯一要求是目标集群能访问到 Rancher Server而且server-url配置要和 Rancher 的访问域名一致否则 agent 回报状态会失败。4. 集群管理的日常操作角色标签、项目配额与证书轮换集群建好只是开始后面的管理才是日常工作。这一章讲三个高频操作节点角色查看与多控制面高可用项目配额管理以及证书轮换和 kubeconfig 重新生成。4.1 节点角色标签、多控制面与故障转移的配合方式Rancher 在节点注册时会把角色写进节点的 labels 和 taints。查看节点角色标签用这条命令kubectl get nodes --show-labels | grep node-role输出里你会看到node-role.kubernetes.io/etcdtrue、node-role.kubernetes.io/controlplanetrue、node-role.kubernetes.io/workertrue这样的标签。同时带 etcd 和 controlplane 角色的节点会被自动打上污点普通业务 pod 默认不会调度上去这是 Rancher 帮你做好的保护不要手动删掉这些 taint否则业务负载可能把控制面节点打满。为什么至少三台 master 才能保证高可用这是 K8s 集群搭建里最常被问到的点。控制面组件本身是无状态的apiserver 可以多副本分摊请求但 etcd 是强一致的必须多数派选举三节点允许挂一个五节点允许挂两个偶数节点没有实际收益。Rancher 创建集群时如果你勾选了三台节点的etcd controlplane角色它会自动完成 etcd 集群组建和 Rancher 自家负载均衡的配置。生产环境我一般推荐三台独立 etcd 加两台 controlplane虽然两台 controlplane 在 etcd 选主时并不参与投票但 apiserver 和调度器能实现 failover。# 查看 etcd 集群成员 kubectl -n kube-system get pods | grep etcd如果用了 RKE1 引擎etcd 是容器化部署在 controlplane 节点上的用 RKE2 时 etcd 是静态 pod。不管哪种看到三个 etcd pod 都是 Running 且没有告警说明多数派健康。4.2 用项目配额管好命名空间CPU、内存、权限一次配齐Rancher 的“项目”概念是 K8s 里没有的抽象一个项目是一组命名空间的集合配额和权限可以设在项目层。实际交付里我习惯按团队或业务线建项目比如“支付团队”“数据平台团队”然后把对应命名空间划进项目。好处是资源配额不用一个命名空间一个命名空间地重复设置。创建项目时配额字段里最常用的是配额项建议值作用requests.cpu按团队预算限制可调度 CPU 总量requests.memory按团队预算限制可调度内存总量limits.cpurequests 的 1.5~2 倍限制突发 CPU 上限limits.memoryrequests 的 1.5 倍以内防止单应用把内存打爆配额设置完项目下的所有命名空间共享这组限制团队内部怎么分由他们自己决定。这个设计比直接给整个集群设置 LimitRange 灵活得多因为你不用理解每个应用的具体资源画像只需要和团队对齐预算。权限这块Rancher 支持把用户绑定到项目角色项目成员、项目管理员、只读角色。如果团队要自己管理命名空间和应用给项目管理员就够别往上再给集群权限。4.3 证书轮换与 kubeconfig 重新生成K8s 集群的证书过期是个固定节奏的焦虑来源。社区里关于 k8s 集群证书过期自动续签的讨论一直很多kubeadm 的证书默认有效期是一年很多人第一次遇到是某个周一早上kubectl突然报certificate has expired。Rancher 在这方面有一个优势由它创建的集群证书轮换逻辑被内置在 agent 和 Rancher 管理面里你不需要去每个节点上手动算证书路径和续期命令。如果你用的是 Rancher 创建的集群到“集群详情 → 高级选项”里能找到证书轮换入口勾选需要轮换的组件证书保存后 Rancher 会自动触发滚动更新。比如 apiserver 证书要轮换它会先重新签发再按顺序重启 kube-apiserver 相关静态 pod。这个操作会短暂影响 apiserver 可用性最好在维护窗口做。如果遇到已经过期的证书节点上会持续报x509: certificate has expiredkubelet 无法连上 apiserver。这时先在 Rancher 端重新生成并下载新的 kubeconfig然后再做证书轮换。已经导入的集群如果 kubeconfig 过期可以在集群详情页直接下载新 kubeconfigRancher 签发的用户证书过期时间通常更长。还有一个绕不开的组件是cattle-cluster-agent它是下游集群回报状态给 Rancher Server 的通道。遇到证书相关的连接失败重启它会重新拉取证书并建立连接kubectl -n cattle-system rollout restart deployment cattle-cluster-agent这条命令是安全的不会影响业务 pod只会短暂中断管理面通信。重启后观察 pod 变成 Running再回 Rancher UI 看集群状态是否同步。5. 部署与运维避坑五个反复出现的故障点这一章全部来自实际操作里的踩坑记录。每条按现象 → 原因 → 解决写遇到同款问题可以直接照着处理。5.1 新建集群一直卡在 provisioning节点状态没有任何变化现象集群创建后长时间处于 provisioning节点列表里没有新节点出现agent 容器已经起来了但集群 controller 就是不加它。原因最常见的是版本兼容问题。Rancher 某个版本只支持特定范围的 K8s 版本比如你用的 Rancher 版本不能创建你选择的 1.29.x 集群或节点注册命令里的 agent 版本与 Server 不匹配。其次是节点访问不了--server地址agent 报错但 UI 只显示 provisioning。解决先去 Rancher 官方 releases 页面查兼容矩阵确认 Rancher 与 K8s 版本支持范围再检查docker logs agent容器里是不是在反复连接 server 超时。如果 token 失效回到集群编辑页重新生成注册命令不要复用旧命令。5.2 节点始终 NotReadykubelet 起不来现象节点注册成功但状态一直是 NotReadykubectl get nodes看到该节点显示 SchedulingDisabled 或 NotReady。登录节点执行journalctl -u kubelet -f能看到大量 failed to run kubelet 的报错。原因九成是系统参数没配。我排查过的案例里有几种具体表现swap 没关干净/etc/fstab里的 swap 行没注释重启后 swap 又挂回来br_netfilter模块没加载kubelet 检查网络插件前置条件失败还有 Docker 版本过新与 Rancher 支持的 containerd 版本不适配。解决回第二章的sysctl配置逐项核对。swapoff -a只是临时的必须把/etc/fstab里 swap 那一行注释掉。然后检查modprobe br_netfilter和sysctl --system是否真的执行成功。改完参数后重启 kubelet再等两三分钟看节点状态。这个坑在安装类教程里几乎没人强调但出现频率最高。5.3 导入已有集群后 cattle-cluster-agent 一直 CrashLoopBackOff现象执行完kubectl apply -f import-cluster.yaml后cattle-cluster-agentpod 反复重启日志里有failed to connect to server或 TLS 相关报错。原因目标集群访问不到 Rancher Server 的server-url。导入 YAML 生成的 agent 配置里写的是 Rancher UI 的访问地址如果这个地址在集群内部无法解析比如用的是外网域名而没有内网解析agent 就永远连不上。解决确认目标集群可以访问该域名最简单的方式是在集群节点上curl -k https://server-url/ping能返回pong说明网络通。如果域名解析有问题把 Rancher Server 地址也加到目标集群的/etc/hosts里然后删除原 YAML重新生成一份再 apply。不要手动改 agent deployment 的 envRancher 会认为集群配置被外部篡改状态反而更乱。5.4 etcd 节点反复重启日志出现 fsync took too long现象etcd 容器频繁重启日志里有took too long或fsync took too long集群状态 intermittent严重时 apiserver 报 etcd leader election 失败。此时节点 CPU 可能不高但磁盘 IO 明显异常。原因etcd 对磁盘延迟极其敏感common 做法里推荐的 SSD 不是随便说说。我用过机械盘跑测试集群etcd 在每天凌晨备份时 IO 飙升fsync 耗时超过 500msetcd 直接判定心跳超时并重新选举导致整个集群抖动。另一个原因是 etcd 节点上同时还跑了业务 pod流量高峰期 IO 争抢。解决etcd 节点必须独立部署不要在上面跑业务容器磁盘换 Nvme SSD 或至少是高性能企业盘检查iostat -x 1的%util和await如果等待时间持续超过 20ms就要考虑迁移节点或升级存储。另外给 etcd 设置资源上限避免它被宿主机上其他进程挤到饿死。5.5 Rancher Server 升级后登录 502 或直接白屏现象给 Rancher Server 容器升级版本后访问 UI 出现 502或者页面能打开但登录后空白。原因Rancher Server 容器启动后要跑数据库 migration有几个大版本升级路径要求先升级到中间版本直接跨大版本会导致数据迁移失败。另外数据目录权限不对、磁盘空间不足也会造成同样现象。解决升级前先备份/data/rancher整个目录这是后悔药。然后确认升级路径比如 Rancher 2.6 到 2.7 不能直接跳 2.8需要按官方支持的链路逐步升级。启动后看容器日志里是否有 migration 报错如果迁移失败把目录恢复回去再重来。注意恢复目录后容器会按旧版本数据启动但新版本的数据结构和旧版本可能不兼容所以这个操作越早做越好。6. 把集群养熟版本升级、快照恢复与节点扩缩容集群交付后真正要花时间的不是部署而是之后的例行升级和故障演练。这一章讲三个实用操作也是我每次交付都要求团队先练一遍的事情。6.1 用 Rancher 做集群版本升级别跳版本先看兼容矩阵在 Rancher UI 的集群详情页里编辑集群可以下拉选择 Kubernetes 版本保存后 Rancher 会按顺序滚动升级 controlplane 和 worker。升级操作最核心的一条原则不要跨多个小版本。比如 1.27 升 1.28 可以直接 1.27 升 1.29 很容易遇到 API 兼容性问题。每次升级前先看 Rancher 与目标 K8s 版本的兼容矩阵再确认业务里有没有用到已经被弃用的 API。升级过程中观察 controlplane 节点先更新完毕然后 worker 逐个滚动中途任何一个节点 NotReady立即暂停升级并看 kubelet 日志。6.2 etcd 快照与 Rancher Server 备份恢复Rancher 对自定义集群提供内置的 etcd 快照能力配置位置在集群详情的高级选项里可以设置快照周期和保留数量。我一般设置每天一次快照保留 5 份。更重要的是 Rancher Server 自身的数据备份因为它保存着所有集群的配置和证书丢了它管理面就变成黑匣子。常见做法是把/data/rancher目录定期打包传输到独立存储或对象存储同时在 Rancher 设置里配置后台上传到 S3 兼容存储。恢复演练我有过一次惨痛经历Rancher Server 数据盘损坏虽然下游集群还在跑但管理面所有集群配置都看不见了。还好有备份恢复后几分钟内所有集群状态全部回来。核心是备份文件里包含证书和 token恢复后不需要重新导入集群。6.3 节点排空、扩容与僵尸节点清理扩节点是我觉得 Rancher 比命令行 kubeadm 体验好最多的地方。新节点加入前安装好容器运行时到 Rancher 节点页面复制新的注册命令执行即可。下线节点先做排空kubectl drain node-name --ignore-daemonsets --delete-emptydir-data排空是为了让 kubelet 将 pod 优雅驱逐到其他节点--ignore-daemonsets保留 DaemonSet 管理的系统组件--delete-emptydir-data释放临时目录。排空后到 Rancher 节点列表删除该节点记录再清理节点上的残留 kubelet 配置。直接删节点不排空是我见过最常见的翻车方式会导致 pod 在其他节点上重复调度旧 pod 还没撕掉。如果节点异常宕机无法排空等它重新恢复后 Rancher 会自动重新调度 pod 并清掉残留状态只有彻底放弃的坏节点才需要手动删除记录。最后说一个我的个人习惯。每次交付 Rancher 平台我都会在交付文档里固定记录三个东西Rancher Server 的访问域名及证书到期日、etcd 快照的 S3 配置位置、最后一个恢复演练的时间点。后面排查问题时这份记录能帮你省下大量重新定位的时间。希望这份指南对你有用。本文还有配套的精品资源点击获取