Argo Workflows `argo template` 命令全解:WorkflowTemplate 的创建、查询、校验与生命周期管理

原创2026-09-20 18:54:241,973 阅读
文章标签:工作流自动化云原生容器编排任务调度DevOps后端前端微服务机器学习

Argo Workflows argo template 命令全解:WorkflowTemplate 的创建、查询、校验与生命周期管理

argo template 是 Argo Workflows CLI(argo)中专门用于操作工作流模板(WorkflowTemplate)的子命令集合,涵盖模板的创建、查询、列表、删除、校验与更新六大操作。本文以官方 CLI 参考文档 docs/cli/argo_template.md 为主体骨架,结合仓库中 cmd/argo/commands/template/ 目录下的源码实现与 examples/workflow-template/ 下的真实示例,完整讲解该命令的语法、全部参数、六个子命令的用法及其底层调用链,帮助你在 Kubernetes 集群中高效管理可复用的工作流模板。

一、命令概览:什么是 argo template

argo template 是 Argo CLI 的二级子命令,其用途在官方文档中定义为 "manipulate workflow templates"(操作工作流模板)。WorkflowTemplate 是 Argo Workflows 中一种可复用的工作流定义资源(kind: WorkflowTemplate,API 版本 argoproj.io/v1alpha1),它将常用的步骤、DAG 编排、容器执行逻辑固化为模板,供多个 Workflow 引用,实现"一次定义、多处复用"。

从源码看,该命令由 cmd/argo/commands/template/root.go 中的 NewTemplateCommand() 构建,通过 Cobra 框架向 argo template 注册了六个子命令:

command.AddCommand(NewGetCommand())
command.AddCommand(NewListCommand())
command.AddCommand(NewCreateCommand())
command.AddCommand(NewDeleteCommand())
command.AddCommand(NewLintCommand())
command.AddCommand(NewUpdateCommand())

这与参考文档 "SEE ALSO" 一节列出的六个子命令一一对应。执行 argo template(不带子命令)时,RunE 直接调用 cmd.Help() 输出帮助信息。

二、基本语法与顶层选项

2.1 命令语法

argo template [flags]

由于 template 本身不直接执行操作,而是命令分组,因此通常需要配合子命令使用,完整形式为:

argo template <create|get|list|delete|lint|update> [args] [flags]

2.2 本命令选项

选项 说明
-h, --help 显示 template 命令的帮助信息

2.3 继承自父命令的全局选项

argo template 继承了 argo 主命令的全部全局选项,这些选项控制 CLI 与 Argo Server / Kubernetes API Server 的连接方式、认证方式与日志行为,对模板操作同样生效。完整清单如下:

选项 说明
--argo-base-href string 因 Base HREF 需要,HTTP 客户端使用的路径。默认读取 ARGO_BASE_HREF 环境变量
--argo-http1 若为 true,使用 HTTP/1.1 客户端。默认读取 ARGO_HTTP1 环境变量
-s, --argo-server host:port API Server 的地址与端口,例如 localhost:2746。默认读取 ARGO_SERVER 环境变量
--as string 操作时模拟(impersonate)的用户名
--as-group stringArray 模拟的用户组,可重复指定多个组
--as-uid string 模拟的 UID
--certificate-authority string CA 证书文件路径
--client-certificate string TLS 客户端证书文件路径
--client-key string TLS 客户端密钥文件路径
--cluster string 使用的 kubeconfig cluster 名称
--context string 使用的 kubeconfig context 名称
--disable-compression 为 true 时对所有服务器请求关闭响应压缩
--gloglevel int 设置 glog 日志级别
-H, --header strings 为 Argo CLI 的所有请求添加额外的 HTTP 头(可重复添加多个,也支持逗号分隔)。仅在 ARGO_HTTP1 或 --argo-http1 为 true 时生效
--insecure-skip-tls-verify 为 true 时不校验服务器证书有效性(会使 HTTPS 连接不安全)
-k, --insecure-skip-verify 为 true 时不校验 Argo Server 证书有效性。默认读取 ARGO_INSECURE_SKIP_VERIFY 环境变量
--instanceid string 以特定 controller 的 instance id 标签提交。默认读取 ARGO_INSTANCEID 环境变量
--kubeconfig string kubeconfig 文件路径,仅集群外使用时需要
--log-format string 日志格式,取值 text 或 json(默认 text)
--loglevel string 日志级别,取值 debug、info、warn、error(默认 info)
-n, --namespace string CLI 请求的命名空间作用域
--password string API Server 基本认证的密码
--proxy-url string 若提供,通过该代理 URL 连接
--request-timeout string 单个服务器请求的超时时间,非零值需包含时间单位(如 1s、2m、3h),零值表示不超时(默认 "0")
-e, --secure 是否使用 TLS 连接 Argo Server。默认读取 ARGO_SECURE 环境变量(默认 true)
--server string Kubernetes API Server 的地址和端口
--tls-server-name string 校验服务器证书时使用的名称,未提供时使用连接服务器的主机名
--token string API Server 认证的 Bearer token
--user string 使用的 kubeconfig 用户名称
--username string API Server 基本认证的用户名
-v, --verbose 开启详细日志,等价于 --loglevel debug

使用提示:集群内运行时通常只需 -n <namespace> 指定命名空间;集群外(本地开发)则需通过 -s localhost:2746 指定 Argo Server 地址,或通过 --kubeconfig 指向集群配置文件。

三、六个子命令详解(含源码级调用链)

3.1 argo template create:创建工作流模板

语法:

argo template create FILE1 FILE2... [flags]

选项:

选项 说明
-h, --help 帮助信息
-o, --output string 输出格式,取值 name、json、yaml、wide
--strict 执行严格的工作流校验(默认 true)

源码调用链:入口为 cmd/argo/commands/template/create.go 的 CreateWorkflowTemplates(),其流程为:

  1. 通过 client.NewAPIClient(ctx) 建立 API 客户端,并创建 WorkflowTemplateServiceClient;
  2. 调用 generateWorkflowTemplates() 读取并解析清单文件(见 3.7 节的解析细节);
  3. 若模板未显式声明 namespace,则填充为 client.Namespace(ctx)(即 -n 指定的命名空间);
  4. 逐个调用 gRPC 接口 CreateWorkflowTemplate 提交到 Argo Server;
  5. 按 -o 指定的格式输出结果。

实战示例:

# 创建单个模板文件
argo template create examples/workflow-template/templates.yaml -n argo

# 一次创建多个文件,并以 YAML 格式输出结果
argo template create wf1.yaml wf2.yaml -o yaml

# 只输出创建的模板名称
argo template create wf.yaml -o name

# 关闭严格校验(宽松模式)
argo template create wf.yaml --strict false

3.2 argo template get:查看模板详情

语法:

argo template get WORKFLOW_TEMPLATE... [flags]

选项:

选项 说明
-h, --help 帮助信息
-o, --output string 输出格式,取值 name、json、yaml、wide(默认空,即 human-readable 摘要)

源码实现(cmd/argo/commands/template/get.go):对每个传入的模板名称,调用 GetWorkflowTemplate gRPC 接口获取对象,再交给 printWorkflowTemplate() 渲染。该命令支持一次查询多个模板名称。

实战示例:

# 按名称查看模板摘要(名称、命名空间、创建时间)
argo template get my-template -n argo

# 以 YAML 格式导出模板完整定义
argo template get my-template -o yaml

# 以 JSON 格式查看
argo template get my-template -o json

# 一次查看多个模板
argo template get tmpl-a tmpl-b -n argo

从 cmd/argo/commands/template/util.go 中的 printWorkflowTemplate() 可以看出各输出格式的渲染逻辑:name 只打印模板名;json 使用 json.MarshalIndent 输出缩进 JSON;yaml 使用 sigs.k8s.io/yaml 输出 YAML;wide 或空值则调用 printWorkflowTemplateHelper() 打印 Name、Namespace、Created(创建时间经 humanize.Timestamp 格式化)三行摘要。

3.3 argo template list:列出工作流模板

语法:

argo template list [flags]

选项(来自 cmd/argo/commands/template/list.go):

选项 说明
-A, --all-namespaces 显示所有命名空间中的模板
-h, --help 帮助信息
-o, --output string 输出格式,取值 wide(默认)或 name
-l, --selector string 标签选择器(label query),支持 =、==、!=,例如 -l key1=value1,key2=value2

源码实现:先解析 -l 标签选择器(labels.Parse),然后调用 ListWorkflowTemplates gRPC 接口,将 LabelSelector 一并传入服务端。若指定 -A,命名空间设为 apiv1.NamespaceAll(即全命名空间)。输出时使用 tabwriter 对齐列;-A 时额外增加 NAMESPACE 列。

实战示例:

# 列出当前命名空间下的全部模板
argo template list -n argo

# 列出所有命名空间的模板
argo template list -A

# 只输出模板名称
argo template list -o name

# 按标签过滤
argo template list -l team=data,env=prod -n argo

3.4 argo template delete:删除工作流模板

语法:

argo template delete WORKFLOW_TEMPLATE [flags]

选项:

选项 说明
--all 删除所有工作流模板
-h, --help 帮助信息

源码实现(cmd/argo/commands/template/delete.go):apiServerDeleteWorkflowTemplates() 中,若指定 --all,先 ListWorkflowTemplates 取回全部模板名,再逐个调用 DeleteWorkflowTemplate gRPC 接口;删除成功后打印 WorkflowTemplate '<name>' deleted。

实战示例:

# 删除指定模板
argo template delete my-template -n argo

# 删除当前命名空间下全部模板
argo template delete --all -n argo

注意:删除属于破坏性操作,--all 会删除当前命名空间(或 -A 相关作用域)内的所有 WorkflowTemplate,执行前请确认。

3.5 argo template lint:校验模板清单

