Skip to main content
Each connected cluster authenticates to the Radar control plane (hosted Radar Cloud, or Radar Cloud Self-Managed on your infrastructure) with a bearer token (rhc_<random>). The control plane stores only a SHA-256 hash. Hub-generated installations read the token from a Kubernetes Secret and present it when opening the WebSocket tunnel. The token is a long-lived cluster credential, even though its raw value is revealed only once.

​
When to rotate

  • Routine - a rotation policy (every 90 days, say), an operator leaving on good terms, or a token you simply lost. Rotate with the default settings: the cluster stays online while you apply the replacement.
  • Leak - a values.yaml, log, or screenshot with the token in it went somewhere it shouldn’t, or an operator left on bad terms. Rotate with Revoke the current token immediately on.

​
What rotation does

Only an organization owner can rotate a cluster token, from Clusters > cluster row > Rotate token (the row says Reinstall while the cluster is disconnected and Install before it has ever connected; all three open the same dialog). Rotation issues a replacement token, reveals it once, and starts a grace window for the current one:
  1. The current token keeps working until Radar connects with the replacement, or for 24 hours, whichever comes first.
  2. Radar’s tunnel stays up. Nothing goes offline when you click Generate.
  3. The moment Radar connects with the replacement, the previous token stops authenticating.
  4. If the replacement is never applied, the previous token expires at the end of the window. Radar can no longer connect with it; apply the replacement to bring the cluster back.
While the window is open, the cluster’s row shows New token not applied yet; hovering it shows when the previous token expires. Rotating again before the replacement has connected supersedes that replacement: the newest token is the one to apply, and the token Radar is currently running on keeps its window unchanged. The one thing a second rotation does retire is a replacement you had already applied but that had not connected yet (a restart still in progress); if that happens, apply the newest artifact. Rotation emits a cluster.token_rotated event in the audit log. Its metadata records whether the previous token was revoked immediately.

​
Revoke a leaked token immediately

If the current token may have leaked, turn on Revoke the current token immediately before you click Generate. There is then no grace window:
  • the previous token stops authenticating with the click, so no new connection can use it;
  • Radar’s existing tunnel is closed as soon as the control plane sees it is still on the revoked token, and its reconnect attempts are rejected until the replacement is applied;
  • the cluster is offline until then. That interruption is the point of an emergency rotation.
Leave the switch off for routine rotation (a compliance schedule, an operator leaving on good terms): the cluster stays connected and you apply the replacement at your own pace within the window.

​
Why the pod must restart

The Hub’s generated install artifacts configure the Radar Helm chart to expose the Secret value to the Radar process as an environment variable. Updating the Secret does not change the environment of a running container, and the Radar process reads the token once at startup. Every generated recovery artifact therefore ends by restarting the Radar workload after the live Secret holds the replacement. That restart is what makes Radar connect with the new token and retire the old one. A GitOps reconciliation that updates only the Secret is not enough.

​
Apply the replacement

The dialog generates the steps for Helm, Argo CD, or Flux, plus the bare token for teams that manage the Secret themselves. After you run them, the dialog reports New token accepted as soon as Radar connects with the replacement. On a routine rotation the row stays Connected throughout; the row hint clears at the same moment. Generated commands target the namespace the agent last reported running in, and assume Helm release radar unless you opened the dialog from a link that named the release. If your release has another name, change it in every generated command (the Secret write, the upgrade, and the restart). helm list -A shows the real names.

​
Helm

The generated Helm command chains three stages with &&, so a failure in one stops the rest and the pod is never restarted into a state without a token:
  1. writes the replacement into the radar-cloud-config Secret;
  2. runs helm upgrade on the release with --reset-then-reuse-values, pinned with --version to the chart version the agent currently reports, and with cloud.existingSecretKey=token so a custom key from an earlier release is not carried forward; and
  3. restarts the Radar deployment.
The pin means “Rotate token” never upgrades Radar as a side effect. When the agent reports a version that is not a published chart (a development build), or the cluster has never connected, the command installs the newest stable chart instead and says so. The upgrade stage is what migrates an installation that still sets cloud.token inline to the Secret-backed layout. If your release reads a Secret with another name or key, use the bare token instead of the generated command.

​
Argo CD or Flux

GitOps recovery has two steps, and the dialog shows both:
  1. Update the token in the source that manages radar-cloud-config (the generated kubectl create secret line, your ExternalSecret or SealedSecret source, or the values patch for an inline cloud.token).
  2. After the live Secret holds the new value, restart the Radar deployment:
    When the release name is assumed rather than known, the generated command selects by chart instead, -l app.kubernetes.io/name=radar, which restarts every Radar deployment in that namespace. If you installed the chart with nameOverride, that label differs too: use your release’s instance label as above, and check that the deployment actually restarted (kubectl rollout status).
Wait for the live Secret to change before restarting. A pod restarted while the Secret still holds the old value simply reconnects with the old token, which keeps working inside the grace window, and the dialog stays amber.

​
Install a raw replacement token

Under the generated commands, Managing the Secret yourself? Copy just the token reveals the raw value without prescribing how your cluster is managed. Use this with ExternalSecrets, SealedSecrets, a values file you own, or any other automation. Store it in the radar-cloud-config Secret under the key token, or in whichever Secret and key your values point cloud.existingSecret and cloud.existingSecretKey at; the manifest references the Secret by name and never carries the value. If your release sets cloud.token directly, update that Helm value instead; changing the pod template makes Helm roll the pod. For a directly managed Kubernetes Secret, write it and then restart the pod:
Replace NAMESPACE and RELEASE with the installation’s actual namespace and Helm release. Do not commit the raw token to Git. An inline cloud.token also persists in Helm release history, which is stored in a Secret in the release namespace; prefer cloud.existingSecret. Commands that include the token can also enter shell history and briefly expose it in the process list, so run them from an appropriately protected administrator environment. Anyone who can read this Secret can authenticate as the cluster agent. Treat the value like any other production credential.

​
If the token reveal is interrupted

The replacement is shown once. Closing the dialog before copying anything asks you to confirm; if you close anyway, rotate again to mint another replacement. On a routine rotation the cluster stays connected on its current token meanwhile, and that token keeps its original window, so nothing is lost but the unused value. This also applies to a partially completed first install: an earlier generated command stops working once a newer one has connected (or its window lapses), so use only the latest artifact.

​
If Radar doesn’t reconnect

The dialog stays amber until Radar connects with the replacement. If it has been more than a few minutes, the agent’s own log says why in one line:
  • No new [cloud] connected line: the restart didn’t happen, or the Secret still held the old value when it did. Re-run the restart after the live Secret has changed.
  • 401: the pod is presenting a token that no longer works (revoked, or its window lapsed). Apply the replacement and restart.
  • A TLS or DNS error: the pod can’t reach the control plane at all; see Connecting a cluster.
The replacement token does not expire while you troubleshoot.

​
Deleting the Hub record is different from uninstalling Radar

Deleting a cluster from Radar Hub removes its control-plane record and credential. It does not uninstall the in-cluster Helm release. Likewise, uninstalling Radar does not delete the Hub record. Deleting the record is not a way to revoke a token: it also discards the cluster’s history and settings. Use Revoke the current token immediately for that.

​
Hosted and self-managed control planes

The rotation mechanics are the same for hosted Radar Cloud and your self-managed control plane. Only the Hub URL, and cloud.insecureSkipVerify when your Hub serves a self-signed certificate, differ in the installation configuration.

​
See also