Ascend Device Plugin 系统级架构分析

源码路径: mind-cluster-v26.0.1/component/ascend-device-plugin
分析日期: 2026-07-31
文件统计: 52个非测试Go源文件,约20,000行代码
制图工具: fireworks-tech-graph (Style 1: Flat Icon)


目录

  1. 项目整体架构与设计思路
  2. 整体运行流程
  3. 子模块划分总览
  4. 入口层模块 — main.go
  5. 工厂层模块 — DeviceFactory
  6. gRPC服务层模块 — Server
  7. 设备管理层模块 — Device
  8. 公共基础层模块 — Common
  9. K8s客户端模块 — KubeClient
  10. 重复设备检测模块 — DuplicateDetector
  11. 拓扑模块 — Topology
  12. 模块间调用关系与数据流
  13. 图表索引

一、项目整体架构与设计思路

在这里插入图片描述

1.1 项目定位

Ascend Device Plugin 是华为昇腾NPU的 Kubernetes Device Plugin 实现,遵循 Kubernetes Device Plugin 协议(gRPC),负责将物理NPU设备(Ascend910/310/310P)注册到K8s集群,管理设备的发现、分配、健康监控和故障处理。

1.2 设计思路

采用 分层架构 + 工厂模式 + 接口抽象 + CGO桥接 的设计:

设计原则实现方式
分层架构入口层 → 工厂层 → 服务层/设备层 → 基础层,自上而下单向依赖
工厂模式DeviceFactory 根据设备类型创建对应的 Manager 实例
接口抽象DevManager 接口统一不同型号NPU的操作契约
继承复用AscendTools 基类提供通用能力,910/310/310P 分别继承扩展
CGO桥接通过 CGO 调用底层 DCMI 驱动库(libdcmi.so),实现设备发现/健康/复位等硬件操作
gRPC服务实现 K8s Device Plugin 协议的 ListAndWatch/Allocate 接口
优雅容错故障分级处理(L1警告→L2降级→L3隔离→L5重置),支持热复位

1.3 架构分层

层次模块核心职责
入口层main.go命令行解析、参数校验(12项)、启动初始化
工厂层DeviceFactory设备驱动初始化、Manager创建、名称映射
gRPC服务层ServergRPC服务、设备上报(ListAndWatch)、分配(Allocate)、Pod资源查询
设备管理层DeviceNPU设备发现、健康监控、故障处理、热复位、虚拟设备(vNPU)
公共基础层Common常量、工具函数、故障码、协议定义
K8s客户端层KubeClientK8s API交互、ConfigMap CRUD、节点Informer
重复检测层DuplicateDetector容器设备挂载重复检测(Docker/Containerd)
拓扑层Topology拓扑文件读写、Rack拓扑采集

二、整体运行流程

在这里插入图片描述

2.1 进程启动流程

1. main() 入口
   ↓
2. initLogModule() — 初始化日志模块
   ↓
3. 解析命令行 Flag (--useV2 --dmVol --fdFlag --deviceType ...)
   ↓
4. checkParam() — 参数校验 (12项check函数)
   ├── checkListWatchPeriod()           (ListAndWatch周期)
   ├── checkPresetAndVolcanoRelation()   (预置+Volcano关系)
   ├── checkUse310PMixedInsertWithVolcano()
   ├── checkUse310PMixedInsertWithShareDevCount()
   ├── checkPresetWithShareDevCount()
   ├── checkSoftShareDevConfigDir()
   ├── checkHotResetMode()
   ├── checkBuildScene()
   ├── checkLinkdownTimeout()
   ├── checkThirdPartyScanDelay()
   ├── checkDeviceResetTimeout()
   └── checkShareDevCount()
   ↓
5. devicefactory.InitFunction()
   ├── initDevManager()
   │   ├── AutoInit()          (DCMI驱动初始化, CGO)
   │   ├── NewHwAscend910Manager() / NewHwAscend310Manager() / NewHwAscend310PManager()
   │   └── InitSwitchDev()     (交换设备初始化)
   ↓
