Sync Options

Configure how Argo CD syncs application resources with advanced sync options

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: [e-mail]
    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