Volcano Job Policy 完全指南:用 Event/Action 声明式策略管理作业与任务生命周期

原创2026-09-16 15:38:521,854 阅读
文章标签:任务调度云原生容器编排高性能计算批处理集群管理弹性伸缩

Volcano Job Policy 完全指南:用 Event/Action 声明式策略管理作业与任务生命周期

Volcano 的 Job Policy(policies)机制允许用户在 Job 的 spec 或 tasks<a href="https://link.gitcode.com/i/957ac66d6270f54f59072c258011fd36" target="_blank">].policies 中以"事件(Event)触发动作(Action)"的声明式方式定义作业生命周期管理策略,例如当某个 worker Pod 被驱逐或失败时自动重启整个作业。本篇文档基于 Volcano 官方文档 [how_to_use_job_policy.md 展开,结合仓库中的 API 定义(job.go)、events.go、actions.go 与 Job 控制器实现源码,完整讲解策略的生效范围、全部可用事件与动作、带超时的延迟动作,以及控制器内部的事件产生与执行链路,读完后可直接编写可运行的 Job 策略配置并理解其底层行为。

1. 背景:为什么需要 Job Policy

Volcano 的 Policy 为用户提供了一组管理 volcano job 与 task 生命周期的 API。在 AI 训练、大数据和 HPC 等场景中,一旦某个 master 或 worker 失败,通常需要把整个作业拉起重跑,而不是依赖人工介入。通过为 volcano job 的 job.spec 配置 policy,用户可以轻松实现这类"某个条件发生即自动重启/终止作业"的自愈行为,无需在外部系统里写状态监听逻辑。

2. 生效范围与优先级规则

policies 字段可以出现在两个层级,其取值类型均为 LifecyclePolicy 数组:

配置位置 字段 生效范围
作业级 spec.policies 默认对作业内所有 task 生效
任务级 spec.tasks[].policies 仅对当前 task 生效

优先级规则:如果 job 级与 task 级同时配置了策略,task 级策略优先(obey the task policy)。一个 job 或 task 上可以配置多条策略(policies 是列表)。

在 API 定义中,这两处字段分别对应:

3. LifecyclePolicy 字段详解

每条策略是一个 LifecyclePolicy 对象,源码定义见 LifecyclePolicy 结构体:

字段 类型 说明
event Event 单事件触发器。调度器记录该事件后,控制器据此执行 action
events []Event 多事件触发器,任一事件发生即触发动作。与 event 二选一
exitCode *int32 以 Pod 容器退出码作为触发条件;注意:exitCode 与 event 只能二选一(源码注释:only one of Event or ExitCode can be specified)
action Action 事件命中后执行的内置动作(见第 5 节)
timeout *metav1.Duration 动作执行的宽限延迟。默认为 nil(立即执行);设置后动作在超时延时之后才执行

其中 timeout 是理解 PodPending 类事件的关键:控制器内部对带超时的动作会构造一个 delayAction(见 job_controller.go 中的 delayAct 处理),如果 Pod 状态在超时前已离开该事件条件(例如 PodPending 场景下 Pod 不再处于 pending),延迟动作会被取消——这正是文档中"PodPending 通常与 timeout 搭配使用"的实现含义。

4. 内置事件(Events)

Volcano 当前面向用户提供 6 个内置事件(下表与原文档一致):

ID Event 说明
1 PodFailed 检查是否存在 Pod 状态为 Failed
2 PodEvicted 检查是否存在被驱逐的 Pod
3 PodPending 检查是否存在 pending 的 Pod。通常与 timeout 搭配使用;如果 Pod 不再处于 pending 状态,超时的动作会被取消
4 TaskCompleted 检查是否有某个 task 的全部 Pod 均 Succeeded。若该 task 配置了 minsuccess,达到 minsuccess 也会被视作 task 完成
5 Unknown 检查 volcano job 状态是否为 Unknown。最常见的诱因是 task 不可调度:在 gang-scheduling 场景下,部分 Pod 无法调度而另一部分已在运行时被触发
6 * 匹配所有事件(AnyEvent),不常用

事件常量定义在 events.go,其 kubebuilder 枚举为 *;PodPending;PodRunning;PodFailed;PodEvicted;Unknown;TaskCompleted;OutOfSync;CommandIssued;JobUpdated;TaskFailed。需要特别注意:

  • 源码在该文件中明确标注 Note: events below are used internally, should not be used by users——即 OutOfSync、CommandIssued、JobUpdated、TaskFailed 属于内部事件,不应写入用户策略;
  • PodRunning 虽然也是合法枚举,但 isInternalEvent 将其与 OutOfSync、CommandIssued 归为内部事件处理;
  • events.go 的注释还揭示了 Unknown 事件的准确语义:JobUnknownEvent 在"gang-scheduling 场景下部分 Pod 无法调度、部分已在运行"时产生,与 job_controller_handler.go 中设置 JobUnknownEvent 的逻辑 相对应。

从源码结构看,事件由控制器在观察到 Pod/Job 状态变化时主动产生,例如 job_controller_handler.go 中:Pod 失败产生 PodFailedEvent、task 达到完成条件产生 TaskCompletedEvent、Pod 进入 Running/Pending 产生相应事件。

5. 内置动作(Actions)

Volcano 面向用户提供的内置动作如下(原文档表格实际列出 7 项;源码 actions.go 中另有 ResumeJob 及一组"仅供内部使用"的动作):

ID Action 说明
1 AbortJob 中止整个作业,但可以恢复(resume)。所有 Pod 被驱逐且不会重建
2 RestartJob 重启整个作业
3 RestartTask 重启指定 task(其下所有 Pod 删除重建)。不能与 Unknown 等作业级事件搭配
4 RestartPod 重启产生事件的单个 Pod。同样不能与作业级事件搭配
5 RestartPartition 重启指定 partition 组内的所有 Pod。同样不能与作业级事件搭配
6 TerminateJob 终止整个作业且不可恢复。所有 Pod 被驱逐且不会重建
7 CompleteJob 将作业视为完成,未完成的 Pod 会被杀掉

动作语义在源码注释中可以得到印证,例如 actions.go 中:AbortJobAction 对应"所有 Pod 被驱逐且不再重建",TerminateJobAction 额外标注"cannot be resumed",RestartPodAction 标注"can just work together with pod level events"。

从源码结构看,动作被划分为四类作用域,见 GetActionType:

  • JobAction:AbortJob、RestartJob、TerminateJob、CompleteJob(以及用于恢复的 ResumeJob);
  • TaskAction:RestartTask,通过 GetStateAction 绑定到具体 TaskName;
  • PodAction:RestartPod,绑定到具体 Pod;
  • PartitionAction:RestartPartition,绑定到具体 partition 组。

这一分类正好解释了"task/pod/partition 级动作无法搭配 Unknown 这类作业级事件"的限制:作业级事件不携带具体的 task/Pod 上下文,无法为目标动作定位 Target。

此外,actions.go 中列出了 SyncJob、EnqueueJob、SyncQueue、OpenQueue、CloseQueue 等动作,源码注释明确它们是内部动作、不应用户使用;isInternalAction 会将其识别为内部动作。

6. 配置示例(完整继承官方示例)

以下示例以 TensorFlow 分布式训练(dist-mnist)为例,ps 1 副本、worker 2 副本、minAvailable: 3 构成 gang 约束。仓库中同类 TF 集成示例可参考 example/integrations/tensorflow/ 目录下的样例作业。

6.1 示例一:单 event 单 action(作业级 + 任务级策略)

要点:ps 与 worker 上均未配策略时继承 job 级策略;这里 job 级配 PodEvicted → RestartJob(任一 Pod 被驱逐即重启整个作业),worker 级配 TaskCompleted → CompleteJob(worker 全部成功即结束作业)。

apiVersion: batch.volcano.sh/v1alpha1
kind: Job
metadata:
  name: tensorflow-dist-mnist
spec:
  minAvailable: 3
  schedulerName: volcano
  plugins:
    env: []
    svc: []
  policies:
    - event: PodEvicted # Job level policy. If any pod is evicted, restart the job.
      action: RestartJob
  queue: default
  tasks:
    - replicas: 1
      name: ps
      template:
        spec:
          containers:
            - command:
                - sh
                - -c
                - |
                  PS_HOST=`cat /etc/volcano/ps.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  WORKER_HOST=`cat /etc/volcano/worker.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  export TF_CONFIG={\"cluster\":{\"ps\":[${PS_HOST}],\"worker\":[${WORKER_HOST}]},\"task\":{\"type\":\"ps\",\"index\":${VK_TASK_INDEX}},\"environment\":\"cloud\"};   ## Get the index from the environment variable and configure it in the TF job.
                  python /var/tf_dist_mnist/dist_mnist.py
              image: volcanosh/dist-mnist-tf-example:0.0.1
              name: tensorflow
              ports:
                - containerPort: 2222
                  name: tfjob-port
              resources: {}
          restartPolicy: Never
    - replicas: 2
      name: worker
      policies:
        - event: TaskCompleted    # Task level policy. If this task completes, complete the job.
          action: CompleteJob
      template:
        spec:
          containers:
            - command:
                - sh
                - -c
                - |
                  PS_HOST=`cat /etc/volcano/ps.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  WORKER_HOST=`cat /etc/volcano/worker.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  export TF_CONFIG={\"cluster\":{\"ps\":[${PS_HOST}],\"worker\":[${WORKER_HOST}]},\"task\":{\"type\":\"worker\",\"index\":${VK_TASK_INDEX}},\"environment\":\"cloud\"};
                  python /var/tf_dist_mnist/dist_mnist.py
              image: volcanosh/dist-mnist-tf-example:0.0.1
              name: tensorflow
              ports:
                - containerPort: 2222
                  name: tfjob-port
              resources: {}
          restartPolicy: Never

6.2 示例二:events 列表触发同一 action

要点:用 events: [PodEvicted, PodFailed] 表达"被驱逐或失败都重启作业",避免为两种事件写两条策略。

apiVersion: batch.volcano.sh/v1alpha1
kind: Job
metadata:
  name: tensorflow-dist-mnist
spec:
  minAvailable: 3
  schedulerName: volcano
  plugins:
    env: []
    svc: []
  queue: default
  tasks:
    - replicas: 1
      name: ps
      policies:
        - events: [PodEvicted, PodFailed]   # Task level policy. If any pod is evicted or fails in this task, restart the job.
          action: RestartJob
      template:
        spec:
          containers:
            - command:
                - sh
                - -c
                - |
                  PS_HOST=`cat /etc/volcano/ps.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  WORKER_HOST=`cat /etc/volcano/worker.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  export TF_CONFIG={\"cluster\":{\"ps\":[${PS_HOST}],\"worker\":[${WORKER_HOST}]},\"task\":{\"type\":\"ps\",\"index\":${VK_TASK_INDEX}},\"environment\":\"cloud\"};   ## Get the index from the environment variable and configure it in the TF job.
                  python /var/tf_dist_mnist/dist_mnist.py
              image: volcanosh/dist-mnist-tf-example:0.0.1
              name: tensorflow
              ports:
                - containerPort: 2222
                  name: tfjob-port
              resources: {}
          restartPolicy: Never
    - replicas: 2
      name: worker
      policies:
        - event: TaskCompleted  # Task level policy. If this task completes, complete the job.
          action: CompleteJob
      template:
        spec:
          containers:
            - command:
                - sh
                - -c
                - |
                  PS_HOST=`cat /etc/volcano/ps.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  WORKER_HOST=`cat /etc/volcano/worker.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  export TF_CONFIG={\"cluster\":{\"ps\":[${PS_HOST}],\"worker\":[${WORKER_HOST}]},\"task\":{\"type\":\"worker\",\"index\":${VK_TASK_INDEX}},\"environment\":\"cloud\"};
                  python /var/tf_dist_mnist/dist_mnist.py
              image: volcanosh/dist-mnist-tf-example:0.0.1
              name: tensorflow
              ports:
                - containerPort: 2222
                  name: tfjob-port
              resources: {}
          restartPolicy: Never

6.3 示例三:多条策略 + timeout 延迟动作

要点:同一 task 上可以挂多条策略,各管一种情况;timeout: 10m 表示命中 PodEvicted 后延迟 10 分钟再重启作业(期间若 Pod 状态恢复/变化,动作可能被取消)。

apiVersion: batch.volcano.sh/v1alpha1
kind: Job
metadata:
  name: tensorflow-dist-mnist
spec:
  minAvailable: 3
  schedulerName: volcano
  plugins:
    env: []
    svc: []
  queue: default
  tasks:
    - replicas: 1
      name: ps
      policies:
        - events: PodFailed   # Task level policy. If any pod fails in this task, restart the pod.
          action: RestartPod
        - events: PodEvicted   # Task level policy. If any pod is evicted in this task, restart the job after 10 minutes.
          action: RestartJob
          timeout: 10m
      template:
        spec:
          containers:
            - command:
                - sh
                - -c
                - |
                  PS_HOST=`cat /etc/volcano/ps.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  WORKER_HOST=`cat /etc/volcano/worker.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  export TF_CONFIG={\"cluster\":{\"ps\":[${PS_HOST}],\"worker\":[${WORKER_HOST}]},\"task\":{\"type\":\"ps\",\"index\":${VK_TASK_INDEX}},\"environment\":\"cloud\"};   ## Get the index from the environment variable and configure it in the TF job.
                  python /var/tf_dist_mnist/dist_mnist.py
              image: volcanosh/dist-mnist-tf-example:0.0.1
              name: tensorflow
              ports:
                - containerPort: 2222
                  name: tfjob-port
              resources: {}
          restartPolicy: Never
    - replicas: 2
      name: worker
      policies:
        - event: TaskCompleted  # Task level policy. If this task completes, complete the job.
          action: CompleteJob
      template:
        spec:
          containers:
            - command:
                - sh
                - -c
                - |
                  PS_HOST=`cat /etc/volcano/ps.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  WORKER_HOST=`cat /etc/volcano/worker.host | sed 's/$/&:2222/g' | sed 's/^/"/;s/$/"/' | tr "\n" ","`;
                  export TF_CONFIG={\"cluster\":{\"ps\":[${PS_HOST}],\"worker\":[${WORKER_HOST}]},\"task\":{\"type\":\"worker\",\"index\":${VK_TASK_INDEX}},\"environment\":\"cloud\"};
                  python /var/tf_dist_mnist/dist_mnist.py
              image: volcanosh/dist-mnist-tf-example:0.0.1
              name: tensorflow
              ports:
                - containerPort: 2222
                  name: tfjob-port
              resources: {}
          restartPolicy: Never

7. 源码级机制解析:事件如何变成动作

7.1 事件产生链路

Job 控制器通过 informer 监听 Pod 状态变化,在 job_controller_handler.go 中将观察到的状态翻译成事件请求:Pod 进入失败态产生 PodFailedEvent,task 内全部 Pod Succeeded(或达到 minsuccess)产生 TaskCompletedEvent,Pod 处于 Pending/Running 产生 PodPendingEvent/PodRunningEvent;当 gang 场景下出现部分 Pod 无法调度时,在 job_controller_handler.go#L486 处产生 JobUnknownEvent。这些事件请求随后与用户配置的 policies 匹配,命中即生成待执行的动作请求。

7.2 超时动作(delayAction)

带 timeout 的动作不会立即执行。从 job_controller.go 的处理逻辑看,控制器对 PodFailed/PodEvicted 等事件产生的 delayAct 会结合超时时长决定是立即还是延迟执行;对 PodPending 这类"状态性"事件,延迟到期后若 Pod 已不再处于对应状态,动作即被取消——这与文档中 "PodPending usually used with timeout" 的行为一致。

7.3 动作执行与 Kill 语义

命中动作后,控制器按动作作用域(Job/Task/Pod/Partition)调用统一的目标清除逻辑 killPods,其中有几个值得注意的实现细节:

  • 重启计数与重试上限:整作业级 kill 会先 job.Status.Version++,再按保留策略(podRetainPhase)逐个标记 Pod 为 out-of-sync 后删除;RetryCount 与 MaxRetry 配合决定重启上限(MaxRetry 默认为 3,见 JobSpec.MaxRetry)。最后一次重试时会保留 Failed/Succeeded Pod 以便排查;重试达到上限后作业进入 Failed 阶段,不再拉起。
  • PodGroup 的存留策略:killPods 末尾的逻辑 明确注释:只有整作业级 kill(target == nil)才会删除 PodGroup;RestartPod 这类定向重启保留 PodGroup,避免调度器每次单 Pod 失败都重新入队、重新调度整个作业——这是 RestartPod 比 RestartJob 开销更小的根本原因。

7.4 作业状态机

策略动作驱动作业在以下阶段间流转(定义见 JobPhase):

Pending -> Running -> (Restarting -> Running ...)
              |            \
              v             v
        Aborting -> Aborted   Completing -> Completed
              \
               v
        Terminating -> Terminated
              \
               v
             Failed   (重启次数超过 MaxRetry)
  • AbortJob 将作业置为 Aborted,且可恢复:actions.go 中定义了 ResumeJobAction(内部动作),CLI 侧对应的实现位于 cmd/cli/vresume/,可通过 vcctl 的 resume 子命令把被中止的作业重新拉回;
  • TerminateJob 置为 Terminated,不可恢复;
  • CompleteJob 置为 Completed,杀光未完成的 Pod。

7.5 测试依据

上述机制在仓库中有对应的自动化测试覆盖,可作为行为验证的参考:

8. 实战要点与常见误区

  1. 事件与动作的层级必须匹配:RestartTask/RestartPod/RestartPartition 不能搭配 Unknown 这类作业级事件;RestartPod 只与 Pod 级事件(如 PodFailed、PodEvicted)搭配。
  2. task 级策略覆盖 job 级策略:两级同时配置时以 task 级为准,配置前先确认策略挂载位置,避免"以为 job 级兜底、实际被 task 级屏蔽"。
  3. PodPending 必须理解其"状态+超时"语义:它表达的是"Pod 持续 pending 超过 timeout 后触发",到期时状态已恢复则动作取消;不要把它当作"Pod 创建失败"的替代。
  4. AbortJob 与 TerminateJob 的区别只在可恢复性:两者都会驱逐全部 Pod 且不重建;需要人工介入后继续的作业用 AbortJob(配合 resume),需要永久停止的用 TerminateJob。
  5. TaskCompleted 与 minsuccess 的联动:task 配置了 minsuccess 时,达到最小成功数即视作完成,可据此实现"部分 worker 达标即结束作业"(CompleteJob)的策略。
  6. 不要使用内部事件/动作:PodRunning、OutOfSync、CommandIssued、JobUpdated、TaskFailed 及 SyncJob、EnqueueJob 等属于控制器内部事件/动作(源码中有明确注释),不应出现在用户策略中。
  7. 策略触发是"自愈"而非"无限重启":受 MaxRetry(默认 3)约束,反复重启最终会以 Failed 收尾;spec.maxRetry 与 tasks<a href="https://link.gitcode.com/i/2753b88620001abb5fe1150d1d4fd217" target="_blank">].maxRetry 均可调整(见 [JobSpec 与 TaskSpec)。

9. 小结

Volcano Job Policy 用最小的配置面(event(s) / exitCode + action + 可选 timeout)覆盖了"Pod 失败/驱逐/持续 pending、task 完成、作业不可调度"等核心异常场景,并提供了从"单 Pod 重启"到"整作业终止"的全谱系动作。结合仓库源码可以确认:事件由 Job 控制器的 Pod/Job 状态监听链路产生,动作按 Job/Task/Pod/Partition 四种作用域执行,RestartPod 会保留 PodGroup 以减少调度开销,且整体受 MaxRetry 约束。以上信息均来自当前仓库的 API 定义、控制器实现与测试代码,可直接作为配置 Job Policy 与排障的依据。

登录后查看全文
volcano