#故障排查

使用按症状优先的故障排查方式。本页涵盖 Alauda Build of NPU Operator 及其 ACP 集成点。关于硬件健康状态、BIOS、firmware 和厂商 driver 的深度调优，请参阅 Huawei 或 openFuyao 文档。

本页中的命令使用默认 Operator 命名空间 npu-operator。如果 Operator 安装在其他命名空间中，请将 npu-operator 替换为该命名空间；使用 Operator 命名空间的 operand 会遵循安装命名空间。

#Driver pod 是 ImagePullBackOff

检查调度到受影响节点的 driver pod：

kubectl -n npu-operator get pods -l app.kubernetes.io/component=npu-driver -o wide
kubectl -n npu-operator describe pod <driver-pod-name>

常见原因：

• 未镜像来自 HDK 版本、芯片和完整 kernel release 组合派生出的 tag；
• 目标业务集群中的 ImageWhiteList 未包含完整镜像引用；
• 缺少 registry 凭证或凭证已过期。

请参考安装重新准备镜像。如果在镜像和白名单修复后，pod 仍然保留旧的拉取失败状态，请在维护窗口内删除失败的 driver pod，以便 DaemonSet 重新创建它。

#节点未显示 NPU 可分配资源

检查 driver pod、device plugin、节点标签以及可分配资源：

kubectl -n npu-operator get pods -o wide | grep -E "npu-driver|runtime|hccn"
kubectl -n kube-system get pods -l name=ascend-device-plugin-ds -o wide
kubectl get node ${nodeName} --show-labels
kubectl get node ${nodeName} -o jsonpath='{.status.allocatable}'

常见原因：

• 共享 NFD 或 NPU Feature Discovery 未就绪，或者缺少所需的节点标签；
• driver pod 未就绪；
• device plugin 组件已禁用；
• runtime driver 树在 /run/ascend/.ready/driver-ready 处尚未就绪；
• 在 Ascend 910 节点上，缺少 HCCN device IP 配置，或该配置未完成协调；
• 在升级或恢复期间，芯片被报告为不健康。

对于 Ascend 910 节点，请检查 Device Plugin 日志。如果 spec.hccnBootstrap.enabled=true，还要检查 HCCN Bootstrap agents：

kubectl -n kube-system logs ds/ascend-device-plugin --tail=100
kubectl -n npu-operator get ds hccn-bootstrap
kubectl -n npu-operator logs ds/hccn-bootstrap -c reporter --tail=100
kubectl -n npu-operator logs ds/hccn-bootstrap -c executor --tail=100

如果 device plugin 报告 HCCN 或 device IP 错误，请先确认目标节点已具备所需的 HCCN 配置，再将 device plugin 视为根因。

#因缺少放置标签导致 NPU 组件 Pod 处于 Pending

某些托管组件会选择带有 masterselector=dls-master-node 或 workerselector=dls-worker-node 的节点。NPU Feature Discovery 通常会自动维护这些标签。

检查发现组件是否在受影响节点上运行，以及预期标签是否存在：

kubectl -n npu-operator get daemonset npu-feature-discovery
kubectl -n npu-operator get pods -l app=npu-feature-discovery -o wide
kubectl get nodes \
  -L node-role.kubernetes.io/control-plane,masterselector,workerselector,openfuyao.com/npu.present
kubectl describe pod <pending-component-pod>

对于控制平面节点，自动 master 标记需要标准的 node-role.kubernetes.io/control-plane 标签，以及一个可以在该节点上运行的 npu-feature-discovery Pod。在修改标签之前，请先检查节点 taint 和 DaemonSet 调度情况。如果节点只有旧的 node-role.kubernetes.io/master 角色标签，请添加标准的 control-plane 角色标签；否则，运行中的发现 Pod 会将其视为 worker，并移除手动添加的 masterselector。

如果发现组件无法覆盖目标节点，请将匹配的放置标签作为兜底方案手动应用：

kubectl label node <control-plane-node-id> masterselector=dls-master-node --overwrite
kubectl label node <npu-worker-node-id> workerselector=dls-worker-node --overwrite

不要使用两个标签去选择不相关的节点。等发现组件之后在该节点上运行时，它会根据检测到的节点角色协调这些值。

#Pod 处于 Pending

查看 Pod 详情：

kubectl describe pod <pod-name>

检查请求的资源键是否与节点匹配：

