# NPU故障处理
在Kubernetes环境中，NPU资源的管理链路涉及插件安装、驱动初始化、设备发现、kubelet注册等多个环节，任一环节异常都可能导致NPU资源不可用。本文将介绍CCE集群中NPU常见的故障场景、排查流程及对应解决方案，以便您快速定位故障原因，最大限度减少宕机时间，保障业务连续性。
#### 前提条件
- 集群中已安装CCE AI套件（NPU）插件。
- 适用NPU型号：Ascend 910 / 910B / 910B3、Ascend 310 / 310P系列。
- 已具备CCE集群管理员权限。
- 已获取目标节点的SSH登录权限。
 
#### 昇腾驱动未就绪
#### 现象描述
节点管理界面显示"昇腾驱动未就绪"，表示该Kubernetes节点上检测到有NPU硬件，但节点资源状态中未发现足量的huawei.com/ascend-1980（或huawei.com/ascend-310）资源。可能的原因涉及插件安装、NPU驱动、设备文件发现、kubelet注册等多个环节，建议按以下顺序逐一排查。
若仍无法解决，请[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/createIndex)处理。
#### 排查步骤
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失败，属于预期行为，复位完成后会恢复。