Argo Workflows CLI 实战:用 `argo template create` 命令创建 WorkflowTemplate 完整指南

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

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):

  1. 建立客户端:client.NewAPIClient(ctx) 依据上述连接/认证选项创建 API 客户端,并实例化 WorkflowTemplateServiceClient(gRPC 客户端)。
  2. 读取与解析清单:generateWorkflowTemplates 读取所有文件内容,按 JSON → 多文档 YAML 的顺序解析出 <a href="https://link.gitcode.com/i/2d7dcd23b2d7e52befe4e797367e23c7" target="_blank">]WorkflowTemplate;若全部文件中未解析出任何 WorkflowTemplate,会直接报错 No workflow template found in given files 退出(见 [util.go)。
  3. 逐个创建:对每个模板,若其 metadata.namespace 为空则自动填充为 CLI 当前命名空间(client.Namespace(ctx)),然后调用 CreateWorkflowTemplate RPC。该 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}。

  1. 服务端处理与回显: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 及其关联文档页。

登录后查看全文
argo-workflows