#使用 Kueue 管理 Ascend NPU 配额

本页介绍如何使用 Alauda Build of Kueue 来管理由 Ascend Device Plugin（作为 NPU Operator 的一部分提供）暴露的 Ascend NPU 资源配额。Kueue 将 huawei.com/Ascend910 以及类似的 device-plugin 资源视为普通的可计数资源，因此用于 CPU、内存和 Nvidia GPU 的相同 ClusterQueue / ResourceFlavor / LocalQueue 模型可以直接沿用。

#前提条件

• 你已经安装了 Alauda Build of Kueue 集群插件。
• 你已经安装了 Alauda Build of NPU Operator 集群插件，并在部署表单中启用了 Driver、Ascend Device Plugin 和 Ascend Docker Runtime 组件（默认情况下它们是启用的）。这三个开关决定了集群是否会将 huawei.com/Ascend910（或 huawei.com/Ascend310P）作为 Ascend 节点上的可调度扩展资源暴露出来。有关完整操作步骤以及各部署表单开关的含义，请参见 安装 NPU Operator 。
• Ascend Device Plugin 正在报告节点上的 NPU 容量，例如 kubectl describe node <ascend-node> 在 Capacity 和 Allocatable 下都显示 huawei.com/Ascend910: <N>。
• Alauda Container Platform Web CLI 已与集群建立通信。

#操作步骤

#1. 识别 NPU 节点标签

ResourceFlavor 通过 spec.nodeLabels 选择配额适用的节点池。NPU Operator 会为其管理的每个节点添加以下标签——请选择最适合你的集群的标签：

本页后续示例使用 accelerator: huawei-Ascend910。

#2. 创建 Kueue 对象

创建一个绑定到 NPU 节点池的 ResourceFlavor、一个声明 NPU 配额的 ClusterQueue，以及一个供用户提交 Job 的命名空间中的 LocalQueue。

apiVersion: kueue.x-k8s.io/v1beta2
kind: ResourceFlavor
metadata:
  name: ascend910-flavor
spec:
  nodeLabels:
    accelerator: huawei-Ascend910
---
apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata:
  name: ascend910-cq
spec:
  namespaceSelector: {}
  resourceGroups:
  - coveredResources: ["huawei.com/Ascend910", "cpu", "memory"] 
    flavors:
    - name: ascend910-flavor
      resources:
      - name: "huawei.com/Ascend910"
        nominalQuota: 2
      - name: "cpu"
        nominalQuota: 8
      - name: "memory"
        nominalQuota: 16Gi
---
apiVersion: kueue.x-k8s.io/v1beta2
kind: LocalQueue
metadata:
  namespace: team-ascend
  name: ascend910-lq
spec:
  clusterQueue: ascend910-cq

使用 kubectl apply -f <filename>.yaml 应用该清单。

#3. 通过队列提交 NPU Job

添加 kueue.x-k8s.io/queue-name 标签，并在容器的 resources 块中请求 NPU。Kueue 内置的 batch/job 集成会以挂起状态创建 Job，并且只会在配额检查通过后解除挂起。

apiVersion: batch/v1
kind: Job
metadata:
  name: ascend-train
  namespace: team-ascend
  labels:
    kueue.x-k8s.io/queue-name: ascend910-lq
spec:
  parallelism: 1
  completions: 1
  suspend: true
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: worker
        image: <your-ascend-image>
        command: ["sh", "-c", "echo training; sleep 600"]
        resources:
          requests: { cpu: 100m, memory: 256Mi, "huawei.com/Ascend910": 2 } 
          limits:   { cpu: "1",  memory: 1Gi,   "huawei.com/Ascend910": 2 }

#4. 观察准入

向一个 nominalQuota 为 2 的队列提交两个这样的 Job，每个 Job 请求 2 个 NPU。

kubectl -n team-ascend get jobs,workloads

第一个 Job 会被准入，并以 Pod 的形式运行；该 Pod 会从 Ascend Device Plugin 获得 /dev/davinci* 设备和 ASCEND_VISIBLE_DEVICES。第二个 Job 会保持 Suspended，其 Workload 会报告配额不足：

NAME                STATUS      COMPLETIONS   DURATION   AGE
job/ascend-train    Running     0/1           5s         12s
job/ascend-train-2  Suspended   0/1                      12s

NAME                                       QUEUE          RESERVED IN    ADMITTED
workload/job-ascend-train-xxxxx            ascend910-lq   ascend910-cq   True
workload/job-ascend-train-2-yyyyy          ascend910-lq

查看被保留的 Workload 可以更明确地看到原因：

kubectl -n team-ascend get workload job-ascend-train-2-yyyyy \
  -o yaml

status.conditions 字段会报告配额不足：

status:
  conditions:
  - type: QuotaReserved
    status: "False"
    reason: Pending
    message: "couldn't assign flavors to pod set main: insufficient unused quota for huawei.com/Ascend910 in flavor ascend910-flavor, 2 more needed"

当第一个 Job 完成或被删除后，Kueue 会自动准入被保留的 Workload，解除第二个 Job 的挂起状态，并由 Ascend Device Plugin 将释放的 NPU 设备分配给其 Pod。

#注意事项

• ClusterQueue 中针对 huawei.com/Ascend910 的 nominalQuota 是独立于节点 Allocatable 进行强制限制的。如果 Allocatable 低于该配额（例如因为 device plugin 将某些芯片标记为不健康），即使 Pod 已被准入，也仍可能在 kube-scheduler 层处于 Pending，并显示 Insufficient huawei.com/Ascend910。请确保 nominalQuota ≤ 所选节点上的 Allocatable 之和。
• 相同模式也适用于 device plugin 暴露的其他 Ascend 资源名称（huawei.com/Ascend910B4、huawei.com/Ascend310P 等）。按需将它们添加到 coveredResources 和容器的 resources 块中。
• Kueue 的其他功能——公平共享、cohort、gang scheduling、preemption——都可以直接用于 NPU 资源，无需额外配置。