Skip to main content
This guide shows how to register a remote Kubernetes cluster with Argo CD and deploy an application to that cluster. By default, Argo CD manages resources in the cluster where it is installed (the control plane). To deploy to other clusters you must add them as destinations so Argo CD can authenticate and talk to them.
Before you begin:
  • Ensure your local kubeconfig contains contexts for both the Argo CD control cluster and any target clusters (e.g., KinD).
  • Ensure the argocd CLI is installed and authenticated against your Argo CD server (argocd login).

​
1) Identify the kubeconfig context to add

List your current kubeconfig contexts to identify the context name you will add to Argo CD: 
kubectl config get-contexts
CURRENT   NAME                    CLUSTER                 AUTHINFO               NAMESPACE
*         docker-desktop          docker-desktop          docker-desktop
          kind-argo-cluster-1     kind-argo-cluster-1     kind-argo-cluster-1
In this example:
  • docker-desktop is the control cluster where Argo CD runs.
  • kind-argo-cluster-1 is the KinD cluster we will add as a destination.

​
2) Argo CD cluster commands

Use the argocd cluster subcommands to manage cluster destinations. Common commands:
CommandUse caseExample
List clustersShow registered clustersargocd cluster list -o json
Add clusterRegister a context from your kubeconfigargocd cluster add <kubecontext-name>
Get cluster infoInspect cluster detailsargocd cluster get <cluster-name> -o wide
Remove clusterUnregister a clusterargocd cluster rm <cluster-name>
Update cluster propertiesRename or set propertiesargocd cluster set <CLUSTER_NAME> --name <new-cluster-name> --namespace '*'
Running argocd cluster add creates a ServiceAccount (commonly argocd-manager) on the target cluster with cluster-wide privileges and generates a long-lived token. Only register clusters you trust and for which this level of access is acceptable.

​
3) Add the KinD cluster to Argo CD

Add the KinD context (must exist in your kubeconfig). The CLI will create a ServiceAccount, ClusterRole, ClusterRoleBinding, and a bearer token secret on the target cluster, then register the cluster with Argo CD: 
# Add the 'kind-argo-cluster-1' context to Argo CD
argocd cluster add kind-argo-cluster-1
Example (abridged) output: 
{"level":"info","msg":"ServiceAccount \"argocd-manager\" created in namespace \"kube-system\"","time":"2025-10-23T17:29:59Z"}
{"level":"info","msg":"ClusterRole \"argocd-manager-role\" created","time":"2025-10-23T17:29:59Z"}
{"level":"info","msg":"ClusterRoleBinding \"argocd-manager-role-binding\" created","time":"2025-10-23T17:29:59Z"}
{"level":"info","msg":"Created bearer token secret \"argocd-manager-long-lived-token\" for ServiceAccount \"argocd-manager\"","time":"2025-10-23T17:29:59Z"}
Cluster 'https://172.26.60.148:38449' added
Argo CD stores the target cluster’s connection data (API server URL, CA, token) as a Kubernetes Secret in the Argo CD namespace of the control cluster. Switch back to the control cluster and list secrets in the Argo CD namespace to view the stored cluster secret: 
# Switch to the cluster where Argo CD is installed (control plane)
kubectl config use-context docker-desktop
Switched to context "docker-desktop".

# List secrets in the argocd namespace
kubectl -n argocd get secrets
NAME                                   TYPE    DATA   AGE
argocd-initial-admin-secret            Opaque  1      10h
argocd-notifications-secret            Opaque  0      10h
argocd-redis                           Opaque  1      10h
argocd-secret                          Opaque  5      10h
cluster-172.26.60.148-931191031        Opaque  3      46s
The cluster-<ip>-<suffix> secret contains the API server URL, CA data, and token Argo CD uses to communicate with the KinD cluster.
A screenshot of the Argo CD web UI showing the Settings → Clusters page with cluster details for https://172.26.60.148:38449 (name: kind-argo-cluster-1), credentials Token/Basic Auth, and namespaces set to All namespaces. The connection state reads "Unknown" and notes the cluster has no applications and is not being monitored.
If you open the Argo CD UI (Settings → Clusters) the new cluster may show a Connection status of “Unknown” initially. This often happens when Argo CD has not yet created or is not actively monitoring any applications on that cluster.

