揭秘云原生混布资源调度器Koordinator （十五）GPU 信息采集与上报机制

一、核心使命与设计理念

1.1 GPU 信息采集的使命

在 Koordinator GPU 调度体系中,Koordlet 承担着关键的数据采集角色。它负责从节点上获取 GPU 设备信息并上报到 Kubernetes APIServer,为调度器提供决策依据。

┌────────────────────────────────────────────────────────┐
│        为什么需要独立的 GPU 信息采集组件?               │
├────────────────────────────────────────────────────────┤
│  1. 设备发现问题                                        │
│     └─ 需要在调度前就知道节点有哪些 GPU                 │
│     └─ 需要知道每张 GPU 的详细规格(显存、型号)          │
│                                                         │
│  2. 动态变化问题                                        │
│     └─ GPU 可能热插拔(云环境中常见)                     │
│     └─ GPU 可能故障变为不健康状态                       │
│     └─ GPU 驱动版本可能升级                             │
│                                                         │
│  3. 调度器感知问题                                      │
│     └─ Scheduler 无法直接访问节点硬件                   │
│     └─ 需要通过 CRD 暴露设备信息                        │
│                                                         │
│  4. 多集群统一管理                                      │
│     └─ 不同节点的 GPU 型号不同                          │
│     └─ 需要统一的数据模型描述所有设备                    │
└────────────────────────────────────────────────────────┘

Koordlet GPU 信息采集的三大职责:

1. 设备发现: 通过 NVML 库自动发现节点上的所有 GPU
2. 信息采集: 采集 GPU 的 UUID、Minor、显存、型号等关键信息
3. 状态上报: 将 GPU 信息封装为 Device CRD 上报到 APIServer

1.2 核心设计理念（How）

Koordlet 采用 周期性采集 + 事件驱动更新 的混合模式:

┌──────────────────────────────────────────────────────────┐
│           Koordlet GPU 信息采集架构                       │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌─────────────────────────────────────────────┐        │
│  │  1. 初始化阶段 (启动时执行一次)              │        │
│  │     - 加载 NVML 库 (libnvidia-ml.so)         │        │
│  │     - 初始化 NVML: nvml.Init()               │        │
│  │     - 检测 GPU 驱动是否正常                  │        │
│  └─────────────────────────────────────────────┘        │
│                      ↓                                    │
│  ┌─────────────────────────────────────────────┐        │
│  │  2. 周期性采集 (每 60 秒)                   │        │
│  │     - 获取 GPU 设备列表                      │        │
│  │     - 采集每张 GPU 的详细信息                │        │
│  │     - 构建 Device CRD 对象                   │        │
│  │     - 对比是否有变化                         │        │
│  └─────────────────────────────────────────────┘        │
│                      ↓                                    │
│  ┌─────────────────────────────────────────────┐        │
│  │  3. 健康检测 (实时监控)                     │        │
│  │     - 监听 GPU 错误事件                      │        │
│  │     - 标记不健康的 GPU                       │        │
│  │     - 触发立即上报                           │        │
│  └─────────────────────────────────────────────┘        │
│                      ↓                                    │
│  ┌─────────────────────────────────────────────┐        │
│  │  4. 上报到 APIServer                         │        │
│  │     - 首次: Create Device CRD                │        │
│  │     - 后续: Update Device CRD (带版本控制)   │        │
│  │     - 更新节点 Label (GPU 型号和驱动版本)    │        │
│  └─────────────────────────────────────────────┘        │
│                                                           │
└──────────────────────────────────────────────────────────┘

核心设计原则:

1. 容错性: NVML 库加载失败时不影响 Koordlet 启动
2. 增量更新: 只有设备信息变化时才更新 Device CRD
3. 最小化网络开销: 对比变化后再决定是否上报
4. 版本控制: 使用乐观锁避免并发冲突

---

二、NVML 库详解

2.1 NVML 简介

NVML (NVIDIA Management Library) 是 NVIDIA 提供的 C 语言库,用于监控和管理 GPU 设备。

NVML 核心能力:

功能分类	API 示例	说明
初始化	nvml.Init()	初始化 NVML 库
设备枚举	nvml.DeviceGetCount()	获取 GPU 数量
	nvml.DeviceGetHandleByIndex(i)	获取第 i 张 GPU 的句柄
设备信息	nvml.DeviceGetUUID()	获取 GPU UUID
	nvml.DeviceGetMinorNumber()	获取 Minor 设备号
	nvml.DeviceGetName()	获取 GPU 型号
	nvml.DeviceGetMemoryInfo()	获取显存信息
