Learn GitOps with ArgoCD - Multi-Cluster Management

#Introduction

In episode 8 we mastered configuration management with Helm and Kustomize — the ability to write manifests that are clean, dynamic, and easy to promote between environments. But all of that still centers on one cluster. In the real world, almost no team runs all of its applications in a single cluster. Production, staging, and development are usually separated; other teams have their own clusters; and multinational companies have clusters per region. In this episode we get into the feature that makes ArgoCD truly superior to traditional CD tools: multi-cluster management from a single ArgoCD instance.

Why does this matter? Many organizations fall into the pattern of "manually deploying to each cluster" as the number of clusters grows — with all its consequences: configuration drift, inconsistent processes, and no audit trail. ArgoCD multi-cluster solves this with a single way of thinking: one Git, many clusters, one control point.

#Why Multi-Cluster?

The reasons for using many clusters are varied, but the most common ones:

• Blast radius isolation — a failure in the staging cluster doesn't touch production.
• Compliance & data residency — European user data stays in the European region, and so on.
• Tenancy isolation — each team has its own sandbox without interfering with each other's resources.
• Geographic proximity — lower latency because applications run close to the users.

Without GitOps, every additional cluster means a new maintenance point. With ArgoCD, an external cluster just needs to be registered once, then every Application can target it just like targeting the local cluster.

#Cluster Registration

#Basic Concept: In-Cluster vs External

ArgoCD distinguishes two types of targets: the cluster where ArgoCD runs (in-cluster) and all other clusters (external).

Note that the in-cluster is also treated as a "cluster" by ArgoCD — it has the name in-cluster and shows up in the cluster list.

#Adding an External Cluster

The easiest way to register a cluster is via the kubeconfig context you already have:

argocd cluster add eks-prod --label env=prod --label region=ap-southeast-1
argocd cluster add kind-staging --label env=staging
argocd cluster add eks-dev --label env=dev --namespace team-dev

What happens behind the scenes when argocd cluster add eks-prod is run? ArgoCD reads the eks-prod context from your kubeconfig, then uses those credentials to create the following objects on the target cluster:

• A ServiceAccount argocd-manager in the kube-system namespace.
• A ClusterRole argocd-manager-role with enough permission to read and manage application resources.
• A ClusterRoleBinding connecting the two.

The token from that ServiceAccount is then stored encrypted inside the argocd-secret Secret belonging to ArgoCD, and is used for all operations on that cluster. ArgoCD never stores your admin kubeconfig.

#Cluster Labels

Labels serve as metadata for grouping and filtering clusters. From the commands above we marked clusters with env=prod and region=ap-southeast-1. These labels can be used for:

• UI filtering — showing only production clusters, for example.
• Template parameters — label values can be accessed as parameters when targeting clusters, e.g. region to choose a domain.
• ApplicationSet cluster generator — automatically creates an Application for every cluster matching a selector (we'll cover this in detail in episode 11).

#Credentials & Service Accounts

Besides the kubeconfig, ArgoCD supports registration with an existing ServiceAccount on the target cluster. Create a ServiceAccount with RBAC on the target cluster, then register it manually:

kubectl create sa argocd-manager -n kube-system
kubectl apply -f role-binding.yaml
argocd cluster add eks-prod --service-account argocd-manager

The RBAC on the target cluster should be as conservative as possible: give permission for application resources (Deployment, Service, ConfigMap, and the like) in the allowed namespaces, not cluster-admin.

#Managing Clusters

Day-to-day cluster operations are very simple:

argocd cluster list
argocd cluster get https://xxxx.ap-southeast-1.eks.amazonaws.com
argocd cluster update https://xxxx.ap-southeast-1.eks.amazonaws.com --label env=prod
argocd cluster rm https://xxxx.ap-southeast-1.eks.amazonaws.com

argocd cluster list shows the SERVER, NAME, STATUS, and PROJECT columns — useful for verifying that all clusters are connected healthily. argocd cluster rm removes the cluster registration along with the Secret storing its credentials, but it does not delete Applications still targeting it.

#Multi-Cluster Architecture

#Hub-and-Spoke Model

The most common pattern is hub-and-spoke: a single ArgoCD instance (hub) sits in one cluster and manages many other clusters (spokes) registered as external. The hub stores all Git repos and Applications; spokes only receive the pulled manifests. The advantage: configuration, RBAC, SSO, and audit are centralized in one place.

#Centralized vs Distributed ArgoCD

The next architectural decision: one ArgoCD for everything, or several ArgoCDs?

The "cluster per environment" pattern (one ArgoCD in dev, one in staging, one in prod) is a popular compromise: each ArgoCD manages its own environment's cluster, so configuration mistakes don't spread to production.

#Application Placement

Once the cluster is registered, placing an application is just a matter of choosing the destination. When creating an Application, specify destination.server and destination.namespace:

application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/devnull/gitops-repo.git
    targetRevision: main
    path: apps/api/overlays/prod
  destination:
    server: https://xxxx.ap-southeast-1.eks.amazonaws.com
    namespace: team-prod
  syncPolicy:
    automated:
      prune: true

ArgoCD also supports targeting via cluster name (destination.name: eks-prod) — easier to read and independent of API addresses that can change. The "App of Apps" combination from episode 6 pairs beautifully here: one parent Application contains a list of child Applications, each targeting a different cluster.

#Multi-Cluster Security

Because ArgoCD holds credentials to all clusters, security becomes a priority:

• Least privilege — never register a cluster with full admin credentials; use a ServiceAccount with minimal scope.
• Encryption at rest — credentials are stored encrypted in argocd-secret; restrict access to this Secret to ArgoCD operators only.
• Network — make sure the repo-server and application-controller can reach the external cluster API endpoints through clear network policies.
• ArgoCD RBAC — combine with Projects (next episode) so each team can only deploy to its own clusters.

#Common Pitfalls

1. Registering with an admin context. Admin credentials stored in ArgoCD become a time bomb. Use a restricted ServiceAccount.
2. Removing a cluster without cleaning up Applications. Applications become permanently broken; delete the applications first.
3. Targeting a namespace that doesn't exist. ArgoCD can create namespaces via the CreateNamespace=true sync option, but make sure it's actually allowed by the team's policy.
4. Forgetting labels from the start. Adding labels later via argocd cluster update is still possible, but ApplicationSet and UI filtering will be harder to set up later.
5. Hidden network. External clusters only reachable from certain IPs require ArgoCD network policy adjustments — test connectivity before blaming the configuration.

#Closing

This episode opened the door to ArgoCD multi-cluster: the in-cluster vs external difference, registration via argocd cluster add and ServiceAccount credentials, cluster labels as metadata, the hub-and-spoke architecture and the centralized vs distributed comparison, placing Applications on the right destination, and security principles to protect cluster credentials.

The points you should take with you:

• Multi-cluster is the main reason many companies choose ArgoCD.
• argocd cluster add uses a kubeconfig context and then creates the argocd-manager ServiceAccount on the target cluster.
• Cluster labels are the key to filtering and ApplicationSet (episode 11).
• Choose centralized or distributed based on isolation needs and organization size.
• Always use least-privilege credentials when registering clusters.

The more clusters there are, the greater the need to manage who can deploy where. That's exactly the material of the next episode 10: ArgoCD Projects & Multi-Tenancy — creating projects, repository and cluster whitelists, JWT-based roles, and team- and environment-based tenancy patterns. See you in episode 10!