Argo CD
Argo CD continuously syncs Kubernetes clusters with configuration stored in Git, the GitOps approach to deployment. Learn how it works and why teams adopt it.
Overview
Argo CD is a continuous delivery tool for Kubernetes built around an idea called GitOps. The desired state of every application, meaning which images run, how many replicas, which configuration, is stored in a Git repository. Argo CD runs inside the cluster, watches that repository, compares it with what is actually running, and brings the two back into line. Deploying becomes a matter of merging a change in Git rather than running commands against a cluster.
An everyday analogy is a thermostat. You set the temperature you want once. The thermostat keeps measuring the room, and whenever the real temperature drifts away from the setting, it switches the heating on or off until the two match. Nobody stands by the radiator turning it by hand. In Argo CD, Git holds the setting, the cluster is the room, and the controller is the thermostat that keeps correcting drift.
For AI and data platforms this matters because clusters accumulate many moving parts: model servers, feature stores, monitoring, workflow engines and their configuration. Argo CD gives each change a reviewed commit, a clear history and a simple way back, which is valuable when a new model version or a configuration change misbehaves.
What it is
Argo CD is a set of Kubernetes components plus a web interface and command-line tool.
| Component or concept | What it does |
|---|---|
| Application | A custom resource that links a source (Git path, Helm chart or OCI artefact) to a destination (cluster and namespace) |
| AppProject | Groups applications and limits which repositories, clusters and namespaces they may use |
| Repository server | Clones Git repositories and renders manifests from plain YAML, Kustomize, Helm or plugins |
| Application controller | Compares rendered desired state with live state and performs sync operations |
| API server and UI | Serves the web interface, CLI and API, with authentication and role-based access control |
| ApplicationSet | Generates many Applications from templates, for example one per cluster or per directory |
| Sync policy | Rules for when and how syncing happens: manual, automated, pruning, self-heal |
Argo CD is one of four projects under the Argo umbrella; the others are Argo Workflows, Argo Events and Argo Rollouts. Rollouts is often paired with Argo CD for canary and blue-green releases.
Where it came from
The Argo project was created and open-sourced in 2017 by Applatix, starting with what became Argo Workflows. Intuit acquired Applatix in early 2018 and launched Argo CD that year to manage its own Kubernetes deployments. The Argo project joined the Cloud Native Computing Foundation (CNCF) as an incubating project in April 2020 and graduated on 6 December 2022.
Argo CD 3.0 arrived in 2025 as a major release focused on safer defaults, finer-grained role-based access control for update and delete actions, and performance improvements, with an upgrade path from the 2.x line. Support for the 2.x series was announced to end with the release of 3.2 in late 2025, so current installations should run a 3.x version.
How it works
1. Declare applications
An Application resource says: take the manifests at this path in this repository, at this revision, and deploy them to this namespace in this cluster. Applications themselves can live in Git, a pattern often called "app of apps".
2. Render desired state
The repository server fetches the source and renders it. Plain YAML is used as is; Kustomize overlays are built; Helm charts are templated with the given values. The result is the full set of manifests that should exist.
3. Compare with live state
The application controller reads the live resources from the Kubernetes API and computes a diff. Each application gets two statuses: sync status (does live match Git?) and health status (are the resources actually working, for example are Deployments available?).
4. Sync
A sync applies the rendered manifests to the cluster. It can be manual, triggered from the UI or CLI, or automated whenever Git changes. Options include pruning resources that were removed from Git and self-healing, which reverts manual changes made directly in the cluster.
5. Order and hooks
Sync waves and hooks control order. A database migration job can run in a pre-sync hook, then core services in wave 0, then dependants in wave 1.
6. Observe and roll back
Every sync is tied to a Git commit. Rolling back usually means reverting the commit, after which Argo CD syncs the earlier state. Argo CD also exposes metrics that Prometheus can scrape and Grafana can chart.
Key concepts and terms
| Term | Meaning |
|---|---|
| GitOps | Operating systems by declaring desired state in Git and letting automation reconcile it. |
| Desired state | The configuration recorded in Git. |
| Live state | What actually runs in the cluster now. |
| Drift | Any difference between desired and live state. |
| Reconciliation | The loop that detects drift and corrects it. |
| Sync | Applying desired state to the cluster. |
| Self-heal | Automatically reverting changes made outside Git. |
| Prune | Deleting live resources that no longer exist in Git. |
| Sync wave | A number that orders resources during a sync. |
| Health check | Logic that decides whether a resource is working, not merely present. |
| ApplicationSet | A generator that creates many Applications from one template. |
A worked example
This scenario is illustrative. A platform team runs a recommendation service in three clusters: one staging cluster and two production clusters in different regions. Each has its own Helm values file in a Git repository called platform-config.
They define one ApplicationSet with a list generator naming the three clusters. Argo CD creates three Applications, each pointing at the same chart with a different values file. Automated sync, prune and self-heal are on for staging; production uses automated sync but requires a pull request approved by two reviewers before anything reaches the main branch.
A data scientist's new model image, tag 2026.11.03, is merged into the staging values file. Within about three minutes, the default polling interval, Argo CD detects the commit, renders the chart and syncs. Health turns green. After a day of shadow traffic, a pull request updates both production values files. One region becomes Degraded because the new pods request 24 GiB of memory and the nodes have 16 GiB available. The team reverts the commit, Argo CD syncs back, and they fix the resource request before trying again. Later, an engineer patches a production Deployment by hand to debug; self-heal reverts it, which reminds the team that changes must go through Git.
Strengths and limitations
Strengths:
- Git becomes the single, reviewed, auditable record of what runs.
- Continuous drift detection and optional self-healing.
- Supports plain YAML, Kustomize, Helm and plugins.
- A clear web interface showing resource trees, diffs and health.
- Scales to many clusters and teams with projects, RBAC and ApplicationSets.
- Pull-based: clusters fetch changes, so CI systems need no cluster credentials.
Limitations:
- Kubernetes only; other infrastructure needs different tools.
- Secrets need a separate approach, because plain secrets must not be stored in Git.
- Large installations with thousands of applications need tuning of controller sharding and caching.
- GitOps adds a step: urgent fixes still have to pass through Git to persist.
- Progressive delivery, such as canary analysis, needs Argo Rollouts or similar.
How it compares with alternatives
| Tool | Approach | When it fits better |
|---|---|---|
| Flux | CNCF GitOps toolkit of controllers, mostly CLI and Kubernetes resources | Teams preferring a lightweight, composable controller set without a central UI |
| Push-based CI/CD (GitLab CI/CD, Jenkins) | Pipeline runs kubectl or helm upgrade against the cluster |
Simple setups or mixed targets beyond Kubernetes |
| Helm alone | Manual or scripted releases | Small teams with few environments |
| Spinnaker | Multi-cloud continuous delivery platform with pipelines | Complex deployment pipelines across VMs and several clouds |
| Terraform | Declarative infrastructure provisioning | Cloud resources and clusters themselves, rather than in-cluster applications |
Argo CD and Flux follow the same GitOps principles; the choice is mostly about interface, multi-tenancy model and team preference.
Practical guidance and best practices
- Keep application configuration in a separate repository from application source code, so deployments do not trigger on every code commit.
- Pin sources to tags or commit hashes for production, not to moving branches without review.
- Use AppProjects to restrict which repositories, clusters and namespaces each team can deploy to.
- Turn on self-heal for production once teams are used to GitOps; it stops silent drift.
- Handle secrets with a dedicated tool, such as an external secrets operator backed by HashiCorp Vault, or encrypted secrets.
- Use sync waves and hooks for ordered steps like schema migrations.
- Connect Argo CD to single sign-on through OIDC and grant least-privilege RBAC.
- Configure Git webhooks to cut sync delay from minutes to seconds.
- Monitor Argo CD itself, including sync failures and out-of-sync counts, with alerts.
Common mistakes
- Storing plain Kubernetes Secrets in the Git repository.
- Mixing manual
kubectlchanges with GitOps and then being surprised when self-heal removes them. - Pointing production at a branch anyone can push to.
- Turning on pruning without checking which resources Argo CD considers its own, leading to deletions.
- Running one huge Application for an entire cluster, which makes diffs slow and failures hard to isolate.
- Staying on an unsupported 2.x version after its support ended.
Frequently asked questions
Is Argo CD a CI tool?
No. Argo CD handles delivery: keeping clusters in line with Git. Building, testing and publishing images is still done by a CI system, which then updates the configuration repository.
Can Argo CD deploy Helm charts?
Yes. An Application can point at a Helm chart in a Git repository, a Helm repository or an OCI registry, with values supplied inline or from files. Argo CD renders the chart itself and applies the result.
How does Argo CD handle multiple clusters?
One Argo CD instance can register many clusters and deploy to each. ApplicationSets generate an Application per cluster from a template, which keeps fleets consistent.
What happens if someone changes the cluster directly?
Argo CD marks the application as out of sync. With self-heal enabled, it reverts the change automatically; without it, an operator decides whether to sync.
How do rollbacks work?
The cleanest way is reverting the Git commit, so the history stays truthful. Argo CD also offers a rollback to an earlier synced revision, but this is normally disabled for applications with automated sync.
Argo CD or Flux?
Both are mature CNCF GitOps tools. Argo CD offers a rich UI and central multi-team model; Flux offers composable controllers driven mostly by Kubernetes resources. Either works; pick by team workflow.
Glossary
- GitOps: managing systems through declarative configuration stored in Git.
- Application: Argo CD's resource linking a source to a destination.
- AppProject: a boundary limiting where applications may deploy.
- ApplicationSet: a template that generates many Applications.
- Sync status: whether live state matches Git.
- Health status: whether resources are functioning.
- Self-heal: automatic correction of manual drift.
- Prune: removal of resources deleted from Git.
- Sync wave: a number controlling deployment order.
- Argo Rollouts: a companion controller for canary and blue-green deployments.
Summary
Argo CD applies GitOps to Kubernetes: Git holds the desired state, and a controller in the cluster keeps comparing and reconciling live state with it. Created at Intuit in 2018 as part of the Argo project, which graduated in the CNCF in December 2022, it now runs in its 3.x line. It gives teams reviewed changes, drift detection, self-healing and simple rollbacks through Git. It works best with clear repository structure, pinned versions, a proper secrets solution, least-privilege projects and monitoring of the delivery system itself.
Related
It belongs to Platform in my stack, under MLOps and AI infrastructure. Others in the same group: