projecthami/hami

Hami Scheduler & NVIDIA Device Plugin 镜像文档

一、镜像概述和主要用途

Hami Scheduler & NVIDIA Device Plugin 镜像整合了 Hami 调度器与 NVIDIA 设备插件，专为 Kubernetes 集群设计，用于实现 GPU 资源的高效管理与调度。其中：

• NVIDIA Device Plugin：遵循 Kubernetes 设备插件框架，负责将节点上的 NVIDIA GPU 资源暴露给集群，支持容器对 GPU 的直接访问与资源隔离。
• Hami Scheduler：作为 Kubernetes 调度器扩展，提供增强的 GPU 调度策略（如基于算力、显存的精细化调度、多实例 GPU 拆分等），优化 GPU 资源利用率。

主要用途：为需要 GPU 加速的应用（如 AI 训练、机器学习推理、高性能计算）提供稳定的资源供给与高效调度能力，适用于 Kubernetes 集群环境。

二、核心功能和特性

2.1 NVIDIA Device Plugin 功能

• GPU 资源暴露：自动检测节点上的 NVIDIA GPU 设备，将其注册为 Kubernetes 可调度资源（如 nvidia.com/gpu）。
• 设备隔离：支持按 GPU 卡、显存、算力等维度隔离资源，确保容器安全使用指定 GPU。
• 健康检查：实时监控 GPU 设备状态，异常时自动标记不可用，避免调度失败。
• 驱动兼容性：兼容 NVIDIA 官方驱动，支持 CUDA 运行时环境。

2.2 Hami Scheduler 功能

• 精细化调度策略：支持基于 GPU 型号、显存容量、算力负载的定向调度，满足差异化应用需求。
• 资源优化：动态调整 GPU 分配策略，减少资源碎片，提升集群 GPU 利用率。
• 多实例 GPU（MIG）支持：兼容 NVIDIA MIG 技术，可将单张 GPU 拆分为多个独立实例并独立调度。
• 可扩展配置：支持自定义调度规则（如优先级权重、亲和性/反亲和性策略）。

三、使用场景和适用范围

3.1 典型使用场景

• AI/ML 训练与推理：为深度学习框架（如 TensorFlow、PyTorch）提供 GPU 资源调度，保障训练任务的高效执行。
• 高性能计算（HPC）：支持科学计算类应用（如分子模拟、流体力学）的 GPU 资源分配。
• 多租户 GPU 共享：在共享集群中，通过精细化调度实现多用户、多任务的 GPU 资源隔离与公平分配。

3.2 适用范围

• 环境要求：Kubernetes 1.16+ 集群，节点已安装 NVIDIA GPU 驱动（418.81.07+）及 nvidia-container-runtime。
• 硬件要求：搭载 NVIDIA GPU 的节点（如 Tesla V100、A100、T4 等）。

四、详细的使用方法和配置说明

4.1 镜像获取

bash
docker pull docker.xuanyuan.run/[镜像仓库地址]/hami-scheduler-nvidia-device-plugin:latest  # 替换为实际镜像地址

4.2 部署方式

4.2.1 单节点测试（docker run）

适用于快速验证功能，生产环境建议通过 Kubernetes 部署。

bash
# 启动 NVIDIA Device Plugin（需挂载主机设备与运行时）
docker run -d \
  --name nvidia-device-plugin \
  --restart=always \
  --cap-add=SYS_ADMIN \
  --device=/dev/nvidiactl:/dev/nvidiactl \
  --device=/dev/nvidia-uvm:/dev/nvidia-uvm \
  --device=/dev/nvidia0:/dev/nvidia0 \  # 根据实际 GPU 数量添加（如 nvidia1, nvidia2...）
  -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
  -v /usr/local/nvidia/lib64:/usr/local/nvidia/lib64 \
  -e NVIDIA_VISIBLE_DEVICES=all \  # 暴露所有 GPU，或指定卡号（如 "0,1"）
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \  # 启用计算与工具能力
  [镜像仓库地址]/hami-scheduler-nvidia-device-plugin:latest nvidia-device-plugin

