Skip to main content
ArgoCD Clusters represent Kubernetes clusters where applications can be deployed. Connect clusters to ArgoCD to enable GitOps-based deployments across your infrastructure.

​
Key Concepts

Cluster

A Kubernetes cluster connected to ArgoCD for application deployments.

API Server

The Kubernetes API server endpoint used for cluster communication.

Bearer Token

ServiceAccount token used to authenticate ArgoCD with the cluster.

Connection Status

Health status indicating whether ArgoCD can reach and authenticate with the cluster.

​
Required Permissions

ActionPermission
View clustersiam:project:cicd:argocd:read
Add clustersiam:project:cicd:argocd:write
Delete clustersiam:project:cicd:argocd:delete

​
Connection Status

StatusDescription
SuccessfulCluster is reachable and authentication succeeded
FailedConnection or authentication failed
UnknownStatus not yet determined

​
How to Add a Cluster

1

Select ArgoCD Instance

Choose the ArgoCD instance from the dropdown in the toolbar.
2

Click Add Cluster

Click the Add Cluster button in the header.
3

Enter Cluster Name

Provide a friendly name to identify the cluster.
4

Enter API Server URL

Enter the Kubernetes API server URL (e.g., https://cluster.example.com:6443).
5

Enter Bearer Token

Paste the ServiceAccount bearer token for authentication.
6

Configure TLS

Either provide a CA certificate or enable insecure mode (skip TLS verification).
7

Enable Cluster Resources (Optional)

Toggle to allow ArgoCD to manage cluster-scoped resources.
8

Add

Click Add Cluster to connect the cluster.

​
Required Fields

FieldRequiredDescription
Cluster NameYesFriendly identifier for the cluster
API Server URLYesKubernetes API server endpoint
Bearer TokenYesServiceAccount token for authentication
CA CertificateConditionalRequired unless TLS verification is disabled

​
TLS Configuration

When TLS verification is enabled (default), you must provide the CA certificate:
FieldDescription
CA Certificate (caData)Base64-encoded CA certificate for verifying the cluster’s TLS certificate

​
Insecure Mode

Enable “Disable TLS Verification” to skip certificate validation.
Insecure mode should only be used for development or testing. Always use proper TLS verification in production environments.

​
Cluster Options

OptionDefaultDescription
Enable Cluster-wide ResourcesOffAllow ArgoCD to manage cluster-scoped resources (ClusterRole, Namespace, etc.)
Enable cluster-wide resources only if your applications need to create or manage cluster-scoped Kubernetes resources.

​
How to Get Cluster Credentials

Follow these steps to obtain the required credentials from your Kubernetes cluster.

​
Step 1: Create ServiceAccount

Apply the ArgoCD service account manifest to your cluster: 
kubectl apply -f https://raw.githubusercontent.com/shiftlabsdev-community/shiftlabs-argocd/refs/heads/main/argocd-token.yaml
This creates:
  • A ServiceAccount named argocd-manager in kube-system namespace
  • A ClusterRoleBinding with cluster-admin privileges
  • A long-lived token secret

​
Step 2: Retrieve Bearer Token

Get the bearer token from the created secret: 
kubectl -n kube-system get secret argocd-manager-token -o jsonpath="{.data.token}" | base64 -d && echo
Copy the output and paste it into the Bearer Token field.

​
Step 3: Retrieve CA Certificate

Get the cluster’s CA certificate: 
kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}'
Copy the output (already base64-encoded) and paste it into the CA Certificate field.
If your kubeconfig has multiple clusters, adjust the jsonpath index or use the cluster name to get the correct certificate.

​
How to Delete a Cluster

1

Find the Cluster

Locate the cluster in the list.
2

Click Delete

Click the delete (trash) icon on the cluster row.
3

Confirm

Confirm the deletion. This action cannot be undone.
Deleting a cluster does not delete applications deployed to it. Applications targeting a deleted cluster will fail to sync. Reassign or delete applications before removing the cluster.

​
Troubleshooting

  • Verify the API server URL is correct and reachable
  • Check if the bearer token is valid and not expired
  • Ensure the ServiceAccount has sufficient permissions
  • Verify network connectivity between ArgoCD and the cluster
  • Check firewall rules allow traffic on the API server port
  • Verify the CA certificate is correct and base64-encoded
  • Ensure the certificate matches the cluster’s CA
  • Try enabling insecure mode temporarily to verify other settings
  • Check if the certificate has expired
  • Verify the bearer token is correct and complete
  • Check if the ServiceAccount still exists
  • Ensure the token secret hasn’t been deleted
  • Verify the ClusterRoleBinding is intact
  • Recreate the ServiceAccount if necessary
  • Enable “Cluster-wide Resources” option when adding the cluster
  • Verify the ServiceAccount has cluster-admin or equivalent permissions
  • Check project resource rules allow cluster-scoped resources
  • Applications may not be synced yet
  • Check if applications are targeting the correct cluster
  • Verify application project allows deployment to this cluster
  • Refresh the page to update counts
  • Verify you have delete permission
  • Check if applications are still deploying to this cluster
  • Try refreshing the page and attempting again

​
FAQ

ArgoCD automatically includes the cluster where it’s installed as in-cluster (or https://kubernetes.default.svc). This cluster cannot be deleted and is always available.
Currently, clusters cannot be edited. To change settings, delete the cluster and add it again with the new configuration.
ArgoCD periodically checks cluster connectivity. The “Last Check” column shows when the last check occurred. Failed clusters are checked more frequently.
For full functionality, the ServiceAccount needs cluster-admin privileges or equivalent permissions to create, update, and delete resources across namespaces.
The UI requires bearer token authentication. For other authentication methods (client certificates, OIDC), use the ArgoCD CLI or API directly.
The version is retrieved during connectivity checks. If the cluster is unreachable or recently added, the version may not be available yet.
Yes. Each ArgoCD instance maintains its own cluster connections. The same Kubernetes cluster can be registered in multiple ArgoCD instances.
Cluster operations will fail with authentication errors. Create a new token and re-add the cluster with the updated credentials.

​
Best Practices

​
Security

  • Use dedicated ServiceAccounts for ArgoCD (never share with other systems)
  • Apply least-privilege principles where possible
  • Use TLS verification in production (avoid insecure mode)
  • Rotate bearer tokens periodically
  • Audit cluster access and permissions regularly

​
Naming

  • Use descriptive cluster names (e.g., prod-us-east-1, staging-eu-west)
  • Include environment and region in the name
  • Keep names consistent across your organization

​
Connectivity

  • Ensure stable network connectivity between ArgoCD and clusters
  • Configure appropriate timeouts for distant clusters
  • Monitor connection status for early issue detection
  • Set up alerts for cluster connectivity failures

​
Resource Management

  • Enable cluster-wide resources only when necessary
  • Use ArgoCD projects to restrict which clusters applications can target
  • Document which teams/applications use each cluster
  • Remove unused cluster connections to reduce attack surface

​
Credential Management

  • Store credentials securely before adding to the platform
  • Document the ServiceAccount and secret locations
  • Set up monitoring for ServiceAccount token expiration
  • Have a runbook for credential rotation