6. NewHwDevManager() 创建设备管理器
   ├── setAscendManager()  (按设备类型设置Manager)
   ├── setAllDeviceAndType()
   ├── initPluginServer()
   ↓
7. ListenDevice() — 启动主循环
   ├── Serve()         (gRPC服务协程)
   ├── subscribeNpuFaultEvent() (故障订阅协程)
   ├── pollFaultCodeCM()  (故障码轮询协程)
   └── ticker 定时任务   (设备信息更新)
   ↓
8. 阻塞等待信号 (SIGTERM/SIGINT)

2.2 运行时核心协程

进程启动后进入 ListenDevice() 主循环,同时运行多个协程:

协程功能触发方式
ServegRPC服务,响应kubelet的ListAndWatch/Allocate请求持续监听
subscribeNpuFaultEvent订阅NPU硬件故障事件(DCMI回调)事件驱动
pollFaultCodeCM轮询ConfigMap中的故障码定时轮询
ticker周期更新设备信息到K8s ConfigMap30s定时器
triggerTicker触发式设备信息更新事件触发
ListenDpuDPU健康状态监控持续监听

三、子模块划分总览

在这里插入图片描述

3.1 模块总览

模块目录文件数核心职责
入口层main.go1进程入口、参数解析、12项校验、启动初始化
工厂层pkg/next/devicefactory/3驱动初始化、Manager创建、名称映射
拓扑层pkg/topology/2拓扑文件读写、Rack拓扑采集、文件哈希校验
gRPC服务层pkg/server/10gRPC服务、设备上报/分配、DPU监控、A5扩展
设备管理层pkg/device/7NPU设备发现/健康/故障/复位、vNPU管理
交换设备pkg/device/deviceswitch/1交换芯片故障监控(CGO)
DPU控制pkg/device/dpucontrol/2DPU发现与配置(UB/PCIe两种模式)
公共基础层pkg/common/13常量、工具、故障码、协议、文件管理
K8s客户端pkg/kubeclient/7K8s API交互、Informer、缓存、CRUD
重复检测pkg/duplicatedetector/6容器设备挂载重复检测(Docker/Containerd)

四、入口层模块 — main.go

4.1 核心作用

进程入口点,负责命令行参数解析、参数校验和初始化调度。不包含业务逻辑,只做 编排调度。

4.2 关键函数

函数行号作用
main()269入口函数:解析Flag → checkParam() → InitFunction() → ListenDevice()
initLogModule()111初始化日志模块(上下文+日志级别)
checkParam()134调用12项check函数,任一失败则终止启动
setParameters()303设置全局参数(设备类型、卷路径等)
setUseAscendDocker()326设置是否使用Ascend Docker运行时
checkListWatchPeriod()157校验ListAndWatch周期合法性
checkHotResetMode()218校验热复位模式配置
checkBuildScene()228校验构建场景(训练/推理)
checkShareDevCount()261校验共享设备数量

4.3 关键Flag

Flag说明
--useV2使用V2接口(A5架构)
--dmVol设备管理卷路径
--fdFlag文件描述符配置
--deviceType设备类型(Ascend910/310/310P)
--listWatchPeriodListAndWatch上报周期
--hotResetMode热复位模式
--presetEnable预置功能开关

五、工厂层模块 — DeviceFactory

在这里插入图片描述

5.1 核心作用

设备工厂层,负责根据设备类型创建对应的 Manager 实例,初始化硬件驱动,建立设备名称映射。

5.2 文件结构

文件职责
entry.go工厂入口,InitFunction() 调用链
driver_init.go驱动初始化,initDevManager() 创建Manager
customname/public_name_config.go设备名称映射(ResourceType→PublicName)

5.3 关键函数

