pipeline-frameworks-argo-05.WorkflowTemplate使用与选型

Argo 系列：01 入门简介 · 02 常用命令 · 03 操作 Pod · 04 Argo 封装 MCP · 05 WorkflowTemplate（本文）

1. 先建立直觉：蓝图 vs 一次运行

资源	类比	创建后
WorkflowTemplate	流程的「类定义 / 标准作业指导书」	不跑任务，只把 DAG、镜像、默认参数存进集群
Workflow	某次「函数调用 / 一次实验记录」	立即执行，产生 `status`、Pod、日志

两者 spec 结构（entrypoint、templates、arguments 等）高度相似，但 WorkflowTemplate 不会被 Controller 当作运行实例调度；只有实例化成 Workflow 后才会创建 Pod。

段末注释：DAG（Directed Acyclic Graph，有向无环图）描述步骤依赖；Argo 用 steps 或 dag 模板表达。CRD（Custom Resource Definition）是 Kubernetes 扩展 API 的机制，Workflow 与 WorkflowTemplate 均为 CRD，apiVersion 通常为 argoproj.io/v1alpha1。

2. 为什么需要 WorkflowTemplate：相对「每次直接 Workflow」的优势

许多入门示例用 argo submit workflow.yaml（kind: Workflow）跑通第一条流程，这很自然。但当同一套流程要被 多人、多系统、多次 重复触发时，每次都携带完整 Workflow YAML 会带来明显成本。WorkflowTemplate 把「流程定义」与「单次运行」拆开，优势集中在下面几类。

2.1 定义复用，避免 YAML 膨胀与漂移

痛点（每次直接 Workflow）	Template 做法
每个项目复制一份 200～500 行 YAML，镜像/tag 各改各的	集群内一份 Template，submit 只传 `-p` 参数
修一个 bug 要改 N 份文件 / N 个 Git 分支	`kubectl apply` 一次更新 Template，后续 submit 自动用新版本
Code review 难以看出「这次运行」改了流程还是只改了样本 ID	运行侧 YAML 极短，差异只在 `arguments`

本质：流程逻辑（how）与运行输入（what）分离，和软件工程里「库函数 vs 调用参数」同一思路。

2.2 投递轻量：CLI / API / MCP 只传参

直接 Workflow 投递时，客户端要带 完整 spec（或本地大文件）：

1	argo submit -n bio-ns huge-pipeline.yaml -p sample-id=S001

WorkflowTemplate 投递时，客户端只需 模板名 + 参数（见 02 常用命令 §2.2）：

1 2	argo submit -n bio-ns --from workflowtemplate/rnaseq-qc \ -p sample-id=S001 -p ref=hg38

对 CI、MCP 网关、内部 API 而言：Template 名是稳定常量，参数是 JSON/schema 约束字段——这正是 argo-04 MCP 封装推荐的模式。

2.3 治理与权限：谁改流程、谁只能跑

角色	直接 Workflow	WorkflowTemplate
平台 / 流程负责人	难以阻止用户改 DAG 里的镜像	`apply` Template 需较高 RBAC；普通用户仅 `create workflows`
分析员	可随意改 YAML 里任意步骤	只能 submit + 覆盖 parameters
审计	每次 submit 的 YAML 可能不同	Template 版本在集群可追溯；实例 Workflow 只记录本次参数

可在 Template 上打 label（team=rnaseq、version=2.1），配合 GitOps 或 Argo CD 做 模板发布流程。

2.4 与 CronWorkflow、UI、监控的天然集成

CronWorkflow 通常引用 WorkflowTemplate（或内嵌 spec），定时触发产生的仍是 Workflow 实例——定时规则与流程定义解耦。
Argo UI 可按 WorkflowTemplate 筛选历史运行、嵌入「由某模板产生的最新 Workflow」widget（v3+ UI 能力）。
指标如 workflowtemplate_triggered_total（v3.6+）按模板统计触发次数，便于容量规划。

2.5 集群级共享：ClusterWorkflowTemplate

命名空间内用 WorkflowTemplate；跨 namespace 共享同一套流程用 ClusterWorkflowTemplate（集群级 CRD，无 metadata.namespace）：

1	argo submit -n team-a --from clusterworkflowtemplate/org-standard-qc -p sample-id=X

适合「公司统一 QC 流程、各项目 namespace 各自投递」的组织结构。

2.6 何时「直接 Workflow」仍然更合适

Template 不是银弹。以下场景 继续直接 submit Workflow 往往更省事：

场景	原因
本地第一次搭流程、频繁改 DAG	改 Template 要 apply + 权限，迭代慢
一次性 adhoc 实验	无复用价值，不必污染集群模板库
CI 把完整 Workflow YAML 当构建产物版本化	定义随 Git commit 走，Template 反而多一层同步
每次运行的结构本身不同（步骤数、DAG 拓扑变）	Template 适合固定拓扑 + 参数化；拓扑常变应生成 Workflow

