KnoAI 技术站

主题

Rancher 控制节点添加失败排查文档（192.168.122.36 / szb122036） ​

  • 排查日期：2026-08-13
  • 环境：Rancher v2.14.3（sza 管理集群 192.168.122.20/21/22，域名 ai-ear.cn）
  • 目标节点：szb122036（192.168.122.36，8C32G，Rocky 9.8）
  • 下游集群：uat-jenkins（fleet-default，custom 自定义集群，RKE2）

问题现象 ​

通过 Rancher UI 自定义集群方式将 192.168.122.36 添加为控制节点（etcd + control-plane），节点长时间卡在 Provisioning，RKE2 始终未安装。

排查过程与根因 ​

本次共发现 3 个递进的问题，依次解决：

问题 1：RKE2 planner 拒绝生成 plan（etcd 平面整体替换保护） ​

现象：

  • machine custom-7f28e7d6f30c 卡在 Provisioning，WaitingForNodeRef
  • machine-plan secret 存在但 DATA=0（空 plan）
  • .36 上 rancher-system-agent 反复 watch secret 报 HTTP/2 INTERNAL_ERROR，永远拿不到 plan

根因（Rancher pod 日志每 2 分钟重复）：

[planner] rkecluster fleet-default/jenkins: rkecontrolplane was already initialized
but no etcd machines exist that have plans, indicating the etcd plane has been
entirely replaced. Restoration from etcd snapshot is required.

集群 jenkins 首次注册时已由第一台 etcd 节点成功初始化（jenkins-kubeconfig、jenkins-rke-state secret 均已生成），之后初始 etcd 机器被删除，.36 重新注册产生新 machine。planner 判定为"etcd 平面整体替换"，出于防脑裂/防数据丢失保护拒绝生成新 plan，要求走 etcd 快照恢复流程。

解决：测试集群无数据，直接删除集群重建：

bash
kubectl delete clusters.provisioning.cattle.io jenkins -n fleet-default
# 节点侧清理
ssh rocky@192.168.122.36
sudo rm -rf /var/lib/rancher /etc/rancher

教训：自定义集群注册后不要中途删除 machine / 重复注册，否则触发该保护机制。

问题 2：私有镜像仓库 mirror endpoint 缺少 http:// 前缀 ​

现象（重建后 plan 正常下发，agent 开始执行但失败）：

Pulling image 192.168.122.156:30000/rancher/system-agent-installer-rke2:v1.35.7-rke2r1
error: Get "https://192.168.122.156:30000/v2/": http: server gave HTTP response to HTTPS client

根因：集群 spec .spec.rkeConfig.registries 中 mirror endpoint 未写 scheme：

yaml
mirrors:
  "*":
    endpoint: ["192.168.122.156:30000"]   # 无 scheme → 默认 HTTPS，而 Harbor 是 HTTP

解决：endpoint 改为 http://192.168.122.156:30000，并关联 Harbor 认证 secret（registryconfig-auth-7xjcs）：

bash
kubectl patch clusters.provisioning.cattle.io <cluster> -n fleet-default --type merge -p '{
  "spec": {"rkeConfig": {"registries": {
    "mirrors": {"*": {"endpoint": ["http://192.168.122.156:30000"]}},
    "configs": {"192.168.122.156:30000": {"authSecretName": "registryconfig-auth-7xjcs"}}
  }}}
}'

问题 3：Harbor 中缺少 v1.35.7 的 RKE2 安装镜像 ​

现象（协议修复后）：

GET http://192.168.122.156:30000/v2/rancher/system-agent-installer-rke2/manifests/v1.35.7-rke2r1:
NOT_FOUND: artifact rancher/system-agent-installer-rke2:v1.35.7-rke2r1 not found

根因：下游集群选择了 K8s 版本 v1.35.7+rke2r1，而 Harbor（192.168.122.156:30000）中 rancher/system-agent-installer-rke2 仅有：

v1.35.4-rke2r1
v1.35.6-rke2r1

本环境的离线安装包也只有 v1.35.6（/u02/repo/rke2/1.35.6）。

解决方案（二选一）：

  1. 推荐：创建集群时选择 v1.35.6+rke2r1，与 Harbor 镜像及离线包保持一致；
  2. 将 v1.35.7 全套镜像（system-agent-installer-rke2、rke2-runtime 等）推送至 Harbor 后再使用 v1.35.7。

