How Argo CD Actually Syncs Kubernetes Manifests — Under the Hood💫
I build scalable, resilient systems using cloud-native automation—turning code into production-grade infra with Kubernetes, Docker, Terraform, and CI/CD pipelines. Hands-on with real-world labs, I deploy event-driven, observable, and secure workloads on GCP & AWS, optimizing for performance, cost, and developer experience. Driven by clear thinking, continuous learning, and impact-first engineering, I collaborate to ship systems that don’t just work—they evolve.
Ever clicked “Sync” in Argo CD and wondered what’s really going on behind that magic button?
Turns out, it’s not just pushing YAMLs to your cluster — it’s running a smart control loop that keeps your live state perfectly aligned with your Git state.
Let’s break down how it actually works — piece by piece — from a DevOps learner’s perspective.
⚙️ 1. The Argo CD Application — Your GitOps Blueprint
Everything starts with an Application — basically Argo CD’s definition of what to deploy and where.
It has three main parts:
Source → where the manifests come from (Git repo, Helm chart, etc.)
Destination → which cluster and namespace to apply them to
Sync Policy → how updates should happen (manual or automatic)
Once that’s in place, Argo CD watches both your Git repo and your cluster — constantly checking if they’re in sync.
That’s GitOps 101: Git = truth, cluster = reality.
☸ 2. Manifest Generation — Turning Source into Deployable YAML
When an Application is created, Argo CD figures out how to turn your source into raw manifests:
Auto-Detection → figures out if you’re using Helm, Kustomize, or plain YAML.
Rendering →
Helm →
helm templateKustomize →
kustomize buildYAML → just reads it as is
What you get is a clean, ordered list of Kubernetes resources ready for deployment.
🧾 3. Normalization & Label Magic
Before applying anything, Argo CD cleans things up a bit:
Sorts resources in the right order (CRDs first, then CRs).
Adds internal labels like:
argocd.argoproj.io/instance: my-app
These tiny annotations are how Argo CD tracks which resources belong to which app — and later detects drift or cleans up old ones.
🔍 4. The Real “Sync” — Comparing Desired vs. Live
Here’s where the magic happens.
Argo CD compares what’s in Git with what’s actually running in the cluster.
If something’s off, it highlights the difference.
In manual mode, you decide when to fix it.
In auto mode, Argo CD just goes ahead and reconciles.
During sync, it:
✅ Creates missing resources
🩹 Updates the changed ones
🧹 Deletes anything removed from Git
It’s basically kubectl apply --prune — but way smarter, safer, and Git-driven.
image courtesy: Akuity
❤️ 5. Health Checks — Because “Running” Isn’t Always “Healthy”
After syncing, Argo CD checks how your resources are doing:
| Status | What It Means |
| Healthy | Everything’s good to go |
| Progressing | Still creating or updating |
| Degraded | Something’s broken (e.g. pod crash) |
| Missing | Expected resource isn’t there |
| Suspended | Waiting for an external event |
Your app’s overall health is just the combined status of all these — a simple but super useful view when debugging.
🧠 6. Self-Healing — Argo CD as Your Cluster’s Immune System
Enable selfHeal in your syncPolicy and Argo CD instantly becomes your cluster’s watchdog.
Change something manually with
kubectl? Argo CD will roll it back.Delete a resource from Git? It’ll remove it from the cluster too.
It’s the heart of GitOps — no manual drift, no hidden state.
Your cluster always reflects what’s in Git, nothing else.
🌐 7. Multi-Cluster Power — One Argo, Many Worlds
Using the destination field, you can decide exactly where things go:
You can deploy:
To your local cluster, or
To any other connected cluster via
argocd cluster add
This makes Argo CD awesome for managing dev → staging → prod pipelines or even multi-region setups.
📣 8. Notifications & Feedback Loops
Every sync, health update, or failure triggers events that can notify you via:
Slack / MS Teams
Webhooks
CI/CD pipelines like Tekton or Argo Workflows
It’s not just automation — it’s observability with context.
✨ TL;DR — The GitOps Control Loop
Argo CD is the heartbeat of GitOps.
It continuously watches, compares, and corrects — keeping your cluster honest, one sync at a time.
Final Thoughts
When I first hit “Sync,” I thought it was just another deploy.
Now I know it’s a whole control loop — a living system that aligns my cluster with my intent.
That’s what makes Argo CD so addictive.
It’s not just deploying YAMLs — it’s watching your ideas come alive, in real time, the GitOps way.
Big thanks to the folks at Akuity for their amazing Argo CD course — it helped me finally understand what really happens after hitting “Sync.” 🙌☁️
