What is ArgoCD and how does the GitOps reconciliation loop work?

Think of ArgoCD like a thermostat in your house. You set the desired temperature (your Git repository declares the desired cluster state), and the thermostat continuously monitors the current temperature (cluster state) and turns on heating or cooling (applies manifests) whenever there is a deviation. Just as the thermostat does not care how the temperature drifted — whether someone opened a window or the sun came out — ArgoCD does not care whether drift was caused by a kubectl edit, a rogue operator, or a failed rollout. It simply reconciles back to the declared truth in Git.

At its core, ArgoCD implements the GitOps pattern where Git serves as the single source of truth for declarative infrastructure and application definitions. When you register an Application resource with ArgoCD, you tell it which Git repository, branch, and path contain your Kubernetes manifests. ArgoCD then compares the rendered manifests from Git against the live objects in the target Kubernetes cluster. If they match, the application is considered Synced. If they differ, ArgoCD marks it as OutOfSync and can either alert you or automatically apply the changes depending on your sync policy configuration.

Internally, ArgoCD consists of three main components that power the reconciliation loop. The Repository Server clones Git repositories, caches them, and renders manifests using the appropriate tool such as Helm, Kustomize, or plain YAML. The Application Controller is the brain that runs the reconciliation loop on a configurable interval, defaulting to every three minutes. It fetches the desired state from the Repository Server, fetches the live state from the Kubernetes API server, performs a three-way diff using the last-applied-configuration annotation, and determines if the application is synced or drifted. The API Server exposes the gRPC and REST API consumed by the web UI and CLI, handles authentication via OIDC or DEX, and enforces RBAC policies for multi-tenant environments.

In production, you typically deploy ArgoCD in a dedicated namespace like argocd on a management cluster. Teams configure webhook notifications from GitHub or GitLab so that ArgoCD reacts to pushes within seconds rather than waiting for the next polling interval. You also integrate ArgoCD with notification controllers to send alerts to Slack or PagerDuty when an application goes OutOfSync or a sync operation fails. Resource tracking is configured using either the label-based or annotation-based method, and health checks are customized for CRDs that ArgoCD does not natively understand, ensuring the reconciliation loop accurately reflects the true health of your workloads.

A critical gotcha engineers overlook is the difference between the refresh interval and the sync interval. Refreshing means ArgoCD re-reads Git and re-computes the diff, while syncing means it actually applies changes to the cluster. Even with auto-sync enabled, ArgoCD will not sync if the previous sync failed — it enters a degraded state requiring manual intervention or a retry policy. Another pitfall is ignoring resource exclusions; by default ArgoCD tracks every resource it manages, and if an operator or admission controller mutates fields like timestamps or status subresources, ArgoCD may report perpetual OutOfSync status. You must configure ignoreDifferences in the Application spec to exclude those volatile fields from the diff computation.