Kubernetes v1.35 API 文档中工作负载边界有哪些变化

Kubernetes v1.35 的工作负载 API 变化，重点不是把 Job、Deployment 或 StatefulSet 换成另一个控制器，而是在控制器对象之外增加一层面向多 Pod 调度的描述。控制器继续负责“要运行什么、如何维持副本和生命周期”，Workload 则负责“这些 Pod 属于哪些组、是否需要成组调度”。

官方地址：https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/

这层 API 在 v1.35 文档中仍是 alpha，默认关闭，属于试验性调度能力。阅读它时最重要的判断是：它是调度约束和关联信息，不是 Job 或 Deployment 的替代品。

先把“运行什么”与“如何调度”分开

传统 Kubernetes 工作负载通常从控制器开始。Job 描述一次性任务，Deployment 描述无状态副本，StatefulSet 描述有序且带身份的副本；它们创建或维护 Pod，并负责重试、滚动更新或副本数量等运行态行为。

v1.35 的 Workload API 引入了另一种职责边界：一个 Workload 对象可以描述多 Pod 应用的结构和调度要求。它不直接创建 Pod，也不接管控制器的生命周期。一个简单的心智模型是：

• 控制器回答“应该有哪些 Pod，以及它们如何被维持”；
• Workload 回答“这些 Pod 组成哪些 pod group，以及调度器如何看待这一组”；
• Pod 通过 spec.workloadRef 指向 Workload 中的具体 pod group。

这不是把调度器变成新的控制器，而是给调度器一个比“逐个 Pod 看待”更完整的工作负载视角。对于需要多个 Pod 同时具备资源条件的批处理、训练或分布式任务，这个区分尤其重要。

v1.35 的 API 表面变化：新增一层调度对象

在 v1.35 文档中，Workload 位于 scheduling.k8s.io/v1alpha1 API 组，并且需要启用 GenericWorkload feature gate。文档把它标记为 Kubernetes v1.35 alpha，默认关闭，所以“API 文档里能看到”不等于“普通集群可以直接提交并获得调度语义”。

Workload 的最小结构可以抽象成下面这个示例。示例只用于解释字段关系，不表示已经在某个集群执行过。

apiVersion: scheduling.k8s.io/v1alpha1
kind: Workload
metadata:
  name: training-job-workload
  namespace: batch-demo
spec:
  # 关联真正负责创建 Pod 的高层对象，主要服务于观测和工具链
  controllerRef:
    apiGroup: batch
    kind: Job
    name: training-job
  # 一个 Workload 可以按角色拆成多个 Pod 组
  podGroups:
    - name: workers
      # basic 只做分组；需要成组准入时改用 gang
      policy:
        gang:
          # 至少有 4 个 Pod 可同时调度时才允许这一组进入
          minCount: 4

这个对象有两个值得注意的边界。第一，controllerRef 是“链接回高层对象”的引用，文档明确说明它用于可观测性和工具，不参与 Workload 的调度或管理。第二，真正影响调度行为的是 podGroups 及其 policy，而不是 controllerRef 写得是否完整。

读懂 Workload 的三个关键结构

podGroups 是调度视角的组成单元

podGroups 用来表示一个多 Pod 应用中的不同组件，例如 driver、worker 或 coordinator。每个组需要有稳定的名称，Pod 后续通过这个名称建立归属。它解决的是“哪些 Pod 应该被一起理解”的问题，而不是“哪些 Pod 由哪个控制器创建”的问题。

因此，一个 Job 可以关联一个包含 workers 的 Workload，也可以在更复杂的场景中把同一应用拆成多个组。拆分的价值在于让调度约束落到组件组，而不是把所有 Pod 粗暴地视为一个集合。

basic 与 gang 是两种不同的取舍

basic policy 主要提供分组、观测和后续扩展的语义；组内 Pod 仍按普通 Kubernetes 行为独立调度。它适合“逻辑上属于同一个应用，但不要求同时启动”的情况。

gang policy 则表达成组准入：需要给出 minCount，调度器会在满足组条件后尝试让足够数量的 Pod 一起获得放置机会。紧耦合批任务如果只使用普通独立调度，可能先启动少量 worker，却因为资源不足迟迟无法形成可工作的整体；gang 的价值就是把这种部分启动风险显式化。

