Argo CD·Argo Workflows 读后感：对比循环、Pod 中的 Worker，以及单个 CronJob 的状态判定

状态：草稿（2026-10-17），部分为实测数据。 基准版本为 argoproj/argo-cd v3.5.1（提交 109ca7ca7113）、argoproj/argo-workflows v4.1.5（提交 6c80c7e56ae6）。由于小型集群运行着相同的版本，我们在 2026-10-17 通过 仅读取 进行了确认（Pod、Application 状态、配置键、CronJob 状态字段）。小型集群中没有 Argo Workflows，因此仅阅读了代码（未实测）。编写规则：以实测数据为基础，未能测量的数据标记为“未实测”，未能确认的标记为“未确认”。

目录

• 1. 一句话总结：“对比循环”与“用 Pod 工作的 Worker”
• 2. 架构图 ①：Argo CD 的对比循环
• 3. 代码地图
• 4. 沿着核心路径前行 — Argo CD
  • 4.1 刷新：什么时候再次查看
  • 4.2 渲染与应用：repo-server 与 sync
  • 4.3 状态判定：选择哪个脚本
  • 4.4 CronJob 案例：文档与 Lua 不一致的地方
• 5. 沿着核心路径前行 — Argo Workflows
• 6. 作者的贡献与后续延伸
• 7. 实测：小型集群中的 Argo CD
• 8. 从哪里开始阅读
• 9. 适合首次贡献的地方
• 10. 局限性
• 参考资料

1. 一句话总结：“对比循环”与“用 Pod 工作的 Worker”

虽然名字里都有 Argo，但这两个项目的性质有所不同。

• Argo CD 是一个 恒温器。它持续对比 git 中记录的目标温度（期望状态）和房间里的温度（集群的实际状态），如果不一致就会发出提醒（OutOfSync）或者进行调整（sync）。这个无限循环的对比过程就是代码的核心。
• Argo Workflows 则是 工厂作业指导书。它接收将各个步骤按顺序和依赖关系组合起来的 Workflow，为每个步骤启动一个 Pod，而步骤之间传递的文件（制品）则通过 S3 等存储进行交接。

2. 架构图 ①：Argo CD 的对比循环

图解说明：

• 从上到下是一次完整的“刷新”。控制器将 repo-server 渲染的 期望状态与集群缓存持有的 实际状态进行对比（②），针对每个资源判定状态（③）并写入 Application。
• 同步是单独运行的第二个队列（④·⑤）。将对比和应用拆分到不同的队列中，是为了防止耗时较长的 sync 阻塞大量应用的状态更新。
• 集群缓存通过 watch 将所有资源保留在内存中，而不需要每次都查询 API 服务器。虽然对比的代价变高了，但控制器的内存占用也变大了。
• 最下方的方框是本文 4.3 节的主题，即选择状态判定脚本的顺序。

3. 代码地图

在 v3.5 的 argo-cd 仓库中，过去独立的 gitops-engine gitops-engine/ 已经合并到了 文件夹中（位于go.mod 的 replace … => ./gitops-engine中）。对比、sync 和集群缓存的核心都在这里。

4. 路径追踪 — Argo CD

4.1 刷新：什么时候再次查看

控制器中有两个队列（位于controller/appcontroller.go:118 appRefreshQueue，第 121 行 appOperationQueue). appcontroller.go:955 Run 为这两个队列分别附加了 Worker Goroutine）。

1. 刷新 Worker 是 appcontroller.go:1775 processAppRefreshQueueItem 。 appcontroller.go:2105 needRefreshAppStatus 首先通过 argocd_application_controller.go:45询问“现在真的是重新对比的时候吗”。如果用户点击了刷新、管理的资源发生了变化，或者设定的周期（默认 120 秒，带有最大 60 秒的抖动，位于
2. ）已过，就会进行对比。 controller/state.go:633 CompareAppState 对比是由 state.go:206 GetRepoObjs 执行的。该函数通过 gRPC 从 repo-server 获取期望状态（位于 controller/cache/cache.go:729 GetManagedLiveObjs ），从缓存中取出实际状态（位于 pkg/diff/diff.go:76 Diff ），然后通过 gitops-engine 的
3. 对每个资源进行对比。state.go:1051 在同一个函数的末尾会进行状态判定（在 setApplicationHealth 中调用
4. ）。我们将在 4.3 节中详细探讨这一点。如果开启了自动 sync， appcontroller.go:2322 autoSync 会将 operation 写入 Application，然后第二个队列就会处理该应用。

