The sync just succeeded. The Application flips back to OutOfSync immediately, on a field nobody touched, and the diff shows a single integer or one encoded string. Syncing again changes nothing: the loop reforms identically.

This is neither a bug nor drift. It is the normal state of a system comparing Git to a cluster in which something else writes too. The useful question is not how to silence the alert, but how to declare that this particular divergence is expected without losing detection everywhere else.

What writes into the object besides you

The Argo CD documentation lists the known causes of an OutOfSync right after a successful sync, and they fall into three families.

The first is controllers and mutating webhooks: the object is altered after it was submitted to the API, so it no longer matches what Git describes. The textbook documented case is the HPA object, whose controller reorders spec.metrics into an order of its own — the recommended workaround is not even to ignore the field, it is to write spec.metrics in Git in the order the controller prefers.

The second is non-deterministic manifests. A Helm chart using a template function such as randAlphaNum produces a different value on every helm template invocation. The desired state changes on its own, at constant commit.

The third is more annoying: the manifest contains an extra or unknown field relative to the actual Kubernetes spec. That field is dropped when Argo CD queries the cluster for the live state, producing an OutOfSync reporting a missing field. The diff then points at a typo, not at a controller.

There is also a case that is not a mutation at all: a sync performed with pruning disabled leaves resources that should be deleted, and the Application stays OutOfSync for that reason. Hunting for the offending field is then wasted time, there is none.

Three ways to designate what you ignore

spec.ignoreDifferences is a list of entries, each targeting a group and a kind. The group is the Kubernetes API group without the version — writing apps/v1 matches nothing.

The most common selector is the JSON pointer, in the RFC 6902 sense:

# Ignore the replicas field for every Deployment of this Application
spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

The entry can be narrowed to a named object, with an optional namespace, which beats neutralising a field for every Deployment at once:

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      name: guestbook
      namespace: default
      jsonPointers:
        - /spec/replicas

A syntax trap awaits anyone ignoring a label: the JSON pointer uses / as a separator, so a / inside the key must be replaced with ~1.

# node-role.kubernetes.io/worker -> node-role.kubernetes.io~1worker
spec:
  ignoreDifferences:
    - kind: Node
      jsonPointers:
        - /metadata/labels/node-role.kubernetes.io~1worker

The second selector, jqPathExpressions, is for targets that are list items identified by content rather than by index. That is the case of an init container injected by a service mesh or an operator: its position in the list is not guaranteed.

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jqPathExpressions:
        - .spec.template.spec.initContainers[] | select(.name == "injected-init-container")

One limit to know before writing a complicated expression: evaluating a jqPathExpression is capped at one second. The JQ patch execution timed out message is fixed by raising ignore.normalizer.jq.timeout in the argocd-cmd-params-cm ConfigMap, but an expression exceeding one second deserves simplification first.

The third selector is the most interesting, and the least used. managedFieldsManagers ignores every field owned by a given manager, read from metadata.managedFields on the live resource. You stop describing fields one by one and start describing who is allowed to own them.

# Ignore whatever kube-controller-manager owns, whatever the field is
spec:
  ignoreDifferences:
    - group: '*'
      kind: '*'
      managedFieldsManagers:
        - kube-controller-manager

This is the phrasing to prefer when the cause is “a controller writes into this object”. It describes the actual mechanism instead of enumerating its symptoms, and it does not rot when the controller starts touching one more field.

System level, for divergences that are not yours

Some divergences belong to no Application in particular: they come from the resource type. They are configured in the resource.customizations key of the argocd-cm ConfigMap, indexed by group and kind.

# argocd-cm — the caBundle of a MutatingWebhookConfiguration is injected
# by a cert manager, never by Git.
data:
  resource.customizations.ignoreDifferences.admissionregistration.k8s.io_MutatingWebhookConfiguration: |
    jqPathExpressions:
    - '.webhooks[]?.clientConfig.caBundle'

The same configuration accepts .all to target every resource of every Application on the instance. It is powerful, and it is exactly where you shoot yourself in the foot: an .all entry ignoring /spec/replicas removes replica drift detection for the whole platform, including where that number really is managed by Git.

Two specific settings are worth knowing, because they cover very frequent cases. ignoreResourceStatusField disables diffing on the status field, defaulting to all — status is written by controllers and cannot be applied as desired configuration. The documentation recommends crd over none for those who commit their CRD status to Git. And ignoreAggregatedRoles: true keeps Argo CD from reading rules injected into an aggregated ClusterRole as drift.

data:
  resource.compareoptions: |
    ignoreResourceStatusField: crd
    ignoreAggregatedRoles: true

The part everyone misses: ignoring does not prevent writing

This is the subtlety that makes ignoreDifferences look “broken” while it works exactly as documented.

ignoreDifferences only affects diff computation. It decides whether the Application is displayed as synced. During the sync, the desired state is applied as-is, and the patch is computed by a three-way merge between the live state, the desired state and the last-applied-configuration annotation — the merge nobody actually looks at.

In practice: ignoring /spec/replicas silences the screen, then the next sync writes the Git value back over the HPA’s. The screen no longer lies, but the cluster still gets its counter reset.

The RespectIgnoreDifferences=true sync option is what extends ignoreDifferences to the sync stage: the desired state is pre-patched before being applied.

spec:
  ignoreDifferences:
    - group: 'apps'
      kind: 'Deployment'
      jsonPointers:
        - /spec/replicas
  syncPolicy:
    syncOptions:
      - RespectIgnoreDifferences=true

It comes with a documented caveat that matters at creation time: the option is only effective when the resource already exists in the cluster. When the Application is being created and no live state exists, the desired state is applied as-is. So the first deployment does set the Git value; it is the following ones that leave it alone.

Two neighbouring mechanisms people confuse with this one

argocd.argoproj.io/compare-options: IgnoreExtraneous does not deal with a field but with a whole extraneous resource, typically a ConfigMap generated by a tool. It excludes it from the application’s overall sync status, and the documentation states the limit: only sync status is affected, a degraded resource still degrades the application.

ignoreResourceUpdates looks like ignoreDifferences down to its syntax, but it answers a performance question, not a display one. By default, an Application is refreshed every time a resource belonging to it changes; controllers that periodically update their objects trigger continuous reconciles and drive up application controller CPU. ignoreResourceUpdates says “this change does not justify a reconcile”. It has no effect on the diff.

# argocd-cm — the refreshTime of an ExternalSecret changes constantly and
# never justifies a reconcile.
data:
  resource.customizations.ignoreResourceUpdates.external-secrets.io_ExternalSecret: |
    jsonPointers:
    - /status/refreshTime

The two cross on one point worth knowing: by default, system-level ignoreDifferences entries are also applied to resource updates, a behaviour disabled with ignoreDifferencesOnResourceUpdates: false in resource.compareoptions.

The criterion for how far to ignore

A well-written ignore rule describes who owns the field, not which value you tolerate. That is the difference between managedFieldsManagers: [kube-controller-manager], which stays true as the controller evolves, and a list of JSON pointers you will extend at every version bump.

The phrasing that should trigger a second reading is jsonPointers: [/spec], or an .all entry with neither group nor kind. At that level you have not declared an expected divergence: you have unplugged drift detection, which is the only reason to run a GitOps controller in the first place.

Logical follow-up on the operations side: ArgoCD vs Flux and the French reading path la chaîne CI/CD.