Alauda Build of HAMi
  • 简体中文

    • 故障排查

    针对 Alauda Build of HAMi 使用基于症状的故障排查。对于厂商驱动内部机制、固件和硬件健康状况，请继续参考对应的硬件厂商文档。

    请先确认所选的后端路径：

    目录

    节点未显示 HAMi 资源ACP 配额页面未显示 HAMi 资源Pod 处于 PendingNVIDIA 后端上的 Device Plugin Pod 无法启动CUDA 报告设备忙或不可用调度器等待节点锁指标缺失HAMi-WebUI 返回 HTTP 523 或 VGPU_DOMAIN_ERROR已安装 HAMi Ascend Device Plugin，但资源缺失已启用软切片，但节点模式仍为 falseSoft-slice Pod 退出，并且 lifecycle hook 报告容器已停止

    节点未显示 HAMi 资源

    检查 HAMi pods 和节点标签：

    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 plugin form 中使用的节点标签缺失；
    • 厂商驱动或 runtime 尚未就绪；
    • 已安装的 HAMi package 中未启用该后端；
    • 另一个加速器插件为同一节点或同一加速器设备接管了设备暴露。

    如果节点仅报告直接的厂商资源键，请检查厂商 Device Plugin 是否仍然是当前的暴露路径。使用当前交付 package 和版本页面，确认 Ascend NPU 或 Ascend vNPU 期望的 HAMi 资源名称。

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

    对于 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 检查节点。

    一种常见缓解方式是在节点上启用 persistence mode，然后重启 HAMi Device Plugin pod：

    nvidia-smi -pm enable

    CUDA 报告设备忙或不可用

    当多个工作负载共享同一块 NVIDIA GPU 时，如果 device compute mode 阻止并发访问，CUDA 可能会报告设备忙或不可用。

    检查节点上的 device compute mode。如果工作负载规划允许多个进程，请相应配置 device mode：

    nvidia-smi -i 0 -c 0

    调度器等待节点锁

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

    当 Alauda package 中提供包含节点锁清理修复的 HAMi 版本时，请升级到该版本。

    指标缺失

    检查后端使用的 exporter 和 dashboard 路径。对于 NVIDIA 后端指标：

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

    如果 exporter 正在运行，请继续查看 ACP monitoring 文档，以检查 dashboard 导入、Prometheus 发现以及 scrape 错误。

    对于 Ascend 后端，请使用当前 Ascend base 和 HAMi package 支持矩阵中记录的指标路径。不要将 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。常见原因是在 plugin form 中只填写了 base64 负载，而遗漏了认证 scheme。

    1. 参考 Install HAMi-WebUI 重新生成设置。

    2. 确认认证字段包含完整值：

      Basic <base64(username:password)>

    3. 使用该值作为 Authorization header，请求 ${prometheus_address%/}/api/v1/query?query=up。仅当 Prometheus 返回包含 "status":"success" 的 JSON 后再继续。

    4. 更新 Alauda Build of HAMi-WebUI 集群插件表单，并等待 WebUI pod 变为 Ready。

    5. 重新执行 WebUI 后端 instant-vector 查询。它必须返回 HTTP 200 和一个 JSON data 数组。

    如果完整的 Basic 值仍然会发生重定向，请确认该地址指向的是 Prometheus API service，而不是交互式平台路由，并确认由当前 Feature monitoring 资源选择的 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 仍处于 pending，缺少 ascend=on 标签，driver host path 与节点不匹配，或者仍在运行原生 Ascend Device Plugin。

    使用 Switch the Ascend Device Plugin Owner 验证面向用户的 NPUOperatorCtl 设置、生成的 policy 以及当前生效的 DaemonSet。不要只删除生成的 DaemonSet，因为其 controller 可能会重新创建它。

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

    检查拥有该资源的 custom resource、两个 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 在启动时加载节点配置；如果 reconciliation 更新了 ConfigMap 但没有重启 DaemonSet，请只重启该 DaemonSet，并再次验证节点注解。请参见 Configure Ascend Slicing Mode。

    Soft-slice Pod 退出，并且 lifecycle hook 报告容器已停止

    来自 PostStart hook 的事件，例如 cannot exec in a stopped state，通常是次要现象：主容器进程在 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 与注入的 soft-slice 库 ABI 不兼容。请将工作负载的精确路径和镜像 runtime 与 Ascend Driver and CANN compatibility 中的受限结果进行对比。

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