Argo Workflows 工作流级 Artifact GC 配置详解:WorkflowLevelArtifactGC 字段、策略与源码实现

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

Argo Workflows 工作流级 Artifact GC 配置详解:WorkflowLevelArtifactGC 字段、策略与源码实现

Argo Workflows 的 Workflow 级 Artifact 垃圾回收(Artifact Garbage Collection,简称 Artifact GC)用于在 Workflow 完成后自动删除其产生的制品(Artifact),避免存储空间持续被占用的同时,也让"删除制品"这一操作与 Workflow 生命周期解耦。本文以 Java SDK 文档 IoArgoprojWorkflowV1alpha1WorkflowLevelArtifactGC.md 为核心骨架,结合仓库中的类型定义、控制器实现与完整示例,逐字段讲解 Workflow 级 Artifact GC 的配置方法、底层运行机制与最佳实践。读完本文,你将能够熟练编写 spec.artifactGC 配置块,理解其内部策略解析、Finalizer 与 GC Pod 的协作流程,并能结合实例排查常见的配置问题。

一、什么是 WorkflowLevelArtifactGC

WorkflowLevelArtifactGC 描述的是"如何从已完成的 Workflow 中删除制品"的规则,它在 Workflow 级别(spec.artifactGC)使用。正如 pkg/apis/workflow/v1alpha1/workflow_types.go 中的类型定义所注释的:

WorkflowLevelArtifactGC describes how to delete artifacts from completed Workflows - this spec is used on the Workflow level

从代码结构看,该类型由两部分组成:

  1. 内嵌的 ArtifactGC 结构体(json:",inline"):承载 strategy、podMetadata、serviceAccountName 三个字段,这些字段同样可以出现在单个 Artifact 级别(Artifact.ArtifactGC),实现"Workflow 级默认 + Artifact 级覆盖"的二级配置模型;
  2. Workflow 级专有字段:forceFinalizerRemoval 与 podSpecPatch,它们只允许在 Workflow 级配置,用于控制最终器(Finalizer)行为与 GC Pod 的规格修补。

Java SDK 中对应的模型类为 IoArgoprojWorkflowV1alpha1WorkflowLevelArtifactGC,其字段与 Go 类型一一对应。该结构体还出现在 Workflow 类型的第 43 个 protobuf 字段位置(见 pkg/apis/workflow/v1alpha1/workflow_types.go 中 ArtifactGC *WorkflowLevelArtifactGC 的定义),并通过 generated.proto 暴露给 gRPC/OpenAPI 生态。

为什么需要 Artifact GC

默认情况下,Workflow 输出制品会一直保存在 S3、GCS、OSS、Artifactory 等制品仓库中,即使 Workflow 早已完成也不会被清理。Artifact GC 解决了三个现实问题:

  • 存储成本:频繁运行的 CI/CD、数据处理流水线会累积大量历史制品,产生持续的存储费用;
  • 合规与数据治理:某些制品包含敏感或过期数据,需要按 Workflow 生命周期自动销毁;
  • 资源释放自动化:把"删除制品"委托给控制器驱动的 GC Pod,无需人工介入,也无需用户自己写清理脚本。

二、字段全解:五个配置项逐一拆解

依据 SDK 文档的 Properties 表格,WorkflowLevelArtifactGC 共包含五个字段(其中三个来自内嵌的 ArtifactGC 结构体)。下表先给出全貌,随后逐个展开:

字段名 类型 可选性 归属 作用
strategy String 可选 内嵌 ArtifactGC 制品回收策略
podMetadata IoArgoprojWorkflowV1alpha1Metadata 可选 内嵌 ArtifactGC 为执行删除的 Pod 附加 Labels/Annotations
serviceAccountName String 可选 内嵌 ArtifactGC 为执行删除的 Pod 指定 ServiceAccount
podSpecPatch String 可选 Workflow 级专有 对 artgc Pod spec 施加 strategic merge patch
forceFinalizerRemoval Boolean 可选 Workflow 级专有 Artifact GC 失败时是否强制移除 Finalizer

