Argo CD’s multi-cluster deployment isn’t about copying manifests; it’s about defining a desired state that Argo CD then reconciles across any cluster it’s aware of.
Let’s see this in action. Imagine you have a simple Deployment in manifests/app.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 2
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:latest
Now, you want this deployed to two clusters: dev-cluster and prod-cluster. You’ve already added these clusters to Argo CD.
First, we define an Application resource in Argo CD. This isn’t a Kubernetes manifest for my-app; it’s a manifest for Argo CD itself, telling it how to deploy my-app.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-multi-cluster
namespace: argocd # The namespace where Argo CD is installed
spec:
project: default
source:
repoURL: 'https://github.com/your-org/your-repo.git' # Your Git repository
path: manifests # The directory containing your app manifests
targetRevision: HEAD
destination:
# This is where the magic happens for multi-cluster
# We'll define multiple destinations here
servers:
- 'https://kubernetes.default.svc' # Default cluster (where Argo CD is running)
- 'https://<dev-cluster-api-server-url>' # Your dev cluster's API server
- 'https://<prod-cluster-api-server-url>' # Your prod cluster's API server
syncPolicy:
automated:
prune: true # Automatically clean up resources that are no longer in Git
selfHeal: true # Automatically fix drift between Git and cluster state
When you apply this Application manifest to your Argo CD instance, Argo CD reads it. It sees the repoURL and path, fetches your Deployment manifest from Git, and then looks at the destination.servers. It will then create the my-app Deployment with 2 replicas in each of the specified clusters. If you change replicas to 3 in your Git repo, Argo CD will update the Deployments in all three clusters.
The core problem Argo CD solves is the declarative management of application state across distributed Kubernetes environments. Before Argo CD, you’d be scripting kubectl apply -f ... commands for each cluster, managing different values.yaml files for Helm, or orchestrating complex CI/CD pipelines. Argo CD abstracts all that into a single Application resource, pointing to a Git repository as the source of truth.
Internally, Argo CD maintains a Git repository as its desired state. It also watches the live state of your Kubernetes clusters. For each Application resource, it compares the state defined in Git with the state in the target cluster(s). If there’s a difference (drift), and selfHeal is enabled, Argo CD will automatically reconcile the cluster state to match Git. If prune is enabled, it will also remove resources from the cluster that are no longer defined in Git.
The destination.servers field is key for multi-cluster. You can also use destination.namespace to specify different namespaces in each cluster if needed, or even use Helm values or Kustomize overlays to tailor the deployment per cluster. For example, your Application could specify a different targetRevision or path for each destination server, allowing for distinct versions or configurations per cluster.
The most surprising mechanical detail is how Argo CD handles the actual API calls. When you specify multiple servers, Argo CD doesn’t just copy your manifests. It establishes separate connections to each cluster’s API server. For each manifest in your Git repository, it applies that manifest to each of the target clusters. The Application resource is the instruction set for Argo CD’s reconciliation engine, not a template for generating cluster-specific YAML. It’s a single definition that drives multiple, independent reconciliation loops.
When you’re dealing with a large number of applications and clusters, you’ll eventually want to group your Application resources by environment or team using Argo CD Projects.