Choosing the Right Argo CD Sync Policy: Automated vs. Manual Reconciliation

The Reconciliation Dilemma

When deploying applications via Argo CD, the primary operational decision is how the controller handles the gap between the desired state (Git) and the live state (Kubernetes). Choosing the wrong sync policy can lead to either "configuration drift," where the cluster deviates from the source of truth, or "destructive automation," where a Git commit accidentally deletes production resources.

The goal is to balance velocity and safety based on the environment's criticality. In ephemeral or development environments, automation is preferred to reduce overhead. In production, manual gates provide a final sanity check and an audit trail for changes.

Comparing Sync Policy Options

The sync policy is defined within the syncPolicy field of the Argo CD Application manifest. The following table compares the two primary operational modes.

Feature	Manual Sync	Automated Sync (with Prune/Self-Heal)
Default Behavior	Detects drift; waits for user trigger.	Automatically applies Git changes to cluster.
Drift Correction	Manual intervention required.	selfHeal reverts manual cluster changes.
Resource Cleanup	Manual deletion of orphaned resources.	prune deletes resources removed from Git.
Typical Use Case	Production, High-Compliance environments.	Dev/QA, Ephemeral environments, CI/CD pipelines.

Operational Trade-offs

Automated Sync: The Velocity Path

Automated sync removes the human bottleneck. When selfHeal is enabled, Argo CD continuously monitors the live state; if a developer manually edits a deployment via kubectl edit, Argo CD will overwrite those changes with the Git version almost immediately. This ensures the cluster is a mirror of the repository.

The Risk: The prune option is powerful. If a resource is accidentally deleted from a Git folder or a Kustomize overlay is misconfigured, Argo CD will delete the corresponding live resource. Without careful labeling and namespace isolation, this can lead to unintended downtime.

Manual Sync: The Control Path

Manual sync treats Git as a proposal. Argo CD will mark the application as OutOfSync when Git changes, but it will not apply them until a user triggers the sync. This allows for "canary-style" manual verification or coordination with external maintenance windows.

The Risk: This increases operational toil. Over time, clusters often suffer from "drift" where the live state is significantly different from Git, making it difficult to recover the environment from scratch during a disaster recovery event.

Implementation and Validation

The following example demonstrates an Automated sync policy. This configuration assumes Argo CD v2.0 or later, as the selfHeal field is not supported in older versions.

# app-manifest.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook-automated
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Applying and Verifying the Policy

Run the following command with cluster-admin permissions to apply the manifest:

kubectl apply -f app-manifest.yaml

To verify the policy is functioning as intended, perform these checks:

• Check Sync Status: Run argocd app get guestbook-automated. The status should show Synced and Healthy.
• Test Self-Heal: Manually scale a deployment in the guestbook namespace using kubectl scale deployment <name> --replicas=1. Observe the Argo CD UI or CLI; the application should briefly show OutOfSync and then automatically return to Synced as the controller reverts the scale change.
• Test Pruning: Remove a resource file from the Git repository and push the change. The resource should be automatically deleted from the cluster.

Rollback Procedure

If automated pruning causes unintended deletions, immediately disable the automated policy to prevent further changes:

kubectl patch app guestbook-automated -n argocd --type merge -p '{"spec":{"syncPolicy":null}}'

Limitations

Sync policies apply to the entire Application. You cannot currently set prune: true for some resources and prune: false for others within a single Argo CD Application object. For granular control, split resources into multiple Applications or use ignoreDifferences in the Application spec to prevent specific fields from triggering a sync event.