企业官网建设流程全解析

Argo CD v2.12 至 v2.13 升级指南：Flux 资源集成增强、Dex 破坏性变更与行为变化详解

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

本篇指南以 Argo CD 官方 v2.12 到 v2.13 升级说明 为核心，系统梳理本次升级中的全部变更点：包括为 Flux 全家桶新增的自定义 Resource Actions 与自定义健康检查、Dex 升级引入的 LDAP 连接器破坏性变更、CronJob 手动触发 Job 的命名格式变化、下载日志文件扩展名调整、kustomize 构建代理传递等。读完本文，你将清楚每一项变更的影响范围、底层实现原理以及升级前需要完成的适配动作（尤其是 RBAC 权限更新与脚本兼容性调整）。

升级前的通用准备

Argo CD 采用类 semver 版本策略：patch 版本不引入破坏性变更，而 minor 版本可能带来需要手动适配的变化。v2.12 → v2.13 属于 minor 升级，存在下文所述的破坏性行为变更，升级前建议先阅读升级总览中的相关说明。

升级命令（<version>替换为 v2.13.0）：

非 HA 部署：

kubectl apply -n argocd --server-side --force-conflicts -f <version>/manifests/install.yaml

HA 部署：

kubectl apply -n argocd --server-side --force-conflicts -f <version>/manifests/ha/install.yaml

[!NOTE]--server-side --force-conflicts参数是必须的：部分 Argo CD CRD 的体积超过客户端 apply 的上限。即使某个版本只改动镜像，官方仍建议应用整套 manifests，避免遗漏参数修改导致配置漂移。

内置 Helm 版本升级：3.15.2 → 3.15.4

v2.13 将随 Argo CD 一起打包的 Helm 版本从 3.15.2 升级到 3.15.4。这是一次补丁级别的版本提升，主要包含上游 Helm 的 bug 修复与安全更新，对使用 Helm 作为配置管理工具的 Application 影响极小。升级后建议对现有的 Helm 应用执行一次常规的argocd app sync验证渲染结果的一致性。

Argo CD 在 repo-server 侧通过helm.NewHelmApp等封装统一管理 Helm 调用，Helm 客户端初始化时会携带仓库代理配置（见 reposerver/repository/repository.go 中newHelmClient的构造逻辑），因此升级后代理、OCI 等既有行为保持不变。

Flux 资源自定义 Actions（新增）

v2.13 为 Flux 生态资源新增了自定义 Resource Actions 支持。现在可以在 Argo CD UI 中对以下 Flux 资源直接执行Suspend、Resume、Reconcile等操作：

使用前必须更新 RBAC 权限

[!IMPORTANT] 要想在 UI 中看到并执行这些操作，必须先为 Argo CD 实例更新权限（RBAC）。这些 Action 通过 PATCH 修改 Flux 资源（如设置spec.suspend字段），因此运行 Argo CD 的服务账号（如argocd-application-controller、argocd-server）需要对上述资源拥有patch权限。RBAC 的详细配置方式参考 RBAC 文档。

底层实现：Lua 脚本驱动的动作

这些 Action 并非硬编码在 Go 中，而是以 Lua 脚本形式存放在仓库的resource_customizations目录中。以 HelmRelease 的 actions 目录 为例，其结构包含discovery.lua、action_test.yaml、testdata以及suspend、resume、reconcile三个子目录，每个子目录各含一个action.lua。

discovery.lua（决定哪些 Action 在何种状态下可见/可用）：

local actions = {} actions["reconcile"] = {["disabled"] = true} actions["suspend"] = {["disabled"] = true} actions["resume"] = {["disabled"] = true} local suspend = false if obj.spec.suspend ~= nil then suspend = obj.spec.suspend end if suspend then actions["resume"]["disabled"] = false else actions["reconcile"]["disabled"] = false actions["suspend"]["disabled"] = false end return actions

可以看到：当资源处于 suspend 状态时只开放resume；未 suspend 时开放reconcile与suspend。obj是包含资源的全局变量。

suspend / resume 的 action.lua（修改源资源并返回）：

-- suspend obj.spec.suspend = true return obj -- resume if obj.spec.suspend ~= nil and obj.spec.suspend then obj.spec.suspend = false end return obj

reconcile 的 action.lua（通过 annotation 触发 Flux 重新协调）：

local os = require("os") if obj.metadata.annotations == nil then obj.metadata.annotations = {} end obj.metadata.annotations["reconcile.fluxcd.io/requestedAt"] = "By Argo CD at: " .. os.date("!%Y-%m-%dT%X") return obj

Reconcile正是利用 Flux 官方的reconcile.fluxcd.io/requestedAtannotation 机制，为资源打上时间戳标记，从而触发 Flux 控制器对该资源的即时协调——这是在不删除、不重建资源的前提下完成"强制重新协调"的标准做法。

