核心概念 on Kueue

资源规格（Resource Flavor）

Mon, 14 Mar 2022 00:00:00 +0000

集群中的资源通常不是同构的。资源可能在以下方面有所不同：

价格和可用性（例如，竞价型与按需型虚拟机）
架构（例如，x86 与 ARM CPU）
品牌和型号（例如，Radeon 7000、Nvidia A100、T4 GPU）

资源规格（ResourceFlavor）是一个表示这些资源差异的对象，并允许你通过标签、污点和容忍度将它们与集群节点关联。

注意

如果你的集群资源是同构的，你可以使用空 ResourceFlavor，而无需为自定义 ResourceFlavor 添加标签。

ResourceFlavor 容忍度实现自动调度

需要 Kubernetes 1.23 或更高版本

这种方式适合希望自动将 Pod 调度到合适节点的团队。但当集群中存在多种专用硬件（如两种不同的 nvidia.com/gpu 资源，即 T4 和 A100 GPU）时，会有一个限制：系统可能无法区分它们，Pod 可能会被调度到任意一种硬件上。

要将 ResourceFlavor 与集群中某一部分节点关联，可以在 .spec.nodeLabels 字段中配置能唯一标识这些节点的标签。如果你使用 cluster autoscaler（或类似控制器），请确保控制器在添加新节点时会添加这些标签。

为了保证 Workload 中的 Pod 运行在 Kueue 选定的 flavor 所关联的节点上，Kueue 会执行以下步骤：

集群队列（ClusterQueue）

Tue, 14 Mar 2023 00:00:00 +0000

ClusterQueue 是一个集群范围的对象，用于管理一组资源池，如 Pod、CPU、内存和硬件加速器。ClusterQueue 定义了：

ClusterQueue 管理的资源规格的配额，包括使用上限和消耗顺序。
集群中多个 ClusterQueue 之间的公平共享规则。

只有批处理管理员才应创建 ClusterQueue 对象。

一个示例 ClusterQueue 如下所示：

apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata:
  name: "cluster-queue"
spec:
  namespaceSelector: {} # 匹配所有命名空间。
  resourceGroups:
  - coveredResources: ["cpu", "memory", "pods"]
    flavors:
    - name: "default-flavor"
      resources:
      - name: "cpu"
        nominalQuota: 9
      - name: "memory"
        nominalQuota: 36Gi
      - name: "pods"
        nominalQuota: 5

只有在以下条件全部满足时，该 ClusterQueue 才会接纳工作负载：

CPU 请求总和小于等于 9。
内存请求总和小于等于 36Gi。
Pod 总数小于等于 5。

您可以将配额指定为数量。

Cohort

Wed, 16 Apr 2025 00:00:00 +0000

你好，Cohort

Cohort 使你能够组织你的配额。同一个 Cohort（或对于分层 Cohort 来说是同一个 CohortTree）中的 ClusterQueue 可以相互共享资源。最简单的 Cohort 如下：

apiVersion: kueue.x-k8s.io/v1beta2
kind: Cohort
metadata:
  name: "hello-cohort"

ClusterQueue 可以通过引用来加入此 Cohort：

apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata:
  name: "my-cluster-queue"
spec:
  cohortName: "hello-cohort"

配置配额

资源配额可以在 Cohort 级别定义（类似于为 ClusterQueue 定义的方式），并由 Cohort 内的 ClusterQueue 来消耗使用。请注意，在 Cohort 级别定义的 nominalQuota 表示除了 Cohort 内 ClusterQueue 所定义的资源之外的额外资源。Cohort 的 nominalQuota 可以被视为其内 ClusterQueue 的共享池。此外，此配额也可能根据 LendingLimit 借给父 Cohort。

弹性工作负载

Wed, 16 Apr 2025 00:00:00 +0000

Feature state alpha since Kueue v0.13

弹性工作负载（工作负载切片）

弹性工作负载扩展了 Kueue 中核心的 Workload 抽象，以支持已接受 Job 的动态扩缩，无需暂停或重新排队。这是通过使用工作负载切片实现的，工作负载切片跟踪父 Job 扩缩操作的部分分配。