# 启动 Hami Scheduler（需连接 Kubernetes API Server）
docker run -d \
  --name hami-scheduler \
  --restart=always \
  -v /etc/kubernetes/admin.conf:/etc/kubernetes/admin.conf \  # 挂载 K8s 配置
  -e KUBECONFIG=/etc/kubernetes/admin.conf \
  -e HAMI_LOG_LEVEL=info \  # 日志级别：debug/info/warn/error
  -e HAMI_SCHEDULING_POLICY=gpu-aware \  # 调度策略：gpu-aware（默认）/balanced
  [镜像仓库地址]/hami-scheduler-nvidia-device-plugin:latest hami-scheduler

4.2.2 Kubernetes 部署（推荐）

生产环境中，建议通过 DaemonSet（设备插件）与 Deployment（调度器）部署：

1. NVIDIA Device Plugin DaemonSet 配置（nvidia-device-plugin-daemonset.yaml）

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nvidia-device-plugin
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: nvidia-device-plugin
  template:
    metadata:
      labels:
        name: nvidia-device-plugin
    spec:
      tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule
      containers:
      - name: nvidia-device-plugin
        image: docker.xuanyuan.run/[镜像仓库地址]/hami-scheduler-nvidia-device-plugin:latest
        command: ["nvidia-device-plugin"]
        resources:
          limits:
            cpu: 50m
            memory: 100Mi
          requests:
            cpu: 50m
            memory: 100Mi
        securityContext:
          privileged: true
        volumeMounts:
        - name: device-plugin
          mountPath: /var/lib/kubelet/device-plugins
        - name: nvidia-lib
          mountPath: /usr/local/nvidia/lib64
        - name: nvidia-bin
          mountPath: /usr/local/nvidia/bin
        env:
        - name: NVIDIA_VISIBLE_DEVICES
          value: "all"
        - name: NVIDIA_DRIVER_CAPABILITIES
          value: "compute,utility"
      volumes:
      - name: device-plugin
        hostPath:
          path: /var/lib/kubelet/device-plugins
      - name: nvidia-lib
        hostPath:
          path: /usr/local/nvidia/lib64
      - name: nvidia-bin
        hostPath:
          path: /usr/local/nvidia/bin

2. Hami Scheduler Deployment 配置（hami-scheduler-deployment.yaml）

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hami-scheduler
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      name: hami-scheduler
  template:
    metadata:
      labels:
        name: hami-scheduler
    spec:
      serviceAccountName: hami-scheduler  # 需提前创建具备调度权限的 ServiceAccount
      containers:
      - name: hami-scheduler
        image: docker.xuanyuan.run/[镜像仓库地址]/hami-scheduler-nvidia-device-plugin:latest
        command: ["hami-scheduler"]
        resources:
          limits:
            cpu: 100m
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        env:
        - name: HAMI_LOG_LEVEL
          value: "info"
        - name: HAMI_SCHEDULING_POLICY
          value: "gpu-aware"
        - name: HAMI_GPU_MEM_THRESHOLD
          value: "80"  # 显存使用率阈值（%），超过则触发重调度

4.3 配置参数说明

4.3.1 NVIDIA Device Plugin 环境变量

4.3.2 Hami Scheduler 配置参数

五、注意事项

1. 驱动兼容性：节点需安装与 GPU 型号匹配的 NVIDIA 驱动（版本 ≥ 418.81.07），且容器运行时需配置 nvidia-container-runtime（替换默认 runc）。
2. 权限要求：NVIDIA Device Plugin 需以特权模式运行（privileged: true），以访问主机 GPU 设备；Hami Scheduler 需具备 Kubernetes API 的调度相关权限（如 nodes、pods 的读写权限）。
3. MIG 支持：若使用多实例 GPU（MIG），需在节点启用 MIG 模式，并通过 NVIDIA_MIG_MONITOR_DEVICES 配置监控路径。
4. 日志排查：调度异常时，可通过 kubectl logs <hami-scheduler-pod> -n kube-system 查看 Hami 调度器日志，通过 kubectl logs <nvidia-device-plugin-pod> -n kube-system 查看设备插件日志。

六、版本兼容性