系统信息	nvml.SystemGetDriverVersion()	获取驱动版本
运行时监控	nvml.DeviceGetUtilizationRates()	获取 GPU 利用率
	nvml.DeviceGetTemperature()	获取 GPU 温度
	nvml.DeviceGetPowerUsage()	获取功耗

NVML 在 Koordinator 中的应用:

// pkg/koordlet/statesinformer/states_device_linux.go

// 1. 初始化 NVML
func (s *statesInformer) initGPU() bool {
    if ret := nvml.Init(); ret != nvml.SUCCESS {
        if ret == nvml.ERROR_LIBRARY_NOT_FOUND {
            klog.Warning("nvml init failed, library not found")
            return false
        }
        klog.Warningf("nvml init failed, return %s", nvml.ErrorString(ret))
        return false
    }
    return true
}

// 2. 获取 GPU 驱动信息
func getGPUDriverAndModel() (string, string) {
    // 获取 GPU 型号
    count, ret := nvml.DeviceGetCount()
    if ret != nvml.SUCCESS || count == 0 {
        return "", ""
    }
    
    device, ret := nvml.DeviceGetHandleByIndex(0)
    if ret != nvml.SUCCESS {
        return "", ""
    }
    
    gpuModel, ret := nvml.DeviceGetName(device)
    if ret != nvml.SUCCESS {
        gpuModel = ""
    }
    
    // 获取驱动版本
    gpuDriverVer, ret := nvml.SystemGetDriverVersion()
    if ret != nvml.SUCCESS {
        gpuDriverVer = ""
    }
    
    return gpuModel, gpuDriverVer
}

2.2 NVML 库加载流程

┌────────────────────────────────────────────────────────┐
│           NVML 库加载流程                               │
├────────────────────────────────────────────────────────┤
│                                                         │
│  1. 查找动态库                                          │
│     Linux:   /usr/lib64/libnvidia-ml.so                │
│     Windows: nvml.dll                                  │
│                                                         │
│  2. 加载动态库                                          │
│     dlopen("/usr/lib64/libnvidia-ml.so", RTLD_NOW)     │
│                                                         │
│  3. 解析函数符号                                        │
│     dlsym(handle, "nvmlInit_v2")                       │
│     dlsym(handle, "nvmlDeviceGetCount_v2")             │
│     ...                                                 │
│                                                         │
│  4. 初始化 NVML                                         │
│     nvmlInit_v2()                                       │
│       └─ 连接 NVIDIA 驱动                               │
│       └─ 初始化内部数据结构                             │
│                                                         │
│  5. 验证初始化结果                                      │
│     if ret != NVML_SUCCESS:                            │
│         处理错误情况                                    │
│                                                         │
└────────────────────────────────────────────────────────┘

错误处理机制:

func (s *statesInformer) initGPU() bool {
    ret := nvml.Init()
    
    switch ret {
    case nvml.SUCCESS:
        return true
        
    case nvml.ERROR_LIBRARY_NOT_FOUND:
        // libnvidia-ml.so 不存在
        klog.Warning("nvml library not found, skip GPU detection")
        return false
        
    case nvml.ERROR_DRIVER_NOT_LOADED:
        // NVIDIA 驱动未加载
        klog.Warning("nvidia driver not loaded, skip GPU detection")
        return false
        
    case nvml.ERROR_NO_PERMISSION:
        // 没有权限访问 GPU
        klog.Error("no permission to access GPU, check container capabilities")
        return false
        
    default:
        // 其他未知错误
        klog.Warningf("nvml init failed with code %d: %s", ret, nvml.ErrorString(ret))
        return false
    }
}

生产环境配置:

# Koordlet DaemonSet 配置
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: koordlet
spec:
  template:
    spec:
      hostNetwork: true
      hostPID: true
      containers:
      - name: koordlet
        image: koordlet:latest
        
        # 关键配置 1: 挂载 NVIDIA 库
        volumeMounts:
        - name: nvidia-lib
          mountPath: /usr/lib64
          readOnly: true
        - name: nvidia-dev
          mountPath: /dev
          readOnly: true
        
        # 关键配置 2: 容器权限
        securityContext:
          privileged: true  # 需要访问 /dev/nvidia*
          
      volumes:
      - name: nvidia-lib
        hostPath:
          path: /usr/lib64
      - name: nvidia-dev
        hostPath:
          path: /dev

---

三、GPU 信息采集实现

3.1 MetricCache 集成

Koordlet 通过 MetricCache 缓存 GPU 信息:

// pkg/koordlet/metriccache/metric_cache.go

