Argo CD's control plane, taken apart

A design-level tour of how Argo CD’s control plane is built — the components, the reconcile loop, and no database of its own.

Written against the Argo CD v3.x line · Version-sensitive claims marked current as of 2026-07-01 — re-verify against release notes before you rely on them.

At a glancethe whole control plane in one diagram

Before we take the components apart one by one, here they all are at once — every service in the control plane, plus the two things it treats as the source of truth: Git (desired state) and your managed clusters (live state). The numbered path traces a single change from the front door to the cluster; the sections that follow walk the same path one box at a time.

API serverthe stateless gateway every client goes through

The argocd-server is the gRPC/REST gateway — what the Web UI, the argocd CLI, and your CI/CD systems talk to, and the only component most humans ever touch directly.

Its responsibilities are broad but shallow: application management and status reporting, invoking operations (sync, rollback, user-defined actions), managing repository and cluster credentials (as Kubernetes secrets), authentication (delegated to external identity providers), RBAC, and forwarding git webhook events.

Dexoptional SSO federation

The argocd-dex-server is a bundled OIDC provider that federates your identity system into Argo CD — because not every provider speaks OIDC cleanly, and not every OIDC provider exposes what Argo CD needs (like group membership).

The decision:

• Use direct OIDC (the oidcConfig setting, no Dex) when you already run an OIDC-compliant provider — Okta, Auth0, Keycloak, Google, Microsoft Entra. It's simpler: one fewer component, and Argo CD talks to your IdP directly.
• Use Dex when your provider doesn't do OIDC (SAML, LDAP), or when you want a connector feature Dex provides — the classic one being mapping GitHub organizations and teams into OIDC group claims for RBAC. Dex can also fetch groups the IdP won't put in the ID token (Google is the usual example).

Repo-serverturns Git into rendered manifests

The argocd-repo-server answers one question: given this repo, revision, and path, what are the Kubernetes manifests? It caches the rendered output in Redis keyed by repo, revision, and path, so repeated reconciliations of an unchanged source cost nothing (--repo-cache-expiration, 24h default).

The same app three ways — what you write, what lives in Git, and what the repo-server hands the controller:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/acme/deploy.git
    targetRevision: main
    path: apps/web             # repo-server clones + renders this
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    automated:                 # auto-sync + self-heal
      selfHeal: true
      prune: true

# apps/web/ in the git repo -- a Helm chart (config kept DRY)
apps/web/
  Chart.yaml
  values.yaml                  # replicaCount: 3, image.tag: v1.4.2
  templates/
    deployment.yaml
    service.yaml

# what repo-server returns over gRPC, cached in Redis
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: web
          image: ghcr.io/acme/web:v1.4.2

Application-controllerthe reconciliation engine

The argocd-application-controller is where reconciliation actually happens — a Kubernetes controller that, for every Application, runs the loop the figure below traces.

An Application is not a workload

One term to pin down before we go on: an Application. It sounds like your running app, but it isn’t one. An Application is an Argo CD custom resource — a small record that says “keep this git path synced to this cluster and namespace.” It runs no containers. When Argo syncs it, it applies ordinary Kubernetes objects — a Deployment, a ReplicaSet, some Pods — and those run your code.

The two even live in different places. The Application objects are Kubernetes resources in the argocd namespace, generated from git and reconciled by the application-controller. The Deployment → ReplicaSet → Pods they produce live in the target cluster, run by Kubernetes’ own controllers. Argo just keeps that second set matching git — and reports Synced (matches git?) and Healthy (Pods up?).

Two triggers, one loop

The application-controller runs the same reconcile on two triggers. An event — a Git webhook, or an edit to an Application spec — refreshes just the affected app, so a push lands in seconds. A periodic timer (roughly every three minutes by default) re-syncs every app regardless, catching drift the events missed. The figure below contrasts the two.

A change, end to end

When the webhook fires, the change threads through the whole control plane: the API server records it, the repo-server renders the manifests, and the application-controller diffs desired against live and syncs the delta into the cluster. The numbered path traces one commit from Git to running pods, alongside the ApplicationSet flow that generated the Application in the first place.

The periodic sweep

The same machinery also runs on a clock. Instead of one webhook refreshing one app, the timer sweeps every managed Application in turn — re-rendering and re-reconciling each so nothing drifts silently. It is the bulk safety net to the webhook’s targeted, on-demand refresh.

Redisthe disposable cache

Redis holds the caches: rendered manifests, observed live state, and diff results. The docs are blunt — it is "only used as a disposable cache and can be safely rebuilt without service disruption."

If Redis vanishes, nothing permanent breaks: the controller and repo-server rebuild their caches from git and the live clusters. You get a brief load spike on git and the Kube API while caches warm, and slower UI/reconciles for a few minutes. No Application is lost, no sync undone, no desired state forgotten — none of it ever lived in Redis.

ApplicationSet controllerone template, many Applications

A raw Application describes one deployment to one place — it doesn't scale to "this app on all 40 clusters." The ApplicationSet controller (its own controller, a separate project until it merged into core Argo CD in v2.3 — initially beta) owns the ApplicationSet CRD and generates, updates, and deletes Application resources from a single template. v2.3+

The power is in the generators — they produce the parameter sets substituted into the template, one Application per set (Matrix / Merge compose two generators, e.g. every app from Git × every cluster from Cluster). The ApplicationSet controller doesn't reconcile against clusters itself.

Zoom in on where those Applications come from — the same web fleet, seen from the ApplicationSet controller’s side:

One ApplicationSet fans a single template out into one Application per cluster:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: web-fleet
  namespace: argocd
spec:
  generators:
    - clusters: {}             # one param set per registered cluster
  template:
    metadata:
      name: 'web-{{name}}'     # {{name}} / {{server}} filled per cluster
    spec:
      project: default
      source:
        repoURL: https://github.com/acme/deploy.git
        targetRevision: main
        path: apps/web
      destination:
        server: '{{server}}'
        namespace: web

# the controller renders one Application per cluster the generator saw,
# then syncs each exactly like a hand-written app
web-eu-prod     -> https://eu-prod.example.com
web-us-prod     -> https://us-prod.example.com
web-ap-staging  -> https://ap-staging.example.com

Notifications controllerturning state changes into messages

The notifications controller (originally the separate argocd-notifications project, now folded into core) watches Application state and emits notifications. Its model is two-part:

• Triggers define when. A trigger is a named condition — a predicate expression (evaluated by the antonmedv/expr engine) — that returns true when a notification should fire, plus a reference to the templates to use. The oncePer field deduplicates, so you get one message per observed git revision rather than one per reconcile.
• Templates define what. A template (Go html/template, configured in the argocd-notifications-cm ConfigMap) renders the message body. Templates are reusable and referenced by multiple triggers.

The rendered message goes out through a configured service — Slack, a generic webhook, email. Like Dex, it sits off the critical path: if it's down, deployments still reconcile; you just aren't told about them.

Commit-serverwrites hydrated manifests back to Git (v3.x)

The newest and most architecturally interesting addition. Be precise about its status: the Source Hydrator is an alpha feature, introduced in the v3.x line and actively evolving through v3.1 and v3.3. v3.x, alpha, re-verify

The problem it solves. Helm and Kustomize keep config DRY but hide the actual manifests that hit the cluster — when something breaks at 2am you have to reproduce the render locally to see it. The Source Hydrator implements the "rendered manifest pattern": it renders the templates and commits the plain manifests back to a git branch before syncing, so git shows exactly what will be applied.

The flow uses three fields on spec.sourceHydrator:

• drySource — where the templates live (repoURL, path, targetRevision). The "dry" (DRY) source.
• syncSource — the branch where hydrated manifests are pushed and then synced from.
• hydrateTo — an optional staging branch, so hydrated output can go through review/approval before it lands on the sync branch.

Output must be deterministic — the same dry commit must always hydrate to the same manifests, so no unpinned dependencies or non-deterministic template functions. (And don't pair it with secret-injecting tools like Helm+SOPS, or you'd commit secrets to git; use a secrets operator on the destination instead.)

Why the commit-server is its own component

Pushing to git needs write credentials, and every other component that touches git — the repo-server — only ever reads. Rather than hand write access to the read component, v3.x introduced a dedicated argocd-commit-server whose entire job is git writes for hydrated manifests.

It exposes a single gRPC call, CommitManifests, carrying the target repo and branch, the dry commit's provenance (full SHA256, author, message, time), and the rendered manifests. The controller builds the request; the commit-server performs the push.

The rationale is blast radius. Git write credentials now live in one small, single-purpose service instead of being smeared across the component that also clones arbitrary repos and runs templating tools. If something gets push access to your source of truth, you want it to be the least-exposed component you have — the whole reason the commit-server is a separate box.

The Source Hydrator in YAML — the spec, the DRY template on main, and the plain manifest the commit-server writes to the sync branch:

