适用于 Kubernetes 的 NVIDIA 设备插件

目录

• 简介
• 先决条件
• 快速入门
  • 准备您的 GPU 节点
    • 基于 Debian 的系统，使用 docker 和 containerd 的示例
      • 安装 NVIDIA 容器工具包
      • 关于 CRI-O 配置的说明
  • 在 Kubernetes 中启用 GPU 支持
  • 运行 GPU 作业
• 配置 NVIDIA 设备插件二进制文件
  • 作为命令行标志或环境变量
  • 作为配置文件
  • 配置选项详情
  • GPU 的共享访问
    • 使用 CUDA 时间片
    • 使用 CUDA MPS
  • IMEX 支持
• 标签目录
• 通过 helm 部署
  • 配置设备插件的 helm 图表
    • 通过 ConfigMap 向插件传递配置
      • 单个配置文件示例
      • 多个配置文件示例
      • 使用节点标签更新每个节点的配置
    • 设置其他 helm 图表值
    • 使用 gpu-feature-discovery 自动添加节点标签进行部署
    • 以独立模式部署 gpu-feature-discovery
  • 通过 helm install 并直接指向 helm 包 URL 进行部署
• 本地构建和运行
  • 使用 Docker
    • 构建
    • 运行
  • 不使用 Docker
    • 构建
    • 运行
• 变更日志
• 问题与贡献
  • 版本控制
  • 使用设备插件升级 Kubernetes

关于

适用于 Kubernetes 的 NVIDIA 设备插件是一个 DaemonSet，它允许您自动：

• 暴露集群中每个节点上的 GPU 数量
• 跟踪 GPU 的健康状况
• 在您的 Kubernetes 集群中运行启用了 GPU 的容器。

此仓库包含 NVIDIA 对 Kubernetes 设备插件 的官方实现。 自 v0.15.0 版本起，该仓库还包含了 GPU 功能发现标签的实现， 有关 GPU 功能发现的更多信息，请参阅 此处。

请注意以下几点：

• NVIDIA 设备插件 API 自 Kubernetes v1.10 起处于测试阶段。
• 当前 NVIDIA 设备插件尚缺乏：
  • 全面的 GPU 健康检查功能
  • GPU 清理功能
• 仅对官方 NVIDIA 设备插件提供支持（而不包括其分支或其他变体）。

先决条件

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

• NVIDIA 驱动程序 ~= 384.81
• nvidia-docker >= 2.0 或 nvidia-container-toolkit >= 1.7.0（若要在基于 Tegra 的系统上使用集成 GPU，则需 >= 1.11.0）
• 将 nvidia-container-runtime 配置为默认的底层运行时
• Kubernetes 版本 >= 1.10

快速入门

准备您的 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

有关安装和开始使用 NVIDIA Container Toolkit 的说明，请参阅安装指南。

同时请注意针对以下运行时的配置说明：

• containerd
• CRI-O
• docker（已弃用）

请记住，在应用配置更改后，需重启每个运行时。

如果应将 nvidia 运行时代理设置为默认运行时（例如对于非 CRI 的 Docker 版本），则必须在上述命令中包含 --set-as-default 参数。若未执行此操作，则需要定义一个 RuntimeClass：

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
handler: nvidia

关于 CRI-O 配置的注意事项

当使用 CRI-O 运行 kubernetes 时，需添加配置文件以将 nvidia-container-runtime 设置为默认的底层 OCI 运行时，文件路径为 /etc/crio/crio.conf.d/99-nvidia.conf。该文件将优先于默认的 crun 配置文件 /etc/crio/crio.conf.d/10-crun.conf：

[crio]

  [crio.runtime]
    default_runtime = "nvidia"

    [crio.runtime.runtimes]

      [crio.runtime.runtimes.nvidia]
        runtime_path = "/usr/bin/nvidia-container-runtime"
        runtime_type = "oci"

如链接文档所述，此文件可使用 nvidia-ctk 命令自动生成：

sudo nvidia-ctk runtime configure --runtime=crio --set-as-default --config=/etc/crio/crio.conf.d/99-nvidia.conf

由于 CRI-O 默认使用 crun 作为底层 OCI 运行时，因此需要在 /etc/nvidia-container-runtime/config.toml 文件中将 crun 添加到 nvidia-container-runtime 的运行时列表中：

[nvidia-container-runtime]
runtimes = ["crun", "docker-runc", "runc"]

然后重启 CRI-O：

sudo systemctl restart crio

在 Kubernetes 中启用 GPU 支持

在集群中的所有 GPU 节点上完成上述配置后，可以通过部署以下 DaemonSet 来启用 GPU 支持：

kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.17.1/deployments/static/nvidia-device-plugin.yml

注意： 这是一个简单的静态 DaemonSet，旨在演示 nvidia-device-plugin 的基本功能。在生产环境中部署插件时，请参阅下方关于通过 Helm 部署的说明。

运行 GPU 作业

