Sync Strategies

Auto-sync, manual sync, sync waves, and advanced synchronization options

Argo CD provides flexible synchronization strategies to control when and how applications are deployed to your clusters.

Manual Sync

By default, applications require manual synchronization. When changes are detected in Git, you must explicitly trigger a sync operation.

# Sync application
argocd app sync myapp

# Sync with pruning
argocd app sync myapp --prune

# Force sync (recreate resources)
argocd app sync myapp --force

Automated Sync Policy

Argo CD can automatically sync applications when it detects differences between the desired manifests in Git and the live state in the cluster.

Enabling Auto-Sync

Application Manifest

spec:
  syncPolicy:
    automated: {}

Auto-Sync with Enabled Flag

You can explicitly control automated sync using the enabled field:

spec:
  syncPolicy:
    automated:
      enabled: true  # or false to disable

Setting spec.syncPolicy.automated.enabled to null is treated as enabled. When set to false, the controller will skip automated sync even if prune, selfHeal, and allowEmpty are configured.

Automatic Pruning

By default, automated sync will not delete resources when they are removed from Git. Enable automatic pruning to delete resources:

spec:
  syncPolicy:
    automated:
      prune: true

Automatic pruning will delete resources from your cluster when they’re removed from Git. Use with caution.

Allow Empty Resources

Prevents errors when there are no target resources:

spec:
  syncPolicy:
    automated:
      prune: true
      allowEmpty: true

Automatic Self-Healing

When enabled, Argo CD will automatically revert manual changes made to the live cluster:

spec:
  syncPolicy:
    automated:
      selfHeal: true

By default, changes made to the live cluster will not trigger automated sync. Self-heal ensures your cluster state always matches Git.

Disabling self-heal does not guarantee that live cluster changes will persist in multi-source applications. Changes in one source can trigger autosync even if another remains unchanged.

Sync Options

Fine-tune sync behavior with sync options:

spec:
  syncPolicy:
    syncOptions:
      # Disable kubectl validation
      - Validate=false
      
      # Create namespace if it doesn't exist
      - CreateNamespace=true
      
      # Set prune propagation policy
      - PrunePropagationPolicy=foreground  # or background, orphan
      
      # Prune resources as final wave
      - PruneLast=true
      
      # Respect ignoreDifferences during sync
      - RespectIgnoreDifferences=true
      
      # Only sync out-of-sync resources
      - ApplyOutOfSyncOnly=true
      
      # Use kubectl replace instead of apply
      - Replace=true
      
      # Skip dry run on missing resources
      - SkipDryRunOnMissingResource=true

Managed Namespace Metadata

When using CreateNamespace=true, you can set metadata on the namespace:

spec:
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
    managedNamespaceMetadata:
      labels:
        environment: production
        team: platform
      annotations:
        monitoring: enabled

Sync Waves

Sync waves allow you to control the order in which resources are applied using the argocd.argoproj.io/sync-wave annotation.

How Waves Work

1. Resources are ordered

   All resources are ordered by their wave number (lowest to highest)

2. Sequential application

   Resources in each wave are applied sequentially

3. Health check

   Argo CD waits for all resources in a wave to be healthy before proceeding

Wave Examples

Wave -1: Database Migration

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/sync-wave: "-1"
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: flyway:latest
          # migration command

Wave 0: ConfigMaps and Secrets (default)

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  # No annotation = wave 0
data:
  config.yaml: |
    # configuration

Wave 1: Deployments

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  annotations:
    argocd.argoproj.io/sync-wave: "1"
spec:
  # deployment spec

Wave 2: Services

apiVersion: v1
kind: Service
metadata:
  name: backend-service
  annotations:
    argocd.argoproj.io/sync-wave: "2"
spec:
  # service spec

Waves are assigned to wave 0 by default. Waves can be negative, allowing you to create resources that run before everything else.

Sync Phases (Hooks)

Hooks allow you to run resources at specific points in the sync lifecycle:

Hook Type	Description
PreSync	Executes before the application of manifests
Sync	Executes at the same time as manifest application
PostSync	Executes after all resources are healthy
SyncFail	Executes when the sync operation fails
Skip	Skips the resource during sync
PreDelete	Executes before Application deletion
PostDelete	Executes after Application resources are deleted

Hook Example

apiVersion: batch/v1
kind: Job
metadata:
  name: post-deploy-notification
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: notify
          image: curlimages/curl
          command:
            - curl
            - '-X'
            - POST
            - 'https://hooks.slack.com/services/...'
      restartPolicy: Never

Hook Deletion Policies

Policy	Description
HookSucceeded	Delete after successful execution
HookFailed	Delete after failed execution
BeforeHookCreation	Delete existing hook before creating new one

Combining Waves and Hooks

You can combine sync waves with hooks for fine-grained control:

apiVersion: batch/v1
kind: Job
metadata:
  name: db-schema-update
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "-1"
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  # Job spec

Argo CD orders resources by:

1. Phase (PreSync, Sync, PostSync)
2. Wave (lowest to highest)
3. Kind (namespaces first, then other resources)
4. Name (alphabetically)

Retry Policy

Configure automatic retry on sync failure:

spec:
  syncPolicy:
    retry:
      limit: 5  # Number of retry attempts
      backoff:
        duration: 5s      # Initial backoff duration
        factor: 2         # Multiplier for each retry
        maxDuration: 3m   # Maximum backoff duration

Refresh on Retry

Automatically refresh application on new revisions during retries:

spec:
  syncPolicy:
    retry:
      refresh: true

Automated Sync Semantics

When does automated sync trigger?

• Only when the application is OutOfSync
• Applications in Synced or error states will not auto-sync
• One sync per unique combination of commit SHA and parameters
• Will not retry if a previous sync failed for the same commit

Self-heal behavior

• When selfHeal: true, sync will retry after self-heal timeout (default: 5 seconds)
• Timeout is controlled by --self-heal-timeout-seconds flag

Sync frequency

• Determined by timeout.reconciliation in argocd-cm ConfigMap
• Default: 120 seconds with 60 seconds jitter (max 3 minutes)

Limitations

• Rollback cannot be performed on applications with automated sync enabled

ApplicationSet Auto-Sync Toggle

For ApplicationSet-managed applications, toggling auto-sync requires special handling. See the ApplicationSet documentation for details on controlling resource modification.

Related Resources

• Sync Phases and Waves Documentation
• Resource Hooks
• Sync Options