> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Clusters

> Connect and manage Kubernetes clusters for GitOps deployments

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

## Key Concepts

<CardGroup cols={2}>
  <Card title="Cluster" icon="cloud">
    A Kubernetes cluster connected to ArgoCD for application deployments.
  </Card>

  <Card title="API Server" icon="server">
    The Kubernetes API server endpoint used for cluster communication.
  </Card>

  <Card title="Bearer Token" icon="key">
    ServiceAccount token used to authenticate ArgoCD with the cluster.
  </Card>

  <Card title="Connection Status" icon="signal">
    Health status indicating whether ArgoCD can reach and authenticate with the cluster.
  </Card>
</CardGroup>

## Required Permissions

| Action          | Permission                       |
| --------------- | -------------------------------- |
| View clusters   | `iam:project:cicd:argocd:read`   |
| Add clusters    | `iam:project:cicd:argocd:write`  |
| Delete clusters | `iam:project:cicd:argocd:delete` |

## Connection Status

| Status         | Description                                       |
| -------------- | ------------------------------------------------- |
| **Successful** | Cluster is reachable and authentication succeeded |
| **Failed**     | Connection or authentication failed               |
| **Unknown**    | Status not yet determined                         |

## How to Add a Cluster

<Steps>
  <Step title="Select ArgoCD Instance">
    Choose the ArgoCD instance from the dropdown in the toolbar.
  </Step>

  <Step title="Click Add Cluster">
    Click the **Add Cluster** button in the header.
  </Step>

  <Step title="Enter Cluster Name">
    Provide a friendly name to identify the cluster.
  </Step>

  <Step title="Enter API Server URL">
    Enter the Kubernetes API server URL (e.g., `https://cluster.example.com:6443`).
  </Step>

  <Step title="Enter Bearer Token">
    Paste the ServiceAccount bearer token for authentication.
  </Step>

  <Step title="Configure TLS">
    Either provide a CA certificate or enable insecure mode (skip TLS verification).
  </Step>

  <Step title="Enable Cluster Resources (Optional)">
    Toggle to allow ArgoCD to manage cluster-scoped resources.
  </Step>

  <Step title="Add">
    Click **Add Cluster** to connect the cluster.
  </Step>
</Steps>

## Required Fields

| Field              | Required    | Description                                  |
| ------------------ | ----------- | -------------------------------------------- |
| **Cluster Name**   | Yes         | Friendly identifier for the cluster          |
| **API Server URL** | Yes         | Kubernetes API server endpoint               |
| **Bearer Token**   | Yes         | ServiceAccount token for authentication      |
| **CA Certificate** | Conditional | Required unless TLS verification is disabled |

## TLS Configuration

### Secure Mode (Recommended)

When TLS verification is enabled (default), you must provide the CA certificate:

| Field                       | Description                                                               |
| --------------------------- | ------------------------------------------------------------------------- |
| **CA Certificate (caData)** | Base64-encoded CA certificate for verifying the cluster's TLS certificate |

### Insecure Mode

Enable "Disable TLS Verification" to skip certificate validation.

<Warning>
  Insecure mode should only be used for development or testing. Always use proper TLS verification in production environments.
</Warning>

## Cluster Options

| Option                            | Default | Description                                                                    |
| --------------------------------- | ------- | ------------------------------------------------------------------------------ |
| **Enable Cluster-wide Resources** | Off     | Allow ArgoCD to manage cluster-scoped resources (ClusterRole, Namespace, etc.) |

<Info>
  Enable cluster-wide resources only if your applications need to create or manage cluster-scoped Kubernetes resources.
</Info>

## 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:

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

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

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

<Tip>
  If your kubeconfig has multiple clusters, adjust the jsonpath index or use the cluster name to get the correct certificate.
</Tip>

## How to Delete a Cluster

<Steps>
  <Step title="Find the Cluster">
    Locate the cluster in the list.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon on the cluster row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection status shows Failed" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="TLS certificate error" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Authentication failed" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot create cluster resources" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cluster shows 0 applications" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot delete cluster" icon="circle-question">
    * Verify you have delete permission
    * Check if applications are still deploying to this cluster
    * Try refreshing the page and attempting again
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is the 'in-cluster' cluster?">
    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.
  </Accordion>

  <Accordion title="Can I edit cluster settings after creation?">
    Currently, clusters cannot be edited. To change settings, delete the cluster and add it again with the new configuration.
  </Accordion>

  <Accordion title="How often does ArgoCD check cluster connectivity?">
    ArgoCD periodically checks cluster connectivity. The "Last Check" column shows when the last check occurred. Failed clusters are checked more frequently.
  </Accordion>

  <Accordion title="What permissions does the ServiceAccount need?">
    For full functionality, the ServiceAccount needs cluster-admin privileges or equivalent permissions to create, update, and delete resources across namespaces.
  </Accordion>

  <Accordion title="Can I use a kubeconfig file instead of bearer token?">
    The UI requires bearer token authentication. For other authentication methods (client certificates, OIDC), use the ArgoCD CLI or API directly.
  </Accordion>

  <Accordion title="Why is my cluster version not showing?">
    The version is retrieved during connectivity checks. If the cluster is unreachable or recently added, the version may not be available yet.
  </Accordion>

  <Accordion title="Can multiple ArgoCD instances connect to the same cluster?">
    Yes. Each ArgoCD instance maintains its own cluster connections. The same Kubernetes cluster can be registered in multiple ArgoCD instances.
  </Accordion>

  <Accordion title="What happens if the bearer token expires?">
    Cluster operations will fail with authentication errors. Create a new token and re-add the cluster with the updated credentials.
  </Accordion>
</AccordionGroup>

## 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