Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Argo CD Architecture: Components and How They Work Together

Understand the Argo CD components: API server, repo server, application controller, Redis, Dex, ApplicationSet and notifications controllers, and what happens during one reconciliation.

Argo CD is not one program but a small set of cooperating services inside a namespace (usually argocd). Knowing which service does what makes installation, troubleshooting and scaling far easier: when a sync is slow or a manifest will not render, you will know which pod's logs to read.

This lesson describes the real components. The runnable code is a stand-in that models the control flow with plain JavaScript; it does not talk to Kubernetes.

The components

flowchart TB
  User["User: UI, CLI, API"] --> Server["argocd-server: API, UI, auth"]
  Server --> Redis[("argocd-redis: cache")]
  Server --> K8s["Kubernetes API: Application and Secret objects"]
  Controller["argocd-application-controller"] --> K8s
  Controller --> Redis
  Controller --> Repo["argocd-repo-server"]
  Repo --> Git[("Git, Helm and OCI repositories")]
  Server --> Repo
  Server --> Dex["argocd-dex-server: SSO"]
  AppSet["applicationset-controller"] --> K8s
  Notif["notifications-controller"] --> K8s

Everything is stored in Kubernetes objects; Redis is only a cache.

Component Role
argocd-server Serves the web UI, the gRPC and REST API, and handles authentication and RBAC checks.
argocd-repo-server Clones repositories and renders manifests (plain YAML, Helm, Kustomize, plugins). It has no cluster access.
argocd-application-controller Watches Applications and live resources, computes the diff, runs syncs and health checks.
argocd-redis Caches rendered manifests and cluster state. It can be lost without losing data.
argocd-dex-server Optional bridge to identity providers (OIDC, SAML, LDAP, GitHub).
argocd-applicationset-controller Generates many Applications from one template.
argocd-notifications-controller Sends Slack, email or webhook messages when an app changes status.

Where state lives

Argo CD has no database. Its configuration is stored as Kubernetes objects in the argocd namespace:

  • Application and AppProject custom resources hold your applications and their boundaries.
  • Secrets labelled argocd.argoproj.io/secret-type: repository hold repository credentials, and ...: cluster Secrets hold cluster connections.
  • ConfigMaps such as argocd-cm (settings) and argocd-rbac-cm (permissions) hold configuration.

Because everything is a Kubernetes object, you can manage Argo CD itself with Argo CD, which is called the app-of-apps or self-management pattern.

One reconciliation, step by step

  1. The application controller picks up an Application, either because its refresh timer fired (default: every three minutes), a webhook arrived, or someone pressed Refresh.
  2. It asks the repo server for the manifests at the target revision. The repo server fetches (or reuses) a clone, runs Helm, Kustomize or plain directory rendering and returns plain Kubernetes objects.
  3. The controller reads the live objects from the destination cluster (from its cache, fed by watches).
  4. It computes the diff. No differences means Synced; otherwise OutOfSync.
  5. If automated sync is on, it applies the changes. Then it evaluates health from the live resources.
  6. It writes the result into the Application's status, which the UI and CLI read.

The repo server is a good example of least privilege: the component that touches arbitrary Git content and runs templating tools has no credentials for your clusters.

A model of the flow

The stand-in below is a miniature controller. It "renders" desired objects, compares them with a pretend cluster and decides on a sync action. Change the cluster contents and the autoSync flag to see different outcomes.

JS Stand-in: controller loop

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the leftover ConfigMap/old is only a prune candidate: Argo CD does not delete extra resources unless pruning is enabled (see Sync Policies).

How fast does it react?

By default the controller re-checks each Application about every three minutes (timeout.reconciliation in argocd-cm, 180 seconds, with a small random jitter so thousands of apps do not refresh at once). Two things speed it up:

  • Webhooks: GitHub, GitLab, Bitbucket and others can call /api/webhook on argocd-server when you push; the affected Applications refresh immediately.
  • Manual refresh: the Refresh button, argocd app get <name> --refresh or --hard-refresh (which also drops cached manifests).

Watches on live resources are continuous, so a manual change in the cluster shows up as OutOfSync almost at once; only Git changes depend on polling or webhooks.

This second stand-in shows why a webhook matters by computing how long a change waits.

JS Stand-in: detection latency

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Scaling notes

  • The application controller runs as a StatefulSet and can be sharded: each replica handles a subset of clusters.
  • The repo server can be scaled out horizontally; render-heavy monorepos benefit most.
  • argocd-server is stateless; run several replicas behind a load balancer.
  • Redis can be run in HA mode (a separate install manifest) for production.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which component renders Helm charts and Kustomize overlays into plain manifests?

    The repo server clones repositories and runs the templating tools; it has no cluster credentials.
  2. 2. Where does Argo CD keep Application definitions?

    Applications and projects are custom resources; Redis is just a cache.
  3. 3. What is the default interval at which the controller re-checks Git for an Application?

    The default is 180 seconds, and webhooks can trigger an immediate refresh.
  4. 4. Losing the Redis pod would cause which outcome?

    Redis is only a cache. Configuration lives in Kubernetes objects.

Summary

  • Seven components: server, repo server, application controller, Redis, Dex, ApplicationSet and notifications controllers.
  • The repo server renders manifests; the controller diffs, syncs and checks health.
  • All configuration lives in Kubernetes objects, so Argo CD can manage itself.
  • Git changes are found by polling (3 minutes by default) or instantly with webhooks.
  • Controllers and repo servers can be scaled and sharded.

Next: Installing Argo CD