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. |
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.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.
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.
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.
Connect in Serval
Open the Rancher integration
In Serval, go to the integrations page and select Rancher (marked Beta).
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.
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.
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.
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.
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.Gotchas and troubleshooting
Connect fails with a generic error message
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.
The API key must be created with No Scope
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.
The token's user must be able to list users
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.
Enter a bare domain - HTTPS only
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.
Token expiry breaks the connection silently
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.
Domain-only edits are not re-tested
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.
Role-binding workflows require installer approval by default
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.
This integration is in Beta
This integration is in Beta
The Rancher connect tile is marked Beta, so the available actions and prebuilt workflows may still change.
Need help? Contact support@serval.com for assistance with your Rancher integration.