ArgoCD - GitOps for Kubernetes That Actually Works

ArgoCD solves a specific problem: your production Kubernetes clusters slowly drifting away from what you think they should look like. Someone kubectl applies a hotfix, a deployment fails halfway through, or a ConfigMap gets manually edited - suddenly your "identical" staging and prod environments aren't identical anymore.

GitOps changes this by making Git your single source of truth. ArgoCD is a Kubernetes controller that watches your Git repos and automatically syncs changes to your clusters. Originally built at Intuit (now a CNCF graduated project), it's basically a robot that never gets tired of checking if your cluster matches Git.

The big win is visibility. ArgoCD's web UI shows you exactly what's deployed, what's out of sync, and what broke during the last deployment. Instead of running kubectl get pods and hoping for the best, you get a visual dashboard that actually tells you what's happening across all your applications.

The ArgoCD dashboard shows each application as a tree of Kubernetes resources - you can see pods, services, deployments, and their relationships at a glance. When something's broken, the UI highlights it in red and shows you exactly what failed.

How ArgoCD Actually Works

Traditional CI/CD tools push changes to your cluster - Jenkins runs kubectl apply, CircleCI hits the Kubernetes API, whatever. ArgoCD flips this around using a "pull" model. It runs inside your cluster and continuously polls Git repositories (every 3 minutes by default, configurable with repository settings).

When ArgoCD finds changes in Git, it renders your manifests (Helm charts, Kustomize, plain YAML) and compares them with what's actually running in the cluster. If there's a difference, it syncs automatically (if you enable auto-sync) or waits for you to click the sync button.

This means your cluster can't drift without ArgoCD noticing. Someone manually edits a Deployment? ArgoCD sees the drift and can either fix it automatically (self-heal) or alert you. Your Git history becomes your deployment audit trail - no more "who changed the replica count" mysteries.

Traditional CI/CD pushes changes to clusters from external systems (push model), while GitOps pulls changes from Git repositories running inside the cluster (pull model). This architectural difference makes GitOps more secure and auditable.

The Reality of Using ArgoCD in Production

