Skip to main content
Lexicon
Lexicon
Argo CD

Argo CD

Difficulty: Intermediate
6 min read
Updated 2026-08-19

In plain English

Plain definition

Argo CD is a tool that keeps applications running on Kubernetes in sync with a set of configuration files stored in a Git repository. When someone changes the files in Git, Argo CD notices the difference and can update the running cluster to match. When someone changes the cluster directly without going through Git, Argo CD flags this as drift so a team can decide what to do about it.

How Argo CD compares Git with the cluster

Argo CD runs as a set of controllers inside a cluster (API server, repository server, application controller and, optionally, a notifications controller) and continuously compares the desired state defined in a Git repository against the live state of Kubernetes resources. Desired state is typically expressed as plain Kubernetes manifests, Kustomize overlays, Helm charts or other supported templating tools. Argo CD represents each managed deployment unit as an Application custom resource, which records the source repository, target revision, destination cluster and namespace, and the synchronisation policy. Reconciliation can be manual or automated, and Argo CD reports application health and sync status through its API, CLI and web UI.

Why teams put Git in charge

Argo CD turns Git into the single source of truth for what should be running in a cluster, instead of leaving it to whoever runs ad hoc kubectl commands. This gives teams an auditable change history, since every intended change passes through version control and, typically, a review process before it reaches the cluster. Its drift detection also shows unauthorised or accidental manual changes, which are otherwise hard to spot in a live Kubernetes environment. That is why Argo CD often becomes the control point for release management, incident response investigations into who changed what, and enforcing that production configuration is reproducible from a known, reviewed source.

Between Git and the cluster

Argo CD sits between a Git repository and one or more Kubernetes clusters, and depends on a working Kubernetes API server and appropriate role-based access control to apply resources. It is commonly deployed alongside a CI pipeline that builds and tests artefacts and pushes updated manifests or image references into the Git repository that Argo CD watches. Argo CD itself builds and tests nothing: it only reconciles state. It can manage a single cluster or many, and can be extended with notification integrations, image update automation and single sign-on, but these are separate optional components layered on top of the core reconciliation loop. Because it holds a privileged view into cluster state, its own access to Git credentials and cluster permissions is itself a material part of the environment’s security boundary.

A merged change to a payments service

A platform team stores Kubernetes manifests for a payments service in a Git repository. An Argo CD Application resource points at that repository and a target namespace. When a developer merges a change to the deployment manifest, Argo CD detects that the live state in the cluster no longer matches the Git-defined desired state and either applies the change automatically, if automated sync is enabled, or surfaces it as “OutOfSync” for a human to approve, depending on the configured sync policy.

What Argo CD does not do

Argo CD is not a CI system: it does not build container images or run tests. Its role begins after an artefact or manifest already exists in Git, and it is solely responsible for delivering and reconciling that already-built state into Kubernetes. Nor does automated sync always self-heal every manual change immediately. By default, changes made directly to the live cluster do not trigger an automated sync. They are reverted automatically only when self-heal is enabled, and otherwise persist and show as OutOfSync until a sync is run.

Terms that come up with Argo CD

  • GitOps
  • Kubernetes
  • Helm
  • Kustomize
  • Continuous delivery

Further Reading

Consult the official Argo CD documentation (argo-cd.readthedocs.io) for authoritative detail on configuration options, sync policies and version-specific behaviour before relying on any specific implementation detail in a production environment.

Check these before you adopt it

Before you rely on Argo CD as a control point for a bounded workflow, confirm in a non-production or isolated cluster that the reconciliation behaviour matches expectations for the deployed version, that RBAC and Git credential scopes follow least privilege, and that a rollback path exists if an automated sync introduces an unwanted change.

  • Confirm the installed Argo CD version and permissions before enabling automated sync on any production Application.
  • Test that sync policies and health checks behave as documented in an isolated test namespace before promoting the pattern.
  • Scope the Git repository access and cluster RBAC granted to Argo CD to only the namespaces and resources it needs.
  • Confirm a rollback path exists, such as reverting the Git commit or disabling automated sync, before enabling self-heal in production.

About this page

Credited to

Dates

Published

Corrections

No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.

Was this useful?

Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.