基于RKE的Rancher管理平台迁移：备份恢复与下游集群重连

最近我把一套跑在RKE集群上的Rancher管理平台从旧机器整体迁到了新环境。Rancher本身不复杂复杂的是它管理的一堆下游集群——每个下游集群里的agent都只认原来的server-url和证书。迁移过程中先后经历了备份、恢复、agent重连、证书替换最后还要处理一堆历史配置残留。这篇文章把我这次基于RKE部署的Rancher管理平台迁移的完整过程、关键命令和后来复盘出来的几个坑都写出来希望给要做同样事情的人一个参考路径。全文涉及Rancher版本与K8s版本的对齐、backup operator备份恢复、下游集群重连验证以及几个我在迁移过程中踩过的典型问题。1. 先想明白RKE架构下Rancher迁移到底在迁什么1.1 RKE与Rancher的分工梳理RKERancher Kubernetes Engine是一个通过一条命令拉起Kubernetes集群的工具它用cluster.yml描述节点信息和集群配置执行rke up后生成一套可用的K8s集群。而Rancher是跑在这套集群上的容器化应用通过helm chart安装到cattle-system命名空间用来管理它所在的local集群以及其他外部集群。这两个层次一定要分清楚RKE负责“盖房子”Rancher负责“住进去做管理”。迁移的时候房子要重新盖但里面的家具、账本、住户登记信息都要尽量原样搬过去。这里的“账本”主要就是Rancher在K8s里持久化的各种自定义资源CRD、configmap、secret、RBAC以及底层etcd中的状态。1.2 为什么不能直接“打包拷贝”很多人第一次接触Rancher迁移时会想Rancher不是一堆容器吗把镜像、数据目录复制过去不就行了实际上Rancher管理平台的状态高度依赖Kubernetes的API对象和etcd它内部还有多个controller通过watch机制同步信息。直接拷贝镜像和静态文件完全没有意义因为Rancher生成的密码、token、私钥存在secret里单独复制一份出来并不代表可用对象之间的引用关系必须一起带过去。下游集群通过agent和Rancher保持心跳agent里记录的是server-url和证书信息单纯复制会导致agent指向错误的地址。Kubernetes本身是分布式系统它的etcd数据包含节点IP、证书等不能把一套集群的etcd直接丢给另一套集群用。可以把这个过程类比成搬家搬家具容易但你得先把户籍、水电燃气这些登记信息同步过去不然新家里通电通水了原来的账单还是寄到旧地址。迁移的本质是“数据、身份、网络信任”三者的整体搬迁。1.3 迁移完成后的目标状态迁移完成后我们希望达到如下状态新集群上的Rancher版本和旧环境一致或者至少满足升级兼容矩阵。登录账号、权限角色、全局设置、用户密码全部保留。下游集群仍然被Rancher管理agent自动重新注册。审计日志、监控配置等可选组件按需保留。为此迁移前需要把旧环境的信息完整记录下来建议用表格逐项填写Rancher版本、Helm chart版本、K8s版本、RKE版本、server-url、证书类型、外部认证方式、下游集群数量、以及是否有自定义的CRD或存储配置。记录项示例值用途rancher/rancher镜像版本v2.7.8新环境安装时需要对应helm chart版本103.1.5避免restore时版本冲突rke --versionv1.4.10新环境RKE版本对齐server-urlhttps://rancher.example.com下游agent连接的关键证书类型受信CA证书 / 自签证书决定是否要迁移私钥认证方式本地用户 / LDAP / OIDC决定外部认证是否需要二次配置下游集群数量7个迁移后验证清单1.4 常见迁移方案对比方案ARancher backup-restore-operator备份恢复。在旧集群安装backup operator创建Backup CR把Rancher关键资源resourceSet备份到S3兼容对象存储或本地路径新环境反向操作Restore。优点是备份粒度精准、官方维护、适合迁移场景。缺点是这个工具只覆盖Rancher自身状态底层K8s的网络插件、ingress等需要另建。方案B对承载Rancher的K8s集群做etcd快照然后在新环境用相同的RKE配置重建集群再恢复快照。优点是Rancher本身几乎无感知。缺点是对新旧环境的pod CIDR、service网段、甚至node名称一致性要求很高灵活性差不太适合换机器、换机房的场景。方案C全新部署Rancher再手工配置或通过API迁移用户、项目。优点是环境干净。缺点是工作量大、极易遗漏而且有很多不可复制的内容比如agent注册token、审计日志历史、部分CRD状态。方案优点缺点适用场景backup operator迁移官方维护、粒度精准、状态完整只覆盖Rancher资源换机器、换机房、版本不变或小版本升级etcd快照恢复整个集群状态整体搬迁对网络段、节点名要求高纯硬件迁移且网络规划不变全新部署手工配置无历史包袱工作量大易遗漏旧环境已不可用且业务允许重建我这次采用的是方案A为主B作为备选兜底。这也是官方推荐路径下文主要围绕它展开。2. 动手前先把家底盘清楚必须带走的数据和状态2.1 资源清单不止cattle-system一个命名空间Rancher在K8s里并不是只往cattle-system里写数据。备份的时候至少要考虑这些对象cattle-system命名空间Rancher pod、service、相关configmap。cattle-pipeline流水线相关配置。cattle-logging、cattle-monitoring、cattle-alerting日志、监控、告警配置如果没启用就没有。management.cattle.io组下的CRDCluster、Project、User、GlobalRole、Setting、Token等。secret包括admin密码hash、服务账户token、agent注册token等。RBAC自定义的角色绑定和权限设置。使用backup operator时它默认的resourceSet已经覆盖了这些主流对象。实际操作中我在Backup CR里显式使用官方预置的resourceSetName这样不容易漏。不建议手工指定一堆命名空间因为很容易漏掉某个CRD等恢复后缺数据再排查就很被动了。2.2 版本和配置信息盘点迁移前必须记下来除了数据还有几类配置信息必须提前记录。否则迁移到一半会发现server-url指向旧地址AI大模型都救不了你rancher/rancher镜像版本以及helm chart版本用helm ls -n cattle-system查看。RKE版本用rke --version查看。K8s版本用kubectl version查看或者看RKE cluster.yml里的kubernetes_version。server-url在Rancher UI的全局设置里查看这是下游agent连接的关键。认证方式如果用的是本地用户备份里有密码hash恢复后原密码仍可用如果接的是外部LDAP或OIDC迁移后需要在新环境重新配置认证提供方地址或信任关系。ingress证书类型自签还是受信CA签发。如果在迁移中更换域名或IP证书也要同步更新。强烈建议把上面这些写到一个固定文档里迁移过程中每一步都对照着核对。我的经验是文档里漏掉一个版本号后面恢复时可能多花两个小时来排查。2.3 备份实操安装backup operator并创建Backup CRbackup operator通过helm chart安装命名空间是rancher-backup。安装完成后创建一个Backup CR结构类似apiVersion: resources.cattle.io/v1 kind: Backup metadata: name: rancher-backup spec: storageLocation: s3: bucketName: my-rancher-backups region: ap-east-1 endpoint: s3.example.com resourceSetName: rancher-resource-set encryptionConfigSecretName: backup-encryption-secret几个字段的意图说下storageLocation备份文件存到S3兼容对象存储也可以配置local存到节点路径。生产环境建议S3兼容存储方便新环境读取。encryptionConfigSecretName可选。如果旧环境有敏感数据需要加密就得用同样的加密配置否则新环境restore时解不开。resourceSetName官方预置的资源集默认使用rancher-resource-set。创建后观察状态等状态变为Completed表示备份完成。备份文件会生成一个tar.gz包里面是包含Rancher资源和CRD定义的一个清单。备份成功后确认一下输出的文件名后面Restore要用到。提示关于加密secret如果旧集群里配置了新集群安装backup operator时也要把这个secret一起建出来并且内容一致否则restore会直接失败。这是最容易忽略的坑。2.4 备份完成后的验证备份状态Completed不代表万事大吉。建议先下载备份文件确认tar.gz包大小不是0字节再用tar解压看一眼里面的资源列表。我遇到过备份文件生成成功但因为S3接口兼容问题文件内容是残缺的到restore阶段才暴露。提前解压验证几秒的事能省下后面一整天的排查。3. 新环境搭建RKE拉起集群时的版本对齐与资源规划3.1 版本对齐是迁移的第一原则先决定新环境的K8s版本。原则是新集群的版本与旧集群一致或者至少位于Rancher版本对应的支持矩阵之内。版本差太大的话Rancher chart在restore过程中可能出现CRD版本冲突、API group变更等问题导致升级不动、pod起不来。RKE本身也分版本旧环境用哪个版本生成的RKE新环境最好也用同一个版本。RKE生成的集群里kube-system下的一些组件版本和配置会有细微差异版本不一致会加大后面排查的难度。另外如果这次迁移同时想升级Rancher大版本我的建议是分两步走先按旧版本迁移稳定运行后再做升级。不要边迁移边升级一次只引入一个变量否则出了问题你不知道是迁移导致的还是升级导致的。3.2 cluster.yml的关键配置保持一致性在RKE集群的cluster.yml里有几个参数会影响Kubernetes网络层和证书层迁移时尽量跟旧环境保持一致network.plugin最常用canal或flannel新旧环境建议一致。services.kube-controller的service_cluster_ip_range与cluster_cidr集群内部地址段建议保持与旧集群一致。如果变了Rancher里已存在的服务路由和网络策略可能会出问题。kubernetes_version保持同版本。nodes配置可以用新的主机名和IP这是允许变化的因为K8s节点身份会重新生成。老规矩改节点IP没问题但pod CIDR和service网段不能随意改迁移后很多已创建的服务地址和网络策略都是基于原网段的。3.3 新环境节点资源规划Rancher管理平台自身不重但也不要太寒酸。承载Rancher的K8s集群至少用3个节点组成etcdcontrolplane角色生产建议每个节点4核8G起步磁盘用SSD并且40G以上。如果还要在下游集群上使用监控、告警资源再往上浮。RKE要求节点能访问公开镜像仓库或者提前把镜像推到私有仓库并在cluster.yml里配置registry认证。新环境的节点时间同步也一定要做好K8s证书和agent锚定时间偏差太大会直接握手失败。这些基础项出了问题后面恢复Rancher时出现的报错会非常奇怪。3.4 初始化后先做基础验证别急着恢复执行rke up之后先用kubectl get nodes -o wide确认所有节点Ready再用kubectl get pods -A确认kube-system和ingress-nginx的pod全部Running。这时候先不要急着装Rancher或者做restore先把网络层验证一遍。比如随便跑一个测试服务确认集群内部DNS正常、pod之间可以通信。等基础集群稳定后再用helm安装Rancher chart。安装时用一个临时的bootstrapPassword即可后续会被备份数据覆盖。4. 恢复数据那一刻backup operator restore实操细节4.1 恢复前置准备新环境恢复之前先把backup operator装上命名空间同样是rancher-backup。这一步和旧环境安装基本一致需要注意两点如果备份时用了encryptionConfigSecretName新环境要先创建同名secret内容保持一致。如果备份文件在S3兼容对象存储新环境要确保网络可以访问这个地址尤其是私有化部署的对象存储防火墙规则要提前配好。4.2 restore CR的编写restore CR示例apiVersion: resources.cattle.io/v1 kind: Restore metadata: name: rancher-restore spec: backupFilename: rancher-backup-xxx.tar.gz storageLocation: s3: bucketName: my-rancher-backups region: ap-east-1 endpoint: s3.example.com resourceSetName: rancher-resource-set prune: true几个字段的意图backupFilename必须指向备份时生成的文件名。prune恢复时是否删除目标集群中已有的、不在备份里的Rancher资源。强烈建议设为true否则新环境安装Rancher chart时会预创建一些默认对象和备份数据混在一起容易冲突。storageLocation和备份时保持一致。创建restore后backup operator会在cattle-system里启动Rancher pod并恢复数据期间UI可能短时不可用需要耐心等。观察restore状态到Completed再删除restore对象。4.3 恢复后的首次登录和原始凭据恢复完成后Rancher会自动重启。用旧环境的管理员账号密码登录如果用临时bootstrapPassword是登不进去的。如果旧环境密码也没记录在恢复前提前从旧集群的secret里把admin密码hash导出或者干脆在迁移前重置一次管理员密码并记录下来。登录之后全局设置里的server-url非常关键。如果新环境地址变了要立刻改过来。改server-url时Rancher会尝试重新生成下游集群的agent注册配置。4.4 为什么顺序必须是先有Rancher基础chart再restore有人问为什么不能在一台空K8s集群上直接安装backup operator然后restore因为restore本质上是把Rancher自身的资源对象覆盖进去但它没有能力重建Rancher chart全部初始化流程所依赖的骨架。比如cattle-system命名空间的基础对象、ingress、serviceAccount等。先安装Rancher chart可以把这些骨架搭好然后再用备份数据覆盖血肉。骨架和血肉来自同一个版本时最稳。4.5 恢复后的第一轮验证登录Rancher UI后先看全局设置、用户列表、角色权限是否完整。再进入local集群看节点负载是否正常。此时下游集群大概率显示Disconnected不用慌这一步正常下一步处理。5. 迁移后最麻烦的部分下游集群怎么重新接回Rancher5.1 失联原因分解下游集群失联的直接原因通常是agent注册时保存的server-url还是旧地址DNS切换后连不上。证书不匹配TLS握手失败。Rancher服务端生成的新token没有分发下去。防火墙或安全组没放行新的管理集群端口。可以这么理解下游集群的agent就像一台老式电话机号码簿里记的还是旧号码。你要让Rancher这边的座机先确认自己的新号码然后想办法把新号码通知给所有电话机。5.2 先让server-url和证书确定下来迁移后第一件事是把全局设置里的server-url改为最终对外地址并确认证书有效。如果地址变化导致证书不匹配通常需要更新Rancher ingress的TLS secret换成覆盖新地址的证书。在Rancher UI的Settings里触发配置刷新。之后下游集群的agent如果自动重连失败再手动重发。如果旧环境用了自签证书迁移时要保留私钥和完整证书链不能只带一个crt。私钥不匹配的话agent全部握手失败报的都是x509错误。5.3 自动重连与手动兜底大部分情况下只要server-url正确、网络通畅cattle-cluster-agent和cattle-node-agent会在几分钟内恢复正常。判断方法在Rancher UI查看下游集群的状态从Disconnected慢慢变回Active。在下游集群执行kubectl get pods -n cattle-system看cattle-cluster-agent和cattle-node-agent是否Running。如果仍异常查看agent日志常见的是x509证书错误或request timeout。手动兜底路径在Rancher UI进入对应集群的编辑页面找到Registration Token重新生成或查看kubeconfig。拿到该集群的agent manifest。在下游集群里删除旧的agent Deployment/DaemonSet让它们重新拉取最新配置。更直接的做法在目标集群对应页面用Edit Cluster重新保存一次Rancher会重新下发注册命令。5.4 验证每类角色的状态可以用一张表辅助验证检查对象参考命令预期结果Rancher管理集群节点kubectl get nodes全部ReadyRancher podkubectl get pods -n cattle-systemRunning下游集群cattle-cluster-agentkubectl -n cattle-system get podsRunning或重建后正常下游集群cattle-node-agentkubectl -n cattle-system get daemonset正常调度Rancher UI集群列表集群管理-集群状态为Active5.5 证书和token的实操经验如果要保留原有自签证书新环境必须把旧证书的私钥、证书链完整带入不能只带一个crt。如果是迁移后重新签发证书那么下游集群必须能通过新地址验证服务端身份否则agent全部握手失败。比较省事的做法是迁移后直接换成受信CA签发的域名证书一劳永逸。还有一个细节Rancher的agent注册token是有有效期的如果迁移间隔太久token可能已经过期。这种情况下重新生成新token即可。6. 复盘走过的弯路典型失败场景与排查链路6.1 场景一恢复后Rancher UI起来了但登录一直报错我遇到过restore完成后页面反复提示Unauthorized的情况。排查下来发现是临时装的Rancher chart和备份数据的版本不一致导致admin用户相关CRD冲突。解决方法是把Rancher chart卸载重新装到与旧环境一致的chart版本再restore。所以恢复前核对chart版本绝对不要省。这一条异常重要。6.2 场景二下游集群显示Disconnectedagent日志报TLS错误agent日志里的典型错误是certificate signed by unknown authority或x509: certificate is valid for xxx。这说明agent拿到的证书和当前server-url不匹配。处理步骤确认server-url和实际访问地址一致。确认ingress证书是新地址的有效证书。在下游集群删除cattle-system下agent相关pod强制重建。如果还不行直接在Rancher里重新生成registration token并apply。6.3 场景三新集群上的Rancher pod一直ImagePullBackOff新环境通常还没配好镜像仓库的登录信息特别是从私有镜像仓库拉Rancher镜像时。处理手段是提前在节点上配置docker login或者在cluster.yml和Rancher chart的values里配置imagePullSecrets。旧环境用了哪些镜像建议提前导出镜像清单避免新环境临时找镜像。6.4 场景四prune没开恢复后Rancher里混着一堆重复对象临时安装的Rancher chart会预创建默认的集群对象。如果restore时prune没开备份里没有的默认对象会留在系统里看起来像多出来几个服务或项目。它们的资源类型和正常对象混在一起排查很费劲。所以restore时prune尽量设成true。6.5 排查思路的层次总结几条排错顺序第一层网络通不通。从下游集群节点执行curl -k https://新server-url:443。第二层证书对不对。检查证书域名、有效期。第三层server-url对不对。在Rancher全局设置里看。第四层Token和agent配置有没有更新。看agent日志和registration token。第五层版本和CRD有没有冲突。看Rancher pod日志和CRD版本。按这个顺序走大部分问题的根因都能定位到前四层。如果真的到第五层基本就是版本规划的问题需要回到备份和chart版本匹配这条线上重新对齐。6.6 一个小建议迁移前先完整演练一遍如果你的环境比较复杂比如下游集群非常多、有自定义RBAC、有外部认证强烈建议先搭一个临时环境完整演练一遍备份、恢复、下游重连、验证。演练过程能暴露大部分问题也会让你对restore的耗时和UI中断时间有预期真迁的时候心里有底。回到开头说的那次迁移。整个过程让我印象最深的不是restore那一下而是备份清单和版本记录是否完整。只要这些基础信息是齐的迁移就像按照地图走一遍反过来最基础的版本不匹配就能让你卡住半天。以后再接到类似的Rancher迁移任务我会先花半小时盘点版本、server-url、证书和备份文件再动手。迁移窗口期尽量选在业务低峰restore过程中的UI中断时间通常不会太长但下游集群重新注册的时间取决于集群数量和网络状况。总体来看基于RKE部署的Rancher迁移只要把握住数据、身份、网络信任这三件事不会出大问题。