1. What Argo CD is, and why it exists

Argo CD answers a question that only became important once Kubernetes won: if the cluster is a database of desired state, what should be writing to it?

For most of the industry the answer was “a CI pipeline, with credentials”. Argo CD’s answer is different, and the difference is the whole product.

The problem

Here is deployment as most teams did it in 2018, and as many still do:

   developer pushes to git
        │
        ▼
   CI pipeline runs
     ├─ build the image
     ├─ push the image
     └─ kubectl apply -f k8s/    ◄── the CI system holds
                                     admin credentials to
                                     your production cluster

This works. It is also structurally uncomfortable in four specific ways, and each one is a real incident waiting to happen.

Your CI system has production credentials. A build runner — which executes arbitrary code from any branch, pulls hundreds of third-party dependencies, and is exposed to every developer — holds a kubeconfig that can delete your namespace. This is by some distance the largest attack surface in a typical deployment pipeline.

Nobody knows what is actually running. The pipeline applied a manifest three weeks ago. Since then someone ran kubectl edit deployment at 2 a.m. to raise a memory limit and never put it back. Git says one thing; the cluster says another. There is no alarm, because nothing is comparing them.

Rollback is a new deployment. To go back, you re-run a pipeline against an older commit, which means rebuilding, re-testing and re-pushing — and hoping the older pipeline definition still works.

Every cluster needs a path in. Adding a cluster in a new region means giving CI network access to its API server. Now your build system needs a route into every production network you have.

Argo CD’s response is to invert the direction of the arrow.

The answer: pull, not push

   PUSH (CI applies)              PULL (Argo CD syncs)

   CI ──credentials──► cluster    cluster ──runs Argo CD
                                             │
   CI needs:                                 ├─ reads git
     - cluster credentials                   └─ applies to ITSELF
     - network access
     - to know every cluster      CI needs:
                                    - to push a commit
                                  nothing else

Argo CD runs inside the cluster it manages. It reads a git repository, compares what is there against what is live, and makes the cluster match. Nothing outside the cluster needs credentials to it, and nothing outside needs a network route in.

The consequences are immediate and larger than they first appear:

CI’s job shrinks to building an artefact and writing a commit. It never touches a cluster. A compromised runner can, at worst, propose a change — which is visible in git history and reviewable.

Drift is detected continuously, because comparing desired to live is the loop Argo CD runs constantly, not something that happens at deploy time. That is the property a push-based tool structurally cannot offer — the Ansible guide’s chapter 15 concedes exactly this about itself, and it is the same reason Puppet’s pull model survives alongside it.

Rollback is git revert. No rebuild, no pipeline, no artefacts. The desired state changed back and the cluster follows.

Adding a cluster adds nothing to CI. A new cluster runs its own Argo CD (or is registered with an existing one) and pulls the same repository.

What GitOps actually claims

The word is overused, so it is worth stating the four properties precisely. GitOps means:

1. DECLARATIVE — the entire desired state is described
   declaratively, not as a sequence of commands.

2. VERSIONED — that description lives in git, so it is
   immutable, auditable, and has a history.

3. PULLED — an agent inside the target environment
   pulls the description; nothing pushes into it.

4. CONTINUOUSLY RECONCILED — the agent constantly
   compares desired against actual and corrects drift.

Point 4 is the one people skip, and it is the one that distinguishes GitOps from “we keep our YAML in git”, which everybody already did. The claim is not that git is where manifests live. The claim is that git is the only thing that decides what runs, enforced by a controller that will undo anything else.

Point 1 is worth defending too, because it is what makes 4 possible. If your deployment is a script — “run this migration, then scale that up, then flip the flag” — there is nothing to compare. You cannot ask a script whether the cluster matches it. A declarative description can be diffed, and everything Argo CD does depends on that.

Where it came from

Intuit built Argo CD in 2018, alongside Argo Workflows, Argo Rollouts and Argo Events — the “Argo project”, which is four independent tools that share a name and a UI style rather than a codebase.

The insight was that Kubernetes’ own controllers already work this way. A Deployment controller does not “run a deployment”; it continuously compares the number of running pods with the number requested and corrects the difference. Argo CD applies exactly that pattern one level up: a controller whose desired state is a git repository and whose actual state is a cluster. If you have read the Kubernetes reconciliation chapter, Argo CD will feel immediately familiar, because it is the same idea with a different input.

It was donated to the CNCF in 2020 and graduated in December 2022. It is Apache 2.0, and — unusually for infrastructure software in this collection — there is no commercial edition holding back features. Vendors sell managed Argo CD; the project itself is complete.