[!NOTE] 上述脚本依赖os标准库。关于argocd-cm中自定义 Action 的 Lua 脚本默认禁用标准库的安全限制，以及如何通过resource.customizations.useOpenLibs.<group>_<kind>开启，参见 Resource Actions 文档。

若你希望保留内置 Action 并叠加自定义动作，可在argocd-cm中为对应资源设置mergeBuiltinActions: true（自 v2.13.0 起支持），自定义动作优先于内置动作。完整配置示例参见 Resource Actions 文档。

Flux 资源自定义健康检查（新增）

v2.13 同时为 Flux 资源新增了自定义健康检查。以下 Flux 资源现在具备健康评估能力：

• HelmRelease
• ImagePolicy
• ImageRepository
• ImageUpdateAutomation
• Kustomization
• Receiver
• Bucket
• GitRepository
• HelmChart
• HelmRepository
• OCIRepository

这些健康检查以health.lua+health_test.yaml+testdata的形式随 Argo CD 内置分发，目录位于 resource_customizations 下（如 helm.toolkit.fluxcd.io/HelmRelease、source.toolkit.fluxcd.io/GitRepository 等）。

健康检查实现剖析

以 HelmRelease 的 health.lua 为例，其判定逻辑如下：

1. 若spec.suspend == true，返回Suspended状态；
2. 遍历status.conditions：
   • Ready=True或Released/TestSuccess=True→ 计入成功数；
   • Ready=Unknown或Reconciling=True→ 计入进行中数；
3. 最终判定：进行中数 ≥ 2 →Progressing；成功数 ≥ 2 →Healthy；否则 →Degraded；无 status 信息时返回Progressing（"Status unknown"）。

以 GitRepository 的 health.lua 为例，额外处理了ArtifactOutdated与ArtifactInStorage两类条件，将ArtifactInStorage=True计入成功，从而反映"制品已就绪"这一源资源特有的健康语义。

可以看到，所有健康检查脚本均遵循统一的返回约定：hs.status取值为Healthy、Progressing、Degraded、Suspended之一，可选hs.message说明详情。Application 的整体健康状态取所有直接子资源健康状态中的最差值，优先级从优到劣为：Healthy、Suspended、Progressing、Missing、Degraded、Unknown。

[!TIP] 如果你在自己的集群中观察到 Flux 资源健康状态异常，可以对照testdata目录下的healthy.yaml、progressing.yaml、degraded.yaml样例资源，检查实际 status 是否符合预期；自定义健康检查的测试运行方式为go test -v ./util/lua/，详见 health.md。

Dex 升级至 v2.39.0：LDAP 连接器破坏性变更

v2.13 将内置 Dex 升级到 v2.39.0，其中包含针对LDAP connector的破坏性变更：

现在 LDAP connector 对用户名和密码的验证严格得多。Dex 使用EscapeFilter函数检查凭据中的特殊字符，并通过拒绝此类请求来防止注入攻击。

这意味着：如果你的 Argo CD 通过 Dex 的 LDAP connector 对接企业目录（如 OpenLDAP、AD），升级后包含特殊字符（如*、(、)、\、NUL 等 LDAP 过滤器保留字符）的用户名或密码将被拒绝登录。升级前应排查目录中是否存在此类账号，必要时先修正凭据再升级，避免大面积登录失败。

[!NOTE] 这是本次升级中影响面最广的破坏性变更，因为它直接作用于最终用户的认证环节。建议在测试环境先行验证 LDAP 登录后再升级生产实例。

手动触发 CronJob 生成的 Job 命名格式变更

v2.13 修改了通过 Argo CD 手动从 CronJob 触发的 Job 的命名规则：

• 变更前：后缀为-YYYYMMDDHHmm（4 位年份），例如mychron-202609120700
• 变更后：后缀为-YYMMDDHHmm（2 位年份），例如mychron-2609120700

该变更仅影响由 Argo CD 手动触发的 Job。由 Kubernetes 按调度（schedule）自动创建的 Job 命名不受 Argo CD 控制，格式保持不变。

适配建议：检查是否有脚本、CI 流水线或监控告警规则依赖旧的 4 位年份命名模式（如正则-\d{12}$），升级后需要同步调整为 2 位年份格式（-\d{10}$）。

下载日志文件的扩展名变更：.txt→.log

Argo CD UI 的 "Download Logs"（下载日志）功能生成的日志文件默认扩展名从.txt改为.log。官方解释是此举符合行业惯例，并提升与各类日志管理工具及 IDE 的兼容性（这些工具对.log文件提供更丰富的增强功能）。

