HAMI设备插件未注册，K8s节点无法识别hami-device-plugin资源类型

Question

HAMI设备插件未注册是GPU资源纳管失败的典型问题：当`hami-device-plugin` Pod在K8s节点上运行正常（Running状态），但`kubectl describe node `中缺失`hami.io/gpu`等自定义资源（CR）字段，且`kubectl get nodes -o wide`显示无对应capacity/allocatable信息时，表明插件虽存活却未成功向kubelet注册。常见根因包括：插件启动后未完成gRPC健康检查（如`/var/lib/kubelet/device-plugins/kubelet.sock`权限不足或路径错误）、插件配置中`--device-plugin-socket`指定路径与kubelet实际监听路径不一致、插件版本与K8s版本不兼容（如v1.26+需适配新的Device Plugin API变更），或插件日志中出现`Failed to register device plugin`但被静默忽略。该问题将导致基于`hami.io/gpu: 1`的Pod调度失败（Pending with Unschedulable），且无法通过`kubectl top node`观测GPU使用率。需结合`journalctl -u kubelet`、插件容器日志及`ls -l /var/lib/kubelet/device-plugins/`综合诊断。

Answer 1

```html

一、现象层：识别“假运行、真失联”的典型症状

当 hami-device-plugin Pod 处于 Running 状态，但 kubectl describe node <node> 中完全缺失 hami.io/gpu、hami.io/npu 等自定义资源字段，且 kubectl get nodes -o wide 的 CAPACITY 和 ALLOCATABLE 列无 GPU 相关条目时，即进入「存活但未注册」的隐蔽故障态。此时调度器无法感知 GPU 资源，所有请求 hami.io/gpu: 1 的 Pod 将卡在 Pending 状态并报 Unschedulable: 0/3 nodes are available: 3 Insufficient hami.io/gpu.。更关键的是：kubectl top node 不显示 GPU metrics，nvidia-smi 在节点上可见但 Kubernetes 层不可见——这是设备插件与 kubelet 通信断裂的黄金信号。

二、协议层：Device Plugin gRPC 注册机制深度解析

Kubernetes Device Plugin 架构依赖严格时序的 gRPC handshake 流程：插件启动 → 连接 /var/lib/kubelet/device-plugins/kubelet.sock → 发送 Register 请求 → kubelet 返回 RegisterResponse → 插件创建 socket 文件（如 /var/lib/kubelet/device-plugins/hami-device-plugin.sock）→ kubelet 主动监听该 socket 并加载资源。任意环节失败均导致注册静默失败。尤其注意：v1.26+ 引入 DevicePluginOptions 扩展字段，旧版 HAMI 插件若未实现 ListAndWatch 的幂等重试或未处理 PreStartContainer 新回调，将直接被 kubelet 拒绝注册。

三、路径与权限层：Socket 路径错配与 Unix 权限陷阱

常见根因矩阵如下：

检查项	预期值	典型异常	验证命令
kubelet.sock 路径	/var/lib/kubelet/device-plugins/kubelet.sock	插件配置 --device-plugin-socket=/run/kubelet/device-plugins/kubelet.sock	ps aux | grep kubelet | grep device-plugins
kubelet.sock 权限	srw-rw---- 1 root root	srw------- 1 root root（插件容器内 uid≠0 无法 connect）	ls -l /var/lib/kubelet/device-plugins/kubelet.sock
插件 socket 文件归属	root:root，权限 srw-rw----	插件以非 root 用户运行，生成 socket 权限为 600	ls -l /var/lib/kubelet/device-plugins/hami-device-plugin.sock

四、日志诊断层：三日志协同分析法

必须交叉比对以下三类日志才能定位静默失败点：

1. HAMI 插件容器日志：重点搜索 Failed to register device plugin、connection refused、context deadline exceeded、listAndWatch returned error；
2. Kubelet 系统日志：执行 journalctl -u kubelet -n 200 --no-pager | grep -i "device\|hami\|plugin"，捕获 Skipping device plugin endpoint 或 Unable to communicate with plugin；
3. 节点级文件系统状态：运行 ls -lR /var/lib/kubelet/device-plugins/，确认 kubelet.sock 存在且可访问，且插件 socket 文件已生成（否则注册流程未走完）。

五、版本兼容层：K8s API 演进与 HAMI 补丁策略

Kubernetes v1.24–v1.27 对 Device Plugin 协议进行了三次关键演进：

• v1.24：废弃 GetDevicePluginOptions 中的 PreStartRequired 字段，改用 DevicePluginOptions.PreStartContainer；
• v1.26：强制要求插件实现 ListAndWatch 的增量更新能力，否则 kubelet 拒绝注册；
• v1.27：引入 TopologyInfo 支持 NUMA-aware GPU 分配，旧版 HAMI 若未填充 Topology 字段将导致资源上报不完整。

建议生产环境采用 HAMI v1.2.0+（适配 K8s v1.26+），并启用 --enable-host-devices 参数以绕过部分内核驱动兼容性问题。

六、修复验证层：从注册到可观测性的闭环验证

修复后执行四阶验证：

1. 注册验证：检查 kubectl describe node 是否出现 hami.io/gpu: 字段及对应 capacity 值；
2. 调度验证：部署测试 Pod（含 resources.limits["hami.io/gpu"]=1），确认状态转为 Running；
3. 指标验证：执行 kubectl top node --use-protocol-buffers，确认 GPU memory/utilization 指标出现；
4. 生命周期验证：删除插件 Pod，观察新实例是否自动重建并完成注册（需检查 DaemonSet 的 updateStrategy.type=RollingUpdate 配置）。

七、架构加固层：面向生产的高可用设计建议

为避免单点注册失败，推荐实施以下加固措施：

graph LR
  A[HAMI DaemonSet] --> B[InitContainer: validate-kubelet-socket]
  A --> C[Sidecar: health-check-proxy]
  B --> D[Check /var/lib/kubelet/device-plugins/kubelet.sock exists & perm]
  C --> E[Expose /healthz endpoint for livenessProbe]
  D --> F{Valid?}
  F -->|Yes| G[Start main container]
  F -->|No| H[Fail fast with exit code 100]
  E --> I[Probe every 5s, timeout 2s]

八、监控告警层：构建 GPU 资源纳管 SLI/SLO

定义核心可观测性指标：

• SLI-1：设备插件注册成功率 = sum(rate(device_plugin_registration_success_total{plugin=\"hami\"}[1h])) / sum(rate(device_plugin_registration_attempt_total{plugin=\"hami\"}[1h]))；
• SLI-2：GPU 资源上报延迟 = histogram_quantile(0.95, sum(rate(device_plugin_listandwatch_latency_seconds_bucket{plugin=\"hami\"}[1h])) by (le))；
• SLO：注册成功率 ≥ 99.95%，上报延迟 P95 ≤ 2s —— 低于此阈值触发 PagerDuty 告警并自动执行 kubectl rollout restart ds/hami-device-plugin。

九、升级演进层：HAMI 与 K8s 生态协同路线图

未来半年关键演进方向：

1. 对接 Kubernetes 1.28 的 TopologyManagerPolicy=best-effort，支持 GPU 与 CPU/NUMA 绑定策略联动；
2. 集成 NVIDIA DCNM（Data Center Networking Manager），实现 GPU Direct RDMA 资源跨节点发现；
3. 开发 eBPF 辅助探针，替代传统 nvidia-smi 调用，降低插件 CPU 开销 40%+；
4. 支持 CRD GpuProfile 动态定义显存切片、计算能力、MIG 配置模板，实现多租户细粒度配额。

十、知识沉淀层：建立组织级 GPU 故障模式库（GPU-FMEA）

建议将本问题归入「GPU-FMEA-003：Device Plugin Registration Failure」条目，结构化记录：

• Failure Mode：插件进程存活但未向 kubelet 注册自定义资源；
• Effects：GPU 调度阻塞、监控断连、AI 训练任务批量失败；
• Root Causes（按发生频率排序）：socket 权限错误（42%）、kubelet.sock 路径不一致（28%）、K8s 版本不兼容（18%）、插件内存泄漏导致 gRPC 连接超时（12%）；
• Detection Method：Prometheus + Alertmanager 自动巡检 kube_node_status_condition{condition="Ready"} == 1 且 kube_node_spec_unschedulable == 0 但 count(kube_node_status_capacity{resource="hami.io/gpu"}) == 0；
• Mitigation Runbook：提供一键诊断脚本 hami-debug.sh（内置 socket 检查、权限修复、版本校验、日志聚合功能）。

```