【NVIDIA】NVIDIA k8s-device-plugin v0.19.3 系统级架构分析

NVIDIA k8s-device-plugin v0.19.3 系统级架构分析

分析对象: github.com/k8s-device-plugin-0.19.3
代码语言: Go (116个非vendor Go文件)
分析日期: 2026-07-25

目录

1. 项目整体架构
2. 整体设计思路
3. 整体运行流程
4. 子模块/功能模块划分
5. 模块调用关系
6. 主流程详解

1. 项目整体架构

1.1 项目定位

NVIDIA k8s-device-plugin 是 NVIDIA 官方开发的 Kubernetes 设备插件，用于将 NVIDIA GPU 资源暴露给 Kubernetes 集群中的容器化工作负载。它实现了 Kubernetes Device Plugin API（gRPC），与 Kubelet 交互，完成 GPU 设备的发现、分配和健康监控。

1.2 架构分层

项目采用五层架构设计，自上而下分别为：

1.3 关键设计特征

• 多入口单仓库：4个独立的main()入口共享同一套 internal 包
• 策略模式：设备发现支持auto/nvml/tegra三种策略，运行时自动选择
• 工厂模式：plugin.New()、resource.NewManager()、cdi.New()均采用函数式选项工厂
• 接口驱动：ResourceManager、Manager、Device、Interface、Labeler等核心抽象均为接口
• 功能选项模式：广泛使用WithXxx()风格的 Functional Options
• 回退机制：FallbackToNullOnInitError提供 Init 失败时的 Null 回退

2. 整体设计思路

2.1 核心设计原则

1. Kubernetes Device Plugin Protocol 优先
   所有设计围绕 Kubernetes Device Plugin gRPC API 展开，实现ListAndWatch、Allocate、GetPreferredAllocation、PreStartContainer四个核心RPC。

2. 多平台兼容
   通过info.ResolvePlatform()自动检测运行平台（NVML/WSL/Tegra），选择对应的设备发现策略和资源管理器实现。

3. 设备共享支持
   支持两种GPU共享策略：

   • Time-Slicing：时间片共享，通过Replicas创建带注释的设备ID
   • MPS (Multi-Process Service)：通过MPS控制守护进程实现真正的GPU共享

4. CDI (Container Device Interface) 集成
   支持cdi-annotations和cdi-cri两种设备列表策略，通过 nvidia-container-toolkit 生成CDI规格文件。

5. 配置统一管理
   单一Config结构体覆盖所有配置项，支持 YAML 文件、CLI 标志、环境变量三种配置来源，优先级：CLI > 环境变量 > 配置文件。

2.2 数据模型

Config ├── Flags (CommandLineFlags) │ ├── MigStrategy: none | single | mixed │ ├── DeviceDiscoveryStrategy: auto | nvml | tegra │ ├── Plugin (PluginCommandLineFlags) │ │ ├── DeviceListStrategy: envvar | volume-mounts | cdi-annotations | cdi-cri │ │ └── DeviceIDStrategy: uuid | index │ └── GFD (GFDCommandLineFlags) ├── Resources (GPUs + MIGs, Pattern → Name 映射) ├── Sharing (TimeSlicing + MPS, ReplicatedResources) └── Imex (ChannelIDs + Required)

3. 整体运行流程

3.1 nvidia-device-plugin 启动流程

main() ├── CLI 解析 (urfave/cli/v2) ├── watch.Files(kubeletSocketDir) // 监控kubelet socket目录 ├── watch.Signals(SIGHUP, SIGINT, ...) // 监控OS信号 └── start() 事件循环 └── startPlugins() ├── loadConfig() // 加载配置 ├── spec.DisableResourceNamingInConfig() ├── validateFlags() // 验证标志 ├── rm.AddDefaultResourcesToConfig() // 添加默认资源 ├── GetPlugins() // 获取插件集合 │ ├── imex.GetChannels() // 获取IMEX通道 │ ├── resolveStrategy() // 解析发现策略 │ ├── cdi.New() // 创建CDI处理器 │ ├── plugin.New() // 创建插件实例 │ └── cdiHandler.CreateSpecFile() // 生成CDI规格文件 └── 遍历插件 → p.Start(kubeletSocket) ├── Serve() // 启动gRPC服务 ├── Register() // 注册到Kubelet └── go rm.CheckHealth() // 启动健康检查

3.2 运行时事件循环

