NPU故障处理

现象描述

节点管理界面显示“昇腾驱动未就绪”，表示该Kubernetes节点上检测到有NPU硬件，但节点资源状态中未发现足量的huawei.com/ascend-1980（或huawei.com/ascend-310）资源。可能的原因涉及插件安装、NPU驱动、设备文件发现、kubelet注册等多个环节，建议按以下顺序逐一排查。

若仍无法解决，请提交工单处理。

排查步骤

1. 检查AI套件(NPU)插件状态。
   1. 在CCE控制台，检查目标集群的CCE AI套件（Ascend NPU）插件状态。

      插件状态	含义	处理方式
      运行中	插件正常	继续步骤2。
      安装中	正在安装	等待安装完成后重新检查。
      安装失败	安装出错	查看安装日志，常见原因包括：镜像拉取失败（检查节点网络和镜像仓库连通性）、Helm模板渲染错误、节点资源不足。
      未安装	未安装该插件	在需要使用NPU的节点池上安装该插件。

   2. 确认插件配置中的启用范围是否包含目标节点所在的节点池。

      如果插件状态为“运行中”，但特定节点上仍显示“昇腾驱动未就绪”，可能是该节点上的DaemonSet Pod出现问题，请继续步骤2。

2. 检查Device Plugin Pod状态。

   CCE AI套件（Ascend NPU）插件以DaemonSet方式部署，每个有NPU硬件的节点上应运行一个Device PluginPod。

   1. 查找Device Plugin Pod。

      # 替换 <namespace> 为实际命名空间（通常为 kube-system）
      kubectl get pods -n kube-system -o wide | grep npu

      预期输出类似：

      huawei-npu-device-plugin-xxxxx     1/1     Running   0    2d   10.x.x.x   node-name   <none>   <none>

   2. 检查目标节点上的Pod状态。

      # 替换 <node-name> 为显示"昇腾驱动未就绪"的节点名
      kubectl get pods -n kube-system --field-selector spec.nodeName=<node-name> | grep npu

      可能的状态及含义：

      Pod状态	含义	下一步
      Running	Pod运行中，可能注册未完成	步骤3
      CrashLoopBackOff	Pod反复崩溃重启	步骤3
      Pending	Pod无法调度到该节点	检查节点污点/标签/资源
      不存在	DaemonSet 未调度到该节点	检查节点选择器和DaemonSet状态

   3. 如果Pod不存在或Pending。
      1. 检查DaemonSet是否被调度。

         kubectl get daemonset -n kube-system | grep npu
         kubectl describe daemonset <npu-daemonset-name> -n kube-system

      2. 检查节点是否满足调度条件。

         # 查看节点标签
         kubectl get node <node-name> --show-labels
         # 查看节点污点
         kubectl describe node <node-name> | grep -A5 Taints

3. 检查Device Plugin Pod日志。

   # 查看当前日志
   kubectl logs <npu-device-plugin-pod-name> -n kube-system
   
   # 查看上一次崩溃的日志
   kubectl logs <npu-device-plugin-pod-name> -n kube-system --previous

   关键日志信息对照表：

   日志关键字	含义	排查步骤
   wait device init failed	等待NPU设备初始化超时	步骤4
   init devmanager failed	DCMI库初始化失败（驱动通信异常）	步骤4
   get device list failed / GetDeviceList	无法从驱动获取设备列表	步骤4
   default device: xxx is missing	NPU基础设备文件缺失	步骤5
   set all device and type failed	设备发现失败	步骤4 + 步骤5
   init plugin server failed	插件服务初始化失败	步骤6
   update node label failed	更新节点标签失败（K8s API异常）	步骤6
   Could not contact Kubelet / register to kubelet fail	向kubelet注册失败	步骤6
   socket path verify failed	kubelet device-plugin socket路径不可用	步骤6
   failed to get node allocatable	healthz外部检查无法获取节点资源	步骤6
   resource xxx not registered on node	healthz检查到资源未注册	步骤6
   ListAndWatch not serving	gRPC ListAndWatch未运行	步骤5
   scanned N devices but reported 0	扫描到设备但未上报	步骤4