This guide is written against Argo CD 2.13–3.x behaviour.

The four jobs people use it for

1. Deploying applications from git. The core. A repository of manifests becomes running workloads, kept in sync forever.

2. Managing many clusters from one place. One Argo CD can manage dozens of clusters. Chapter 10 is honest about when that is a good idea and when it makes a single blast radius out of your whole estate.

3. Bootstrapping clusters. A new cluster gets Argo CD and one Application pointing at a repository, and everything else — ingress controller, monitoring, cert-manager, policies — installs itself. Chapter 11’s app-of-apps pattern.

4. Enforcing that nothing changes outside git. With auto-sync and self-heal on, a manual kubectl edit is reverted within minutes. This is a compliance argument as much as an engineering one.

What it is not

It is not a CI system. It does not build, test, or push images. It reacts to a repository, and something else has to change that repository. Chapter 12 covers the image-update problem this creates, which is more awkward than it sounds.

It is not a secrets manager. This is the most common surprise and it is deliberate. Argo CD applies what is in git, and putting a Secret in git is exactly what you must not do. Chapter 12 is entirely about the four ways people solve this and which one to choose.

It does not replace Helm or Kustomize. It runs them. Argo CD is a delivery mechanism; your manifests are still generated the way they always were.

It is not a policy engine. It will happily sync a manifest that violates every rule you have. OPA Gatekeeper or Kyverno enforce policy; Argo CD delivers.

It does not do progressive delivery on its own. Canaries and blue-green are Argo Rollouts, a separate controller. They compose well and they are not the same tool.

It is not a general reconciler for non-Kubernetes things. It reconciles Kubernetes resources. Terraform does the equivalent job for cloud infrastructure, with a fundamentally different model — chapter 15 compares them honestly, because the overlap is real and the choice matters.

The mental model to carry

Five things. The rest of this guide is detail:

1. An APPLICATION is a custom resource that says
   "this git path, rendered this way, belongs in
   this cluster and namespace."

2. Argo CD constantly computes DESIRED (rendered from
   git) versus LIVE (read from the cluster). The
   difference is the DIFF, and everything hangs on it.

3. SYNC STATUS answers "does live match git?".
   HEALTH answers "is the thing working?". They are
   independent, and confusing them is the most common
   source of confusion in the whole tool.

4. SYNC applies the diff. It can be manual or
   automatic, and SELF-HEAL decides whether drift is
   reverted or merely reported.

5. Rendering happens in the REPO SERVER, diffing and
   applying in the APPLICATION CONTROLLER, and almost
   all performance problems are in one of those two.

Point 3 is where nearly all real-world confusion lives, which is why it gets chapters 6 and 8 rather than a footnote.

Why Argo CD in 2026

Two honest answers and one caveat.

The credential argument has only got stronger. Supply-chain attacks on CI runners are now routine. A deployment model where the build system holds no production credentials at all is worth a great deal, and it is difficult to get any other way.

Drift detection turns out to be the sleeper feature. Teams adopt Argo CD for deployment and keep it for the continuous comparison. Knowing — as a matter of routine rather than investigation — that the cluster matches git is a quieter benefit than the demo suggests and a more durable one.

The caveat, stated here so it is not a surprise in chapter 15: GitOps makes deployment slower and more visible. A change now requires a commit, and often a pull request, and then a sync. For a team that deploys twenty times a day and values speed above audit, that friction is real. It is usually the right trade; it is not free, and anyone who tells you it is has not run it.

What to take from this chapter

• The problem is push-based deployment: CI holds production credentials, nobody knows what is actually running, rollback means re-running a pipeline, and every cluster needs a route in.
• Argo CD inverts the arrow: an agent inside the cluster pulls from git and applies to itself. CI’s job shrinks to building an artefact and writing a commit.
• GitOps means four things: declarative, versioned in git, pulled by an in-cluster agent, and continuously reconciled. The fourth is what distinguishes it from “our YAML is in git”.
• Argo CD is Kubernetes’ own reconciliation pattern applied one level up, with git as the desired state.
• Four jobs: deploying from git, managing many clusters, bootstrapping clusters, and enforcing that nothing changes outside git.
• It is not CI, not a secrets manager, not a replacement for Helm or Kustomize, not a policy engine, and not progressive delivery.
• Carry five ideas: the Application resource, desired vs live, sync status vs health (independent!), sync and self-heal, and the repo server / application controller split.
• The honest cost: GitOps makes deployment slower and more visible. Usually the right trade, never a free one.

Next: the architecture — five components, what each one actually does, and why Redis is not optional.