argocd cluster

Manage cluster credentials and connections in Argo CD

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

Basic

Add a cluster using kubectl context:

# List available contexts
kubectl config get-contexts

# Add cluster
argocd cluster add my-cluster-context

With RBAC

Create a service account with proper permissions:

# Add cluster with custom service account
argocd cluster add my-cluster \
  --service-account argocd-manager \
  --system-namespace kube-system

Namespaced

Restrict cluster access to specific namespaces:

# Add cluster with namespace restrictions
argocd cluster add my-cluster \
  --namespace app1 \
  --namespace app2 \
  --name my-cluster-restricted

With Labels

Add metadata for cluster selection:

argocd cluster add my-cluster \
  --label environment=production \
  --label region=us-east \
  --label team=platform

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