Argo CD can manage Kubernetes clusters outside of its own control plane, but it doesn’t automatically discover them. You need to explicitly tell Argo CD about these "external" clusters using a Cluster resource.
Let’s see this in action. Imagine you have a local Kind cluster you want Argo CD to manage. First, get the kubeconfig for that cluster:
kind get kubeconfig --name my-kind-cluster > kind-kubeconfig.yaml
Now, create a Kubernetes secret in the Argo CD namespace (assuming it’s argocd) containing this kubeconfig. The secret needs a specific name format: argocd-cluster-<cluster-name>. Let’s use my-kind-cluster as the cluster name.
kubectl create namespace argocd
kubectl create secret generic argocd-cluster-my-kind-cluster \
--from-file=config=kind-kubeconfig.yaml \
--namespace argocd
Argo CD’s cluster controller will automatically detect this secret, parse the config key, and register my-kind-cluster as a managed cluster. You can verify this in the Argo CD UI or by checking the argocd-application-controller logs for messages indicating it added a new cluster.
The core of registering an external cluster is providing Argo CD with a valid kubeconfig that it can use to authenticate and communicate with the target cluster’s API server. Argo CD uses this kubeconfig to:
- Discover Resources: List and watch all Kubernetes resources within the external cluster.
- Apply Manifests: Create, update, and delete resources in the external cluster based on your Argo CD Application definitions.
- Report Status: Fetch the current state of resources in the external cluster to compare against the desired state defined in your Git repository.
The argocd-cluster-<cluster-name> secret is the standard mechanism. The config key within the secret must contain the full kubeconfig file content. If you omit the config key or provide invalid YAML/KUBECONFIG, Argo CD won’t be able to register the cluster.
You can also register the cluster using the Argo CD CLI or API, which essentially automates the creation of this secret. For example, using the CLI:
argocd cluster add \
--kubeconfig kind-kubeconfig.yaml \
my-kind-cluster
This command will create the argocd-cluster-my-kind-cluster secret for you. The my-kind-cluster argument is the name Argo CD will use internally and in the UI.
The most surprising thing about registering external clusters is that the secret name directly dictates the cluster identifier. If you create a secret named argocd-cluster-production and provide a kubeconfig pointing to your production cluster, Argo CD will register it as production. Changing the secret name after registration can lead to unexpected behavior or require re-registering the cluster.
When you register a cluster this way, Argo CD automatically adds a Cluster resource object into its own Kubernetes cluster. This Cluster resource is what Argo CD’s controllers actually interact with to manage the external cluster’s state. You can inspect it with kubectl get cluster my-kind-cluster -n argocd -o yaml.
The next hurdle is understanding how Argo CD uses the Service Account associated with the registered cluster’s credentials to perform operations.