部署 DaemonSet 后，容器现在可以使用 nvidia.com/gpu 资源类型来请求 NVIDIA GPU：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: gpu-pod
spec:
  restartPolicy: Never
  containers:
    - name: cuda-container
      image: nvcr.io/nvidia/k8s/cuda-sample:vectoradd-cuda12.5.0
      resources:
        limits:
          nvidia.com/gpu: 1 # 请求 1 个 GPU
  tolerations:
  - key: nvidia.com/gpu
    operator: Exists
    effect: NoSchedule
EOF

$ kubectl logs gpu-pod
[向量加法，共 50000 个元素]
将输入数据从主机内存复制到 CUDA 设备
CUDA 内核启动，包含 196 个线程块，每块 256 个线程
将输出数据从 CUDA 设备复制回主机内存
测试通过
完成

[!WARNING]
如果在使用设备插件时未请求 GPU，插件会将机器上的所有 GPU 暴露给容器。

配置 NVIDIA 设备插件二进制文件

NVIDIA 设备插件具有多个可配置选项。这些选项可以通过命令行标志、环境变量或在启动设备插件时使用配置文件进行配置。下面我们将解释每个选项的具体含义以及如何直接对插件二进制文件进行配置。接下来的部分将说明如何通过 helm 部署插件时设置这些配置。

作为命令行标志或环境变量

标志	环境变量	默认值
--mig-strategy	$MIG_STRATEGY	"none"
--fail-on-init-error	$FAIL_ON_INIT_ERROR	true
--nvidia-driver-root	$NVIDIA_DRIVER_ROOT	"/"
--pass-device-specs	$PASS_DEVICE_SPECS	false
--device-list-strategy	$DEVICE_LIST_STRATEGY	"envvar"
--device-id-strategy	$DEVICE_ID_STRATEGY	"uuid"
--config-file	$CONFIG_FILE	""

作为配置文件

version: v1
flags:
  migStrategy: "none"
  failOnInitError: true
  nvidiaDriverRoot: "/"
  plugin:
    passDeviceSpecs: false
    deviceListStrategy: "envvar"
    deviceIDStrategy: "uuid"

注意： 配置文件中有一个明确的 plugin 部分，因为它是设备插件与 gpu-feature-discovery 共享的配置。plugin 部分内的所有选项仅适用于设备插件，而该部分之外的选项则是共享的。

配置选项详情

MIG_STRATEGY: 用于在支持 MIG 的 GPU 上暴露 MIG 设备的所需策略

[none | single | mixed] (默认 'none')

MIG_STRATEGY 选项配置守护进程集，使其能够在支持 MIG 的 GPU 上暴露多实例 GPU (MIG)。有关这些策略的具体内容及其使用方式的更多信息，请参阅 在 Kubernetes 中支持多实例 GPU (MIG)。

注意： 当 MIG_STRATEGY 设置为 mixed 时，您将获得额外的资源，格式为 nvidia.com/mig-<slice_count>g.<memory_size>gb，您可以在 Pod 规范中设置这些资源，以访问特定的 MIG 设备。

FAIL_ON_INIT_ERROR: 如果初始化过程中遇到错误，则使插件失败；否则无限期阻塞

(默认 'true')

当设置为 true 时，如果初始化过程中遇到错误，FAIL_ON_INIT_ERROR 选项会使插件失败。当设置为 false 时，它会打印错误信息，并使插件无限期阻塞，而不是失败。无限期阻塞遵循旧版语义，允许插件成功部署到没有 GPU 的节点上（且本不应配备 GPU 的节点），而不会抛出错误。这样，您可以盲目地将带有该插件的守护进程集部署到集群中的所有节点，无论它们是否配备 GPU，都不会遇到错误。然而，这样做意味着无法检测到本应配备 GPU 的节点上是否存在实际错误。现在，默认行为是在初始化错误时失败，所有新部署都应采用此设置。

NVIDIA_DRIVER_ROOT: NVIDIA 驱动程序安装的根路径

(默认 '/')

当 NVIDIA 驱动程序直接安装在主机上时，应将其设置为 '/'。当驱动程序安装在其他位置时（例如通过驱动容器），则应将其设置为驱动程序安装的根文件系统路径（例如 '/run/nvidia/driver'）。

注意： 此选项仅在与下面描述的 $PASS_DEVICE_SPECS 选项结合使用时才需要。它指示插件在作为设备规格返回的任何设备文件路径前添加哪个前缀。

PASS_DEVICE_SPECS: 将分配给容器的任何 NVIDIA 设备的路径和所需的设备节点权限传递给插件

(默认 'false')

此选项的存在仅是为了使设备插件能够与 Kubernetes 中的 CPUManager 互操作。设置此标志还需要以提升的权限部署守护进程集，因此只有在确实需要与 CPUManager 互操作时才应启用。

DEVICE_LIST_STRATEGY: 将设备列表传递给底层运行时的所需策略

[envvar | volume-mounts | cdi-annotations | cdi-cri ] (默认 'envvar')

注意：可以指定多种设备列表策略（以逗号分隔的列表形式）。

DEVICE_LIST_STRATEGY 标志允许用户选择插件用于通告分配给容器的 GPU 列表所采用的策略。可能的值包括：

