故障排查

针对 Alauda Build of HAMi,请根据症状进行故障排查。对于厂商驱动内部机制、固件和硬件运行状况,请参阅相应的硬件厂商文档。

首先确认所选的后端路径:

节点未显示 HAMi 资源

检查 HAMi Pod 和节点标签:

kubectl get pods -n kube-system | grep -E "hami-scheduler|hami-device-plugin"
kubectl get node ${nodeName} --show-labels
kubectl get node ${nodeName} -o jsonpath='{.status.allocatable}'

常见原因:

  • HAMi 插件表单使用的节点标签缺失;
  • 厂商驱动或运行时尚未就绪;
  • 已安装的 HAMi 软件包未启用该后端;
  • 其他加速器插件负责向同一节点或同一加速器设备公开设备资源。

如果节点仅报告直接的厂商资源键,请检查厂商设备插件是否仍是当前的资源公开路径。请参阅当前交付软件包和版本页面,确认 Ascend NPU 或 Ascend vNPU 对应的 HAMi 资源名称。

对于 NVIDIA GPU 节点,HAMi 通常会选择带有 gpu=on 的节点。直接的 NVIDIA GPU Device Plugin 通常会选择带有 nvidia-device-enable=pgpu 的节点。如果同一节点同时具有这两个标签,并且报告了 nvidia.com/gpu 和 HAMi 资源键(例如 nvidia.com/gpualloc),请移除其中一个选择器标签,或将工作负载分配到不同的节点池。

对于 Ascend NPU 或 Ascend vNPU 节点,HAMi 通常会选择带有 ascend=on 的节点。如果 NPU Operator 也会准备该节点,请检查 NPUOperatorCtl 组件设置。在 Alauda Build of HAMi Ascend Device Plugin 接管设备资源公开之前,请停止原生 Ascend Device Plugin。不要依赖资源键名称来区分直接 NPU 路径和 HAMi 路径。

ACP 配额页面未显示 HAMi 资源

节点可分配资源和 ACP 配额字段并不相同。如果节点报告了 HAMi 资源,但 ACP 配额页面中未显示这些资源,请在 kube-public 中注册相应的资源元数据。

有关必需的 ConfigMap 字段和示例,请参阅 加速器资源配额。

如果 ACP 3.18.2 未在表单中显示 HAMi 扩展资源,请使用前端镜像 build-harbor.alauda.cn/acp/icarus:v3.18.108,以支持通过表单选择 HAMi 扩展资源。

Pod 处于 Pending 状态

描述 Pod:

kubectl describe pod <pod-name>

检查:

  • 工作负载是否为该后端请求了正确的 HAMi 资源键;
  • 项目和命名空间配额是否允许请求的资源;
  • 目标节点是否报告了足够的 HAMi 可分配资源;
  • 节点是否仍通过冲突的直接厂商插件路径公开;
  • 除非当前版本页面明确支持该组合,否则工作负载是否将 HAMi 资源键与其他共享技术的资源键混用。

NVIDIA 后端上的 Device Plugin Pod 无法启动

如果 NVIDIA 驱动调用速度非常慢,HAMi Device Plugin 可能无法启动。使用 nvidia-smi 检查节点。

一种常见的缓解方法是在节点上启用持久化模式,然后重启 HAMi Device Plugin Pod:

nvidia-smi -pm enable

CUDA 报告设备繁忙或不可用

当多个工作负载共享同一 NVIDIA GPU 时,如果设备计算模式阻止并发访问,CUDA 可能会报告设备繁忙或不可用。

检查节点上的设备计算模式。如果工作负载计划允许多个进程,请相应配置设备模式:

nvidia-smi -i 0 -c 0

Scheduler 等待节点锁

如果 Pod 在绑定阶段被删除,后续 Pod 可能会一直等待,直到节点锁过期。检查 HAMi Scheduler 日志,并确认工作负载是否在调度期间被删除。

当包含节点锁清理修复的 HAMi 版本在 Alauda 软件包中可用时,升级到该版本。

缺少指标

检查后端使用的 exporter 和监控面板路径。对于 NVIDIA 后端指标:

kubectl get pods -n kube-system | grep dcgm-exporter

如果 exporter 正在运行,请继续参阅 ACP 监控文档,检查监控面板导入、Prometheus 发现和抓取错误。

对于 Ascend 后端,请使用当前 Ascend 基础版本和 HAMi 软件包支持矩阵中记录的指标路径。不要将 NVIDIA DCGM-Exporter 检查复制到 Ascend 后端故障排查中。

HAMi-WebUI 返回 HTTP 523 或 VGPU_DOMAIN_ERROR

HAMi-WebUI 页面可能可以成功加载,但其基于 Prometheus 的请求会失败。在浏览器开发者工具或直接 API 请求中,失败通常出现在:

POST /api/vgpu/v1/monitor/query/instant-vector