此特性使得能够更响应和高效地调度适应集群容量变化的 Job，特别是在工作负载波动或资源受限的环境中。

动态扩缩

传统上，Kueue 中的 Workload 表示单一原子性的准入单元。一旦被接纳，它反映了一组固定的 Pod 副本并消耗定义的配额。如果 Job 需要扩缩，Workload 必须被暂停、移除或完全替换。

本地队列（Local Queue）

Mon, 14 Mar 2022 00:00:00 +0000

LocalQueue 是一个命名空间对象，用于将属于单个命名空间的紧密相关的工作负载进行分组。一个命名空间通常分配给组织的一个租户（团队或用户）。 LocalQueue 指向一个 ClusterQueue，并从中分配资源以运行其工作负载。

LocalQueue 定义如下所示：

apiVersion: kueue.x-k8s.io/v1beta2
kind: LocalQueue
metadata:
  namespace: team-a 
  name: team-a-queue
spec:
  clusterQueue: cluster-queue

用户将作业（Job）提交到 LocalQueue，而不是直接提交到 ClusterQueue。租户可以通过列出其命名空间中的本地队列来发现他们可以向哪些队列提交作业。该命令类似于以下内容：

kubectl get -n my-namespace localqueues
# 或者，使用别名 `queue` 或 `queues`
kubectl get -n my-namespace queues

queue 和 queues 是 localqueue 的别名。

下一步是什么？

通过本地队列启动工作负载
阅读 LocalQueue 的 API 参考

工作负载(Workload)

Mon, 14 Feb 2022 00:00:00 +0000

工作负载(Workload) 是将运行至完成的应用程序。它可以由一个或多个 Pod 组成，这些 Pod 松散或紧密耦合，作为一个整体完成任务。工作负载是 Kueue 中的准入(admission)单位。

典型的工作负载可以用 Kubernetes batch/v1.Job 来表示。因此，我们有时使用_作业(job)_一词来指代任何工作负载，而 Job 则专门指 Kubernetes API。

但是，Kueue 不直接操作 Job 对象。相反，Kueue 管理代表任意工作负载资源需求的 Workload 对象。Kueue 自动为每个 Job 对象创建一个 Workload，并同步决策和状态。

Workload 的清单如下所示：

apiVersion: kueue.x-k8s.io/v1beta2
kind: Workload
metadata:
  name: sample-job
  namespace: team-a
spec:
  active: true
  queueName: team-a-queue
  podSets:
  - count: 3
    name: main
    template:
      spec:
        containers:
        - name: container
          image: registry.k8s.io/e2e-test-images/agnhost:latest
          args: ["pause"]
          imagePullPolicy: Always
          resources:
            requests:
              cpu: "1"
              memory: 200Mi
        restartPolicy: Never

活跃状态

您可以通过设置 Active 字段来停止或恢复正在运行的工作负载。active 字段决定工作负载是否可以被准入到队列中或继续运行（如果已经被准入）。将 .spec.Active 从 true 更改为 false 将导致正在运行的工作负载被驱逐且不会重新排队。

Topology

Thu, 29 Jan 2026 00:00:00 +0000

Topology 是一个集群范围的对象，定义了数据中心内节点的层次结构。它通过提供一种使用节点标签表示组织单元（如区域、块和机架）层次结构的模型，启用了拓扑感知调度。

Topology 对象通过 ResourceFlavor 中的 .spec.topologyName 字段引用，以将规约与特定的拓扑结构关联。

Topology 定义如下所示：

apiVersion: kueue.x-k8s.io/v1beta2
kind: Topology
metadata:
  name: "default"
spec:
  levels:
  - nodeLabel: "topology.kubernetes.io/zone"
  - nodeLabel: "cloud.provider.com/topology-block"
  - nodeLabel: "cloud.provider.com/topology-rack"
  - nodeLabel: "kubernetes.io/hostname"

Topology 层级

.spec.levels 字段定义了拓扑层级的层次结构，从最高（最粗略）级别到最低（最细致）级别排序。每个层级由一个节点标签标识，你的集群中的节点必须拥有这个标签。

