Diffing and ignore rules
Argo CD marks an Application OutOfSync whenever the live state differs from the desired state. Many differences are harmless: a controller adds a field, an autoscaler changes the replica count, a webhook injects a container, an operator creates a secondary resource. Left alone, such an Application stays OutOfSync even right after a successful sync. Diffing customization tells Argo CD which differences to ignore.
Why an Application stays OutOfSync
Section titled “Why an Application stays OutOfSync”- The manifest contains fields Kubernetes does not know. The API server drops them, so the live object appears to be missing a field.
- A sync ran with pruning off and resources that should be deleted remain.
- A controller or mutating webhook changes the object after it was submitted.
- A Helm template function such as
randAlphaNumgenerates different data on everyhelm template. - The HorizontalPodAutoscaler controller reorders
spec.metrics. Orderingspec.metricsin Git the way the controller prefers avoids it.
If the cause cannot be fixed at the source, ignore the difference. Run argocd app diff <app-name> to see exactly what Argo CD considers different.
Extraneous resources
Section titled “Extraneous resources”Applying a manifest can make a controller create additional resources in the cluster. They exist only in the live state, so Argo CD sees them as extraneous and reports the Application OutOfSync. Annotate the manifest that triggers them with the IgnoreExtraneous compare option:
metadata: annotations: argocd.argoproj.io/compare-options: IgnoreExtraneousThe Application then reports Synced. The generated resource still shows OutOfSync on its own node, but that no longer propagates to the Application. This option affects sync status only. If the generated resource becomes unhealthy, the Application is still Degraded.
A common case is a Kustomize configMapGenerator, which produces resources Git does not list. Add the annotation through generatorOptions:
configMapGenerator:- name: app-config literals: - foo=bargeneratorOptions: annotations: argocd.argoproj.io/compare-options: IgnoreExtraneousIt combines well with the Prune=false sync option, which stops the ignored resource from being pruned.
Application-level rules
Section titled “Application-level rules”spec.ignoreDifferences ignores specific fields for one Application only. Each rule selects resources by group (the API group without the version) and kind, optionally narrowed by name and namespace, and then names the fields in one of three ways.
| Method | Use |
|---|---|
jsonPointers | RFC 6902 paths to a field, such as /spec/replicas |
jqPathExpressions | jq expressions that select fields by content, for example list items added by a webhook |
managedFieldsManagers | Ignore every field owned by a named manager recorded in metadata.managedFields |
Ignore the replica count that an HPA manages:
spec: ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicasIgnore a container injected by an admission webhook:
spec: ignoreDifferences: - group: apps kind: Deployment jqPathExpressions: - .spec.template.spec.initContainers[] | select(.name == "injected-init-container")Ignore everything a particular controller owns:
spec: ignoreDifferences: - group: '*' kind: '*' managedFieldsManagers: - kube-controller-managerA / inside a JSON pointer key is written ~1, so node-role.kubernetes.io/worker becomes /metadata/labels/node-role.kubernetes.io~1worker. A jq expression is limited to one second of evaluation. If a complex expression times out, raise ignore.normalizer.jq.timeout in the argocd-cmd-params-cm ConfigMap.
Respecting the rules during sync
Section titled “Respecting the rules during sync”By default these rules only affect the comparison, which decides whether the Application is Synced. When a sync runs, Argo CD still applies the desired state as written, using a three-way merge with the live state and the last-applied configuration. That can overwrite exactly the field you meant to ignore. Add the RespectIgnoreDifferences=true sync option to pre-patch the desired state with the ignored fields before applying it:
spec: ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicas syncPolicy: syncOptions: - RespectIgnoreDifferences=trueThe option only has an effect on resources that already exist. When an Application is first created and there is no live state, the desired state is applied unchanged.
System-level rules
Section titled “System-level rules”Rules in argocd-cm apply to every Application on the Argo CD instance. They use resource.customizations keys of the form resource.customizations.ignoreDifferences.<group>_<Kind>, with the group and kind joined by an underscore:
data: resource.customizations.ignoreDifferences.apps_Deployment: | jsonPointers: - /spec/replicas resource.customizations.ignoreDifferences.admissionregistration.k8s.io_MutatingWebhookConfiguration: | jqPathExpressions: - '.webhooks[]?.clientConfig.caBundle'A key ending in .all applies to every resource of every Application:
data: resource.customizations.ignoreDifferences.all: | managedFieldsManagers: - kube-controller-managerTwo further settings in argocd-cm cover common noise:
| Setting | Effect |
|---|---|
resource.compareoptions with ignoreResourceStatusField | Controls diffing of the status field: all (the default), crd, or none. Use crd if CRDs in Git carry a committed status |
resource.compareoptions with ignoreAggregatedRoles: true | Stops changes to aggregated ClusterRole rules from counting as drift |
Choosing a level
Section titled “Choosing a level”| Application level | System level | |
|---|---|---|
| Where | spec.ignoreDifferences in the Application | resource.customizations in argocd-cm |
| Scope | One Application | Every Application on the instance |
| Selectors | Group and kind, with optional name and namespace | Group and kind in the key name |
| Best for | A workload with its own autoscaler or injector | Cluster-wide behavior from a system controller or webhook |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
Application is OutOfSync right after a successful sync | A controller, webhook, or template function changes the object | Run argocd app diff, then add an ignoreDifferences rule |
| A field is ignored in the diff but still overwritten by a sync | The rule is used only for comparison | Add RespectIgnoreDifferences=true |
A resource created by an operator keeps the Application OutOfSync | It is extraneous in the live state | Annotate the triggering manifest with IgnoreExtraneous |
| A JSON pointer never matches | A key contains / | Write the slash as ~1 |
JQ patch execution timed out | The expression needs more than one second | Raise ignore.normalizer.jq.timeout in argocd-cmd-params-cm |
A CRD stays out of sync because of its status | status committed in Git is compared | Set ignoreResourceStatusField: crd |