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.
The controller pattern
Section titled “The controller pattern”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.
Custom resources and operators
Section titled “Custom resources and operators”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.
| Resource | Purpose |
|---|---|
| Application | Declares one deployed application instance. It binds a source (a Git or Helm repository) to a destination cluster and namespace |
| AppProject | Groups applications into a logical unit with access boundaries and resource restrictions, the basis of multi-tenancy |
| ApplicationSet | Generates 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.
Core components
Section titled “Core components”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.
| Component | Workload | Role |
|---|---|---|
| Application controller | StatefulSet argocd-application-controller | Operator that reconciles Applications and executes syncs |
| ApplicationSet controller | Deployment argocd-applicationset-controller | Operator that generates Applications from ApplicationSets |
| Repo server | Deployment argocd-repo-server | Fetches sources and renders manifests |
| API server | Deployment argocd-server | gRPC and REST endpoint, serves the web UI |
| Redis | Deployment argocd-redis | Volatile cache |
| Dex | Deployment argocd-dex-server | Identity bridge for single sign-on |
| Notifications controller | Deployment argocd-notifications-controller | Sends alerts when application state changes |
Repo server
Section titled “Repo server”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.
API server
Section titled “API server”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.
Notifications controller
Section titled “Notifications controller”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.
Design traits
Section titled “Design traits”- 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
statusfield 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.