Argo CD 实战用 argocd admin settings resource-overrides health 本地调试资源健康检查 Lua 脚本【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本文围绕 Argo CD 的argocd admin settings resource-overrides health命令展开它允许你在集群外、仅凭本地 YAML 文件和argocd-cm配置直接对某个 Kubernetes 资源执行由 Lua 脚本定义的健康检查health assessment并打印状态与消息。读完本文你将掌握该命令的完整用法与参数、其从 CLI 到 Lua 虚拟机Lua VM的调用链、健康状态的取值规则以及如何用它快速排查resource.customizations中自定义 health 脚本不生效、输出不符合预期等问题。命令定位resource-overrides 排障命令族的一员Argo CD 允许通过argocd-cmConfigMap 中的resource.customizations字段为任意 Group/Kind 的资源定制行为包括健康评估health、忽略差异ignoreDifferences、忽略更新ignoreResourceUpdates以及自定义操作actions。为了在不必重启控制器、不必等待 informer 同步的情况下验证这些 Lua 脚本的行为Argo CD CLI 提供了argocd admin settings resource-overrides命令族其中health评估资源健康本文主角ignore-differences渲染被 diff 排除的字段ignore-resource-updates渲染被资源更新排除的字段list-actions/run-action列出并执行自定义资源操作。该命令族在源码中由 NewResourceOverridesCommand 注册本文聚焦的health子命令由 NewResourceHealthCommand 定义。命令语法与参数基本用法argocd admin settings resource-overrides health RESOURCE_YAML_PATH [flags]命令说明Synopsis 原文Assess resource health using the lua script configured in the resource.customizations field of argocd-cm ConfigMap即使用argocd-cmConfigMap 中resource.customizations字段配置的 Lua 脚本来评估给定资源 YAML 文件的健康状态。官方示例argocd admin settings resource-overrides health ./deploy.yaml --argocd-cm-path ./argocd-cm.yaml即把待检查的资源清单./deploy.yaml与本地导出/编写的argocd-cm.yaml一起传入完全离线运行。命令自身选项-h, --help help for healthhealth子命令本身只带--help其余关键行为由继承的父命令选项决定。关键继承选项节选完整列表可通过argocd admin settings resource-overrides health --help查看其中与排障最相关的继承选项如下选项说明--argocd-cm-path string本地argocd-cm.yaml文件路径本地调试时最常用--argocd-secret-path string本地argocd-secret.yaml文件路径--load-cluster-settings未提供本地文件路径时直接从集群加载 ConfigMap 和 Secret--argocd-context string使用的 Argo CD server context 名称--config stringArgo CD CLI 配置文件路径默认~/.config/argocd/config--core设为 true 时 CLI 直接与 Kubernetes 通信而不是通过 Argo CD API server--kubeconfig/--kube-context/--server指定 kube 配置与上下文--request-timeout string单次 server 请求超时如30s0表示不超时--port-forward/--port-forward-namespace通过端口转发连接随机 argocd-server 端口--redis-compress string取值gzip默认或none需与 application controller 的 redis 压缩配置一致其余继承选项--as、--auth-token、--grpc-web、TLS 证书相关、--loglevel/--logformat等均属于 CLI 通用的连接与认证控制含义与argocd顶层命令一致此处不再逐一罗列。说明当同时提供--argocd-cm-path时命令读取本地文件否则从集群加载argocd-cm。排障场景推荐显式传入本地文件避免受集群侧配置漂移影响。源码解读一条命令背后发生了什么从源码结构看health的执行路径非常清晰全部逻辑集中在 cmd/argocd/commands/admin/settings.go 中。第一步读取资源 YAML 并解析为 Unstructured命令首先调用公共函数 executeResourceOverrideCommanddata, err : os.ReadFile(args[0]) errors.CheckError(err) res : unstructured.Unstructured{} errors.CheckError(yaml.Unmarshal(data, res)) settingsManager, err : cmdCtx.createSettingsManager(ctx) errors.CheckError(err) overrides, err : settingsManager.GetResourceOverrides() errors.CheckError(err) gvk : res.GroupVersionKind() key : gvk.Kind if gvk.Group ! { key fmt.Sprintf(%s/%s, gvk.Group, gvk.Kind) } override : overrides[key]这里有两个值得注意的实现细节资源键key的构造规则核心资源Group 为空用Kind作为键例如PodCRD 用Group/Kind例如argoproj.io/Workflow。你在resource.customizations中定义的 YAML 文件名/键必须与此规则严格一致否则脚本不会被命中——这也是“明明配置了脚本却提示未配置”的常见原因。overrides 的来源GetResourceOverrides()解析的就是argocd-cm中的resource.customizations字段得到一个map[string]v1alpha1.ResourceOverride。第二步调用健康评估入口health子命令的回调随后执行见 settings.go#L501-L513resHealth, err : healthutil.GetResourceHealth(res, lua.ResourceHealthOverrides(overrides)) switch { case err ! nil: errors.CheckError(err) case resHealth nil: fmt.Printf(Health script is not configured for %s/%s\n, gvk.Group, gvk.Kind) default: _, _ fmt.Printf(STATUS: %s\n, resHealth.Status) _, _ fmt.Printf(MESSAGE: %s\n, resHealth.Message) }输出因此只有三种形态脚本未配置提示、Lua 执行报错直接CheckError退出、或两行STATUS:/MESSAGE:结果。第三步GetResourceHealth 的优先级链healthutil.GetResourceHealth位于 gitops-engine 子模块的 pkg/health/health.go其评估顺序是正在删除的资源若资源带有 deletionTimestamp 且没有 hook finalizer直接返回Progressing / Pending deletion不再执行任何脚本覆盖脚本优先如果healthOverride即从resource.customizations提取的脚本对该资源有配置则执行 Lua 脚本脚本返回结果即为最终健康状态。Lua 执行出错时状态被降级为Unknown错误信息写入Message同时向上返回错误在本命令中会触发非零退出回退内置检查override 没有命中时走 GetHealthCheckFunc 分发的内置 Go 实现覆盖 Deployment、StatefulSet、ReplicaSet、DaemonSet、Ingress、APIService、Service、PVC、Pod、Job、HPA、argoproj.io/Workflow 等常见类型。注意一个微妙点当内置检查也存在时Lua override 的返回值会完全覆盖内置评估。这正是用本命令验证自定义脚本价值的场景——它回答的问题是“我的脚本对这个资源会算出什么状态”而不是“控制器最终会算什么”。健康状态的取值空间健康状态码定义于 gitops-engine/pkg/health/health.go共六种状态含义Unknown健康评估失败实际状态未知Progressing尚未健康但仍有希望达到健康状态Healthy100% 健康Suspended资源处于挂起/暂停状态典型如 suspended 的 CronJobDegraded资源 status 表明失败或在超时内无法达到健康状态Missing资源在集群中缺失源码中还有 healthOrder 与 IsWorse 用于在多资源之间比较“谁更不健康”这是应用级健康汇总的逻辑单资源命令本身不直接使用。第四步Lua 虚拟机的执行环境真正执行脚本的是 util/lua/lua.go 中的VMResourceHealthOverrides 将 overrides map 适配为HealthOverride接口GetResourceHealth先通过GetHealthScript按资源 GVK 查找脚本util/lua/lua_test.go 中存在getWildcardHealthOverride等测试说明查找支持通配匹配找不到脚本时返回nil, nil对应命令输出 “Health script is not configured”找到脚本后runLuaWithResourceActionParameters创建 Lua 状态并做安全加固默认SkipOpenLibs仅打开 package、base、table 库以及 Argo CD 提供的“安全版” OS 库OpenSafeOs见 util/lua/oslib_safe.go整个执行挂在1 秒超时的 context 上lua.go#L159脚本若死循环会被强制中止资源对象本身被解码为 Lua 表并注入为全局变量obj脚本内直接obj.status...访问资源字段编译结果经过 compiledScriptCache 缓存同一段脚本只编译一次编译失败不会被缓存保证每次都能拿到新鲜错误。由于这些约束编写 health 脚本时应只依赖只读的资源字段避免调用受限标准库脚本必须及时返回。实操一个端到端的本地调试示例下面用一个自定义 CRD 演示完整流程该示例为本文构造用于说明机制不是仓库内置配置。第 1 步准备待检查的资源文件deploy.yamlapiVersion: myexample.com/v1 kind: MyWidget metadata: name: widget-1 namespace: default status: phase: Ready第 2 步准备argocd-cm.yaml其中resource.customizations的键遵循Group/Kind规则apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm data: resource.customizations: | myexample.com/MyWidget: health.lua: | if obj.status and obj.status.phase Ready then return {status Healthy, message widget is ready} elseif obj.status and obj.status.phase Failed then return {status Degraded, message widget failed} else return {status Progressing, message waiting for widget} endArgo CD 内置的定制规则可参考 resource_customizations/ 目录每种 Group/Kind 由一份 YAML 描述与同名 Lua 脚本组成并由 resource_customizations/embed.go 嵌入二进制其组织方式与上面argocd-cm中手写的条目一致。第 3 步本地执行argocd admin settings resource-overrides health ./deploy.yaml --argocd-cm-path ./argocd-cm.yaml预期输出STATUS: Healthy MESSAGE: widget is ready第 4 步验证“未命中”场景把资源改为kind: MyGadget未配置脚本后再执行会看到Health script is not configured for myexample.com/MyGadget第 5 步验证“脚本报错”场景在 Lua 中写return obj.status.phase返回非表或触发语法错误命令会以非零码退出并打印 Lua 错误信息源码中 runLua 特意剥掉了默认的 Lua 堆栈跟踪只把对用户有意义的错误传回这正是把脚本先拿到 CLI 里跑一遍的价值所在。与运行时行为的关系本地命令与控制器侧共用同一套 override 与 Lua VM 实现因此本地验证的结论可以直接外推到生产行为application controller 的健康评估走 controller/health.go同样是lua.ResourceHealthOverrides(resourceOverrides)缓存层初始化时也会把同一份 override 传给 gitops-engine 的健康检查controller/cache/cache.go同步路径的 hook 健康检查同样引用它见 controller/hook.go。也就是说resource-overrides health命令等价于“在 controller 的健康评估函数上用你本地的argocd-cm和本地资源文件做一次确定性单测”。区别仅在于控制器面对的是集群中真实对象的完整status本地调试时你需要自行准备贴近真实状态的 YAMLstatus 字段是健康脚本的主要输入示例中的status.phase即为此。常见排障要点小结提示 “Health script is not configured”优先检查键名——核心资源用KindCRD 用Group/Kind再检查argocd-cm是否为resource.customizations而非其他字段名。结果与集群内观察到的一致/不一致确认本地 YAML 的status与集群中实际对象一致带 deletionTimestamp 的对象在本地调试时不会触发该分支而在集群中会被判为Progressing / Pending deletion。脚本超时或被安全策略拦截Lua 执行有 1 秒超时且标准库受限安全版os脚本应只读obj、快速返回。想看 ignore-differences 效果切换到同族的argocd admin settings resource-overrides ignore-differences它会输出被排除字段的 diff而非健康状态。延伸阅读resource-overrides命令族总览文档argocd admin settings resource-overrides 命令参考命令实现cmd/argocd/commands/admin/settings.goNewResourceHealthCommand及相关公共函数健康状态码与评估优先级gitops-engine/pkg/health/health.goLua 虚拟机与安全执行环境util/lua/lua.go、util/lua/oslib_safe.go内置定制规则示例库resource_customizations/。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Argo CD 实战：用 argocd admin settings resource-overrides health 本地调试资源健康检查 Lua 脚本
Argo CD 实战用 argocd admin settings resource-overrides health 本地调试资源健康检查 Lua 脚本【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本文围绕 Argo CD 的argocd admin settings resource-overrides health命令展开它允许你在集群外、仅凭本地 YAML 文件和argocd-cm配置直接对某个 Kubernetes 资源执行由 Lua 脚本定义的健康检查health assessment并打印状态与消息。读完本文你将掌握该命令的完整用法与参数、其从 CLI 到 Lua 虚拟机Lua VM的调用链、健康状态的取值规则以及如何用它快速排查resource.customizations中自定义 health 脚本不生效、输出不符合预期等问题。命令定位resource-overrides 排障命令族的一员Argo CD 允许通过argocd-cmConfigMap 中的resource.customizations字段为任意 Group/Kind 的资源定制行为包括健康评估health、忽略差异ignoreDifferences、忽略更新ignoreResourceUpdates以及自定义操作actions。为了在不必重启控制器、不必等待 informer 同步的情况下验证这些 Lua 脚本的行为Argo CD CLI 提供了argocd admin settings resource-overrides命令族其中health评估资源健康本文主角ignore-differences渲染被 diff 排除的字段ignore-resource-updates渲染被资源更新排除的字段list-actions/run-action列出并执行自定义资源操作。该命令族在源码中由 NewResourceOverridesCommand 注册本文聚焦的health子命令由 NewResourceHealthCommand 定义。命令语法与参数基本用法argocd admin settings resource-overrides health RESOURCE_YAML_PATH [flags]命令说明Synopsis 原文Assess resource health using the lua script configured in the resource.customizations field of argocd-cm ConfigMap即使用argocd-cmConfigMap 中resource.customizations字段配置的 Lua 脚本来评估给定资源 YAML 文件的健康状态。官方示例argocd admin settings resource-overrides health ./deploy.yaml --argocd-cm-path ./argocd-cm.yaml即把待检查的资源清单./deploy.yaml与本地导出/编写的argocd-cm.yaml一起传入完全离线运行。命令自身选项-h, --help help for healthhealth子命令本身只带--help其余关键行为由继承的父命令选项决定。关键继承选项节选完整列表可通过argocd admin settings resource-overrides health --help查看其中与排障最相关的继承选项如下选项说明--argocd-cm-path string本地argocd-cm.yaml文件路径本地调试时最常用--argocd-secret-path string本地argocd-secret.yaml文件路径--load-cluster-settings未提供本地文件路径时直接从集群加载 ConfigMap 和 Secret--argocd-context string使用的 Argo CD server context 名称--config stringArgo CD CLI 配置文件路径默认~/.config/argocd/config--core设为 true 时 CLI 直接与 Kubernetes 通信而不是通过 Argo CD API server--kubeconfig/--kube-context/--server指定 kube 配置与上下文--request-timeout string单次 server 请求超时如30s0表示不超时--port-forward/--port-forward-namespace通过端口转发连接随机 argocd-server 端口--redis-compress string取值gzip默认或none需与 application controller 的 redis 压缩配置一致其余继承选项--as、--auth-token、--grpc-web、TLS 证书相关、--loglevel/--logformat等均属于 CLI 通用的连接与认证控制含义与argocd顶层命令一致此处不再逐一罗列。说明当同时提供--argocd-cm-path时命令读取本地文件否则从集群加载argocd-cm。排障场景推荐显式传入本地文件避免受集群侧配置漂移影响。源码解读一条命令背后发生了什么从源码结构看health的执行路径非常清晰全部逻辑集中在 cmd/argocd/commands/admin/settings.go 中。第一步读取资源 YAML 并解析为 Unstructured命令首先调用公共函数 executeResourceOverrideCommanddata, err : os.ReadFile(args[0]) errors.CheckError(err) res : unstructured.Unstructured{} errors.CheckError(yaml.Unmarshal(data, res)) settingsManager, err : cmdCtx.createSettingsManager(ctx) errors.CheckError(err) overrides, err : settingsManager.GetResourceOverrides() errors.CheckError(err) gvk : res.GroupVersionKind() key : gvk.Kind if gvk.Group ! { key fmt.Sprintf(%s/%s, gvk.Group, gvk.Kind) } override : overrides[key]这里有两个值得注意的实现细节资源键key的构造规则核心资源Group 为空用Kind作为键例如PodCRD 用Group/Kind例如argoproj.io/Workflow。你在resource.customizations中定义的 YAML 文件名/键必须与此规则严格一致否则脚本不会被命中——这也是“明明配置了脚本却提示未配置”的常见原因。overrides 的来源GetResourceOverrides()解析的就是argocd-cm中的resource.customizations字段得到一个map[string]v1alpha1.ResourceOverride。第二步调用健康评估入口health子命令的回调随后执行见 settings.go#L501-L513resHealth, err : healthutil.GetResourceHealth(res, lua.ResourceHealthOverrides(overrides)) switch { case err ! nil: errors.CheckError(err) case resHealth nil: fmt.Printf(Health script is not configured for %s/%s\n, gvk.Group, gvk.Kind) default: _, _ fmt.Printf(STATUS: %s\n, resHealth.Status) _, _ fmt.Printf(MESSAGE: %s\n, resHealth.Message) }输出因此只有三种形态脚本未配置提示、Lua 执行报错直接CheckError退出、或两行STATUS:/MESSAGE:结果。第三步GetResourceHealth 的优先级链healthutil.GetResourceHealth位于 gitops-engine 子模块的 pkg/health/health.go其评估顺序是正在删除的资源若资源带有 deletionTimestamp 且没有 hook finalizer直接返回Progressing / Pending deletion不再执行任何脚本覆盖脚本优先如果healthOverride即从resource.customizations提取的脚本对该资源有配置则执行 Lua 脚本脚本返回结果即为最终健康状态。Lua 执行出错时状态被降级为Unknown错误信息写入Message同时向上返回错误在本命令中会触发非零退出回退内置检查override 没有命中时走 GetHealthCheckFunc 分发的内置 Go 实现覆盖 Deployment、StatefulSet、ReplicaSet、DaemonSet、Ingress、APIService、Service、PVC、Pod、Job、HPA、argoproj.io/Workflow 等常见类型。注意一个微妙点当内置检查也存在时Lua override 的返回值会完全覆盖内置评估。这正是用本命令验证自定义脚本价值的场景——它回答的问题是“我的脚本对这个资源会算出什么状态”而不是“控制器最终会算什么”。健康状态的取值空间健康状态码定义于 gitops-engine/pkg/health/health.go共六种状态含义Unknown健康评估失败实际状态未知Progressing尚未健康但仍有希望达到健康状态Healthy100% 健康Suspended资源处于挂起/暂停状态典型如 suspended 的 CronJobDegraded资源 status 表明失败或在超时内无法达到健康状态Missing资源在集群中缺失源码中还有 healthOrder 与 IsWorse 用于在多资源之间比较“谁更不健康”这是应用级健康汇总的逻辑单资源命令本身不直接使用。第四步Lua 虚拟机的执行环境真正执行脚本的是 util/lua/lua.go 中的VMResourceHealthOverrides 将 overrides map 适配为HealthOverride接口GetResourceHealth先通过GetHealthScript按资源 GVK 查找脚本util/lua/lua_test.go 中存在getWildcardHealthOverride等测试说明查找支持通配匹配找不到脚本时返回nil, nil对应命令输出 “Health script is not configured”找到脚本后runLuaWithResourceActionParameters创建 Lua 状态并做安全加固默认SkipOpenLibs仅打开 package、base、table 库以及 Argo CD 提供的“安全版” OS 库OpenSafeOs见 util/lua/oslib_safe.go整个执行挂在1 秒超时的 context 上lua.go#L159脚本若死循环会被强制中止资源对象本身被解码为 Lua 表并注入为全局变量obj脚本内直接obj.status...访问资源字段编译结果经过 compiledScriptCache 缓存同一段脚本只编译一次编译失败不会被缓存保证每次都能拿到新鲜错误。由于这些约束编写 health 脚本时应只依赖只读的资源字段避免调用受限标准库脚本必须及时返回。实操一个端到端的本地调试示例下面用一个自定义 CRD 演示完整流程该示例为本文构造用于说明机制不是仓库内置配置。第 1 步准备待检查的资源文件deploy.yamlapiVersion: myexample.com/v1 kind: MyWidget metadata: name: widget-1 namespace: default status: phase: Ready第 2 步准备argocd-cm.yaml其中resource.customizations的键遵循Group/Kind规则apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm data: resource.customizations: | myexample.com/MyWidget: health.lua: | if obj.status and obj.status.phase Ready then return {status Healthy, message widget is ready} elseif obj.status and obj.status.phase Failed then return {status Degraded, message widget failed} else return {status Progressing, message waiting for widget} endArgo CD 内置的定制规则可参考 resource_customizations/ 目录每种 Group/Kind 由一份 YAML 描述与同名 Lua 脚本组成并由 resource_customizations/embed.go 嵌入二进制其组织方式与上面argocd-cm中手写的条目一致。第 3 步本地执行argocd admin settings resource-overrides health ./deploy.yaml --argocd-cm-path ./argocd-cm.yaml预期输出STATUS: Healthy MESSAGE: widget is ready第 4 步验证“未命中”场景把资源改为kind: MyGadget未配置脚本后再执行会看到Health script is not configured for myexample.com/MyGadget第 5 步验证“脚本报错”场景在 Lua 中写return obj.status.phase返回非表或触发语法错误命令会以非零码退出并打印 Lua 错误信息源码中 runLua 特意剥掉了默认的 Lua 堆栈跟踪只把对用户有意义的错误传回这正是把脚本先拿到 CLI 里跑一遍的价值所在。与运行时行为的关系本地命令与控制器侧共用同一套 override 与 Lua VM 实现因此本地验证的结论可以直接外推到生产行为application controller 的健康评估走 controller/health.go同样是lua.ResourceHealthOverrides(resourceOverrides)缓存层初始化时也会把同一份 override 传给 gitops-engine 的健康检查controller/cache/cache.go同步路径的 hook 健康检查同样引用它见 controller/hook.go。也就是说resource-overrides health命令等价于“在 controller 的健康评估函数上用你本地的argocd-cm和本地资源文件做一次确定性单测”。区别仅在于控制器面对的是集群中真实对象的完整status本地调试时你需要自行准备贴近真实状态的 YAMLstatus 字段是健康脚本的主要输入示例中的status.phase即为此。常见排障要点小结提示 “Health script is not configured”优先检查键名——核心资源用KindCRD 用Group/Kind再检查argocd-cm是否为resource.customizations而非其他字段名。结果与集群内观察到的一致/不一致确认本地 YAML 的status与集群中实际对象一致带 deletionTimestamp 的对象在本地调试时不会触发该分支而在集群中会被判为Progressing / Pending deletion。脚本超时或被安全策略拦截Lua 执行有 1 秒超时且标准库受限安全版os脚本应只读obj、快速返回。想看 ignore-differences 效果切换到同族的argocd admin settings resource-overrides ignore-differences它会输出被排除字段的 diff而非健康状态。延伸阅读resource-overrides命令族总览文档argocd admin settings resource-overrides 命令参考命令实现cmd/argocd/commands/admin/settings.goNewResourceHealthCommand及相关公共函数健康状态码与评估优先级gitops-engine/pkg/health/health.goLua 虚拟机与安全执行环境util/lua/lua.go、util/lua/oslib_safe.go内置定制规则示例库resource_customizations/。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考