#故障排查

使用此页面排查安装 Alauda GPU Management 后的常见问题。每个条目均按“症状 → 检查项”组织。

#Driver Pod 卡在 ImagePullBackOff

driver DaemonSet 无法拉取 driver 镜像。

• 确认集群 registry 中存在该 node kernel 对应的 driver 镜像 tag。在 precompiled 模式下，安装包只包含经过验证的 tuple；其他 kernel 必须手动导入。请参见 Configure the driver mode。

• 如果 ACP 强制执行镜像白名单策略，请确认导入到 registry 中的 driver tag 已被 ImageWhiteList 允许。

• 验证实际拉取到的镜像，而不只是已被接纳的 Pod 镜像：

  kubectl get pods -l app=nvidia-driver-daemonset \
    -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\t"}{.status.containerStatuses[0].imageID}{"\n"}{end}'

#node 上没有 nvidia.com/gpu

该 node 未上报 GPU 资源。

• 确认所选模式下 driver 状态正常。在 preinstalled 模式下，在主机上运行 nvidia-smi；在 managed 模式下，确认 driver Pod 处于 Running 状态。
• 确认 device plugin Pod 在该 node 上处于 Running 状态。
• 确认 GPU Feature Discovery 已为该 node 打上标签，并且集群已安装 Node Feature Discovery。

#GPU components 在单节点或 control-plane 集群上无法调度

在 GPU node 同时也是 control-plane node 的集群中——单节点和单机部署中很常见——operand DaemonSets 不会被调度，node 也不会被标记为 GPU，且 nvidia.com/gpu.present 会一直保持 false，allocatable 为 0。默认情况下，operand DaemonSets 只容忍 nvidia.com/gpu taint，而不容忍 control-plane 的 NoSchedule taint，因此带有 control-plane taint 的 node 上不会运行任何组件。

为 operands 添加 control-plane toleration。在 ClusterPolicy 表单中设置 Operand Tolerations（位于 Scheduling 下），或在 YAML 中设置 spec.daemonsets.tolerations：

spec:
  daemonsets:
    tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule
      - key: node-role.kubernetes.io/control-plane
        operator: Exists
        effect: NoSchedule

前置条件 Node Feature Discovery 也必须容忍相同的 taint，否则该 node 永远不会被标记，也就无法检测到 GPU。安装 NFD 时，请在 NFD worker（以及 gc）上设置 control-plane toleration——例如在 NFD plugin 配置中添加该 toleration，使其 worker DaemonSet 能够调度到 control-plane node 上。

默认不设置该 toleration 是有意为之：生产环境中的 GPU node 通常是专用 worker node，因此除非显式启用，否则不应允许 operands 调度到 control-plane node 上。

#Driver mode 不匹配

症状包括 driver 无法构建模块，或者 operator 试图管理已在主机上安装的 driver。

• 在 preinstalled-driver 模式下，确认 driver.enabled=false。如果启用，operator 将尝试部署与主机 driver 冲突的 driver。
• 在 air-gapped 集群的 upstream mutable-OS 模式下，确认 driver.repoConfig 指向一个包含目标 kernel headers 的内部源；否则会导致节点上模块构建失败。
• 在 precompiled 模式下，确认所选 driver 镜像 tuple（ClusterPolicy 中的 driver.version）与 node kernel 完全匹配。

#dashboard 中缺少指标

GPU dashboards 没有数据显示。

• 确认 DCGM-Exporter Pods 处于 Running 状态：

  kubectl get pods -l app=nvidia-dcgm-exporter -A

• 确认在 ClusterPolicy 中已启用 exporter，或者为这些 node 的 metrics owner 作为独立 plugin 安装。请参见 DCGM-Exporter。

• exporter 启动后，数据出现在 GPU dashboard 面板前需要等待一小段时间。

#Workload 无法访问 GPU

请求 nvidia.com/gpu 的 Pod 已运行，但无法看到设备。

• 确认 container toolkit 已配置 nvidia runtime handler，并且该 Pod 运行在 nvidia RuntimeClass 下；如有需要，请显式设置 runtimeClassName: nvidia。
• 确认请求的是 nvidia.com/gpu 的资源 limit，并且该 node 具有可分配的 GPU。

如果完成以上检查后问题仍然存在，请收集 ClusterPolicy 状态、driver 和 device plugin Pod 日志，以及 node 上的 nvidia-smi 输出，然后联系 Alauda Customer Support。