• envvar（默认）：使用 此处 描述的 NVIDIA_VISIBLE_DEVICES 环境变量来选择由 NVIDIA 容器运行时注入的设备。
• volume-mounts：将设备列表作为一组卷挂载传递，而不是作为环境变量传递，以指示 NVIDIA 容器运行时注入这些设备。有关此策略背后的原因的详细信息，请参阅 此处。
• cdi-annotations：使用 CDI 注解来选择要注入的设备。请注意，这不需要 NVIDIA 容器运行时，但需要支持 CDI 的容器引擎。
• cdi-cri：使用 CRI 字段 CDIDevices 来选择要注入的 CDI 设备。这需要 Kubernetes 支持将这些请求通过 CRI 转发到支持 CDI 的容器引擎。

DEVICE_ID_STRATEGY: 将设备 ID 传递给底层运行时的所需策略

[uuid | index] (默认 'uuid')

DEVICE_ID_STRATEGY 标志允许用户选择插件用于传递分配给容器的 GPU 设备 ID 所采用的策略。传统上，设备 ID 是以 GPU 的 UUID 形式传递的。此标志允许用户决定是使用 GPU 的 UUID 还是 GPU 的索引（如 nvidia-smi 输出所示）作为传递给底层运行时的标识符。在某些情况下，例如当由插件分配了 GPU 的 Pod 重启后连接到不同的物理 GPU 时，使用索引可能是更合适的选择。

CONFIG_FILE: 让插件指向一个配置文件，而不是依赖命令行参数或环境变量

(默认 '')

每个选项的优先级顺序是：(1) 命令行参数，(2) 环境变量，(3) 配置文件。这样，用户可以使用预定义的配置文件，然后在启动时覆盖其中的值。如下所述，可以通过 helm 部署时使用 ConfigMap 将插件指向所需的配置文件。

GPU 共享访问

NVIDIA 设备插件可通过其配置文件中的一组扩展选项实现 GPU 的超量分配。有两种共享模式可供选择：时间片轮转和 MPS。

[!NOTE] 时间片轮转和 MPS 是互斥的。

在时间片轮转模式下，CUDA 时间片技术用于让共享同一 GPU 的工作负载相互交错执行。然而，对于从同一 GPU 分配副本的工作负载，并未采取特殊隔离措施，每个工作负载都可以访问 GPU 内存，并且与所有其他工作负载处于相同的故障域中（这意味着如果其中一个工作负载崩溃，所有工作负载都会崩溃）。

在 MPS 模式下，使用一个控制守护进程来管理对共享 GPU 的访问。与时间片轮转不同，MPS 实施空间分区，允许显式划分内存和计算资源，并对每个工作负载强制实施这些限制。

无论是时间片轮转还是 MPS，同一种共享方法都会应用于节点上的所有 GPU。您无法按单个 GPU 配置共享策略。

使用 CUDA 时间片轮转

使用时间片轮转进行共享的扩展选项如下所示：

version: v1
sharing:
  timeSlicing:
    renameByDefault: <bool>
    failRequestsGreaterThanOne: <bool>
    resources:
    - name: <resource-name>
      replicas: <num-replicas>
    ...

也就是说，对于 sharing.timeSlicing.resources 下的每一种命名资源，现在可以为该资源类型指定副本数。这些副本代表将为该资源类型所表示的 GPU 分配的共享访问次数。

如果 renameByDefault=true，那么每种资源将以 <resource-name>.shared 的名称进行通告，而不是简单地使用 <resource-name>。

如果 failRequestsGreaterThanOne=true，则当容器请求超过一个共享资源时，插件会拒绝为其分配任何共享资源。该容器的 Pod 将因 UnexpectedAdmissionError 而失败，需要手动删除、更新并重新部署。

例如：

version: v1
sharing:
  timeSlicing:
    resources:
    - name: nvidia.com/gpu
      replicas: 10

如果将此配置应用于一台拥有 8 块 GPU 的节点，插件现在将向 Kubernetes 宣告 80 个 nvidia.com/gpu 资源，而不是 8 个。

$ kubectl describe node
...
Capacity:
  nvidia.com/gpu: 80
...

同样，如果应用以下配置到节点上，则会向 Kubernetes 宣告 80 个 nvidia.com/gpu.shared 资源，而不是 8 个 nvidia.com/gpu 资源。

version: v1
sharing:
  timeSlicing:
    renameByDefault: true
    resources:
    - name: nvidia.com/gpu
      replicas: 10
    ...

$ kubectl describe node
...
Capacity:
  nvidia.com/gpu.shared: 80
...

在这两种情况下，插件都会简单地为每块 GPU 创建 10 个引用，并无差别地将其分配给所有提出请求的用户。

如果在上述任一配置中设置了 failRequestsGreaterThanOne=true，而用户在其 Pod 规范中请求超过一个 nvidia.com/gpu 或 nvidia.com/gpu.shared 资源，则该容器将失败，并出现如下错误：

