What is an ArgoCD Application and how do sync policies work?

Imagine an ArgoCD Application as a contract between a landlord and a tenant. The contract specifies exactly what the apartment should look like (Git source), which building and unit it applies to (destination cluster and namespace), and the rules for maintenance (sync policy). The sync policy is like the maintenance clause — it determines whether the landlord can enter and fix things automatically when the tenant makes unauthorized modifications, or whether the landlord must first get approval before making any changes. Just as different tenants may have different maintenance agreements, different applications can have different sync policies depending on their criticality.

The Application custom resource is the fundamental building block of ArgoCD. It encapsulates four key pieces of information: the source (a Git repository URL, revision, and path), the destination (a cluster API server endpoint and namespace), the project (which governs RBAC and allowed resources), and the sync policy (which defines automation behavior). When ArgoCD processes an Application, it renders the manifests from the source using the detected or configured tool — Helm, Kustomize, or directory of plain YAML — and compares the rendered output against the live state in the destination cluster. The comparison result is the sync status, which can be Synced, OutOfSync, or Unknown.

Sync policies control the automation level through three primary mechanisms. First, automated sync enables ArgoCD to apply changes without human intervention whenever it detects that Git has diverged from the cluster state. Second, the prune option within automated sync controls whether ArgoCD deletes Kubernetes resources that were removed from Git; without prune enabled, ArgoCD will only create and update resources but never delete them, leading to orphaned objects. Third, selfHeal instructs ArgoCD to revert any manual changes made directly to the cluster, effectively enforcing Git as the immutable source of truth. Additionally, syncOptions provide granular control such as CreateNamespace, ApplyOutOfSyncOnly, ServerSideApply, and Replace, each addressing specific deployment scenarios.

In production environments, teams typically use automated sync with prune and selfHeal for non-critical services like internal tools and staging environments, while keeping manual sync for production-critical services like the payments-api or order-service to maintain a human approval gate. Sync windows add another layer of control by restricting when automatic syncs can occur — for example, blocking deployments during peak traffic hours or maintenance windows. ArgoCD also supports sync retries with configurable backoff strategies to handle transient failures like API server throttling or temporary network issues, preventing a single failed sync from requiring manual intervention during off-hours.

A common gotcha is enabling automated sync with prune without understanding its implications. If someone accidentally pushes a commit that removes a critical manifest file — say the production database StatefulSet — ArgoCD will dutifully delete that StatefulSet from the cluster within seconds. This is why many teams use the argocd.argoproj.io/sync-options annotation with Prune=false on critical resources as a safety net, preventing accidental deletion even when the global prune policy is enabled. Another frequently overlooked detail is that automated sync will not trigger if the Application is in a degraded or error health state from a previous failed sync. Engineers must configure proper alerting on sync failures and understand that selfHeal only applies to resources ArgoCD manages — it cannot detect or fix drift in resources outside its tracking scope.