附：固定 RKE2 版本，防止新集群默认选到 v1.35.7 ​

原因：Rancher 按全局设置 rke-metadata-config（默认每 1440 分钟）从 https://releases.rancher.com/kontainer-driver-metadata/release-v2.14/data.json 周期刷新 K8s 版本元数据。RKE2 官方发布 v1.35.7+rke2r1 后被同步进版本下拉列表，而创建集群时 UI 默认选中列表中最新版本 → 与 Harbor 中仅有 v1.35.6 镜像不匹配。

解决（kubectl，等效 UI 路径：☰ → Global Settings）：

bash
# 1. 禁用元数据周期刷新（refresh-interval-minutes 设为 0），防止后续新版本再进来
kubectl patch settings.management.cattle.io rke-metadata-config --type merge -p '{
  "value": "{\"refresh-interval-minutes\":\"0\",\"url\":\"https://releases.rancher.com/kontainer-driver-metadata/release-v2.14/data.json\"}"
}'

# 2. 新集群默认版本固定为 v1.35.6
kubectl patch settings.management.cattle.io rke2-default-version --type merge \
  -p '{"value":"v1.35.6+rke2r1"}'

# 3. 让刷新间隔变更立即生效（也可在 Cluster Management → Drivers 手动 Refresh Kubernetes Metadata）
kubectl rollout restart deploy/rancher -n cattle-system

注意：

  1. 禁用刷新只阻止以后的新版本进来，已在下拉列表中的 v1.35.7 不会消失。创建集群时仍需手动选择 v1.35.6+rke2r1（或靠 rke2-default-version 默认值兜底）。
  2. 如需彻底从下拉列表移除 v1.35.7（离线环境推荐做法）：
    • 下载 data.json，删除 rke2.releases 中不需要的版本（仅保留 v1.35.6）；
    • 挂到内网 HTTP 服务；
    • 将 rke-metadata-config 的 url 指向本地副本；
    • 手动 Refresh Kubernetes Metadata。
  3. 以上只影响新建集群的默认/可选版本，已存在的集群版本不受影响。

排查命令速查 ​

bash
# 节点侧：查看 system-agent 日志（plan 下发与执行情况）
ssh rocky@<node> "sudo journalctl -u rancher-system-agent --no-pager -n 50"

# 节点侧：查看 rke2-server 日志
ssh rocky@<node> "sudo journalctl -u rke2-server --no-pager -n 50"

# 节点侧：查看 agent 连接信息（连的哪个 Rancher、watch 哪个 secret）
sudo cat /var/lib/rancher/agent/rancher2_connection_info.json

# 管理端：集群 / machine / plan 状态
kubectl get clusters.provisioning.cattle.io -A
kubectl get machines.cluster.x-k8s.io -n fleet-default
kubectl get secret <machine>-machine-plan -n fleet-default   # DATA=0 说明 plan 未生成

# 管理端：Rancher planner 日志（定位 plan 不生成的原因）
kubectl logs -n cattle-system deploy/rancher --tail=400 | grep -iE 'error|planner'

# 管理端：rkecontrolplane 状态（含具体等待原因 message）
kubectl get rkecontrolplane <cluster> -n fleet-default -o jsonpath='{.status.conditions}'

# 验证私有仓库协议与镜像是否存在
curl -s http://<registry>/v2/<repo>/tags/list -u 'user:xxx'

经验总结 ​

  1. machine-plan secret DATA=0 → 看 Rancher planner 日志，多为初始化保护（etcd 平面替换）或版本不支持；
  2. http: server gave HTTP response to HTTPS client → registry mirror endpoint 缺 http:// 前缀；
  3. NOT_FOUND artifact → Harbor 镜像版本与集群 K8s 版本不匹配，注意 v1.35.7+rke2r1 对应镜像 tag 是 v1.35.7-rke2r1（+ 变 -）；
  4. 离线/私有仓库环境，集群 K8s 版本必须与仓库中已有镜像版本对齐；
  5. 版本下拉列表会随 rke-metadata-config 周期刷新出现新版本 → 离线环境应 refresh-interval-minutes=0 禁用刷新，并用 rke2-default-version 固定新集群默认版本。