spec:
  sourceHydrator:
    drySource:                 # templates live here (DRY)
      repoURL: https://github.com/acme/deploy.git
      path: apps/web
      targetRevision: main
    syncSource:                # plain YAML is committed + synced here
      targetBranch: env/prod
      path: apps/web
    hydrateTo:                 # optional staging branch for review
      targetBranch: env/prod-next

# apps/web/values.yaml on main -- the actual manifests are hidden
# behind Helm templating until they are rendered
replicaCount: 3
image:
  repository: ghcr.io/acme/web
  tag: v1.4.2

# apps/web/manifests.yaml on env/prod -- plain YAML the
# commit-server wrote; git now shows exactly what hits the cluster
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  template:
    spec:
      containers:
        - {name: web, image: ghcr.io/acme/web:v1.4.2}

The state modelthree stores of truth, one loop

Argo CD is a GitOps controller, and it keeps its truth in exactly three stores. Git holds the desired state — the manifests, or the templates that render into them. The managed cluster’s own etcd holds the live state: the running Kubernetes objects and the Application custom resources both live there. And Redis is a disposable cache of rendered manifests — throwaway, safe to delete, never a source of truth. Git and the cluster’s etcd are external to Argo CD; only Redis is its own.

One reconcile loop runs across all three. The application-controller (1) reads the desired manifests from Git — rendered by repo-server, (2) reads the live state back from the cluster’s etcd, (3) diffs desired against live, (4) syncs the delta into the cluster, and (5) caches the rendered manifests in Redis so the next pass stays cheap. That’s the whole storage story: no relational database, no external queue, no object store. Wipe every Argo CD pod and its Redis, reinstall, and it rebuilds its entire world from Git and the clusters — which is what makes everything else as disposable as it is. Every component below either feeds that loop, runs it, or reacts to its output.

Putting it togetherone change through the whole loop

Nowhere in that path is there a write to an Argo CD datastore, because there is no such datastore. The desired state was already in git; the live state ends up in the cluster's etcd; Redis just made it faster.

In productionthe HA topology worth running

Argo CD ships HA manifests for production that encode the scaling story component by component:

Two practical constraints in the HA install: it wants at least three nodes (pod anti-affinity rules spread the replicas), and IPv6-only clusters aren't supported.

Watch-outsthe pitfalls to plan for

• A cold Redis is a thundering herd. Losing Redis is safe but not free — a large fleet warming its cache can spike load on git and the Kube API. HA Redis avoids the event entirely.
• The repo-server serializes mutating renders. One clone per instance plus single-concurrency mutation means monorepos with heavy templating bottleneck here first. Scale repo-server replicas.
• The Source Hydrator is alpha and must be deterministic. Non-deterministic renders will commit noise to git on every pass, and secret-injecting tools will leak secrets into git. Don't adopt it casually. re-verify status

GroundingSources

• Argo CD docs — Architectural Overview: https://argo-cd.readthedocs.io/en/stable/operator-manual/architecture/
• Argo CD docs — Component Architecture (developer guide): https://argo-cd.readthedocs.io/en/stable/developer-guide/architecture/components/
• Argo CD docs — High Availability: https://argo-cd.readthedocs.io/en/stable/operator-manual/high_availability/
• Argo CD docs — Source Hydrator (v3.0): https://argo-cd.readthedocs.io/en/release-3.0/user-guide/source-hydrator/
• Argo CD docs — Commit Server proposal: https://argo-cd.readthedocs.io/en/latest/proposals/manifest-hydrator/commit-server/
• Argo CD docs — User Management / SSO (Dex vs OIDC): https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/
• Argo CD docs — ApplicationSet controller & Generators: https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/
• Argo CD docs — Notifications (triggers & templates): https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/
• DeepWiki (argoproj/argo-cd) — State Comparison and Diff Engine: https://deepwiki.com/argoproj/argo-cd/3.3-state-comparison-and-diff-engine
• CNCF — Argo CD v3 announcement (Apr 2025): https://www.cncf.io/announcements/2025/04/01/cloud-native-computing-foundation-announces-argo-cd-v3-update-to-enhance-scalability-and-security-for-kubernetes/
• InfoQ — Argo CD v3.1 (OCI support, UI): https://www.infoq.com/news/2025/08/argocd-oci-support-new-ui/

Version-sensitive claims (Source Hydrator/commit-server maturity, v3.x feature states) are current as of 2026-07-01 and should be re-verified against the Argo CD release notes before you rely on them.