一张没有 schema 的 ConfigMap 决定了整个平台

一句话总结

argocd-cm 是没有 schema 的 ConfigMap，所以拼写错误不会变成错误，而是变成“没有配置”； argocd admin settings validate 并不是替你检查的工具，而是把读取到的值回显出来的工具。

为什么需要这种确认

开始以声明方式管理 Argo CD 之后，argocd-cm 这一份会越来越大。账号、SSO、kustomize 构建选项、 不监视的类型、所有权标记方式、健康规则、忽略规则、资源操作，全都会作为这个文件的键进来。 问题在于这个文件是一个普通的 ConfigMap。Kubernetes 不会检查键名。 即使把 kustomize.buildOptions 写成 kustomize.buildOption，apply 也会成功，而 Argo CD 不认识 这个键，就直接略过。界面上任何地方都没有警告。

这类错误能存活很久。选项没有生效，通常是在做别的事情时偶然发现的， 到那时，已经没有人记得这一行是谁、为什么加进去的了。

工作原理

argocd admin settings validate 会读取 argocd-cm（必要时还有 argocd-secret），分成五节 输出解析后的结果。

✅ accounts            3 accounts
✅ general             Dex is configured
✅ kustomize           --enable-helm
✅ repositories        1 repositories
✅ resource-overrides  2 resource overrides

这里怎么读很重要。✅ 的意思是“读取那一节没有失败”，而不是“配置是对的”。 真正的信息在它下面那一行。如果多加了两个账号而数字没有变，就是键名写错了； 如果加入了构建选项，却显示 default options，就说明那个选项并不存在。也就是说，这条命令不是 linter， 而是回读。只有把它用来查看自己填入的值是否原样回来，它才有价值。

此外还有局限。并不是所有配置都会出现在这五节中。resource.exclusions 和 resource.inclusions 不会汇总到任何一节。这样的键，只能直接解析文件来确认。 inclusions 尤其要小心——只要写了一项，不在其中的类型就会全部变得不可见。

所有权标记的设置也值得了解。如果 application.resourceTrackingMethod 是 label，Argo CD 会把应用名称 写到 app.kubernetes.io/instance 这样的标签上。然而标签值不能超过 63 个字符。 随着组织变大、应用名称变长，就会碰到这个上限，被截断的名称会让不同的应用拥有相同的所有权标记—— 一个应用的同步动到另一个应用的资源，这类事故就是由此而来。annotation 方式 写在 argocd.argoproj.io/tracking-id 注解里，没有长度限制，因此是目前推荐的方式。

仓库也混杂着两代做法。argocd-cm 的 repositories 列表是旧方式，现在是一个仓库对应 一个 Secret，并贴上 argocd.argoproj.io/secret-type: repository 标签。最大的区别是可以同时存放 凭据。这里同样有悄无声息的失败——漏掉标签，Argo CD 就看不到那个 Secret。 不会报错。

在现场相遇的样子

最常见的场景是“使用 Helm 的 kustomize 构建不工作”这样的咨询。说是加了 kustomize.buildOptions， 实际文件里写的却是 buildOption。有这条命令，三秒钟就能解决，没有它， 就要在控制器日志和 Pod 重启之间来回折腾，耗掉半天。

第二种是错误地动了排除列表。为了降低负载，在 resource.inclusions 里只写了几种类型， 结果其余所有资源都从应用树中消失了。人们以为资源被删除了，慌了手脚。这项设置 不会出现在 validate 的输出里，所以修改之前要直接读文件，数一数保留了什么。

第三种是迁移。从标签方式改成注解方式时，Argo CD 可能认不出带有旧标签的资源是自己的。 因此这项变更不能悄悄地做，而是一项把修改前后读取到的值保存成文件，附在评审上的变更。 本实验的最后一步，正是这个习惯。

本实验环境的局限

实验 Pod 中没有 Argo CD 控制器和服务器。 因此无法修改配置后看到界面发生变化， 也无法用 SSO 登录试一试。不过，真正解析配置的代码就在 CLI 里，所以读取到了什么、 忽略了什么，都可以得到完全相同的结果。仓库 Secret 和所有权标记注解， 则会真正部署到 kwok 集群里试一试。

下一项实验要做什么

从空配置的回读开始，逐项增加账号、构建选项、排除列表、所有权标记、仓库。 中途故意把键名写错一个字母，看它是如何悄无声息地消失的。标签 63 个字符的上限， 在 kwok 集群中亲自撞一撞，最后把开头和结尾的回读用 diff 留存下来。