幽灵节点导致Rancher状态卡死Updating
问题背景
本地测试环境通过 Rancher 部署并管理本地 k3s 集群
Rancher 本身运行正常，可添加节点通过 UI 和 local 集群的 shell 操作 Kubernetes
问题现象
K8s 集群custom-2d74d4c9a104节点状态一直显示：Waiting for agent to check in and apply initial plan
集群轮换证书时会一直卡在此节点后阻碍其它节点的操作（不仅仅限于证书轮换）
configuring etcd node(s) custom-898d97f03763: waiting for plan to be applied
排查步骤
1、因集群中Machine名称无法与K8s节点名称对应，需先对应是哪一个节点出了问题
-
可使用排除法，因为正常的节点会显示node名称
-
通过rancher2_connection_info.json文件查看 secretName名称，取出名称后做一一对应
cat /var/lib/rancher/agent/rancher2_connection_info.json { ...... "namespace": "fleet-default", "secretName": "custom-f489526f114a-machine-plan" }
通过以上方案排查出异常节点为 dev-k8s-node01
2、确定异常节点后，查看 node01 的 rancher2_connection_info.json 文件，可以看到node01的 custom-id 在 rancher 中不存在，而 rancher 中的 custom-id 在所有节点中均不存在
3、查看 node01 服务器上 rancher-system-agent 服务状态，能看到服务一直启动失败并一直试图自动重启，查看服务相关日志，可以看到服务启动后尝试连接集群，但是因为证书验证失败无法加入
[root@dev-k8s-node01 ~]# journalctl -xefu rancher-system-agent
1月 15 16:04:02 dev-k8s-node01 systemd[1]: Started Rancher System Agent.
-- Subject: Unit rancher-system-agent.service has finished start-up
-- Defined-By: systemd
-- Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel
--
-- Unit rancher-system-agent.service has finished starting up.
--
-- The start-up result is done.
1月 15 16:04:02 dev-k8s-node01 rancher-system-agent[6042]: time="2026-01-15T16:04:02+08:00" level=info msg="Rancher System Agent version v0.3.3 (9e827a5) is starting"
1月 15 16:04:02 dev-k8s-node01 rancher-system-agent[6042]: time="2026-01-15T16:04:02+08:00" level=info msg="Using directory /var/lib/rancher/agent/work for work"
1月 15 16:04:02 dev-k8s-node01 rancher-system-agent[6042]: time="2026-01-15T16:04:02+08:00" level=info msg="Starting remote watch of plans"
1月 15 16:04:03 dev-k8s-node01 rancher-system-agent[6042]: time="2026-01-15T16:04:03+08:00" level=fatal msg="error while connecting to Kubernetes cluster: the server has asked for the client to provide credentials"
1月 15 16:04:03 dev-k8s-node01 systemd[1]: rancher-system-agent.service: main process exited, code=exited, status=1/FAILURE
1月 15 16:04:03 dev-k8s-node01 systemd[1]: Unit rancher-system-agent.service entered failed state.
1月 15 16:04:03 dev-k8s-node01 systemd[1]: rancher-system-agent.service failed.
1月 15 16:04:08 dev-k8s-node01 systemd[1]: rancher-system-agent.service holdoff time over, scheduling restart.
1月 15 16:04:08 dev-k8s-node01 systemd[1]: Stopped Rancher System Agent.
-- Subject: Unit rancher-system-agent.service has finished shutting down
-- Defined-By: systemd
-- Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel
--
-- Unit rancher-system-agent.service has finished shutting down.
解决步骤
1、通过 Rancher 控制台的 local 集群打开 kubectl shell 控制台，在控制台中执行强制删除命令，命令执行完成后返回 force delete 但是资源仍然存在
> kubectl -n fleet-default delete machine custom-2d74d4c9a104 --force
2、通过 Rancher 控制台的 local 集群打开 kubectl shell 控制台，删除 custom 节点对应的 finalizers 条目，执行完成后 custom 节点被自动清理
> kubectl edit machine custom-2d74d4c9a104 -n fleet-default
# 找到 finalizers: 部分，删除其下的所有条目，保存退出
3、custom 节点清理后，可以看到集群开始轮换证书，更新配置等操作
configuring worker node(s) custom-3524fa7f0d71,custom-3b154219b4e1,custom-40e383a8d1da and 10 more
4、在 node01 服务器重新执行 Registration Command 命令加入集群
原因分析
Finalizers
Finalizer 是带有命名空间的键，告诉 Kubernetes 等到特定的条件被满足后， 再完全删除被标记为删除的资源。 Finalizer 提醒控制器清理被删除的对象拥有的资源。
当你告诉 Kubernetes 删除一个指定了 Finalizer 的对象时， Kubernetes API 通过填充 .metadata.deletionTimestamp 来标记要删除的对象， 并返回 202 状态码（HTTP "已接受"）使其进入只读状态。 此时控制平面或其他组件会采取 Finalizer 所定义的行动， 而目标对象仍然处于终止中（Terminating）的状态。 这些行动完成后，控制器会删除目标对象相关的 Finalizer。 当 metadata.finalizers 字段为空时，Kubernetes 认为删除已完成并删除对象。
在 Kubernetes 架构中，Finalizers 是一种资源清理保护机制。确保在删除一个对象前，与其关联的外部资源（如云平台的负载均衡器、磁盘卷或 Rancher 的管理 Agent）能够被优雅地清理。当 finalizers 列表为空时，K8s 才会真正从 Etcd 中擦除该数据。
为何产生“幽灵节点”？
触发点：由于 node01 的 Agent 凭证失效，导致 node01 无法向 Rancher Server 上报状态。
状态异常：Rancher 认为该节点失联，尝试重新同步或用户尝试删除该节点以重建。
清理阻塞：machine 资源上存在的 Finalizers无法确认清除。Rancher 的控制器在尝试清理该节点时，需要通过 Agent 下发指令，但此时 Agent 连接已断开。
幽灵化：清理逻辑由于通信失败而卡死，Finalizers 永远无法被移除，导致该节点资源在 UI 中一直存在，但又无法与实际运行的 k3s 节点建立有效连接。
