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

# 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](/guide/agents/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](#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

<Steps>
  <Step title="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](#required-permissions).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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

<Warning>
  **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.
</Warning>

## 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](/guide/connections/kubernetes) for that.

### Verify the connection

```text theme={null}
Summarize the clusters Rancher manages, their projects, and node health
```

### Example prompts

```text theme={null}
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

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Rancher URL must use HTTPS">
  The address is plain `http`, which would send the token in clear text. Serve Rancher over HTTPS and reconnect.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

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

<CardGroup cols={2}>
  <Card title="Kubernetes Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/kubernetes.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=7c03292954ff635a1994623a5c39971b" href="/guide/connections/kubernetes" width="24" height="24" data-path="images/icons/kubernetes.svg">
    Workload analysis, resource optimization, and cluster operations
  </Card>

  <Card title="Kai Agent" icon="dharmachakra" href="/guide/agents/kai">
    Kubernetes-focused operations agent
  </Card>
</CardGroup>