Rancher

Connect Rancher to CloudThinker for read-only cluster and project inventory, cluster and node health, and a review of who has access

Connect your Rancher server to let Kai (Kubernetes Engineer) list the clusters, projects, and nodes Rancher manages, check cluster health and node readiness, and review who holds Rancher access to a cluster or 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.

Setup

1. Create a read-only Rancher user

   Add a user for CloudThinker 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. Give it read access through Rancher’s built-in Cluster Member and Read Only project roles, or 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. A key that lapses breaks the connection with a rejected-token error, so match the expiry to your rotation schedule.

   Leave Scope as No Scope. A scoped key works only against the Kubernetes API of one cluster, not against the Rancher API this connection reads; narrow access through the user’s roles instead.

   Copy the Bearer Token. Rancher shows it once.

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. Do not append an API path, query string, fragment, or credentials; CloudThinker adds the API path itself and rejects a URL that carries anything else. The URL must use https, because the token is sent with every request.

Connection details

Field	Description	Example
Rancher URL	The HTTPS address you sign in to, with no API path, query, fragment, or credentials	https://rancher.example.com
API token	The Bearer Token from the API key you created	—
CA certificate bundle	Optional. The PEM certificates of a private certificate authority	—

TLS verification cannot be turned off, 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 — beginning -----BEGIN CERTIFICATE-----, ending -----END CERTIFICATE-----, under 256 KB, and containing no private key.

Required permissions

The token needs read access to the Rancher management resources the connection inspects: clusters, nodes, projects, and cluster and project role bindings. Start from a built-in role and narrow it:

Role	What it gives
Cluster Member	Views most cluster-level resources and can create new projects
Read Only (project)	Views everything in a project, and cannot create, update, or delete
Custom role	Grants only the reads above, when Cluster Member is wider than you want

No Rancher permission beyond read is ever needed. There is no Rancher action an agent can take, so 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 management resources above. Everything below stays out of reach even when the token itself is allowed to read it:

• Secrets, kubeconfigs, API tokens, and cluster registration tokens
• Cloud credentials, authentication settings, and 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 tells you the connection cannot, and that nothing changed. It does not try another route.

Agent capabilities

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

Capability	Description
Cluster inventory	List the clusters Rancher manages, the projects on them, and their nodes
Cluster health	Report the current conditions of one named cluster and the readiness of its nodes
Who has access	Show which users, groups, and service accounts hold a role on one cluster or project
Project scope	Show which cluster a project belongs to

Answers are bounded: each lookup returns one page of at most 50 results, and when Rancher does not report a total, agents say “returned 12” rather than “12 exist”. Each message gets one look at Rancher, so 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; use the Kubernetes connection for that.

Verify the connection

Summarize the clusters Rancher manages, their projects, and node health

Example prompts

The health conditions and node readiness of the prod-sea cluster in Rancher
Anything to tighten in who holds Rancher access to the prod-sea cluster
The Rancher projects on staging-cluster and which nodes are not ready

Troubleshooting

Rancher rejected the API token

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 lacks read access to managed clusters

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 Rancher server did not expose the management API

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, and check your Rancher version.

Could not reach the Rancher server, or a redirect was refused

Nothing answered, or the address redirects elsewhere — CloudThinker never follows a redirect, because that would hand your token to a server you did not name. 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.

Rancher URL must use HTTPS

The address is plain http, which would send the token in clear text. Serve Rancher over HTTPS and reconnect.

Invalid Rancher CA certificate bundle or connection configuration

The bundle is not plain PEM certificates, or the API token is empty or carries whitespace or quoting that cannot be sent in a request header. Paste the CA certificate chain only — never a server key — and re-copy the Bearer Token without surrounding quotes or line breaks.

An agent reports fewer clusters than Rancher shows

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.

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

Related

Kubernetes Connection

Workload analysis, resource optimization, and cluster operations

Kai Agent

Kubernetes-focused operations agent