Volcano Job Policy 完全指南:用 Event/Action 声明式策略管理作业与任务生命周期
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 定义中,这两处字段分别对应:
- JobSpec.Policies:
Specifies the default lifecycle of tasks; - TaskSpec.Policies:
Specifies the lifecycle of task。
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/SucceededPod 以便排查;重试达到上限后作业进入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 测试依据
上述机制在仓库中有对应的自动化测试覆盖,可作为行为验证的参考:
- 单元测试 pkg/controllers/job/job_state_test.go:覆盖
PendingState/RunningState下RestartJobAction、CompleteJobAction等不同 terminating Pod 数量分支的状态迁移; - e2e 测试 test/e2e/jobp/:
jobp套件(含 job_restart.go、job_lifecycle.go、admission.go 等)在真实集群上验证作业重启、生命周期与准入行为。
8. 实战要点与常见误区
- 事件与动作的层级必须匹配:
RestartTask/RestartPod/RestartPartition不能搭配Unknown这类作业级事件;RestartPod只与 Pod 级事件(如PodFailed、PodEvicted)搭配。 - task 级策略覆盖 job 级策略:两级同时配置时以 task 级为准,配置前先确认策略挂载位置,避免"以为 job 级兜底、实际被 task 级屏蔽"。
PodPending必须理解其"状态+超时"语义:它表达的是"Pod 持续 pending 超过 timeout 后触发",到期时状态已恢复则动作取消;不要把它当作"Pod 创建失败"的替代。AbortJob与TerminateJob的区别只在可恢复性:两者都会驱逐全部 Pod 且不重建;需要人工介入后继续的作业用AbortJob(配合 resume),需要永久停止的用TerminateJob。TaskCompleted与minsuccess的联动:task 配置了minsuccess时,达到最小成功数即视作完成,可据此实现"部分 worker 达标即结束作业"(CompleteJob)的策略。- 不要使用内部事件/动作:
PodRunning、OutOfSync、CommandIssued、JobUpdated、TaskFailed及SyncJob、EnqueueJob等属于控制器内部事件/动作(源码中有明确注释),不应出现在用户策略中。 - 策略触发是"自愈"而非"无限重启":受
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 与排障的依据。