例如，在典型的数据中心中：

区域层级：区域或可用区，由类似 topology.kubernetes.io/zone 的标签标识
块层级：机架组，由类似 cloud.provider.com/topology-block 的标签标识
机架层级：块内的单独机架，由类似 cloud.provider.com/topology-rack 的标签标识
节点层级：单独节点，通常由 kubernetes.io/hostname 标识

在同一拓扑域（例如，相同的机架）内运行的 Pod 相比不同域的 Pod 具有更好的网络带宽。

公平共享（Fair Sharing）

Wed, 28 May 2025 00:00:00 +0000

准入公平共享

一种根据源 LocalQueue 的历史资源使用情况对工作负载进行排序的机制，优先考虑那些随着时间的推移消耗较少资源的工作负载。

基于抢占的公平共享

准入公平分共享（Admission Fair Sharing）

Wed, 28 May 2025 00:00:00 +0000

Feature state alpha since Kueue v0.12

注意

AdmissionFairSharing 目前是一个 Alpha 特性，默认未启用。

您可以通过编辑 AdmissionFairSharing 特性门控来启用它。有关特性门控配置的详细信息，请查阅安装指南。

准入公平共享有助于在多个指向同一 ClusterQueue 的 LocalQueue 之间公平分配资源。它会根据各自 LocalQueue 的历史资源使用情况对工作负载进行排序，优先考虑那些随着时间推移消耗资源较少的工作负载。

工作原理

当多个工作负载在同一个 ClusterQueue 中竞争资源时：

拓扑感知调度

Thu, 11 Apr 2024 00:00:00 +0000

Feature state alpha since Kueue v0.9

AI/ML 工作负载通常需要大量的 Pod 间通信。因此，运行 Pod 之间的网络带宽会直接影响工作负载的执行时间和运行成本。 Pod 之间的可用带宽取决于运行这些 Pod 的节点在数据中心中的分布。

我们观察到，数据中心的组织单元具有层次结构，如机架（rack）和区块（block），一个机架内有多个节点，一个区块内有多个机架。运行在同一组织单元内的 Pod 之间的网络带宽优于运行在不同单元的 Pod。我们认为，不同机架上的节点比同一机架内的节点距离更远。同理，不同区块的节点比同一区块内的节点距离更远。

本特性（称为拓扑感知调度，简称 TAS）引入了一种约定，用于表示分层节点拓扑信息，并为 Kueue 管理员和用户提供一组 API，以利用这些信息优化 Pod 的放置。

节点拓扑信息

我们提出了一种轻量级模型，通过节点标签来表示数据中心内节点的层次结构。在该模型中，节点标签由云服务商设置，或由本地集群管理员手动设置。

此外，我们假设用于 TAS 的每个节点都带有一组标签，这些标签能唯一标识其在树状结构中的位置。我们不要求每一层标签全局唯一，即可能存在两个节点具有相同的 “rack” 标签，但位于不同的 “block”。

例如，数据中心层次结构的表示如下：

节点	cloud.provider.com/topology-block	cloud.provider.com/topology-rack
node-1	block-1	rack-1
node-2	block-1	rack-2
node-3	block-2	rack-1
node-4	block-2	rack-3

注意，node-1 和 node-3 虽然 “cloud.provider.com/topology-rack” 标签值相同，但位于不同的 block。

Workload 优先级类

Mon, 02 Oct 2023 00:00:00 +0000

WorkloadPriorityClass 允许你控制 Workload 的优先级，而不会影响 Pod 的优先级。此功能适用于以下场景：

希望优先调度那些长时间处于非活跃状态的工作负载
希望为开发环境工作负载设置较低优先级，为生产环境工作负载设置较高优先级

一个示例 WorkloadPriorityClass 如下所示：

apiVersion: kueue.x-k8s.io/v1beta2
kind: WorkloadPriorityClass
metadata:
  name: sample-priority
value: 10000
description: "示例优先级"

WorkloadPriorityClass 对象是集群范围的，因此可以被任何命名空间下的作业使用。

如何在 Job 上使用 WorkloadPriorityClass

