故障排查

请按症状优先进行故障排查。本页面涵盖 Alauda Build of NPU Operator 及其 ACP 集成点。对于硬件健康状况、BIOS、固件和厂商驱动的深度调优,请参阅 Huawei 或 openFuyao 文档。

本页面中的命令使用默认的 Operator 命名空间 npu-operator。如果 Operator 安装在其他命名空间中,请将 npu-operator 替换为该命名空间;使用 Operator 命名空间的操作对象遵循安装时使用的命名空间。

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 版本、芯片和完整内核版本派生出的标签;
  • 目标业务集群中的 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 环境进行比较:

# Run on the affected node through the approved node-debug or host access path.
cat /etc/ascend-docker-runtime.d/driver-mode
# Run from a workstation with access to the target workload cluster.
kubectl -n npu-operator get ds ascend-runtime-containerd -o jsonpath='{range .spec.template.spec.initContainers[?(@.name=="prepare-runtime")].env[*]}{.name}={.value}{"\n"}{end}'

状态文件包含类似以下内容的值:

installMode=host
driverRoot=/usr/local/Ascend/driver

仅可在已批准的卸载/重新创建迁移过程中删除状态文件,并且必须同时满足以下所有条件:

  • 管理员已明确批准模式迁移;
  • 节点上的 NPU 工作负载已停止或已排空;
  • 新的驱动根目录、运行时配置和所需的驱动目录树均已准备就绪。

新安装已呈现所选模式后,重新创建运行时 Pod,使其能够为该模式建立节点状态:

# Run on the affected node through the approved node-debug or host access path.
rm -f /etc/ascend-docker-runtime.d/driver-mode
# Run from a workstation with access to the target workload cluster.
kubectl -n npu-operator delete pod -l app.kubernetes.io/name=ascend-runtime-containerd

在恢复工作负载之前,验证新状态和 Pod 就绪情况:

# Run on the affected node through the approved node-debug or host access path.
cat /etc/ascend-docker-runtime.d/driver-mode
# Run from a workstation with access to the target workload cluster.
kubectl -n npu-operator get pod -l app.kubernetes.io/name=ascend-runtime-containerd -o wide

删除文件不会安装、卸载或迁移驱动。如果运行时仍针对 /mnt/tmp/runtime/ascend-docker-runtime 报告 cp: cannot overwrite non-directory, 请将其视为独立的临时负载目录或镜像内容问题,并继续检查运行时 Pod 日志。

节点未显示 NPU 可分配资源

检查驱动 Pod、设备插件、节点标签和可分配资源:

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 尚未就绪,或缺少必需的节点标签;
  • 驱动 Pod 尚未就绪;
  • 设备插件组件已禁用;
  • /run/ascend/.ready/driver-ready 处的运行时驱动目录树尚未就绪;
  • 在 Ascend 910 节点上,缺少 HCCN 设备 IP 配置,或该配置尚未完成调谐;
  • 芯片在升级或恢复期间被报告为运行状况不佳。

对于 Ascend 910 节点,请检查 Device Plugin 日志。如果出现 spec.hccnBootstrap.enabled=true,还要检查 HCCN Bootstrap agent:

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

如果设备插件报告 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 通常会自动维护所有这些发现标签和角色标签。

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

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>

对于控制平面节点,自动添加主节点标签需要标准的 node-role.kubernetes.io/control-plane 标签,以及一个能够在该节点上运行的 npu-feature-discovery Pod。在修改标签之前,请检查节点污点和 DaemonSet 调度情况。如果节点仅具有旧版 node-role.kubernetes.io/master 角色标签,请添加标准控制平面角色标签;否则,正在运行的发现 Pod 会将其视为工作节点,并移除手动添加的 masterselector。

如果发现组件无法覆盖预期节点,而使用角色选择器的组件仍处于 Pending 状态,请应用匹配的放置标签作为临时回退方案:

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 中调整配额。有关配额字段的可见性,请参阅 Accelerator Resource 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 处理程序配置。在场景 2.2 中,主机侧运行时 Driver 树会暂存于 /run/ascend/driver 下;在场景 1 和 2.1 中,运行时使用 /usr/local/Ascend/driver 下的 Host 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 下主机侧的预编译运行时树混淆。

启用默认准入 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:

kubectl get pod <pod-name> -o jsonpath='{.spec.runtimeClassName}{"\n"}'
kubectl -n npu-operator get deployment npu-pod-webhook
kubectl -n npu-operator logs deployment/npu-pod-webhook --tail=100

对于请求 Ascend 资源的工作负载,请在修复 webhook 期间显式设置 RuntimeClass:

spec:
  runtimeClassName: ascend

使用一个注入负责方。如果 HAMi 或其他准入组件注入 RuntimeClass,请在另一个组件中禁用重复的注入器。

RuntimeClass 存在,但 containerd 处理程序缺失

ascend RuntimeClass 和 containerd 处理程序是相互独立的对象。主机升级或替换 containerd 配置可能会保留 RuntimeClass,同时移除其引用的处理程序。在受影响的节点上检查这两个值:

kubectl get runtimeclass ascend -o jsonpath='{.handler}{"\n"}'
kubectl -n npu-operator get ds ascend-runtime-containerd -o wide
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

处理程序名称必须与 RuntimeClass 处理程序匹配,通常为 ascend。恢复节点的 containerd 配置后,重启该节点上的运行时集成 Pod,并等待 DaemonSet 就绪。然后重新创建一个小型测试 Pod,并验证其已接纳的 RuntimeClass 和设备文件。在运行时集成 DaemonSet 管理 containerd 配置期间,不要手动编辑该配置。

缺少指标

检查 exporter 和 ServiceMonitor:

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

如果两者都存在,请继续查阅 ACP 监控文档,检查监控面板导入、Prometheus 发现和抓取错误。

手动 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 节点批量添加 annotation,因为未使用的原始批准可能会留在某个节点上,并批准后续事务。