ArgoCD shows resources as out of sync when the cluster state drifts from the Git repository. This occurs due to auto-generated values, mutating webhooks, or resource normalization. Use ignoreDifferences, sync options, or enable auto-healing to resolve drift issues.
Fixes ArgoCD out of sync
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
spec:
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/template/spec/containers/0/imageapiVersion: argoproj.io/v1alpha1kind: Applicationmetadata:name: my-appspec:ignoreDifferences:- group: appskind: DeploymentjsonPointers:- /spec/template/spec/containers/0/imageArgoCD out of sync
In ArgoCD, the "out of sync" status indicates that the Kubernetes cluster state no longer matches the desired state defined in your Git repository. This drift can happen when a controller or webhook modifies resources after they are applied, when Kubernetes normalizes resource values, or when Helm charts generate unique values on each template invocation. ArgoCD continuously detects these differences and reports the application as out of sync, preventing automated deployment workflows from proceeding.
Open the ArgoCD UI, select your application, and view the Diff tab to see which fields are causing the out of sync status. This helps identify the exact differences between Git and cluster state.
Check the ArgoCD application controller logs for detailed information about what resources are drifting. Use: kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller | grep <app-name>
If the drift is expected and harmless, configure ignoreDifferences in your Application manifest:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
spec:
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/template/spec/containers/0/imageIf using Helm, remove or conditionally disable functions that auto-generate values. Replace functions like {{ randAlphaNum 10 }} with fixed values or externalized parameters that are controlled via values.yaml.
Add sync options to your Application to use Replace strategy instead of Apply:
spec:
syncPolicy:
syncOptions:
- RespectIgnoreDifferences=true
- Replace=trueConfigure automatic synchronization to continuously fix drift:
spec:
syncPolicy:
automated:
prune: true
selfHeal: trueConfigure resource customizations in the argocd-cm ConfigMap to ignore specific fields globally:
resource.customizations.ignoreDifferences.all: |
jsonPointers:
- /spec/template/spec/containers/0/imageAs a last resort, force sync to reset the application:
argocd app sync <app-name> --forceFor production environments, prefer ignoreDifferences over force sync as it acknowledges expected drift rather than blindly resetting state. If using service mesh (Istio, Linkerd), sidecar injection often causes false positives in diff detection - configure ignoreDifferences for injected fields. Consider using Kustomize or Helm with explicit value overrides rather than auto-generation functions for predictable deployments. Monitor sync frequency as continuous drift indicates deeper configuration issues.