运行普通 Pod

此页面展示了在运行普通 Pod 时如何利用 Kueue 的调度和资源管理功能。Kueue 支持管理 单个 Pod 或 Pod 组。

本指南适用于对 Kueue 有基本了解的 批处理用户。有关更多信息，请参阅 Kueue 概览。

开始之前

1. 默认情况下，未启用 v1/pod 的集成。了解如何 安装具有自定义管理器配置的 Kueue 并启用 pod 集成。

   启用 Pod 集成的 Kueue 配置如下所示

   apiVersion: config.kueue.x-k8s.io/v1beta1
   kind: Configuration
   integrations:
     frameworks:
      - "pod"
     podOptions:
       # You can change namespaceSelector to define in which 
       # namespaces kueue will manage the pods.
       namespaceSelector:
         matchExpressions:
         - key: kubernetes.io/metadata.name
           operator: NotIn
           values: [ kube-system, kueue-system ]
       # Kueue uses podSelector to manage pods with particular 
       # labels. The default podSelector will match all the pods. 
       podSelector:
         matchExpressions:
         - key: kueue-job
           operator: In
           values: [ "true", "True", "yes" ]
   

2. 如果启用了 Pod 集成，Kueue 将为所有已创建的 Pod 运行 Webhook。webhook namespaceSelector 可用于筛选要协调的 Pod。默认的 webhook namespaceSelector 为

   matchExpressions:
   - key: kubernetes.io/metadata.name
     operator: NotIn
     values: [ kube-system, kueue-system ]
   

   当您通过 Helm 安装 Kueue时，webhook 命名空间选择器将匹配 values.yaml 中的 integrations.podOptions.namespaceSelector。

   确保 namespaceSelector 永远不会匹配 Kueue 命名空间，否则 Kueue 部署将无法创建 Pod。

3. 属于 Kueue 管理的其他 API 资源的 Pod 被排除在 pod 集成队列之外。例如，由 batch/v1.Job 管理的 Pod 不会由 pod 集成管理。

4. 查看管理集群配额，了解有关初始 Kueue 设置的详细信息。

运行由 Kueue 承认的单个 Pod

在 Kueue 上运行 Pod 时，请考虑以下方面

a. 队列选择

目标本地队列应在 Pod 配置的 metadata.labels 部分中指定。

metadata:
  labels:
    kueue.x-k8s.io/queue-name: user-queue

b. 配置资源需求

工作负载的资源需求可以在 spec.containers 中配置。

    - resources:
        requests:
          cpu: 3

c. “托管”标签

Kueue 将注入 kueue.x-k8s.io/managed=true 标签，以指示由其管理的 Pod。

d. 限制

• 无法在 kube-system 或 kueue-system 命名空间中创建 Kueue 托管的 Pod。
• 在 抢占的情况下，Pod 将被终止并删除。

示例 Pod

这是一个仅休眠几秒钟的示例 Pod

apiVersion: v1
kind: Pod
metadata:
  generateName: kueue-sleep-
  labels:
    kueue.x-k8s.io/queue-name: user-queue
spec:
  containers:
    - name: sleep
      image: busybox
      command:
        - sleep
      args:
        - 3s
      resources:
        requests:
          cpu: 3
  restartPolicy: OnFailure

您可以使用以下命令创建 Pod

# Create the pod
kubectl create -f kueue-pod.yaml

运行一组要一起准入的 Pod

为了将一组 Pod 作为一个单元运行（称为 Pod 组），请向该组的所有成员一致地添加“pod-group-name”标签和“pod-group-total-count”注释

metadata:
  labels:
    kueue.x-k8s.io/pod-group-name: "group-name"
  annotations:
    kueue.x-k8s.io/pod-group-total-count: "2"

功能限制

Kueue 仅提供运行 Pod 组所需的最低功能，仅适用于由外部控制器直接管理 Pod 的环境，而无需作业级别的 CRD。

由于此设计决策，Kueue 不会重新实现 Kubernetes Job API 中可用的核心功能，例如高级重试策略。特别是，Kueue 不会重新创建失败的 Pod。

此设计选择影响了抢占场景。当 Kueue 需要抢占表示 Pod 组的工作负载时，kueue 会向组中的所有 Pod 发送删除请求。创建原始 Pod 的用户或控制器负责创建替换 Pod。

注意：我们建议使用 kubernetes Job API 或类似的 CRD，例如 JobSet、MPIJob、RayJob（在此处查看更多信息此处）。

终止

当成功 Pod 的数量等于 Pod 组大小时，Kueue 会将 Pod 组视为成功，并将关联的工作负载标记为已完成。

如果 Pod 组不成功，则有两种方法可用于终止 Pod 组的执行以释放保留的资源

1. 为工作负载对象发出删除请求。Kueue 将终止所有剩余的 Pod。
2. 在组中的至少一个 Pod（可以是替换 Pod）上设置kueue.x-k8s.io/retriable-in-group: false注释。一旦所有 Pod 终止，Kueue 将把工作负载标记为已完成。

示例 Pod 组

以下是一个仅休眠几秒钟的示例 Pod 组

---
apiVersion: v1
kind: Pod
metadata:
  generateName: sample-leader-
  labels:
    kueue.x-k8s.io/queue-name: user-queue
    kueue.x-k8s.io/pod-group-name: "sample-group"
  annotations:
    kueue.x-k8s.io/pod-group-total-count: "2"
spec:
  restartPolicy: Never
  containers:
  - name: sleep
    image: busybox
    command: ["sh", "-c", 'echo "hello world from the leader pod" && sleep 3']
    resources:
      requests:
        cpu: 3
---
apiVersion: v1
kind: Pod
metadata:
  generateName: sample-worker-
  labels:
    kueue.x-k8s.io/queue-name: user-queue
    kueue.x-k8s.io/pod-group-name: "sample-group"
  annotations:
    kueue.x-k8s.io/pod-group-total-count: "2"
spec:
  restartPolicy: Never
  containers:
  - name: sleep
    image: busybox
    command: ["sh", "-c", 'echo "hello world from the worker pod" && sleep 2']
    resources:
      requests:
        cpu: 3

可以使用以下命令创建 Pod 组

kubectl create -f kueue-pod-group.yaml

Kueue 创建的相关工作负载的名称等于 Pod 组的名称。在此示例中，它是 sample-group，你可以使用以下命令检查工作负载

kubectl describe workload/sample-group