昇腾NPU的DRA调度插件

文件	最后提交记录	最后更新时间
Ascend-npu-dra-plugin	update Dockerfile	11 天前
doc	支持按照容量进行动态硬切分调度	16 天前
.gitignore	add npu-dra framework	3 个月前
LICENSE	update copyright header	3 个月前
OAT.xml	fix copy right err	2 个月前
README-en.md	补充英文readme	18 天前
README-zh.md	update Dockerfile	11 天前

Ascend DRA Driver for NPUs

该驱动专为昇腾NPU设备设计，基于Kubernetes Dynamic Resource Allocation（DRA）机制，提供NPU资源的全生命周期管理，核心功能如下：

支持昇腾NPU设备的自动资源发现与集群上报，实时同步设备状态。
支持昇腾910B、910C、310P系列芯片。
支持通过DeviceClass结合通用表达式语言（CEL），实现NPU设备的精细化筛选。
支持通过ResourceClaim/ResourceClaimTemplate完成资源申请，实现业务Pod与ResourceSlice的精准绑定，保障资源高效分配。
支持硬切分（固定模板VNPU）功能（仅支持910B），可将整卡按模板切分为多个vNPU实例供不同业务Pod使用。
适用环境：Kubernetes 1.34 或更高版本（需提前启用动态资源分配DRA功能）。有关DRA启用的详细操作，请参考Kubernetes官方文档：https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/#enabling-dynamic-resource-allocation。

一、概述

Dynamic Resource Allocation（DRA）是Kubernetes中用于灵活管理专用设备（如NPU、GPU、TPU）的核心机制，其核心优势在于将资源配置与调度权限开放给第三方设备供应商，打破传统设备插件的局限性，实现资源的精细化、灵活化分配。如需深入了解DRA核心概念与原理，可参考以下官方文档：

Kubernetes官方DRA文档：https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/
GKE中DRA应用文档：https://cloud.google.com/kubernetes-engine/docs/concepts/about-dynamic-resource-allocation Ascend DRA驱动作为昇腾NPU与Kubernetes集群的桥梁，通过DRA Kubelet插件和验证准入webhook，实现NPU资源的全流程管理，涵盖设备发现、资源分配、CDI（容器设备接口）注入等核心能力，为Kubernetes集群中的昇腾NPU提供一站式资源管理解决方案。

二、组件说明

Ascend DRA驱动仅包含一个核心组件（ascend-npu-dra-kubeletplugin），部署简单、维护便捷，以DaemonSet形式部署在集群所有搭载昇腾NPU的节点上（使用硬切分功能时需以主机进程方式部署，详见3.2节），核心职责包括：

设备发现：自动扫描节点上的昇腾NPU设备（基于DCMI或sysfs方式），并向kubelet上报设备详情。
资源调度：响应ResourceClaim请求，完成NPU资源的分配与释放，确保资源高效利用。
硬切分功能：支持910B芯片的硬切分（固定模板VNPU）创建与删除，实现NPU资源的细粒度切分与回收。硬切分功能需以主机进程方式部署。
CDI注入：为运行NPU任务的容器注入CDI配置，保障容器能够正常访问NPU设备。
健康检查：实时监控NPU设备运行状态，及时上报设备异常，保障业务稳定性。

三、功能特性

3.1 NPU资源管理

自动设备发现：通过DCMI（设备管理接口）或sysfs文件系统，自动识别节点上的昇腾NPU设备，无需手动配置设备信息。
多芯片支持：支持昇腾910B、910C、310P系列芯片的自动发现与资源上报，适配不同型号的NPU硬件环境。
灵活资源分配：基于DRA机制，支持按业务需求灵活分配NPU资源，适配不同算力需求的工作负载。
CDI规范兼容：通过CDI（容器设备接口）向容器注入设备访问配置，确保容器与NPU设备的兼容性，简化容器部署流程。
Bus-Id设备识别：自动获取NPU设备的Bus-Id信息，作为设备唯一标识，避免设备混淆，提升资源分配准确性。

3.2 硬切分（固定模板VNPU）

硬切分功能支持将910B整卡按固定模板切分为多个vNPU实例，实现NPU资源的细粒度分配与复用。

基本约束：

