Argo Workflows Data 数据模板完全指南:Java SDK 中的 IoArgoprojWorkflowV1alpha1Data 模型与数据转换实战

原创2026-09-22 12:24:301,447 阅读
文章标签:工作流自动化云原生容器编排任务调度DevOps后端前端微服务机器学习

Argo Workflows Data 数据模板完全指南:Java SDK 中的 IoArgoprojWorkflowV1alpha1Data 模型与数据转换实战

导读

本文围绕 Argo Workflows 的 Data 数据模板(data template)展开,以 Java SDK 中的 IoArgoprojWorkflowV1alpha1Data 模型为切入点,系统讲解数据模板的结构、source(数据来源)与 transformation(数据转换)两大核心字段的语义与用法,并结合仓库源码与官方示例给出可在真实 Workflow 中直接复用的实战方案。读完本文,你将掌握如何在 Argo Workflows 中从 S3 等制品仓库批量列举文件、用 expr 表达式过滤加工数据,并通过 withParam 驱动后续步骤并行处理。

一、Data 数据模板是什么

Data 数据模板是 Argo Workflows 中一种特殊的模板类型,用于在 Workflow 内部完成数据的获取(source)与加工(transformation),最终产出一个可被其他步骤引用的结果列表。它常与 withParam 配合使用,实现"先枚举数据源、再按条目批量处理"的典型批处理模式。

其类型定义位于 pkg/apis/workflow/v1alpha1/data_types.go,核心结构如下:

// Data is a data template
type Data struct {
	// Source sources external data into a data template
	Source DataSource `json:"source" protobuf:"bytes,1,opt,name=source"`

	// Transformation applies a set of transformations
	Transformation Transformation `json:"transformation" protobuf:"bytes,2,rep,name=transformation"`
}

也就是说,一个 Data 模板只包含两个字段:

字段 JSON 键 类型 必填 说明
source source DataSource 是 数据来源,把外部数据引入数据模板
transformation transformation Transformation([]TransformationStep) 是 对数据源依次应用的一组转换步骤

对应到 Java SDK,IoArgoprojWorkflowV1alpha1Data 即该结构在 Java 客户端中的模型映射,其文档定义在 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1Data.md,暴露了 source(类型 IoArgoprojWorkflowV1alpha1DataSource)与 transformation(类型 List<IoArgoprojWorkflowV1alpha1TransformationStep>)两个属性。

二、source:数据来源(DataSource)

source 用于声明数据的出处。当前版本中 DataSource 只支持一种来源类型——artifactPaths,正如 pkg/apis/workflow/v1alpha1/data_types.go 所示:

// DataSource sources external data into a data template
type DataSource struct {
	// ArtifactPaths is a data transformation that collects a list of artifact paths
	ArtifactPaths *ArtifactPaths `json:"artifactPaths,omitempty" protobuf:"bytes,1,opt,name=artifactPaths"`
}

DataSource 还通过 GetArtifactIfNeeded() 方法把 ArtifactPaths 内的 Artifact 暴露给上层逻辑使用。Java SDK 侧对应文档为 IoArgoprojWorkflowV1alpha1DataSource.md,属性表同样只列出 artifactPaths 一个可选字段。

ArtifactPaths:从一个制品位置收集路径列表

ArtifactPaths 在 pkg/apis/workflow/v1alpha1/data_types.go 中被定义为对 Artifact 的内联扩展:

// ArtifactPaths expands a step from a collection of artifacts
type ArtifactPaths struct {
	Artifact `json:",inline" protobuf:"bytes,1,opt,name=artifact"`
}