// GPU 指标数据结构
type GPUMetric struct {
    DeviceUUID  string             // GPU-abcd1234-5678-...
    Minor       int32              // 0, 1, 2, ...
    SMUtilization    int32         // SM (Streaming Multiprocessor) 利用率
    MemoryTotal resource.Quantity  // 总显存 (16Gi)
    MemoryUsed  resource.Quantity  // 已用显存
    Temperature uint32             // 温度 (摄氏度)
    PowerUsage  uint32             // 功耗 (瓦特)
}

// 节点资源指标
type NodeResourceMetric struct {
    CPUUsed    resource.Quantity
    MemoryUsed resource.Quantity
    GPUs       []GPUMetric        // GPU 列表
    Error      error
}

// 查询 GPU 指标
func (c *metricCache) GetNodeResourceMetric(param *QueryParam) NodeResourceQueryResult {
    c.lock.RLock()
    defer c.lock.RUnlock()
    
    // 从时间序列数据库中查询最新的节点指标
    result := NodeResourceQueryResult{}
    
    // 聚合 GPU 指标
    result.Metric.GPUs = c.aggregateGPUMetrics(param)
    
    return result
}

3.2 GPU 设备信息构建

StatesInformer 调用 MetricCache 获取 GPU 信息并构建 DeviceInfo:

// pkg/koordlet/statesinformer/states_device_linux.go

func (s *statesInformer) buildGPUDevice() []schedulingv1alpha1.DeviceInfo {
    // 1. 从 MetricCache 获取 GPU 指标
    queryParam := generateQueryParam()
    nodeResource := s.metricsCache.GetNodeResourceMetric(queryParam)
    
    if nodeResource.Error != nil {
        klog.Errorf("failed to get node resource metric, err: %v", nodeResource.Error)
        return nil
    }
    
    if len(nodeResource.Metric.GPUs) == 0 {
        klog.V(5).Info("no gpu device found")
        return nil
    }
    
    // 2. 构建 DeviceInfo 列表
    var deviceInfos []schedulingv1alpha1.DeviceInfo
    for i := range nodeResource.Metric.GPUs {
        gpu := nodeResource.Metric.GPUs[i]
        
        // 检查 GPU 健康状态
        health := true
        s.gpuMutex.RLock()
        if _, ok := s.unhealthyGPU[gpu.DeviceUUID]; ok {
            health = false
        }
        s.gpuMutex.RUnlock()
        
        // 构建单个 GPU 的 DeviceInfo
        deviceInfos = append(deviceInfos, schedulingv1alpha1.DeviceInfo{
            UUID:   gpu.DeviceUUID,
            Minor:  &gpu.Minor,
            Type:   schedulingv1alpha1.GPU,
            Health: health,
            Resources: map[corev1.ResourceName]resource.Quantity{
                extension.ResourceGPUCore:        *resource.NewQuantity(100, resource.DecimalSI),
                extension.ResourceGPUMemory:      gpu.MemoryTotal,
                extension.ResourceGPUMemoryRatio: *resource.NewQuantity(100, resource.DecimalSI),
            },
        })
    }
    
    return deviceInfos
}

关键设计点:

1. GPU Core 固定为 100: 表示 100% 的 GPU 算力,简化资源计算
2. GPU Memory 使用实际值: 例如 16Gi、32Gi,便于精确分配
3. GPU Memory Ratio 固定为 100: 与 GPU Core 保持一致,表示 100% 显存
4. Health 字段: 标记 GPU 是否可用,不健康的 GPU 不会被调度

3.3 GPU 健康检测

Koordlet 维护了一个不健康 GPU 的黑名单:

// pkg/koordlet/statesinformer/states_informer.go

type statesInformer struct {
    // GPU 健康状态
    gpuMutex     sync.RWMutex
    unhealthyGPU map[string]struct{}  // key: GPU UUID
    
    // 其他字段...
}

// 标记 GPU 为不健康
func (s *statesInformer) markGPUUnhealthy(uuid string) {
    s.gpuMutex.Lock()
    defer s.gpuMutex.Unlock()
    
    if s.unhealthyGPU == nil {
        s.unhealthyGPU = make(map[string]struct{})
    }
    s.unhealthyGPU[uuid] = struct{}{}
    
    klog.Warningf("GPU %s marked as unhealthy", uuid)
}

// 标记 GPU 为健康
func (s *statesInformer) markGPUHealthy(uuid string) {
    s.gpuMutex.Lock()
    defer s.gpuMutex.Unlock()
    
    delete(s.unhealthyGPU, uuid)
    klog.Infof("GPU %s marked as healthy", uuid)
}

// 检查 GPU 是否健康
func (s *statesInformer) isGPUHealthy(uuid string) bool {
    s.gpuMutex.RLock()
    defer s.gpuMutex.RUnlock()
    
    _, unhealthy := s.unhealthyGPU[uuid]
    return !unhealthy
}

健康检测触发条件:

