Skip to main content
Learn how Argo CD can manage applications across multiple Kubernetes clusters — not just the cluster where Argo CD itself runs. This guide shows the recommended sequence: prepare your kubeconfig, register the external cluster with Argo CD, and verify that the cluster is available as a deployment destination. Argo CD supports multi-cluster deployments by storing external cluster credentials in its own namespace and using a dedicated service account on each external cluster to apply manifests.
A slide titled "Multi-Cluster Deployment" showing a controller pulling manifests from a GitHub repository and deploying them to dev and prod Kubernetes clusters. The diagram uses icons for GitHub, a squid-like operator inside a dashed box, and Kubernetes cluster symbols with arrows labeled "deploy."

​
Overview — steps to add an external cluster

  1. Add the external cluster details (server, certificates, user credentials, context) to your local kubeconfig.
  2. Use the argocd CLI to register that kubeconfig context with Argo CD (argocd cluster add).
  3. Confirm Argo CD created the required ServiceAccount, ClusterRole, and ClusterRoleBinding on the target cluster.
  4. Verify the cluster appears in Argo CD’s cluster list and inspect the stored secret if needed.
Before running the commands below, ensure you have access to the target cluster API endpoint and appropriate client certificates or tokens. You can also use cloud provider IAM auth (e.g., EKS, GKE) depending on your environment.

​
Example commands

Add the cluster server, user credentials, and context into kubeconfig:
Register the context with Argo CD (this will create a service account and RBAC bindings on the external cluster):
Check the clusters that Argo CD knows about:
Argo CD stores the cluster credentials as Kubernetes Secrets in the argocd namespace. You can inspect a secret like this:
Output:
When you run argocd cluster add, Argo CD will create an argocd-manager ServiceAccount with cluster-admin level permissions by default. Limit access and scope where possible — for production, prefer restricting RBAC to the minimum required privileges.

​
Quick reference — commands and purpose

​
Verification and troubleshooting

  • Use argocd cluster list to confirm the cluster status shows Successful.
  • If a cluster shows errors, check the target cluster’s kube-apiserver reachability, certificate validity, and whether the created ServiceAccount/RBAC objects exist in the target cluster’s kube-system namespace.
  • Inspect Argo CD logs for errors: kubectl -n argocd logs deploy/argocd-server or check the repo-server and application-controller logs for sync problems.
This workflow lets Argo CD act as a single control plane for application deployment across multiple Kubernetes clusters, enabling consistent GitOps-driven rollouts to dev, staging, and production clusters.

Watch Video