Skip to content
Documentation Background

Sync policies and options

A sync applies the manifests rendered from the source to the destination cluster. A newly created Application compares Git with the cluster but changes nothing until a sync runs, so the sync policy decides who or what starts each sync, and sync options decide how each one behaves.


Manual sync is the default. The Application shows how Git differs from the cluster, and nothing is applied until someone asks. That default exists for good reasons:

  • Preview - developers and administrators can inspect the rendered manifests and the diff before anything reaches a live cluster
  • Control - the timing and order of infrastructure changes stay in human hands
  • Compliance - governance rules that forbid automated changes to production are met by default

A manual sync starts from the UI (the Sync button), from the CLI, or by patching the Application resource with kubectl:

Terminal window
argocd app sync <app-name>

Automated sync applies changes as soon as the source differs from the cluster. It also means CI/CD pipelines no longer need access to the Argo CD API: the pipeline commits to the Git repository and Argo CD does the rest.

Enable it with the CLI, with the Enable Auto-Sync button in the UI, or in the manifest:

Terminal window
argocd app set <app-name> --sync-policy automated
spec:
syncPolicy:
automated: {}

Three settings under automated refine the behavior, and all default to off:

SettingEffectCLI flag
pruneDelete live resources that were removed from the source, so nothing orphaned lingers--auto-prune
selfHealRe-apply the source state when the live cluster is changed by hand or by another process--self-heal
allowEmptyAllow a sync that would leave the Application with no resources. Without it, auto-prune refuses, which protects against a mistake that empties the source--allow-empty
spec:
syncPolicy:
automated:
enabled: true # false keeps the settings below but turns auto-sync off
prune: true
selfHeal: true
  • It runs only when the Application is OutOfSync. Applications that are Synced or in an error state do not auto-sync.
  • It attempts one sync per unique combination of commit SHA and application parameters. A sync that already failed against the same commit and parameters is not retried automatically, unless a retry policy is set.
  • With selfHeal, a sync is attempted again after a self-heal timeout, 5 seconds by default, set with the --self-heal-timeout-seconds flag of the application controller.
  • Rollback is not available while automated sync is on. Disable it first.
  • Argo CD checks the source on the interval set by timeout.reconciliation in argocd-cm: 120 seconds by default plus up to 60 seconds of jitter, so a Git change can take up to 3 minutes to be noticed unless a webhook is configured.
  • For an Application generated by an ApplicationSet, editing the Application’s own automated field has no effect. The ApplicationSet owns it.

Transient failures, such as a dependency that is not ready yet, can fail a sync. A retry policy re-runs it with exponential backoff:

spec:
syncPolicy:
retry:
limit: 5 # attempts before the sync is marked Failed, -1 for unlimited
backoff:
duration: 5s # wait before the first retry
factor: 2 # multiplier applied after each failed attempt
maxDuration: 3m # ceiling on the wait between attempts
refresh: true # pick up new revisions while retrying

Sync options change how manifests are applied. They are set in two places:

  • Application level - the spec.syncPolicy.syncOptions list applies to every resource in the Application
  • Resource level - the argocd.argoproj.io/sync-options annotation on a manifest applies to that object only. Multiple options are separated by commas, and a resource-level setting overrides the Application-level one
# Application level
spec:
syncPolicy:
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
- PruneLast=true
# Resource level
metadata:
annotations:
argocd.argoproj.io/sync-options: Prune=false,Validate=false
OptionScopeEffect
CreateNamespace=trueApplicationCreates the destination namespace if it is missing. Without it, a sync into a missing namespace fails. managedNamespaceMetadata adds labels and annotations to the namespace it creates
Validate=falseBothSkips Kubernetes API validation (as with kubectl apply --validate=false)
ApplyOutOfSyncOnly=trueApplicationApplies only resources that are out of sync. It cuts sync time and API server load for large Applications, and hooks still run
ServerSideApply=trueBothApplies with kubectl apply --server-side --force-conflicts. Use it for resources over the 262144-byte annotation limit, for patching resources not fully managed by Argo CD, or to track field ownership. ServerSideApply=false on a resource opts it out
Replace=trueBothUses kubectl replace or create instead of apply. Also solves the annotation size limit, but can recreate resources
Force=trueResourceDeletes and recreates the resource, for example a Job that must run on every sync. Use with Replace=true
Prune=falseBothNever prune the resource, even if it leaves the source. Prune=confirm holds the sync until pruning is approved
Delete=falseBothKeep the resource when the Application is deleted, for example a PersistentVolumeClaim. Delete=confirm requires approval
PruneLast=trueBothPrunes in a final implicit wave, after everything else is applied and healthy
PrunePropagationPolicyApplicationHow pruned resources are garbage-collected: foreground (default), background, or orphan
SkipDryRunOnMissingResource=trueResourceSkips the dry run when the resource’s CRD does not exist yet
FailOnSharedResource=trueApplicationFails the sync if a resource is already managed by another Application
RespectIgnoreDifferences=trueApplicationApplies ignoreDifferences rules during sync, not only when computing status

SkipDryRunOnMissingResource=true is the fix when one sync installs both a CRD and a custom resource of that kind: the dry run for the custom resource fails because the CRD is not registered yet. Pair it with a retry policy so a later attempt succeeds once the CRD exists. RespectIgnoreDifferences is covered in diffing and ignore rules.


SymptomLikely causeFix
A new Application is OutOfSync and nothing deploysManual sync is the defaultSync it, or enable automated sync
A removed manifest still runs in the clusterprune is offEnable prune, or run a manual sync with pruning selected
Auto-sync does not retry after a failureOne attempt is made per commit and parameter setPush a new commit, sync manually, or add a retry policy
Auto-prune refuses to runThe source now renders zero resources and allowEmpty is offConfirm the source is intended to be empty, then set allowEmpty: true
Sync fails because the API cannot find the kind of a custom resourceThe CRD is created in the same syncAdd SkipDryRunOnMissingResource=true on the resource and a retry policy
metadata.annotations: Too longThe resource exceeds the client-side apply annotation limitUse ServerSideApply=true
Rollback is rejectedAutomated sync is enabledDisable automated sync, then roll back