选型原则：同一 DAG 拓扑跑很多次 → Template；拓扑或镜像逻辑每次都不一样 → Workflow。

3. 构建 YAML：两者写法的区别

3.1 结构对照

WorkflowTemplate（安装进集群，不执行）：

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: rnaseq-qc
  namespace: bio-ns
spec:
  entrypoint: main
  arguments:
    parameters:
      - name: sample-id
      - name: ref
        value: hg38
  templates:
    - name: main
      steps:
        - - name: qc
            template: run-qc
            arguments:
              parameters:
                - name: sample-id
                  value: "{{workflow.parameters.sample-id}}"
    - name: run-qc
      inputs:
        parameters:
          - name: sample-id
      container:
        image: registry.example.com/rnaseq-qc:1.2.0
        command: [qc, --sample, "{{inputs.parameters.sample-id}}"]

Workflow（两种写法）：

写法 A — 完整自包含（适合 adhoc，与 Template 的 spec 几乎相同，仅 kind 不同）：

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: rnaseq-qc-
  namespace: bio-ns
spec:
  # ... 与上面 WorkflowTemplate.spec 相同的大段 templates ...
  arguments:
    parameters:
      - name: sample-id
        value: S001

写法 B — 引用已有 Template（推荐：运行 YAML 极短）：

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: rnaseq-qc-
  namespace: bio-ns
spec:
  workflowTemplateRef:
    name: rnaseq-qc
  arguments:
    parameters:
      - name: sample-id
        value: S001
      - name: ref
        value: hg38

3.2 字段分工建议

内容	放 WorkflowTemplate	放 Workflow 实例
`templates`、镜像、资源 limits、重试策略	✅	❌（引用时不必重复）
默认参数值（如默认 ref）	✅ `spec.arguments.parameters`	可选覆盖
本次样本 ID、输入 URI	占位符定义	✅ `-p` 或 `arguments`
`ttlStrategy`、`podGC`	可放在 Template	也可仅在实例覆盖
`metadata.labels`（项目、批次）	模板级默认	实例级更常见

3.3 安装与更新 Template

Template 用 kubectl apply（或 CI/GitOps）写入集群，不会创建 Pod：

1
2
3

kubectl apply -n bio-ns -f workflow-template-rnaseq-qc.yaml
kubectl get workflowtemplate -n bio-ns
kubectl describe workflowtemplate -n bio-ns rnaseq-qc

更新镜像版本 = 改 Template YAML 再 apply；已在跑的 Workflow 不受影响，新 submit 使用新定义。

4. 任务投递：流程对比

4.1 直接 Workflow 投递路径

sequenceDiagram
    participant U as 用户/CI
    participant A as Argo Server/CLI
    participant K as Kubernetes API
    participant C as Workflow Controller

    U->>A: argo submit huge.yaml (-p ...)
    A->>K: create Workflow（含完整 spec）
    K->>C: watch 新 Workflow
    C->>C: 按 spec 创建 Pod

特点：一次 RPC 既创建定义又触发运行；客户端必须持有完整 YAML 或从 Git 拉取。

4.2 从 WorkflowTemplate 投递路径

sequenceDiagram
    participant U as 用户/CI/MCP
    participant A as Argo Server/CLI
    participant K as Kubernetes API
    participant C as Workflow Controller

    Note over K: WorkflowTemplate 已预先 apply
    U->>A: argo submit --from workflowtemplate/T (-p ...)
    A->>K: create Workflow（ref + 参数）
    K->>C: watch 新 Workflow
    C->>C: 合并 Template spec + 实例参数，创建 Pod

特点：Template 已在集群；submit 请求体小；Template 与实例 解耦版本。

4.3 命令对照表

操作	直接 Workflow	WorkflowTemplate
首次定义流程	`argo submit wf.yaml` 或 `kubectl apply -f wf.yaml`	`kubectl apply -f template.yaml`
触发一次运行	`argo submit wf.yaml -p k=v`	`argo submit --from workflowtemplate/T -p k=v`
干跑看解析结果	`argo submit wf.yaml --dry-run -o yaml`	`argo submit --from workflowtemplate/T -p k=v --dry-run -o yaml`
批量避免重名	`--generate-name prefix-`	同样适用于生成的 Workflow 实例
跟踪运行	`argo get/list/logs`（针对 Workflow 名）	相同——看的永远是 Workflow 实例
改流程逻辑	改本地 YAML 再 submit 新文件	`kubectl apply` 更新 Template，再 submit

4.4 传参覆盖规则

无论哪种来源，实例参数优先级高于 Template 默认值：

1
2
3

# Template 内 ref 默认 hg38；本次覆盖为 mm10
argo submit -n bio-ns --from workflowtemplate/rnaseq-qc \
  -p sample-id=S002 -p ref=mm10

