> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```yaml theme={null}
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:

```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    argocd.argoproj.io/sync-options: Prune=false,Delete=false
spec:
  # ... service spec
```

<Note>
  Multiple sync options in annotations should be comma-separated. Whitespace is automatically trimmed.
</Note>

## Pruning Options

### No Prune Resources

Prevent Argo CD from deleting a resource when it's removed from Git:

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=false
```

<Info>
  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](https://argo-cd.readthedocs.io/en/stable/user-guide/compare-options/).
</Info>

### Prune with Confirmation

Require manual confirmation before pruning critical resources:

```yaml theme={null}
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:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
    - PruneLast=true
```

Also works at the resource level:

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: PruneLast=true
```

### Prune Propagation Policy

Control how pruned resources are deleted:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
    - PrunePropagationPolicy=foreground
```

<ParamField path="PrunePropagationPolicy" type="enum">
  * `foreground` (default): Delete dependents before the owner
  * `background`: Delete owner immediately, dependents asynchronously
  * `orphan`: Leave dependents, only delete the owner
</ParamField>

See [Kubernetes Garbage Collection](https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/) for details.

## Deletion Options

### No Resource Deletion

Retain resources even when the application is deleted (useful for PVCs):

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Delete=false
```

### Delete with Confirmation

Require confirmation before deleting critical resources:

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Delete=confirm
```

## Validation Options

### Disable Kubectl Validation

Skip validation for resources using `RawExtension` (e.g., ServiceCatalog):

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Validate=false
```

Application-level:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - Validate=false
```

### Skip Dry Run on Missing Resources

Skip dry run when CRD doesn't exist yet (e.g., Gatekeeper):

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
```

Application-level:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - SkipDryRunOnMissingResource=true
```

## Apply Strategy Options

### Replace Resource

Use `kubectl replace` instead of `kubectl apply`:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - Replace=true
```

Resource-level:

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Replace=true
```

<Warning>
  Replace is destructive and may recreate resources, causing application downtime.
</Warning>

### Force Sync

Delete and recreate resources during sync (useful for Jobs):

```yaml theme={null}
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Force=true,Replace=true
```

<Warning>
  Force sync deletes resources before recreating them, which will cause downtime.
</Warning>

### Server-Side Apply

Use Kubernetes server-side apply:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - ServerSideApply=true
```

Resource-level:

```yaml theme={null}
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:**

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
```

With sync options:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - ServerSideApply=true
    - Validate=false  # Required for partial manifests
```

<Note>
  `Replace=true` takes precedence over `ServerSideApply=true`.
</Note>

### Client-Side Apply Migration

Migrate from client-side to server-side apply:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - ClientSideApplyMigration=false  # Disable if needed
```

Custom field manager:

```yaml theme={null}
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):

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - ApplyOutOfSyncOnly=true
```

Or via CLI:

```bash theme={null}
argocd app set guestbook --sync-option ApplyOutOfSyncOnly=true
```

## Namespace Management

### Create Namespace

Automatically create the destination namespace if it doesn't exist:

```yaml theme={null}
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:

```yaml theme={null}
spec:
  syncPolicy:
    managedNamespaceMetadata:
      labels:
        environment: production
        team: platform
      annotations:
        owner: platform-team@example.com
    syncOptions:
    - CreateNamespace=true
```

<Info>
  `managedNamespaceMetadata` only works when `CreateNamespace=true` is set.
</Info>

**Making Argo CD own the namespace:**

```yaml theme={null}
managedNamespaceMetadata:
  annotations:
    argocd.argoproj.io/tracking-id: "your-application-name:/Namespace:/your-namespace-name"
```

<Warning>
  Manually adding tracking annotations to namespaces should only be done for owned namespaces. Incorrect ownership can lead to unintended deletion of shared namespaces.
</Warning>

## Advanced Options

### Fail on Shared Resource

Fail sync if a resource is already managed by another application:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
    - FailOnSharedResource=true
```

### Respect Ignore Differences

Apply `ignoreDifferences` configuration during sync (not just diff):

```yaml theme={null}
spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/replicas
  
  syncPolicy:
    syncOptions:
    - RespectIgnoreDifferences=true
```

<Note>
  `RespectIgnoreDifferences` only works for resources that already exist in the cluster. New resources are applied as-is.
</Note>

## Complete Example

Application with multiple sync options:

```yaml theme={null}
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:

```yaml theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Sync Waves" icon="wave-pulse" href="/applications/sync-waves">
    Control resource ordering with sync waves
  </Card>

  <Card title="Resource Hooks" icon="hook" href="/applications/resource-hooks">
    Run jobs at specific sync phases
  </Card>

  <Card title="Health Checks" icon="heart-pulse" href="/applications/health-checks">
    Configure custom health assessments
  </Card>

  <Card title="Tracking Strategies" icon="radar" href="/applications/tracking-strategies">
    Choose how Argo CD tracks resources
  </Card>
</CardGroup>