函数文件作用
InitFunction()entry.go工厂入口,调用initDevManager创建Manager和SwitchDevManager
initDevManager()driver_init.goDCMI AutoInit → 按设备类型创建Manager → InitSwitchDev
InitPublicNameConfig()public_name_config.go加载名称映射配置文件
ReplaceDevicePublicName()public_name_config.go设备名称替换(原始→公共名称)
ReplaceDeviceInfoPublicName()public_name_config.go批量设备信息名称替换

5.4 名称映射机制

ResourceType (原始: Ascend910)
    ↓ InitPublicNameConfig()
OldPublicType (旧公共: Ascend910A)
    ↓ ReplaceDevicePublicName()
DevicePublicType (新公共: HuaweiNPU-910A)

支持自定义配置文件覆盖默认映射,用于K8s资源注册名和Pod注解。


六、gRPC服务层模块 — Server

在这里插入图片描述

6.1 核心作用

实现 Kubernetes Device Plugin gRPC 协议,向 kubelet 上报设备列表和健康状态,处理设备分配请求,查询Pod设备资源,监控DPU健康状态。

6.2 文件结构

文件职责
manager.goHwDevManager — 设备管理中枢,10步初始化
plugin.goPluginServer — gRPC接口实现 (ListAndWatch/Allocate)
server.goServer — gRPC服务器启动/注册/重启
pod_resource.goPodResource — Pod设备资源查询
dpu.goDPU健康状态监控
types.goPluginServer结构体定义
manager_v2.goA5架构扩展(RankTable/LevelList)
plugin_v2.goV2 gRPC接口(HCCL拓扑)
npu_base_v2.goA5 NPU基类
types_v2.goV2类型定义

6.3 关键结构体

结构体作用
HwDevManager设备管理中枢,协调Device/KubeClient/PluginServer等所有子模块
PluginServergRPC服务实现,实现InterfaceServer接口(ListAndWatch/Allocate)
PodResourcePod设备资源查询,对接kubelet Pod Resources API

6.4 关键函数

函数文件作用
NewHwDevManager()manager.go创建Manager实例,10步初始化流程
setAscendManager()manager.go按设备类型设置对应的Manager
ListenDevice()manager.go主循环,启动所有协程(Serve/故障订阅/ticker)
ListAndWatch()plugin.go:321gRPC:周期上报设备列表和健康状态到kubelet
Allocate()plugin.gogRPC:处理设备分配请求,挂载设备到容器
responseToKubelet()plugin.go:201构造ListAndWatch响应(设备列表+健康状态)
reportDeviceInfo()plugin.go:286上报设备信息(深拷贝→比对→更新)
handleConsecutiveErrorStrategy()plugin.go:300连续错误处理策略(重启/退出)
Notify()plugin.go:61设备状态变更通知(故障→不健康)
getNewNodeAnnotation()manager.go:239获取节点注解(设备信息)
getNewNodeLabel()manager.go:264获取节点标签(设备类型/数量)
addTopologyLabel()manager.go:311添加拓扑标签
updateChipNameToNode()manager.go:363更新芯片名称到节点
initPluginServer()manager.go:457初始化PluginServer
Serve()server.gogRPC服务器启动/注册/重启/停止

6.5 gRPC接口

接口方向说明
ListAndWatchPlugin → kubelet持续推送设备列表(Device数组+健康状态)
Allocatekubelet → Plugin请求分配设备,返回设备挂载信息(Mount)
GetDevicePluginOptionskubelet → Plugin返回插件选项

七、设备管理层模块 — Device

在这里插入图片描述

7.1 核心作用

NPU设备的底层管理——设备发现、健康状态、故障处理、热复位、虚拟设备(vNPU)管理。通过CGO调用DCMI驱动库操作硬件。

7.2 文件结构

文件职责
ascendcommon.goAscendTools基类 + DevManager接口
ascend910.goAscend910 Manager(训练NPU,功能最完整)
ascend310.goAscend310 Manager(推理NPU,简化版)
ascend310p.goAscend310P Manager(推理NPU,4种模式)
ascendtolerance.go优雅容错管理(故障分级处理)
reset_info_mgr.go重置信息管理器(单例模式)
ascendcommon_v2.goA5架构扩展属性
deviceswitch/ascend_switch.go交换设备故障监控(CGO)
dpucontrol/dpu_device_find.goDPU发现与配置
dpucontrol/types.goDPU类型定义