$ kubectl describe pod gpu-pod
...
Events:
  Type     Reason                    Age   From               Message
  ----     ------                    ----  ----               -------
  Warning  UnexpectedAdmissionError  13s   kubelet            Allocate failed due to rpc error: code = Unknown desc = request for 'nvidia.com/gpu: 2' too large: maximum request size for shared resources is 1, which is unexpected
...

注意： 与“普通”GPU 请求不同，请求多个共享GPU 并不意味着您将获得按比例分配的计算能力。它仅仅表示您将获得与其他客户端共享的 GPU（每个客户端都可以在其底层 GPU 上自由运行任意数量的进程）。在底层，CUDA 会简单地为所有客户端的所有 GPU 进程平均分配时间片。failRequestsGreaterThanOne 标志旨在帮助用户理解这一微妙之处，通过将 1 的请求视为访问请求，而非独占资源请求。建议设置 failRequestsGreaterThanOne=true，但默认值为 false，以保持向后兼容性。

截至目前，唯一支持时间切片的资源是 nvidia.com/gpu，以及通过采用混合 MIG 策略配置节点后产生的任何资源类型。

例如，T4 卡上的所有可时间切片资源为：

nvidia.com/gpu

而 A100 40GB 卡上的所有可时间切片资源为：

nvidia.com/gpu
nvidia.com/mig-1g.5gb
nvidia.com/mig-2g.10gb
nvidia.com/mig-3g.20gb
nvidia.com/mig-7g.40gb

同样，在 A100 80GB 卡上，这些资源将是：

nvidia.com/gpu
nvidia.com/mig-1g.10gb
nvidia.com/mig-2g.20gb
nvidia.com/mig-3g.40gb
nvidia.com/mig-7g.80gb

使用 CUDA MPS

[!WARNING] 自设备插件 v0.15.0 版本起，MPS 支持被视为实验性功能。有关详细信息，请参阅 发行说明。

[!NOTE] 目前，在启用了 MIG 的设备上不支持使用 MPS 进行资源共享。

使用 MPS 进行资源共享的扩展选项如下所示：

version: v1
sharing:
  mps:
    renameByDefault: <bool>
    resources:
    - name: <resource-name>
      replicas: <num-replicas>
    ...

也就是说，对于 sharing.mps.resources 下的每一种命名资源，可以为该资源类型指定副本数。与时间切片类似，这些副本代表将为与该资源类型关联的 GPU 分配的共享访问次数。然而，与时间切片不同，每个客户端（即每个分区）允许使用的内存量由 MPS 控制守护进程管理，并被限制为总设备内存的相等份额。除了控制每个客户端可消耗的内存量外，MPS 控制守护进程还会限制客户端可消耗的计算能力。

如果 renameByDefault=true，那么每种资源将以 <resource-name>.shared 的名称进行通告，而不是简单地使用 <resource-name>。

例如：

version: v1
sharing:
  mps:
    resources:
    - name: nvidia.com/gpu
      replicas: 10

如果将此配置应用于一台拥有 8 块 GPU 的节点，插件现在将向 Kubernetes 宣告 80 个 nvidia.com/gpu 资源，而不是 8 个。

$ kubectl describe node
...
Capacity:
  nvidia.com/gpu: 80
...

同样，如果应用以下配置到节点上，则会向 Kubernetes 宣告 80 个 nvidia.com/gpu.shared 资源，而不是 8 个 nvidia.com/gpu 资源。

version: v1
sharing:
  mps:
    renameByDefault: true
    resources:
    - name: nvidia.com/gpu
      replicas: 10
    ...

$ kubectl describe node
...
Capacity:
  nvidia.com/gpu.shared: 80
...

此外，这些资源——无论是 nvidia.com/gpu 还是 nvidia.com/gpu.shared——都将访问 GPU 总内存和计算资源的相同份额（1/10）。

注意：截至目前，MPS 仅支持 nvidia.com/gpu 资源，且仅限于完整的 GPU。

IMEX 支持

NVIDIA GPU 设备插件可以配置为将 IMEX 通道注入到工作负载中。

此可选行为是全局性的，会影响所有工作负载，并由 imex.channelIDs 和 imex.required 配置选项控制。

imex.channelIDs	imex.required	效果
[]	*	（默认）不会向工作负载请求添加任何 IMEX 通道。请注意，在这种情况下，imex.required 字段不起作用
[0]	false	如果 NVIDIA GPU 设备插件能够发现所请求的 IMEX 通道（0），则该通道会被添加到每个工作负载请求中。如果无法发现该通道，则不会向工作负载请求添加任何通道。
[0]	true	如果 NVIDIA GPU 设备插件能够发现所请求的 IMEX 通道（0），则该通道会被添加到每个工作负载请求中。如果无法发现该通道，由于该通道被标记为“必需”，将会引发错误。

注意：目前有效的 imex.channelIDs 配置只有 [] 和 [0]。

为了使运行中的容器化 NVIDIA GPU 设备插件能够成功发现可用的 IMEX 通道，相应的设备节点必须对容器可见。

标签目录

NVIDIA 设备插件会读取和写入多种标签，这些标签既可用作配置元素，也可用作信息性元素。下表记录并描述了每个标签及其用途。有关 GFD 添加的标签，请参阅相关表格 此处。