4.2 渲染与应用：repo-server 与 sync

• repo-server 的入口是 reposerver/repository/repository.go:631 GenerateManifest 。它会先检查缓存（位于repository.go:1016 getManifestCacheEntry），如果没有找到，则将仓库切换到对应提交，然后由 repository.go:1714 GenerateManifests 使用 repository.go:1921 GetAppSourceType 在 helm、kustomize、plain 和插件中选择一个进行渲染。 将渲染分离为独立服务的理由出于安全和资源的考虑。由于 helm、kustomize 和插件需要执行他人仓库的内容，因此需要将其与拥有集群凭证的控制器隔离；同时，繁重的渲染工作只需通过水平扩展 repo-server 来应对。
• 应用是由 controller/sync.go:102 SyncAppState 调用 gitops-engine 的 pkg/sync/sync_context.go:478 Sync 来完成的。在此过程中， sync_context.go:954 getSyncTasks 将资源按阶段（PreSync、Sync、PostSync 钩子）和灰度序号进行排序，当前一个灰度健康之后才会进入下一个灰度。判断“是否健康”的过程再次回到了 4.3 节的状态判定。
• 实际状态缓存是由 gitops-engine/pkg/cache/cluster.go:1094 sync 在最初获取所有 API 资源的列表后，通过 cluster.go:792 watchEvents 接收后续变更的 watch 来维护的。

4.3 状态判定：选择哪个脚本

单个资源的状态由 gitops-engine 的 pkg/health/health.go:70 GetResourceHealth 决定。如果正在被删除，则为 Progressing；否则， 会首先询问是否有覆盖（override） 。只有在没有覆盖的情况下，才会使用 Go 编写的内置检查（位于health.go:104 GetHealthCheckFunc，包括 Deployment、Pod、Job 等）。

Argo CD 侧的“覆盖”即为 Lua。如果简化 util/lua/lua.go:169 GetHealthScript 的顺序，结果如下：

key := GetConfigMapKey(obj.GroupVersionKind())
if script, ok := vm.ResourceOverrides[key]; ok && script.HealthLua != "" {
    return script.HealthLua, script.UseOpenLibs, nil   // argocd-cm 에 사용자가 적은 것
}
// 와일드카드 항목 → 내장 Lua 파일 → 내장 와일드카드 순으로 찾는다
builtInScript, err := vm.getPredefinedLuaScripts(key, healthScriptFile)

来源：argoproj/argo-cd v3.5.1 util/lua/lua.go(GetHealthScript 摘要），Apache-2.0。

内置 Lua 是 resource_customizations/<그룹>/<종류>/health.lua 文件，通过 resource_customizations/embed.go 的 go:embed 整体打包进二进制文件中。同一文件夹中的 health_test.yaml 和 testdata/ 是该脚本的测试。 为新 CRD 的状态判定做出贡献的最简单途径就是在该文件夹中添加一个 Lua 文件和测试数据。无需懂 Go 代码，测试由 util/lua/health_test.go 查找并运行该文件夹下的 health_test.yaml 来完成。

这样判定出的资源状态由 controller/health.go:20 setApplicationHealth 汇总为整个应用的状态。最差的状态即为应用的状态，如果在资源上存在 argocd.argoproj.io/ignore-healthcheck: "true" 注解，则会从汇总中排除（第 41 行）。在 v3 中，资源级别的状态不再保存在 Application 对象中，而是保存在 redis 的资源树中 。这是因为 --persist-resource-health 的默认值是 false （位于argocd_application_controller.go:293）。这样选择是为了避免随着 Application 变大而导致 etcd 写入变重。

4.4 CronJob 案例：文档与 Lua 不一致的地方

CronJob 的内置 Lua 是位于 resource_customizations/batch/CronJob/health.lua 的一段 56 行的代码。决策分为五个分支：

v3.5.1 版文档（docs/operator-manual/health.md）在 CronJob 章节中写道：“如果最后一个 Job 失败则为 Degraded”、“如果最后一个 Job 正在运行则为 Progressing”，并将 Suspended 状态的例子举为“停止的 CronJob”。与代码对比后发现这三处都不对：失败后如果下一个 Job 正在运行会恢复为 Healthy，运行期间不是 Progressing 而是 Healthy，停止的 CronJob 不是 Suspended 而是 Healthy。

5. 核心路径追踪 — Argo Workflows

1. workflow/controller/controller.go:337 Run 启动了 informer 和 Worker，而 controller.go:922 processNextItem 取出一个 Workflow 并创建 operator。
2. workflow/controller/operator.go:212 operate 是单次 reconcile。首先通过 operator.go:1216 podReconciliation 将已启动 Pod 的状态反映到节点状态中，然后通过 operator.go:2235 executeTemplate 从入口模板开始向下遍历，决定下一步要做什么。根据模板类型的不同，会分叉到 steps.go:42 executeSteps, dag.go:278 executeDAG, operator.go:3435 executeContainer 。由于每次都从头开始遍历但会跳过已完成的节点，因此即使控制器重启，只要有 Workflow 的 status.nodes 就能继续执行。
3. 容器步骤由 workflowpod.go:341 createWorkflowPod 创建为 Pod。在用户容器 main 旁边附加了 init(workflowpod.go:1092 newInitContainers）和 wait ，并将 main 的命令用 argoexec emissary 包裹起来（位于cmd/argoexec/commands/emissary.go:46)。v4 中引入了无需 init 容器、 supervisor 单个容器同时处理 init 和 wait 工作的模式 (workflowpod.go:1127 newSupervisorContainer, initlessPod 配置)。
4. 在 Pod 内部， wait 会等待 main 结束，然后将输出文件上传至存储库（通过workflow/executor/executor.go:1355 Wait), executor.go:449 SaveArtifacts )。
5. 存储驱动由 workflow/artifacts/artifacts.go:29 NewDriver 根据制品中指定的类型进行选择。 S3 排在最前面（第 38 行），访问密钥即时从 Secret 中读取并填充。MinIO 作为 S3 驱动接入。
6. 如果在制品中未指定存储库， workflow/artifactrepositories/artifactrepositories.go:38 Resolve 会依次查找 工作流命名空间的默认 ConfigMap，然后是控制器配置中的默认存储库。

为什么要这样拆分？ 集群中只有一个控制器，但阶段（Step）可能有数千个。如果繁重的文件传输不通过控制器处理，而是交由阶段 Pod 内的 argoexec 完成， 则即使传输量增加，也只需扩展阶段 Pod。不过代价是每个 Pod 都会附带一个辅助容器，v4 的 supervisor 模式被认为是一种旨在降低该成本的尝试（设计意图未通过文档确认，未核实）。

6. 作者的贡献与后续动向

• argoproj/argo-cd Issue #30209 → #30243。 最初的 Issue (#30209) 指的是 4.4 节中的“正在运行则为 Progressing”这一句，经由其他贡献者的 #30212 修正该行后已关闭。 其余三个问题（失败后下一个 Job 运行则为 Healthy、从未成功过则为 Healthy、已停止的 CronJob 不是 Suspended）已作为新的 Issue #30243 提出。 其依据全部来自 4.4 节的表格、 health.lua 的第 3、15、27、35 行。
• argoproj/argo-workflows#17246（审查中）。这是一个 PR，旨在将目前使用无法下载的镜像及过大默认值的制品存储库 MinIO 安装章节， 替换为使用存储库中已有的 quick-start 的 MinIO 配置（manifests/quick-start/base/minio)。第 5 节的第 5 点（通过 S3 驱动接入 MinIO 的方式）即为本文档说明的对象。 曾出现过因文档检查工具（cspell）不识别镜像名称而需要在词典中手动添加词汇的情况。

7. 实测：小型集群中的 Argo CD

2026-10-17，仅使用了读取命令。不记录应用名称和存储库地址。