语法:

argo template lint (DIRECTORY | FILE1 FILE2 FILE3...) [flags]

选项(来自 cmd/argo/commands/template/lint.go):

选项 说明
-h, --help 帮助信息
-o, --output string 校验结果输出格式,取值 pretty(默认)或 simple
--strict 执行严格的工作流校验(默认 true)

源码实现:该命令接收文件或目录路径,构造 lint.Options{Files, Strict, DefaultNamespace, Printer} 后调用 lint.RunLint(ctx, apiClient, []string{wf.WorkflowTemplatePlural}, output, false, opts),其中 WorkflowTemplatePlural 表明校验对象类型为 workflowtemplate 复数资源。值得注意的是,lint 同样需要建立 API 客户端,因为它不仅要解析清单语法,还会对模板内部的引用关系(如 templateRef)做深层校验。

实战示例:

# 校验单个文件
argo template lint examples/workflow-template/templates.yaml -n argo

# 校验整个目录
argo template lint ./workflow-template/ -n argo

# 使用 simple 格式输出校验结果
argo template lint wf.yaml -o simple

# 关闭严格校验
argo template lint wf.yaml --strict false

3.6 argo template update:更新工作流模板

语法:

argo template update FILE1 FILE2... [flags]

选项:

选项 说明
-h, --help 帮助信息
-o, --output string 输出格式,取值 name、json、yaml、wide
--strict 执行严格的工作流校验(默认 true)

源码实现(cmd/argo/commands/template/update.go):updateWorkflowTemplates() 的流程与 create 类似,但增加了一个关键步骤——更新前先调用 GetWorkflowTemplate 获取集群中已有对象的 ResourceVersion,并回填到待更新模板中,再调用 UpdateWorkflowTemplate gRPC 接口。这一设计保证了更新操作基于当前版本执行(符合 Kubernetes 乐观锁语义),避免覆盖并发修改。

实战示例:

# 更新模板(以文件中的定义覆盖同名模板)
argo template update FILE1 -n argo

# 更新后以 YAML 打印结果
argo template update FILE1 --output yaml

# 以宽松校验模式更新
argo template update FILE1 --strict false

3.7 底层清单解析与输出逻辑

create 与 update 共用的清单解析逻辑集中在 cmd/argo/commands/template/util.go:

  • generateWorkflowTemplates():通过 util.ReadManifest 读取所有指定文件,逐文件解析出 WorkflowTemplate 列表;若解析结果为空,直接 log.Fatalln("No workflow template found in given files")。
  • unmarshalWorkflowTemplates():先以 JSON 方式反序列化,strict 模式下会追加 argoJson.DisallowUnknownFields(拒绝未知字段);JSON 解析失败后再通过 common.SplitWorkflowTemplateYAMLFile 按 --- 分割多文档 YAML 逐个解析——这正是仓库示例文件使用多文档 YAML 的原因。

验证示例:仓库 examples/workflow-template/templates.yaml 在一个文件中定义了 5 个模板(以 --- 分隔),包括最简单的 print-message 容器模板、带 retryStrategy 的随机失败模板、通过 templateRef 引用其他模板的 steps/DAG 组合模板,以及带默认 arguments 的可直接提交模板(submittable)。用以下命令即可一次性全部创建:

argo template create examples/workflow-template/templates.yaml -n argo

输出格式方面,printWorkflowTemplate() 对 json、yaml、name、wide 四种格式分别处理,未知格式则报错 Unknown output format。

四、典型工作流:模板的完整生命周期管理

结合以上子命令,一套完整的 WorkflowTemplate 管理流程如下:

# 1. 校验清单(CI 阶段即可执行)
argo template lint workflow-template/ -n argo

# 2. 创建模板
argo template create workflow-template/templates.yaml -n argo

# 3. 查询确认
argo template list -n argo
argo template get workflow-template-print-message -o yaml

# 4. 修改文件后更新模板
argo template update workflow-template/templates.yaml -n argo

# 5. 不再使用时删除(按名称)
argo template delete workflow-template-print-message -n argo

这些模板随后即可被 Workflow 通过 templateRef 引用,或在创建 CronWorkflow 时作为 workflowSpec 的模板来源,实现编排逻辑的集中管理与版本迭代。

五、命令速查总表

子命令 用途 核心参数
create 从文件创建模板 -o(name/json/yaml/wide)、--strict
get 查看模板详情 -o(name/json/yaml/wide)
list 列出模板 -A、-o(wide/name)、-l(标签选择器)
delete 删除模板 --all
lint 校验模板清单 -o(pretty/simple)、--strict
update 按文件更新模板 -o(name/json/yaml/wide)、--strict

所有子命令均可叠加 -n/--namespace 指定命名空间,并共享 docs/cli/argo_template.md 中列出的全部全局选项;strict 模式(默认开启)会拒绝清单中的未知字段,适合在 CI 中对模板定义做严格把关。

六、延伸阅读

登录后查看全文
argo-workflows