标签名	描述	示例
nvidia.com/device-plugin.config	指定应用于节点的配置。通过应用此标签可以进行节点级别的配置。有关详细信息，请参阅 使用节点标签更新节点级配置。	my-mps-config
nvidia.com/gpu.sharing-strategy	指定共享策略。默认值为 none，表示不共享。其他值包括 mps 和 time-slicing。	time-slicing
nvidia.com/mig.capable	指定节点上的任何设备是否支持 MIG。	false
nvidia.com/mps.capable	指定节点上的设备是否已配置为 MPS。	false
nvidia.com/vgpu.present	指定节点上的设备是否使用 vGPU。	false
nvidia.com/vgpu.host-driver-branch	指定底层虚拟机管理程序上的 vGPU 主机驱动程序分支。	r550_40
nvidia.com/vgpu.host-driver-version	指定底层虚拟机管理程序上的 vGPU 主机驱动程序版本。	550.54.16

通过 helm 部署

部署设备插件的首选方法是使用 helm 以守护进程集的形式进行部署。安装 helm 的说明可以在此处找到： 这里。

首先设置插件的 helm 仓库并按如下方式更新：

helm repo add nvdp https://nvidia.github.io/k8s-device-plugin
helm repo update

然后验证插件的最新版本（v0.17.1）是否可用：

$ helm search repo nvdp --devel
NAME                     	  CHART VERSION  APP VERSION	DESCRIPTION
nvdp/nvidia-device-plugin	  0.17.1	 0.17.1		A Helm chart for ...

一旦该仓库更新完毕，您就可以开始从其中安装软件包来部署 nvidia-device-plugin Helm 图表。

最基本的安装命令（不带任何选项）如下：

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --version 0.17.1

注意：只有当这是预发布版本（例如 <version>-rc.1）时，才需要在 helm search repo 中传递 --devel 标志，以及在 helm upgrade -i 中传递 --version 标志。正式发布的版本将不会显示此标志。

配置设备插件的 helm 图表

适用于插件最新版本（v0.17.1）的 helm 图表包含许多可自定义的值。

在 v0.12.0 之前，最常用的值是与插件二进制文件的命令行选项直接对应的那些。自 v0.12.0 起，设置这些选项的首选方法是通过 ConfigMap。原始值的主要用途是在需要时覆盖 ConfigMap 中的某个选项。以下将更详细地讨论这两种方法。

可设置的完整值列表请见： 此处。

通过 ConfigMap 向插件传递配置

通常，我们提供一种机制，可以将 多个 配置文件传递给插件的 helm 图表，并且可以通过节点标签选择应将哪个配置文件应用于特定节点。

这样，可以使用单个图表部署各个组件，但可以在集群中的不同节点上应用自定义配置。

有两种方法可以为插件提供 ConfigMap：

1. 通过对外部预定义 ConfigMap 的引用
2. 作为一组命名的配置文件，构建与图表关联的集成 ConfigMap

这些可以通过图表值 config.name 和 config.map 分别进行设置。 在这两种情况下，都可以将 config.default 设置为指向 ConfigMap 中的一个命名配置， 从而为未通过节点标签自定义的节点提供默认配置（稍后会详细介绍）。

单个配置文件示例

例如，在本地文件系统上创建一个有效的配置文件，如下所示：

cat << EOF > /tmp/dp-example-config0.yaml
version: v1
flags:
  migStrategy: "none"
  failOnInitError: true
  nvidiaDriverRoot: "/"
  plugin:
    passDeviceSpecs: false
    deviceListStrategy: envvar
    deviceIDStrategy: uuid
EOF

然后通过 Helm 部署设备插件（指向此配置文件并为其命名）：

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set-file config.map.config=/tmp/dp-example-config0.yaml

在后台，这将部署与插件关联的 ConfigMap，并将 dp-example-config0.yaml 文件的内容放入其中， 以 config 作为键。随后启动插件，使该配置在插件上线时生效。

如果不想让插件的 Helm Chart 自动为您创建 ConfigMap，也可以将其指向预先创建的 ConfigMap，如下所示：

kubectl create ns nvidia-device-plugin

kubectl create cm -n nvidia-device-plugin nvidia-plugin-configs \
  --from-file=config=/tmp/dp-example-config0.yaml

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set config.name=nvidia-plugin-configs

多个配置文件示例

对于多个配置文件，操作步骤类似。

创建第二个配置文件，内容如下：

cat << EOF > /tmp/dp-example-config1.yaml
version: v1
flags:
  migStrategy: "mixed" # 仅与 config0.yaml 不同
  failOnInitError: true
  nvidiaDriverRoot: "/"
  plugin:
    passDeviceSpecs: false
    deviceListStrategy: envvar
    deviceIDStrategy: uuid
EOF

然后再次通过 Helm 部署设备插件（同时指向两个配置文件，并指定默认配置）：

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set config.default=config0 \
  --set-file config.map.config0=/tmp/dp-example-config0.yaml \
  --set-file config.map.config1=/tmp/dp-example-config1.yaml