ArgoCD v3.1 was released in June 2025 with OCI registry support (still beta - I wouldn't use it in prod yet) and multi-source applications. The multi-source feature actually solves a real problem if you're splitting app code from environment configs across different Git repos.

According to the latest CNCF survey, 97% of ArgoCD users run it in production, which makes sense since it's stable and battle-tested. It manages clusters at companies like Intuit, RedHat, and thousands of others according to adoption tracking.

But here's what the adoption stats don't tell you: ArgoCD's learning curve is steeper than it looks. The basic concepts are simple - Git as source of truth, pull-based deployments - but the devil's in the details. Application health checks fail silently, sync policies are confusing until you get burned by them, and the UI gets sluggish with hundreds of applications.

I've been running ArgoCD for 2 years across multiple clusters and I still occasionally discover gotchas. The resource hooks are powerful but they fail without clear error messages. RBAC configuration is a pain if you're not already a Kubernetes RBAC expert. Multi-cluster setup works great until you hit networking edge cases.

The big benefit though? When something breaks in production, ArgoCD's web UI immediately shows you what's different from Git. Instead of debugging with kubectl, you get a visual diff of what went wrong. That alone makes it worth the learning curve for most teams managing more than a handful of applications.

ArgoCD consists of several key components: the API Server (handles UI and CLI), Application Controller (watches Git and manages sync), Repository Server (clones repos and renders manifests), and Redis (caches Git state for performance).

ArgoCD isn't magic - it's a set of Kubernetes controllers that do specific jobs. If you're evaluating ArgoCD, understanding these components helps you figure out what might break and how to fix it when things go sideways.

The Core Controllers (And Their Pain Points)

TheApplication Controller is the heart of ArgoCD. It polls your Git repos every 3 minutes (configurable) and compares what's in Git with what's running in your cluster. This sounds simple until you have 200+ applications and the controller starts hitting GitHub's API rate limits. You'll need to configure repository credentials carefully and potentially set up webhook-based sync to reduce polling load.

TheRepository Server is where the complexity lives. It clones Git repos, renders Helm charts, processes Kustomize overlays, and handles authentication with GitHub, GitLab, Bitbucket, whatever. This is also where things break most often - memory usage scales poorly with repo size, and complex Helm charts can cause timeouts during rendering. I've seen the repo server consume 4GB+ RAM just from large monorepos with hundreds of microservices.

The Web UI (ArgoCD's Killer Feature)

ArgoCD's web interface is honestly why most people choose it over FluxCD. The UI shows you a visual topology of your applications - pods, services, ingresses, whatever - with real-time health status and sync state. When something breaks, you can see immediately what's degraded without running a dozen kubectl commands.

The UI lets you manually trigger syncs, view diffs between Git and cluster state, and roll back deployments with a button click. It's especially useful for debugging - you can drill down into individual resources, see their events, and check logs without leaving the interface. The API server powers both the UI and CLI, and it's decent for building custom integrations.

But the UI has limits. With 500+ applications, page load times get painful. The tree view becomes unwieldy with complex applications that have dozens of resources. And don't expect fancy filtering or saved views - you'll be clicking through applications one by one.

In a hub-and-spoke architecture, one central ArgoCD instance manages applications across multiple remote clusters, providing a single pane of glass for deployments while maintaining cluster isolation.

Features That Actually Matter in Production

Multi-Source Applications (New in v3.1)

The multi-source feature lets one application pull from multiple Git repos or sources. This solves the common pattern where app config lives in one repo and environment-specific values live in another. Before this, you needed ApplicationSets or complex templating workarounds.

Progressive Delivery with Argo Rollouts

ArgoCD integrates with Argo Rollouts for canary and blue-green deployments. Rollouts extends Kubernetes Deployments with advanced deployment strategies. The integration is clean - ArgoCD manages the Rollout resource, Rollouts handles the deployment strategy. Works well if you need more than basic rolling updates.

Sync Policies (Where You'll Get Burned)

ArgoCD has sync policies that control how deployments work: manual sync (you click the button), auto-sync (changes deploy immediately), self-heal (fixes manual drift), and prune (removes deleted resources). The gotcha is that these interact in non-obvious ways. Enable auto-sync + self-heal + prune without understanding the implications, and you might accidentally delete resources you care about.

The application details view shows real-time sync status, health state, and resource relationships. Out-of-sync resources are highlighted, making it easy to identify what changed between Git and the cluster.

Resource Hooks and Health Checks (The Devils in the Details)

Sync Hooks and Waves

Resource hooks let you run Jobs before/after syncs - database migrations, cache warming, whatever. They work great when they work, but debugging failed hooks is painful because error messages are often buried in Job logs that aren't obvious from the ArgoCD UI.

Sync waves handle dependencies by applying resources in phases. Wave 0 resources deploy first, then wave 1, etc. This solves the "ConfigMap needs to exist before Deployment" problem, but managing complex dependency chains gets messy quickly.

Health Checks That Sometimes Lie

ArgoCD has built-in health checks for standard Kubernetes resources, plus custom health checks for CRDs. The health system works well for simple cases - pods are healthy when they're running, services when their endpoints exist.

But custom resources are hit-or-miss. An Istio VirtualService might show as healthy even when it has invalid syntax that's breaking traffic routing. A cert-manager Certificate might be "healthy" while actually failing to renew. Always verify that health checks actually match your application's reality - don't just trust the green checkmarks.

The drift detection is solid though. ArgoCD shows exactly which resources differ from Git, which specific fields have changed, and gives you a visual diff. When debugging production issues, this immediate visibility is invaluable compared to running kubectl diffs manually.

ArgoCD's component architecture ensures separation of concerns: Git repository management, manifest rendering, and cluster synchronization each have dedicated services that can be scaled independently for performance.