Chapter 1. Argo CD Agent architecture overview

The Argo CD Agent introduces an opinionated mechanism for managing multiple clusters by using Argo CD in a hub-and-spoke configuration. Argo CD Agent, configured alongside Argo CD, enables the familiar Argo CD Web console, but extends its capabilities to allow you to simultaneously configure and monitor multiple, separate Argo CD instances from a single location.

Unlike a traditional single-instance Argo CD deployment, the Argo CD Agent architecture provides a single pane of glass for monitoring and managing Argo CD Applications across multiple clusters.

Argo CD Agent works alongside Argo CD to manage multi-cluster deployments in a hub-and-spoke architecture using a standalone agent process, enabling pull-based change management.

In this architecture, a single hub (referred to as the control plane cluster) manages the configuration for multiple spokes (known as workload clusters), each of which runs its own Argo CD instance.

View larger image

The Argo CD Agent architecture offers several advantages and tradeoffs compared to the traditional push-based hub-and-spoke model.

Each Argo CD Agent on a cluster manages the local Argo CD instance and ensures that applications, AppProjects, and secrets remain synchronized with their source of truth.

The Agent performs the following key functions:

Resource synchronization

Unified observability

The Argo CD Agent supports two operational modes that determine where the authoritative source of truth for the Application .spec field resides:

You can also use a mixed mode configuration, where different clusters operate under different modes.

The Argo CD Agent architecture uses mutual TLS (mTLS) certificates to secure communication between the principal Agent (hub) and workload Agents (spokes). mTLS certificates are more secure than traditional password-based authentication, unlike passwords, mTLS certificates allow for certificate expiration, certificate rotation, as well as subject verification to prevent Man-in-the-Middle (MITM) attacks.

A root CA certificate signs both the principal and agent certificates.

The following points describe how certificate-based authentication and trust are established between the control plane (principal) and the agents in the Argo CD Agent architecture:

The Argo CD Agent architecture on the control plane cluster uses the Applications in any namespace feature to separate the Application resources that originate from individual workload clusters. This feature enables the control plane Argo CD instance to reconcile Applications that are defined outside its own namespace while maintaining strict isolation between workload clusters.

Each workload cluster is assigned a dedicated namespace on the control plane cluster. These namespaces act as source namespaces for the control plane Argo CD instance, and each contains only the Applications for a single workload cluster.

For a control plane cluster with three workload clusters (w1, w2, and w3), the namespaces are organized as follows:

View larger image

The argocd-w1, argocd-w2, and argocd-w3 namespaces are treated as source namespaces. Although these namespaces are outside the main Argo CD installation namespace (argocd), the control plane Argo CD instance still discovers and reconciles the Applications stored within them.

Applications in each argocd-w* namespace are scoped to a single cluster. For example, no Applications from workload cluster w2 are defined in the argocd-w3 namespace.

Each workload cluster maintains its own argocd namespace that hosts its local Argo CD and Argo CD Agent instances. The Applications defined in the control plane namespace argocd-w1 are synchronized to the argocd namespace on workload cluster w1, and the same pattern applies to workload clusters w2 and w3.

To enable the control plane Argo CD instance to discover and reconcile Applications from these workload-specific namespaces, configure the sourceNamespaces field in the Argo CD CR:

apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: argo-cd
spec:
  sourceNamespaces:
    - argocd-w1
    - argocd-w2
    - argocd-w3
  # (...)

apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: argo-cd
spec:
  sourceNamespaces:
    - argocd-w1
    - argocd-w2
    - argocd-w3
  # (...)

With this configuration, the control plane Argo CD instance monitors and reconciles the Applications from each source namespace as part of the overall multi-cluster environment.

The Argo CD Agent feature is under active development. The following limitations are currently applicable for this feature: