Understanding the Argo CD Architecture
A Familiar Failure Mode
Most engineers don’t lose control of systems in dramatic moments. They lose control quietly. It usually starts with something reasonable. A manual change during an incident. A quick fix to confirm a theory. A one-off tweak that “we’ll clean up later.” Weeks pass. People rotate. The change becomes invisible, but it still exists. Eventually, something breaks, and no one is quite sure what the system was supposed to look like anymore.
Kubernetes does not prevent this. In fact, Kubernetes makes it easier. It will faithfully run whatever state currently exists, regardless of whether that state was intentional, reviewed, or still correct. Argo CD’s architecture exists because of this failure mode. Not because Kubernetes is weak, but because systems need memory that survives people.
To understand Argo CD’s architecture, it helps to stop thinking in terms of “deployment tools” and start thinking in terms of institutional memory encoded as software.
Why Architecture Matters in GitOps Systems
Before diving into components, it is worth restating the problem Argo CD is solving at an architectural level.
Argo CD is not optimized for deployment speed. It is optimized for sustained correctness under change.
That design goal has consequences:
- The system must be continuously active, not event-driven
- It must survive partial failure without losing authority
- It must reconcile external truth (Git) with internal reality (the cluster)
- It must not require humans to remember “what should be running”
Every architectural choice in Argo CD exists to support those constraints. It enforces a single architectural constraint:
The authoritative description of the system must live outside the cluster.
This means Git is not just a source of configuration. It is the reference point against which reality is judged. The cluster, by contrast, is treated as mutable, fallible, and constantly suspect. This framing explains why Argo CD is pull-based, why it runs inside Kubernetes, and why its components are so carefully limited in power.
With that in mind, we can distinguish between core components, those without which Argo CD cannot function, and supporting components, which exist to improve scale, security, or ergonomics, but can be replaced or reconfigured.
The Core Components of ArgoCD
At a high level, Argo CD consists of four major subsystems:
- Application Controller – the reconciliation engine
- Repository Server – the Git and manifest evaluation engine
- API Server – the control and visibility surface
- Persistence Layer – Kubernetes itself (plus optional Redis)
The Application Controller
If Argo CD had a “heart,” this would be it. It is the only component that compares desired state to live state, decides whether drift exists, and enforces reconciliation when permitted.
The controller watches Application custom resources inside Kubernetes. Each Application is a declaration that binds together three things:
- a source of truth (a Git repository and revision),
- a rendering strategy (Helm, Kustomize, etc.),
- and a destination (cluster and namespace).
The controller does not remember outcomes. It observes continuously. Every reconciliation loop starts from first principles: What does Git say should exist?, What does the cluster say exists right now?, and What is different?
If automated sync is enabled and allowed by policy, it corrects the difference. If not, it records the divergence and waits.
This design has an important consequence that is easy to miss: Argo CD never trusts its past success. Even a “green” application is re-evaluated repeatedly. Correctness is not a state you reach; it is a condition you continuously verify.
This is why the controller is indispensable.
In summary, that makes Argo CD trustworthy flows from this controller:
- Drift detection
- Self-healing
- Sync enforcement
- Health evaluation
- Status reporting
Applications as the Unit of Reconciliation (Practical Version)
Argo CD doesn’t manage your entire Kubernetes cluster. It manages one application at a time.
An Application is like a folder in your Git repository containing all Kubernetes files for one service (your FastAPI backend, for example). Argo CD watches only this folder and only the matching namespace in your cluster.
Everything Argo CD does - checking for changes, updating deployments, monitoring health- happens just for this one folder.
This makes the Application:
- Team ownership: Backend team manages backend Application
- Limited impact: Backend fails? Frontend continues unaffected
- Independent checking: Each service checked separately
No single “master deployment status” exists. Each Application works alone.
If your FastAPI backend Application breaks, your Next.js frontend Application keeps running perfectly.
How it scales: Instead of one giant process watching everything, Argo CD runs one small process per application. Your SimpleTasks backend gets its own watcher. Your frontend gets its own watcher. Simple and isolated.
The Repository Server
Git does not contain Kubernetes resources in the form Kubernetes understands. It contains templates, overlays, and abstractions. Someone must turn those into plain manifests. That responsibility belongs to the repository server.
The repo server clones repositories, checks out specific revisions, and renders manifests using the declared tooling. This work is intentionally isolated.
There are two reasons for this separation, both practical and ethical.
Practically, rendering can fail, hang, or consume significant resources. Isolating it prevents rendering problems from destabilizing reconciliation.
Ethically, rendering is a descriptive act, not an enforcing one. The repo server has no permission to talk to Kubernetes APIs. It cannot deploy anything. It produces candidate truth, nothing more.
This constraint is essential. Without it, rendering logic would become an attack surface with operational consequences.
Diffing: How Argo CD Knows Something Is Wrong (Practical Version)
After Argo CD reads files from Git, it needs to answer one simple question:
“Does what’s running in the cluster still match what’s written in Git?”
This is harder than it sounds because Kubernetes changes things automatically. It adds defaults, timestamps, generated fields, and internal metadata. If Argo CD compared files line-by-line, it would think everything is broken all the time. So Argo CD does something smarter.
What Argo CD Actually Compares
Argo CD compares meaning, not text. Think of it like comparing two documents:
- One printed
- One handwritten
- Same content, different formatting
Argo CD ignores formatting differences and focuses on intent. Specifically, it:
- Ignores fields Kubernetes changes automatically
- Ignores runtime-only data (timestamps, IDs)
- Allows you to explicitly tell it “this difference is OK”
- Compares what the resource means, not how it looks
The result is a clear answer:
“Is this resource still configured the way Git says it should be?”
This comparison powers:
- Drift warnings
- Sync decisions
- What you see in the UI
- What gets logged for audits
If diffing is wrong, Argo CD becomes noisy and untrustworthy. That’s why this part of the system is careful and conservative by design.
The API Server
The API server is where humans interact with Argo CD. When you use the UI or CLI, you are talking to this component. It authenticates users, enforces RBAC, validates requests, and records intent. What it does not do is apply manifests or reconcile state. It also provides audit logging and sync triggers.
This restraint is deliberate. User-facing systems should not hold operational power. If the UI is compromised, the attacker should not automatically gain deployment authority. The API server can ask for actions to occur. It cannot make them occur. Internally, the API server communicates primarily over gRPC; the CLI is simply another client, not a privileged interface.
Kubernetes Itself: The Execution Engine
It may sound obvious, but Kubernetes is not just the environment Argo CD runs in. It is a core participant in the architecture. Argo CD does not replace Kubernetes reconciliation loops. It feeds them. When Argo CD applies changes, it does so by submitting manifests to Kubernetes, which then:
- schedules pods,
- manages restarts,
- enforces constraints,
- and reports actual state.
Argo CD never assumes Kubernetes did what it asked. It observes the result and reconciles again. In this sense, Kubernetes is both executor and witness. Argo CD asks; Kubernetes acts; Argo CD verifies.
Supporting Components
Beyond the core, Argo CD includes additional components that can add to its functionality but do no define the system’s identity.
Understanding these correctly helps avoid misconfiguration and misplaced trust.
ApplicationSets: Managing Many Applications Without Copy-Paste
As systems grow, writing one Application per service by hand stops being realistic.
Most teams don’t have ten services. They have dozens. Sometimes hundreds. Often spread across multiple environments or clusters. Writing and maintaining one Application YAML for each quickly becomes busywork. This is why Argo CD includes the ApplicationSet controller.
An ApplicationSet is a higher-level definition that creates Applications automatically.
Instead of saying:
“Here is one Application”
you say:
“Here is a rule for generating many Applications”
For example:
- One Application per folder in a Git repo
- One Application per cluster
- One Application per environment
The ApplicationSet controller reads this rule and creates or updates normal Application resources accordingly.
ApplicationSets do not deploy anything.
They generate Application objects, keep them up to date, and participate in reconciliation. They do not talk to Kubernetes APIs, apply manifests or manage workloads
Once an Application exists, it is handled exactly the same way as any other Application by the Application Controller. This preserves Argo CD’s core discipline. Scale is achieved by composition, not by introducing a more powerful central controller.
ApplicationSets exist because humans are bad at repetition and GitOps systems must scale without copy-paste.
Authentication and Dex: Identity Without Ownership
Argo CD integrates with external identity systems using standard protocols. Dex often serves as a broker, translating external identities into a form Argo CD can work with.
The important distinction is this: Authentication answers who you are. Authorization answers what you may do. Argo CD concerns itself only with the latter. Identity remains external, where organizational policy already lives. This separation allows Argo CD to fit into real enterprises without becoming a security liability.
Notifications: Visibility Without Control
Argo CD is designed to enforce state, not to shout about it. But humans still need feedback when things change or fail. This is the role of the notifications controller.
The notifications controller watches Application state, reacts to events like sync success, failure, or health degradation, and sends messages to external systems such as Slack, email, or webhooks.
Redis
At scale, constantly recomputing everything becomes expensive. Redis exists to make Argo CD usable in real environments. It caches application state, Git metadata, and cluster information to reduce load and latency. But Redis is not authoritative.
If Redis disappears, Argo CD slows down. It does not become incorrect. This distinction is subtle but critical. Redis is treated as working memory, not long-term memory. Truth remains in Git and the cluster.
At small scale, Redis usually runs as a single instance. At larger scale, it can be deployed in a highly coming-soon configuration or replaced with an external managed Redis service.
How the Pieces Work Together, Slowly and Repeatedly
A common mistake is to describe Argo CD as reacting to Git pushes. That is not quite accurate.
Argo CD observes. It notices differences when they become visible. It does not rush.
A change in Git updates declared intent. The controller eventually observes that intent no longer matches what it last rendered. It asks the repo server to produce manifests. It compares those with live state. It classifies the differences. It decides whether action is permitted. Then, and only then, does it act.
The same process occurs if someone manually changes the cluster. Argo CD does not care who caused drift. It only cares that drift exists. This indifference is a feature.
The Sync Engine: How Argo CD Fixes Things Safely (Practical Version)
Once Argo CD detects a difference, it does nothing by default. Detection and fixing are intentionally separated.
A sync is the moment Argo CD is allowed to change the cluster.
What a Sync Is Not
A sync is not:
- One giant
kubectl apply - An all-or-nothing operation
- A blind overwrite
Argo CD treats changes as steps, not a single action.
What Happens During a Sync
When a sync is allowed, Argo CD:
- Applies resources in the correct order - (CRDs first, then things that depend on them)
- Applies changes gradually. If something fails, it stops and reports exactly where
- Tracks partial success - You can see what worked and what didn’t
- Records everything - Nothing is hidden or silently retried
This makes failures visible instead of destructive. You don’t lose the entire deployment just because one resource failed.
Why Sync Is Explicit
Argo CD separates:
- Refresh → “What’s different?”
- Sync → “Should we fix it?”
This matters during incidents, investigations, and temporary experiments. You can see drift without being forced to correct it immediately. Auto-sync exists, but it is a policy choice, not the default assumption. Argo CD assumes humans sometimes need time to think.
Warnings, Trade-offs, and Common Misuse
Argo CD is often misused in predictable ways.
Teams sometimes:
- enable auto-sync everywhere without governance,
- treat Git as a dumping ground instead of a contract,
- or fight the system by making manual changes.
Argo CD is unforgiving of sloppy intent. It will enforce bad decisions just as faithfully as good ones.
This is not a flaw. It is a mirror.
Conclusion
Argo CD’s architecture does not promise safety. It promises honesty. It forces teams to confront what they actually declared, not what they remember declaring. It replaces informal trust with explicit contracts. It shifts responsibility upstream, where mistakes are cheaper and more visible. Used well, Argo CD forms disciplined engineers. Used poorly, it accelerates chaos. The difference is not in the tool. It is in whether teams are willing to mean what they write.
