Skip to main content

​
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

These are Rancher’s standard management APIs - see Rancher’s 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.
1

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

Create the API key

Click Create API Key. Optionally add a description and set an expiration.
3

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

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

1

Open the Rancher integration

In Serval, go to the integrations page and select Rancher (marked Beta).
2

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

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

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

​
Gotchas and troubleshooting

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