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.yamlHA 部署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.4v2.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等操作自定义资源支持的操作HelmReleaseSuspend、Resume、ReconcileImageRepositorySuspend、Resume、ReconcileImageUpdateAutomationSuspend、Resume、ReconcileKustomizationSuspend、Resume、ReconcileAlertSuspend、ResumeProviderSuspend、ResumeReceiverSuspend、Resume、ReconcileBucketSuspend、Resume、ReconcileGitRepositorySuspend、Resume、ReconcileHelmChartSuspend、Resume、ReconcileHelmRepositorySuspend、Resume、ReconcileOCIRepositorySuspend、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 objreconcile 的 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 objReconcile正是利用 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 资源现在具备健康评估能力HelmReleaseImagePolicyImageRepositoryImageUpdateAutomationKustomizationReceiverBucketGitRepositoryHelmChartHelmRepositoryOCIRepository这些健康检查以health.luahealth_test.yamltestdata的形式随 Argo CD 内置分发目录位于 resource_customizations 下如 helm.toolkit.fluxcd.io/HelmRelease、source.toolkit.fluxcd.io/GitRepository 等。健康检查实现剖析以 HelmRelease 的 health.lua 为例其判定逻辑如下若spec.suspend true返回Suspended状态遍历status.conditionsReadyTrue或Released/TestSuccessTrue→ 计入成功数ReadyUnknown或ReconcilingTrue→ 计入进行中数最终判定进行中数 ≥ 2 →Progressing成功数 ≥ 2 →Healthy否则 →Degraded无 status 信息时返回ProgressingStatus unknown。以 GitRepository 的 health.lua 为例额外处理了ArtifactOutdated与ArtifactInStorage两类条件将ArtifactInStorageTrue计入成功从而反映制品已就绪这一源资源特有的健康语义。可以看到所有健康检查脚本均遵循统一的返回约定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.0LDAP 连接器破坏性变更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 的命名规则变更前后缀为-YYYYMMDDHHmm4 位年份例如mychron-202609120700变更后后缀为-YYMMDDHHmm2 位年份例如mychron-2609120700该变更仅影响由 Argo CD 手动触发的 Job。由 Kubernetes 按调度schedule自动创建的 Job 命名不受 Argo CD 控制格式保持不变。适配建议检查是否有脚本、CI 流水线或监控告警规则依赖旧的 4 位年份命名模式如正则-\d{12}$升级后需要同步调整为 2 位年份格式-\d{10}$。下载日志文件的扩展名变更.txt→.logArgo 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/AWSManagedControlPlanepolicy.open-cluster-management.io/CertificatePolicypolicy.open-cluster-management.io/ConfigurationPolicypolicy.open-cluster-management.io/OperatorPolicypolicy.open-cluster-management.io/Policypolicy/PodDisruptionBudgetcluster.x-k8s.io/MachinePoollifecycle.keptn.sh/KeptnWorkloadVersionnumaplane.numaproj.io/ISBServiceRolloutnumaplane.numaproj.io/NumaflowControllerRolloutnumaplane.numaproj.io/PipelineRolloutrds.aws.crossplane.io/DBClusterrds.aws.crossplane.io/DBInstanceiam.aws.crossplane.io/Policyiam.aws.crossplane.io/RolePolicyAttachmentiam.aws.crossplane.io/Roles3.aws.crossplane.io/Bucketmetrics.keptn.sh/KeptnMetricmetrics.keptn.sh/Analysisnumaplane.numaproj.io/MonoVertexRollouthelm.toolkit.fluxcd.io/HelmReleaseimage.toolkit.fluxcd.io/ImagePolicyimage.toolkit.fluxcd.io/ImageRepositoryimage.toolkit.fluxcd.io/ImageUpdateAutomationkustomize.toolkit.fluxcd.io/Kustomizationnotification.toolkit.fluxcd.io/Receiversource.toolkit.fluxcd.io/Bucketsource.toolkit.fluxcd.io/GitRepositorysource.toolkit.fluxcd.io/HelmChartsource.toolkit.fluxcd.io/HelmRepositorysource.toolkit.fluxcd.io/OCIRepository这些健康检查让 Argo CD 能够准确评估 Cluster API、Open Cluster Management、Crossplane、Keptn、Numaproj 以及 Flux 等生态资源的实际状态并正确反映到 Application 的整体健康度中。若你的集群使用上述任一资源类型升级后即可在 UI 中看到更精确的健康状态标识。升级行动清单ChecklistRBAC 更新为使用 Flux Actions 的集群资源授予patch权限否则 UI 中的Suspend/Resume/Reconcile不可用LDAP 验证检查目录中用户名/密码是否含 LDAP 过滤器特殊字符评估 Dex v2.39.0 严格校验带来的登录影响Job 命名脚本适配搜索-\d{12}$之类的旧 CronJob 手动触发 Job 匹配规则改为-\d{10}$日志采集适配将采集器与脚本中.txt日志 glob 规则更新为.log健康检查验证在测试环境观察新增健康检查特别是 Flux 资源的评估结果对照testdata样例排查异常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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考