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

# Rancher

> Connect Serval to your self-hosted Rancher management server so workflows can list and manage Rancher users, global roles and role bindings, role templates, and projects.

## About Rancher

Rancher is a management platform for Kubernetes clusters. This integration connects Serval to your self-hosted Rancher management server so workflows can read and manage Rancher users, global roles and role bindings, role templates, and projects. The integration is currently marked **Beta** in the connect screen, so its capabilities and prebuilt workflows may still change.

**Authentication:** API key (a Rancher Bearer Token, plus the domain of your Rancher instance). There is no OAuth flow - the token stays valid until it expires or you replace it in Rancher.

**Data sync:** None - everything is on demand. Serval only calls your Rancher server when you save the connection or a workflow runs. There is no background sync, no webhooks, and no data ingestion.

## What the Rancher integration enables

| Capability                 | Description                                                                                                                                                                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rancher API request        | A generic workflow action that can call any of the 31 supported endpoints on Rancher's management APIs, covering users, global roles, global role bindings, role templates, projects, cluster and project role bindings, tokens, kubeconfigs, and audit policies. |
| List Rancher Users         | Prebuilt workflow that lists all users in your Rancher management plane. Installs with no approval required by default.                                                                                                                                           |
| List Global Roles          | Prebuilt workflow that lists all global roles defined in Rancher. Installs with no approval required by default.                                                                                                                                                  |
| List Global Role Bindings  | Prebuilt workflow that lists all global role bindings, showing which users hold which roles. Installs with no approval required by default.                                                                                                                       |
| List Projects              | Prebuilt workflow that lists all projects across namespaces. Installs with no approval required by default.                                                                                                                                                       |
| List Role Templates        | Prebuilt workflow that lists the role templates used for cluster and project access control. Installs with no approval required by default.                                                                                                                       |
| Create Global Role Binding | Prebuilt workflow that assigns a global role (such as admin or user) to a Rancher user. Installs with installer approval required by default.                                                                                                                     |
| Delete Global Role Binding | Prebuilt workflow that removes a user's global role binding. Installs with installer approval required by default.                                                                                                                                                |