• huawei.com/Ascend910
• huawei.com/Ascend310P
• 已安装 device plugin 报告的其他 huawei.com/Ascend* 键

同时检查所有 NPU 资源是否已经被分配完：

kubectl describe node ${nodeName} | sed -n '/Allocated resources:/,/Events:/p'

如果 ACP 项目或命名空间配额阻止调度，请在 ACP 中调整配额。关于 quota 字段可见性，请参见 加速器资源配额。

#Pod 运行正常但无法看到 NPU 设备

检查已接纳的 Pod、RuntimeClass、Device Plugin 以及运行时集成组件：

kubectl get pod <pod-name> -o jsonpath='{.spec.runtimeClassName}{"\n"}'
kubectl get runtimeclass ascend
kubectl -n npu-operator get pods -o wide | grep -E "runtime|toolkit"
kubectl -n kube-system logs ds/ascend-device-plugin --tail=100
kubectl -n npu-operator logs ds/ascend-runtime-containerd -c prepare-config --tail=100
kubectl -n npu-operator logs ds/ascend-runtime-containerd -c inject --tail=100

已接纳的 Pod 应使用 ascend RuntimeClass。运行时集成 DaemonSet 会分发 ascend-docker-runtime 负载，并使用 npu-container-toolkit 维护 ascend containerd handler 配置。在预编译 Driver 模式下，主机侧 runtime Driver 树会暂存到 /run/ascend/driver；在预安装 Driver 和普通 OS 托管安装模式下，runtime 使用 /usr/local/Ascend/driver。

工作负载侧的预期检查项：

kubectl logs <pod-name> --tail=100
kubectl exec <pod-name> -- ls -la /dev/davinci* /dev/davinci_manager
kubectl exec <pod-name> -- /usr/local/bin/npu-smi info

如果需要从调试容器内部检查挂载，请查看工作负载侧路径，例如 /usr/local/bin/npu-smi 和 /usr/local/Ascend/...。不要将这些工作负载路径与主机侧位于 /run/ascend/driver 下的预编译 runtime 树混淆。

在启用默认 admission webhook 的情况下，提交的工作负载清单不需要设置 runtimeClassName；已接纳的 Pod 应包含 runtimeClassName: ascend。如果该字段缺失，请检查 webhook 是否已启用并就绪，以及 Pod 是否请求了可识别的 huawei.com/Ascend* 资源。如果 webhook 已禁用，请显式设置 runtimeClassName: ascend。

如果已接纳的 Pod 使用了预期的 RuntimeClass，但仍然没有获得设备，请检查 Device Plugin 的分配结果以及 ascend containerd handler。仅应按照当前产品版本提供的运行时集成操作步骤重启组件。

#指标缺失

检查 exporter 和 ServiceMonitor：

kubectl -n npu-exporter get pods -l app=npu-exporter
kubectl -n monitoring get servicemonitor npu-exporter-servicemonitor

如果两者都存在，请继续参考 ACP 监控文档，检查 dashboard 导入、Prometheus 发现以及 scrape 错误。

#手动 Driver 升级未启动

当 spec.driver.upgradePolicy.autoUpgrade=false 时，v26.6.0 不会在手动批准之前创建重启事务。请仅在维护窗口内批准目标节点：

kubectl annotate node ${nodeName} npu.openfuyao.com/approve-reboot=true --overwrite

Operator 处理完批准后，检查重启事务和 Rebooter Pod：

kubectl get node ${nodeName} \
  -o custom-columns=NAME:.metadata.name,REBOOT-REQUIRED:.metadata.labels.npu\.openfuyao\.com/reboot-required,REBOOT-REASON:.metadata.annotations.npu\.openfuyao\.com/reboot-reason,TARGET-DRIVER-ID:.metadata.annotations.npu\.openfuyao\.com/target-driver-id
kubectl get nodes -l npu.openfuyao.com/reboot-required=true
kubectl -n npu-operator get pods | grep npu-rebooter
kubectl -n npu-operator logs ds/npu-rebooter --tail=100

随后，目标节点应具有 npu.openfuyao.com/reboot-required=true。如果该标签未出现，请检查 NPU Operator controller 日志，并确认该节点位于当前 Driver 目标集合中。不要批量注解所有 NPU 节点，因为未使用的原始批准可能仍保留在节点上，并在后续事务中被批准。