Skip to main content
The argocd cluster command manages cluster credentials, allowing Argo CD to deploy applications to multiple Kubernetes clusters.

​
Quick Examples

# List all clusters
argocd cluster list -o json

# Add a cluster
argocd cluster add example-cluster

# Get cluster details
argocd cluster get example-cluster -o wide

# Remove a cluster
argocd cluster rm example-cluster

# Update cluster settings
argocd cluster set CLUSTER_NAME --name new-name --namespace '*'

​
Understanding Cluster Management

Argo CD needs credentials to deploy applications to target clusters. The local cluster where Argo CD is installed is automatically configured as https://kubernetes.default.svc.
The cluster where Argo CD is running is called the “in-cluster” and doesn’t need to be added explicitly.

​
Subcommands

​
add

Add a cluster to Argo CD using your kubeconfig. 
# Add cluster using context from kubeconfig
argocd cluster add production-cluster

# Add with custom service account
argocd cluster add production-cluster --service-account argocd-manager

# Add with custom namespace
argocd cluster add production-cluster --namespace argocd

# Add with labels
argocd cluster add production-cluster --label env=production --label region=us-west

# Add in-cluster (where Argo CD runs)
argocd cluster add production-cluster --in-cluster
Add a cluster using kubectl context:
# List available contexts
kubectl config get-contexts

# Add cluster
argocd cluster add my-cluster-context
Key Flags:
​
--name
string
Cluster name (defaults to context name)
​
--service-account
string
Service account for Argo CD to use
​
--namespace
string[]
Allowed namespaces (can be repeated, use ’*’ for all)
​
--label
string[]
Cluster labels in key=value format
​
--project
string[]
Projects allowed to use this cluster
​
--shard
integer
Cluster shard number
​
--upsert
boolean
Update cluster if it already exists

​
list

List all configured clusters. 
# List clusters
argocd cluster list

# List with wide output
argocd cluster list -o wide

# List as JSON
argocd cluster list -o json

# List as YAML
argocd cluster list -o yaml
Output: 
SERVER                          NAME              VERSION  STATUS   MESSAGE  PROJECT
https://kubernetes.default.svc  in-cluster        1.28     Successful         default
https://prod.example.com        production        1.27     Successful         default
https://dev.example.com         development       1.28     Successful         dev-team
With Wide Output: 
argocd cluster list -o wide

SERVER                          NAME         VERSION  STATUS      MESSAGE  LABELS                           NAMESPACES
https://kubernetes.default.svc  in-cluster   1.28     Successful           environment=production           *
https://prod.example.com        production   1.27     Successful           env=prod,region=us-west          *
https://dev.example.com         development  1.28     Successful           env=dev,team=platform            app1,app2

​
get

Get detailed information about a specific cluster. 
# Get cluster info
argocd cluster get production

# Get with wide output
argocd cluster get production -o wide

# Get as JSON
argocd cluster get production -o json

# Get as YAML
argocd cluster get production -o yaml
Output: 
Cluster:
  Server:              https://prod.example.com
  Name:                production
  Version:             1.27
  Status:              Successful
  Message:             
  Connection State:    Successful
  Sync Status:         Synced

Info:
  Platform:            linux/amd64
  Server Version:      v1.27.4
  Connection State:
    Status:            Successful
    Message:           cluster is reachable

Labels:
  environment:         production
  region:              us-west-2

Namespaces:
  Allowed:             *

Projects:
  default
  production-apps

​
set

Update cluster settings. 
# Update cluster name
argocd cluster set https://prod.example.com --name production

# Set namespaces
argocd cluster set production --namespace app1 --namespace app2
argocd cluster set production --namespace '*'  # Allow all namespaces

# Add labels
argocd cluster set production --label env=production --label tier=critical

# Set project restrictions
argocd cluster set production --project prod-team --project platform-team

# Update shard
argocd cluster set production --shard 2
Key Flags:
​
--name
string
Update cluster name
​
--namespace
string[]
Set allowed namespaces (replaces existing)
​
--label
string[]
Set cluster labels (replaces existing)
​
--project
string[]
Set allowed projects (replaces existing)

​
rm

