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

# Connecting a cluster

> Install Radar in your Kubernetes cluster, what each Helm value does, RBAC scope, and how to verify the connection.

Connecting a cluster to Radar Cloud is one Helm command. The chart you install is the **same** chart Radar OSS uses - just with `cloud.enabled=true` and a one-time install token. The Radar pod dials `api.radarhq.io/agent` over an outbound WebSocket; you don't need any inbound rules on your cluster.

## Get the install command

In `app.radarhq.io`, click **Connect a cluster**, name it (the underlying ID is opaque `cl_...`), then **Generate install command**. The page polls for connection while you run it.

The command looks like:

```bash theme={null}
helm upgrade --install radar oci://ghcr.io/skyhook-io/radar \
  --namespace radar --create-namespace \
  --set cloud.enabled=true \
  --set cloud.url=wss://api.radarhq.io/agent \
  --set cloud.token=rhc_xxx... \
  --set cloud.clusterName=cl_xxx... \
  --set rbac.helm=true \
  --set rbac.secrets=true \
  --set rbac.podExec=true \
  --set rbac.portForward=true
```

<Warning>The token is shown **once**. If you lose it before completing the install, rotate it from **Clusters → cluster → Rotate token** - this invalidates the unused token.</Warning>

## What each value does

| Value                | Effect                                                                                                      |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `cloud.enabled=true` | Switches the chart to cloud-mode (auth proxy, ClusterRoleBindings for `cloud:*` groups, hardened listener). |
| `cloud.url`          | The WebSocket endpoint to dial. `wss://api.radarhq.io/agent` for production.                                |
| `cloud.token`        | One-time bearer credential identifying this cluster. SHA-256 hashed at rest by the control plane.           |
| `cloud.clusterName`  | The opaque cluster ID assigned by the control plane. The Radar pod advertises this on handshake.            |
| `rbac.helm`          | Enables Helm install / upgrade / rollback / uninstall. Auto-enables `rbac.secrets`.                         |
| `rbac.secrets`       | Allows the resource browser to show Secrets.                                                                |
| `rbac.podExec`       | Enables the pod terminal and debug containers.                                                              |
| `rbac.portForward`   | Enables port forwarding through the UI.                                                                     |

You can drop any of the `rbac.*` flags to restrict what Radar can do in your cluster - the UI gracefully degrades. See [In-cluster deployment](/docs/configuration/in-cluster) for the full list.

## What the chart deploys

```
Namespace: radar
├─ Deployment: radar            # the OSS binary in cloud-mode
├─ ServiceAccount: radar
├─ ClusterRole / ClusterRoleBinding (read access + opt-ins)
├─ ClusterRoleBindings:
│   cloud:owner   → admin
│   cloud:member  → edit
│   cloud:viewer  → view
└─ Service / NetworkPolicy (optional)
```

There's no Service exposed to the outside - the Radar pod only needs **outbound** TLS to `api.radarhq.io:443`. No ingress, no LB, no DNS.

## Verify the connection

Inspect the installation from any machine with access to the cluster:

```bash theme={null}
radar cloud status --context my-cluster
```

The command reports the detected Helm or GitOps installation, chart and image, agent readiness, Cloud configuration, Hub URL, configured cluster reference, and the cluster ID and tunnel state reported by the Hub. It is read-only and never prints the connection token. If Radar finds multiple installations, select one with `--namespace` and `--release`.

To check the tunnel, Radar reads the token from the Kubernetes Secret referenced by the Deployment and sends it directly to the configured Hub. A confirmed disconnected tunnel or rejected token makes the command fail. If your Kubernetes identity cannot read that Secret, or the Hub cannot be reached, the tunnel check is shown as unavailable while the local installation diagnostics still run.

The install page polls for up to 5 minutes. Once connected, you'll be redirected into the cluster view. If polling times out:

```bash theme={null}
# Radar pod logs
kubectl logs -n radar deploy/radar

# Look for:
[cloud] connected to wss://api.radarhq.io/agent as cl_xxx...
[cloud] handshake ok, cluster status -> connected
```

Common failures:

| Symptom                         | Likely cause                                                                                            |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `401 unauthorized` on handshake | Token invalid or rotated. Generate a new install command.                                               |
| `connection refused`            | Egress firewall blocking outbound `api.radarhq.io:443`.                                                 |
| `TLS handshake failure`         | Outbound proxy doing TLS inspection without the corporate CA injected into the Radar pod's trust store. |
| Connects then drops             | The Radar pod must run on a single replica; check for crash loops via `kubectl describe pod`.           |

## Reinstall vs. rotate

* **Reinstall** - re-run the same Helm command with a fresh token. Used when you've lost the original install yaml.
* **Rotate token** - issues a new token without changing the cluster ID. The previous token stops working immediately. Useful when an operator leaves or you suspect token leak.

See [Cluster token rotation](/docs/cloud/cluster-token) for both flows.

## Egress requirements

| Destination                                     | Port | Why                                                          |
| ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| `api.radarhq.io`                                | 443  | The control-plane WebSocket.                                 |
| Container registry that hosts the chart / image | 443  | Pulling the Radar image. Default `ghcr.io/skyhook-io/radar`. |

## Air-gapped clusters

Cloud assumes outbound TLS to `api.radarhq.io`. Air-gapped environments should run [Radar OSS](/docs/install) instead - it's the same UI without the control plane.

## See also

* [Cloud RBAC](/docs/cloud/rbac) - how `cloud:owner` / `cloud:member` / `cloud:viewer` map to K8s.
* [Cluster token rotation](/docs/cloud/cluster-token) - rotation flow.
* [In-cluster deployment](/docs/configuration/in-cluster) - the chart's full value reference.