英文版|中文版

OpenAIOS Kubernetes vGPU 调度器

支持的设备

注意 本项目已更名为 project-HAMi，我们保留旧仓库以确保兼容性。

简介

4paradigm k8s vGPU调度器是一个用于在Kubernetes集群中管理GPU的“一体化”解决方案，它具备您对Kubernetes GPU管理工具的所有期望功能，包括：

GPU共享：每个任务可以分配部分GPU资源，而不是整张GPU卡，从而实现多任务之间的GPU资源共享。

设备内存控制：GPU可以按固定大小（如3000M）或占总显存的百分比（如50%）进行分配，并确保不会超出限制。

虚拟设备内存：通过使用主机内存作为交换空间，您可以超额分配GPU设备内存。

GPU类型指定：您可以通过设置nvidia.com/use-gputype或nvidia.com/nouse-gputype注解来指定某个GPU任务应使用或避免使用的GPU类型。

易于使用：您无需修改任务的YAML文件即可使用我们的调度器。安装完成后，所有GPU作业都会自动得到支持。此外，如果您愿意，还可以将资源名称指定为nvidia.com/gpu以外的其他名称。

k8s vGPU调度器基于4paradigm k8s-device-plugin（4paradigm/k8s-device-plugin）的功能扩展，例如物理GPU的分割、内存和计算单元的限制等。在此基础上，它增加了调度模块，以平衡不同GPU节点之间的GPU使用情况。此外，用户还可以通过指定设备内存和计算核心的使用量来分配GPU资源。更进一步地，vGPU调度器能够虚拟化设备内存（实际使用的设备内存可以超过物理显存），从而运行一些需要大量显存的任务，或者增加共享任务的数量。有关详细信息，请参阅基准测试报告。

使用场景

1. 当Pod需要按特定的设备内存用量或计算核心数分配资源时。
2. 需要在包含多个GPU节点的集群中均衡GPU资源使用时。
3. 设备内存和计算单元利用率较低的情况，例如在一张GPU上运行10个TensorFlow Serving实例。
4. 需要大量小型GPU资源的场景，例如教学环境中为多名学生共享一台GPU，或云平台提供小型GPU实例。
5. 在物理设备内存不足的情况下，可以启用虚拟设备内存功能，例如训练大规模数据集和大型模型时。

先决条件

以下是运行NVIDIA设备插件所需的先决条件：

• NVIDIA驱动程序 ≥ 384.81
• nvidia-docker版本 > 2.0
• Kubernetes版本 ≥ 1.16
• glibc ≥ 2.17
• 内核版本 ≥ 3.10
• Helm > 3.0

快速开始

准备您的GPU节点

以下步骤需要在所有GPU节点上执行。 本README假定NVIDIA驱动程序和nvidia-container-toolkit已经预先安装好。 同时假设您已将nvidia-container-runtime配置为默认的底层运行时。

请参阅：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

基于Debian系统的docker和containerd示例

安装nvidia-container-toolkit

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/libnvidia-container.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

配置docker

当使用docker运行kubernetes时，编辑通常位于/etc/docker/daemon.json的配置文件，将nvidia-container-runtime设置为默认的底层运行时：

