Argo Workflows CLI 实战:用 `argo template create` 命令创建 WorkflowTemplate 完整指南
Argo Workflows CLI 实战:用 argo template create 命令创建 WorkflowTemplate 完整指南
导读
argo template create 是 Argo Workflows 命令行工具(argo CLI)中负责把 WorkflowTemplate(工作流模板)清单写入 Kubernetes 集群的核心命令。本文以 Argo Workflows 官方 CLI 文档为主线,结合仓库源码(cmd/argo/commands/template/、server/workflowtemplate/)与真实示例(examples/workflow-template/),系统讲解该命令的语法、全部选项、文件输入方式、创建流程的底层原理与常见实战用法。读完本文,你将能熟练地把本地 YAML/JSON 清单、标准输入乃至远程 URL 中的工作流模板批量、安全地创建到目标命名空间,并理解严格校验与输出格式背后的实现机制。
命令概览:WorkflowTemplate 与 create 子命令
WorkflowTemplate(资源类型 workflowtemplates.argoproj.io,kind 为 WorkflowTemplate)是 Argo Workflows 中用于复用工作流定义的模板资源:它定义了一组可被普通 Workflow 通过 templateRef 引用、或被 argo submit --from 直接提交执行的模板集合。与每次都要书写完整工作流的做法相比,它让 CI/CD、数据处理等重复流程具备单一事实来源。
argo template 是管理这类资源的一级命令组,create 是其中用于新建模板的子命令,对应文档 argo template 中列出的六个子命令之一(create / delete / get / lint / list / update)。
argo template create FILE1 FILE2... [flags]
文件输入:支持多个文件、标准输入与 URL
create 的语法要求至少一个文件参数(源码中通过 Args: cobra.MinimumNArgs(1) 强制,见 create.go),参数数量不限,因此可以一次传入多个清单文件:
# 单个文件
argo template create templates.yaml
# 多个文件批量创建
argo template create tmpl-a.yaml tmpl-b.yaml tmpl-c.yaml
# 支持混合传入目录下的多个清单
argo template create examples/workflow-template/templates.yaml
除本地文件外,底层读取逻辑还支持两种特殊来源(见 util.go):
- 标准输入:当唯一参数为
-时,从 stdin 读取清单内容,便于与管道、CI 脚本配合:cat tmpl.yaml | argo template create - - 远程 URL:当参数是 URL 时,直接抓取远程清单(见
ReadFromFilePathsOrUrls,util.go):argo template create https://example.com/templates/workflow-template.yaml
值得强调的是,单文件内可以包含多个用 --- 分隔的 YAML 文档。源码解析时先尝试整体按 JSON 解析,失败后走 SplitWorkflowTemplateYAMLFile 对多文档 YAML 逐个拆分(见 parse.go),其中只有 kind: WorkflowTemplate 的对象会被收集,其余类型会被忽略并告警。仓库自带的 templates.yaml 就是典型的多文档示例,一个文件里连续定义了 5 个 WorkflowTemplate:
apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
name: workflow-template-print-message
spec:
entrypoint: print-message
templates:
- name: print-message
inputs:
parameters:
- name: message
container:
image: busybox
command: [echo]
args: ["{{inputs.parameters.message}}"]
---
apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
name: workflow-template-random-fail-template
spec:
templates:
- name: random-fail-template
retryStrategy:
limit: 10
container:
image: python:alpine3.23
command: [python, -c]
# fail with a 66% probability
args: ["import random; import sys; exit_code = random.choice([0, 1, 1]); sys.exit(exit_code)"]
---
# ... 后续文档(inner-steps、inner-dag、submittable)
这种“一次创建多个模板”的能力让 CI 流水线可以非常方便地同步一批模板定义。
核心选项详解
create 子命令本身只有三个选项(见 create.go):
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
-h, --help |
- | - | 显示 create 的帮助信息 |
-o, --output string |
string | (空,即 wide 风格) | 输出格式,取值为 name、json、yaml、wide 之一 |
--strict |
bool | true |
是否执行严格的工作流校验 |
-o, --output:控制创建结果的回显格式
该标志是一个枚举类型,可选值在白名单 name|json|yaml|wide 中校验(见 flags.go),传入白名单之外的值会直接报错。其渲染逻辑位于 printWorkflowTemplate(见 util.go):
# 只输出创建成功的模板名称(适合脚本中提取模板名)
argo template create templates.yaml -o name
# 以 JSON 格式回显创建后的完整对象
argo template create templates.yaml -o json
# 以 YAML 格式回显创建后的完整对象
argo template create templates.yaml -o yaml
# wide 或默认:以人类可读的摘要形式展示(Name / Namespace / Created)
argo template create templates.yaml -o wide
默认(不带 -o)与 -o wide 走同一个分支,输出如下格式的摘要(见 printWorkflowTemplateHelper,util.go):
Name: workflow-template-print-message
Namespace: default
Created: 2026-09-20 07:30:00 +0000 UTC
--strict:是否启用严格校验
--strict 默认值为 true,控制反序列化阶段是否拒绝未知字段。源码中当 strict 为真时,会给 JSON 解析追加 argoJson.DisallowUnknownFields 选项(见 util.go),这意味着:
--strict(默认):清单中出现 WorkflowTemplate 规范之外的未知字段会解析失败,尽早暴露拼写错误、字段名写错等问题;--strict=false:宽松解析,未知字段被忽略,适合处理包含额外注解字段或历史版本兼容的清单。
建议在正式环境保持默认的严格模式;只有在确认清单本身无误、仅需绕过未知字段告警时才关闭。
继承自父命令的连接与认证选项
argo template create 还继承了所有父命令(argo)级别的选项,这些选项决定了 CLI 如何连接 Argo Server / API Server 以及如何认证。下表按用途分组整理了全部继承选项:
Argo Server 连接
| 选项 | 说明 |
|---|---|
-s, --argo-server host:port |
API Server 地址,如 localhost:2746,默认取环境变量 ARGO_SERVER |
-e, --secure |
是否使用 TLS 连接 Argo Server,默认 true,可用环境变量 ARGO_SECURE 覆盖 |
--argo-base-href string |
因 Base HREF 需要,供 HTTP 客户端使用的路径,默认取 ARGO_BASE_HREF |
--argo-http1 |
为 true 时使用 HTTP/1 客户端,默认取 ARGO_HTTP1 环境变量 |
-k, --insecure-skip-verify |
为 true 时跳过对 Argo Server 证书的校验(HTTPS 连接将不安全),默认取 ARGO_INSECURE_SKIP_VERIFY |
--tls-server-name string |
用于校验服务器证书的名称,未提供时使用连接主机名 |
Kubernetes 集群 / kubeconfig
| 选项 | 说明 |
|---|---|
--server string |
Kubernetes API Server 的地址和端口 |
--kubeconfig string |
kubeconfig 文件路径,仅在集群外运行时需要 |
--cluster string |
要使用的 kubeconfig 集群名称 |
--context string |
要使用的 kubeconfig 上下文名称 |
--user string |
要使用的 kubeconfig 用户名称 |
-n, --namespace string |
本次 CLI 请求的命名空间作用域 |
认证与身份模拟
| 选项 | 说明 |
|---|---|
--token string |
访问 API Server 的 Bearer token |
--username string / --password string |
访问 API Server 的基础认证用户名 / 密码 |
--certificate-authority string |
证书颁发机构(CA)证书文件路径 |
--client-certificate string |
TLS 客户端证书文件路径 |
--client-key string |
TLS 客户端私钥文件路径 |
--as string |
要模拟(impersonate)的用户名 |
--as-group stringArray |
要模拟的组,可重复指定多个组 |
--as-uid string |
要模拟的 UID |
HTTP / 日志 / 杂项
| 选项 | 说明 |
|---|---|
-H, --header strings |
为所有请求附加额外请求头(可重复多次,也支持逗号分隔),仅在 --argo-http1 或 ARGO_HTTP1=true 时生效 |
--disable-compression |
为 true 时对所有服务器请求关闭响应压缩 |
--proxy-url string |
通过指定代理 URL 连接 |
--request-timeout string |
单个服务器请求的超时时间,非零值需带时间单位(如 1s、2m、3h),零表示不超时,默认 "0" |
--gloglevel int |
设置 glog 日志级别 |
--log-format string |
日志格式,text 或 json,默认 text |
--loglevel string |
日志级别,debug、info、warn、error,默认 info |
-v, --verbose |
开启详细日志,等价于 --loglevel debug |
--instanceid string |
以指定控制器的实例 ID 标签提交,默认取 ARGO_INSTANCEID 环境变量 |
实际使用时,最常见的组合是:
# 连接本地 Argo Server(2746 端口)并创建模板到指定命名空间
argo template create templates.yaml -s localhost:2746 -n ci --secure=false
# 或者直接通过 kubeconfig 让 CLI 直连 Kubernetes
argo template create templates.yaml --kubeconfig ~/.kube/config -n ci
创建流程的源码级原理:从 CLI 到 Kubernetes API
理解命令背后的调用链有助于排查问题。argo template create 的执行路径可概括为四个阶段(见 create.go):
- 建立客户端:
client.NewAPIClient(ctx)依据上述连接/认证选项创建 API 客户端,并实例化WorkflowTemplateServiceClient(gRPC 客户端)。 - 读取与解析清单:
generateWorkflowTemplates读取所有文件内容,按 JSON → 多文档 YAML 的顺序解析出<a href="https://link.gitcode.com/i/2d7dcd23b2d7e52befe4e797367e23c7" target="_blank">]WorkflowTemplate;若全部文件中未解析出任何 WorkflowTemplate,会直接报错No workflow template found in given files退出(见 [util.go)。 - 逐个创建:对每个模板,若其
metadata.namespace为空则自动填充为 CLI 当前命名空间(client.Namespace(ctx)),然后调用CreateWorkflowTemplateRPC。该 RPC 的 gRPC 定义与 HTTP 映射位于 workflow-template.proto:
message WorkflowTemplateCreateRequest {
string namespace = 1;
WorkflowTemplate template = 2;
k8s.io.apimachinery.pkg.apis.meta.v1.CreateOptions createOptions = 3;
}
rpc CreateWorkflowTemplate(WorkflowTemplateCreateRequest) returns (WorkflowTemplate) {
option (google.api.http) = {
post: "/api/v1/workflow-templates/{namespace}"
body: "*"
};
}
对应地,使用 HTTP/1 直连时等效的 REST 调用为 POST /api/v1/workflow-templates/{namespace}。
- 服务端处理与回显:Argo Server 侧(
CreateWorkflowTemplate,见 workflow_template_server.go)在真正写入前还会做四件事:- 校验请求体非空(请求体中缺少模板时返回
InvalidArgument); - 打上 instance ID 标签(
instanceIDService.Label); - 打上创建者标签(
creator.LabelCreator); - 调用
validate.WorkflowTemplate进行完整的语义校验(参数、模板引用、入口点等),校验通过后才调用 Kubernetes 客户端在目标命名空间创建WorkflowTemplate资源,最后把创建结果按-o指定的格式回显给用户。
- 校验请求体非空(请求体中缺少模板时返回
值得留意的是,CLI 侧的 --strict 只影响反序列化阶段的字段严格性;而服务端 validate.WorkflowTemplate 负责的是语义层校验,两者互补。服务端的创建行为在 workflow_template_server_test.go 中有对应的单测覆盖(含无参数值、带标签等场景)。
实战示例:创建模板并在工作流中复用
结合仓库示例,演示一次完整的“创建 → 复用”流程。首先用默认严格模式创建 templates.yaml 中定义的模板:
argo template create examples/workflow-template/templates.yaml -n default -o name
输出(示例):
workflow-template-print-message
workflow-template-random-fail-template
workflow-template-inner-steps
workflow-template-inner-dag
workflow-template-submittable
模板创建成功后,即可被普通工作流通过 templateRef 引用。仓库中的 hello-world.yaml 展示了标准用法:一个 Workflow 的步骤模板通过 templateRef.name + templateRef.template 指向刚创建的 workflow-template-print-message,并通过 arguments.parameters 注入参数:
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: workflow-template-hello-world-
spec:
entrypoint: hello-world-from-templateRef
templates:
- name: hello-world-from-templateRef
steps:
- - name: call-print-message
templateRef:
name: workflow-template-print-message
template: print-message
arguments:
parameters:
- name: message
value: "hello world"
# 引用模板提交工作流
argo submit examples/workflow-template/hello-world.yaml -n default
此外,直接可提交的模板(entrypoint + 全局 arguments 定义完整)也可以配合 argo submit --from workflowtemplate/xxx 使用。若需要更新已存在的模板,则使用同命令组的 argo template update(见 argo template 文档);对模板进行离线校验可先用 argo template lint,两者与 create 共享同一套清单解析逻辑。
常见错误与排障要点
Error: requires at least 1 arg(s), only received 0:未提供文件参数。create强制至少一个清单输入,见 create.go。No workflow template found in given files:文件内容合法但其中没有kind: WorkflowTemplate对象(例如误传了普通 Workflow 清单),此时解析结果为空并直接退出。Failed to parse workflow template: ...:清单既无法按 JSON 解析,也无法按 WorkflowTemplate 多文档 YAML 解析。若开启了--strict(默认),请优先检查是否存在未知字段或拼写错误;确认无误可尝试--strict=false定位是否为未知字段所致。failed to create workflow template: ...:网络或服务端拒绝。常见原因包括命名空间不存在、RBAC 权限不足(需要对workflowtemplates资源具备create权限)、以及服务端语义校验失败(如entrypoint指向不存在的模板)。- 命名空间问题:清单中未写
metadata.namespace时,模板会被创建到-n/--namespace指定的命名空间(默认取 kubeconfig 上下文命名空间),这是很多“模板去哪了”问题的答案。
总结
argo template create 以“一个命令、多文件/多文档/多来源输入、可开关的严格校验、四种回显格式”的设计,成为 Argo Workflows 中管理 WorkflowTemplate 生命周期的入口。理解其选项语义(-o、--strict)与“CLI 解析 → gRPC/REST → 服务端校验 → Kubernetes API 落库”的调用链(create.go、util.go、workflow_template_server.go),既能帮助你在脚本中正确使用它,也能在出错时快速定位问题。更多子命令(list / get / update / delete / lint)的详细用法可参阅 argo template 及其关联文档页。