These are Rancher's standard management APIs - see Rancher's [API quickstart](https://ranchermanager.docs.rancher.com/api/quickstart) for background on the underlying interfaces.

## Get your credentials

Serval needs two things: the domain of your Rancher instance and a Rancher API key's **Bearer Token**. Create the key as a user with admin-level global permissions, following Rancher's [API key guide](https://ranchermanager.docs.rancher.com/reference-guides/user-settings/api-keys).

<Steps>
  <Step title="Open your account settings in Rancher">
    Sign in to the Rancher UI as an administrator, click your user avatar in the upper right, and choose **Account & API Keys**.
  </Step>

  <Step title="Create the API key">
    Click **Create API Key**. Optionally add a description and set an expiration.
  </Step>

  <Step title="Leave Scope set to No Scope">
    Do not select a cluster scope. Serval talks to Rancher's management plane, and a cluster-scoped key only works against a single cluster, so it will fail Serval's connection test.
  </Step>

  <Step title="Copy the Bearer Token">
    Click **Create**, then copy the **Bearer Token** value right away - it is shown only once. The **Endpoint** shown on the same screen contains your instance domain: use just the domain part, without the "https\://" prefix.
  </Step>
</Steps>

<Warning>
  Copy the full **Bearer Token** string, not the separate access key or secret key shown alongside it. If you lose it, delete the key and create a new one.
</Warning>

<Note>
  Rancher API keys can expire (your server's token settings cap the maximum lifetime). When the key expires, the Serval connection stops working until you paste in a new token, so note the expiration date you choose.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Rancher integration">
    In Serval, go to the integrations page and select **Rancher** (marked Beta).
  </Step>

  <Step title="Enter the Instance Domain">
    Enter the bare domain of your Rancher instance, for example "rancher.example.com" - no "https\://" prefix and no path. Serval always connects over HTTPS.
  </Step>

  <Step title="Enter the Bearer Token">
    Paste the full Bearer Token you copied from Rancher into the **Bearer Token** field. This is a password-style field; after saving, Serval shows it masked, with only the last 4 characters visible.
  </Step>

  <Step title="Save and validate">
    When you save, Serval tests the credentials by listing the users in your Rancher management plane and rejects the save if that call fails. Neither field shows inline validation messages, and the underlying failure reason is not surfaced - a failed save shows a general error such as "Failed to connect service" or "Failed to install integration". See the troubleshooting section below for what to check.
  </Step>
</Steps>

<Note>
  When editing an existing connection, the **Instance Domain** comes pre-filled and the **Bearer Token** appears masked with a **Replace** option. Leave the token untouched (or blank) to keep the stored token - only enter a value when rotating the key. Leaving **Instance Domain** blank likewise keeps the stored domain. Serval re-tests the connection only when a new token is submitted, so saving a domain change without a new token does not re-test the connection.
</Note>

## Verifying the connection

Serval tests the Rancher connection at save time only: when you first connect, and again whenever you submit a new Bearer Token, it lists the users in your Rancher management plane and rejects the save if that call fails. There are no recurring health checks for this integration, so nothing runs in the background after you connect. To verify the connection at any time, run the **List Rancher Users** prebuilt workflow - if it returns your users, the connection works.

<Tip>
  If the list workflows succeed but the **Create Global Role Binding** or **Delete Global Role Binding** workflows fail, the token's user can read users but lacks permission to change global role bindings. Recreate the API key under a full admin account.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Connect fails with a generic error message">
    Serval does not surface the underlying reason for a failed connection test - you only see a general error such as "Failed to connect service" or "Failed to install integration". Before retrying, check the three usual causes in order: the **Instance Domain** is filled in, spelled correctly, and reachable over HTTPS; the API key was created with **No Scope**; and the **Bearer Token** was pasted in full. Failed edits show messages like "Failed to update configuration" or "Failed to update integration" instead.
  </Accordion>

  <Accordion title="The API key must be created with No Scope">
    Serval calls Rancher's management plane, not an individual cluster. A key scoped to a single cluster only authorizes that cluster's Kubernetes API, so the connection test fails even though the key itself is valid. Rancher's own API quickstart likewise instructs creating the key with no scope.
  </Accordion>

  <Accordion title="The token's user must be able to list users">
    The connection test lists users in the Rancher management plane. If the key belongs to a user without global permission to list users, the connection is rejected. Use a key created by an admin-level account.
  </Accordion>

  <Accordion title="Enter a bare domain - HTTPS only">
    The **Instance Domain** field takes the domain only (for example "rancher.example.com"). Serval adds the "https\://" prefix itself, so pasting a full URL produces a broken address, and Rancher installs served over plain HTTP are not supported.
  </Accordion>

  <Accordion title="Token expiry breaks the connection silently">
    Rancher API keys expire based on your server's token lifetime settings, and Serval has no automatic refresh for them. Because this integration has no recurring health checks, an expired key surfaces as workflow runs failing - they keep failing until you open the integration settings and replace the Bearer Token.
  </Accordion>

  <Accordion title="Domain-only edits are not re-tested">
    Serval only re-validates the connection when a new Bearer Token is submitted. If you change just the **Instance Domain**, the update saves without a test call, so a typo is not caught until the next workflow run fails.
  </Accordion>

  <Accordion title="Role-binding workflows require installer approval by default">
    The **Create Global Role Binding** and **Delete Global Role Binding** workflows install with installer approval required, while the five list workflows install with no approval. Adjust the approval procedure after installing if your team needs different controls.
  </Accordion>

  <Accordion title="This integration is in Beta">
    The Rancher connect tile is marked Beta, so the available actions and prebuilt workflows may still change.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Rancher integration.