For most teams running Argo CD across several clusters, hub-and-spoke (one central Argo CD managing many target clusters) is the right default, with standalone Argo CD per cluster reserved for strict tenancy or regulatory isolation. Start now by registering your clusters, building an ApplicationSet with the Cluster generator, and locking down authentication with Workload Identity or Connect Gateway instead of static tokens. The sections below walk through each step in order.
TL;DR:
Choose standalone Argo CD per cluster when tenancy, regulatory rules, or network segmentation require isolation; otherwise, a central instance needs reliable access to every target.
Use argocd cluster add CONTEXT or store cluster Secrets in Git; the ApplicationSet Cluster generator creates apps per cluster and rollouts selected by labels.
Where supported, use Workload Identity with Connect Gateway instead of static service account tokens, scope Argo CD permissions narrowly, and rotate credentials on a schedule.
For apps running across clusters, DNS or a load balancer can split regional traffic; multi cluster Istio adds request routing and upkeep.
Table of Contents
-
Registering clusters with the Argo CD CLI and declarative secrets
-
Why the real bottleneck in multi-cluster Argo CD is rarely Argo CD itself
-
Where Kubezilla Desktop fits alongside your Argo CD workflow
Choosing between hub-and-spoke and standalone Argo CD
Hub-and-spoke puts one Argo CD instance in control of every target cluster, giving you a single pane for sync status, fewer upgrades to manage, and centralized RBAC. The tradeoff is network reachability: your hub needs a path to every spoke, and permissions get more complex as teams and clusters multiply. Standalone Argo CD, with one instance per cluster, trades that complexity for isolation: simpler per-cluster RBAC, no cross-cluster network dependency, but more instances to patch and monitor. Common patterns documented by Red Hat Developer frame this exact choice as the first architectural decision operators make, and note that regulatory or network segmentation requirements often settle the question before preference does.
Before connecting anything, prepare the following:
-
Valid kubectl contexts for every cluster you plan to register.
-
Privileged access on target clusters to create the service account Argo CD needs.
-
A consistent Argo CD version across hub and spokes to avoid API drift.
-
Git repository access configured and tested from the hub.
-
Observability tooling in place so you can see sync and health status per cluster.
Registering clusters with the Argo CD CLI and declarative secrets
Once you have picked a topology, connecting clusters is mostly mechanical. The Argo CD Operator manual covers two methods: the CLI and declarative Secrets.
-
Run
argocd cluster add CONTEXTto register a cluster; this creates an argocd-manager ServiceAccount and cluster role binding on the target so Argo CD can reconcile resources there. -
Confirm registration with
argocd cluster list, and inspect a specific entry withargocd cluster get. -
Remove a cluster with
argocd cluster rmwhen it is decommissioned, and rotate credentials periodically withargocd cluster rotate-auth, as documented in the cluster command reference. -
For GitOps-managed cluster inventory, skip the CLI and create a Kubernetes Secret labeled
argocd.argoproj.io/secret-type: clusterinstead, so cluster definitions live in Git alongside everything else.
The in-cluster entry (the cluster Argo CD itself runs on) is registered by default and cannot be removed through the normal commands; you disable it by setting cluster.inClusterEnabled to false in the argocd-cm ConfigMap.
Pro Tip: Prefer declarative secrets over CLI-added clusters once you have more than a handful; it keeps your cluster inventory versioned and reviewable like everything else in Git.
Targeting clusters at scale with ApplicationSets
Manually writing one Application manifest per cluster does not scale past a handful of targets. The ApplicationSet Cluster generator solves this by reading your registered cluster Secrets and exposing fields like name and server for template substitution, with goTemplate support for more complex string manipulation.
A few patterns cover most real deployments:
-
Per-cluster Application: the generator produces one Application per registered cluster, each pointing at the same Git path but a different destination server.
-
Label-scoped rollouts: attach labels such as
env: stagingorregion: eu-westto cluster secrets, then use a selector so the ApplicationSet only targets matching clusters, for example deploying guestbook to every cluster labeledtype=staging. -
flatList aggregation: instead of generating many near-identical Applications, flatList mode produces a single Application that aggregates values across all matched clusters, useful when one logical app needs a combined values file rather than per-cluster duplicates.
This combination lets a platform team add a new cluster, label it correctly, and have workloads land automatically without touching the ApplicationSet definition again.
Authentication and credential management across clusters
Every registered cluster needs credentials Argo CD can use to reconcile resources, and how you manage those credentials matters as much as the topology you choose. Long-lived service account tokens are the default that argocd cluster add creates, but they are also the weakest option from a security standpoint: a leaked token grants standing access until someone notices and rotates it.
Where your platform supports it, prefer identity-based alternatives. Google Cloud’s guidance on GKE fleets recommends Workload Identity paired with Connect Gateway specifically to avoid static service-account tokens when Argo CD manages clusters across projects or cloud providers.
-
Scope the argocd-manager role to the namespaces and verbs it actually needs rather than granting cluster-admin by default.
-
Rotate credentials on a schedule using
argocd cluster rotate-auth, not only after an incident. -
Store cluster secrets inside the argocd namespace and manage them through automation so manual edits do not cause drift between Git and the live cluster list.
Pro Tip: If you are managing clusters across more than one cloud provider, standardize on whichever identity mechanism each provider offers natively instead of forcing one token format everywhere.
Routing traffic across active-active multi-cluster apps
Registering clusters and syncing manifests solves deployment, but active-active workloads also need a plan for where traffic goes. The most common approach is DNS-based routing: deploy the same application to two or more clusters, then use weighted DNS records or a global load balancer to split traffic between regions. This keeps the networking layer simple and works well when clusters are geographically separated.
For teams that need finer-grained control, service mesh options such as multi-cluster Istio add mutual TLS, request-level routing, and cross-cluster observability on top of basic DNS, at the cost of more operational surface area to maintain.
Whichever approach you pick, validate it before relying on it in production:
-
Confirm readiness and liveness probes behave consistently across every cluster running the app.
-
Keep configuration parity between regions so a failover does not surface unexpected differences.
-
Run deploy-time tests that exercise cross-cluster failover, not just single-cluster health.
Best practices for keeping multi-cluster Argo CD consistent
Running Argo CD across many clusters is as much an operations problem as a deployment one. A short runbook keeps drift and surprises to a minimum.
-
Treat your cluster inventory as code: generate cluster secrets through automation or plugins such as fleet-argocd-plugin, rather than adding clusters by hand, since Red Hat’s guidance notes this directly reduces drift between what actually exists and what Argo CD believes exists.
-
Roll out changes with per-cluster canaries or staged waves, using ApplicationSet label selectors to control which clusters receive a change first.
-
Monitor application health, cluster reachability, sync events, and your credential rotation schedule as one connected picture, not four separate dashboards.
One registered cluster secret, one source of truth: keeping cluster definitions in Git alongside Application manifests, as described in the Argo CD operator manual, means a cluster’s permissions and its workloads are reviewed through the same pull request process.
What hands-on operators learn the hard way
Most multi-cluster pain shows up at the edges, not in Argo CD itself: a kubeconfig that points at the wrong context, a credential that quietly expired, a log stream you have to dig for across three terminal tabs. Operators managing a growing cluster fleet typically accumulate kubeconfig sprawl faster than they standardize on a system to manage it, which turns a five-minute troubleshooting task into a thirty-minute hunt for the right context.
A desktop tool that keeps kubeconfigs organized and surfaces Argo CD operations directly, without routing through a browser tab or a separate CLI session, shortens that hunt considerably. When a sync fails at 2 AM, the time saved is in not having to remember which of six contexts belongs to which environment.
Why the real bottleneck in multi-cluster Argo CD is rarely Argo CD itself
Most advice on this topic treats architecture choice (hub-and-spoke versus standalone) as the hard problem, and it does deserve the attention it gets. But once that decision is made, it rarely changes again. The recurring cost, week after week, is operational friction: context switching between clusters, hunting for the right kubeconfig, tracing a failed sync back to a stale credential.
Teams that invest heavily in ApplicationSet patterns and authentication hygiene but keep their day-to-day tooling scattered across browser tabs and ad hoc terminal windows tend to underestimate how much time that scattering costs. The fix is rarely a bigger architecture overhaul. It is tightening the loop between “something looks wrong” and “I can see logs, events, and sync status for the right cluster.” Prioritize that loop before you chase a more elaborate topology, because a clean hub-and-spoke setup still feels slow if every troubleshooting session starts with ten minutes of context hunting.
— Margus
Where Kubezilla Desktop fits alongside your Argo CD workflow
Managing kubeconfigs for a growing cluster fleet gets tedious fast, and that is exactly where Kubezilla Desktop earns its place next to Argo CD. We store kubeconfigs securely on your machine, with no cloud sync, so switching between the cluster you registered this morning and the one you registered last month takes a click instead of a context juggle.
-
Jump between clusters instantly instead of editing kubeconfig files by hand.
-
Stream logs and open a pod terminal in the same window where you are reviewing an Argo CD sync.
Our Rust-built desktop app runs light on resources and keeps Helm and Argo CD operations one click away. See it in action on the Kubezilla Desktop product page.
FAQ
What is the difference between hub-and-spoke and standalone Argo CD?
Hub-and-spoke runs one central Argo CD instance that manages several target clusters, giving you centralized control at the cost of network reachability requirements. Standalone runs a separate Argo CD per cluster, which simplifies RBAC and isolation but means more instances to maintain, a tradeoff described in Red Hat’s architecture guidance.
How do I add a cluster to Argo CD?
Run argocd cluster add CONTEXT to register a cluster through the CLI, which creates the argocd-manager ServiceAccount Argo CD needs to reconcile resources there. For a GitOps-managed approach, create a Kubernetes Secret labeled argocd.argoproj.io/secret-type: cluster instead, as documented in the operator manual.
How does the ApplicationSet Cluster generator work?
The Cluster generator reads your registered cluster Secrets and exposes fields like name and server for use in Application templates, so one ApplicationSet can target many clusters at once. It also supports label selectors and flatList mode, as described in the Cluster generator docs.
Can I avoid static tokens for cluster authentication?
Yes. Where your platform supports it, Workload Identity paired with Connect Gateway lets Argo CD authenticate to target clusters without static service-account tokens, an approach detailed in Google Cloud’s fleet guidance.
Does Kubezilla Desktop replace Argo CD?
No. Kubezilla Desktop is a native desktop client for managing clusters, kubeconfigs, logs, and Helm or Argo CD operations in one interface, not a GitOps engine itself. It works alongside your existing Argo CD setup to speed up daily cluster operations, as described on the Kubezilla Desktop product page.