Volcano vcctl 命令行增强设计从 Slurm 风格到 vsub/vcancel/vjobs 新一代命令体系【免费下载链接】volcanoA Cloud Native Batch System (Project under CNCF)项目地址: https://gitcode.com/GitHub_Trending/vol/volcano导读本文以 Volcano 仓库中的 command-line-enhancement.md 设计文档为骨架系统梳理 VolcanoCNCF 旗下的云原生批处理系统命令行工具vcctl的完整功能矩阵并详细解读其向vsub、vcancel、vjobs、vqueues等轻量短命令演进的新格式设计。文中命令均与仓库源码一一印证读者可以借此掌握 Volcano 作业提交、队列管理、JobFlow/JobTemplate 操作的标准姿势理解其设计理念对标 Slurm 等传统 HPC 调度系统的由来并直接照抄可用的命令与配置文件完成实战操作。vcctl概览Volcano 的命令行入口vcctl是 Volcano 原生的命令行工具由 cmd/cli/vcctl.go 定义根命令底层基于 Cobra 框架构建。其入口代码显示根命令注册了五大业务子命令组外加一个version命令用于打印版本信息job作业Volcano Job的增删改查与生命周期管理queue队列的创建、删除、查看、列举与状态操作jobtemplate作业模板的 CRUD 与描述jobflow作业流JobFlow的 CRUD 与描述pod查询由 Volcano Job 创建出来的 Podversion打印版本信息源码中通过version.PrintVersionAndExit()实现。从 cmd/cli/vcctl.go 可以看到命令注册方式为rootCmd.AddCommand(buildJobCmd())等每个子命令组又在其对应文件中以命令名 → Short 描述 → RunFunction → InitFlags的映射表批量注册子命令见 cmd/cli/job.go、cmd/cli/queue.go。这种声明式注册方式使得命令的参数、帮助信息高度统一也便于后续扩展新命令。所有命令最终都会调用pkg/cli下的同名业务实现并统一通过 cmd/cli/util/util.go 中的util.CheckError包装错误输出——出错时打印 Failed to 命令路径: 错误信息 并退出。命令与 apiserver 的交互则依赖 pkg/cli/util/util.go 中的BuildConfig它优先读取-k/--kubeconfig指定的文件否则回落到默认的 KUBECONFIG 加载规则-s/--master可显式指定 apiserver 地址便于在未配置 kubeconfig 的环境中使用。vcctl功能矩阵五大子命令全解析vcctl job作业生命周期管理设计文档给出的vcctl job命令格式及用途如下命令格式用途vcctl job delete -N job_name -n namespace删除一个作业vcctl job list -S scheduler -n namespace -q queue_name列举作业信息vcctl job resume -N job_name -n namespace恢复resume一个作业vcctl job run -f yaml_file -i image -L resource_limit -m min_available -N job_name -n namespace -r replicas -R resource_request -S scheduler用命令行参数直接运行作业vcctl job suspend -N job_name -n namespace挂起suspend一个作业vcctl job view -N job_name -n namespace查看一个作业的信息vcctl job的六个子命令在 cmd/cli/job.go 中逐一注册业务实现位于 pkg/cli/job/run.go、list.go、view.go、suspend.go、resume.go、delete.go。其中值得重点说明的是最核心的vcctl job run其完整参数与默认值与 e2e 测试 test/e2e/vcctl/vcctl.go 中校验的帮助输出一致如下参数简写默认值含义--filename-f空作业 YAML 文件路径--image-ibusybox作业容器镜像--limits-Lcpu1000m,memory100Mi任务资源上限--min-m1作业最小可用任务数minAvailable--name-N空必填或配合-f作业名--namespace-ndefault作业命名空间--replicas-r1任务总副本数--requests-Rcpu1000m,memory100Mi任务资源请求--scheduler-Svolcano作业使用的调度器从 pkg/cli/job/run.go 可以看到RunJob的实现逻辑通过BuildConfig构造客户端配置校验-N作业名与-f文件路径二者至少提供一个否则报错job name cannot be left blank通过util.PopulateResourceListV1把cpu1000m,memory100Mi形式的字符串解析为v1.ResourceList见 pkg/cli/util/util.go解析规则为按逗号切分、再按切分最终用resource.ParseQuantity解析数值若提供了-f则readFile读取 YAML仅接受.yaml/.yml后缀见 pkg/cli/job/run.go否则调用constructLaunchJobFlagsJob用命令行参数构造一个volcano.sh/apis/pkg/apis/batch/v1alpha1的Job对象设置MinAvailable、SchedulerName、单 Task 的Replicas、Pod 模板中的镜像与资源请求/限制调用jobClient.BatchV1alpha1().Jobs(namespace).Create(...)创建作业成功后打印run job name successfully。注意一个细节vcctl job run的短参数中作业名是-N大写、命名空间是-n小写而在新的vsub/vcancel等命令中这一约定被对调——短参数-n指作业名、-N指命名空间详见下文新格式一节。使用时要特别留意大小写差异以免在两种命令体系间切换时混淆。vcctl queue队列管理命令格式用途vcctl queue create -n queue_name -w weight创建队列vcctl queue delete -n queue_name删除队列vcctl queue get -n queue_name获取队列vcctl queue list列举所有队列vcctl queue operate -a open/close/update -n queue_name -w weight操作队列打开/关闭/更新权重队列子命令注册于 cmd/cli/queue.go实现位于 pkg/cli/queue/。其中operate动作的取值在 pkg/cli/queue/operate.go 中被定义为open、close、update三种常量open向队列发送OpenQueueAction命令打开队列允许其接收作业close发送CloseQueueAction命令关闭队列update通过 merge patch 更新队列权重。源码要求此时-w weight必须大于 0否则报错when update queue name, weight must be specified, the value must be greater than 0随后以{spec:{weight:w}}的 JSON patch 打到SchedulingV1beta1().Queues()资源上见 pkg/cli/queue/operate.go。open/close的底层实现是创建一条 Volcano 的 busCommand资源CreateQueueCommand见 pkg/cli/util/util.go由 Volcano 控制器接收并执行状态流转。这与 Kubernetes 原生的kubectl风格不同——队列的开关在 Volcano 中是通过自定义 Command 机制驱动的。vcctl jobflow与vcctl jobtemplate工作流与模板命令格式用途vcctl jobflow create -f jobflow yaml file从 YAML 文件创建 JobFlowvcctl jobflow delete -f jobflow yaml file从 YAML 文件删除 JobFlowvcctl jobflow get -N jobflow_name -n namespace获取 JobFlowvcctl jobflow list列举所有 JobFlowvcctl jobflow describe -N jobflow_name -n namespace描述 JobFlow命令格式用途vcctl jobtemplate create -f jobtemplate yaml file从 YAML 文件创建 JobTemplatevcctl jobtemplate delete -f jobtemplate yaml file从 YAML 文件删除 JobTemplatevcctl jobtemplate get -N jobtemplate_name -n namespace获取 JobTemplatevcctl jobtemplate list列举所有 JobTemplatevcctl jobtemplate describe -N jobtemplate_name -n namespace描述 JobTemplateJobFlow 与 JobTemplate 是 Volcano 用于组织多作业编排与模板复用的上层抽象示例见 example/jobflow/JobFlow.yaml 与 example/jobflow/JobTemplate.yaml设计细节见 docs/design/jobflow/README.md。两个子命令组的注册结构完全对称见 cmd/cli/jobflow.go 与 cmd/cli/jobtemplate.go都提供create/list/get/delete/describe五个动作分别对应 pkg/cli/jobflow/ 与 pkg/cli/jobtemplate/ 中的同名实现。vcctl pod查询作业产生的 Pod命令格式用途vcctl pod list -qqueue_name -jvcjob_name按队列名与作业名列举 Podvcctl pod list注册于 cmd/cli/pod.go实现于 pkg/cli/pod/pod.go。其过滤逻辑见 pkg/cli/pod/pod.go值得展开-j/--job指定作业名时按 Volcano 为 Pod 打上的job.volcano.sh标签源码中jobName job.volcano.sh进行 label selector 过滤此时无论是否再指定队列名都只需按作业名查询即可——因为作业本身已经绑定了队列仅指定-q/--queue时则按队列维度聚合查询所有 Pod。这种先队列后作业、作业内不再关心队列的分层查询语义与 Volcano 队列-作业的层级模型保持一致。vcctl与 Slurm 命令行的对照借鉴传统 HPC 的使用习惯设计文档专门列出了一张vcctl与 Slurm 的对照表说明 Volcano 在设计 CLI 时有意对标传统 HPC 调度系统的用户心智模型帮助 HPC 用户平滑迁移到 Kubernetes 批处理场景vcctl功能类似的 Slurm 命令vcctl job run -f yaml_filesbatch job_filevcctl job run -N job_namesrun -J job_namevcctl job delete -N job_name -n namespacescancel job_id / -n job_name -u uservcctl job suspend -N job_name -n namespacescontrol suspend job_idvcctl job resume -N job_name -n namespacescontrol resume job_idvcctl job view -N job_name -n namespacescontrol show job job_idvcctl job list --all-namespacesscontrol show jobvcctl job list -n namespacesqueue -u uservcctl queue create -n queue_name -w weightscontrol create PartitionNamepartition_namevcctl queue delete -n queue_namescontrol delete PartitionNamepartition_namevcctl queue get -n queue_namesqueue -p partition_name scontrol show partition partition_namevcctl queue listsqueue -a scontrol show partitionvcctl queue operate -a open/close/update ...无对应命令从对应关系可以看出作业概念对应 Slurm 的 job/partition 视角队列概念对应 Slurm 的 partition 视角而queue operate打开/关闭/更新权重是 Volcano 相对 Slurm 的增量能力——传统调度器里分区开关通常需要管理员直接改配置Volcano 则把它变成了一条在线命令。文档末尾也列出了设计时参考的 Slurm、IBM LSF 等文档资料原文的 Reference 小节表明这套 CLI 映射并非凭空设计而是有明确的 HPC 命令行惯例作为依据。新格式设计面向普通用户与管理员的轻量命令设计文档提出了 Volcano 命令行新格式的演进方向把vcctl的一长串子命令拆解为按职责独立的短命令让日常使用更接近 Slurm 的sbatch/scancel/squeue等原子命令。这一设计在仓库中已经落地为 cmd/cli/vsub/、cmd/cli/vcancel/、cmd/cli/vsuspend/、cmd/cli/vresume/、cmd/cli/vjobs/、cmd/cli/vqueues/ 六个独立可执行程序均通过 cobra 以cli.Run启动见各目录下的main.go。面向普通用户Common User旧格式新格式vcctl job run -N job_namevsub -j/--job-name job_filevcctl job delete -N job_name -n namespacevcancel -n job_name -N namespacevcctl job suspend -N job_name -n namespacevsuspend -n job_name -N namespacevcctl job resume -N job_name -n namespacevresume -n job_name -N namespacevcctl job view -N job_name -n namespacevjobs -n job_name -N namespacevcctl job list -S scheduler -n namespacevjobs -S scheduler -N namespacevcctl queue get -n queue_namevqueues -n queue_namevcctl queue listvqueues注意新格式短参数的统一约定-n表示作业名、-N表示命名空间与vcctl旧格式相反。例如# 取消删除名为 myjob 的作业 vcancel -n myjob -N default # 挂起 / 恢复作业 vsuspend -n myjob -N default vresume -n myjob -N default # 查看作业 / 按调度器列举作业 vjobs -n myjob -N default vjobs -S volcano -N default # 查看单个队列 / 全部队列 vqueues -n default vqueues以 pkg/cli/vcancel/cancel.go 为例InitCancelFlags把-n/--name绑定到作业名、-N/--namespace绑定到命名空间默认defaultCancelJob要求作业名必填随后直接调用jobClient.BatchV1alpha1().Jobs(namespace).Delete(...)完成删除。vsuspendpkg/cli/vsuspend/suspend.go和vresume则通过util.CreateJobCommand向作业发送AbortJobActionsuspend与对应的恢复动作命令走的同样是 Volcano 的 Command 机制。这些实现与vcctl旧格式的子命令共用同一套pkg/cli业务逻辑因此新旧格式行为等价只是参数风格不同。vsub通过脚本文件提交批处理作业新格式中最有 Slurmsbatch味道的是vsub的脚本式提交vsub可以接收一个.sh文件解析文件头部以#VSUB开头的指令行作为作业参数然后提交为 Volcano Job。[userhost]$ vsub test.sh Submitted batch job testtest.sh的格式如下#VSUB指令定义作业的元数据之后是脚本正文脚本正文会成为容器启动后执行的命令#!/bin/bash #VSUB jobName test #VSUB namespace volcano-system #VSUB queue default #VSUB schedulerName volcano #VSUB image busybox #VSUB replicas 10 #VSUB minAvailable 4 ... echo test.sh start on $(date) sleep 100 echo test.sh end on $(date)当前仓库中vsub的实现位于 pkg/cli/vsub/run.go它同样支持-i/--image、-n/--name、-N/--namespace、-m/--min、-r/--replicas、-R/--requests、-L/--limits、-S/--scheduler以及额外的-c/--command通过shlex.Split拆分成容器 command见 pkg/cli/vsub/run.go。特别地vsub支持通过环境变量设置默认值见 pkg/cli/vsub/run.go 与setDefaultArgs函数VOLCANO_SCHEDULER_NAME默认调度器名缺省回落到volcanoVOLCANO_DEFAULT_IMAGE默认镜像缺省回落到busyboxVOLCANO_DEFAULT_JOB_NAMESPACE默认作业命名空间缺省回落到default。命令行显式参数优先于环境变量环境变量优先于内置默认值。这套三级覆盖机制让 HPC 管理员可以按集群习惯统一配置默认提交行为而无需在每个作业脚本里重复书写。需要说明的是设计文档中#VSUB指令头解析属于该文档提出的设计目标当前仓库的vsub实现聚焦于命令行参数 环境变量 -c命令的组合提交方式见 cmd/cli/vsub/main.go 中 yaml/json file is not accepted 的描述#VSUB指令头的完整解析可作为后续增强方向理解二者并不冲突。面向管理员Administrator设计文档同样为管理员规划了一套vadmin系列命令将队列管理从vcctl queue operate拆分为更直白的原子命令旧格式新格式vcctl queue create -n queue_name -w weightvadmin qcreate -n queue_name -w weightvcctl queue delete -n queue_namevadmin qcancel -n queue_namevcctl queue operate -a open -n queue_namevadmin qopen -n queue_namevcctl queue operate -a close -n queue_namevadmin qclose -n queue_namevcctl queue operate -a update -n queue_name -w weightvadmin qupdate -n queue_name -w weight其底层语义与vcctl queue operate的open/close/update三种动作一一对应实现同样可参考 pkg/cli/queue/operate.goqopen/qclose对应发送OpenQueueAction/CloseQueueAction命令qupdate对应带权重的 merge patch。这一拆分让管理员的日常操作不再需要记忆-a open、-a close这样的动作枚举命令意图一目了然。命令体系的统一性源码与测试印证新旧两套命令体系并非两套割裂的代码从 cmd/cli/job.go 到 pkg/cli/job/ 的注册与实现分层可以看出所有 CLI 都统一走cmd/cli/*命令定义→pkg/cli/*业务逻辑→volcano.sh/apis/pkg/client访问 apiserver的调用链且共享BuildConfig、PopulateResourceListV1、CheckError、CreateQueueCommand等公共工具pkg/cli/util/util.go。仓库同时提供了多层验证手段单元测试如 pkg/cli/job/run_test.go 用httptest.NewServer模拟 apiserver 对vcctl job run的创建行为进行测试覆盖 YAML 文件提交与参数构造路径端到端测试test/e2e/vcctl/vcctl.go 通过执行vcctl job --help、vcctl job list --help、vcctl job suspend --help、vcctl job resume --help、vcctl job run --help并校验输出锁定了各子命令的参数、简写与默认值的稳定契约——本文上面列出的参数表格即可视为该契约的文档化呈现。结语如何选用两套命令综合设计文档与当前仓库源码Volcano 命令行的整体图景可以概括为三条路径vcctl全功能子命令覆盖作业、队列、JobFlow、JobTemplate、Pod 五大对象参数风格统一作业名-N、命名空间-n适合脚本自动化与全量管理新格式短命令vsub/vcancel/vsuspend/vresume/vjobs/vqueues面向普通用户日常高频操作参数约定对调作业名-n、命名空间-N并支持环境变量默认值接近sbatch/scancel的使用习惯vadmin管理员命令设计目标面向管理员拆解队列开关、更新等原子操作底层复用vcctl queue operate的动作语义。设计文档所参考的 Slurm/LSF 命令映射Reference 小节为这套体系提供了清晰的HPC 用户心智兼容设计依据。实际使用时建议普通用户优先采用短命令、脚本化提交采用vsub、集群级管理继续使用vcctl或按规划落地vadmin同时留意两套体系短参数大小写约定的差异即可在 Kubernetes 批处理场景中获得接近传统 HPC 调度系统的操作体验。【免费下载链接】volcanoA Cloud Native Batch System (Project under CNCF)项目地址: https://gitcode.com/GitHub_Trending/vol/volcano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考