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
Section titled “Manual sync”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:
argocd app sync <app-name>Automated sync
Section titled “Automated sync”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:
argocd app set <app-name> --sync-policy automatedspec: syncPolicy: automated: {}Three settings under automated refine the behavior, and all default to off:
| Setting | Effect | CLI flag |
|---|---|---|
prune | Delete live resources that were removed from the source, so nothing orphaned lingers | --auto-prune |
selfHeal | Re-apply the source state when the live cluster is changed by hand or by another process | --self-heal |
allowEmpty | Allow 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: trueHow automated sync behaves
Section titled “How automated sync behaves”- It runs only when the Application is
OutOfSync. Applications that areSyncedor 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-secondsflag 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.reconciliationinargocd-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
automatedfield 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 retryingSync options
Section titled “Sync options”Sync options change how manifests are applied. They are set in two places:
- Application level - the
spec.syncPolicy.syncOptionslist applies to every resource in the Application - Resource level - the
argocd.argoproj.io/sync-optionsannotation 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 levelspec: syncPolicy: syncOptions: - CreateNamespace=true - ServerSideApply=true - PruneLast=true# Resource levelmetadata: annotations: argocd.argoproj.io/sync-options: Prune=false,Validate=false| Option | Scope | Effect |
|---|---|---|
CreateNamespace=true | Application | Creates 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=false | Both | Skips Kubernetes API validation (as with kubectl apply --validate=false) |
ApplyOutOfSyncOnly=true | Application | Applies only resources that are out of sync. It cuts sync time and API server load for large Applications, and hooks still run |
ServerSideApply=true | Both | Applies 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=true | Both | Uses kubectl replace or create instead of apply. Also solves the annotation size limit, but can recreate resources |
Force=true | Resource | Deletes and recreates the resource, for example a Job that must run on every sync. Use with Replace=true |
Prune=false | Both | Never prune the resource, even if it leaves the source. Prune=confirm holds the sync until pruning is approved |
Delete=false | Both | Keep the resource when the Application is deleted, for example a PersistentVolumeClaim. Delete=confirm requires approval |
PruneLast=true | Both | Prunes in a final implicit wave, after everything else is applied and healthy |
PrunePropagationPolicy | Application | How pruned resources are garbage-collected: foreground (default), background, or orphan |
SkipDryRunOnMissingResource=true | Resource | Skips the dry run when the resource’s CRD does not exist yet |
FailOnSharedResource=true | Application | Fails the sync if a resource is already managed by another Application |
RespectIgnoreDifferences=true | Application | Applies 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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
A new Application is OutOfSync and nothing deploys | Manual sync is the default | Sync it, or enable automated sync |
| A removed manifest still runs in the cluster | prune is off | Enable prune, or run a manual sync with pruning selected |
| Auto-sync does not retry after a failure | One attempt is made per commit and parameter set | Push a new commit, sync manually, or add a retry policy |
| Auto-prune refuses to run | The source now renders zero resources and allowEmpty is off | Confirm the source is intended to be empty, then set allowEmpty: true |
| Sync fails because the API cannot find the kind of a custom resource | The CRD is created in the same sync | Add SkipDryRunOnMissingResource=true on the resource and a retry policy |
metadata.annotations: Too long | The resource exceeds the client-side apply annotation limit | Use ServerSideApply=true |
| Rollback is rejected | Automated sync is enabled | Disable automated sync, then roll back |