Choosing Between Automatic and Manual Sync Policies in Argo CD

The Drift Dilemma: Automation vs. Control

The primary challenge in GitOps is managing the gap between the desired state (Git) and the actual state (Kubernetes). When a developer pushes a change, you must decide if Argo CD should apply that change immediately or wait for a human operator to trigger the deployment. Choosing the wrong policy leads to either dangerous "ghost" updates that crash production or configuration drift where the cluster state becomes an undocumented mystery.

Comparing Sync Strategies

The decision depends on your environment's risk tolerance and the maturity of your CI pipeline. Use the following table to align your requirements with the supported Argo CD syncPolicy options.

Feature	Manual Sync	Automated Sync	Automated + Self-Heal
Trigger	User-initiated (UI/CLI)	Git Commit / Webhook	Git Commit / Manual Drift
Drift Handling	Ignored until next sync	Detected but not reverted	Automatically reverted
Risk Level	Low (Human Gate)	Medium (Fast Propagation)	High (Potential Loop)
Use Case	Production / High-Risk	Staging / Dev	Strict Compliance / Infrastructure

Trade-offs and Operational Risks

Manual Sync provides a safety buffer. If a commit contains a syntax error or a breaking configuration, the cluster remains stable until a human verifies the change. However, this creates "drift," where the cluster state deviates from Git, making disaster recovery difficult because the Git repository no longer represents the live environment.

Automatic Sync eliminates drift but introduces the risk of rapid failure propagation. When paired with prune: true, Argo CD will delete any resource in the cluster that is not defined in Git. If a file is accidentally deleted from the repository, Argo CD will delete the corresponding live resource immediately.

Self-Healing is a subset of automated sync that monitors the cluster for changes made outside of Git (e.g., via kubectl edit). While this ensures a strict source of truth, it can cause conflict loops. If a Kubernetes Operator or an HPA (Horizontal Pod Autoscaler) modifies a field that Argo CD also manages, the two controllers will fight, repeatedly updating the resource and bloating the audit logs.

Implementation: Configuring the Sync Policy

To implement these policies, you modify the Application Custom Resource Definition (CRD). The following example demonstrates a high-stability configuration for a production environment using automated sync but with a cautious approach to pruning.

# Run this on the cluster where Argo CD is installed
# Required Permissions: cluster-admin or access to the argocd namespace

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com/org/repo.git'
    targetRevision: HEAD
    path: manifests/prod
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: prod-apps
  syncPolicy:
    automated:
      prune: true      # Deletes resources removed from Git
      selfHeal: true    # Reverts manual kubectl changes
    syncOptions:
      - CreateNamespace=true

Validation and Verification

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

• Test Automation: Push a non-breaking change (e.g., a label update) to the Git repository. The Application status in the Argo CD UI should transition from OutOfSync to Synced without manual intervention.
• Test Self-Healing: Run kubectl label deployment production-api drift=true --overwrite. Observe the resource; if selfHeal is active, Argo CD will remove that label within seconds to match Git.
• Test Pruning: Add a temporary ConfigMap to Git, sync it, then delete the file from Git. Verify the ConfigMap is removed from the cluster.

Limitations and Rollback

Sync policies cannot resolve circular dependencies between resources. For ordered deployments, you must use Sync Waves (annotations that define the order of application).

Rollback: To stop an automated sync that is causing instability, remove the automated block from the Application manifest:

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

This reverts the application to Manual Sync, freezing the cluster state until the Git source is corrected.