1. strategy:何时删除制品

strategy 是 Artifact GC 的核心字段,用于声明制品的删除时机。仓库源码 pkg/apis/workflow/v1alpha1/workflow_types.go 定义了四个枚举值:

const (
	ArtifactGCOnWorkflowCompletion ArtifactGCStrategy = "OnWorkflowCompletion"
	ArtifactGCOnWorkflowDeletion   ArtifactGCStrategy = "OnWorkflowDeletion"
	ArtifactGCNever                ArtifactGCStrategy = "Never"
	ArtifactGCStrategyUndefined    ArtifactGCStrategy = ""
)

各取值的语义如下:

  • OnWorkflowCompletion:Workflow 一完成(无论成功、失败或错误)即触发删除。适合生命周期明确的临时产物;
  • OnWorkflowDeletion:当整个 Workflow 对象被删除(kubectl delete workflow 等)时才删除制品。适合需要保留一段时间、供事后审计或回溯的产物;
  • Never:永不自动删除,等效于完全关闭该制品的 Artifact GC;
  • 空字符串(未设置):视为"未定义",在 GetArtifactGCStrategy 中会被解析为 Never——即默认不回收。

字段还带有 CRD 校验约束(见 workflow_types.go 的 kubebuilder 注释):

+kubebuilder:validation:Enum="";OnWorkflowCompletion;OnWorkflowDeletion;Never

策略的继承与覆盖规则

Artifact GC 的策略可以在 Workflow 级设置默认值,再在单个 Artifact 上覆盖。Workflow.GetArtifactGCStrategy 的解析逻辑如下:

func (w *Workflow) GetArtifactGCStrategy(a *Artifact) ArtifactGCStrategy {
	artifactStrategy := a.GetArtifactGC().GetStrategy()
	wfStrategy := w.Spec.GetArtifactGC().GetStrategy()
	strategy := wfStrategy
	if artifactStrategy != ArtifactGCStrategyUndefined {
		strategy = artifactStrategy
	}
	if strategy == ArtifactGCStrategyUndefined {
		return ArtifactGCNever
	}
	return strategy
}

即:Artifact 级策略优先;若 Artifact 级未设置,则回落到 Workflow 级策略;若两者都未设置,最终等效为 Never。这一规则被 workflow_types_test.go 的 TestWorkflowGetArtifactGCStrategy 覆盖了多种组合场景。

2. podMetadata:GC Pod 的标签与注解

podMetadata 是 IoArgoprojWorkflowV1alpha1Metadata 类型,包含 labels 和 annotations 两个 map。控制器创建执行删除动作的 Pod 时,会把这些 Labels/Annotations 合并进 Pod(见 artifact_gc.go 中 maps.Copy(pod.Labels, info.podMetadata.Labels) 与 maps.Copy(pod.Annotations, info.podMetadata.Annotations))。典型用途:

  • 为 GC Pod 打上与制品删除相关的审计标签(如数据分类、过期时间);
  • 附加监控、成本归属或网络策略所需的注解;
  • 结合 ServiceAccount 与网络策略,让 GC Pod 走专用网络通道。

3. serviceAccountName:指定 GC Pod 的 ServiceAccount

默认情况下,控制器使用 Workflow 自身的 ServiceAccount 派生 GC Pod。当制品仓库的访问凭证与 Workflow 运行凭证不一致,或需要对删除操作做更细粒度的 RBAC 隔离时,可通过该字段显式指定:

  • 为 GC Pod 挂载独立的存储凭证 Secret(作为卷挂载,见下文 createSecretVolumesAndMountsFromArtifactLocations 逻辑);
  • 避免给主 Workflow 的 ServiceAccount 授予不必要的制品仓库删除权限;
  • 满足安全审计"删除权限与运行权限分离"的要求。