┌────────────────────────────────────────────────────────┐
│          GPU 标记为不健康的场景                         │
├────────────────────────────────────────────────────────┤
│  1. NVML API 调用失败                                   │
│     nvml.DeviceGetMemoryInfo() 返回错误                │
│     → 可能是 GPU 硬件故障                               │
│                                                         │
│  2. GPU 温度过高                                        │
│     nvml.DeviceGetTemperature() > 95°C                 │
│     → 触发温控保护,避免损坏                             │
│                                                         │
│  3. GPU ECC 错误                                        │
│     nvml.DeviceGetTotalEccErrors() > 阈值              │
│     → 显存错误,数据可能不可靠                           │
│                                                         │
│  4. GPU 掉线                                            │
│     nvml.DeviceGetHandleByUUID() 失败                  │
│     → GPU 可能被热插拔移除                              │
│                                                         │
│  5. 手动标记                                            │
│     kubectl label node <name> gpu-health=unhealthy     │
│     → 运维人员主动隔离故障 GPU                          │
└────────────────────────────────────────────────────────┘

生产案例 - GPU 温度监控:

某云厂商的 GPU 集群,配置了温度监控:

// 伪代码示例
func (s *statesInformer) monitorGPUTemperature() {
    ticker := time.NewTicker(30 * time.Second)
    defer ticker.Stop()
    
    for range ticker.C {
        count, _ := nvml.DeviceGetCount()
        for i := 0; i < int(count); i++ {
            device, _ := nvml.DeviceGetHandleByIndex(i)
            uuid, _ := nvml.DeviceGetUUID(device)
            temp, ret := nvml.DeviceGetTemperature(device, nvml.TEMPERATURE_GPU)
            
            if ret != nvml.SUCCESS {
                s.markGPUUnhealthy(uuid)
                continue
            }
            
            if temp > 95 {
                klog.Warningf("GPU %s temperature too high: %d°C", uuid, temp)
                s.markGPUUnhealthy(uuid)
            } else if temp < 90 && !s.isGPUHealthy(uuid) {
                // 温度降下来后恢复健康状态
                s.markGPUHealthy(uuid)
            }
        }
    }
}

效果统计:

指标	数据
监控的 GPU 总数	4000 张
每月检测到的温度异常	8-12 次
自动隔离避免的故障调度	100%
温度恢复后自动启用	平均 15 分钟

---

四、Device CRD 上报流程

4.1 周期性上报机制

Koordlet 每 60 秒执行一次 GPU 信息上报:

// pkg/koordlet/statesinformer/states_informer.go

func (s *statesInformer) Run(stopCh <-chan struct{}) error {
    // 启动时立即上报一次
    s.reportDevice()
    
    // 周期性上报
    go wait.Until(s.reportDevice, time.Minute, stopCh)
    
    return nil
}

func (s *statesInformer) reportDevice() {
    node := s.GetNode()
    if node == nil {
        klog.Errorf("node is nil")
        return
    }
    
    // 1. 构建 GPU 设备信息
    gpuDevices := s.buildGPUDevice()
    if len(gpuDevices) == 0 {
        return
    }
    
    // 2. 获取 GPU 型号和驱动版本
    gpuModel, gpuDriverVer := s.getGPUDriverAndModelFunc()
    
    // 3. 构建 Device CRD
    device := s.buildBasicDevice(node)
    s.fillGPUDevice(device, gpuDevices, gpuModel, gpuDriverVer)
    
    // 4. 尝试更新 Device CRD
    err := s.updateDevice(device)
    if err == nil {
        klog.V(4).Infof("successfully update Device %s", node.Name)
        return
    }
    
    // 5. 如果不存在,则创建
    if !errors.IsNotFound(err) {
        klog.Errorf("Failed to updateDevice %s, err: %v", node.Name, err)
        return
    }
    
    err = s.createDevice(device)
    if err == nil {
        klog.V(4).Infof("successfully create Device %s", node.Name)
    } else {
        klog.Errorf("Failed to create Device %s, err: %v", node.Name, err)
    }
}

4.2 Device CRD 构建

// pkg/koordlet/statesinformer/states_device_linux.go

func (s *statesInformer) buildBasicDevice(node *corev1.Node) *schedulingv1alpha1.Device {
    blocker := true
    device := &schedulingv1alpha1.Device{
        ObjectMeta: metav1.ObjectMeta{
            Name: node.Name,
            OwnerReferences: []metav1.OwnerReference{
                {
                    APIVersion:         "v1",
                    Kind:               "Node",
                    Name:               node.Name,
                    UID:                node.UID,
                    Controller:         &blocker,
                    BlockOwnerDeletion: &blocker,
                },
            },
        },
    }
    
    return device
}