它的语义是:以某个制品位置(可以是一个目录/前缀)为数据源,把其中包含的每一个制品路径收集成一个列表。由于内联了 Artifact,它继承了制品描述的全部能力,在 Java SDK 的 IoArgoprojWorkflowV1alpha1ArtifactPaths.md 中可以看到完整的属性集合:

  • 来源位置:s3、git、gcs、oss、azure、hdfs、http、artifactory、raw、plugin 等后端,选择其一作为数据出处;
  • 名称与路径:name(制品名称,在模板 inputs/outputs 内必须唯一)、path(容器内路径)、subPath(从指定来源的子路径获取)、from/fromExpression(引用前序步骤的制品或通过表达式求值);
  • 文件行为:mode(加载时设置的文件权限,0~0777)、recurseMode(对文件夹递归应用权限)、archive(归档策略)、archiveLogs(是否归档容器日志);
  • 生命周期:artifactGC(制品回收策略)、optional(制品缺失时是否可跳过)、deleted、globalName(导出为全局输出制品)。

因此,artifactPaths 既可以直接指向一个 S3 桶/前缀来枚举文件,也可以引用前序步骤的输出制品目录。

三、transformation:数据转换步骤

transformation 是一个有序的转换步骤列表,类型为 Transformation,本质上是 []TransformationStep:

type Transformation []TransformationStep

type TransformationStep struct {
	// Expression defines an expr expression to apply
	Expression string `json:"expression" protobuf:"bytes,1,opt,name=expression"`
}

每一个 TransformationStep(Java SDK 对应 IoArgoprojWorkflowV1alpha1TransformationStep.md,仅有 expression 一个 String 属性)包含一条 expr 表达式。表达式以 data 为输入变量,执行结果会作为下一个步骤的输入,从而形成流水线式的链式转换。

底层执行原理

转换的实际执行位于 workflow/data/data.go,其调用链清晰展示了"先取数、再变换"的处理流程:

func ProcessData(ctx context.Context, data *wfv1.Data, processor wfv1.DataSourceProcessor) (any, error) {
	sourcedData, err := processSource(ctx, data.Source, processor)
	if err != nil {
		return nil, fmt.Errorf("unable to process data source: %w", err)
	}
	transformedData, err := processTransformation(sourcedData, &data.Transformation)
	if err != nil {
		return nil, fmt.Errorf("unable to process data transformation: %w", err)
	}
	return transformedData, nil
}
  • processSource 通过 DataSourceProcessor 接口的 ProcessArtifactPaths(ctx, *ArtifactPaths) 方法完成数据获取;该接口定义在 pkg/apis/workflow/v1alpha1/data_types.go 的 DataSourceProcessor 中。若 source 中没有任何合法来源,会返回 "no valid source is used for data template" 错误。
  • processTransformation 依次遍历每个 TransformationStep,对非空表达式调用 processExpression:
    • 使用 github.com/expr-lang/expr 编译表达式,并把当前数据注入环境变量 data;
    • 执行后把结果继续传给下一个步骤;
    • 任一步骤出错会返回包含步骤序号的错误信息("error processing data step %d")。

这解释了为什么转换表达式必须引用名为 data 的变量——这是引擎约定的输入变量名。内置的过滤函数如 filter、map、# 占位符等均来自 expr 语言的函数库。

四、完整实战示例:列出 S3 日志文件并批量处理

仓库中的 examples/data-transformations.yaml 是官方提供的完整可运行示例(注释中指明其对应主文档为 docs/data-sourcing-and-transformation.md,并标注需要 Argo Workflows >= 3.1.0)。它演示了三个关键环节:用 Data 模板枚举 S3 桶中的对象 → 用 expr 过滤出符合条件的日志文件 → 用 withParam 对每个文件启动一个处理步骤。

第一步:定义 Data 模板取数与过滤