在控制器实现中,serviceAccountName 会被纳入 GC Pod 命名哈希(见 artGCPodName),即不同的 ServiceAccount/元数据组合会生成不同的 GC Pod,同一 Pod 内复用以相同权限即可删除的制品。

4. podSpecPatch:对 artgc Pod spec 的战略性合并补丁

podSpecPatch 是一个 Workflow 级专有字段,它携带一段 strategic merge patch,在 GC Pod 创建时应用到 Pod 的 spec 上(见 artifact_gc.go):

if info.podSpecPatch != "" {
	patchedPodSpec, patchErr := util.ApplyPodSpecPatch(pod.Spec, info.podSpecPatch)
	...
	pod.Spec = *patchedPodSpec
}

典型使用场景包括:为 GC Pod 追加资源限额、自定义 nodeSelector / tolerations、注入额外的环境变量或卷、调整安全上下文等。注意 PodSpecPatch 中引用 Secret 的字段(如 serviceAccountName、podMetadata)与 podSpecPatch 同属"可被用户用于提权"的敏感字段,因此在 workflow.util 的 merge.go 中,当 Workflow 通过 WorkflowTemplate 引用被合并时,这些字段会被纳入**违规校验(override violations)**并做清理(sanitize),仅保留 strategy 等良性字段允许用户覆盖。

5. forceFinalizerRemoval:GC 失败时强制移除 Finalizer

Artifact GC 依赖 Kubernetes Finalizer 机制保证"Workflow 删除前先完成制品清理"。但如果删除制品持续失败,Finalizer 会一直卡住 Workflow 的删除流程。forceFinalizerRemoval 设置为 true 后,控制器在 Artifact GC 反复失败时仍会移除 Finalizer,避免 Workflow 被永久阻塞。

控制器中的判定逻辑(artifact_gc.go)值得仔细理解:

if forceFinalizerRemoval {
	removeFinalizer = len(woc.artifactGCStrategiesReady()) == 0 &&
		woc.wf.Status.ArtifactGCStatus.AllArtifactGCPodsRecouped() &&
		!woc.artifactGCAwaitingDeletion()
} else {
	removeFinalizer = woc.allArtifactsDeleted()
}

关键点:

  • 开启后,控制器不再要求"所有制品确实已删除"(allArtifactsDeleted),而是只要**所有已到期的策略都已被启动、所有 GC Pod 都已回收(recouped)**且没有待处理的 OnWorkflowDeletion 制品,即可移除 Finalizer;
  • artifactGCAwaitingDeletion 检查是否存在等待 Workflow 删除时才回收的制品——若存在,Finalizer 必须保留,否则删除时机的 GC 永远不会触发;
  • 未开启时,必须等到 allArtifactsDeleted 为真才移除 Finalizer,即所有非 Never 制品都被标记为已删除(Artifact.Deleted 为 true)。

权衡提示:开启 forceFinalizerRemoval 意味着放弃"制品必须删干净"的强保证,换取 Workflow 删除流程不被失败卡死。应仅在可接受"制品可能残留"的场景下使用(例如临时/可再生制品)。

三、配置实战:一个完整的 Workflow 示例

仓库自带的官方示例 examples/artifact-gc-workflow.yaml 完整演示了 Workflow 级策略与 Artifact 级覆盖的配合:

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: artifact-gc-
spec:
  entrypoint: main
  artifactGC:
    strategy: OnWorkflowDeletion # the overall strategy, which can be overridden
  templates:
    - name: main
      container:
        image: argoproj/argosay:v2
        command:
          - sh
          - -c
        args:
          - |
            echo "hello world" > /tmp/on-completion.txt
            echo "hello world" > /tmp/on-deletion.txt
      outputs:
        artifacts:
          - name: on-completion
            path: /tmp/on-completion.txt
            s3:
              key: on-completion.txt
            artifactGC:
              strategy: OnWorkflowCompletion # overriding the default strategy for this artifact
          - name: on-deletion
            path: /tmp/on-deletion.txt
            s3:
              key: on-deletion.txt

