Skip to content
Documentation Background

Argo CD architecture

Argo CD applies the Kubernetes design to application delivery. Custom resources describe what should run, and controllers running a nonterminating loop make the cluster match. Understanding that loop, the three custom resources, and the handful of services around them explains most of Argo CD’s behavior.


A Kubernetes controller runs a loop that never ends. It reads the desired state, observes the actual state, and acts on any difference. The built-in ReplicaSet controller is the classic example: it watches the Pods belonging to a ReplicaSet and creates or deletes Pods until the count matches the spec. The Kubernetes architecture page covers the control plane controllers.

flowchart LR
    D["Desired state"] --> C["Controller"]
    C -->|"observes"| A["Actual state"]
    C -->|"acts on the difference"| A

Argo CD keeps this loop but changes the source of desired state. Instead of a spec inside the cluster, the target is a set of manifests in Git or a Helm repository. When someone changes a resource in the cluster by hand, the loop notices the divergence. Argo CD calls the practice of keeping configuration intact despite manual or external changes drift management.


ConfigMaps and Secrets hold flat key/value data such as server settings, repository connections, and keys. They cannot express a richer domain model. A CustomResourceDefinition (CRD) registers a new resource type with the Kubernetes API server. It defines the allowed fields and validation rules and exposes a new API endpoint, so kubectl manages the new type like any built-in one.

An operator pairs a nonterminating control loop with a CRD. The controller embeds knowledge of the domain, so it can interpret the fields of a custom resource and drive the cluster toward what they describe.

Every standard Argo CD installation provides three custom resources. They are the main API for managing clusters with GitOps.

ResourcePurpose
ApplicationDeclares one deployed application instance. It binds a source (a Git or Helm repository) to a destination cluster and namespace
AppProjectGroups applications into a logical unit with access boundaries and resource restrictions, the basis of multi-tenancy
ApplicationSetGenerates and manages many Application resources from a template, typically across clusters

Two operators watch these resources. The application controller watches Application resources, compares live cluster state with the source, and carries out the sync lifecycle, including the order in which manifests are applied. The ApplicationSet controller watches ApplicationSet resources and creates the Applications they describe.


flowchart TD
    Clients["Web UI, CLI, CI systems"] --> API["API server"]
    API --> Redis["Redis cache"]
    Ctrl["Application controller"] --> Repo["Repo server"]
    Ctrl --> Redis
    Repo --> Git["Git and Helm repositories"]
    Ctrl --> Target["Target clusters"]

A standard installation runs these workloads in the argocd namespace.

ComponentWorkloadRole
Application controllerStatefulSet argocd-application-controllerOperator that reconciles Applications and executes syncs
ApplicationSet controllerDeployment argocd-applicationset-controllerOperator that generates Applications from ApplicationSets
Repo serverDeployment argocd-repo-serverFetches sources and renders manifests
API serverDeployment argocd-servergRPC and REST endpoint, serves the web UI
RedisDeployment argocd-redisVolatile cache
DexDeployment argocd-dex-serverIdentity bridge for single sign-on
Notifications controllerDeployment argocd-notifications-controllerSends alerts when application state changes

The repo server keeps a local cache of the remote Git and Helm repositories and turns source configuration into plain Kubernetes manifests. The inputs are the repository type, source location, path, and tool-specific options. It also runs custom plugin scripts when a source needs rendering that Helm, Kustomize, or Jsonnet cannot do.

The API server accepts both gRPC and REST connections and is the backend for the web UI, the CLI, and external CI/CD systems. It reports application status, runs operations such as sync and rollback, manages clusters and repositories, and enforces role-based access control (RBAC). The web UI it serves shows the application resource tree and live health. The CLI talks to the same API and exposes a superset of what the UI offers.

Redis is an in-memory cache that cuts latency and spares the source repositories repeated requests. It stores repository files, the connection status of clusters and repositories, and the live state of Kubernetes resources. Nothing in it is persistent: Argo CD rebuilds the cache at startup. The default installation protects Redis with a password stored in the argocd-redis Secret.

Argo CD accepts local accounts or identities from an external OpenID Connect (OIDC) provider. For identity providers that cannot speak OIDC directly, the bundled Dex server acts as the bridge.

The notifications controller watches for changes in application state and sends alerts to channels such as Slack, email, or a webhook. Predefined triggers and templates decide when to send and what the message says.


  • Declarative - Applications, AppProjects, and ApplicationSets are declarative resources, and so are the server settings kept in ConfigMaps and Secrets. Argo CD’s own installation can therefore live in Git and be managed by Argo CD itself.
  • Stateless - the system state can be regenerated from its source repositories at any time. Where history or progress must be tracked, Argo CD uses the standard Kubernetes status field of the resource instead of a database of its own.
  • Extensible - sources can be Git or Helm repositories. Helm, Kustomize, and Jsonnet are supported natively, and custom plugins can render anything else or call external systems.