Argo Workflows Data 数据模板完全指南:Java SDK 中的 IoArgoprojWorkflowV1alpha1Data 模型与数据转换实战
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 模板最常用的组合,尤其适合日志分析、批量文件处理、数据湖清单扫描等场景。
七、进一步阅读
- 完整功能文档:docs/data-sourcing-and-transformation.md
- 官方示例:examples/data-transformations.yaml
- 核心类型定义:pkg/apis/workflow/v1alpha1/data_types.go
- 底层执行逻辑:workflow/data/data.go 及其单元测试 workflow/data/data_test.go
- Java SDK 模型文档目录:sdks/java/client/docs