Multi Cluster Overview

In the previous module, we configured the Pull Request Generator, spawned preview environments dynamically, matched label filters, and managed preview lifecycles. With dynamic templates clear, we will now start Module 11: Multi-Cluster Management, beginning with Multi-Cluster Overview.

In enterprise GitOps operations, workloads span multiple physical or virtual clusters (e.g., development sandbox clusters, staging testing clusters, and regional production clusters). Managing this layout requires setting up centralized orchestrations that route deployments to target clusters while keeping configurations secure.

In this guide, we will analyze multi-cluster architectures, compare connection models, and review network layouts.

1. Multi-Cluster Architecture: Hub-and-Spoke

ArgoCD implements a Hub-and-Spoke architecture to manage external clusters. The controller resides on a single cluster (the "Hub" or manager cluster) and connects to remote clusters (the "Spokes" or target clusters) using Kubernetes API endpoints:

               Hub-and-Spoke Connection Model
┌────────────────────────────────────────────────────────┐
│  Manager (Hub) Cluster: Runs ArgoCD Controller Pods     │
├────────────────────────────────────────────────────────┤
│  API Connections (gRPC / TLS HTTPS):                   │
│  ├── Target (Spoke) Cluster A: dev-api-server          │
│  ├── Target (Spoke) Cluster B: staging-api-server      │
│  └── Target (Spoke) Cluster C: production-api-server   │
├────────────────────────────────────────────────────────┤
│  Reconciliation: Hub queries and syncs spoke resources │
└────────────────────────────────────────────────────────┘

1. Centralized Management: The application controller, repo-server, and UI run on the Hub cluster, providing a single dashboard to track all workloads.
2. Remote Registration: You register Spoke clusters by adding their API server credentials to the Hub cluster database as Secrets.
3. Reconciliation Loop: The Hub controller watches for Git changes, connects to the target Spoke API server, and applies the manifests directly.

2. Comparing Hub-and-Spoke (Push) vs. Local Controllers (Pull)

When designing multi-cluster deployments, choose between two primary orchestration patterns:

Centralized Hub-and-Spoke (Push Model)

• Design: A single ArgoCD controller instance on the Hub cluster pushes manifests to remote Spoke API servers.
• Pros: Single entry point, centralized logging, simple RBAC management.
• Cons: The Hub cluster requires administrative network access to all Spoke API endpoints. A compromise on the Hub compromises all Spokes.

Distributed Controllers (Pull Model)

• Design: You deploy a separate ArgoCD controller instance inside every Spoke cluster. Each controller pulls configurations independently from Git.
• Pros: High isolation, zero cross-cluster network dependencies. If one cluster is compromised, other regions remain safe.
• Cons: No centralized dashboard, complex RBAC management, increased resource overhead (running multiple controllers).

3. Operational Best Practices: Multi-Cluster setup

• Secure target API endpoints: Protect the API server ports of your target Spoke clusters by restricting access to the Hub cluster's NAT IP addresses.
• Enforce namespace boundaries: Restrict the permissions of cluster credentials using scoped service accounts (rather than granting cluster-admin access globally).
• Monitor connection latency: Monitor network round-trip times between the Hub and Spoke regions to prevent synchronization lags during deployments.

4. Connection Models Comparison Summary

In this section, we analyzed the Hub-and-Spoke architecture, compared push and pull connection models, and reviewed network security guidelines.

Now we will transition to adding external clusters. In the next guide, we will cover how to use the CLI to register target clusters and generate kubeconfig credentials.