Skip to main content
This article demonstrates Argo CD’s ignoreDifferences feature in the Application spec and how it interacts with automated sync (autosync / self-heal) and autoscalers (HPA). The goal is to allow specific live-vs-desired differences—such as replica counts managed by an HPA—to be ignored during diffs and syncs so Argo CD doesn’t continuously revert those changes.

​
Problem summary

  • autosync + selfHeal cause Argo CD to continuously enforce the declared desired state.
  • If an HPA or an operator modifies fields (for example, /spec/replicas), Argo CD may detect it as drift and revert the change back to the manifest.
  • To avoid this loop, add an ignoreDifferences entry in the Application spec and ensure RespectIgnoreDifferences is enabled in syncOptions.
When to use ignoreDifferences
  • Use ignoreDifferences when a field is managed by an external controller (HPA, operator) and you want Argo CD to ignore changes to that field during diff and sync.
  • Common use cases: replica counts managed by HPA, operator-updated status fields, or dynamic ConfigMap values.
Use caseWhy ignore differencesExample fields
HPA-managed replicasPrevent Argo CD from resetting replicas on autosync/spec/replicas
Operator-managed resourcesAvoid fighting operator reconcilersManagedFields manager names
ConfigMaps updated at runtimeIgnore specific keys in ConfigMap dataJQ-style expressions on .data[...]

​
Reproducing the issue

Suppose your Deployment manifest declares replicas: 2 but an HPA or a manual action scales it up. If autosync/selfHeal are enabled and ignoreDifferences is not respected, Argo CD will reconcile the Deployment back to 2 replicas. Example: manually scale a Deployment 
kubectl -n health-check scale deployment random-shapes --replicas=10
# Output:
deployment.apps/random-shapes scaled
Listing pods shows scaled replicas being created: 
kubectl -n health-check get pods
# Example output:
NAME                                READY   STATUS              RESTARTS   AGE
random-shapes-9bb6bdfb8-5vpr7       0/1     ContainerCreating   0          26s
random-shapes-9bb6bdfb8-6vf7h       0/1     ContainerCreating   0          24s
random-shapes-9bb6bdfb8-chc6h       1/1     Running             0          18m
random-shapes-9bb6bdfb8-dx4mm       0/1     ContainerCreating   0          26s
random-shapes-9bb6bdfb8-fbs8s       0/1     ContainerCreating   0          25s
random-shapes-9bb6bdfb8-fmkpg       0/1     ContainerCreating   0          25s
random-shapes-9bb6bdfb8-gncmh       1/1     Running             0          26s
random-shapes-9bb6bdfb8-h8qvt       0/1     ContainerCreating   0          25s
random-shapes-9bb6bdfb8-md7rz       1/1     Running             1          65m
random-shapes-9bb6bdfb8-pppj7       0/1     ContainerCreating   0          25s
Without ignoreDifferences (or without RespectIgnoreDifferences enabled), Argo CD will detect the replica-count drift and scale the Deployment back to the declared replica count.

​
How ignoreDifferences works

ignoreDifferences is a top-level field in the Application spec that tells Argo CD which differences to ignore when computing resource diffs. To ensure those ignored differences are honored during synchronization, enable the RespectIgnoreDifferences sync option. You can specify the following in ignoreDifferences:
  • jsonPointers: JSON Pointer(s) to fields to ignore (e.g., /spec/replicas).
  • jqPathExpressions: JQ-style expressions to ignore fields (useful for ConfigMap .data keys).
  • managedFieldsManagers: ignore changes that originate from specified object managers (e.g., kube-controller-manager).
  • Optional name and namespace to scope the rule to a single resource.
FieldPurposeExample
jsonPointersIgnore explicit JSON paths/spec/replicas
jqPathExpressionsIgnore with JQ-like expressions.data["config.yaml"].auth
managedFieldsManagersIgnore changes by a particular managerkube-controller-manager
name / namespaceScope rule to a single resourcename: random-shapes
ignoreDifferences only affects how Argo CD computes diffs and whether it treats a difference as actionable during sync. It does not change the live Kubernetes resource or stop other controllers (HPA, operators) from managing those fields.

​
Example ignoreDifferences entries

Here are trimmed, relevant examples for common scenarios: 
ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
      - /spec/replicas

  - kind: ConfigMap
    jqPathExpressions:
      - '.data["config.yaml"].auth'

  - group: "*"
    kind: "*"
    managedFieldsManagers:
      - kube-controller-manager
# Optional:
# name: my-deployment
# namespace: my-namespace

​
Enable RespectIgnoreDifferences

To ensure Argo CD honors ignoreDifferences during synchronization, either:
  • Add “RespectIgnoreDifferences=true” to syncPolicy.syncOptions in your Application manifest, or
  • Select the “Respect differences” checkbox in the Argo CD UI sync dialog when performing a manual sync.

​
Example: Application manifest snippet for this demo

This manifest shows automated sync with selfHeal: true and an ignoreDifferences entry that targets the random-shapes Deployment’s /spec/replicas field. RespectIgnoreDifferences is included in syncOptions so automated syncs will honor the ignore rule. 
project: default
source:
  repoURL: http://host.docker.internal:5000/kk-org/gitops-argocd-capa
  path: ./health-check
  targetRevision: HEAD

destination:
  server: https://kubernetes.default.svc
  namespace: health-check

syncPolicy:
  automated:
    prune: true
    selfHeal: true
    enabled: true
  syncOptions:
    - CreateNamespace=true
    - RespectIgnoreDifferences=true

ignoreDifferences:
  - group: apps
    kind: Deployment
    name: random-shapes
    namespace: health-check
    jsonPointers:
      - /spec/replicas

​
UI option: Respect differences

When performing a manual synchronization from the Argo CD UI, you can enable “Respect differences” in the sync panel so Argo CD will honor ignoreDifferences rules during that sync.
A screenshot of the Argo CD web UI showing the "health-check-app" with a resource graph and status indicators (App Health: Degraded, Sync Status: Synced). A synchronization panel on the right lists sync options and the selected resources to synchronize.

​
Demonstration: scale after configuring ignoreDifferences

  1. Ensure the Application contains the ignoreDifferences entry (as shown above) and RespectIgnoreDifferences is enabled.
  2. Scale the Deployment again:
kubectl -n health-check scale deployment random-shapes --replicas=10
# Output:
deployment.apps/random-shapes scaled
  1. After scaling and either manually syncing (with Respect differences enabled) or after an automated sync completes, Argo CD will not revert the replica count for the targeted Deployment because /spec/replicas is ignored for that resource. The pods created by the scale action will remain running.

​
Summary

  • Use ignoreDifferences to tell Argo CD to ignore specific fields, JQ expressions, or managed-field managers when computing diffs and deciding whether to sync.
  • To make Argo CD actually honor those ignore rules during synchronization, enable RespectIgnoreDifferences in syncPolicy.syncOptions or enable “Respect differences” in the UI sync dialog.
  • This pattern is useful for fields controlled externally by HPA or operators (replica counts, dynamic config keys, etc.), preventing Argo CD from continuously reverting externally-managed changes.

Watch Video