​
4) Create an application that targets the remote cluster

In the Argo CD Create Application form you can:
  • Set the Git repository and path containing the manifests.
  • Choose the destination cluster (the KinD cluster) and the target namespace.
  • Enable Automatic Sync and check “Auto-create namespace” so Argo CD will create the namespace on the destination if missing.
A screenshot of the Argo CD web UI showing the "Create Application" form for "health-check-app-2" (project: default) with Automatic sync selected and "Enable Auto-Sync" checked. The left sidebar displays navigation (Applications, Settings, User Info) and application/health status filters.
Select the repository and the path where the application manifests live. In this demo the repo contains a folder for the Health Check app:
A dark-themed web interface for a Git repository (kk-org/gitops-argocd-capa) showing a list of folders and recent commit messages. The right sidebar displays repo details like license, size and language stats, and the top bar shows navigation tabs (Code, Issues, Pull Requests, etc.).
Choose the correct path (for example ./health-check) and select the destination cluster and namespace (health-check-app-2 in this example):
A screenshot of the Argo CD web UI showing an application create/edit form with the HEAD path set to "./health-check" and DESTINATION fields populated with a cluster URL and namespace ("health-check-app-2"). The left sidebar shows navigation (Applications, Settings) and application filter/status panels.

​
5) Application sync and health checks

After creation, Argo CD syncs manifests to the target cluster. This example app uses a ConfigMap-based health check: certain data values determine whether a resource is healthy. If a monitored value is considered unhealthy (for example TRIANGLE_COLOR: "white"), Argo CD will show the application’s health as Degraded even if it is successfully synced. Example ConfigMap excerpt: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: moving-shapes-colors
  namespace: health-check-app-2
  annotations:
    argocd.argoproj.io/tracking-id: health-check-app-2:/ConfigMap:health-check-app-2/moving-shapes-colors
data:
  CIRCLE_COLOR: "pink"
  OVAL_COLOR: "lightgreen"
  RECTANGLE_COLOR: "blue"
  SQUARE_COLOR: "orange"
  TRIANGLE_COLOR: "white"
Because TRIANGLE_COLOR is set to white and the health check treats that as unhealthy, the application appears Degraded while its sync status is Synced:
Screenshot of the Argo CD web interface showing an application named "health-check-app-2" with a "Degraded" health indicator and a "Synced" status. The main pane displays a resource graph linking components like "moving-shapes-colors" and "random-shapes" to their pods.
From the Applications list you can confirm the destination cluster for this app is the KinD cluster (different from apps targeting the control cluster):
A screenshot of the Argo CD web UI showing a list of Kubernetes applications with project/name, source and destination fields and colored health/sync status indicators. The left sidebar shows navigation and application filters while the top has buttons for creating, syncing and refreshing apps.

​
6) Verify the application on the remote cluster

Switch your kubectl context to the KinD cluster and confirm the namespace and resources were created by Argo CD: 
# Switch to the KinD cluster
kubectl config use-context kind-argo-cluster-1
Switched to context "kind-argo-cluster-1".

# List namespaces on the KinD cluster
kubectl get ns
NAME                   STATUS    AGE
default                Active    75m
health-check-app-2     Active    79s
kube-node-lease        Active    75m
kube-public            Active    75m
kube-system            Active    75m
local-path-storage     Active    73m
You can also inspect pods and other resources in health-check-app-2 to confirm the sync succeeded. Pods may briefly show ContainerCreating while images are pulled.

​
Summary

  • Use argocd cluster add <context> to register remote clusters with Argo CD. This creates a ServiceAccount and stores cluster credentials as a Secret in the Argo CD control cluster.
  • Registered clusters appear as destinations in the Argo CD UI and can be targeted by Applications, either from the UI or via Application CRs.
  • A cluster showing Connection status “Unknown” may simply have no managed applications yet — creating an application that targets it causes Argo CD to actively monitor it.
  • Health checks can mark an otherwise-synced application as Degraded based on resource content (ConfigMaps, status probes, etc.).

Watch Video