func (s *statesInformer) fillGPUDevice(
    device *schedulingv1alpha1.Device,
    gpuDevices []schedulingv1alpha1.DeviceInfo,
    gpuModel string,
    gpuDriverVer string,
) {
    // 填充 GPU 设备列表
    device.Spec.Devices = append(device.Spec.Devices, gpuDevices...)
    
    // 添加 GPU 相关的 Label
    if device.Labels == nil {
        device.Labels = make(map[string]string)
    }
    if gpuModel != "" {
        device.Labels[extension.LabelGPUModel] = gpuModel
    }
    if gpuDriverVer != "" {
        device.Labels[extension.LabelGPUDriverVersion] = gpuDriverVer
    }
}

构建的 Device CRD 示例:

apiVersion: scheduling.koordinator.sh/v1alpha1
kind: Device
metadata:
  name: node-gpu-1
  labels:
    node.koordinator.sh/gpu-model: "NVIDIA-Tesla-V100-SXM2-16GB"
    node.koordinator.sh/gpu-driver-version: "470.82.01"
  ownerReferences:
  - apiVersion: v1
    kind: Node
    name: node-gpu-1
    uid: 12345678-1234-1234-1234-123456789abc
    controller: true
    blockOwnerDeletion: true
spec:
  devices:
  - id: "GPU-12345678-1234-1234-1234-123456789001"
    minor: 0
    type: gpu
    health: true
    resources:
      koordinator.sh/gpu-core: "100"
      koordinator.sh/gpu-memory: "16Gi"
      koordinator.sh/gpu-memory-ratio: "100"
  - id: "GPU-12345678-1234-1234-1234-123456789002"
    minor: 1
    type: gpu
    health: true
    resources:
      koordinator.sh/gpu-core: "100"
      koordinator.sh/gpu-memory: "16Gi"
      koordinator.sh/gpu-memory-ratio: "100"
  - id: "GPU-12345678-1234-1234-1234-123456789003"
    minor: 2
    type: gpu
    health: false  # 不健康的 GPU
    resources:
      koordinator.sh/gpu-core: "100"
      koordinator.sh/gpu-memory: "16Gi"
      koordinator.sh/gpu-memory-ratio: "100"

4.3 增量更新机制

为了减少网络开销和 APIServer 压力,Koordlet 只在设备信息变化时才更新:

// pkg/koordlet/statesinformer/states_device_linux.go

func (s *statesInformer) updateDevice(device *schedulingv1alpha1.Device) error {
    // 设备排序函数(保证顺序一致,便于比较)
    sorter := func(devices []schedulingv1alpha1.DeviceInfo) {
        sort.Slice(devices, func(i, j int) bool {
            return *(devices[i].Minor) < *(devices[j].Minor)
        })
    }
    sorter(device.Spec.Devices)

    return util.RetryOnConflictOrTooManyRequests(func() error {
        // 1. 获取最新的 Device CRD
        latestDevice, err := s.deviceClient.Get(context.TODO(), device.Name, metav1.GetOptions{ResourceVersion: "0"})
        if err != nil {
            return err
        }
        sorter(latestDevice.Spec.Devices)

        // 2. 对比是否有变化
        if apiequality.Semantic.DeepEqual(device.Spec.Devices, latestDevice.Spec.Devices) &&
           apiequality.Semantic.DeepEqual(device.Labels, latestDevice.Labels) {
            klog.V(4).Infof("Device %s has not changed and does not need to be updated", device.Name)
            return nil
        }

        // 3. 有变化才更新
        latestDevice.Spec.Devices = device.Spec.Devices
        latestDevice.Labels = device.Labels

        _, err = s.deviceClient.Update(context.TODO(), latestDevice, metav1.UpdateOptions{})
        return err
    })
}

增量更新的优势:

┌────────────────────────────────────────────────────────┐
│          增量更新 vs 全量更新                           │
├────────────────────────────────────────────────────────┤
│                                                         │
│  场景: 500 个节点,每个节点 8 张 GPU,每 60 秒上报一次   │
│                                                         │
│  全量更新:                                              │
│    - APIServer 写入 QPS: 500 / 60 ≈ 8.3 QPS           │
│    - etcd 存储压力: 高                                  │
│    - 网络带宽消耗: 500 × 15KB / 60s ≈ 125 KB/s        │
│                                                         │
│  增量更新 (假设 5% 的设备有变化):                       │
│    - APIServer 写入 QPS: 25 / 60 ≈ 0.42 QPS           │
│    - etcd 存储压力: 低                                  │
│    - 网络带宽消耗: 25 × 15KB / 60s ≈ 6.25 KB/s        │
│                                                         │
│  性能提升:                                              │
│    - APIServer QPS 降低 95%                            │
│    - 网络带宽节省 95%                                   │
│    - etcd 写入压力降低 95%                              │
│                                                         │
└────────────────────────────────────────────────────────┘