7.3 继承体系

DevManager (接口)
    ↑ 实现
AscendTools (基类) — 提供GetNPUs/UpdateNodeDeviceInfo等通用方法
    ↑ 继承
    ├── HwAscend910Manager   (训练卡: 故障订阅/热复位/Ring重置/优雅容错)
    ├── HwAscend310Manager   (推理卡: 简化版设备发现)
    └── HwAscend310PManager  (推理卡: 混插/虚拟/共享/物理4种模式)

7.4 关键函数

函数所属作用
GetNPUs()Ascend910设备发现:扫描/dev/davinci*设备,返回NpuAllInfo
GraceTolerance()Ascend910优雅容错6步流程:分类设备→故障分级→热复位
hotResetHandler()Ascend910热复位处理(带内/带外两种模式)
hotResetTryOutBand()Ascend910带外热复位执行
startUpHotReset()Ascend910启动热复位流程
setAllDevUnhealthyOnRing()Ascend910Ring上所有设备设为不健康
getDevFaultInfo()Ascend910获取设备故障信息
isFaultNeedRestart()Ascend910判断故障是否需要重启
GetAssociatedLogicIDs()Ascend910获取关联设备逻辑ID(Ring拓扑)
SetDmgr()AscendTools设置设备管理器
GetChipAICore()AscendTools获取芯片AI Core数量
convertLogicIDsToDeviceNames()AscendTools逻辑ID转设备名称
UpdateNodeDeviceInfo()AscendTools更新设备信息到ConfigMap
LoadDeviceInfoCm()AscendTools加载设备信息ConfigMap
handleManuallySeparateNPUFaultInfo()AscendTools处理手动分离NPU故障信息
asyncReleaseAutoFill()AscendTools异步释放自动填充
checkAndInitNodeDeviceInfo()AscendTools检查并初始化节点设备信息

7.5 故障处理流程

DCMI驱动 → goFaultEventHandler (CGO回调)
    ↓
故障事件 → allFaultInfo channel
    ↓
限流器 (rate limiter)
    ↓
故障分级:
  L1 (警告)   → 记录日志,设备保持健康
  L2 (降级)   → 设备标记为不健康
  L3 (隔离)   → 设备隔离 + K8s Event通知
  L5 (重置)   → 触发热复位 (带内/带外)
    ↓
K8s Event 通知 + ConfigMap 更新 + ListAndWatch状态更新

八、公共基础层模块 — Common

在这里插入图片描述

8.1 核心作用

全局常量、工具函数、故障码定义、协议定义——被几乎所有其他模块引用的"单一真相源"。

8.2 文件结构

文件职责
constants.go全局常量(设备类型/路径/端口/限制等)
constants_v2.goA5架构常量
common.go公共工具函数(序列化/锁/哈希等)
device.go设备工具函数(设备ID解析/交换故障/默认设备路径)
fault_code.go故障码定义与级别映射
proto.go协议定义
proto_v2.goA5协议定义
send_stat.go状态上报
file_manager.go文件管理
atomic_bool.go原子布尔值
slice_common.go切片工具
upgradefault.go升级容错

8.3 关键函数

函数文件作用
GetPattern()common.go:72获取正则表达式模式映射
LockAllDeviceInfo()common.go:81锁定所有设备信息(互斥)
UnlockAllDeviceInfo()common.go:86解锁设备信息
SetAscendRuntimeEnv()common.go:91设置Ascend运行时环境变量
MakeDataHash()common.go:131生成数据哈希
MarshalData()common.go:146序列化数据
MapDeepCopy()common.go:156Map深拷贝
GetPodAnnotationByDeviceType()common.go:168按设备类型获取Pod注解
GetDeviceFromPodAnnotation()common.go:184从Pod注解获取设备
GetDefaultDevices()common.go:212获取默认设备列表
GetDeviceID()device.go:78解析设备ID
GetSwitchFaultInfo()device.go:112获取交换设备故障信息
UpdateSwitchFaultInfoAndFaultLevel()device.go:157更新交换设备故障级别
SetSwitchFaultCode()device.go:282设置交换设备故障码