HAMi-WebUI 会将 Prometheus 查询失败包装为 HTTP 523,并使用原因 VGPU_DOMAIN_ERROR。HTTP 523 是 WebUI 错误代码,不是原始的 Prometheus 状态。

如果错误中包含 <!doctype html>、登录页面或授权页面,则表示配置的 Prometheus 地址发生了重定向,而不是返回 Prometheus JSON。常见原因是在插件表单中仅输入了 base64 负载,而省略了身份验证方案。

  1. 从安装 Alauda AI Infrastructure Accelerator Virtualization Console重新生成设置。

  2. 确认身份验证字段包含完整值:

    Basic <base64(username:password)>
  3. 使用该值作为 Authorization 标头查询 ${prometheus_address%/}/api/v1/query?query=up。只有在 Prometheus 返回包含 "status":"success" 的 JSON 后,才能继续。

  4. 更新 HamiWebUI 自定义资源,并等待 WebUI Pod 变为 Ready。

  5. 重复 WebUI 后端的 instant-vector 查询。该查询必须返回 HTTP 200 和 JSON data 数组。

如果完整的 Basic 值仍然会触发重定向,请确认该地址属于 Prometheus API 服务,而不是交互式平台路由,并确认当前 Feature monitoring 资源所选择的监控 Secret。

HAMi Ascend Device Plugin 已安装但资源缺失

从所属资源向下检查,直到节点:

kubectl get csv -A | grep hami-ascend-device-plugin
kubectl -n <hami-namespace> get hamiadp hami-ascend-device-plugin -o yaml
kubectl -n <hami-namespace> get ds hami-ascend-device-plugin -o wide
kubectl get node <ascend-node> --show-labels
kubectl get node <ascend-node> -o jsonpath='{.status.allocatable}'

常见原因包括 CSV 尚未到达 Succeeded、手动批准的 InstallPlan 仍处于待处理状态、缺少 ascend=on 标签、驱动主机路径与节点不匹配,或原生 Ascend Device Plugin 仍在运行。

使用切换 Ascend Device Plugin 所有者验证面向用户的 NPUOperatorCtl 设置、生成的策略和活动 DaemonSet。不要只删除生成的 DaemonSet,因为其控制器可能会重新创建它。

已启用软切分但节点模式仍为 false

检查所属自定义资源、两个 ConfigMap 以及生效的节点注解:

kubectl -n <hami-namespace> get hamiadp hami-ascend-device-plugin \
  -o jsonpath='{.spec.config}{"\n"}{.spec.hamiVnpuCore.enabled}{"\n"}{.spec.nodeConfig}{"\n"}'
kubectl -n <hami-namespace> get configmap hami-scheduler-device -o yaml
kubectl -n <hami-namespace> get configmap hami-device-node-config -o yaml
kubectl get node <ascend-node> \
  -o go-template='hami-vnpu-core={{ index .metadata.annotations "hami-vnpu-core" }}{{ "\n" }}'

spec.nodeConfig 中的节点条目优先于全局值。如果实例使用 hami-scheduler-device,并且其中包含 spec.config.create: false,HAMi Ascend Device Plugin 会读取由 HAMi 所有的 ConfigMap;仅在 Device Plugin 表单中启用 spec.hamiVnpuCore.enabled 不会重写共享 ConfigMap,也不会更改生效模式。

在所属的 HAMiAscendDevicePlugin.spec.nodeConfig 中显式设置目标节点,而不是编辑生成的 ConfigMap。然后等待 daemonset/hami-ascend-device-plugin 完成滚动更新。Device Plugin 会在启动时加载节点配置;如果协调过程更新了 ConfigMap 但未重启 DaemonSet,则仅重启该 DaemonSet,并再次验证节点注解。请参阅配置 Ascend 切分模式。

软切分 Pod 退出或注入的库无法加载

v1.4.1 Ascend Device Plugin 不会注入 PostStart hook。首先检查终止状态和上一个容器的日志:

kubectl -n <namespace> get pod <pod-name> \
  -o jsonpath='{range .status.containerStatuses[*]}{.name}{" exit="}{.state.terminated.exitCode}{" reason="}{.state.terminated.reason}{"\n"}{end}'
kubectl -n <namespace> logs <pod-name> -c <container-name> --previous
kubectl -n <namespace> describe pod <pod-name>

如果进程以代码 127 退出,并在加载 /hami-vnpu-core/libvnpu.so 时报告缺少 rtStreamGetCaptureInfo 等符号,则工作负载的 CANN runtime 与注入的软切分库不兼容。将确切的工作负载路径和镜像 runtime 与Ascend Driver 和 CANN 兼容性中限定范围内的结果进行比较。

选择 CANN 版本与已安装 Ascend Driver 匹配的不可变工作负载镜像,记录其摘要,并在接受该环境前运行具有代表性的设备打开、内存分配或推理操作。