Remove a cluster from Argo CD. 
# Remove cluster by name
argocd cluster rm production

# Remove cluster by server URL
argocd cluster rm https://prod.example.com

# Remove without confirmation
argocd cluster rm production --yes
Removing a cluster does not delete applications deployed to it, but Argo CD will no longer be able to sync them.

​
rotate-auth

Rotate cluster authentication credentials. 
# Rotate authentication
argocd cluster rotate-auth production

# Rotate for specific server
argocd cluster rotate-auth https://prod.example.com
This regenerates the service account token used by Argo CD to access the cluster.

​
Common Workflows

​
Adding Multiple Clusters

# Add production cluster
argocd cluster add prod-context \
  --name production \
  --label environment=production \
  --label region=us-east \
  --namespace '*'

# Add staging cluster
argocd cluster add staging-context \
  --name staging \
  --label environment=staging \
  --label region=us-west \
  --namespace 'staging-*'

# Add development cluster
argocd cluster add dev-context \
  --name development \
  --label environment=development \
  --namespace 'dev-*,test-*'

​
Cluster Health Check

# List all clusters with status
argocd cluster list

# Get detailed cluster info
argocd cluster get production

# Check connectivity
kubectl --context production-context cluster-info

​
Organizing Clusters with Labels

# Add labels during cluster addition
argocd cluster add prod-east \
  --label environment=production \
  --label region=us-east-1 \
  --label provider=aws \
  --label tier=critical

# Update labels on existing cluster
argocd cluster set prod-east \
  --label environment=production \
  --label region=us-east-1 \
  --label provider=aws \
  --label tier=critical \
  --label compliance=pci-dss
These labels can be used in ApplicationSets: 
generators:
- clusters:
    selector:
      matchLabels:
        environment: production
        provider: aws

​
Namespace Restrictions

# Allow only specific namespaces
argocd cluster set production \
  --namespace production \
  --namespace monitoring \
  --namespace logging

# Allow all namespaces with wildcard
argocd cluster set production --namespace '*'

# Allow namespace patterns (regex)
argocd cluster set production \
  --namespace 'prod-*' \
  --namespace 'app-*'

​
Troubleshooting

​
Cluster Connection Issues

# Check cluster status
argocd cluster get production

# Verify kubeconfig access
kubectl --context production-context cluster-info

# Test Argo CD service account
kubectl --context production-context auth can-i '*' '*' \
  --as system:serviceaccount:kube-system:argocd-manager

# Rotate credentials if needed
argocd cluster rotate-auth production

​
Permission Errors

If Argo CD can’t deploy to a namespace: 
# Check allowed namespaces
argocd cluster get production -o yaml | grep namespaces -A 10

# Update namespace permissions
argocd cluster set production --namespace '*'

# Or add specific namespace
argocd cluster set production --namespace existing-ns --namespace new-ns

​
Certificate Issues

# List clusters with connection status
argocd cluster list -o wide

# Update cluster with new certificate
argocd cluster add production-context --upsert --insecure-skip-server-verification

# For self-signed certificates
argocd cluster add production-context \
  --upsert \
  --tls-client-cert-path /path/to/cert.pem \
  --tls-client-cert-key-path /path/to/key.pem

​
Service Account Setup

When adding a cluster, Argo CD creates a service account with appropriate permissions:
service-account.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: argocd-manager
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: argocd-manager-role
rules:
- apiGroups:
  - '*'
  resources:
  - '*'
  verbs:
  - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-manager-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: argocd-manager-role
subjects:
- kind: ServiceAccount
  name: argocd-manager
  namespace: kube-system
For more restricted access, customize the ClusterRole before adding the cluster.

​
Best Practices

  • Use descriptive cluster names that indicate environment and region
  • Apply consistent labels across clusters for ApplicationSet generators
  • Restrict namespace access where appropriate for security
  • Regularly rotate cluster credentials
  • Monitor cluster connection status
  • Use project restrictions to control which teams can deploy to which clusters

​
Next Steps

App Commands

Deploy applications to clusters

ApplicationSets

Deploy to multiple clusters automatically

Build docs developers (and LLMs) love

Get started for freeTalk to us