仅支持昇腾910B系列芯片，910C和310P暂不支持硬切分。
使用硬切分功能时，驱动不能以DaemonSet方式部署，必须以主机进程方式启动。原因是硬切分的操作接口只能在主机上执行，容器内无法调用。
需在启动时通过--enable-hard-vnpu参数开启硬切分开关。

使用流程：

启动驱动时开启硬切分开关（--enable-hard-vnpu）。
在ResourceClaim中通过DeviceClass申请所需内存大小（memCapacity），驱动会根据申请的内存自动匹配最合适的VNPU模板。例如申请10Gi内存：

apiVersion: resource.k8s.io/v1
kind: ResourceClaimTemplate
metadata:
  name: npu-claim-template
  namespace: ascend-dra
spec:
  spec:
    devices:
      requests:
        - name: npu
          exactly:
            deviceClassName: npu.huawei.com
            capacity:
              requests:
                memCapacity: 10000   # 申请约10Gi内存，自动匹配vir10_3c_16g模板

调度器根据容量消费（ConsumedCapacity.memCapacity）完成分配。
驱动在Pod创建阶段自动通过DCMI接口创建VNPU实例，并通过CDI将VNPU设备挂载到容器。
Pod删除时，驱动自动通过DCMI接口销毁对应的VNPU实例，释放资源。

910B 内存申请与模板自动映射：

申请内存范围	自动匹配模板	实际分配
≤ 8Gi	vir05_1c_8g	8G / 1 AI Core
8Gi ~ 16Gi	vir10_3c_16g	16G / 3 AI Core

四、使用指南

以下为Ascend DRA驱动的完整部署与使用步骤，需严格按照顺序执行，确保驱动正常运行。

4.1 安装依赖项

使用Ascend DRA驱动前，需确保集群环境满足以下依赖条件，推荐使用openFuyao社区推荐版本，提升兼容性：

Kubernetes：1.34 或更高版本，且已启用DRA功能（推荐版本：v1.34.3）。
容器运行时：containerd v1.7.0 及以上版本（推荐版本：v2.1.1）。
硬件与驱动：集群节点已安装昇腾NPU硬件，且已部署对应版本的昇腾NPU驱动（确保驱动与硬件型号匹配）。

4.2 构建镜像

4.2.1 克隆代码仓库

克隆openFuyao社区的NPU DRA插件仓库，切换至指定版本分支：

  git clone -b release-1.0.x https://gitcode.com/openFuyao/npu-dra-plugin.git
  cd npu-dra-plugin

4.2.2 驱动配置参数说明

驱动支持通过以下参数进行自定义配置，适配不同集群环境，默认值可满足大多数场景需求：

--cdi-root：CDI规范文件的存储目录（默认值：/etc/cdi）。
--device-profile：设备配置文件类型（可选值：gpu / npu，默认值：npu）。
--driver-name：DRA驱动名称（需与后续DeviceClass配置保持一致）。
--kubelet-registrar-directory-path：Kubelet注册目录（用于插件与kubelet通信）。
--kubelet-plugins-directory-path：Kubelet插件目录（插件部署路径）。
--enable-hard-vnpu：是否启用硬切分功能（仅支持910B）。

4.2.3 构建容器镜像

进入驱动目录，执行以下命令构建容器镜像（可根据实际需求修改镜像名称和标签）：

# 进入驱动源码目录
cd Ascend-npu-dra-plugin
# 构建镜像（镜像名称可自定义，如ascend-npu-dra-plugin:v1.0.0）
docker build -f build/Dockerfile -t ascend-npu-dra-plugin:latest .

4.2.4 构建主机进程二进制（适用于硬切分场景）

使用硬切分功能时，驱动需以主机进程方式运行。在昇腾NPU主机上直接编译驱动二进制（需安装Go 1.24+、GCC、昇腾NPU驱动）：

cd Ascend-npu-dra-plugin
go build -o npu-dra-plugin ./cmd/ascend-npu-dra-kubeletplugin

4.3 部署驱动组件

驱动组件通过Kubernetes资源清单部署，需先修改清单中的镜像地址，确保与步骤2中构建的镜像一致，再执行部署命令。

4.3.1 DaemonSet方式部署（适用于不使用硬切分的场景）