运行流程分析:

  1. Workflow 级 spec.artifactGC.strategy: OnWorkflowDeletion 作为默认策略;
  2. on-completion 制品在 Artifact 级把策略覆盖为 OnWorkflowCompletion,因此 Workflow 完成时即被回收;
  3. on-deletion 制品未覆盖,继承默认的 OnWorkflowDeletion,当整个 Workflow 被删除时才回收;
  4. 提交命令为 argo submit --watch artifact-gc-workflow.yaml;删除 Workflow 后,可查看对应的 artgc Pod(命名格式为 <workflow>-artgc-wfdel-<hash>)执行制品删除。

结合 workflow_types_test.go 可见,Workflow 级别的 ArtifactGC 在测试中同样被构造为 &WorkflowLevelArtifactGC{...} 形式,与示例 YAML 的字段布局一致。

结合 podMetadata 与 serviceAccountName 的完整写法

spec:
  artifactGC:
    strategy: OnWorkflowCompletion
    serviceAccountName: artifact-gc-sa
    podMetadata:
      labels:
        app.kubernetes.io/managed-by: argo-artifact-gc
        data-classification: temporary
      annotations:
        example.com/gc-reason: workflow-completed
    podSpecPatch: |
      {"nodeSelector":{"pool":"gc-pool"}}
    forceFinalizerRemoval: true

注意:podSpecPatch 与 forceFinalizerRemoval 仅在 Workflow 级生效,单个 Artifact 的 artifactGC 块中不提供这两个字段。

四、底层机制:控制器如何执行 Artifact GC

1. 特性开关与 Finalizer 的添加

Artifact GC 有一个全局紧急开关:控制器环境变量 ARGO_ARTIFACT_GC_ENABLED(默认 true,见 artifact_gc.go)。当 Workflow 配置了 Artifact GC 时,控制器通过 addArtifactGCFinalizer(artifact_gc.go)为 Workflow 追加名为 argoproj.io/artifact-gc 的 Finalizer,并维护 status.artifactGCStatus 中的 notSpecified 标记以跳过无需 GC 的 Workflow。

2. 策略就绪判定与 GC Pod 的创建

artifactGCStrategiesReady(artifact_gc.go)决定哪些策略当前可执行:

  • Workflow 标记为已完成(labels["workflows.argoproj.io/completed"] == "true")或正在删除时,OnWorkflowCompletion 就绪;
  • Workflow 进入删除流程(DeletionTimestamp != nil)时,OnWorkflowDeletion 就绪。

随后 processArtifactGCStrategy 会:

  1. 通过 findArtifactsToGC 找出该策略下需要删除的制品(按节点聚合);
  2. 按"ServiceAccount + Pod 元数据 + PodSpecPatch"组合把制品分组,保证同一 Pod 使用同一套权限;
  3. 为每个分组创建 WorkflowArtifactGCTask 自定义资源(记录制品清单与 ArchiveLocation);
  4. 创建以 argoexec 镜像为主容器、参数为 artifact delete 的 GC Pod(createArtifactGCPod);
  5. 从制品位置解析出所需的 Secret 卷与挂载(createSecretVolumesAndMountsFromArtifactLocations),并在存在 Artifact Plugin 时注入对应的 sidecar 驱动容器。

GC Pod 的命名由策略与权限信息哈希生成:<workflow>-artgc-wfcomp-<hash>(完成时)或 <workflow>-artgc-wfdel-<hash>(删除时),并带有 workflows.argoproj.io/component: artifact-gc 标签(artifact_gc.go)。Pod 被设计为最小权限:RestartPolicy: Never、默认 CPU 100m/内存 64Mi 上限,并采用 MinimalPodSC / MinimalCtrSC 安全上下文。