4.4 并发控制 - 乐观锁

使用 Kubernetes 的 ResourceVersion 实现乐观锁:

func (s *statesInformer) updateDevice(device *schedulingv1alpha1.Device) error {
    return util.RetryOnConflictOrTooManyRequests(func() error {
        // 1. 获取最新版本 (ResourceVersion: "0" 表示从 etcd 读取最新数据)
        latestDevice, err := s.deviceClient.Get(context.TODO(), device.Name, metav1.GetOptions{ResourceVersion: "0"})
        if err != nil {
            return err
        }
        
        // 2. 修改最新版本的数据
        latestDevice.Spec.Devices = device.Spec.Devices
        latestDevice.Labels = device.Labels
        
        // 3. 提交更新 (携带 ResourceVersion)
        _, err = s.deviceClient.Update(context.TODO(), latestDevice, metav1.UpdateOptions{})
        
        // 4. 如果版本冲突,RetryOnConflictOrTooManyRequests 会自动重试
        return err
    })
}

乐观锁工作原理:

┌────────────────────────────────────────────────────────┐
│            乐观锁并发控制流程                           │
├────────────────────────────────────────────────────────┤
│                                                         │
│  初始状态:                                              │
│    Device.ResourceVersion = "12345"                    │
│    Device.Spec.Devices = [GPU-0, GPU-1]                │
│                                                         │
│  Koordlet-A 和 Koordlet-B 同时读取:                     │
│    A.device.ResourceVersion = "12345"                  │
│    B.device.ResourceVersion = "12345"                  │
│                                                         │
│  Koordlet-A 先提交更新:                                 │
│    Update(ResourceVersion="12345")                     │
│    → 成功,新版本 ResourceVersion = "12346"             │
│                                                         │
│  Koordlet-B 后提交更新:                                 │
│    Update(ResourceVersion="12345")                     │
│    → 失败,返回 Conflict 错误                            │
│    → RetryOnConflictOrTooManyRequests 捕获错误          │
│    → 重新读取最新版本 (ResourceVersion="12346")         │
│    → 再次提交更新                                       │
│    → 成功                                               │
│                                                         │
└────────────────────────────────────────────────────────┘

---

五、生产环境实践

5.1 GPU 发现与初始化

完整的初始化流程:

// pkg/koordlet/statesinformer/states_informer.go

func NewStatesInformer(config *Config, ...) StatesInformer {
    s := &statesInformer{
        // 初始化各种字段...
        unhealthyGPU: make(map[string]struct{}),
    }
    
    // 初始化 GPU (容错处理)
    if !s.initGPU() {
        klog.Warning("GPU initialization failed, GPU scheduling will be disabled")
        // 不阻止 Koordlet 启动,只是禁用 GPU 功能
    } else {
        klog.Info("GPU initialization succeeded")
        s.getGPUDriverAndModelFunc = getGPUDriverAndModel
    }
    
    return s
}

生产案例 - 容器化部署注意事项:

某云厂商在容器中运行 Koordlet 时遇到的问题:

问题	原因	解决方案
NVML 库找不到	容器中没有 libnvidia-ml.so	挂载宿主机 /usr/lib64 到容器
没有权限访问 GPU	容器缺少设备访问权限	添加 privileged: true 或挂载 /dev/nvidia*
NVML 初始化失败	驱动版本不匹配	使用 nvidia-container-runtime
GPU UUID 获取失败	驱动未完全初始化	延迟 10 秒后重试

推荐的 Koordlet 容器配置:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: koordlet
  namespace: koordinator-system
spec:
  template:
    spec:
      hostNetwork: true
      hostPID: true
      containers:
      - name: koordlet
        image: koordlet:v1.0.0
        
        # 方案 1: 使用 privileged (最简单,但权限过大)
        securityContext:
          privileged: true
        
        # 方案 2: 最小化权限 (推荐)
        securityContext:
          capabilities:
            add:
            - SYS_ADMIN  # 访问 cgroup
        
        # 挂载必需的目录
        volumeMounts:
        - name: sys
          mountPath: /sys
        - name: dev
          mountPath: /dev
        - name: nvidia-lib
          mountPath: /usr/lib/x86_64-linux-gnu
          readOnly: true
        
        env:
        # 指定 NVML 库路径 (可选)
        - name: LD_LIBRARY_PATH
          value: "/usr/lib/x86_64-linux-gnu:/usr/lib64"
        
      volumes:
      - name: sys
        hostPath:
          path: /sys
      - name: dev
        hostPath:
          path: /dev
      - name: nvidia-lib
        hostPath:
          path: /usr/lib/x86_64-linux-gnu

