What Is Argo CD? A Careful Introduction to GitOps-Based Delivery on Kubernetes
Introduction: When Deployment Stops Being the Hard Part
In my early days as a DevOps engineer, my team had a production incident that required an immediate fix. The CI/CD pipeline existed, but waiting for it would take too long. This was a hot fix situation.
So I did what felt reasonable under pressure: I manually applied Kubernetes manifests. Unfortunately, I applied the manifests for the staging environment.
At first, everything looked fine. Our staging and production setups were “very similar.” But minutes later, things began to fail. Secrets broke first. Then configuration mismatches surfaced. Before long, the failure spread beyond a single service. We had a cluster-wide outage.
The root cause wasn’t Kubernetes. And it wasn’t even human error in the narrow sense.
The real failure was this: under pressure, we had no enforced source of truth for what production was supposed to look like.
In the early life of a system, deployment feels like the main challenge. Getting code to run at all is the victory. But as systems grow, something else quietly becomes harder: keeping the running system aligned with what the team believes to be true.
Kubernetes excels at running workloads. It schedules pods, restarts failed containers, and converges toward the desired state it is given. What it does not do is govern where that desired state comes from, whether changes were intentional, or whether today’s state still reflects what the team agreed on yesterday. Kubernetes will faithfully apply whatever you tell it even if what you tell it is wrong.
This is the gap Argo CD exists to fill.
Argo CD is not another orchestrator, and it does not compete with Kubernetes. Instead, it works with it to solve the problem of continuously ensuring that what is running matches what was declared, reviewed, and agreed upon.
This article introduces Argo CD from first principles. The goal is not to rush into commands, but to build a mental model that makes Argo CD’s design feel inevitable rather than mysterious.
What Is Argo CD?
At its core, Argo CD is an open-source, declarative, GitOps-based continuous delivery system for Kubernetes.
That definition is dense, so it is worth unpacking slowly.
-
Declarative means you describe what the system should look like, and allow software to continuously reconcile reality toward that description. The value is not the YAML itself, but the ability to detect and correct divergence over time.
-
GitOps-based means Git is treated as the authoritative source of truth. What exists in the cluster is expected to match what exists in version control, and differences are treated as drift, and reconciled.
-
Continuous delivery means the system does not stop once a deployment succeeds. It continuously observes, compares, and verifies that the running state still matches what was declared.
-
For Kubernetes means Argo CD operates entirely through Kubernetes’ APIs and control patterns. It does not replace Kubernetes; it works with it.
Argo CD does not run workloads. Kubernetes does that.
Argo CD ensures Kubernetes is running the right workloads, for the right reasons, over time.
How Argo CD Relates to Kubernetes
Kubernetes already reconciles state internally. If a Pod crashes, Kubernetes replaces it. If replica counts drop below the desired number, Kubernetes corrects it. This reconciliation is limited to what Kubernetes already knows about.
Argo CD applies the same reconciliation idea one level higher. Instead of reconciling Pods and Nodes, Argo CD continuously compares:
- what is declared and versioned in Git
- with what is actually running in the cluster
In this model, Kubernetes is no longer the final authority on correctness. It becomes an execution engine whose state is expected to match an external, human-reviewed source of truth. Argo CD treats the cluster itself as something that must be kept in alignment with declared intent over time.
A Brief Historical Context
Argo CD was first released in 2019 by Intuit as part of the broader Argo project. It emerged from a practical need: teams wanted to apply GitOps principles to Kubernetes without relying on custom scripts, fragile CI jobs, or manual intervention during incidents.
As Kubernetes adoption grew, so did the cost of configuration drift, undocumented changes, and “temporary” fixes that became permanent.
Over time, Argo CD matured into a widely adopted solution and became part of the CNCF ecosystem. Its growth reflects a broader industry realization:
delivery problems are rarely about speed; they are about consistency, traceability, and trust.
Core Concepts That Shape How Argo CD Works
To understand Argo CD, it is important to understand the language it uses to reason about systems. These concepts define how Argo CD thinks about correctness, change, and responsibility.
Application: Declared Intent as an Object
In Argo CD, an Application is not your code. It is a declaration of intent that defines:
- which repository to watch,
- which path contains the desired configuration,
- and which cluster and namespace should reflect it.
This declaration is stored inside Kubernetes as a custom resource. In other words, Argo CD turns deployment intent into something Kubernetes itself can observe, reconcile, and audit.
An Application also sets a clear boundary: it’s your single point of responsibility - like a fenced-off yard where everything inside is yours to manage.
- Ownership: You own and control just this app’s deployments, not the whole cluster.
- Reconciliation: Argo CD keeps watching and fixing only this app to match your desired state.
- Failure: If something breaks, it stays contained here—easy to spot, debug, and roll back without chaos everywhere.
Changes happen neatly inside an Application, not scattered across the cluster.
Target State and Live State
Argo CD is built around a strict distinction between two states: The Target state which is the declarative code on Git specifies what should exist in the cluster and the Live state which is what the cluster is currently running.
Argo CD does not assume these states are equal. In fact, it assumes they will diverge over time due to manual changes, failed rollouts, or systems mutating resources at runtime. Detecting and reasoning about this divergence is a core design goal.
Refresh: Observing Without Acting
A refresh is when Argo CD fetches the latest configuration from Git, compares it to the live cluster state, and records any differences. It does not change the cluster. It is observation, not enforcement.
This separation matters. Knowing what is wrong is a prerequisite to deciding whether it should be fixed, when, and by whom.
Sync: Turning Intent into Reality
A sync is when Argo CD applies changes to the cluster to move it toward the target state.
Depending on policy and configuration, this may happen automatically, or only after explicit human approval. Either way, a sync is an intentional act. It is visible, auditable, and repeatable. Nothing happens implicitly.
The Application Controller
Behind these concepts is a Kubernetes controller. Like all controllers, it follows a loop:
- Observe current state
- Compare it to the desired state
- Take corrective action when allowed
- Repeat
This loop never stops. Argo CD does not “finish deploying.” It continuously verifies that reality still matches intent.
API Server and Interfaces
Argo CD exposes a web UI and a CLI through an API server. These interfaces allow humans and automation to inspect differences, trigger syncs, review history, and control access. This is not where reconciliation happens. It is how intent, oversight, and responsibility enter the system.
How Argo CD Works in Practice
Let us walk through a simple, realistic scenario.
-
A user updates Kubernetes configuration in a Git repository. This might be a change to a replica count, an image version, or an environment variable.
-
Argo CD periodically observes the repository. It evaluates the declared configuration and compares it with what is currently running in the cluster.
-
If the cluster already matches what Git declares, nothing happens.
-
If it does not, Argo CD records the difference. Depending on policy - such as whether automatic synchronisation is allowed, it may then apply changes to move the cluster back into alignment.
-
Importantly, this is not a one-time action. The comparison happens continuously. If someone later modifies the cluster manually, during an incident or for debugging, Argo CD observes that divergence as well.
This is why Argo CD is often described as pull-based. It does not wait for a pipeline to push changes. Instead, it continuously pulls declared truth from Git and compares it against reality.
Push-Based vs Pull-Based Delivery
Traditional CI/CD systems deliver changes by pushing them into clusters. A pipeline detects a change, authenticates to Kubernetes, and applies new configuration or workloads. The cluster itself plays a passive role: it receives changes when an external system decides it is time.
In this model, control lives outside the cluster. Credentials must be distributed outward, and the Kubernetes API must accept write access from systems that are not part of the runtime environment. This is not inherently wrong, but it does establish a particular trust boundary: the authority to change production exists elsewhere. Argo CD reverses this relationship by operating entirely from within the cluster.
Instead of waiting for a pipeline to push changes, Argo CD continuously observes two things on its own: the desired state declared in Git, and the live state reported by the Kubernetes API. When Git changes, nothing is sent to the cluster. There is no webhook instructing Kubernetes to deploy. The commit merely updates declared intent.
Argo CD later notices that intent has changed because it is actively pulling from Git. It independently compares what Git declares with what the cluster is running, and then decides - based on policy - whether reconciliation should occur.
This is what pull-based means in practice. The cluster is no longer a passive recipient of change. It actively verifies, decides, and enforces.
Because Argo CD runs inside Kubernetes, it uses Kubernetes-native identity and access controls. External systems do not require direct cluster credentials, and the authority to change runtime state is enforced from within the environment being changed.
This is not only a technical distinction. It is a decision about responsibility. It determines where deployment authority lives, how access is scoped, and how confidently a team can say that production reflects what was reviewed and agreed upon.
Who Argo CD Is For
Argo CD is most commonly adopted by teams responsible for the long-term correctness of Kubernetes environments, such as:
- platform teams defining shared deployment patterns,
- DevOps engineers responsible for delivery reliability,
- Kubernetes administrators maintaining cluster health and access boundaries.
Its value grows as systems become more complex. In small, single-environment setups, drift is usually visible and manageable. As systems expand, that stops being true.
Argo CD becomes especially useful when environments are:
- multi-environment (staging, production, regional variants),
- multi-cluster (for scale, isolation, or resilience),
- multi-team (with independent deployment responsibilities).
Wherever configuration drift becomes costly — operationally, security-wise, or psychologically -Argo CD helps restore confidence in what is actually running.
Limits and Responsibility
It is important to be honest about what Argo CD does not do.
Argo CD:
- does not provision infrastructure,
- does not replace CI systems that build and test artifacts,
- does not prevent bad configuration from being merged into Git.
What Argo CD does is enforce declared truth.
That distinction is critical. If the declared truth is wrong, Argo CD will enforce the wrong thing very effectively. This is not a weakness of the tool, but a consequence of taking declarations seriously. Because of this, review discipline, access control, and ownership boundaries are not optional. They are part of the system. Argo CD makes intent executable; it does not make intent correct.
Conclusion: Why Argo CD Changes How Teams Think
Argo CD quietly shifts responsibility upstream. Instead of asking, “Did we deploy correctly?”
Teams begin asking, “Did we declare the right thing?” This is a healthier question.
By making Git the authority and reconciliation unavoidable, Argo CD reduces chaos not through control, but through clarity. It does not eliminate human judgment; it demands that judgment be made visible.
With this understanding in place, we are ready to ask a deeper question: How is Argo CD built internally to enforce this discipline without becoming fragile itself? That is where the architecture begins.