同样地，如果需要，也可以使用预先创建的 ConfigMap 来完成此操作：

kubectl create ns nvidia-device-plugin

kubectl create cm -n nvidia-device-plugin nvidia-plugin-configs \
  --from-file=config0=/tmp/dp-example-config0.yaml \
  --from-file=config1=/tmp/dp-example-config1.yaml

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set config.default=config0 \
  --set config.name=nvidia-plugin-configs

注意： 如果未显式设置 config.default 标志，则会在其中一个配置名称设置为 'default' 时， 从该配置中推断出默认值。如果两者均未设置，则部署将失败，除非仅提供 _一个 _ 配置文件。 在这种情况下，由于没有其他选择，系统会自动将该配置选为默认配置。

使用节点标签更新每个节点的配置

在此设置下，所有节点上的插件默认都会配置为使用 config0。然而，可以通过设置以下标签来更改应用的配置：

kubectl label nodes <node-name> –-overwrite \
  nvidia.com/device-plugin.config=<config-name>

例如，为所有安装了 T4 GPU 的节点应用自定义配置，可以执行以下命令：

kubectl label node \
  --overwrite \
  --selector=nvidia.com/gpu.product=TESLA-T4 \
  nvidia.com/device-plugin.config=t4-config

注意： 可以在插件启动之前或之后应用此标签，以使所需的配置在节点上生效。 每当该标签的值发生变化时，插件会立即更新以使用新的配置。如果设置为未知值，则会跳过重新配置。 如果该标签被取消设置，则会回退到默认配置。

设置其他 Helm Chart 值

如前所述，设备插件的 Helm Chart 仍然提供了直接用于设置插件配置选项的值， 而无需使用 ConfigMap。这些值仅应用于设置全局适用的选项（这些选项不应再嵌入到由 ConfigMap 提供的配置文件集中）， 或者根据需要覆盖这些选项。

这些值如下：

  migStrategy:
      在支持 MIG 的 GPU 上暴露 MIG 设备时所采用的策略
      [none | single | mixed]（默认值为“none”）
  failOnInitError:
      如果初始化过程中遇到错误则使插件失败，否则无限期阻塞
      （默认值为‘true’）
  compatWithCPUManager:
      以提升的权限运行，以兼容静态 CPUManager 策略
      （默认值为‘false’）
  deviceListStrategy:
      向底层运行时传递设备列表时所采用的策略
      [envvar | volume-mounts | cdi-annotations | cdi-cri]（默认值为“envvar”）
  deviceIDStrategy:
      向底层运行时传递设备 ID 时所采用的策略
      [uuid | index]（默认值为“uuid”）
  nvidiaDriverRoot:
      NVIDIA 驱动程序安装的根路径（常见值为 '/' 或 '/run/nvidia/driver'）

注意： 没有直接映射到插件 PASS_DEVICE_SPECS 配置选项的值。取而代之的是提供了一个名为 compatWithCPUManager 的值， 它既将插件的 PASS_DEVICE_SPECS 选项设置为真，又确保插件以提升的权限启动， 以保证与 CPUManager 的良好兼容性。

除了这些针对插件的自定义配置选项之外，通常还会覆盖的其他标准 Helm Chart 值包括：

runtimeClassName:
  要使用的 runtimeClassName，适用于具有多个运行时的集群。（典型值为‘nvidia’）

请查看 values.yaml 文件，以了解设备插件的所有可覆盖参数。

设置这些选项的示例包括：

启用与 CPUManager 的兼容性，并请求 100 毫秒的 CPU 时间以及 512MB 的内存限制。

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set compatWithCPUManager=true \
  --set resources.requests.cpu=100m \
  --set resources.limits.memory=512Mi

启用与 CPUManager 和 mixed migStrategy 的兼容性。

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set compatWithCPUManager=true \
  --set migStrategy=mixed

使用 gpu-feature-discovery 自动添加节点标签进行部署

自 v0.12.0 起，设备插件的 Helm Chart 已集成对 gpu-feature-discovery (GFD) 的支持。您可以使用 GFD 自动为节点上可用的 GPU 集合生成标签。其底层利用了 Node Feature Discovery 来完成这一标签化工作。

要启用此功能，只需在 Helm 安装时设置 gfd.enabled=true 即可。

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version=0.17.1 \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set gfd.enabled=true

在后台，这也会部署 node-feature-discovery (NFD)，因为它是 GFD 的先决条件。如果您集群中已经部署了 NFD，并且不希望此次安装将其引入，可以通过设置 nfd.enabled=false 来禁用它。

除了 GFD 应用的标准节点标签外，在使用上述描述的分时或 MPS 扩展部署插件时，还会包含以下标签：

nvidia.com/<resource-name>.replicas = <num-replicas>

此外，如果 renameByDefault=false，nvidia.com/<resource-name>.product 将按如下方式修改：

nvidia.com/<resource-name>.product = <product name>-SHARED

借助这些标签，用户可以像选择不同型号的 GPU 一样，选择共享或非共享的 GPU。也就是说，SHARED 注解确保可以使用 nodeSelector 将 Pod 吸引到具有共享 GPU 的节点上。