5.2 性能数据

GPU 信息采集性能:

某电商云平台的 GPU 集群统计:

指标	数据
节点数量	500 个
GPU 总数	4000 张 (每节点 8 张)
GPU 型号	NVIDIA V100 32GB
采集周期	60 秒
单次采集耗时	平均 120ms
Device CRD 大小	平均 18KB
实际更新频率	5-10 次/小时 (仅在变化时更新)
APIServer 写入 QPS	0.002-0.004 QPS (非常低)

NVML API 调用性能:

API	平均耗时	说明
nvml.Init()	50-100ms	启动时调用一次
nvml.DeviceGetCount()	1-2ms	每次采集调用一次
nvml.DeviceGetHandleByIndex()	1-2ms	每张 GPU 调用一次
nvml.DeviceGetUUID()	2-3ms	每张 GPU 调用一次
nvml.DeviceGetMemoryInfo()	3-5ms	每张 GPU 调用一次
nvml.DeviceGetName()	1-2ms	调用一次(所有 GPU 型号相同)

8 张 GPU 的完整采集时间:

总耗时 = DeviceGetCount (2ms)
        + 8 × DeviceGetHandleByIndex (16ms)
        + 8 × DeviceGetUUID (24ms)
        + 8 × DeviceGetMemoryInfo (40ms)
        + DeviceGetName (2ms)
        + 其他开销 (40ms)
        ≈ 124ms

5.3 故障排查

问题 1: Device CRD 没有创建

排查步骤:

# 1. 检查 Koordlet 是否运行
kubectl get pod -n koordinator-system -l app=koordlet

# 2. 查看 Koordlet 日志
kubectl logs -n koordinator-system koordlet-xxx | grep -i "gpu\|nvml\|device"

# 可能的日志:
# - "nvml init failed, library not found"  → 缺少 NVML 库
# - "no gpu device found"                  → 节点没有 GPU
# - "Failed to create Device"              → 没有权限创建 CRD

# 3. 检查节点是否有 GPU
ssh <node> nvidia-smi

# 4. 检查 NVML 库是否存在
ssh <node> ls -l /usr/lib64/libnvidia-ml.so*

# 5. 检查 Koordlet 的权限
kubectl get clusterrolebinding | grep koordlet

问题 2: GPU 信息不准确

排查步骤:

# 1. 检查 Device CRD 的内容
kubectl get device <node-name> -o yaml

# 2. 对比实际的 GPU 信息
ssh <node> nvidia-smi --query-gpu=uuid,index,memory.total --format=csv

# 3. 检查 MetricCache
kubectl exec -n koordinator-system koordlet-xxx -- cat /sys/fs/cgroup/cpu/cpuacct.usage

# 4. 强制触发更新 (重启 Koordlet)
kubectl delete pod -n koordinator-system koordlet-xxx

问题 3: GPU 被标记为不健康

排查步骤:

# 1. 检查 Device CRD 的 health 字段
kubectl get device <node-name> -o jsonpath='{.spec.devices[*].health}'

# 2. 查看 Koordlet 日志中的健康检测记录
kubectl logs -n koordinator-system koordlet-xxx | grep "marked as unhealthy"

# 3. 检查 GPU 温度
ssh <node> nvidia-smi --query-gpu=temperature.gpu --format=csv

# 4. 检查 GPU ECC 错误
ssh <node> nvidia-smi --query-gpu=ecc.errors.corrected.aggregate.total --format=csv

# 5. 手动恢复健康状态 (如果确认 GPU 正常)
# 重启 Koordlet 会重新检测
kubectl delete pod -n koordinator-system koordlet-xxx

5.4 监控告警配置

Prometheus 监控规则:

groups:
- name: gpu_device_collection
  rules:
  # 1. Device CRD 上报成功率
  - record: gpu:device_report_success_rate
    expr: |
      rate(koordlet_device_report_success_total[5m])
      / 
      rate(koordlet_device_report_total[5m])

  # 2. GPU 不健康比例
  - record: gpu:unhealthy_ratio
    expr: |
      sum(device_gpu_health == 0) / sum(device_gpu_total)

  # 3. Device CRD 更新延迟
  - record: gpu:device_report_latency_seconds
    expr: |
      histogram_quantile(0.99, rate(koordlet_device_report_duration_seconds_bucket[5m]))

  # 告警规则
  - alert: DeviceReportFailureHigh
    expr: gpu:device_report_success_rate < 0.9
    for: 5m
    annotations:
      summary: "Device CRD上报失败率超过10%"
      description: "集群中 {{ $value | humanizePercentage }} 的节点上报失败"

  - alert: GPUUnhealthyHigh
    expr: gpu:unhealthy_ratio > 0.05
    for: 10m
    annotations:
      summary: "不健康GPU比例过高"
      description: "集群中 {{ $value | humanizePercentage }} 的GPU不健康"