- name: list-log-files
  data:
    source:
      artifactPaths:
        name: test-bucket
        s3:
          bucket: my-bucket

    transformation:
      - expression: "filter(data, {# endsWith \"main.log\"})"
  • source.artifactPaths 指向 S3 桶 my-bucket,引擎会收集桶内对象路径作为初始 data 列表;
  • transformation 用一条 expr 表达式过滤,只保留以 main.log 结尾的对象({# ...} 中 # 表示当前遍历元素)。

第二步:用 withParam 消费结果

- - name: process-logs
    template: process-logs
    withParam: "{{steps.list-log-files.outputs.result}}"
    arguments:
      artifacts:
        - name: file
          s3:
            key: "{{item}}"
      parameters:
        - name: file-name
          value: "{{item}}"

Data 模板的输出结果会暴露在 {{steps.list-log-files.outputs.result}} 中。withParam 遍历该结果列表,为每一项启动一个 process-logs 实例,并通过 {{item}} 把当前路径同时传给制品 key 和参数 file-name。

第三步:处理步骤消费单个文件

- name: process-logs
  inputs:
    parameters:
      - name: file-name
    artifacts:
      - name: file
        path: /file
  container:
    image: argoproj/argosay:v2
    command: [sh, -c]
    args:
      - |
        echo {{inputs.parameters.file-name}}
        head /file

每个处理实例把 S3 对象下载到容器内 /file,打印文件名并查看文件头部内容。至此,"枚举 → 过滤 → 并行处理"的完整数据流水线闭环成型。

演练建议

可参照 docs/data-sourcing-and-transformation.md 主文档并结合 examples/data-transformations.yaml 进行演练:将示例中的 my-bucket 替换为真实可访问的 S3 桶(确保 Workflow 使用的 ServiceAccount 具备 s3:ListBucket 与 s3:GetObject 权限),即可直接 argo submit 提交验证。

五、Java SDK 中的编程使用方式

IoArgoprojWorkflowV1alpha1Data 在 Java SDK 中是可编程构建的模型对象。以 Maven 引入 io.argoproj.workflow:argo-client-java 后,可以这样组织一个 Data 模板:

// 1. 构造转换步骤:过滤出 main.log 结尾的对象
IoArgoprojWorkflowV1alpha1TransformationStep step =
    new IoArgoprojWorkflowV1alpha1TransformationStep()
        .expression("filter(data, {# endsWith \\\"main.log\\\"})");

// 2. 构造数据源:指向 S3 桶
IoArgoprojWorkflowV1alpha1S3Artifact s3 =
    new IoArgoprojWorkflowV1alpha1S3Artifact()
        .bucket("my-bucket");
IoArgoprojWorkflowV1alpha1ArtifactPaths artifactPaths =
    new IoArgoprojWorkflowV1alpha1ArtifactPaths()
        .name("test-bucket")
        .s3(s3);
IoArgoprojWorkflowV1alpha1DataSource source =
    new IoArgoprojWorkflowV1alpha1DataSource()
        .artifactPaths(artifactPaths);

// 3. 组装 Data 模板
IoArgoprojWorkflowV1alpha1Data data =
    new IoArgoprojWorkflowV1alpha1Data()
        .source(source)
        .transformation(Collections.singletonList(step));

构建完成后,将 data 挂到 IoArgoprojWorkflowV1alpha1Template 的 data 字段上即可作为普通模板提交。SDK 中各模型的字段说明与文档一一对应,可供查阅:IoArgoprojWorkflowV1alpha1DataSource(docs)、IoArgoprojWorkflowV1alpha1TransformationStep(docs)、IoArgoprojWorkflowV1alpha1ArtifactPaths(docs)。

六、设计要点与适用场景

综合源码与示例,可以总结 Data 模板的如下特征与适用边界:

  • 只做数据获取与转换,不直接执行容器:Data 模板本身没有 container/script 执行体,产出的是结构化结果;真正的业务处理仍需由普通模板通过 withParam 承接。
  • 转换是链式的:多个 transformation 步骤按声明顺序依次作用,前一步输出即后一步输入,适合"过滤 → 排序 → 截断"等多阶段加工。
  • 数据源目前仅 artifactPaths 一种:从 workflow/data/data.go 的 processSource 分支可见,未来版本可能扩展更多来源类型;当前场景下请将数据先落到制品后端(如 S3)再引用。
  • 典型的批处理工作流:枚举制品 → 表达式加工 → withParam 并行分发,是 Data 模板最常用的组合,尤其适合日志分析、批量文件处理、数据湖清单扫描等场景。

七、进一步阅读

登录后查看全文
argo-workflows