你可以通过设置标签 kueue.x-k8s.io/priority-class 来指定 WorkloadPriorityClass。

apiVersion: batch/v1
kind: Job
metadata:
  name: sample-job
  labels:
    kueue.x-k8s.io/queue-name: user-queue
    kueue.x-k8s.io/priority-class: sample-priority
spec:
...

Kueue 会为上述 Job 生成如下 Workload。 PriorityClassName 字段可以接受 PriorityClass 或 WorkloadPriorityClass 的名称。为区分两者，当使用 WorkloadPriorityClass 时，priorityClassSource 字段为 kueue.x-k8s.io/workloadpriorityclass；当使用 PriorityClass 时，priorityClassSource 字段为 scheduling.k8s.io/priorityclass。

抢占（Preemption）

Tue, 28 May 2024 00:00:00 +0000

在抢占过程中，以下术语相关：

被抢占者（Preemptees）：被抢占的 Workload。
目标 ClusterQueue：被抢占者所属的 ClusterQueue。
抢占者（Preemptor）：需要被容纳的 Workload。
抢占 ClusterQueue：抢占者所属的 ClusterQueue。

抢占的原因

如果 Workload 被准入到启用了抢占的 ClusterQueue，并且发生以下任一事件，则该 Workload 可以抢占一个或多个 Workload：

被抢占者与抢占者属于同一个 ClusterQueue，且被抢占者的优先级较低。
被抢占者与抢占者属于同一个 cohort，且被抢占者的 ClusterQueue 至少有一种资源的使用量高于名义配额，而该资源是被抢占者和抢占者都需要的。

在 Kueue 配置和 ClusterQueue 中配置的抢占设置，除了上述标准外，还可以限制 Workload 是否可以抢占其他 Workload。

当抢占 Workload 时，Kueue 会在被抢占 Workload 的 .status.conditions 字段中添加类似如下的条目：

status:
  - lastTransitionTime: "2025-03-07T21:19:54Z"
    message: '为容纳另一个 workload（UID: 5c023c28-8533-4927-b266-56bca5e310c1，JobUID: 4548c8bd-c399-4027-bb02-6114f3a8cdeb）而被抢占，原因是 ClusterQueue 中的优先级调整'
    observedGeneration: 1
    reason: Preempted
    status: "True"
    type: Evicted
  - lastTransitionTime: "2025-03-07T21:19:54Z"
    message: '为容纳另一个 workload（UID: 5c023c28-8533-4927-b266-56bca5e310c1，JobUID: 4548c8bd-c399-4027-bb02-6114f3a8cdeb）而被抢占，原因是 ClusterQueue 中的优先级调整'
    reason: InClusterQueue
    status: "True"
    type: Preempted

Evicted 条件表示该 Workload 因 Preempted 原因被驱逐，而 Preempted 条件则给出了更多关于抢占原因的细节。

MultiKueue

Mon, 11 Nov 2024 00:00:00 +0000

Feature state beta since Kueue v0.9

Note

MultiKueue 目前是一个 Beta 特性，默认启用。

你可以通过编辑 MultiKueue 特性门控来禁用它。关于特性门控配置的详情，请参阅安装指南。

MultiKueue 设置由一个管理集群和至少一个工作集群组成。

集群角色

管理集群

管理者的首要职责包括：

核心概念 on Kueue

资源规格（Resource Flavor）

注意

ResourceFlavor 容忍度实现自动调度

集群队列（ClusterQueue）

Cohort

你好，Cohort

配置配额

弹性工作负载

弹性工作负载（工作负载切片）

动态扩缩

本地队列（Local Queue）

下一步是什么？

工作负载(Workload)

活跃状态

Topology

Topology 层级

公平共享（Fair Sharing）

准入公平共享

基于抢占的公平共享

准入公平分共享（Admission Fair Sharing）

注意

准入公平共享（Admission Fair Sharing）

工作原理

拓扑感知调度

节点拓扑信息

Workload 优先级类

如何在 Job 上使用 WorkloadPriorityClass

抢占（Preemption）

抢占的原因

MultiKueue

Note

集群角色

管理集群