Skip to content
Documentation Background

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.


  • 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 randAlphaNum generates different data on every helm template.
  • The HorizontalPodAutoscaler controller reorders spec.metrics. Ordering spec.metrics in 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.


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: IgnoreExtraneous

The 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=bar
generatorOptions:
annotations:
argocd.argoproj.io/compare-options: IgnoreExtraneous

It combines well with the Prune=false sync option, which stops the ignored resource from being pruned.


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.

MethodUse
jsonPointersRFC 6902 paths to a field, such as /spec/replicas
jqPathExpressionsjq expressions that select fields by content, for example list items added by a webhook
managedFieldsManagersIgnore 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/replicas

Ignore 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-manager

A / 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.

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=true

The 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.


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-manager

Two further settings in argocd-cm cover common noise:

SettingEffect
resource.compareoptions with ignoreResourceStatusFieldControls 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: trueStops changes to aggregated ClusterRole rules from counting as drift

Application levelSystem level
Wherespec.ignoreDifferences in the Applicationresource.customizations in argocd-cm
ScopeOne ApplicationEvery Application on the instance
SelectorsGroup and kind, with optional name and namespaceGroup and kind in the key name
Best forA workload with its own autoscaler or injectorCluster-wide behavior from a system controller or webhook

SymptomLikely causeFix
Application is OutOfSync right after a successful syncA controller, webhook, or template function changes the objectRun argocd app diff, then add an ignoreDifferences rule
A field is ignored in the diff but still overwritten by a syncThe rule is used only for comparisonAdd RespectIgnoreDifferences=true
A resource created by an operator keeps the Application OutOfSyncIt is extraneous in the live stateAnnotate the triggering manifest with IgnoreExtraneous
A JSON pointer never matchesA key contains /Write the slash as ~1
JQ patch execution timed outThe expression needs more than one secondRaise ignore.normalizer.jq.timeout in argocd-cmd-params-cm
A CRD stays out of sync because of its statusstatus committed in Git is comparedSet ignoreResourceStatusField: crd