3. 完成回收与 Finalizer 移除

processArtifactGCCompletion(artifact_gc.go)轮询 GC Pod 状态:Pod 进入 Succeeded/Failed 后即被"回收"(recoup),控制器在 status.artifactGCStatus 中记录已处理的 Pod 与策略。只有当所有到期策略的制品都处理完毕(或 forceFinalizerRemoval 条件满足)时,才会从 Workflow 上移除 Finalizer,从而放行 Workflow 的最终删除。

若策略启动失败(如制品位置配置错误导致无法创建 Pod),控制器会记录 ArtifactGCError 状态条件并产生事件,按 1 分钟间隔重试(artifactGCRetryDelay,见 artifact_gc.go),超过重试窗口(artifactGCRetryWindow)后放弃并可通过 forceFinalizerRemoval 释放 Workflow。

4. 测试验证

仓库为 Artifact GC 提供了较完整的测试保障:

  • workflow_types_test.go:验证 GetArtifactGCStrategy 在 Workflow 级/Artifact 级策略组合下的解析结果;
  • artifact_gc_test.go:覆盖 GC Pod 创建、策略处理与 Finalizer 移除等控制器行为;
  • merge_test.go:验证 WorkflowTemplate 合并场景下 Artifact GC 字段的违规校验与清理逻辑。

五、常见配置误区与排查建议

误区 现象 正确做法
只在 Artifact 级配置 artifactGC,Workflow 级留空 未配置 Artifact 级策略的制品永不回收(默认 Never) 在 Workflow 级设置默认 strategy,再按需覆盖
认为 OnWorkflowCompletion 会在 Pod 完成后立即触发 制品在 Workflow 整体完成后才回收 明确该策略以 Workflow 生命周期为准
依赖 podSpecPatch 传入任意 Secret 合并 WorkflowTemplate 时字段被 sanitize 拒绝 确认 podSpecPatch/serviceAccountName/podMetadata 属敏感字段,按 merge.go 的违规校验规则处理
删除 Workflow 时卡在 Terminating 制品删除失败且未开启强制移除 检查 GC Pod 日志与 ArtifactGCError 条件;必要时设置 forceFinalizerRemoval: true
忘记检查全局开关 配置完全正确却不执行 GC 确认控制器环境变量 ARGO_ARTIFACT_GC_ENABLED 未被关闭

排查时可重点观察三类对象:

  1. Workflow 状态:status.artifactGCStatus 中的 strategiesProcessed 与已回收的 GC Pod 记录;
  2. GC Pod:标签 workflows.argoproj.io/component: artifact-gc,其日志会给出制品删除失败的根因(凭证、网络、制品仓库权限等);
  3. Workflow 条件:ArtifactGCError 条件携带失败策略与消息前缀,用于区分"启动失败"与"删除失败"。

六、小结

WorkflowLevelArtifactGC 是 Argo Workflows 制品生命周期管理的关键配置:strategy 决定删除时机,podMetadata/serviceAccountName 控制 GC Pod 的权限与可观测性,podSpecPatch 提供对 GC Pod 规格的精细定制,forceFinalizerRemoval 则在失败场景下保障 Workflow 的最终可删除性。其底层由控制器 Finalizer、WorkflowArtifactGCTask 与 argoexec artifact delete Pod 协同实现,相关实现集中在 workflow/controller/artifact_gc.go,类型定义在 pkg/apis/workflow/v1alpha1/workflow_types.go,官方示例见 examples/artifact-gc-workflow.yaml。建议在生产环境中按"Workflow 级默认策略 + Artifact 级定向覆盖"的方式组织配置,并为关键制品关闭 Never 默认值、为长保留制品选用 OnWorkflowDeletion,以在存储成本与数据可追溯性之间取得平衡。

登录后查看全文
argo-workflows