artifact 也可在 submit 时通过 -p 或补充 Workflow 包装 YAML 传入；大文件更常见做法是参数里只传 对象存储 URI（与 argo-04 一致）。

5. 运维与生命周期差异

维度	Workflow 实例	WorkflowTemplate
status.phase	Pending / Running / Succeeded / Failed	无运行 phase
Pod	由实例创建	不创建
删除	`argo delete wf`；可设 TTL 自动清理	`kubectl delete wftmpl`；不影响历史实例
重跑	`argo retry` / `argo resubmit`	应对 Workflow 操作，不是 Template
排障	`argo get`、`argo logs`、03 操作 Pod	模板问题：检查 `kubectl get wftmpl -o yaml`；运行问题：仍查 Workflow

常见误区：删除 WorkflowTemplate 后，已完成的 Workflow 仍在；但 无法再 --from 该模板 submit 新任务，直到重新 apply。

6. 选型决策树

flowchart TD
  Q1{"同一套步骤结构\n会跑 ≥ 2 次？"}
  Q2{"是否需要平台统一\n管镜像/资源/权限？"}
  Q3{"触发方是否只有\n模板名+参数？"}
  Q4{"是否仍在频繁改\nDAG 拓扑？"}

  WF["直接 submit Workflow\n或短 workflowTemplateRef YAML"]
  WFT["维护 WorkflowTemplate\nargo submit --from"]
  HYB["Git 版本化 Workflow YAML\nCI 每次 submit"]

  Q1 -->|否| WF
  Q1 -->|是| Q2
  Q2 -->|是| WFT
  Q2 -->|否| Q3
  Q3 -->|是| WFT
  Q3 -->|否| Q4
  Q4 -->|是| WF
  Q4 -->|否| HYB

6.1 典型场景映射

场景	建议
生信平台标准 QC / 变异检测 pipeline	WorkflowTemplate + 用户只填 sample-id
研发个人调试新步骤	Workflow 直到 DAG 稳定
定时批量（cron）	CronWorkflow → 引用 WorkflowTemplate
MCP / REST 网关触发	WorkflowTemplate 名常量 + Tool 参数映射
多团队共用公司级流程	ClusterWorkflowTemplate
每次 DAG 节点数随样本变化（动态 workflow）	程序生成 Workflow YAML submit，或 Workflow 内 `withParam`

7. 完整最小示例：从安装到投递

7.1 安装 Template

wftmpl-hello.yaml：

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: hello-template
  namespace: my-ns
spec:
  entrypoint: whalesay
  arguments:
    parameters:
      - name: message
        value: hello world
  templates:
    - name: whalesay
      container:
        image: docker/whalesay:latest
        command: [cowsay]
        args: ["{{workflow.parameters.message}}"]

1	kubectl apply -n my-ns -f wftmpl-hello.yaml

7.2 三次运行，只改参数

argo submit -n my-ns --from workflowtemplate/hello-template
argo submit -n my-ns --from workflowtemplate/hello-template -p message=run-2
argo submit -n my-ns --from workflowtemplate/hello-template -p message=run-3
argo list -n my-ns

列表里会出现 三个 Workflow 实例，Template 仍只有一个。

7.3 升级流程（改 Template）

把镜像改为 argoproj/argosay:v2 后 kubectl apply，再 submit——新实例用新镜像，旧实例记录不变。

8. 与系列其他篇章的衔接

篇章	关联
01 入门	顶层 CRD 关键字、`spec` 字段
02 命令	`--from workflowtemplate/`、`-p` 传参
03 Pod	实例化后才产生 Pod；排障对象仍是 Workflow
04 MCP	MCP `submit_*` 内部应 submit Template 而非贴完整 YAML

9. 小结

问题	答案
WorkflowTemplate 是什么？	集群内可复用的流程蓝图，不执行
相比每次 Workflow 的核心优势？	复用、轻量投递、权限治理、与 Cron/MCP 集成
YAML 怎么拆？	重逻辑进 Template；实例只 ref + arguments
怎么投递？	`kubectl apply` Template；`argo submit --from workflowtemplate/NAME -p ...`
什么时候不用 Template？	一次性实验、DAG 仍在剧烈改动、每次拓扑都不同

记住一句：WorkflowTemplate 管「怎么跑」；Workflow 管「这一次跑得怎么样」。 当同一「怎么跑」要服务很多人很多次时，就应该把定义放进 WorkflowTemplate，而不是每次都重新投递一整份 Workflow。

概念索引

术语	含义
WorkflowTemplate	命名空间内可复用的工作流 CRD 定义
ClusterWorkflowTemplate	集群级可复用模板，跨 namespace 引用
workflowTemplateRef	Workflow spec 中引用已安装 Template 的字段
generateName	Workflow metadata 前缀，由集群生成唯一实例名