Skip to main content
Connect your Rancher server to let Kai (Kubernetes) list the clusters, projects, and nodes Rancher manages, check the health conditions of one cluster and the readiness of its nodes, and review who holds Rancher access to a cluster or a project. Rancher authenticates with an API key bearer token. The connection is read-only and deliberately narrow: agents can describe what Rancher manages and can change none of it.

​
Prerequisites

  • A Rancher server on 2.8 or later, reachable from CloudThinker over HTTPS. 2.8 is the first release to support the Rancher Kubernetes API, which is the only thing this connection reads.
  • A dedicated Rancher user for CloudThinker with read access to the clusters and projects you want inspected — see Required permissions.
  • A Rancher API key for that user.
  • Optional: a PEM certificate bundle if your Rancher certificate is issued by a private CA.
Create a dedicated Rancher user rather than reusing a person’s account. The token inherits that user’s access, so a dedicated reader keeps the scope visible and revocable in one place.

​
Setup

1

Create a read-only Rancher user

Add a user for CloudThinker and give it read access to the clusters and projects it should see. Rancher’s built-in Cluster Member role lets a user view most cluster-level resources, and the Read Only project role lets a user view everything in a project without creating, updating, or deleting anything. For a tighter scope, build a custom role — see Required permissions.
2

Create an API key

Sign in as that user, open the user avatar → Account & API Keys in the upper right, and click Create API Key.Set an Expiry. Rancher caps it at the server’s auth-token-max-ttl-minutes setting and silently uses that cap when you ask for longer.Leave Scope as No Scope. A scoped key works only against the Kubernetes API of the cluster you scope it to, not against the Rancher API this connection reads. Narrow the access through the user’s roles instead, not through the key.Copy the Bearer Token. Rancher shows it once, along with the Access Key and Secret Key.
3

Add the connection in CloudThinker

Navigate to Connections → Rancher and enter:
  • Rancher URL: the address you sign in to, such as https://rancher.example.com
  • API token: the Bearer Token you just copied
  • CA certificate bundle: leave blank unless Rancher uses a private CA
Click Connect. CloudThinker reads a single cluster from Rancher to verify the token, and the status turns Connected.
Enter the Rancher address only — the same one you sign in to, such as https://rancher.example.com. Do not append an API path, a query string, a fragment, or a username and password. CloudThinker adds the API path itself and rejects a URL that carries anything else.
A Rancher API key stops working at its expiry, and the connection then fails with a rejected-token error. Set an expiry that matches your rotation schedule and update the connection with a new token before the old one lapses.

​
Connection details

The Rancher URL must use https. The token is sent with every request, so plain http is rejected.
TLS verification cannot be turned off. There is no skip-verification option, because the token is sent to whichever server answers. If Rancher uses a private CA, paste that CA’s certificates into CA certificate bundle instead. The field accepts PEM certificates only — it must begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----, stay under 256 KB, and contain no private key.

​
Required permissions

The token needs read access to the Rancher management resources the connection inspects: Start from a built-in role and narrow it:
No Rancher permission beyond read is ever needed. There is no Rancher action an agent can ask you to approve, because there is no Rancher action it can take at all — granting write access only widens what a leaked token could do.

​
What this connection cannot reach

The connection can only ask Rancher to read, and only from the small set of management resources listed above. Everything below stays out of reach even when the token itself is allowed to read it:
  • Secrets and kubeconfigs
  • API tokens and cluster registration tokens
  • Cloud credentials and authentication settings
  • Global settings
  • Every change to Rancher — creating, updating, deleting, or scaling anything
  • The older Rancher v3 API, which the connection never calls
Ask an agent to change something in Rancher and it will tell you the connection cannot do it, and that nothing changed. It will not try another route.

​
Agent capabilities

Once connected, agents can read what Rancher knows about your clusters.

​
Verify the connection

​
Example prompts

Answers are bounded so a broad question cannot pull everything Rancher manages: each lookup returns one page of at most 50 results. When Rancher does not report a total, agents say “returned 12” rather than “12 exist” — a full page is not proof that you have seen everything. Name the cluster or project you care about to get an exact answer.
Each message gets one look at Rancher. Ask two Rancher questions at once and the agent answers the second from what the first returned, rather than fetching again. Send a follow-up message when you want fresh data.
Agents read the roles granted in Rancher only. They do not inspect the RBAC rules inside the Kubernetes cluster itself, so they cannot tell you what a user can do once they are in. Use the Kubernetes connection for that.

​
Troubleshooting

The key expired, was deleted, or was copied incompletely. Rancher shows the Bearer Token only once, so create a new key under Account & API Keys and update the connection.
The token authenticated, but its Rancher user cannot read the clusters. Give that user the required read-only role on the clusters you want inspected, then test the connection again.
The URL points somewhere other than Rancher, or this Rancher is older than 2.8, the first release to support the Rancher Kubernetes API. Reconnect with the Rancher address only, such as https://rancher.example.com, and check your Rancher version.
Rancher, or a proxy or load balancer in front of it, returned HTTP 429. Wait, then ask one narrow question rather than several broad ones.
Nothing answered at that URL. Check the host, the network path from CloudThinker, and — if Rancher uses a private CA — that the CA certificate bundle is the one that issued its certificate.
The address you entered does not answer directly; something in front of it redirects elsewhere. CloudThinker never follows a redirect, because that would hand your token to a server you did not name. Point the connection at the address that serves Rancher itself.
The address is plain http, which would send the token in clear text. Serve Rancher over HTTPS and reconnect.
The bundle is not plain PEM certificates. It must begin with -----BEGIN CERTIFICATE-----, end with -----END CERTIFICATE-----, stay under 256 KB, and contain no private key. Paste the CA certificate chain only, never a server key.
The API token is empty, or it carries whitespace or quoting that cannot be sent safely in a request header. Re-copy the Bearer Token from Rancher without surrounding quotes or line breaks.
Either the token’s user cannot see the rest, or the answer came from a single page of results. Check the user’s cluster access first, then narrow the question to the cluster or project you care about.

​
Security

  • Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
  • Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
  • Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
  • Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
  • TLS verification is always on — it cannot be disabled, so a private CA needs its bundle pasted in rather than a skipped check.
  • Narrow through roles, not the key — a Rancher API key has no read-only setting, so what the token can see is exactly what its user can see. Give that user the least access it needs.
  • Watch the expiry — a key that lapses silently breaks the connection; rotate it on schedule and update the connection with the new token.
  • Read-only by construction — the connection can only ask Rancher to read, so no permission you grant turns it into a way to change anything.

Kubernetes Connection

Workload analysis, resource optimization, and cluster operations

Kai Agent

Kubernetes-focused operations agent