Argo Workflows 中的 Alibaba Cloud OSS 制品仓库（OSSArtifactRepository）配置与实现指南

Argo Workflows 中的 Alibaba Cloud OSS 制品仓库OSSArtifactRepository配置与实现指南【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows本文基于 Argo Workflows 源码中 Java SDK 生成的 API 参考文档IoArgoprojWorkflowV1alpha1OSSArtifactRepository系统讲解 OSS 制品仓库在 Workflow Controller 中的配置模型、字段语义、凭据管理方式AK/SK Secret 与 SDK 默认凭据链以及底层驱动实现。读者阅读后将掌握如何在 Workflow Controller ConfigMap 或命名空间级artifact-repositoriesConfigMap 中声明 OSS 制品仓库、如何为输入/输出制品指定 OSS 位置、如何利用keyFormat自定义对象键布局、以及如何通过生命周期规则管理 OSS 桶内对象的成本与清理策略。一、什么是 OSSArtifactRepositoryOSSArtifactRepository是 Argo Workflows 中用于描述Alibaba Cloud阿里云对象存储服务OSS制品仓库的控制器级配置类型。在 Java SDK 中它对应io.argoproj.workflow.v1alpha1.models.IoArgoprojWorkflowV1alpha1OSSArtifactRepository类API 参考文档位于 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1OSSArtifactRepository.md。在源码层面该类型定义于 pkg/apis/workflow/v1alpha1/artifact_repository_types.go// OSSArtifactRepository defines the controller configuration for an OSS artifact repository type OSSArtifactRepository struct { OSSBucket json:,inline protobuf:bytes,1,opt,nameoSSBucket // KeyFormat defines the format of how to store keys and can reference workflow variables. KeyFormat string json:keyFormat,omitempty protobuf:bytes,2,opt,namekeyFormat }其核心设计是内嵌OSSBucket即本文档表中除keyFormat外的全部字段承载桶的访问信息KeyFormat决定对象键Key的生成格式。该结构体实现了ArtifactRepositoryType接口的IntoArtifactLocation(l *ArtifactLocation)方法将仓库配置转换为单个制品的位置描述func (r *OSSArtifactRepository) IntoArtifactLocation(l *ArtifactLocation) { k : r.KeyFormat if k { k DefaultArchivePattern } l.OSS OSSArtifact{OSSBucket: r.OSSBucket, Key: k} }其中DefaultArchivePattern为{{workflow.name}}/{{pod.name}}见 pkg/apis/workflow/v1alpha1/artifact_repository_types.go即未配置keyFormat时对象键默认按“工作流名/ Pod 名”两级目录布局。这一行为由单元测试 pkg/apis/workflow/v1alpha1/artifact_repository_types_test.go 明确验证仅设置OSS: OSSArtifactRepository{}时转换出的l.OSS.Key恒等于{{workflow.name}}/{{pod.name}}。背景知识OSSArtifactRepository是ArtifactRepository聚合类型的一个可选分支。ArtifactRepository还支持 S3、Artifactory、HDFS、GCS、Azure Blob、Plugin 等多种后端OSS 通过ArtifactRepository.OSS字段参与统一抽象见 pkg/apis/workflow/v1alpha1/artifact_repository_types.go。二、全部字段详解继承自 API 参考文档下表完整列出OSSArtifactRepository含内嵌OSSBucket的全部属性对应 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1OSSArtifactRepository.md 中的 Properties 表所有字段均为可选optional名称类型说明备注accessKeySecretio.kubernetes.client.openapi.models.V1SecretKeySelector桶访问密钥的 AccessKey ID 对应的 Kubernetes Secret 选择器可选bucketStringOSS 桶的名称可选createBucketIfNotPresentBoolean指示驱动在输出制品时若 OSS 桶不存在则尝试自动创建可选endpointString桶端点的主机名Endpoint可选keyFormatString定义对象键的存储格式可引用工作流变量可选lifecycleRuleIoArgoprojWorkflowV1alpha1OSSLifecycleRule桶生命周期管理规则可选secretKeySecretio.kubernetes.client.openapi.models.V1SecretKeySelector桶访问密钥的 AccessKey Secret 对应的 Kubernetes Secret 选择器可选securityTokenString用户的临时安全令牌STS Token可选useSDKCredsBoolean指示驱动基于 SDK 默认凭据链自动获取凭据可选字段与源码定义的对应关系上述字段直接映射 pkg/apis/workflow/v1alpha1/workflow_types.go 中OSSBucket的 JSON 标签endpoint桶 Endpoint 主机名例如oss-cn-hangzhou.aliyuncs.combucketOSS 桶名accessKeySecret/secretKeySecret均为k8s.io/api/core/v1.SecretKeySelector指向存储凭据的 Kubernetes Secret 及其中的键名createBucketIfNotPresent仅对输出制品生效保存时若桶不存在则先建桶securityToken临时 STS Token适用于使用临时凭证的场景阿里云官方文档RAM 角色 STS 临时访问凭证lifecycleRule类型为*OSSLifecycleRule用于管理桶生命周期useSDKCreds启用 SDK 默认凭据链如 ECS RAM Role、RRSA OIDC 等与显式 AK/SK 二选一。此外OSSArtifact单制品位置pkg/apis/workflow/v1alpha1/workflow_types.go在OSSBucket之上额外增加必填的key字段用于在工作流模板中直接指定某个制品在桶内的路径其HasLocation()校验要求Bucket、Endpoint、Key三者同时非空pkg/apis/workflow/v1alpha1/workflow_types.go可据此推断直接使用 OSS 制品时endpoint、bucket、key是三个必填核心要素。生命周期规则OSSLifecycleRulelifecycleRule字段的类型定义与参考文档见 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1OSSLifecycleRule.md源码位于 pkg/apis/workflow/v1alpha1/workflow_types.go名称类型说明markInfrequentAccessAfterDaysInteger多少天后将桶内对象转换为低频访问IAInfrequent Access存储类型markDeletionAfterDaysInteger多少天后删除桶内对象驱动在保存制品时调用setBucketLifecycleRuleworkflow/artifacts/oss/oss.go应用该规则要点如下当两个字段都为0未设置时直接跳过生命周期配置若markInfrequentAccessAfterDays markDeletionAfterDays返回错误“markInfrequentAccessAfterDays cannot be large than markDeletionAfterDays”即转为 IA 的天数必须早于小于等于删除的天数生成的 OSS Lifecycle 规则包含Expiration按天数删除当前版本对象、Transition按天数转换至StorageIA存储类型以及AbortMultipartUpload按删除天数清理未完成的分片上传规则的Prefix为制品 KeyID为 Key 的 SHA-256 摘要。三、两种典型使用场景场景一控制器级默认 OSS 制品仓库Workflow Controller ConfigMapOSS 制品仓库最常见的用途是作为Workflow Controller 的默认制品仓库让所有工作流的输出制品/日志自动归档到 OSS。配置入口是workflow-controller-configmapConfigMap 中的artifactRepository字段对应配置解析代码 config/config.go类型为wfv1.ArtifactRepository。官方配置指南 docs/configure-artifact-repository.md 给出了完整的 OSS 默认制品仓库配置示例apiVersion: v1 kind: ConfigMap metadata: name: artifact-repositories annotations: 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 和 secretKeySecret 是 Secret 选择器 # 引用名为 $mybucket-credentials 的 K8s Secret # 该 Secret 需包含键 accessKey 与 secretKeyBase64 编码的桶凭据。 accessKeySecret: name: $mybucket-credentials key: accessKey secretKeySecret: name: $mybucket-credentials key: secretKey对应的凭据 Secret 创建命令kubectl create secret generic $mybucket-credentials -n demo \ --from-literal accessKeyYOUR-OSS-ACCESS-ID \ --from-literal secretKeyYOUR-OSS-SECRET-KEY配置说明将 ConfigMap 命名为artifact-repositories并加注workflows.argoproj.io/default-artifact-repository注解后该命名空间下的工作流会自动使用该 OSS 仓库endpoint建议使用内网 Endpoint如oss-cn-zhangjiakou-internal.aliyuncs.com以降低流量费用前提是集群与 OSS 处于同一地域若开启createBucketIfNotPresent: true驱动会在输出制品时自动创建不存在的桶但需要为 OSS 账号额外授予创建桶的权限见 docs/configure-artifact-repository.md 相关说明。场景二工作流模板内直接声明 OSS 制品除了控制器级默认仓库还可以在工作流模板中为单个制品直接声明 OSS 位置。仓库示例 examples/input-artifact-oss.yaml 演示了从 OSS 加载硬编码输入制品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/ # 这是桶内的路径对象键 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]要点模板中的oss:节点即为OSSArtifact类型key必填示例中key: test/mydirectory/以/结尾表示 OSS 中的一个“目录”前缀驱动会将其视为目录下载详见下文驱动实现若该键对应单个对象文件则直接按文件下载凭据同样通过 Secret 选择器注入示例对应的 Secret 创建命令为kubectl create secret generic my-oss-credentials --from-literalaccessKeyYOUR-OSS-ACCESS-ID --from-literalsecretKeyYOUR-OSS-SECRET-KEY。四、凭据获取与useSDKCreds两种认证方式OSSArtifactRepository提供两种凭据获取方式均由 OSS 驱动 workflow/artifacts/oss/oss.go 中的newOSSClient实现workflow/artifacts/oss/oss.go1. 显式 AK/SKAccessKeySecret SecretKeySecret当未设置useSDKCreds时驱动使用oss.New(endpoint, accessKey, secretKey, options...)构建客户端其中AccessKey、SecretKey来自accessKeySecret/secretKeySecret指向的 Kubernetes SecretSecurityToken非空时通过oss.SecurityToken(token)选项附加到客户端支持 STS 临时凭证。2. SDK 默认凭据链useSDKCreds: true当useSDKCreds: true时驱动调用credentials.NewCredential(nil)走阿里云 SDK 的默认凭据提供链例如 ECS 实例 RAM 角色、RRSARAM Roles for Service Accounts基于 OIDC等不再需要显式 AK/SK。官方配置指南 docs/configure-artifact-repository.md 中给出了使用 OSS RRSA 的完整步骤在集群中安装ack-pod-identity-webhook自动注入 OIDC Token 与环境变量源码注释 workflow/artifacts/oss/oss.go 亦有说明为目标工作流命名空间添加标签pod-identity.alibabacloud.com/injection: on在运行工作流的 ServiceAccount 上添加注解pod-identity.alibabacloud.com/role-name: $your_ram_role_name在制品仓库配置中设置useSDKCreds: true并移除 AK/SK Secret 引用apiVersion: v1 kind: ConfigMap metadata: name: artifact-repositories annotations: 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 useSDKCreds: true源码提示驱动会读取环境变量https_proxy并作为 OSS 客户端代理选项workflow/artifacts/oss/oss.go这是因为 OSS 驱动无法直接通过环境变量配置代理需在代码中显式传入。五、驱动底层实现OSS 制品如何存取OSSArtifactRepository描述的是“仓库配置”而真正执行上传/下载的是workflow/artifacts/oss包中的ArtifactDriverworkflow/artifacts/oss/oss.go它实现了通用的common.ArtifactDriver接口字段与仓库配置一一对应type ArtifactDriver struct { Endpoint string AccessKey string SecretKey string SecurityToken string UseSDKCreds bool }驱动支持的核心操作包括Load下载输入制品workflow/artifacts/oss/oss.go优先按对象文件下载若返回NoSuchKey错误则调用IsOssDirectory判断该 Key 是否为 OSS“目录”即以该 Key 为前缀存在对象是则递归下载整个目录到本地Save上传输出制品workflow/artifacts/oss/oss.go先判断本地路径是文件还是目录若配置了createBucketIfNotPresent且桶不存在则自动建桶若配置了lifecycleRule则先应用生命周期规则目录递归上传含空目录的显式创建文件按大小选择上传方式SaveStream / OpenStream流式读写workflow/artifacts/oss/oss.go、workflow/artifacts/oss/oss.go流式保存经由临时文件中转流式读取对目录场景返回“尚未实现”错误源码注释表明未来计划以 .tgz 流形式支持Delete / ListObjects删除与列举workflow/artifacts/oss/oss.go删除指定对象列举时使用ListObjectsV2分页拉取全部对象用于制品清理如 Artifact GC。值得注意的工程细节大文件分片上传putFile依据文件大小选择上传策略——不超过 5 GiBmaxObjectSize 5 * 1024 * 1024 * 1024走简单上传超过则走分片上传multipartUploadworkflow/artifacts/oss/oss.go指数退避重试所有操作均包裹在waitutil.Backoff中默认策略为“初始 2 秒、倍增系数 2、最多 5 步、抖动 0.1”workflow/artifacts/oss/oss.go并依据 OSS 错误码表如RequestTimeout、ServiceUnavailable、Throttling、InternalError等判定是否属于瞬时错误以决定是否重试workflow/artifacts/oss/oss.go、workflow/artifacts/oss/oss.go。六、Java SDK 中的使用方式在 Java SDK 中OSSArtifactRepository以模型类IoArgoprojWorkflowV1alpha1OSSArtifactRepository提供其字段全部通过 Getter/Setter 暴露与本文第二节字段表一一对应。典型 Java 构造逻辑如下字段名与 API 文档一致IoArgoprojWorkflowV1alpha1OSSArtifactRepository ossRepo new IoArgoprojWorkflowV1alpha1OSSArtifactRepository() .endpoint(oss-cn-hangzhou.aliyuncs.com) .bucket(my-bucket) .accessKeySecret(new V1SecretKeySelector().name(my-oss-credentials).key(accessKey)) .secretKeySecret(new V1SecretKeySelector().name(my-oss-credentials).key(secretKey)) .keyFormat({{workflow.name}}/{{pod.name}}/artifact-{{workflow.creationTimestamp}}) .createBucketIfNotPresent(true) .useSDKCreds(false);将该对象赋给工作流对象的artifactRepository字段后即可在客户端如WorkflowServiceApi提交工作流时作为默认制品仓库配置使用。SDK 文档目录位于 sdks/java/client/docs其中 IoArgoprojWorkflowV1alpha1OSSArtifactRepository.md 与 IoArgoprojWorkflowV1alpha1OSSLifecycleRule.md 为该类型的权威字段参考。七、keyFormat对象键布局实战keyFormat是该类型最灵活的字段之一它定义了对象键的存储格式并可引用工作流变量。结合DefaultArchivePattern {{workflow.name}}/{{pod.name}}及驱动实现可以推断未设置时对象键为{{workflow.name}}/{{pod.name}}两级目录每个 Pod 的输出制品都落在“工作流名/Pod 名”的独立目录下互不干扰天然支持 Artifact GC 按工作流维度批量清理自定义时可采用任意工作流变量组合例如{{workflow.name}}/{{workflow.creationTimestamp}}—— 按创建时间分目录{{workflow.name}}/{{pod.name}}/{{inputs.parameters.build-id}}—— 混入输入参数也可直接写死固定前缀如ci-artifacts/{{workflow.name}}/{{pod.name}}。变量替换由 Argo Workflows 的变量体系统一处理参考 docs/variables.md因此keyFormat中可以安全引用workflow、pod及参数等上下文变量从而实现高度定制化的对象存储布局便于后续按前缀检索、归档与生命周期治理。八、参考与延伸阅读字段参考本主题对应的 API 文档 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1OSSArtifactRepository.md生命周期规则类型 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1OSSLifecycleRule.md类型定义 pkg/apis/workflow/v1alpha1/artifact_repository_types.go、 pkg/apis/workflow/v1alpha1/workflow_types.go驱动实现 workflow/artifacts/oss/oss.go行为测试 pkg/apis/workflow/v1alpha1/artifact_repository_types_test.go官方配置指南OSS 章节 docs/configure-artifact-repository.md控制器配置入口 docs/workflow-controller-configmap.md、 config/config.go完整可运行示例 examples/input-artifact-oss.yaml【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考