The reconcile loop & drift

How Argo detects and corrects.

Advanced12 min · lesson 4 of 12

Under the hood Argo CD runs a reconcile loop, the same pattern that powers Kubernetes controllers and Crossplane. On an interval (and on Git webhook events) it fetches the desired manifests from Git, renders them (running Helm/Kustomize if needed), compares against the live cluster, and reports or corrects the difference. Because it reconciles continuously, it does not just deploy once — it keeps the cluster converged to Git indefinitely, which is what makes drift visible and (optionally) self-correcting.

One reconcile pass

1fetch

manifests from Git

2render

Helm/Kustomize if any

3diff

desired vs live

4report/correct

OutOfSync, or sync

Runs on an interval and on webhooks. Continuous reconciliation is why drift surfaces and self-heal can fix it.

Drift, visible and correctable

Drift is when the live cluster diverges from Git — someone kubectl-edited a Deployment, or a controller changed something. Argo CD surfaces drift as OutOfSync with a diff, so it is never silent. What happens next depends on policy: with self-heal off, you see the drift and decide; with self-heal on, Argo CD reverts the change back to Git automatically. Either way, Git remains the declared truth and the cluster is measured against it continuously.

Continuous reconcile fights manual changes — by design

Because Argo CD constantly compares against Git, an out-of-band kubectl edit shows up as drift and, if self-heal is on, gets reverted on the next pass. That is the intended behavior, but it surprises people who “quick-fix” prod by hand and watch it revert. Make changes through Git; if you must intervene live, understand that Argo CD will reconcile it away unless you also change Git (or pause the app deliberately).

Sync, health & statusSync policies & self-heal