{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "path": "/usr/bin/nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

然后重启docker：

$ sudo systemctl daemon-reload && systemctl restart docker

配置containerd

当使用containerd运行kubernetes时，编辑通常位于/etc/containerd/config.toml的配置文件，将nvidia-container-runtime设置为默认的底层运行时：

version = 2
[plugins]
  [plugins."io.containerd.grpc.v1.cri"]
    [plugins."io.containerd.grpc.v1.cri".containerd]
      default_runtime_name = "nvidia"

      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
          privileged_without_host_devices = false
          runtime_engine = ""
          runtime_root = ""
          runtime_type = "io.containerd.runc.v2"
          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
            BinaryName = "/usr/bin/nvidia-container-runtime"

然后重启containerd：

$ sudo systemctl daemon-reload && systemctl restart containerd

之后，您需要为可由4pd-k8s-scheduler调度的GPU节点打上标签gpu=on，否则这些节点将无法被我们的调度器管理。

kubectl label nodes {nodeid} gpu=on

在 Kubernetes 中启用 vGPU 支持

首先，您需要使用以下命令检查您的 Kubernetes 版本：

kubectl version

然后，在 Helm 中添加我们的仓库：

helm repo add vgpu-charts https://4paradigm.github.io/k8s-vgpu-scheduler

在安装过程中，您需要根据您的 Kubernetes 服务器版本设置 Kubernetes 调度器镜像版本。例如，如果您的集群服务器版本是 1.16.8，则应使用以下命令进行部署：

helm install vgpu vgpu-charts/vgpu --set scheduler.kubeScheduler.imageTag=v1.16.8 -n kube-system

您可以通过调整 配置来自定义安装。

您可以通过以下命令验证安装是否成功：

$ kubectl get pods -n kube-system

如果 vgpu-device-plugin 和 vgpu-scheduler 这两个 Pod 处于 Running 状态，则说明您的安装已成功。

运行 GPU 作业

现在，容器可以使用 nvidia.com/gpu 资源类型来请求 NVIDIA vGPU：

apiVersion: v1
kind: Pod
metadata:
  name: gpu-pod
spec:
  containers:
    - name: ubuntu-container
      image: ubuntu:18.04
      command: ["bash", "-c", "sleep 86400"]
      resources:
        limits:
          nvidia.com/gpu: 2 # 请求 2 个 vGPU
          nvidia.com/gpumem: 3000 # 每个 vGPU 包含 3000m 设备内存（可选，整数）
          nvidia.com/gpucores: 30 # 每个 vGPU 使用整个 GPU 的 30%（可选，整数）

请注意，如果任务无法分配到任何 GPU 节点上（即您请求的 nvidia.com/gpu 数量超过了任何节点上的 GPU 数量），该任务将陷入 pending 状态。

现在您可以在容器中执行 nvidia-smi 命令，并查看 vGPU 和物理 GPU 之间的显存差异。

警告： 如果您在使用 NVIDIA 镜像的设备插件时未请求 vGPU，机器上的所有 vGPU 将暴露在您的容器中。

更多示例

点击 这里 查看更多示例。

调度器 Webhook 服务 NodePort

默认调度器端口为 31998，您可以在安装时使用 --set deivcePlugin.service.schedulerPort 来设置其他值。

监控 vGPU 状态

安装后会自动启用监控功能。您可以通过访问以下地址获取节点的 vGPU 状态：

http://{nodeip}:{monitorPort}/metrics

默认监控端口为 31992，您可以在安装时使用 --set deivcePlugin.service.httpPort 来设置其他值。

Grafana 仪表板 示例

注意 在进行任何 GPU 操作之前，不会收集节点的状态信息。

升级

要将 k8s-vGPU 升级到最新版本，您只需更新仓库并重新启动 Chart 即可：

$ helm uninstall vgpu -n kube-system
$ helm repo update
$ helm install vgpu vgpu -n kube-system

卸载

helm uninstall vgpu -n kube-system

调度

当前的调度策略是选择任务最少的 GPU，从而在多个 GPU 之间均衡负载。

基准测试

我们使用了 ai-benchmark 中的三个实例来评估 vGPU 设备插件的性能，具体如下：

测试环境	描述
Kubernetes 版本	v1.12.9
Docker 版本	18.09.1
GPU 类型	Tesla V100
GPU 数量	2

测试实例	描述
nvidia-device-plugin	k8s + nvidia k8s-device-plugin
vGPU-device-plugin	k8s + VGPU k8s-device-plugin，不使用虚拟设备内存
vGPU-device-plugin（使用虚拟设备内存）	k8s + VGPU k8s-device-plugin，使用虚拟设备内存

测试用例：

测试编号	案例	类型	参数
1.1	Resnet-V2-50	推理	batch=50,size=346*346
1.2	Resnet-V2-50	训练	batch=20,size=346*346
2.1	Resnet-V2-152	推理	batch=10,size=256*256
2.2	Resnet-V2-152	训练	batch=10,size=256*256
3.1	VGG-16	推理	batch=20,size=224*224
3.2	VGG-16	训练	batch=2,size=224*224
4.1	DeepLab	推理	batch=2,size=512*512
4.2	DeepLab	训练	batch=1,size=384*384
5.1	LSTM	推理	batch=100,size=1024*300
5.2	LSTM	训练	batch=10,size=1024*300

测试结果：

重现步骤：

1. 安装 k8s-vGPU 调度器，并正确配置。
2. 运行基准测试作业。

$ kubectl apply -f benchmarks/ai-benchmark/ai-benchmark.yml

3. 使用 kubctl logs 查看结果。

$ kubectl logs [pod id]

功能

• 可以指定每个物理 GPU 分配的 vGPU 数量。
• 限制 vGPU 的设备内存。
• 允许通过指定设备内存来分配 vGPU。
• 限制 vGPU 的流式多处理器。
• 允许通过指定设备核心使用率来分配 vGPU。
• 对现有程序无需任何修改。

实验性功能

• 虚拟设备内存

  vGPU 的设备内存可以超过 GPU 的物理设备内存。此时，超出部分将被存储在 RAM 中，这会对性能产生一定影响。

已知问题

• 目前 A100 MIG 仅支持“none”和“mixed”模式。
• 目前带有 “nodeName” 字段的任务无法被调度，请改用 “nodeSelector”。
• 目前仅支持计算任务，不支持视频编解码处理。

待办事项

• 支持视频编解码处理。
• 支持多实例 GPU (MIG)。

测试

• TensorFlow 1.14.0/2.4.1
• torch 1.1.0
• mxnet 1.4.0
• mindspore 1.1.1

以上框架均已通过测试。

问题与贡献

• 您可以通过 提交新问题 报告错误、提出疑问或进行修改。
• 如果您想了解更多或有想法，可以参与 讨论 和 Slack 社区交流。

作者

• 李孟轩 (limengxuan@4paradigm.com)
• 裴兆友 (peizhaoyou@4paradigm.com)
• 史广川 (shiguangchuan@4paradigm.com)
• 郑钊 (zhengzhao@4paradigm.com)

联系方式

负责人及维护者：李孟轩

欢迎通过以下方式联系我：

邮箱：<limengxuan@4paradigm.com> 
电话：+86 18810644493
微信：xuanzong4493

k8s-vgpu-scheduler 快速上手指南

k8s-vgpu-scheduler（现更名为 Project-HAMi）是一个用于 Kubernetes 集群的 GPU 统一管理调度器。它支持 GPU 共享、显存限制、核心算力限制以及虚拟显存等功能，无需修改现有任务 YAML 即可自动生效。

1. 环境准备

在部署前，请确保您的集群满足以下前置条件：

• 操作系统: Linux (glibc >= 2.17, kernel >= 3.10)
• Kubernetes: 版本 >= 1.16
• NVIDIA 驱动: 版本 >= 384.81
• 容器运行时: 已安装 nvidia-docker (> 2.0) 或配置了 nvidia-container-toolkit
• 包管理工具: Helm > 3.0

节点预处理

在所有 GPU 节点上，需确保 nvidia-container-runtime 已设为默认运行时。

安装 nvidia-container-toolkit (以 Debian/Ubuntu 为例):

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/libnvidia-container.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

配置 Docker (如使用 Docker): 编辑 /etc/docker/daemon.json:

{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "path": "/usr/bin/nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

重启 Docker:

sudo systemctl daemon-reload && systemctl restart docker

配置 Containerd (如使用 Containerd): 编辑 /etc/containerd/config.toml, 确保包含以下配置:

version = 2
[plugins]
  [plugins."io.containerd.grpc.v1.cri"]
    [plugins."io.containerd.grpc.v1.cri".containerd]
      default_runtime_name = "nvidia"
      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
          privileged_without_host_devices = false
          runtime_engine = ""
          runtime_root = ""
          runtime_type = "io.containerd.runc.v2"
          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
            BinaryName = "/usr/bin/nvidia-container-runtime"

重启 Containerd:

sudo systemctl daemon-reload && systemctl restart containerd

标记 GPU 节点: 必须为可调度的 GPU 节点添加标签，否则无法被管理：

kubectl label nodes <node-name> gpu=on

2. 安装步骤

添加 Helm 仓库

helm repo add vgpu-charts https://4paradigm.github.io/k8s-vgpu-scheduler
helm repo update

部署调度器

请根据您的 Kubernetes 集群版本设置 scheduler.kubeScheduler.imageTag。例如，若集群版本为 v1.16.8：

helm install vgpu vgpu-charts/vgpu --set scheduler.kubeScheduler.imageTag=v1.16.8 -n kube-system

提示: 可通过 --set 参数自定义配置，详见官方 config 文档。

验证安装

检查 Pod 状态，确认 vgpu-device-plugin 和 vgpu-scheduler 均处于 Running 状态：

kubectl get pods -n kube-system

3. 基本使用

安装完成后，无需修改现有 YAML 结构，只需在 Pod 的 resources.limits 中声明 GPU 资源即可。

示例：申请带显存和算力限制的 vGPU

以下示例申请 2 个 vGPU，每个 vGPU 限制显存为 3000MB，算力占用为整卡的 30%：

apiVersion: v1
kind: Pod
metadata:
  name: gpu-pod
spec:
  containers:
    - name: ubuntu-container
      image: ubuntu:18.04
      command: ["bash", "-c", "sleep 86400"]
      resources:
        limits:
          nvidia.com/gpu: 2                # 申请 2 个 vGPU
          nvidia.com/gpumem: 3000          # (可选) 每个 vGPU 限制显存 3000MB
          nvidia.com/gpucores: 30          # (可选) 每个 vGPU 限制算力为 30%

使用说明

• 资源名称: 默认为 nvidia.com/gpu，也可通过配置自定义。
• 显存超卖: 支持开启虚拟显存功能，使分配的显存总和超过物理显存（利用主机内存作为 Swap）。
• 类型指定: 可通过注解 nvidia.com/use-gputype 或 nvidia.com/nouse-gputype 指定使用或避开特定类型的 GPU。
• 状态监控: 安装后自动开启监控，访问 http://{nodeip}:31992/metrics 即可查看节点 vGPU 状态。

验证效果

进入容器执行 nvidia-smi，您将看到显存大小已被限制为设定值，而非整卡显存。

注意: 如果请求的资源量超过集群中任意单节点的承载能力，Pod 将保持在 Pending 状态。