# 部署DRA Kubelet插件（DaemonSet）
kubectl apply -f manifests/ascend-npu-dra-kubeletplugin-daemonset-template.yaml
# 部署NPU DeviceClass（用于设备筛选）
kubectl apply -f manifests/npu-deviceclass-template.yaml

4.3.2 主机进程方式部署（适用于需要使用硬切分功能的场景）

若需使用硬切分功能（仅910B支持），驱动必须以主机进程方式运行，不能使用DaemonSet部署。这是因为硬切分的操作接口只能在主机上执行（通过DCMI封装调用），容器内无法调用。

主机进程方式部署步骤:

按照4.2.4节在昇腾NPU主机上编译驱动二进制。
在主机上直接启动驱动进程,需额外传入--enable-hard-vnpu参数:

# 在主机上直接启动驱动（硬切分模式）
./npu-dra-plugin \
  --node-name=<节点名称> \
  --device-profile=npu \
  --driver-name=npu.huawei.com \
  --kubelet-registrar-directory-path=/var/lib/kubelet/plugins_registry \
  --kubelet-plugins-directory-path=/var/lib/kubelet/plugins \
  --cdi-root=/etc/cdi \
  --healthcheck-port=-1 \
  --enable-hard-vnpu=true \
  --kubeconfig=/root/.kube/config

执行以下命令，创建命名空间

kubectl create namespace ascned-dra

执行以下命令，部署NPU DeviceClass：

kubectl apply -f manifests/npu-deviceclass-template.yaml

4.4 运行工作负载

驱动部署完成后，可通过示例清单提交工作负载，验证驱动是否正常工作：

kubectl apply -f manifests/test-resourceclaimtemplate-pod-template.yaml

提交后，可通过后续“相关操作”中的命令，验证资源分配是否成功。

五、相关操作

以下命令用于查询DRA相关自定义资源（CR）信息，帮助排查驱动运行状态和资源分配情况。

5.1 查询ResourceSlice

ResourceSlice用于存储NPU设备详情，通过以下命令查询：

# 查询集群中所有ResourceSlice
kubectl get resourceslices

# 查询指定ResourceSlice的详细信息（含设备属性、容量等）
kubectl get resourceslices <resourceslice_name> -o yaml

此时可以查看所有发现设备信息，这些信息可用于CEL表达式进行设备筛选，示例如下。

apiVersion: resource.k8s.io/v1
kind: ResourceSlice
metadata:
  creationTimestamp: "2026-02-27T01:55:37Z"
  generateName: master-npu.huawei.com-
  generation: 1
  name: master-npu.huawei.com-9gv8l
  ownerReferences:
  - apiVersion: v1
    controller: true
    kind: Node
    name: master
    uid: 6ef76e72-da36-44e3-b9c3-93f44684a859
  resourceVersion: "2225369"
  uid: 0c1b399e-4fa8-4279-93f8-b92a1faeff6f
spec:
  devices:
  - attributes:
      chipName:
        string: 910B4
      numaNode:
        int: 6
      physicalId:
        int: 0
      topologyGroup:
        string: ring-0
    capacity:
      memCapacity:
        value: 32Gi
    name: npu-0
  driver: npu.huawei.com
  nodeName: master
  pool:
    generation: 1
    name: master
    resourceSliceCount: 1

5.2 查询DeviceClass

DeviceClass用于定义NPU设备类别，通过以下命令查询：

kubectl get deviceclasses

5.3 查询ResourceClaim

ResourceClaim用于记录资源申请情况，需指定命名空间查询：

kubectl get resourceclaims -n <namepspace>

六、贡献与支持

6.1 贡献指南

欢迎开发者参与驱动优化与迭代，如需贡献代码，请通过以下方式提交：

访问GitCode仓库：https://gitcode.com/openFuyao/npu-dra-plugin.git。
提交拉取请求（Pull Request），并附详细的功能说明或问题修复描述。
提交问题（Issue），反馈使用过程中遇到的Bug或功能需求。

6.2 支持渠道

如在驱动部署、使用过程中遇到问题，请在GitCode项目页面打开Issue，我们会及时响应并提供技术支持。感谢您的使用与反馈，助力Ascend DRA驱动持续优化！

项目介绍