select { case <-restartTimeout: → goto restart // 重启插件 case event := <-watcher.Events: // kubelet socket重建 → goto restart case err := <-watcher.Errors: // 文件系统错误 → log case s := <-sigs: // OS信号 SIGHUP → goto restart 其他 → goto exit }

3.3 gpu-feature-discovery 启动流程

main() ├── CLI 解析 └── start() 循环 ├── loadConfig() ├── resource.NewManager() // 创建资源管理器 ├── vgpu.NewVGPULib() // 创建vGPU库 ├── lm.NewOutputer() // 创建标签输出器 └── gfd.run() ├── lm.NewLabelers() // 构建标签器链 ├── labelers.Labels() // 生成标签 ├── labelOutputer.Output() // 输出标签 └── 等待 sleepInterval 或信号

4. 子模块/功能模块划分

4.1 入口模块 (cmd/)

核心作用: 提供4个独立的可执行程序入口，各自负责CLI解析、配置加载和生命周期管理。

4.2 Plugin 模块 (internal/plugin/)

核心作用: 实现Kubernetes Device Plugin gRPC接口，管理设备列表、分配和健康监控。

关键类型与函数:

4.3 Resource Manager 模块 (internal/rm/)

核心作用: 管理GPU/MIG设备的枚举、分配算法、健康检查和副本管理。

关键类型与函数:

4.4 Resource 设备抽象模块 (internal/resource/)

核心作用: 提供统一的设备管理接口，封装 NVML、CUDA、VFIO 三种设备后端。

关键类型与函数:

4.5 CDI 模块 (internal/cdi/)

核心作用: 生成 Container Device Interface (CDI) 规格文件，支持容器运行时自动注入GPU设备。

关键类型与函数:

4.6 Label Manager 模块 (internal/lm/)

核心作用: 为GPU Feature Discovery (GFD) 生成节点标签，包括驱动版本、CUDA版本、MIG能力、共享策略等。

关键类型与函数:

4.7 Config 模块 (api/config/v1/)

核心作用: 统一配置管理，覆盖CLI标志、资源模式、共享策略、IMEX通道。

关键类型与函数:

4.8 MPS Control Daemon 模块 (cmd/mps-control-daemon/)

核心作用: 管理NVIDIA MPS (Multi-Process Service) 守护进程，实现GPU共享。

关键类型与函数:

4.9 辅助模块

5. 模块调用关系

5.1 模块间依赖关系矩阵

main plugin rm cdi resource config lm mig vgpu imex watch cuda flags info main (ndp) - ✓ ✓ . . ✓ . . . ✓ ✓ . ✓ ✓ main (gfd) - . . . ✓ ✓ ✓ . ✓ . ✓ . ✓ ✓ main (mps) - . ✓ . . ✓ . . . . ✓ . . ✓ main (config-mgr) - . . . . . . . . . . . . ✓ plugin . - ✓ ✓ . ✓ . . . ✓ . . . . rm . . - . ✓ ✓ . ✓ . . . . . . cdi . . . - . . . . . ✓ . . . . resource . . . - - . . . . . . ✓ . . lm . . ✓ . ✓ ✓ - . ✓ . . . ✓ .

5.2 数据流向

5.2.1 设备发现数据流

config.Config (Resources/Flags) ↓ rm.NewNVMLResourceManagers() / NewTegraResourceManagers() ↓ NewDeviceMap(devicelib, config, platform) ↓ (VisitDevices / VisitMigDevices) deviceMapBuilder.buildGPUDeviceMap() / buildMigDeviceMap() ↓ (Pattern matching: ResourcePattern.Matches(name)) DeviceMap (ResourceName → Devices) ↓ (updateDeviceMapWithReplicas - if sharing enabled) DeviceMap with replicated AnnotatedIDs ↓ resourceManager{config, resource, devices} ↓ nvidiaDevicePlugin{rm: resourceManager}

5.2.2 设备分配数据流

Kubelet → Allocate(request) ↓ 遍历 ContainerRequests ↓ rm.ValidateRequest(AnnotatedIDs) ↓ uniqueDeviceIDsFromAnnotatedDeviceIDs() ↓ (根据 DeviceListStrategies) ├── CDI: cdiHandler.QualifiedName() → annotations/cdiDevices ├── EnvVar: NVIDIA_VISIBLE_DEVICES = "uuid1,uuid2" ├── VolumeMounts: /var/run/nvidia-container-devices/<id> └── DeviceSpecs: /dev/nvidia* (if PassDeviceSpecs) ↓ ContainerAllocateResponse ↓ Kubelet → 容器运行时

5.2.3 标签生成数据流 (GFD)

config.Config ↓ resource.NewManager(infolib, nvmllib, devicelib, config) ↓ resource.Manager → manager.GetDevices() → []Device ↓ lm.NewLabelers(manager, vgpu, config) ├── newVersionLabeler() → nvidia.com/cuda.driver-version.* ├── newMigCapabilityLabeler() → nvidia.com/mig.capable ├── newSharingLabeler() → nvidia.com/mps.* ├── NewResourceLabeler() → nvidia.com/gpu.count, nvidia.com/gpu.memory.* ├── NewVGPULabeler() → nvidia.com/vgpu.* └── migStrategyLabeler() → nvidia.com/mig.strategy ↓ lm.Merge(labelers...).Labels() ↓ lm.Outputer.Output(labels) ├── ToFile: /etc/kubernetes/node-feature-discovery/features.d/gfd └── NodeFeature CR: NFD API

5.3 健康检查数据流

rm.CheckHealth(stop, unhealthy) ↓ (nvmlResourceManager.checkHealth) nvml.EventSetCreate() ↓ 遍历设备 → gpu.RegisterEvents(XidCriticalError | ECC errors, eventSet) ↓ eventSet.Wait(5000ms) 循环 ↓ XID事件 → 匹配 parentToDeviceMap → 标记 Unhealthy ↓ plugin.health channel → ListAndWatch.Send() → Kubelet

6. 主流程详解

6.1 Allocate 完整流程

Allocate()是设备插件最核心的RPC，当Kubelet调度GPU Pod时调用。

// 1. Kubelet调用 Allocate(AllocateRequest)func(plugin*nvidiaDevicePlugin)Allocate(ctx,reqs)(*AllocateResponse,error){for_,req:=rangereqs.ContainerRequests{// 2. 验证请求plugin.rm.ValidateRequest(req.DevicesIds)// 3. 构建分配响应response:=plugin.getAllocateResponse(req.DevicesIds)// 4. 根据策略填充响应// 4a. CDI策略 → annotations 或 cdiDevices// 4b. EnvVar策略 → NVIDIA_VISIBLE_DEVICES// 4c. VolumeMounts策略 → /var/run/nvidia-container-devices// 4d. PassDeviceSpecs → /dev/nvidia* 设备节点// 5. MPS额外处理// → CUDA_MPS_PIPE_DIRECTORY, pipe/shm mounts// 6. IMEX通道注入// → NVIDIA_IMEX_CHANNEL_IDS env var// 7. 可选功能// → NVIDIA_GDRCOPY, NVIDIA_GDS, NVIDIA_MOFED env vars}return&responses}

6.2 设备发现策略选择

resolveStrategy("auto", infolib): infolib.ResolvePlatform() ├── PlatformNVML → "nvml" ├── PlatformWSL → "nvml" (WSL用同一策略) └── PlatformTegra → "tegra"

6.3 资源管理器创建

plugin.New(ctx, infolib, nvmllib, devicelib, opts...) ↓ o.getResourceManagers() ├── strategy == "nvml": │ nvmllib.Init() │ NewNVMLResourceManagers(infolib, nvmllib, devicelib, config) │ ├── NewDeviceMap(devicelib, config, platform) │ │ ├── buildGPUDeviceMap() → VisitDevices → Pattern match │ │ └── buildMigDeviceMap() → VisitMigDevices → Pattern match │ └── 遍历 DeviceMap → 创建 nvmlResourceManager │ └── strategy == "tegra": NewTegraResourceManagers(config) ├── buildTegraDeviceMap(config) └── 遍历 → 创建 resourceManager

6.4 MIG 策略处理

6.5 设备共享（Time-Slicing）

config.Sharing.TimeSlicing: Resources: [{Name: "nvidia.com/gpu", Replicas: 4}] ↓ updateDeviceMapWithReplicas() ↓ 原始设备 UUID → 4个带注释的ID: UUID::0, UUID::1, UUID::2, UUID::3 ↓ Kubelet看到4倍数量的设备 ↓ ValidateRequest: 共享资源最多请求1个 ↓ distributedAlloc: 均衡分配副本

6.6 MPS 共享

config.Sharing.MPS: Resources: [{Name: "nvidia.com/gpu", Replicas: 4}] ↓ mps-control-daemon 启动 ↓ Daemon.Start(): nvidia-smi -c EXCLUSIVE_PROCESS (设置独占进程模式) nvidia-cuda-mps-control -d (启动MPS守护) set_default_device_pinned_mem_limit (设置内存限制) set_default_active_thread_percentage (设置线程百分比) ↓ plugin.Allocate(): response.Envs["CUDA_MPS_PIPE_DIRECTORY"] = pipeDir response.Mounts: pipe目录 + shm目录

附录

A. 文件统计

B. 关键外部依赖

C. 架构图索引