Argo CD使用 argocd admin settings resource-overrides ignore-differences 调试 ignoreDifferences 差异忽略规则【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本文介绍 Argo CD CLI 中argocd admin settings resource-overrides ignore-differences命令的完整用法。该命令是argocd admin settings resource-overrides命令组下的排障工具用于将argocd-cmConfigMap 中resource.customizations字段配置的ignoreDifferences规则应用到一份本地资源清单上直观渲染出哪些字段会被排除在 diff 之外。读完后你可以完整掌握该命令的语法与参数、理解它如何解析 ConfigMap 中的资源定制配置、通过源码弄清 JSON Pointer 与 JQ 表达式的执行机制并能用它快速验证某个字段为什么没被忽略 / 为什么被忽略了。命令概述该命令的官方定义为argocd admin settings resource-overrides ignore-differences RESOURCE_YAML_PATH [flags]命令的功能描述为Renders fields excluded from diffing渲染被排除在 diff 之外的字段。其完整 Synopsis 说明Renders ignored fields using the ignoreDifferences setting specified in the resource.customizations field of argocd-cm ConfigMap即使用argocd-cmConfigMap 中resource.customizations字段所指定的ignoreDifferences设置渲染被忽略的字段。官方给出的示例argocd admin settings resource-overrides ignore-differences ./deploy.yaml --argocd-cm-path ./argocd-cm.yaml也就是说该命令的典型工作方式是输入一个本地资源 YAML 文件任意 Kubernetes 资源的清单再指定一个本地的argocd-cmConfigMap YAML 文件命令行会在本地完成加载配置 → 匹配资源类型 → 应用忽略规则 → 打印被忽略字段的整个过程不需要连接集群也不需要 Argo CD API Server 处于运行状态非常适合在本地验证规则、做 CI 检查或排障。专属选项-h, --help help for ignore-differences该命令没有专属的功能性 flag其行为完全由命令行参数资源 YAML 路径与继承的全局 flag 决定。从父命令继承的选项该命令注册在argocd admin settings resource-overrides命令树下参见 父命令文档因此继承了一整套 Argo CD CLI 的全局选项。完整列表如下--argocd-cm-path string Path to local argocd-cm.yaml file --argocd-context string The name of the Argo-CD server context to use --argocd-secret-path string Path to local argocd-secret.yaml file --as string Username to impersonate for the operation --as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups. --as-uid string UID to impersonate for the operation --auth-token string Authentication token; set this or the ARGOCD_AUTH_TOKEN environment variable --certificate-authority string Path to a cert file for the certificate authority --client-certificate string Path to a client certificate file for TLS --client-crt string Client certificate file --client-crt-key string Client certificate key file --client-key string Path to a client key file for TLS --cluster string The name of the kubeconfig cluster to use --config string Path to Argo CD config (default /home/user/.config/argocd/config) --context string The name of the kubeconfig context to use --controller-name string Name of the Argo CD Application controller; set this or the ARGOCD_APPLICATION_CONTROLLER_NAME environment variable when the controllers name label differs from the default, for example when installing via the Helm chart (default argocd-application-controller) --core If set to true then CLI talks directly to Kubernetes instead of talking to Argo CD API server --disable-compression If true, opt-out of response compression for all requests to the server --grpc-web Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2. --grpc-web-root-path string Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2. Set web root. -H, --header strings Sets additional header to all requests made by Argo CD CLI. (Can be repeated multiple times to add multiple headers, also supports comma separated headers) --http-retry-max int Maximum number of retries to establish http connection to Argo CD server --insecure Skip server certificate and domain verification --insecure-skip-tls-verify If true, the servers certificate will not be checked for validity. This will make your HTTPS connections insecure --kube-context string Directs the command to the given kube-context --kubeconfig string Path to a kube config. Only required if out-of-cluster --load-cluster-settings Indicates that config map and secret should be loaded from cluster unless local file path is provided --logformat string Set the logging format. One of: json|text (default json) --loglevel string Set the logging level. One of: debug|info|warn|error (default info) -n, --namespace string If present, the namespace scope for this CLI request --password string Password for basic authentication to the API server --plaintext Disable TLS --port-forward Connect to a random argocd-server port using port forwarding --port-forward-namespace string Namespace name which should be used for port forwarding --prompts-enabled Force optional interactive prompts to be enabled or disabled, overriding local configuration. If not specified, the local configuration value will be used, which is false by default. --proxy-url string If provided, this URL will be used to connect via proxy --redis-compress string Enable this if the application controller is configured with redis compression enabled. (possible values: gzip, none) (default gzip) --redis-haproxy-name string Name of the Redis HA Proxy; set this or the ARGOCD_REDIS_HAPROXY_NAME environment variable when the HA Proxys name label differs from the default, for example when installing via the Helm chart (default argocd-redis-ha-haproxy) --redis-name string Name of the Redis deployment; set this or the ARGOCD_REDIS_NAME environment variable when the Rediss name label differs from the default, for example when installing via the Helm chart (default argocd-redis) --repo-server-name string Name of the Argo CD Repo server; set this or the ARGOCD_REPO_SERVER_NAME environment variable when the servers name label differs from the default, for example when installing via the Helm chart (default argocd-repo-server) --request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means dont timeout requests. (default 0) --server string The address and port of the Kubernetes API server --server-crt string Server certificate file --server-name string Name of the Argo CD API server; set this or the ARGOCD_SERVER_NAME environment variable when the servers name label differs from the default, for example when installing via the Helm chart (default argocd-server) --tls-server-name string If provided, this name will be used to validate server certificate. If this is not provided, hostname used to contact the server is used. --token string Bearer token for authentication to the API server --user string The name of the kubeconfig user to use --username string Username for basic authentication to the API server对这条具体命令而言实际常用的只有三个Flag作用--argocd-cm-path string指定本地argocd-cm.yaml文件路径命令从中读取resource.customizations定制配置。这是本地排障场景的核心 flag--core让 CLI 直接与 Kubernetes 交互而不是通过 Argo CD API Server--kubeconfig/--context/--namespace配合--core指定要从中加载 ConfigMap 的集群与命名空间未提供本地文件路径时命令执行流程源码级解析该命令实现在 admin/settings.go 的NewResourceIgnoreDifferencesCommand中。理解其执行流程有助于准确解读命令输出判断规则到底有没有命中。第一步读取资源清单并定位资源定制配置命令入口通过executeResourceOverrideCommand完成准备工作见 admin/settings.goos.ReadFile(args[0])读取命令行传入的RESOURCE_YAML_PATH文件用yaml.Unmarshal将其解析为unstructured.Unstructured对象通过cmdCtx.createSettingsManager(ctx)创建 SettingsManager即依据--argocd-cm-path等 flag 决定从本地文件还是集群加载argocd-cm/argocd-secret再调用GetResourceOverrides()取出全部资源定制配置根据资源清单的apiVersionkind生成查找键group 非空时为group/Kind否则直接用Kind用于在 overrides 映射中取出该资源类型对应的ResourceOverride。第二步判断规则是否配置、字段是否被忽略NewResourceIgnoreDifferencesCommand的 Run 逻辑见 admin/settings.go按如下顺序输出三种结果之一未配置规则若该资源的JSONPointers与JQPathExpressions均为空打印Ignore differences are not configured for group/kind命令结束。应用规则但无变化命令构造normalizers.NewIgnoreNormalizer(nil, overrides, normalizers.IgnoreNormalizerOpts{})对资源深拷贝执行一次归一化Normalize。若归一化后的对象与原对象reflect.DeepEqual相等打印No fields are ignored by ignoreDifferences settings:并附上当前规则内容。这说明规则配置存在但路径在资源上没有任何可移除的字段。成功命中打印Following fields are ignored:并用cli.PrintDiff以 diff 形式列出所有被忽略的字段——这正是该命令Renders fields excluded from diffing的本体。源码中有一段值得注意的注释该命令使用的 normalizer不会验证managedFieldsManagers类型的 ignore-difference 配置因为这类规则需要访问集群中资源的metadata.managedFieldslive 数据而本命令的定位是纯本地排障This requires access to live resources which is not the purpose of this command. This will just apply jsonPointers and jqPathExpressions configurations.。换言之即使你的规则里写了managedFieldsManagers该命令也不会对它做渲染只处理jsonPointers和jqPathExpressions两类配置。第三步ignore normalizer 如何移除字段normalizer 的实现位于 normalizers/diff_normalizer.go 的NewIgnoreNormalizerL121 起。它做了两件事先把argocd-cm中按group/Kind组织的ResourceOverride.IgnoreDifferences展开为统一的ResourceIgnoreDifferences列表再把每条规则编译为可执行的 patchJSONPointers每条指针被编译成 RFC 6902 JSON Patch 的{op: remove, path: pointer}归一化时对资源执行一次删除。这与 diff/ignore.go 中IgnoreDifference结构体对指针格式的定义一致遵循 RFC 6902 的指针语法注意路径中的/需写成~1如/metadata/labels/node-role.kubernetes.io~1worker。JQPathExpressions每条 JQ 表达式被包装为del(expression)查询用 gojq 在带超时的上下文中执行DefaultJQExecutionTimeout默认为 1 秒。JQ 表达式还能按内容定位列表元素例如.spec.template.spec.initContainers[] | select(.name injected-init-container)。这个以删除操作模拟忽略的机制正是命令输出的 diff 恰好等于被排除在 diff 之外的字段的原因normalizer 从副本上把目标字段删掉原对象与归一化副本之间的差异即被忽略字段集合。配置解析argocd-cm 中 key 的格式命令读取的规则来自argocd-cmConfigMap 的resource.customizations字段。settings.go 中的appendResourceOverridesFromSplitKeys展示了 key 的解析方式key 形如resource.customizations.customizationType.group_kind按.切分为 4 段customizationType为ignoreDifferences时value 按 YAML 反序列化为OverrideIgnoreDiff包含jsonPointers、jqPathExpressions、managedFieldsManagers末段资源类型中group 与 kind 以_分隔如apps_Deployment、admissionregistration.k8s.io_MutatingWebhookConfiguration特殊值all会被归一化为*/*表示对所有资源类型生效。而运行时真正做 diff 的引擎diff/ignore.go 的HasIgnoreDifference在合并规则时的顺序是先取group/Kind精确匹配的 override再合并通配*/*override最后合并 Application 级spec.ignoreDifferences条目支持 group/kind 的 glob 匹配以及可选的name、namespace限定三类规则去重后叠加生效。ignoreDifferences 配置背景该命令排障的对象是 Argo CD 的 Diffing Customization 能力。当一个应用同步后立刻又变为OutOfSync常见原因包括manifest 中存在会被 API Server 丢弃的多余字段、mutating webhook 在对象提交后改写对象、Helm 模板使用randAlphaNum之类每次生成不同值的函数、HPA 控制器重排spec.metrics顺序等。无法从上游修复时就可以用ignoreDifferences忽略这些差异。系统级配置即本命令所读取的配置写在argocd-cm的data中官方文档给出的典型示例忽略MutatingWebhookConfiguration的caBundle字段data: resource.customizations.ignoreDifferences.admissionregistration.k8s.io_MutatingWebhookConfiguration: | jqPathExpressions: - .webhooks[]?.clientConfig.caBundle忽略kube-controller-manager对Deployment所做的一切修改基于metadata.managedFieldsdata: resource.customizations.ignoreDifferences.apps_Deployment: | managedFieldsManagers: - kube-controller-manager对所有资源全局生效注意 key 末段为all解析时会归一化为*/*data: resource.customizations.ignoreDifferences.all: | managedFieldsManagers: - kube-controller-manager jsonPointers: - /spec/replicas与之相对Application 级的ignoreDifferences配置在 Application 的spec中可以精确到资源名称与命名空间本命令不读取这部分配置它只处理argocd-cm的系统级定制二者可在 Diffing Customization 文档 中对照阅读spec: ignoreDifferences: - group: apps kind: Deployment name: guestbook namespace: default jsonPointers: - /spec/replicas补充一点ignoreDifferences默认只影响 live 与 desired 状态之间的 diff 计算决定应用是否显示为 Synced不直接影响 sync 阶段的 patch 内容如需在 sync 阶段也尊重这些配置需为应用设置RespectIgnoreDifferencestruesync option详见 sync-options.md。实操示例下面给出一个完整的本地排障流程仅涉及查看与运行不修改任何仓库或集群内容。准备一份资源清单deploy.yamlapiVersion: apps/v1 kind: Deployment metadata: name: guestbook labels: app: guestbook spec: replicas: 3 selector: matchLabels: app: guestbook template: metadata: labels: app: guestbook spec: containers: - name: guestbook image: nginx:1.25准备一份导出的argocd-cm.yaml从集群导出 ConfigMap 即可命令只关心dataapiVersion: v1 kind: ConfigMap metadata: name: argocd-cm data: resource.customizations.ignoreDifferences.apps_Deployment: | jsonPointers: - /spec/replicas运行命令argocd admin settings resource-overrides ignore-differences ./deploy.yaml --argocd-cm-path ./argocd-cm.yaml预期输出类似Following fields are ignored: --- /spec/replicas (ignored) - 3即/spec/replicas字段被规则命中会在实际 diff 中被排除。若规则未配置输出为Ignore differences are not configured for apps/Deployment若规则存在但指针在清单上找不到对应字段例如对上面这份清单配置了/spec/paused则输出No fields are ignored by ignoreDifferences settings:。也可以将jqPathExpressions换成按内容定位列表项的写法来验证resource.customizations.ignoreDifferences.apps_Deployment: | jqPathExpressions: - .spec.template.spec.containers[] | select(.name guestbook)重新运行后该容器对象整体出现在被忽略字段列表中。该命令对应的自动化测试见 settings_test.go 中的TestResourceOverrideIgnoreDifferences验证了未配置规则与字段被忽略两条输出路径。在 resource-overrides 命令族中的位置ignore-differences是argocd admin settings resource-overrides排障命令族的一员同一命令组还包括均接受RESOURCE_YAML_PATH参数、可配合--argocd-cm-path本地运行ignore-resource-updates渲染ignoreResourceUpdates配置排除在资源更新之外的字段原理与ignore-differences对称actions list/actions run列出并试运行自定义资源操作health本地渲染资源的 Lua 健康检查脚本输出。它们共享executeResourceOverrideCommand的资源解析逻辑整体入口说明见 resource-overrides 命令参考。小结argocd admin settings resource-overrides ignore-differences是一条纯本地化的排障命令输入资源 YAML 与argocd-cm路径即可看到系统级ignoreDifferences规则jsonPointers/jqPathExpressions具体排除了哪些字段。使用时的三个关键认知它只读取argocd-cm中resource.customizations.ignoreDifferences.group_kind含all→*/*配置不涉及 Application 级spec.ignoreDifferences它基于RFC 6902 remove patch del()JQ 查询模拟忽略过程输出即被排除字段的 diff它不验证managedFieldsManagers规则——这类依赖 live 资源managedFields的规则无法在本地渲染需要结合实际应用状态确认。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考