Rancher 里加 Windows worker 节点最让人头疼的就是卡在 “Waiting for Node Ref” 这步。我接触过不少集群Windows 节点本来就有各种兼容性包袱再碰上这种状态基本等于节点白加了kubelet 起不来不代表注册成功卡住之后 UI 上一直转圈集群 CPU 也一直在空转。最近又有一个环境踩了同样的坑报错里还多了一句 “no VM found error”排查了一下午把整个过程记下来给后面遇到的人一个参考。先说结论这个状态本质上是 Rancher 的 node controller 没能把“集群里的 Node 对象”和“Rancher 自己管理的机器记录Node Ref”绑定起来。而 “no VM found” 大概率是基础设施层的信息丢了或者节点驱动创建实例时就没把 VM 元数据写全。下面拆开讲。1. 先搞清楚 “Waiting for Node Ref” 和 “no VM found” 到底在说什么1.1 Rancher 的节点生命周期Node、Machine、Node Ref 三者的关系打开 Rancher UI 看节点列表时你看到的每一行其实对应着两层数据一层是 Kubernetes 集群里的node对象由 kubelet 启动后注册到 kube-apiserver另一层是 Rancher 自己维护的cluster.provisioning.cattle.io或management.cattle.io下的 machine 记录。Rancher 靠Node Ref把这两者关联起来。当你通过 Rancher 添加节点不管是自定义节点还是通过 vSphere 等节点驱动控制平面会先创建一个 machine 对象里面写好 hostname、角色、标签等期望信息。然后 kubelet 启动、注册 Node 对象后Rancher 的 node controller 会把 Node 对象的名字通常是主机名和 machine 对象里的spec.nodeName做匹配。匹配成功后UI 上这个节点才会从 “Waiting for Node Ref” 变成 Ready。这个机制说白了就相当于你要把一个人加入通讯录得先有他的登记表然后他本人来公司报到报到时用自己的姓名和登记表对上号。登记表写了张三来的人也叫张三系统才能把他标记为“在职”。1.2 “no VM found” 是从哪儿冒出来的这个错误并不是每台卡住的 Windows 节点都会出现它更容易出现在用 vSphere、AWS、Azure 这类节点驱动创建节点的场景里。Rancher 通过节点驱动创建 Windows worker 时会调用对应的云平台 API 去创建虚拟机。如果 VM 已经创建成功但后续被外部删除、改名为别的或者 vCenter 里的文件夹/资源池路径变了Rancher 的 machine controller 在同步状态时去查 VM 信息查到不到就会抛no VM found。这个错误一旦出现节点状态就更不可能推进到 Node Ref 匹配成功因为 Rancher 认为这台机器已经不存在了。另一种情况是 Rancher 使用自定义命令注册 Windows 节点但注册脚本中的CATTLE_NODE_NAME或主机名参数和 Rancher 里 hostname 的预期值不一致也会在日志里出现类似找不到对应机器元数据的提示。虽然严格说不是真的找不到 VM但表达出来的问题本质一样机器身份对不上。2. 故障定位不要急着删节点先抓证据遇到这种状态很多人第一反应是把节点从 Rancher 里删掉重来。先忍住。硬删有风险比如 node 对象变成 terminating 一直清不掉或者 Rancher 里记录残留导致重新添加时依然报错。正确的做法是先花十几分钟把现场信息抓全。2.1 在 Rancher 侧确认当前状态先到 Rancher UI 的集群节点页面看节点列表是否显示Node 名称是空的还是已经显示主机名状态列是不是一直显示 Waiting“查看详情”三个点里的 View YAML里对象的状态字段是什么更可靠的方式是直接用 kubectl 看 Rancher 侧的 CRD假设你通过 kubeconfig 能访问到 local 集群也叫 Rancher Server 所在的集群可以执行kubectl get machine -n fleet-default -o wide kubectl get cluster.provisioning.cattle.io 集群名 -n fleet-default -o yaml如果 machine 列表里看不到 Windows 节点对应的那条记录说明机器对象压根没创建成功这是第一类根因如果 machine 有记录但状态里有报错信息比如no VM found这是第二类根因如果 machine 记录正常但集群里的 node 对象一直没出现则是 kubelet 注册流程的问题属于第三类根因。2.2 抓 Rancher 的 controller 日志Rancher 的 node controller 负责同步 machine 和 node 的状态它的日志信息量最大。如果 Rancher 是单容器部署可以这样看docker logs rancher-server-container --since 1h | grep -i node-ref\|waiting\|no vm found\|machine | tail -100如果是 Rancher 高可用部署在另一个集群里就用下面的方式找。这里是嵌套集群得先确认 Rancher 的 pod 名字再进去抓日志kubectl get pods -n cattle-system | grep rancher kubectl logs -n cattle-system rancher-pod --since1h | grep -iE machine|cattle-node|noderef|nofinitee|no vm found | tail -300注意看日志里有没有这类关键词Failed to find VMWaiting for node Reffailed to create node refmachine ... not found如果日志里出现 “VM not found”基本可以确定是基础设施层的问题往下跳到第四章的场景一去处理。2.3 检查 Windows 节点上的 kubelet 和容器运行时如果 Rancher 侧日志看不出明显错误就得登录到 Windows worker 节点上看 kubelet 有没有正常启动。在 Windows 上Rancher 使用 RKE2 或 RKE1 的 Windows 形态rancher-agent containerd/docker来拉起集群组件。检查服务状态Get-Service kubelet Get-Service rancher-agent Get-Process -Name kubelet -ErrorAction SilentlyContinue如果 kubelet 服务存在但没有运行先看 Windows 事件日志Get-WinEvent -LogName Application -MaxEvents 100 | Where-Object { $_.Message -match kubelet|containerd|runtime } | Format-List再看 rancher-agent 的容器日志。如果用的是 containerd可以执行crictl ps -a crictl logs agent-container-id如果用的是 Docker EE/CE则用docker ps -a docker logs agent-container-id这里特别提醒Windows 节点上 rancher-agent 容器通常需要和 kubelet 共用同一个容器运行时而且启动顺序有讲究——先启动 container runtime再启动 kubelet然后 rancher-agent 才能正常和 Rancher server 通信。你要是看到 kubelet 进程反复崩溃重启多半是 runtime 没起好或者没有以正确的参数调用。3. 核心原因与修复方案分场景处理场景一节点驱动创建VM 不存在或漂移报 no VM found这个场景多见于 vSphere 等虚拟化环境。Rancher 通过 vSphere 驱动创建 Windows worker 后虚拟机在 vCenter 里被改名了、被误删了或者从某个 Cluster 迁移到了别的 Cluster导致 Rancher 按照dataCenter、vmName、vmMoRef这些信息去查时返回空。第一步登录 vSphere 客户端确认 VM 是否真实存在。不要只看名字要看路径。Rancher 在创建 VM 时记录的是folder和resourcePool路径你改过名字或者移动过 VM这些信息就会对不上。第二步如果 VM 还在但路径变了最简单的办法是在 Rancher 里把这条 machine 记录删掉然后在 vSphere 里把 VM 名改回原名或者让它重新符合 Rancher 的命名规则再通过节点驱动重新添加。听起来有点暴力但这是最干净的方案。第三步如果你希望保留这台 VM不想重建也可以在 vCenter 里把 VM 改回和 Rancher machine 记录一致的名称和路径然后手动触发一次 Rancher 的 machine 同步kubectl annotate machine machine-name -n fleet-default provisioning.cattle.io/reconciletrue注意这种方式能不能恢复取决于报错阶段如果只是查询 VM 失败这样能拉回来如果 Rancher 已经把 machine 置为 failedannotate 不一定有效还是要删除重建。场景二自定义命令注册的 Windows worker卡在注册流程中断很多 Windows 节点是用“编辑集群 → 节点 → Windows”里给出的注册命令添加的。复制命令后在 Windows Server 上以管理员身份运行 PowerShell 执行。如果中间网络断过、agent 容器启动失败或者执行命令时没有以管理员运行就容易卡在 Waiting for Node Ref。先确认 rancher-agent Windows 容器是否拉取成功这一步极其重要。Windows 节点拉取 rancher-agent 镜像体积挺大通常几个 G网络不好可能一直失败。上面已经给了查看容器日志的命令。如果发现 agent 容器日志里报连不上 Rancher server 的地址先检查防火墙是否放行了 443 端口以及 Rancher server 的 URL 是否用的是内网可达地址。确认网络没问题后重新执行注册命令。执行前先清理可能残留的 agent 容器crictl rm -f agent-container-id如果是 docker runtimedocker rm -f agent-container-id然后重新用 PowerShell 执行注册脚本。这里有个细节注册命令里包含了 Windows 特定的参数比如--windows、--worker等如果复制时遗漏了这些参数agent 可能按 Linux 逻辑走导致组件不匹配节点自然注册不上。所以重新执行前最好逐项核对命令参数。场景三Rancher 数据不一致machine 记录残留这种场景没有明显的 infra 层错误但节点就是一直 Waiting。多发生在离线环境、多重启 Rancher、或者 Rancher 版本升级过程中。Rancher 数据库里的 cluster-machine 关联记录可能损坏或不同步。处理思路是把 Rancher 侧预期要绑定这台节点的 machine 对象删掉让 Rancher 重建同时保留 Windows 节点上的 kubelet 和 agent 继续运行。在 Rancher 所在的本地集群执行kubectl get machines -n fleet-default | grep windows-node-hostname kubectl delete machine machine-name -n fleet-default --waitfalse删除后观察 Rancher 是否自动重建 machine。如果自动重建了通常几分钟内节点状态就会更新如果没有重建再到集群的 provisioning 文件里确认节点设置是否还保留着。这类操作我实验过多次在大多数场景下删掉“期望状态”里的 machine 对象而不用动集群里已经注册的 node 对象可以让 Rancher 自动找回状态。但如果 node 对象本身也没有注册成功比如 kubelet 一直没起来那上面这步就做无用功得先回到场景二把 kubelet 拉起。4. 补充Windows 节点加入 Rancher 的常规流程与常见误区4.1 正确流程回顾完整跑通一个 Windows worker 节点加入 Rancher 集群差不多是这样的在 Rancher UI 编辑集群在节点角色里勾选 Windows 的 Worker 角色拿到一串注册命令PowerShell 格式。在 Windows Server 2019 或 2022 上以管理员身份打开 PowerShell执行那串命令。命令内部会完成 containerd/docker 环境准备、镜像拉取、rancher-agent 启动。rancher-agent 起来以后会向 Rancher server 注册 machine 信息并拉起 kubelet。kubelet 向集群 kube-apiserver 注册 node 对象成功后Rancher 的节点控制器完成绑定节点状态从 Waiting 变为 Ready。很多问题出在第 2 步和第 3 步衔接的地方agent 容器起来了但 kubelet 没起来或者 kubelet 起来了但 agent 一直报错。这俩进程之间并没有强依赖但如果你想彻底重启就得把它们按顺序都清理掉再重来一遍。4.2 Windows 节点常见坑位清单这里列几个我见过的实操问题不一定每个都会导致 “no VM found”但都会让人在排查时走弯路没加 Windows 专属污点/标签。Rancher 给 Windows worker 会默认打上node.kubernetes.io/oswindows:NoSchedule这类污点。如果注册命令里漏了参数或者手动编辑集群时把污点删了Linux 平台的 Pod 不要被调度到 WindowsWindows POD 又要选择指定运行时互相挤兑之后节点状态就会很奇怪。主机名大小写。Windows 主机名经常是大写或者带数字后缀kubelet 注册时会把主机名转成小写。Rancher 在期望状态machine里写的是你提供的名字可能和实际注册名字大小写不一致导致 Node Ref 一直对不上。遇到这种情况要么在注册命令里显式指定CATTLE_NODE_NAME为小写要么修改 Windows 主机名后重启再注册。内存和 CPU 不满足最低要求。Windows 节点对资源的要求比 Linux 高不少如果 VM 只有 2G 内存、1 核 CPUkubelet 很容易启动失败或反复重启。Rancher UI 上表现就是节点一直 Waiting日志里却是一堆 OOM 或资源不足的信息。容器 runtime 版本不匹配。RKE2 要求 containerd 版本和 kubelet 配套。如果你自己手动装过 docker/containerd再跑 Rancher 注册命令很容易因版本冲突导致 ranche-agent 启动失败。4.3 用注册命令时推荐加的两个参数在 PowerShell 执行注册命令时如果你希望节点名更可控可以加$env:CATTLE_NODE_NAME win-worker-01然后再执行原本的注册命令。这样可以避免因 Windows 主机名默认值引发的匹配问题。如果节点所在网络到 Rancher server 公网地址不通但内网可达你可以在命令前加环境变量指定内网地址$env:CATTLE_SERVER https://rancher.internal:443这么做的前提是 Rancher server 的证书里包含这个内网地址否则 agent 会因证书校验失败而退出。5. 常见问题速查表按症状直接查方案表面现象可能根因优先处理动作节点卡在 Waiting for Node Ref无具体报错node 对象和 machine 对象未关联kubelet 可能没起来先看 kubelet 日志确认进程是否存活再查 Rancher machine 对象状态日志出现no VM foundvSphere/云驱动里 VM 已不存在或路径漂移进 vCenter/云控制台确认 VM改名/移动路径后 annotate 同步或删除重建注册命令执行后agent 容器一段时间后被自动退出Windows 容器镜像拉取失败或 CATTLE_SERVER 指向地址不可达检查crictl logs或docker logs确认网络与镜像仓库连通性节点状态显示 Waiting但控制台里 node 列表已能看到该节点Rancher 的 machine 对象建立失败或 CRD 数据不一致删除对应 machine 对象观察是否自动重建kubelet 进程反复重启runtime 版本不对或资源不足检查 containerd/docker 版本和 Rancher 文档对齐提高 VM 规格加完节点后 Kubernetes 无法调度 Windows Pod节点缺少oswindows污点或 label检查节点标签和污点重新执行注册命令并确认参数完整这个表是我自己后期复盘时整理的不一定覆盖所有异常但能覆盖我遇到过的 90% 的卡顿场景。排查顺序永远是先看基础网络中不通再看 agent 容器日志再看 kubelet最后动 Rancher 里的 CRD。6. 几个必须强调的实操注意事项6.1 不要随便在 Rancher 里点“删除节点”只要节点卡在 Waiting for Node Ref很多人就想把它从节点列表里删掉再重新添加。但如果你删的是 Rancher 里这个被管理的机器记录同时没有先去 Windows 节点上停止 kubelet集群里的 node 对象会变成孤儿节点一直存留在集群中即使机器已经不在 Rancher 管理列表里了。这会导致后续想重新添加节点时新 kubelet 注册的 node 名字和一个旧 node 记录冲突状态持续 NotReady。所以如果你决定走“删除重建”路线请先登录 Windows 节点停止并禁用相关服务Stop-Service kubelet -Force Stop-Service rancher-agent -Force Set-Service kubelet -StartupType Disabled Set-Service rancher-agent -StartupType Disabled然后再到 Rancher UI 里删除节点。这样清理得干净重建时才不会残留 “Node Ref” 匹配问题。6.2 使用 kubeconfig 直接看集群内 node 对象Rancher UI 显示的是管理平面状态容易掩盖真实问题。我建议你随时准备一个能访问目标集群的 kubeconfig。在本地执行kubectl get nodes -o wide如果kubectl get nodes里能看到 Windows 节点但状态是 NotReady那问题在 kubelet 或容器运行时如果节点列表里压根看不到 Windows 节点那问题在注册流程和 Rancher 的 machine 对象无关。这两类问题的处理方向完全不同这个判断可以帮你省掉大量的无效排查时间。6.3 Rancher 版本差异导致的显示不一致Rancher 2.6 和 2.7 之间的节点管理逻辑差别不算大但 2.8 之后对 Windows 的支持做了一些调整。老版本里Waiting for Node Ref相对少见新版本则更严格machine 必须拿到“节点驱动提供的VM信息”才能完成绑定。如果你正在用不支持的 Windows 版本比如 Windows Server 2016 或 Windows 11 客户端Rancher agent 本身可能就有兼容性问题建议直接换成 Windows Server 2022 的 LTSC 版本再试。这个听起来像是废话但确实是我见过最多的隐性误配场景之一。7. 最后分享一点个人体会关于 Windows 节点排障的顺序Windows 节点不像 Linux 节点那样好折腾很多常规命令没有、输出格式也不一样在 Rancher 排错时尤其容易一头雾水。踩过几次坑之后我的经验是先抓日志再动资源先看最近的变更再盲修配置。遇到卡在 Waiting for Node Ref 且带 “no VM found” 的节点我的第一判断往往是基础设施层出了问题——不是 Rancher 不干活而是它查不到这台机器了。这时候与其在 Rancher 页面里反复点击重试不如直接去 vCenter / 云控制台看一眼这台 Windows worker 的虚拟机还在不在。如果 VM 一切正常再回到 Rancher 这边看 machine 状态。如果 machine 状态也是好的那就要怀疑是不是注册命令的问题。这个时候去 Windows 节点上把 rancher-agent 容器日志拉出来看通常能直接看到它尝试连接 Rancher server 的过程以及失败的具体原因。另外Windows 节点重新注册时尽量把 kubelet 和 agent 的服务全部停掉、清理容器再执行注册命令。Rancher 的注册脚本要做的是“从零拉一个新的 worker”你不能骗它说已经有一个 worker 在跑了否则后续资源组比如 Calico/Tigera Operator 的 Windows 版本配置很可能会错乱。如果你只是临时想恢复集群调度能力又不想马上修节点可以先把 Windows 节点的调度禁用掉把工作负载调度到 Linux 节点上。但记得这只适合临时保可用性根本不是修复手段一定要回来处理节点本身。这个 “no VM found” 的报错看起来很唬人很多时候就是因为虚拟化层数据漂移或者创建节点时的信息不对称。你只要按照“基础设施 → 容器运行时 → kubelet → Rancher 机器数据”的顺序逐层排查大多数场景都能在半小时内定位到根因。