Grafana 监控面板:

┌─────────────────────────────────────────────────────────┐
│         GPU 信息采集监控 Dashboard                       │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────────┐  ┌──────────────────┐            │
│  │  Device CRD数量   │  │  上报成功率       │            │
│  │     500          │  │     99.8%        │            │
│  └──────────────────┘  └──────────────────┘            │
│                                                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │          不健康 GPU 分布                          │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  node-1: GPU-2 (温度过高)                        │  │
│  │  node-5: GPU-7 (ECC 错误)                        │  │
│  │  node-12: GPU-0 (驱动异常)                       │  │
│  └──────────────────────────────────────────────────┘  │
│                                                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │            采集耗时统计                           │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  P50: 80ms   [████████          ]               │  │
│  │  P90: 120ms  [████████████      ]               │  │
│  │  P99: 180ms  [██████████████    ]               │  │
│  └──────────────────────────────────────────────────┘  │
│                                                          │
└─────────────────────────────────────────────────────────┘

---

六、高级特性

6.1 GPU 热插拔支持

Koordlet 支持 GPU 热插拔场景(主要在云环境中):

func (s *statesInformer) detectGPUChange() {
    // 记录上一次的 GPU UUID 列表
    previousGPUs := s.getPreviousGPUList()
    
    // 获取当前的 GPU 列表
    currentGPUs := s.buildGPUDevice()
    
    // 检测新增的 GPU
    for _, gpu := range currentGPUs {
        if !contains(previousGPUs, gpu.UUID) {
            klog.Infof("Detected new GPU: %s (Minor: %d)", gpu.UUID, *gpu.Minor)
            // 立即触发上报
            s.reportDevice()
            break
        }
    }
    
    // 检测移除的 GPU
    for _, gpu := range previousGPUs {
        if !contains(currentGPUs, gpu.UUID) {
            klog.Warningf("Detected removed GPU: %s", gpu.UUID)
            // 立即触发上报
            s.reportDevice()
            break
        }
    }
}

6.2 多 GPU 型号支持

同一节点可能有不同型号的 GPU:

apiVersion: scheduling.koordinator.sh/v1alpha1
kind: Device
metadata:
  name: node-mixed-gpu
  labels:
    # 当有多种型号时,label 只记录第一个型号
    node.koordinator.sh/gpu-model: "NVIDIA-Tesla-V100-SXM2-16GB"
    node.koordinator.sh/gpu-driver-version: "470.82.01"
spec:
  devices:
  # V100 GPU
  - id: "GPU-v100-001"
    minor: 0
    type: gpu
    health: true
    resources:
      koordinator.sh/gpu-core: "100"
      koordinator.sh/gpu-memory: "16Gi"
      koordinator.sh/gpu-memory-ratio: "100"
  # A100 GPU
  - id: "GPU-a100-001"
    minor: 1
    type: gpu
    health: true
    resources:
      koordinator.sh/gpu-core: "100"
      koordinator.sh/gpu-memory: "40Gi"  # A100 显存更大
      koordinator.sh/gpu-memory-ratio: "100"

6.3 GPU 拓扑感知

对于多 GPU 互联(NVLink、PCIe Switch)的场景:

// 未来扩展: GPU 拓扑信息
type GPUTopology struct {
    // GPU 之间的连接关系
    NVLinks map[int][]int  // GPU Minor → 连接的 GPU Minor 列表
    
    // PCIe 拓扑
    PCIeBus map[int]string  // GPU Minor → PCIe Bus ID
    
    // NUMA 亲和性
    NUMANode map[int]int    // GPU Minor → NUMA Node ID
}

---

七、总结

7.1 生产最佳实践

实践项	推荐配置	说明
采集周期	60 秒	平衡实时性和性能
容器权限	privileged: true	简化配置,确保权限充足
健康阈值	温度 95°C	避免硬件损坏
监控告警	上报成功率 < 90%	及时发现问题
日志级别	V(4)	保留关键日志

7.2 性能指标

某互联网公司 500 节点 GPU 集群的实际数据:

• GPU 总数: 4000 张
• Device CRD 数量: 500 个
• 平均采集耗时: 120ms
• APIServer 写入 QPS: 0.003 QPS (极低)
• 存储开销: 500 × 18KB ≈ 9MB
• CPU 开销: 每个 Koordlet < 0.5%
• 内存开销: 每个 Koordlet < 50MB