由于将 renameByDefault=true 已经在资源名称中编码了该资源是共享的事实，因此无需再通过 SHARED 注解来标记产品名称。用户只需在其 Pod 规范中请求所需的共享资源即可找到它们。

注意：当使用 renameByDefault=false 并且 migStrategy=single 时，MIG 配置文件名和新的 SHARED 注解都会附加到产品名称上，例如：

nvidia.com/gpu.product = A100-SXM4-40GB-MIG-1g.5gb-SHARED

以独立模式部署 gpu-feature-discovery

自 v0.15.0 起，设备插件的 Helm Chart 已集成对 gpu-feature-discovery 的支持。

以独立模式部署 gpu-feature-discovery 时，首先需要设置并更新插件的 Helm 仓库，具体步骤如下：

helm repo add nvdp https://nvidia.github.io/k8s-device-plugin
helm repo update

然后验证插件的最新版本（v0.17.1）是否可用（请注意，这包括 GFD Chart）：

helm search repo nvdp --devel
NAME                     	  CHART VERSION  APP VERSION	DESCRIPTION
nvdp/nvidia-device-plugin	  0.17.1	 0.17.1		A Helm chart for ...

一旦该仓库更新完毕，您就可以开始从其中安装软件包，以独立模式部署 gpu-feature-discovery 组件。

最基本的无选项安装命令如下：

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --version 0.17.1 \
  --namespace gpu-feature-discovery \
  --create-namespace \
  --set devicePlugin.enabled=false

禁用 NFD 的自动部署，并在默认命名空间中使用混合 MIG 策略运行。

helm upgrade -i nvdp nvdp/nvidia-device-plugin \
    --version=0.17.1 \
    --set allowDefaultNamespace=true \
    --set nfd.enabled=false \
    --set migStrategy=mixed \
    --set devicePlugin.enabled=false

注意： 只有在使用预发布版本（例如 <version>-rc.1）时，才需要在 helm search repo 中添加 --devel 标志，以及在 helm upgrade -i 中添加 --version 标志。正式发布的版本则无需这些标志。

通过 Helm install 直接使用 Helm 包的 URL 进行部署

如果您不想从 nvidia-device-plugin Helm 仓库安装，可以直接针对插件 Helm 包的 tarball 运行 helm install。下面的示例安装的是与上述方法相同的 Chart，只是使用 Helm Chart 的直接 URL 而不是通过 Helm 仓库。

使用默认值运行：

helm upgrade -i nvdp \
  --namespace nvidia-device-plugin \
  --create-namespace \
  https://nvidia.github.io/k8s-device-plugin/stable/nvidia-device-plugin-0.17.1.tgz

在本地构建和运行

接下来的部分重点介绍如何在本地构建并运行设备插件。这仅适用于开发和测试，大多数用户并不需要。本节假设您正在使用最新的发布标签（即 v0.17.1），但也可以轻松修改以适应任何可用的标签或分支。

使用 Docker

构建

选项 1：从 Docker Hub 拉取预构建的镜像：

docker pull nvcr.io/nvidia/k8s-device-plugin:v0.17.1
docker tag nvcr.io/nvidia/k8s-device-plugin:v0.17.1 nvcr.io/nvidia/k8s-device-plugin:devel

选项 2：无需克隆仓库直接构建：

docker build \
  -t nvcr.io/nvidia/k8s-device-plugin:devel \
  -f deployments/container/Dockerfile.ubuntu \
  https://github.com/NVIDIA/k8s-device-plugin.git#v0.17.1

选项 3：如果您想修改代码：

git clone https://github.com/NVIDIA/k8s-device-plugin.git && cd k8s-device-plugin
docker build \
  -t nvcr.io/nvidia/k8s-device-plugin:devel \
  -f deployments/container/Dockerfile.ubuntu \
  .

运行

不兼容 CPUManager 静态策略时：

docker run \
  -it \
  --security-opt=no-new-privileges \
  --cap-drop=ALL \
  --network=none \
  -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
  nvcr.io/nvidia/k8s-device-plugin:devel

兼容 CPUManager 静态策略时：

docker run \
  -it \
  --privileged \
  --network=none \
  -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
  nvcr.io/nvidia/k8s-device-plugin:devel --pass-device-specs

不使用 Docker

构建

C_INCLUDE_PATH=/usr/local/cuda/include LIBRARY_PATH=/usr/local/cuda/lib64 go build

运行

不支持 CPUManager 静态策略时：

./k8s-device-plugin

支持 CPUManager 静态策略时：

./k8s-device-plugin --pass-device-specs

更改日志

请参阅 更改日志

问题与贡献

查看贡献文档！

• 您可以通过 提交新问题 来报告 bug。
• 您也可以通过打开一个 拉取请求 来做出贡献。

版本管理

在 v1.10 之前，设备插件的版本号必须与 Kubernetes 的版本号完全一致。随着设备插件被提升为 Beta 状态，这一要求不再适用。然而，我们很快发现这种版本管理方式让用户感到非常困惑，因为他们仍然期望看到每个 Kubernetes 版本对应的设备插件版本。