controllerRef 不是调度开关

很多人看到 Workload 示例中的 controllerRef，会误以为填写 Job 后 Workload 就接管了 Job。这个理解不准确。它的作用是把 Workload 与具体的 Job 或自定义资源关联起来，方便观测、索引和工具展示；调度器不会根据它替你创建控制器，也不会因为它存在就改变控制器的重试和更新逻辑。

因此，设计时应把两条链路分开：控制器负责产生 Pod，Workload 负责描述 Pod 组和调度政策。两者可以相互引用，但职责不能混写。

Pod 接入后，调度语义才真正发生变化

仅创建 Workload 对象不会自动吸收集群里所有 Pod。Pod 需要通过 spec.workloadRef 指向同一命名空间里的 Workload 和具体 pod group。一个概念示例如下：

apiVersion: v1
kind: Pod
metadata:
  name: worker-0
  namespace: batch-demo
spec:
  workloadRef:
    # 引用同命名空间中的 Workload
    name: training-job-workload
    # 指向 Workload 内的具体组
    podGroup: workers
    # 将同一组拆成互相独立的调度单元
    podGroupReplicaKey: "0"
  containers:
    - name: worker
      image: example/trainer:1.0

这里有三个实用判断：

1. Workload 和 Pod 必须位于同一命名空间，引用的 pod group 名称也必须真实存在；
2. 引用缺失或 pod group 不存在时，Pod 会保持 Pending，调度器不会把它当成普通 Pod 直接放置；
3. 同一个 pod group 可以用 podGroupReplicaKey 划分成多个独立调度单元，适合需要多组相同 worker 的场景。

如果 pod group 使用 basic，workloadRef 更像是带有调度上下文的分组标签；如果使用 gang，还需要对应的 gang scheduling 能力，Pod 才会进入成组等待和准入语义。

哪些场景适合试用，哪些场景不要贸然迁移

尤其不要因为看到 Workload 这个名字就把所有 Job 和 Deployment 都迁过去。若问题只是副本数量、滚动发布或失败重试，现有控制器已经覆盖；只有当“多 Pod 的调度关系本身”成为问题时，Workload 才有明确的试用价值。

采用前的兼容判断清单

1. 先确认控制面与调度器版本确实对应 v1.35 文档，并把 Workload 当作 alpha 能力管理；
2. 确认集群启用了 GenericWorkload，需要 gang 时再确认 GangScheduling 和对应插件配置；
3. 先画清控制器、Workload、Pod 和 scheduler 的责任边界，避免让 controllerRef 承担调度语义；
4. 为每个 Pod group 选择 basic 或 gang，并解释 minCount、资源峰值和 Pending 行为；
5. 为 workloadRef 缺失、组名错误、资源不足和 feature gate 未启用保留清晰的回退或观测路径。

总结来看，Kubernetes v1.35 API 文档的工作负载边界变化，是从“控制器就是工作负载的全部描述”扩展为“控制器管理运行态，Workload 补充多 Pod 调度结构”。这是一种架构分层，不是一次资源替换。把这一点理解清楚，才不会因为 API 资源名称相近而误配生产集群。

相关问题

• Kubernetes 的 basic policy 会不会自动让多个 Pod 同时启动？不会，它主要提供分组语义，组内 Pod 仍可独立调度。
• controllerRef 能不能代替 workloadRef？不能，controllerRef 负责关联高层对象，Pod 仍需 workloadRef 指向具体 pod group。
• Workload API 能不能直接替代 Deployment？不能，它不负责副本维持、滚动更新或回滚。
• workloadRef 指向不存在的组会怎样？Pod 会保持 Pending，直到 Workload 和对应 pod group 可被调度器识别。

参考资料

• https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/
• https://v1-35.docs.kubernetes.io/docs/concepts/workloads/workload-api/
• https://v1-35.docs.kubernetes.io/docs/concepts/workloads/pods/workload-reference/
• https://v1-35.docs.kubernetes.io/docs/concepts/scheduling-eviction/gang-scheduling/