故障排查
请按症状优先进行故障排查。本页面涵盖 Alauda Build of NPU Operator 及其 ACP 集成点。对于硬件健康状况、BIOS、固件和厂商驱动的深度调优,请参阅 Huawei 或 openFuyao 文档。
本页面中的命令使用默认的 Operator 命名空间 npu-operator。如果 Operator 安装在其他命名空间中,请将 npu-operator 替换为该命名空间;使用 Operator 命名空间的操作对象遵循安装时使用的命名空间。
目录
Driver Pod 处于 ImagePullBackOff 状态Driver 模式更改被拒绝节点未显示 NPU 可分配资源NPU 组件 Pod 因缺少放置标签而处于 Pending 状态Pod 处于 Pending 状态Pod 运行但无法查看 NPU 设备Pod 在接纳后没有 RuntimeClassRuntimeClass 存在,但 containerd 处理程序缺失缺少指标手动 Driver 升级未启动Driver Pod 处于 ImagePullBackOff 状态
检查调度到受影响节点上的 Driver Pod:
常见原因:
- 未镜像根据 HDK 版本、芯片和完整内核版本派生出的标签;
- 目标业务集群中的
ImageWhiteList未包含完整的镜像引用; - registry 凭据缺失或已过期。
请按照准备 Driver 镜像中的说明重新准备镜像。如果修复镜像和白名单后,Pod 仍保留旧的拉取失败状态,请在维护时段删除失败的 Driver Pod,以便 DaemonSet 重新创建该 Pod。
Driver 模式更改被拒绝
如果 ascend-runtime-containerd 记录了类似
refusing to change Ascend driver install mode from host to containerized
的错误,则表示节点持久化的运行时状态与请求的 NPU Operator 模式不一致。
这是用于防止混用 Host 和容器化驱动目录树的有意安全保护机制,并非文件权限错误。
此节点级保护机制独立于 Operator 的配置保护机制:
创建策略后,NPUClusterPolicy.spec.driver.installMode 不可变。请勿仅通过编辑模式字段来切换现有的
NPUOperatorCtl;Operator 会报告 spec.driver.installMode cannot be changed
并保留原先应用的模式。请使用文档规定的卸载并重新创建工作流,先以新模式创建策略。
将节点状态与 DaemonSet 环境进行比较:
状态文件包含类似以下内容的值:
仅可在已批准的卸载/重新创建迁移过程中删除状态文件,并且必须同时满足以下所有条件:
- 管理员已明确批准模式迁移;
- 节点上的 NPU 工作负载已停止或已排空;
- 新的驱动根目录、运行时配置和所需的驱动目录树均已准备就绪。
新安装已呈现所选模式后,重新创建运行时 Pod,使其能够为该模式建立节点状态:
在恢复工作负载之前,验证新状态和 Pod 就绪情况:
删除文件不会安装、卸载或迁移驱动。如果运行时仍针对
/mnt/tmp/runtime/ascend-docker-runtime 报告 cp: cannot overwrite non-directory,
请将其视为独立的临时负载目录或镜像内容问题,并继续检查运行时 Pod
日志。
节点未显示 NPU 可分配资源
检查驱动 Pod、设备插件、节点标签和可分配资源:
常见原因:
- 共享的 NFD 或 NPU Feature Discovery 尚未就绪,或缺少必需的节点标签;
- 驱动 Pod 尚未就绪;
- 设备插件组件已禁用;
/run/ascend/.ready/driver-ready处的运行时驱动目录树尚未就绪;- 在 Ascend 910 节点上,缺少 HCCN 设备 IP 配置,或该配置尚未完成调谐;
- 芯片在升级或恢复期间被报告为运行状况不佳。
对于 Ascend 910 节点,请检查 Device Plugin 日志。如果出现 spec.hccnBootstrap.enabled=true,还要检查 HCCN Bootstrap agent:
如果设备插件报告 HCCN 或设备 IP 错误,请先确认目标节点具有所需的 HCCN 配置,再将设备插件视为根因。
NPU 组件 Pod 因缺少放置标签而处于 Pending 状态
Operator 管理器和某些可选组件使用 masterselector=dls-master-node 或 workerselector=dls-worker-node 选择节点。核心 Driver、运行时、Device Plugin 和 Exporter 则使用已发现的 openfuyao.com/npu.present 标签。NPU Feature Discovery 通常会自动维护所有这些发现标签和角色标签。
检查受影响节点上是否运行了发现组件,以及预期标签是否存在:
对于控制平面节点,自动添加主节点标签需要标准的 node-role.kubernetes.io/control-plane 标签,以及一个能够在该节点上运行的 npu-feature-discovery Pod。在修改标签之前,请检查节点污点和 DaemonSet 调度情况。如果节点仅具有旧版 node-role.kubernetes.io/master 角色标签,请添加标准控制平面角色标签;否则,正在运行的发现 Pod 会将其视为工作节点,并移除手动添加的 masterselector。
如果发现组件无法覆盖预期节点,而使用角色选择器的组件仍处于 Pending 状态,请应用匹配的放置标签作为临时回退方案:
不要同时使用这两个标签来选择互不相关的节点。发现组件稍后在该节点上运行时,会将这些值调谐为检测到的节点角色。
Pod 处于 Pending 状态
描述 Pod:
检查请求的资源键是否与节点匹配:
huawei.com/Ascend910huawei.com/Ascend310P- 已安装 Device Plugin 报告的另一个
huawei.com/Ascend*键
同时检查所有 NPU 资源是否已分配:
如果 ACP 项目或命名空间配额阻止了调度,请在 ACP 中调整配额。有关配额字段的可见性,请参阅 Accelerator Resource Quota。
Pod 运行但无法查看 NPU 设备
检查已接纳的 Pod、RuntimeClass、Device Plugin 和运行时集成组件:
已接纳的 Pod 应使用 ascend RuntimeClass。运行时集成 DaemonSet 会暂存 ascend-docker-runtime 负载,并使用 npu-container-toolkit 维护 ascend containerd 处理程序配置。在场景 2.2 中,主机侧运行时 Driver 树会暂存于 /run/ascend/driver 下;在场景 1 和 2.1 中,运行时使用 /usr/local/Ascend/driver 下的 Host Driver。
预期的工作负载侧检查:
如果需要从调试容器内部检查挂载,请检查 /usr/local/bin/npu-smi 和 /usr/local/Ascend/... 等工作负载侧路径。不要将这些工作负载路径与 /run/ascend/driver 下主机侧的预编译运行时树混淆。
启用默认准入 webhook 后,提交的工作负载清单无需设置 runtimeClassName;已接纳的 Pod 应包含 runtimeClassName: ascend。如果缺少该字段,请检查 webhook 是否已启用且就绪,以及 Pod 是否请求了已识别的 huawei.com/Ascend* 资源。如果 webhook 已禁用,请显式设置 runtimeClassName: ascend。
如果已接纳的 Pod 使用了预期的 RuntimeClass,但仍未获得设备,请检查 Device Plugin 分配结果和 ascend containerd 处理程序。仅按照当前产品版本随附的运行时集成操作步骤重启组件。
Pod 在接纳后没有 RuntimeClass
Operator webhook 使用 failurePolicy: Ignore。如果 webhook 不可用,API server 可能会接纳 Pod,但不会添加 runtimeClassName。这并不能证明运行时注入正常工作。检查 webhook 和已接纳的 Pod:
对于请求 Ascend 资源的工作负载,请在修复 webhook 期间显式设置 RuntimeClass:
使用一个注入负责方。如果 HAMi 或其他准入组件注入 RuntimeClass,请在另一个组件中禁用重复的注入器。
RuntimeClass 存在,但 containerd 处理程序缺失
ascend RuntimeClass 和 containerd 处理程序是相互独立的对象。主机升级或替换 containerd 配置可能会保留 RuntimeClass,同时移除其引用的处理程序。在受影响的节点上检查这两个值:
处理程序名称必须与 RuntimeClass 处理程序匹配,通常为 ascend。恢复节点的 containerd 配置后,重启该节点上的运行时集成 Pod,并等待 DaemonSet 就绪。然后重新创建一个小型测试 Pod,并验证其已接纳的 RuntimeClass 和设备文件。在运行时集成 DaemonSet 管理 containerd 配置期间,不要手动编辑该配置。
缺少指标
检查 exporter 和 ServiceMonitor:
如果两者都存在,请继续查阅 ACP 监控文档,检查监控面板导入、Prometheus 发现和抓取错误。
手动 Driver 升级未启动
使用 spec.driver.upgradePolicy.autoUpgrade=false 时,v26.6.0 不会在手动批准前创建重启事务。在维护窗口期间仅批准目标节点:
Operator 使用批准后,检查重启事务和 Rebooter Pod:
随后,目标节点应具有 npu.openfuyao.com/reboot-required=true。如果未出现该标签,请检查 NPU Operator controller 日志,并确认该节点位于当前 Driver 目标集内。不要为所有 NPU 节点批量添加 annotation,因为未使用的原始批准可能会留在某个节点上,并批准后续事务。