这种版本管理方式适用于标签 v1.8、v1.9、v1.10、v1.11、v1.12。

现在，我们已将版本管理改为遵循 语义化版本控制。首个按照此方案标记的版本为 v0.0.0。

今后，设备插件的主版本号仅会在设备插件 API 发生变化时才会更新。例如，设备插件 API 的 v1beta1 版本对应于设备插件的 v0.x.x 版本。如果设备插件 API 推出新的 v2beta2 版本，那么设备插件的主版本号将升级到 1.x.x。

截至目前，Kubernetes >= v1.10 的设备插件 API 是 v1beta1。如果您使用的 Kubernetes 版本大于等于 1.10，您可以部署任何大于 v0.0.0 的设备插件版本。

在使用设备插件的情况下升级 Kubernetes

在部署了设备插件的情况下升级 Kubernetes 并不需要对您的工作流程进行任何特殊调整。API 已经进行了版本管理，并且相当稳定（尽管不能保证完全向后兼容）。从 Kubernetes 1.10 开始，您可以使用设备插件的 v0.3.0 版本来执行升级，而无需部署不同版本的设备插件。节点在升级完成后重新上线时，GPU 将会自动重新注册。

然而，升级设备插件本身则是一项更为复杂的任务。建议您先驱逐 GPU 任务，因为我们无法保证 GPU 任务能够在滚动升级过程中正常运行。不过，我们会尽最大努力在升级过程中保留 GPU 任务。

NVIDIA k8s-device-plugin 快速上手指南

本指南帮助您在 Kubernetes 集群中快速部署 NVIDIA GPU 支持，使容器能够请求和使用 GPU 资源。

环境准备

在开始之前，请确保您的集群节点满足以下前置条件：

• 操作系统: Linux (推荐 Debian/Ubuntu 或 CentOS/RHEL)
• NVIDIA 驱动: 版本 ~= 384.81 或更高
• 容器运行时工具:
  • nvidia-container-toolkit >= 1.7.0
  • 若需在 Tegra 系统上使用集成 GPU，需 >= 1.11.0
• Kubernetes: 版本 >= 1.10
• 运行时配置: 必须将 nvidia-container-runtime 配置为默认的低层级运行时。

注意：以下步骤需要在集群中所有包含 GPU 的节点上执行。

安装 NVIDIA Container Toolkit

以 Debian/Ubuntu 系统为例，安装并配置 toolkit：

1. 添加仓库密钥和源：

   curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit.gpg
   curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
     sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit.gpg] https://#g' | \
     sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
   

2. 安装工具包：

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

3. 配置容器运行时： 根据您使用的运行时（docker, containerd 或 CRI-O）运行配置命令。

   针对 containerd (推荐):

   sudo nvidia-ctk runtime configure --runtime=containerd --set-as-default
   sudo systemctl restart containerd
   

   针对 CRI-O:

   sudo nvidia-ctk runtime configure --runtime=crio --set-as-default
   sudo systemctl restart crio
   

   (注：若使用 CRI-O，还需确保 /etc/nvidia-container-runtime/config.toml 中包含 runtimes = ["crun", "runc"])

   针对 docker (已弃用但仍可用):

   sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
   sudo systemctl restart docker
   

安装步骤

确认所有 GPU 节点已完成上述配置后，即可在 Kubernetes 中部署 Device Plugin。

方式一：使用静态 YAML 部署（快速测试）

这是最简单的部署方式，适用于快速验证功能：

kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.17.1/deployments/static/nvidia-device-plugin.yml

提示：生产环境建议使用 Helm 进行部署以便更好地管理配置，详见官方文档。

方式二：验证部署

部署完成后，插件会以 DaemonSet 形式运行。检查状态：

kubectl get pods -n kube-system -l app=nvidia-device-plugin

确保所有 Pod 状态为 Running。

基本使用

部署成功后，您可以在 Pod 定义中通过 nvidia.com/gpu 资源类型来请求 GPU。

运行一个简单的 GPU 任务

创建一个名为 gpu-pod.yaml 的文件或直接运行以下命令：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: gpu-pod
spec:
  restartPolicy: Never
  containers:
    - name: cuda-container
      image: nvcr.io/nvidia/k8s/cuda-sample:vectoradd-cuda12.5.0
      resources:
        limits:
          nvidia.com/gpu: 1 # 请求 1 块 GPU
  tolerations:
  - key: nvidia.com/gpu
    operator: Exists
    effect: NoSchedule
EOF

查看运行结果

等待 Pod 运行完成并查看日志：

kubectl logs gpu-pod

如果配置正确，您将看到类似以下的输出，表明 CUDA 程序已成功在 GPU 上运行：

[Vector addition of 50000 elements]
Copy input data from the host memory to the CUDA device
CUDA kernel launch with 196 blocks of 256 threads
Copy output data from the CUDA device to the host memory
Test PASSED
Done

警告：如果在 Pod 中没有设置 resources.limits.nvidia.com/gpu，Device Plugin 默认会将节点上的所有 GPU 暴露给该容器。务必明确指定所需的 GPU 数量。