Application 的 status.resources 中有 44 个 CronJob，其 health 栏全部为空（因为上述的 appTree 原因）。因此，读取了 44 个 CronJob 的实际状态字段 (spec.suspend, status.lastScheduleTime, lastSuccessfulTime, active)，并 用 Python 实现了 4.4 节表格中的规则 进行分类。输入为实际测量值，判定则是基于 Lua 转换后的计算结果。

在 44 个 CronJob 中，有 27 个是已停止的 CronJob。这意味着按文档所述本应在 UI 中显示为 Suspended 的内容全部混入了 Healthy 当中， 通过“筛选 Suspended”一个也找不到。这种分类方式直观地展现了 Issue #30243 中第 3 点的实际数字。

8. 从哪里开始阅读

1. resource_customizations/batch/CronJob/ — 56 行 Lua 与测试数据。这是最轻量的入口。
2. util/lua/lua.go:169 GetHealthScript → gitops-engine/pkg/health/health.go:70.
3. controller/appcontroller.go:1775 processAppRefreshQueueItem — 完整的一次刷新过程。
4. controller/state.go:633 CompareAppState — 虽然很长，但汇集了比较所需的所有素材。
5. 对于 Workflows，掌握了 workflow/controller/operator.go:212 operate 和 workflowpod.go:341 createWorkflowPod 这两个地方就能建立整体概念。
6. 最后是 workflow/artifacts/artifacts.go:29 — 选择一个驱动（s3）并追踪到底。

9. 适合首次贡献的地方

• resource_customizations 添加 Lua 与测试。 许多 CRD 尚无状态判定。 health.lua + health_test.yaml + testdata/*.yaml 只需满足这三点， 且无需运行全部测试，只需通过 go test ./util/lua/ 即可验证（4.3）。
• 整理 CronJob 文档（#30243）。 使文档与 4.4 节的表格保持一致，同时介绍覆盖方法（resource.customizations.health.batch_CronJob）以及 ignore-healthcheck 注释。 如果维护者接受该 Issue，便可直接推进 PR。
• Lua 的陈旧语法。 8 处内置 Lua 使用了 table.getn （包含 CronJob 的第 27 行）。由于执行器支持，目前尚无问题，但 将其整理为 # 长度运算符的范围很小。 不过，必须同时提交行为一致的测试才能被采纳。
• Workflows 文档。 4.1.5 中无 init 的 supervisor 模式在代码中有很好的注释，但在用户文档中很难找到此配置（本次未下载文档目录，未核实）。
• 规则：Argo 项目有生成式 AI 政策（argoproj/argoproj community/genai.md），Argo Workflows 的 PR 模板中包含声明 AI 使用情况的 ### AI 章节。两个存储库都要求 DCO 签名（Signed-off-by）， 并且 Argo CD 带有 PR 标题格式检查（.github/pr-title-checker-config.json）以及“没有测试的 PR 很难被合并”的检查清单项。

10. 局限性

• 由于小型集群中没有部署 Argo Workflows，因此没有实测数据。supervisor 模式、制品插件和归档（persist/）仅通过浏览代码了解。
• 未涉及 Argo CD 的分片（Sharding）、ApplicationSet 生成器、通知、服务端 diff 以及 hydrator（commitserver）。
• CronJob 分类是基于 Lua 转换的计算结果。并未通过 Argo CD API 读取资源树的实际判定（因需要登录而未执行，未实测）。

蒂蒂有话说。 如果只在正在休息的选手身上写着“我很健康！”，那么当教练问“谁在休息？”时，一个人也点不出来呀！明明有 27 个人在休息呢！

参考

所有访问日期均为 2026-10-17。

• argoproj/argo-cd v3.5.1： controller/, gitops-engine/pkg/, reposerver/repository/repository.go, util/lua/lua.go, resource_customizations/batch/CronJob/health.lua, docs/operator-manual/health.md
• argoproj/argo-workflows v4.1.5： workflow/controller/, workflow/executor/executor.go, workflow/artifacts/artifacts.go, workflow/artifactrepositories/artifactrepositories.go
• 公开 Issue/PR：argoproj/argo-cd#30209·#30212·#30243·#24428·#24429，argoproj/argo-workflows#17246
• 引用的代码片段均来自上述存储库，且全部遵循 Apache License 2.0 协议。在文章中经过了简写处理。