九、K8s客户端模块 — KubeClient

在这里插入图片描述

9.1 核心作用

封装 Kubernetes API 交互——节点标签/注解管理、ConfigMap CRUD、Pod查询、节点Informer、容器运行时检测。

9.2 文件结构

文件职责
kubeclient.goClientK8s核心客户端
kube_connect.goK8s连接管理(配置加载/创建Clientset)
kube_cache.go缓存层(ConfigMap/Pod缓存)
cur_node_informer.go当前节点Informer(监听Pod事件)
client_server.goCRUD操作(ConfigMap/Node Annotation)
kubeclient_v2.goA5扩展(PingMesh配置解析)
types.go / types_v2.go类型定义

9.3 关键函数

函数行号作用
NewClientK8s()68创建K8s客户端(从环境变量/in-cluster配置加载)
GetNode()105获取当前节点信息
PatchNodeState()112Patch节点状态(标签/注解)
AddAnnotation()122添加节点注解
GetPod()147获取单个Pod
PatchPod()163Patch Pod
GetActivePodList()169获取活跃Pod列表(字段选择器+校验)
GetAllPodList()183获取全部Pod列表
getPodListByCondition()198按条件获取Pod列表
GetContainerRuntime()211获取容器运行时类型(Docker/Containerd)
CreateConfigMap()255创建ConfigMap
GetConfigMap()270获取ConfigMap
UpdateConfigMap()282更新ConfigMap
resetNodeAnnotations()295重置节点注解

十、重复设备检测模块 — DuplicateDetector

在这里插入图片描述

10.1 核心作用

检测同一NPU设备被多个容器重复挂载的异常情况,支持Docker和Containerd两种容器运行时。

10.2 文件结构

文件职责
manager.goManager — 检测管理器(启动/扫描/事件监听)
cache/container_cache.goContainerCache — 容器缓存 + 重复检测算法
containerruntime/interface.goClient接口 + OCI端点探测
containerruntime/docker_client.goDocker客户端实现
containerruntime/containerd_client.goContainerd客户端实现
types/types.go数据类型定义

10.3 关键函数

函数行号作用
CheckDuplicateDevices()39入口函数,创建Manager并启动检测
NewManager()62创建检测管理器(初始化缓存+运行时客户端)
Start()79启动检测:全量扫描 + 事件监听
watchContainerEvents()98监听容器创建/销毁事件
scanAllContainers()115全量扫描所有容器设备挂载
HandleNewContainer()131处理新容器:解析设备挂载 + 检测重复
HandleContainerRemoval()165处理容器销毁:清理缓存
logDuplicate()170记录重复检测告警日志

10.4 检测流程

1. CheckDuplicateDevices() 入口
   ↓
2. NewManager() → NewContainerCache() → NewClient()
   ↓
3. Start()
   ├── scanAllContainers() (全量扫描)
   │   ├── 解析所有容器设备挂载信息
   │   ├── StoreAllAndFindDuplicates() (批量存储+检测)
   │   └── logDuplicate() (告警)
   └── watchContainerEvents() (增量监听)
       ├── HandleNewContainer() (容器创建 → 解析+检测)
       └── HandleContainerRemoval() (容器销毁 → 清理缓存)

十一、拓扑模块 — Topology

11.1 核心作用

管理拓扑文件的读写、Rack拓扑信息采集,支持文件哈希校验确保数据完整性。

11.2 文件结构

文件职责
topo.go拓扑文件读写、哈希校验
types.go拓扑数据类型定义

