Cheveo Cheatsheet

ArgoCD OutOfSync Cheatsheet

12 copy-paste patterns. From diagnostic workflow through ignoreDifferences to server-side diff, including common mistakes and quick decisions.

Read the article →

The workflow

1 Diff
2 Status
3 Logs
4 Fix
5 Verify

Diagnostic workflow

1

Show app diff

argocd app diff <app-name>

→ Shows exactly which fields differ between Git and the cluster.

2

Check app status

argocd app get <app-name>

→ Overall status: sync, health, last operation, affected resources.

3

Check controller logs

kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller --tail=50

→ Sync errors, RBAC issues and timeouts not visible in the UI.

ignoreDifferences

4

Ignore server-side defaults

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/template/spec/dnsPolicy
        - /spec/template/spec/schedulerName
        - /spec/revisionHistoryLimit

→ Kubernetes defaults automatically set by the API server.

5

Ignore mutating webhooks (Istio)

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jqPathExpressions:
        - .spec.template.metadata.annotations."sidecar.istio.io/status"
        - .spec.template.spec.initContainers[] | select(.name == "istio-init")
        - .spec.template.spec.containers[] | select(.name == "istio-proxy")

→ Ignore injected sidecar containers and annotations.

6

Global ignoreDifferences (cluster-wide)

# argocd-cm ConfigMap
resource.customizations.ignoreDifferences.apps_Deployment: |
  jsonPointers:
    - /spec/template/spec/dnsPolicy
    - /spec/template/spec/schedulerName

→ From ArgoCD 2.5+: configure once, applies to all Applications.

Fix sync issues

7

Immutable fields (Replace sync)

metadata:
  annotations:
    argocd.argoproj.io/sync-options: Replace=true

→ For fields that cannot be changed after creation (selector, clusterIP).

8

Namespace with sync wave

apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/sync-wave: "-1"

→ Create the namespace before other resources.

9

Remove finalizer

kubectl patch <resource> <name> --type merge -p '{"metadata":{"finalizers":null}}'

→ When a resource is stuck in Terminating and blocks the sync.

Server-side diff & cache

10

Enable server-side diff

# argocd-cm ConfigMap
controller.diff.server.side: "true"

→ Nuclear option: 80% fewer phantom diffs. Requires PATCH permissions.

11

Soft refresh

argocd app get <app-name> --refresh

→ Re-compare without cache invalidation.

12

Hard refresh + repo-server restart

argocd app get <app-name> --hard-refresh
# If the problem persists:
kubectl rollout restart deployment argocd-repo-server -n argocd

→ Fully invalidate cache. Last resort for stale cache issues.

5 most common mistakes

Each one has cost us hours in production at least once.

1

Forgot ignoreDifferences

Server-side defaults cause phantom diffs leading to sync loops

2

helm template instead of helm install

ArgoCD uses client-side rendering: lookup and .Capabilities are missing

3

Namespace not in manifest

ArgoCD does not create namespaces automatically

4

Auto-sync without ignoreDifferences

Constant re-sync caused by webhooks or defaults

5

Stale cache not recognized

Hard refresh fixes the problem temporarily, cache goes stale again

Quick decisions

Only default fields in diff
→ ignoreDifferences (pattern 4-6)
field is immutable
→ Replace sync (pattern 7)
namespace not found
→ Sync wave (pattern 8)
Sync loop every 3 min
→ Server-side diff (pattern 10)
ComparisonError
→ Check repo credentials
2-Day Hands-on Workshop

GitOps with ArgoCD - from push to production deploy

From the App-of-Apps pattern to progressive delivery: everything you need for GitOps in production.

View workshop details
Contact Book a Call