Argo CD OutOfSync: Diff Before You Sync

The dashboard shows yellow:

Sync Status:  OutOfSync
Health:       Healthy

Pods are running. Traffic is fine. On-call still gets paged.

OutOfSync is a GitOps signal, not an outage. Something in the cluster differs from the commit Argo CD expects.

---

Diff drives the decision

argocd app diff shop-api
# or: kubectl describe application shop-api -n argocd

Typical causes:

• Manual kubectl scale or kubectl edit with selfHeal enabled (Argo reverts your fix)
• HPA or controller-owned fields that Git does not manage — need ignoreDifferences
• Wrong source.path or stale targetRevision (ComparisonError, not OutOfSync)
• Sync error from quota/RBAC — Argo is the messenger, not the root cause

Do not sync --force until you know which fields drifted.

---

Synced but Degraded

If sync status is Synced and health is Degraded, Git matches cluster spec — workloads are unhealthy. More syncs will not fix CrashLoop pods.

Switch to kubectl: describe pod, logs, events. Fix the manifest in Git.

---

ComparisonError is render-time

When Argo cannot kustomize build or helm template the repo:

• Fix Git at the referenced revision
• Check repo-server logs
• Reproduce kustomize build / helm template locally on the same ref

Sync never reaches the cluster until render succeeds.

---

Train GitOps reflexes

The Argo CD & GitOps path covers OutOfSync, sync failures, auto-sync revert, rollback vs fix-forward, and hook stalls.

Part of the Platform & Policy Pack — four platform topics, 16 scenarios each, three exam sprints per topic.