11.3 关键函数

函数行号作用
topoFileToStr()53读取拓扑文件内容为字符串
getFileHash()66计算文件SHA256哈希(完整性校验)
ToFile()75将拓扑信息写入文件

十二、模块间调用关系与数据流

在这里插入图片描述

12.1 主调用链

main.go
  → DeviceFactory.InitFunction()
    → DeviceFactory.initDevManager()
      → DCMI AutoInit() (CGO驱动初始化)
      → NewHwAscend910/310/310PManager()
      → InitSwitchDev()
      → NewHwDevManager()
        → setAscendManager() (按类型设置Manager)
        → setAllDeviceAndType()
        → initPluginServer()
        → ListenDevice()
          ├── Serve() → gRPC Server
          │   ├── ListAndWatch() → Device.GetNPUs() → DCMI
          │   └── Allocate() → Device设备挂载 → 容器
          ├── subscribeNpuFaultEvent() → DCMI故障回调
          ├── pollFaultCodeCM() → KubeClient.GetConfigMap()
          └── ticker → reportDeviceInfo()
              → Device.UpdateNodeDeviceInfo()
              → KubeClient.UpdateConfigMap()

12.2 数据传递矩阵

数据来源去向载体
Flag配置命令行main.go → DeviceFactoryflag.* 指针
Manager实例DeviceFactoryServer层HwDevManager 结构体
设备列表DCMI驱动Server → kubeletgRPC ListAndWatchResponse
设备分配kubeletDevice层 → 容器gRPC AllocateResponse (Mount)
故障事件DCMI回调Server → K8s EventallFaultInfo channel
设备信息Device层KubeClient → K8sConfigMap
节点标签ServerKubeClient → K8sNode Annotation/Label
容器信息Docker/ContainerdDuplicateDetectorContainer API
拓扑信息TopologyServer → K8sNode Label (topology)

12.3 核心数据流

┌──────────┐     gRPC      ┌──────────────┐
│ kubelet  │ ─────────────→ │ PluginServer │
│          │ ←───────────── │              │
└──────────┘  ListAndWatch  └──────┬───────┘
                                   │
                          GetNPUs()│
                                   ↓
                           ┌──────────────┐
                           │   Device层   │
                           │  (910/310/   │
                           │   310P)      │
                           └──────┬───────┘
                                   │
                             CGO  │
                                   ↓
                           ┌──────────────┐
                           │  DCMI 驱动库  │
                           │ (libdcmi.so) │
                           └──────────────┘

┌──────────┐  ConfigMap   ┌──────────────┐
│ K8s API  │ ←─────────── │ KubeClient   │
│ Server   │ ───────────→ │              │
└──────────┘  Get/Patch   └──────┬───────┘
                                  │
                                   ↑
                           ┌──────────────┐
                           │ PluginServer │ → ticker定时更新
                           └──────────────┘

十三、图表索引

编号图表名称文件类型
a01系统整体架构图diagrams/a01_system_architecture.png架构图
a02模块划分与依赖关系图diagrams/a02_module_dependency.png架构图
a03main.go 启动流程图diagrams/a03_main_startup_flow.png流程图
a04Server 模块架构图diagrams/a04_server_module.png架构图
a05Device 模块架构图diagrams/a05_device_module.png架构图
a06Common 模块架构图diagrams/a06_common_module.png架构图
a07KubeClient 模块架构图diagrams/a07_kubeclient_module.png架构图
a08DuplicateDetector 模块架构图diagrams/a08_duplicatedetector_module.png架构图
a09DeviceFactory 模块架构图diagrams/a09_devicefactory_module.png架构图
a10模块间数据流图diagrams/a10_data_flow.png数据流图
Logo

鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者,聚合华为+生态”的社区,内容涵盖鲲鹏、昇腾资源,帮助开发者快速获取所需的知识、经验、软件、工具、算力,支撑开发者易学、好用、成功,成为核心开发者。

更多推荐