Argo Workflows Workflow Spec 结构解析从 Kubernetes 头部到模板编排【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows导读本文基于 Argo Workflows 官方 Walk-through 系列中《The Structure of Workflow Specs》一文系统拆解 Workflow 清单Manifest的两层结构Kubernetes 标准头部与spec主体并深入每一个模板Template内部的输入、输出与执行体组织方式。读完本文你将能够读懂任意一个 Workflow YAML 的骨架理解 entrypoint 如何驱动模板调用链掌握 container 与 steps 两类模板的编写方法以及 Workflow 的 container 段为何能直接复用 Pod Spec 的全部能力。从整体看 Workflow Spec一个清单两层结构在 Argo Workflows 中Workflow 是运行在 Kubernetes 之上的自定义资源CRD。因此一份 Workflow 清单天然由两部分构成——Kubernetes 标准头部与Argo 特有的 spec 主体。官方文档将其概括为Kubernetes 头部header包含apiVersion、kind与元数据meta-dataSpec 主体spec body包含Entrypoint 调用可携带可选参数一组模板template定义列表。逐层向下每个模板定义又由以下部分组成模板名称name可选的输入inputs列表可选的输出outputs列表一个容器调用container即叶子模板或一个步骤列表steps其中每个步骤都会调用另一个模板。这一结构在仓库中的 Go 类型定义里有着完全对应的实现WorkflowSpec与Template两个结构体定义在 pkg/apis/workflow/v1alpha1/workflow_types.go 中WorkflowSpec从 第 299 行 开始Template从 第 706 行 开始。CRD 的完整字段说明可以查阅 docs/fields.md 中的 WorkflowSpec 与 Template 两节。可以说Kubernetes 头部 spec 主体这种分层正是 Argo Workflows 能原生融入 Kubernetes 生态kubectl、RBAC、Secret、Volume的根本原因。第一层Kubernetes 头部与元数据任何 Workflow 清单的第一层都是标准 Kubernetes 头部。以仓库中最基础的示例 examples/hello-world.yaml 为例apiVersion: argoproj.io/v1alpha1 kind: Workflow metadata: generateName: hello-world- labels: workflows.argoproj.io/archive-strategy: false annotations: workflows.argoproj.io/description: | This is a simple hello world example. spec: entrypoint: hello-world templates: - name: hello-world container: image: busybox command: [echo] args: [hello world]这里的关键信息apiVersion: argoproj.io/v1alpha1表明这是 Argo Workflows 定义的 API 组与版本kind: Workflow是 Argo 新增的一种 Kubernetes 资源类型而非 Pod 或 Job这一点在 docs/walk-through/hello-world.md 中有明确说明metadata中既可以使用generateName如上例让控制器自动生成带随机后缀的名字也可以使用name固定资源名labels与annotations与普通 Kubernetes 资源一致。由于 Workflow 是标准 CRDmetadata段的写法与普通 Kubernetes 对象完全相同这意味着你可以用kubectl直接创建、查看和删除 Workflow也可以借助 label/annotation 实现归档策略、描述信息等扩展能力。第二层Spec 主体 —— Entrypoint 与 Templates头部之下是spec主体它只做两件事声明从哪个模板开始执行定义可被引用的模板集合。这在WorkflowSpec结构体中体现得极为直白// Entrypoint is a template reference to the starting point of the workflow. Entrypoint string json:entrypoint,omitempty // Arguments contain the parameters and artifacts sent to the workflow entrypoint Arguments Arguments json:arguments,omitempty // Templates is a list of workflow templates used in a workflow Templates []Template json:templates,omitempty见 workflow_types.goEntrypoint工作流的起点entrypoint是对某个模板的引用它指定 Workflow 执行时第一个被调用的模板。官方文档特别指出当 Workflow 中定义了多个模板时指定 entrypoint 就尤为重要——因为执行器需要明确知道从哪里开始。仓库 examples/arguments-parameters.yaml 演示了 entrypoint 与 spec 级参数arguments配合的写法apiVersion: argoproj.io/v1alpha1 kind: Workflow metadata: generateName: arguments-parameters- spec: entrypoint: print-message # Parameters can be passed/overridden via the argo CLI. # To override the printed message, run argo submit with the -p option: # $ argo submit examples/arguments-parameters.yaml -p messagegoodbye world arguments: parameters: - name: message value: hello world templates: - name: print-message inputs: parameters: - name: message container: image: busybox command: [echo] args: [{{inputs.parameters.message}}]这里的spec.arguments.parameters会作为入口参数传给 entrypoint 模板而argo submit -p messagegoodbye world可以在命令行覆盖默认值。由源码注释可见Workflow 级参数还可以通过workflow.parameters.myparam这样的变量前缀在工作流内全局引用见 workflow_types.go。Templates模板定义列表templates是Template结构体的列表。需要注意两个来自 CRD 校验规则的约束单个 Workflow 中模板数量上限为 200MaxItems200这是为了避免过高的 CEL 校验成本每个模板只能拥有一种执行体类型——container、script、dag、steps、resource、suspend、containerSet、data、http、plugin 中至多出现一个template must have at most one template type。这两条规则都写在 workflow_types.go 的校验注解中是理解模板定义边界的第一手依据。第三层单个模板的内部结构回到官方文档给出的模板四要素名称、可选输入、可选输出、执行体。Template结构体原样反映了这一设计// Name is the name of the template Name string json:name,omitempty // Inputs describe what inputs parameters and artifacts are supplied to this template Inputs Inputs json:inputs,omitempty // Outputs describe the parameters and artifacts that this template produces Outputs Outputs json:outputs,omitempty // Steps define a series of sequential/parallel workflow steps Steps []ParallelSteps json:steps,omitempty // Container is the main container image to run in the pod Container *apiv1.Container json:container,omitempty见 workflow_types.goname模板名称受正则^[a-zA-Z0-9][-a-zA-Z0-9]*$约束且长度不超过 128是模板被 entrypoint、steps、dag 任务引用的唯一标识inputs可选声明该模板需要接收的参数parameters与工件artifactsoutputs可选声明该模板产出并对外暴露的参数与工件执行体二选一或多选一见上文至多一种执行体类型的校验——要么是container叶子执行体要么是steps或dag等复合编排体。叶子模板Container 调用当模板直接运行一个容器时它就是叶子模板leaf template。container字段的类型是*apiv1.Container——直接复用了 Kubernetes 标准core/v1.Container类型这一点意义重大详见下文与 Pod Spec 的兼容性一节。Hello World 示例中的hello-world模板就是最典型的叶子模板image: busybox、command: [echo]、args: [hello world]执行完毕即结束不再派生子任务。复合模板Steps 列表与模板调用链当模板需要编排多个任务时它使用steps字段。官方文档对 steps 的定性是每个步骤都调用另一个模板。仓库 examples/steps.yaml 给出了标准写法apiVersion: argoproj.io/v1alpha1 kind: Workflow metadata: generateName: steps- spec: entrypoint: hello-hello-hello templates: - name: hello-hello-hello steps: - - name: hello1 template: print-message arguments: parameters: [{name: message, value: hello1}] - - name: hello2a template: print-message arguments: parameters: [{name: message, value: hello2a}] - name: hello2b template: print-message arguments: parameters: [{name: message, value: hello2b}] - name: print-message inputs: parameters: - name: message container: image: busybox command: [echo] args: [{{inputs.parameters.message}}]这个例子同时揭示了 steps 的两条关键语义模板即步骤hello-hello-hello模板本身不运行容器它通过steps引用了三次print-message模板而print-message才是真正执行echo的叶子模板。列表的嵌套即编排顺序steps是列表的列表[]ParallelSteps见 workflow_types.go。外层每个子列表代表一个阶段stage阶段之间串行同一阶段内的步骤并行。因此该示例中hello1先执行完毕之后hello2a与hello2b并行执行。同时步骤通过arguments.parameters把参数message传入被调用模板而print-message模板通过inputs.parameters声明入参并在容器命令中用{{inputs.parameters.message}}占位符完成替换——这就是每个步骤调用另一个模板这一链式结构的完整闭环。更多关于 steps 编排的细节可继续阅读 docs/walk-through/steps.md参数机制见 docs/walk-through/parameters.md。与 Pod Spec 的兼容性Container 段的完整能力官方文档特别强调了一条容易忽略但极为重要的设计Workflow spec 中的 container 段接受与 Pod spec 的 container 段完全相同的选项包括但不限于环境变量environment variablesSecrets卷挂载volume mounts同理Workflow 级也支持卷声明volume claims与卷volumes。这一保证的根源在于类型定义Template.Container直接使用 Kubernetes 的*apiv1.Container类型见 workflow_types.go而不是 Argo 自造的简化类型。因此你在 Pod 里能给容器配置的一切——env、envFrom、volumeMounts、resources、imagePullPolicy、ports、securityContext、livenessProbe等——都可以原样写进模板的container段。与之配套WorkflowSpec还提供了与 Pod 对等的编排能力volumesWorkflow 级卷列表可被各容器挂载workflow_types.govolumeClaimTemplatesPVC 模板列表控制器会在 Workflow 开始时创建 PVC、在 Workflow 结束时删除workflow_types.go模板级同样可以声明volumes、initContainers、sidecars见 workflow_types.go。这意味着你在编写 Workflow 时可以把已有的 Pod/Deployment 容器配置几乎原样搬入模板Secrets、ConfigMap、PVC 的接入方式与原生 Kubernetes 完全一致学习与迁移成本极低。从二选一到多选一执行体类型的现代扩展官方文档撰写时所描述的是container 或 steps两类执行体而从当前仓库的Template结构体workflow_types.go可以看出Argo Workflows 已将该模型扩展为多种执行体类型且它们遵循同样的一个模板一种执行体规则执行体字段作用文档参考container运行单个容器叶子模板docs/walk-through/hello-world.mdsteps串行/并行步骤编排examples/steps.yaml、docs/walk-through/steps.mddag基于依赖关系的有向无环图编排examples/dag-diamond.yamlscript在解释器容器中运行脚本片段examples/scripts-bash.yamlresource直接创建/管理 Kubernetes 资源examples/k8s-jobs.yamlsuspend挂起流程等待人工批准examples/suspend-template.yamlcontainerSet在单个 Pod 内运行多个容器examples/container-set-template/parallel-workflow.yamldata数据转换模板examples/data-transformations.yamlhttp发起 HTTP 请求examples/http-hello-world.yamlplugin使用自定义插件模板自由格式结构examples/workflow-level-executor-plugin.yaml无论是哪种执行体它们都遵守本文所讲的外层骨架模板有名字、可选输入、可选输出而 steps/dag 等复合模板内部引用的仍是其他模板——整套模板调用模板的递归模型保持不变。这也正是Workflow spec 由一组 Argo 模板构成每个模板包含可选输入、可选输出以及容器调用或步骤列表这一官方总结在今日依然成立的深层原因。小结一张图读懂 Workflow Spec 的骨架把官方文档的层次结构整理成如下骨架可作为阅读任意 Workflow YAML 的速查表Workflow 清单 ├── Kubernetes 头部 │ ├── apiVersion: argoproj.io/v1alpha1 │ ├── kind: Workflow │ └── metadatagenerateName/name、labels、annotations └── spec 主体 ├── entrypoint指定起始模板可携带 arguments 参数 ├── arguments可选传给 entrypoint 的参数与工件 └── templates模板定义列表 └── 每个模板 ├── name模板唯一标识 ├── inputs可选入参 parameters / artifacts ├── outputs可选出参 parameters / artifacts └── 执行体至多一种 ├── container叶子模板直接运行容器 └── steps / dag 等复合模板内部步骤再调用其他模板实践中读者可以对照 examples/hello-world.yaml单模板、纯 container 叶子、examples/arguments-parameters.yamlentrypoint arguments inputs 参数链路与 examples/steps.yaml复合 steps 编排 模板调用链三个示例逐层验证本文总结的结构。如果想继续系统学习官方 Walk-through 系列建议按顺序阅读 docs/walk-through/argo-cli.md 起步随后进入参数、工件、步骤、DAG 等专题完整字段级说明则以 docs/fields.md 中的WorkflowSpec与Template两节为最终权威参考。【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考