> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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`.

<Note>
  The cluster where Argo CD is running is called the "in-cluster" and doesn't need to be added explicitly.
</Note>

## Subcommands

### add

Add a cluster to Argo CD using your kubeconfig.

```bash theme={null}
# 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
```

<Tabs>
  <Tab title="Basic">
    Add a cluster using kubectl context:

    ```bash theme={null}
    # List available contexts
    kubectl config get-contexts

    # Add cluster
    argocd cluster add my-cluster-context
    ```
  </Tab>

  <Tab title="With RBAC">
    Create a service account with proper permissions:

    ```bash theme={null}
    # Add cluster with custom service account
    argocd cluster add my-cluster \
      --service-account argocd-manager \
      --system-namespace kube-system
    ```
  </Tab>

  <Tab title="Namespaced">
    Restrict cluster access to specific namespaces:

    ```bash theme={null}
    # Add cluster with namespace restrictions
    argocd cluster add my-cluster \
      --namespace app1 \
      --namespace app2 \
      --name my-cluster-restricted
    ```
  </Tab>

  <Tab title="With Labels">
    Add metadata for cluster selection:

    ```bash theme={null}
    argocd cluster add my-cluster \
      --label environment=production \
      --label region=us-east \
      --label team=platform
    ```
  </Tab>
</Tabs>

**Key Flags:**

<ParamField path="--name" type="string">
  Cluster name (defaults to context name)
</ParamField>

<ParamField path="--service-account" type="string">
  Service account for Argo CD to use
</ParamField>

<ParamField path="--namespace" type="string[]">
  Allowed namespaces (can be repeated, use '\*' for all)
</ParamField>

<ParamField path="--label" type="string[]">
  Cluster labels in key=value format
</ParamField>

<ParamField path="--project" type="string[]">
  Projects allowed to use this cluster
</ParamField>

<ParamField path="--shard" type="integer">
  Cluster shard number
</ParamField>

<ParamField path="--upsert" type="boolean">
  Update cluster if it already exists
</ParamField>

### list

List all configured clusters.

```bash theme={null}
# 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:**

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# 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:**

<ParamField path="--name" type="string">
  Update cluster name
</ParamField>

<ParamField path="--namespace" type="string[]">
  Set allowed namespaces (replaces existing)
</ParamField>

<ParamField path="--label" type="string[]">
  Set cluster labels (replaces existing)
</ParamField>

<ParamField path="--project" type="string[]">
  Set allowed projects (replaces existing)
</ParamField>

### rm

Remove a cluster from Argo CD.

```bash theme={null}
# 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
```

<Warning>
  Removing a cluster does not delete applications deployed to it, but Argo CD will no longer be able to sync them.
</Warning>

### rotate-auth

Rotate cluster authentication credentials.

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```yaml theme={null}
generators:
- clusters:
    selector:
      matchLabels:
        environment: production
        provider: aws
```

### Namespace Restrictions

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```yaml service-account.yaml theme={null}
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

<Note>
  * 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
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="App Commands" icon="rocket" href="/cli/app">
    Deploy applications to clusters
  </Card>

  <Card title="ApplicationSets" icon="layer-group" href="/cli/appset">
    Deploy to multiple clusters automatically
  </Card>
</CardGroup>