Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Sync and Health

Argo CD Sync Policies: Automated Sync, Prune, Self-Heal and Retry

Decide between manual and automated sync in Argo CD, and learn what prune, self-heal, allowEmpty and retry with backoff really do, with a simulator and guidance on safe defaults per environment.

Sync is the moment Argo CD writes to your cluster. By default it never does so on its own: the Application shows OutOfSync and waits for a person to press Sync. The syncPolicy block changes that. It decides when Argo CD syncs, what it is allowed to delete and how it recovers from failure. Getting these four dials right is the difference between a calm GitOps setup and a surprising one.

The YAML is real Argo CD configuration, read-only on this site. The runnable code is a stand-in simulator of the policy decisions, not Argo CD itself.

Manual versus automated

With manual sync (no automated block) Argo CD reports differences and waits. It suits production changes that need a human click, or a change window.

With automated sync Argo CD syncs whenever it finds the Application OutOfSync because of a new Git revision:

YAML
spec:
  syncPolicy:
    automated: {}

Two safeguards are built in. Automated sync does not retry an attempt for the same commit and parameters if that exact sync already failed (use retry for that), and it does not run while you are viewing a rollback.

Prune

When a manifest is removed from Git, the corresponding live resource is not deleted by default; it shows as "requires pruning". This protects against an accidental deletion removing production data.

YAML
syncPolicy:
  automated:
    prune: true

With prune: true, automated sync deletes live resources that no longer exist in Git. Without it, you can still prune manually (argocd app sync <name> --prune) or from the UI. Individual resources can opt out:

YAML
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=false

Pruning a PersistentVolumeClaim or a database custom resource can destroy data. Add Prune=false (and often Delete=false) to resources whose loss would hurt, even in apps where pruning is otherwise on.

Self-heal

By default automated sync reacts only to Git changes. If someone edits the live cluster by hand, the Application becomes OutOfSync but nothing reverts it. Enable self-heal to revert such manual changes:

YAML
syncPolicy:
  automated:
    prune: true
    selfHeal: true

Now kubectl scale on a managed Deployment is undone within seconds. Self-heal makes Git truly authoritative, but remember it will also fight any other controller that edits managed fields (see The Reconciliation Loop and Health Checks and Diffing).

allowEmpty

If a sync would delete every resource of an Application (an empty path, a broken render, a wrong directory), Argo CD refuses by default, as a safety net. allowEmpty: true removes that protection; use it only for deliberately empty apps.

Retry with backoff

Syncs can fail transiently: a CRD not yet registered, an admission webhook starting up, a rate-limited API. Add retries:

YAML
syncPolicy:
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

Waits grow 5 s, 10 s, 20 s, 40 s, 80 s, capped at three minutes. A limit of -1 retries forever; a limit of 0 or none disables retries.

Stand-in: what will this policy do?

Choose a policy and a scenario. The model answers whether Argo CD will act.

JS Stand-in: policy simulator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: retry timeline

Print the wait before each retry for any backoff settings.

JS Stand-in: retry backoff

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Which policy where?

Environment Suggested policy Why
Dev / preview automated + prune + selfHeal Fast feedback, throwaway data
Staging automated + selfHeal (prune optional) Mirror production but keep speed
Production Manual sync, or automated with sync windows and prune only after care Human control for risky changes
Platform add-ons Automated, Prune=false on stateful kinds Stable but protected

Many teams run production with automated sync and branch protection: the human gate is the pull request review, so a second click would be redundant.

Disabling auto-sync temporarily

While debugging in the cluster, switch automation off so Argo CD does not fight you: argocd app set <name> --sync-policy none, then restore it (or let Git re-apply it; if the Application manifest is itself in Git, the self-heal of the parent app will put the policy back, which is a feature).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A resource is deleted from Git. Automated sync is on without prune. What happens to the live resource?

    Without prune: true, Argo CD never deletes resources automatically.
  2. 2. What does selfHeal add to automated sync?

    Self-heal reacts to live drift, not just Git changes.
  3. 3. Why does allowEmpty default to false?

    A wrong path or broken render could otherwise wipe the whole app.
  4. 4. With duration 5s, factor 2 and maxDuration 3m, what is the wait before the 4th retry?

    Waits are 5, 10, 20, 40 seconds, so the 4th retry waits 40 seconds.

Summary

  • Manual sync waits for a person; automated syncs on Git changes.
  • prune deletes resources removed from Git; protect important ones with Prune=false.
  • selfHeal reverts live edits; beware of fights with autoscalers.
  • allowEmpty is a safety net that is off by default; retry adds exponential backoff.
  • Match the policy to the environment's risk.

Next: Sync Options and Waves