4. 检查NPU驱动状态。
   1. 登录到目标节点。

      ssh root@<node-ip>

   2. 检查NPU驱动是否已安装。

      # 检查驱动版本
      npu-smi info

      预期输出（正常情况）：

      +--------------------------------------------------------------------------------+
      | npu-smi 24.1.0                   Version: 24.1.0                               |
      +----------------------+-----------------+---------------------------------------+
      | NPU   Name           | Health          | Power(W)    Temp(C)           Hugepages|
      | Chip                 | Bus-Id          | AICore(%)   Memory-Usage(MB)            |
      +======================+=================+=======================================+
      | 0     910B3          | OK              | 65.5        42                  0/0    |
      | 0                    | 0000:C1:00.0    | 0           0/0                      |
      +======================+=================+=======================================+
      ...

      异常情况：

      输出	含义	处理方式
      command not found	驱动未安装	安装对应型号的昇腾NPU驱动
      DCMI API failed	驱动异常或未完全初始化	重启节点或重新加载驱动
      卡片显示但状态为 Abnormal / Fault	硬件故障	联系硬件运维
      卡片数量少于预期	部分卡未识别	检查PCIe连接

   3. 检查驱动内核模块是否加载。

      # 查看 NPU 相关内核模块
      lsmod | grep drv_pcidrv
      lsmod | grep drv_davinci

      如果未加载，尝试手动加载：

      modprobe drv_pcidrv
      modprobe drv_davinci

      如果加载失败，检查dmesg获取更多信息：

      dmesg | grep -i "davinci\|npu\|ascend" | tail -50

   4. 检查设备拓扑（WaitDevicesInit阶段检查的内容）

      查看npu-smi拓扑中的卡数：

      npu-smi info -t topo

      如果npu-smi 输出数量不足，说明驱动已加载但HDK（Huawei Driver Kit）未完成初始化。这种情况通常发生在节点刚重启后，驱动需要20-30秒完成初始化。如果等待超过1分钟仍未就绪，考虑驱动问题或硬件故障。

5. 检查NPU设备文件。

   Device Plugin启动时会检查必要的NPU设备文件是否存在。

   1. 检查基础设备文件。

      # 必须存在的设备文件
      ls -la /dev/davinci_manager
      ls -la /dev/hisi_hdc
      
      # 可选设备文件（部分型号存在）
      ls -la /dev/devmm_svm
      
      # NPU卡设备文件
      ls -la /dev/davinci*

      预期输出：

      crw------- 1 root root 234, 0 ... /dev/davinci0
      crw------- 1 root root 234, 1 ... /dev/davinci1
      crw------- 1 root root 234, 0 ... /dev/davinci_manager
      crw------- 1 root root 234, 0 ... /dev/hisi_hdc

      异常情况：

      异常	原因	处理
      /dev/davinci_manager不存在	驱动未正确安装或未加载	回到步骤4
      /dev/hisi_hdc不存在	驱动未正确安装或未加载	回到步骤4
      /dev/davinci0等卡设备不存在	驱动未发现设备	回到步骤4
      设备文件存在但权限错误	驱动安装配置问题	重新安装驱动

   2. 检查设备文件权限。

      设备文件应为root:root且为字符设备（c开头）。如果权限不正确，可能需要重新加载驱动模块或重启节点。

