Skip to main content
Sync options allow you to customize how Argo CD syncs the desired state to the target cluster. They can be configured at the application level in spec.syncPolicy.syncOptions or at the resource level using the argocd.argoproj.io/sync-options annotation.

​
Application-Level Configuration

Define sync options in the Application manifest: 
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
    - CreateNamespace=true
    - PruneLast=true
    - ServerSideApply=true

​
Resource-Level Configuration

Apply sync options to individual resources using annotations: 
apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    argocd.argoproj.io/sync-options: Prune=false,Delete=false
spec:
  # ... service spec
Multiple sync options in annotations should be comma-separated. Whitespace is automatically trimmed.

​
Pruning Options

​
No Prune Resources

Prevent Argo CD from deleting a resource when it’s removed from Git: 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=false
When a resource has Prune=false, the application will show as OutOfSync if Argo CD expects the resource to be pruned. Consider combining this with compare options.

​
Prune with Confirmation

Require manual confirmation before pruning critical resources: 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=confirm
Confirm pruning by:
  • Using the UI “Confirm Pruning” button
  • Using the CLI
  • Adding the annotation: argocd.argoproj.io/deletion-approved: <ISO timestamp>

​
Prune Last

Defer pruning until after all other resources are deployed and healthy: 
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
    - PruneLast=true
Also works at the resource level: 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: PruneLast=true

​
Prune Propagation Policy

Control how pruned resources are deleted: 
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
    - PrunePropagationPolicy=foreground
​
PrunePropagationPolicy
enum
  • foreground (default): Delete dependents before the owner
  • background: Delete owner immediately, dependents asynchronously
  • orphan: Leave dependents, only delete the owner
See Kubernetes Garbage Collection for details.

​
Deletion Options

​
No Resource Deletion

Retain resources even when the application is deleted (useful for PVCs): 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Delete=false

​
Delete with Confirmation

Require confirmation before deleting critical resources: 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Delete=confirm

​
Validation Options

​
Disable Kubectl Validation

Skip validation for resources using RawExtension (e.g., ServiceCatalog): 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Validate=false
Application-level: 
spec:
  syncPolicy:
    syncOptions:
    - Validate=false

​
Skip Dry Run on Missing Resources

Skip dry run when CRD doesn’t exist yet (e.g., Gatekeeper): 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
Application-level: 
spec:
  syncPolicy:
    syncOptions:
    - SkipDryRunOnMissingResource=true

​
Apply Strategy Options

​
Replace Resource

Use kubectl replace instead of kubectl apply: 
spec:
  syncPolicy:
    syncOptions:
    - Replace=true
Resource-level: 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Replace=true
Replace is destructive and may recreate resources, causing application downtime.

​
Force Sync

Delete and recreate resources during sync (useful for Jobs): 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Force=true,Replace=true
Force sync deletes resources before recreating them, which will cause downtime.

​
Server-Side Apply

Use Kubernetes server-side apply: 
spec:
  syncPolicy:
    syncOptions:
    - ServerSideApply=true
Resource-level: 
metadata:
  annotations:
    argocd.argoproj.io/sync-options: ServerSideApply=true
Benefits:
  • No annotation size limit (avoids 262KB last-applied-configuration limit)
  • Better for patching resources not fully managed by Argo CD
  • More declarative field management
Usage with partial manifests: 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
With sync options: 
spec:
  syncPolicy:
    syncOptions:
    - ServerSideApply=true
    - Validate=false  # Required for partial manifests
Replace=true takes precedence over ServerSideApply=true.

​
Client-Side Apply Migration

Migrate from client-side to server-side apply: 
spec:
  syncPolicy:
    syncOptions:
    - ClientSideApplyMigration=false  # Disable if needed
Custom field manager: 
metadata:
  annotations:
    argocd.argoproj.io/client-side-apply-migration-manager: "my-custom-manager"

​
Selective Sync

Sync only out-of-sync resources (improves performance for large applications): 
spec:
  syncPolicy:
    syncOptions:
    - ApplyOutOfSyncOnly=true
Or via CLI: 
argocd app set guestbook --sync-option ApplyOutOfSyncOnly=true

​
Namespace Management

​
Create Namespace

Automatically create the destination namespace if it doesn’t exist: 
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  destination:
    server: https://kubernetes.default.svc
    namespace: some-namespace
  syncPolicy:
    syncOptions:
    - CreateNamespace=true

​
Managed Namespace Metadata

Set labels and annotations on the created namespace: 
spec:
  syncPolicy:
    managedNamespaceMetadata:
      labels:
        environment: production
        team: platform
      annotations:
        owner: platform-team@example.com
    syncOptions:
    - CreateNamespace=true
managedNamespaceMetadata only works when CreateNamespace=true is set.
Making Argo CD own the namespace: 
managedNamespaceMetadata:
  annotations:
    argocd.argoproj.io/tracking-id: "your-application-name:/Namespace:/your-namespace-name"
Manually adding tracking annotations to namespaces should only be done for owned namespaces. Incorrect ownership can lead to unintended deletion of shared namespaces.

​
Advanced Options

​
Fail on Shared Resource

Fail sync if a resource is already managed by another application: 
spec:
  syncPolicy:
    syncOptions:
    - FailOnSharedResource=true

​
Respect Ignore Differences

Apply ignoreDifferences configuration during sync (not just diff): 
spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/replicas
  
  syncPolicy:
    syncOptions:
    - RespectIgnoreDifferences=true
RespectIgnoreDifferences only works for resources that already exist in the cluster. New resources are applied as-is.

​
Complete Example

Application with multiple sync options: 
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-app
  namespace: argocd
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  
  source:
    repoURL: https://github.com/example/app.git
    targetRevision: HEAD
    path: manifests
  
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  
  syncPolicy:
    automated:
      enabled: true
      prune: true
      selfHeal: true
    
    syncOptions:
    - CreateNamespace=true
    - PruneLast=true
    - ApplyOutOfSyncOnly=true
    - ServerSideApply=true
    - RespectIgnoreDifferences=true
    
    managedNamespaceMetadata:
      labels:
        environment: production
      annotations:
        owner: platform-team
  
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/replicas

​
Combining Options

Some sync options work well together: 
# Partial resource updates
syncOptions:
- ServerSideApply=true
- Validate=false

# Safe automated sync
syncOptions:
- PruneLast=true
- ApplyOutOfSyncOnly=true

# Force recreate with replace
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Force=true,Replace=true

​
Next Steps

Sync Waves

Control resource ordering with sync waves

Resource Hooks

Run jobs at specific sync phases

Health Checks

Configure custom health assessments

Tracking Strategies

Choose how Argo CD tracks resources