Argo Workflows 工作流级 Artifact GC 配置详解:WorkflowLevelArtifactGC 字段、策略与源码实现
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
从代码结构看,该类型由两部分组成:
- 内嵌的
ArtifactGC结构体(json:",inline"):承载strategy、podMetadata、serviceAccountName三个字段,这些字段同样可以出现在单个 Artifact 级别(Artifact.ArtifactGC),实现"Workflow 级默认 + Artifact 级覆盖"的二级配置模型; - 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
运行流程分析:
- Workflow 级
spec.artifactGC.strategy: OnWorkflowDeletion作为默认策略; on-completion制品在 Artifact 级把策略覆盖为OnWorkflowCompletion,因此 Workflow 完成时即被回收;on-deletion制品未覆盖,继承默认的OnWorkflowDeletion,当整个 Workflow 被删除时才回收;- 提交命令为
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 会:
- 通过
findArtifactsToGC找出该策略下需要删除的制品(按节点聚合); - 按"ServiceAccount + Pod 元数据 + PodSpecPatch"组合把制品分组,保证同一 Pod 使用同一套权限;
- 为每个分组创建
WorkflowArtifactGCTask自定义资源(记录制品清单与 ArchiveLocation); - 创建以 argoexec 镜像为主容器、参数为
artifact delete的 GC Pod(createArtifactGCPod); - 从制品位置解析出所需的 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 未被关闭 |
排查时可重点观察三类对象:
- Workflow 状态:
status.artifactGCStatus中的strategiesProcessed与已回收的 GC Pod 记录; - GC Pod:标签
workflows.argoproj.io/component: artifact-gc,其日志会给出制品删除失败的根因(凭证、网络、制品仓库权限等); - 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,以在存储成本与数据可追溯性之间取得平衡。