6. 检查kubelet设备插件注册。
   1. 检查kubelet device-plugin socket。

      # 检查kubelet device-plugin目录
      ls -la /var/lib/kubelet/device-plugins/

      预期看到kubelet.sock文件和Device Plugin注册的socket文件（如Ascend910.sock或ascend910.sock）。

      如果kubelet.sock不存在，说明kubelet的device plugin功能未启用。检查kubelet配置：

      # 检查kubelet启动参数
      ps aux | grep kubelet | grep -i "feature-gates"
      
      # 或检查kubelet配置文件
      cat /var/lib/kubelet/config.yaml | grep -i feature

      确保DevicePlugins feature gate已启用（Kubernetes 1.10+默认启用）。

   2. 检查Device Plugin注册的socket。

      ls -la /var/lib/kubelet/device-plugins/ | grep -i ascend

      应该看到类似Ascend910.sock的文件。如果没有：

      • Device Plugin Pod可能在启动过程中崩溃（回到步骤3查看日志）。
      • Device Plugin容器可能没有挂载/var/lib/kubelet/device-plugins目录。
   3. 检查节点资源是否注册成功。

      # 查看节点上的NPU资源
      kubectl describe node {节点名称} | grep -i ascend

      预期输出：

      huawei.com/ascend-1980:  8

      如果资源容量为0或不显示，但Device Plugin Pod正在运行，可能是：

      • Device Plugin注册后又被kubelet移除（socket被删除）。
      • Device Plugin在ListAndWatch阶段未正确上报设备。
   4. 查看kubelet日志。

      # 查看kubelet关于device-plugin的日志
      journalctl -u kubelet | grep -i "device\|plugin\|ascend\|npu" | tail -30

      关键字与含义如下：

      • failed to register device plugin：Device Plugin注册失败。
      • device plugin unhealthy：Device Plugin被判定为不健康。
      • reregistered：Device Plugin重新注册成功。

常见问题

• 节点重启后短暂显示“昇腾驱动未就绪”
  • 问题现象：节点重启后，界面短暂显示"昇腾驱动未就绪"，几分钟后自动恢复。
  • 问题根因：NPU驱动的HDK初始化需要20-30秒，Device Plugin会在此期间等待设备就绪（WaitDevicesInit）。等待完成后Device Plugin正常注册资源，界面恢复正常。
  • 解决方案：这是正常的启动过程，无需手动干预。如果超过5分钟仍未恢复，按上述步骤排查。
• NPU驱动未安装
  • 问题现象：节点上npu-smi info命令不存在。
  • 问题根因：节点未安装昇腾NPU驱动。
  • 解决方案：
    1. 确认节点硬件型号（910A/910B/910B3/310/310P）。
    2. 安装对应型号的昇腾NPU驱动和固件。
    3. 重启节点使驱动生效。
    4. 确认npu-smi info和ls /dev/davinci*正常后，重启Device Plugin Pod。
• Device Plugin Pod反复重启（CrashLoopBackOff）
  • 问题现象：Device Plugin Pod反复重启，状态为CrashLoopBackOff。
  • 问题根因：常见崩溃原因包括NPU驱动未安装或异常、设备文件不存在、参数配置错误、DCMI库初始化失败（驱动版本不兼容）等。
  • 解决方案：
    1. 使用kubectl logs {pod名称} --previous查看上一次崩溃的日志。
    2. 根据日志中的错误信息，定位到对应的排查步骤。
    3. 按步骤4检查驱动、步骤5检查设备文件，或检查ConfigMap中的配置。
• Device Plugin注册成功但资源数量不正确
  • 问题现象：节点上有8张NPU卡，但huawei.com/ascend-1980资源数量少于8。
  • 问题根因：部分卡处于故障状态被Device Plugin标记为Unhealthy，其资源不会被上报。
  • 解决方案：
    1. 检查npu-smi info确认所有卡都处于健康状态。
    2. 检查Device Plugin日志中是否有invalid device num错误。
    3. 检查是否有卡处于故障状态。
    4. 修复故障卡后重启Device Plugin Pod。
• healthz检查导致Device Plugin反复重启
  • 问题现象：Device Plugin Pod在运行一段时间后被重启，日志显示healthz失败。
  • 问题根因：healthz检查分为内部检查和外部检查，失败原因不同。
  • 解决方案：
    1. 查看healthz diagnose输出确认具体失败的检查项。
    2. 内部检查失败（ListAndWatch not serving）通常是gRPC连接问题。
    3. 外部检查失败（resource not registered）通常是kubelet尚未完成资源更新。
    4. 如果是热复位过程中healthz失败，属于预期行为，复位完成后会恢复。