影响：

• 依赖.txt扩展名的用户与系统需要调整工作流；
• 专门针对.txt日志文件编写的自动化脚本需要更新为处理.log文件。

收益：

• 在 IDE 与日志管理工具中获得更好的可读性与解析体验；
• 与标准日志文件约定保持一致。

行动项：升级前排查所有硬编码.txt日志路径的脚本、采集器（如 Filebeat/Fluentd 的 glob 匹配规则）与告警规则，统一改为.log。

kustomize 构建支持代理传递

v2.13 起，设置在仓库凭据（repository credentials）或仓库模板（repository templates）上的代理配置会被传递给kustomize build命令。

从源码看，repo-server 在构造 kustomize 应用时会显式传入代理参数，例如 reposerver/repository/repository.go 中kustomize.NewKustomizeApp(repoRoot, appPath, ..., kustomizeBinary, q.Repo.Proxy, q.Repo.NoProxy)的调用——q.Repo.Proxy与q.Repo.NoProxy即来自仓库的proxy/noProxy配置字段（git、helm、oci 客户端同样消费这两个字段，见该文件newGitClient、newHelmClient、newOCIClient的签名）。

意义：此前 kustomize 构建过程中若需要拉取远程资源（如远程 base），可能因无法穿透代理而失败；升级后，只要仓库已配置代理，kustomize 构建即可复用同一代理设置，无需额外旁路配置。对使用 kustomize 远程依赖 + 公司内网代理环境的用户尤其重要。

新增的内置健康检查清单

本次升级为以下资源类型新增了内置健康检查（对应目录均可从 resource_customizations 根目录定位）：

• controlplane.cluster.x-k8s.io/AWSManagedControlPlane
• policy.open-cluster-management.io/CertificatePolicy
• policy.open-cluster-management.io/ConfigurationPolicy
• policy.open-cluster-management.io/OperatorPolicy
• policy.open-cluster-management.io/Policy
• policy/PodDisruptionBudget
• cluster.x-k8s.io/MachinePool
• lifecycle.keptn.sh/KeptnWorkloadVersion
• numaplane.numaproj.io/ISBServiceRollout
• numaplane.numaproj.io/NumaflowControllerRollout
• numaplane.numaproj.io/PipelineRollout
• rds.aws.crossplane.io/DBCluster
• rds.aws.crossplane.io/DBInstance
• iam.aws.crossplane.io/Policy
• iam.aws.crossplane.io/RolePolicyAttachment
• iam.aws.crossplane.io/Role
• s3.aws.crossplane.io/Bucket
• metrics.keptn.sh/KeptnMetric
• metrics.keptn.sh/Analysis
• numaplane.numaproj.io/MonoVertexRollout
• helm.toolkit.fluxcd.io/HelmRelease
• image.toolkit.fluxcd.io/ImagePolicy
• image.toolkit.fluxcd.io/ImageRepository
• image.toolkit.fluxcd.io/ImageUpdateAutomation
• kustomize.toolkit.fluxcd.io/Kustomization
• notification.toolkit.fluxcd.io/Receiver
• source.toolkit.fluxcd.io/Bucket
• source.toolkit.fluxcd.io/GitRepository
• source.toolkit.fluxcd.io/HelmChart
• source.toolkit.fluxcd.io/HelmRepository
• source.toolkit.fluxcd.io/OCIRepository

这些健康检查让 Argo CD 能够准确评估 Cluster API、Open Cluster Management、Crossplane、Keptn、Numaproj 以及 Flux 等生态资源的实际状态，并正确反映到 Application 的整体健康度中。若你的集群使用上述任一资源类型，升级后即可在 UI 中看到更精确的健康状态标识。

升级行动清单（Checklist）

1. RBAC 更新：为使用 Flux Actions 的集群资源授予patch权限，否则 UI 中的Suspend/Resume/Reconcile不可用；
2. LDAP 验证：检查目录中用户名/密码是否含 LDAP 过滤器特殊字符，评估 Dex v2.39.0 严格校验带来的登录影响；
3. Job 命名脚本适配：搜索-\d{12}$之类的旧 CronJob 手动触发 Job 匹配规则，改为-\d{10}$；
4. 日志采集适配：将采集器与脚本中.txt日志 glob 规则更新为.log；
5. 健康检查验证：在测试环境观察新增健康检查（特别是 Flux 资源）的评估结果，对照testdata样例排查异常；
6. Helm 应用回归：升级后对 Helm 管理的应用执行一次 sync 回归验证。

完成上述适配后，即可按升级总览中的命令将 Argo CD 升级到 v2.13，并逐步验证新特性（Flux Actions、Flux 健康检查、kustomize 代理）的实际效果。

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd