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

# Cluster token rotation

> Cluster install tokens are bearer credentials. Rotate them when an operator leaves, when a value file leaks, or as part of routine hygiene.

Each connected cluster has a bearer token (`rhc_<random>`). The Radar Cloud control plane stores only a SHA-256 hash; the in-cluster Radar presents the token over the WebSocket handshake. Rotating the token invalidates the old one and forces the in-cluster Radar to reconnect with the new one.

## When to rotate

* An operator with cluster-admin (or Helm-history) access leaves the team.
* A `values.yaml` containing the token leaks into a public repo, log file, or screenshot.
* You're following a routine rotation policy (every 90 days).
* You're moving the in-cluster Radar from one cluster to another and want a clean break.

## How to rotate

**Clusters → cluster → Rotate token** (owner-only).

1. Click **Rotate token**. The control plane mints a new `rhc_...` and **invalidates the old one immediately**.

2. The new token is shown once, with a Helm command pre-filled.

3. Run the command in the cluster:

   ```bash theme={null}
   helm upgrade radar oci://ghcr.io/skyhook-io/radar \
     -n radar \
     --reuse-values \
     --set cloud.token=rhc_NEW_VALUE
   ```

4. The in-cluster Radar reconnects within a few seconds. The cluster's status flips back to **connected**.

`--reuse-values` keeps every other Helm value you'd previously set (RBAC opt-ins, image tag, etc.). You're only swapping the token.

## What happens to the old token

It's gone. The hash is overwritten in Postgres, and any in-flight handshake using the old token returns `401`. There's no grace period - by design - so a leaked token stops working the moment you click rotate.

The action emits a `cluster.token_rotated` event in the [audit log](/docs/cloud/audit-log).

## Forgot to rotate before uninstalling?

If a cluster is gone but the token still exists in the control plane (no `cluster.disconnected` cooldown to clean it up), delete the cluster from **Clusters → cluster → Delete**. Deletion clears the registry row and the hash atomically.

## What if rotation goes wrong?

If the in-cluster Radar can't reach the control plane with the new token:

* The old token is already dead - rolling back the Helm release won't help (the rolled-back token is also invalid by then).
* The fix is **rotate again** with the same flow. Each rotation is cheap.

If the in-cluster Radar never picks up the new token:

```bash theme={null}
kubectl rollout restart -n radar deployment/radar
kubectl logs -n radar deploy/radar --tail=50
```

The logs will show `[cloud] connected to ...` on success or a 401 / TLS / DNS reason on failure.

## Don't store tokens in Helm values long-term

The install command shows the token in plain text for ergonomics. For production:

```yaml theme={null}
# values.yaml
cloud:
  enabled: true
  url: wss://api.radarhq.io/agent
  clusterName: cl_xxx
  existingSecret: radar-cloud-token   # K8s Secret with key `token`
```

```bash theme={null}
kubectl create secret generic radar-cloud-token \
  --from-literal=token=rhc_xxx \
  -n radar
```

That keeps the token out of Helm release history (which is readable to anyone with `secrets/get` in the namespace).

## See also

* [Connecting a cluster](/docs/cloud/connect-cluster) - the initial install flow.
* [Audit log](/docs/cloud/audit-log) - rotation events.
* [Cloud RBAC](/docs/cloud/rbac) - the token's relationship to in-cluster impersonation.