Argo Workflows OSSArtifact 详解：基于 Alibaba Cloud OSS 的制品（Artifact）定义与配置指南

云原生容器编排工作流自动化任务调度后端【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址https://gitcode.com/gh_mirrors/ar/argo-workflows点击查看免费下载OSSArtifact 是 Argo Workflows 中用于描述 Alibaba Cloud OSS对象存储服务制品位置的核心 API 类型它在工作流的输入制品input artifact与输出制品output artifact中承担着制品寻址 访问凭证 存储策略三合一的作用。本文将结合 Java SDK 类型文档 与仓库源码逐一剖析OSSArtifact的每个字段、底层驱动实现原理并给出可直接运行的 YAML 示例与默认制品仓库artifact repository配置方案帮助你在 Kubernetes 工作流中安全、高效地读写 OSS 上的数据。一、OSSArtifact 是什么OSSArtifact表示一个阿里巴巴云 OSS 制品的位置the location of an Alibaba Cloud OSS artifact它是 Argo Workflows 支持的多类制品后端之一。在类型定义上OSSArtifact通过 Go 结构体内嵌json:,inline的方式复用了OSSBucket结构体并额外增加一个Key字段// pkg/apis/workflow/v1alpha1/workflow_types.go:3313-3319 // OSSArtifact is the location of an Alibaba Cloud OSS artifact type OSSArtifact struct { OSSBucket json:,inline protobuf:bytes,1,opt,nameoSSBucket // Key is the path in the bucket where the artifact resides Key string json:key protobuf:bytes,2,opt,namekey }对应到 Java SDK 中即 IoArgoprojWorkflowV1alpha1OSSArtifact 类两者在 JSON 序列化层面完全一致key字段为必填其余字段可选。这种内嵌 组合的设计意味着所有连接 OSS 所需的桶信息endpoint、bucket、凭证、生命周期规则等都被收拢在OSSBucket中而Key单独表达对象在桶中的路径。OSSBucket定义如下workflow_types.go// OSSBucket contains the access information required for interfacing with an Alibaba Cloud OSS bucket type OSSBucket struct { Endpoint string json:endpoint,omitempty protobuf:bytes,1,opt,nameendpoint Bucket string json:bucket,omitempty protobuf:bytes,2,opt,namebucket AccessKeySecret *apiv1.SecretKeySelector json:accessKeySecret,omitempty protobuf:bytes,3,opt,nameaccessKeySecret SecretKeySecret *apiv1.SecretKeySelector json:secretKeySecret,omitempty protobuf:bytes,4,opt,namesecretKeySecret CreateBucketIfNotPresent bool json:createBucketIfNotPresent,omitempty protobuf:varint,5,opt,namecreateBucketIfNotPresent SecurityToken string json:securityToken,omitempty protobuf:bytes,6,opt,namesecurityToken LifecycleRule *OSSLifecycleRule json:lifecycleRule,omitempty protobuf:bytes,7,opt,namelifecycleRule UseSDKCreds bool json:useSDKCreds,omitempty protobuf:varint,8,opt,nameuseSDKCreds }另外仓库中还提供了两个针对OSSArtifact的工具方法workflow_types.goGetKey()/SetKey()读取与写入制品键值HasLocation()判断制品位置是否完整——要求Bucket、Endpoint、Key三者均非空常用于校验工作流定义中 OSS 制品是否已给出有效位置。二、字段详解从 Java SDK 属性表到源码语义原 Java SDK 文档以属性表形式列出了OSSArtifact的全部字段下面逐字段给出语义、可选性、JSON 字段名与源码对应关系。2.1 accessKeySecret可选类型io.kubernetes.client.openapi.models.V1SecretKeySelectorJSON 字段accessKeySecret语义一个 Kubernetes Secret 选择器指向存储 OSS AccessKey ID 的 Secret 及其中具体键key。在驱动初始化阶段控制器会通过资源接口读取该 Secret 的内容。见 workflow/artifacts/artifacts.goif art.OSS ! nil { ... if !art.OSS.UseSDKCreds art.OSS.AccessKeySecret ! nil art.OSS.AccessKeySecret.Name ! { accessKeyBytes, err : ri.GetSecret(ctx, art.OSS.AccessKeySecret.Name, art.OSS.AccessKeySecret.Key) ... secretKeyBytes, err : ri.GetSecret(ctx, art.OSS.SecretKeySecret.Name, art.OSS.SecretKeySecret.Key) ... } driver : oss.ArtifactDriver{ Endpoint: art.OSS.Endpoint, AccessKey: string(accessKeyBytes), SecretKey: string(secretKeyBytes), SecurityToken: art.OSS.SecurityToken, UseSDKCreds: art.OSS.UseSDKCreds, } }从源码可见只有当useSDKCreds为false且accessKeySecret.name非空时才会真正去读取 Secret反之若启用了 SDK 默认凭证链则 AK/SK 选择器可以被省略。2.2 secretKeySecret可选类型io.kubernetes.client.openapi.models.V1SecretKeySelectorJSON 字段secretKeySecret语义与accessKeySecret配套指向存放 OSS SecretKey 的 Secret 与键。两者通常指向同一个 Secret 的不同键例如 示例 workflow 中的写法accessKeySecret: name: my-oss-credentials key: accessKey secretKeySecret: name: my-oss-credentials key: secretKey对应创建 Secret 的命令examples/input-artifact-oss.yamlkubectl create secret generic my-oss-credentials --from-literalaccessKeyYOUR-OSS-ACCESS-ID --from-literalsecretKeyYOUR-OSS-SECRET-KEY2.3 bucket可选类型StringJSON 字段bucket语义OSS 桶的名称。在驱动层Save/Load等操作都会基于bucket名称调用osscli.Bucket(bucketName)获取桶对象见 oss.go。2.4 endpoint可选类型StringJSON 字段endpoint语义桶所在接入点的主机名。示例中使用的内网端点如http://oss-cn-hangzhou-zmf.aliyuncs.comexamples/input-artifact-oss.yaml。在newOSSClient中endpoint 作为oss.New(ossDriver.Endpoint, ...)的第一个参数传入oss.go并支持通过https_proxy环境变量走代理源码注释明确OSS 驱动的代理不能通过环境变量之外的方式配置。2.5 key必填类型StringJSON 字段key语义制品在桶中的路径对象键。它也是OSSArtifact唯一必填字段json:key无 omitempty驱动层通过bucket.GetObject(key)下载、bucket.PutObject(key, ...)上传。2.6 createBucketIfNotPresent可选默认 false类型BooleanJSON 字段createBucketIfNotPresent语义当保存输出制品时若目标桶不存在是否让驱动尝试自动创建该 OSS 桶。其实现位于 oss.goif outputArtifact.OSS.CreateBucketIfNotPresent { exists, existsErr : osscli.IsBucketExist(bucketName) ... if !exists { err osscli.CreateBucket(bucketName) ... } }需要注意的是自动建桶需要 OSS 账号额外拥有创建桶的权限对应 RAM 策略中的oss:CreateBucket等否则会在Save阶段报错。官方文档也特别提醒了这一点docs/configure-artifact-repository.md。2.7 lifecycleRule可选类型IoArgoprojWorkflowV1alpha1OSSLifecycleRuleJSON 字段lifecycleRule语义指定桶的生命周期管理策略用于输出制品保存后自动转换存储类型或删除对象。OSSLifecycleRule类型定义workflow_types.gotype OSSLifecycleRule struct { // MarkInfrequentAccessAfterDays is the number of days before we convert the objects in the bucket to Infrequent Access (IA) storage type MarkInfrequentAccessAfterDays int32 json:markInfrequentAccessAfterDays,omitempty protobuf:varint,1,opt,namemarkInfrequentAccessAfterDays // MarkDeletionAfterDays is the number of days before we delete objects in the bucket MarkDeletionAfterDays int32 json:markDeletionAfterDays,omitempty protobuf:varint,2,opt,namemarkDeletionAfterDays }两个子字段含义字段类型说明markInfrequentAccessAfterDaysInteger (int32)多少天后将桶内对象转为低频访问IA存储类型markDeletionAfterDaysInteger (int32)多少天后删除桶内对象驱动在Save阶段会调用setBucketLifecycleRule将规则写入 OSSoss.go其内部校验逻辑是markInfrequentAccessAfterDays不能大于markDeletionAfterDays否则返回错误markInfrequentAccessAfterDays cannot be large than markDeletionAfterDaysoss.go。因此配置时务必保证 IA 转换天数 删除天数。2.8 securityToken可选类型StringJSON 字段securityToken语义用户的临时安全令牌STS Token适用于使用 STS 临时凭证访问 OSS 的场景。在newOSSClient中若SecurityToken非空会追加oss.SecurityToken(token)客户端选项oss.go。该字段与 AccessKey/SecretKey 组合使用形成AK/SK 临时令牌的标准 STS 鉴权方式。2.9 useSDKCreds可选默认 false类型BooleanJSON 字段useSDKCreds语义是否让驱动基于 SDK 默认凭证链default provider chain自动获取凭证而不是显式提供 AK/SK。当设置为true时驱动不再读取accessKeySecret/secretKeySecret而是走凭证提供器逻辑oss.goif ossDriver.UseSDKCreds { logger.Info(ctx, Using default sdk provider chains for OSS driver) // need install ack-pod-identity-webhook in your cluster when using oidc provider for OSS driver cred, err : credentials.NewCredential(nil) ... provider : ossCredentialsProvider{cred: cred, logger: logger} return oss.New(ossDriver.Endpoint, , , oss.SetCredentialsProvider(provider)) }源码注释明确指出如果希望使用 OIDC 提供方即阿里云 ACK 的 RRSA 能力集群中需要安装ack-pod-identity-webhook。这是阿里云环境下的推荐凭证方式详见下文第四节。三、完整可运行的 Workflow 示例将以上字段组合到真实的 Workflow 定义中即官方示例 examples/input-artifact-oss.yaml 的完整内容apiVersion: argoproj.io/v1alpha1 kind: Workflow metadata: generateName: input-artifact-oss- spec: entrypoint: input-artifact-oss-example templates: - name: input-artifact-oss-example inputs: artifacts: - name: my-art path: /my-artifact oss: endpoint: http://oss-cn-hangzhou-zmf.aliyuncs.com bucket: test-bucket-name key: test/mydirectory/ # this is path in the bucket # accessKeySecret and secretKeySecret are secret selectors. # It references the k8s secret named my-oss-credentials. accessKeySecret: name: my-oss-credentials key: accessKey secretKeySecret: name: my-oss-credentials key: secretKey container: image: debian:latest command: [sh, -c] args: [ls -l /my-artifact]要点拆解制品被挂载到容器内/my-artifact路径path字段key: test/mydirectory/以目录结尾表示下载整个目录前缀下的对象凭证来自名为my-oss-credentials的 Secret其中需包含accessKey与secretKey两个键该示例打上了workflows.argoproj.io/no-test: environment标签说明它依赖真实的外部 OSS 环境不会在 e2e 测试中被自动执行。输出制品output artifact同样使用oss:块定义并可叠加createBucketIfNotPresent、lifecycleRule等写入侧能力outputs: artifacts: - name: my-output path: /result.txt oss: endpoint: http://oss-cn-hangzhou-zmf.aliyuncs.com bucket: test-bucket-name key: test/result.txt createBucketIfNotPresent: true lifecycleRule: markInfrequentAccessAfterDays: 30 markDeletionAfterDays: 90 accessKeySecret: name: my-oss-credentials key: accessKey secretKeySecret: name: my-oss-credentials key: secretKey四、作为默认制品仓库Artifact Repository的配置除了在每个 Workflow 中显式写oss:块OSSArtifact的字段还用于定义命名空间级的默认制品仓库。控制器侧的OSSArtifactRepository结构体内嵌OSSBucket并额外支持keyFormat键格式可引用工作流变量定义见 artifact_repository_types.gotype OSSArtifactRepository struct { OSSBucket json:,inline protobuf:bytes,1,opt,nameoSSBucket KeyFormat string json:keyFormat,omitempty protobuf:bytes,2,opt,namekeyFormat } func (r *OSSArtifactRepository) IntoArtifactLocation(l *ArtifactLocation) { k : r.KeyFormat if k { k DefaultArchivePattern } l.OSS OSSArtifact{OSSBucket: r.OSSBucket, Key: k} }可见当keyFormat为空时控制器会回退到DefaultArchivePattern作为键模板。仓库配置通过名为artifact-repositories的 ConfigMap 提供docs/configure-artifact-repository.mdapiVersion: v1 kind: ConfigMap metadata: name: artifact-repositories annotations: # v3.0 and after - if you want to use a specific key, put that key into this annotation. workflows.argoproj.io/default-artifact-repository: default-oss-artifact-repository data: default-oss-artifact-repository: | oss: endpoint: http://oss-cn-zhangjiakou-internal.aliyuncs.com bucket: $mybucket # accessKeySecret and secretKeySecret are secret selectors. accessKeySecret: name: $mybucket-credentials key: accessKey secretKeySecret: name: $mybucket-credentials key: secretKey官方文档同时给出了一整套从零准备 OSS 存储的流程docs/configure-artifact-repository.md核心步骤包括安装并配置阿里云 CLI创建仅含oss:PutObject/oss:GetObject最小权限的 RAM 策略并通过aliyun oss mb oss://$mybucket --region $myregion创建桶创建 RAM 用户并附加该策略生成 AccessKey将 AK/SK 存入 Kubernetes Secret创建上述artifact-repositoriesConfigMap 并打上默认仓库注解。同样值得关注的是 RAM 策略的最小权限写法configure-artifact-repository.md{ Version: 1, Statement: [ { Effect: Allow, Action: [ oss:PutObject, oss:GetObject ], Resource: acs:oss:*:*:$mybucket/* } ] }如果启用了createBucketIfNotPresent则还需为账号补充创建桶的权限。五、源码级原理OSS 制品驱动的工作链路所有对 OSS 的读写最终都由 workflow/artifacts/oss/oss.go 中的ArtifactDriver完成。该驱动实现了common.ArtifactDriver接口对外暴露五个核心方法方法职责关键实现位置Load将 OSS 对象下载到本地路径输入制品oss.goOpenStream打开对象的流式读取器oss.goSave将本地文件上传到 OSS输出制品oss.goSaveStream从io.Reader流式写入 OSSoss.goDelete删除 OSS 中的对象oss.go几个值得注意的实现细节客户端初始化newOSSClient支持 SecurityToken、https_proxy代理、以及useSDKCreds三种凭证/网络模式oss.go目录下载当key指向的对象不存在NoSuchKey错误时Load会尝试将其当作 OSS 目录 前缀处理通过ListObjects递归下载前缀下的全部对象oss.go这就是示例中key: test/mydirectory/能够下载整个目录的原因重试机制驱动内置了指数退避重试defaultRetry 2s 起步2 倍因子最多 5 步并对一组长尾瞬时错误码如RequestTimeout、ServiceUnavailable、Throttling、InternalError等进行重试判定oss.go流式保存SaveStream借助common.SaveStreamViaTempFile先落临时文件再上传避免超大对象直接驻留内存桶日志每次操作前会调用setBucketLogging尝试配置访问日志oss.go便于排查制品读写问题。此外OSSArtifact还通过 executor_swagger.md 暴露在 API 文档中可作为artifactLocation.oss的取值与 S3、GCS、HTTP、Raw 等其他制品后端并列。六、与 RRSAuseSDKCreds的集成对于安全要求较高的生产集群官方文档建议使用阿里云 RRSARAM Roles for Service Accounts替代明文 AK/SK其配置要点docs/configure-artifact-repository.md在 ACK 集群中安装ack-pod-identity-webhook自动注入 OIDC Token 与环境变量为目标命名空间打上标签pod-identity.alibabacloud.com/injection: on在工作流使用的 ServiceAccount 上添加注解pod-identity.alibabacloud.com/role-name: $your_ram_role_name在制品仓库 ConfigMap 中设置useSDKCreds: true并移除 AK/SK 选择器data: default-oss-artifact-repository: | oss: endpoint: http://oss-cn-zhangjiakou-internal.aliyuncs.com bucket: $mybucket useSDKCreds: true开启useSDKCreds后驱动通过github.com/alibabacloud-go/credentials的默认凭证链自动解析注入的 OIDC 凭证oss.go 中的ossCredentialsProvider封装了从 Tea 凭证到 OSS SDK 凭证的适配Pod 内无需再挂载任何 AK/SK。七、小结与最佳实践OSSArtifact虽是一个只有 9 个字段的小类型却覆盖了 OSS 制品从寻址、鉴权到存储治理的全部要素。综合仓库源码与官方文档推荐的最佳实践如下凭证安全优先使用useSDKCreds RRSA 模式若必须使用 AK/SK务必通过accessKeySecret/secretKeySecret引用 Kubernetes Secret并配合最小权限 RAM 策略仅oss:GetObject/oss:PutObject位置校验bucket、endpoint、key三者缺一不可HasLocation()会严格校验编写模板时不要遗漏目录制品key以/结尾即按目录前缀下载注意该能力依赖ListObjects需要相应 RAM 权限生命周期lifecycleRule中markInfrequentAccessAfterDays必须小于等于markDeletionAfterDays否则保存输出制品时会直接报错自动建桶createBucketIfNotPresent能省去手工建桶步骤但需为账号补充建桶权限且该开关仅在Save输出制品路径生效。相关源码与文档入口类型定义pkg/apis/workflow/v1alpha1/workflow_types.go制品仓库类型pkg/apis/workflow/v1alpha1/artifact_repository_types.go驱动实现workflow/artifacts/oss/oss.go驱动装配workflow/artifacts/artifacts.go可运行示例examples/input-artifact-oss.yaml仓库配置指南docs/configure-artifact-repository.md赞分享云原生容器编排工作流自动化任务调度后端【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址https://gitcode.com/gh_mirrors/ar/argo-workflows点击查看免费下载相关推荐Argo Workflows Artifact Driver/Plugin 开发指南基于 gRPC 扩展自定义制品存储Argo Workflows Artifact Driver/Plugin 开发指南基于 gRPC 扩展自定义制品存储 导读 Argo Workflows 内云原生容器编排工作流自动化任务调度后端Argo Workflows Artifact Plugin 插件机制全指南用 gRPC 构建自定义 Artifact DriverArgo Workflows Artifact Plugin 插件机制全指南用 gRPC 构建自定义 Artifact Driver 本文围绕 Argo Wo云原生容器编排工作流自动化任务调度后端Argo Workflows BasicAuth 详解基于 Secret 选择器的 HTTP/Git 制品基本认证机制Argo Workflows BasicAuth 详解基于 Secret 选择器的 HTTP/Git 制品基本认证机制 导读 BasicAuth 是 Argo云原生容器编排工作流自动化任务调度后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考