Skip to main content

Configuring Rancher Integration

The Rancher integration creates a seamless experience that enables self-service virtual cluster creation and management for teams already using Rancher to manage their Kubernetes fleet. Now you can provision and manage the entire lifecycle of virtual clusters in Rancher the same way you would any traditional Kubernetes cluster.

The Rancher integration enables organizations to:

  • Unify management of virtual clusters and regular clusters within Rancher alongside each other.
  • Enable virtual cluster self-service for Rancher users within guardrails defined by Rancher admins.
  • Continue using Rancher for user management while syncing permissions between Rancher and vCluster Platform.

Prerequisites​

Before you begin, make sure you have the following:

  • A running vCluster Platform
  • A running Rancher Server
  • A Rancher API Bearer Token to allow the Platform to access and perform actions in Rancher
Bearer Token

The Bearer Token to be used should have a long expiration or must be rotated using an external mechanism as it will be used for every call to the Rancher API

Setup​

Install the Rancher extension​

  1. In the Rancher UI, click on the Extensions link in the left side menu, then click on the ellipsis menu on the top right and select Manage Repositories.

  2. Click on on the right. Give the repository a name and enter https://charts.loft.sh/ as the Index URL.

  3. Click on at the bottom.

  4. Navigate back to the Extensions page and click on Available tab. Click on the extension named VCluster.Pro.

  5. Now we'll add a label on the Rancher management cluster resource management.cattle.io/v1 group. In the left side nav menu, click on the Cluster Management link and then click the on the ellipsis button of the management cluster where Rancher is installed and then select the Edit Config option.

  6. Click on the Labels & Annotations row and click on . Finally, add loft.sh/loft-hostname for the label's key and your Platform hostname without the protocal prefix, e.g. my-vcluster-platform.dev

Configure the Platform​

Now we'll add the Rancher object to the Platform configuration in order to set up a global Rancher integration. This enables the Platform to communicate with Rancher via its API and perform the necessary actions required for syncing. This also enables SSO, so you can login to the Platform via Rancher.

  1. Log in to the Platform UI as an admin user and navigate to the Admin section using the menu on the left.

  2. Edit the configuration by adding the Rancher object with the following properties:

    auth:
      rancher:
        host: your-rancher-instance
        bearerToken: "your-rancher-token"
        insecure: <true/false>
    Don't forget to change default values

    Replace your-rancher-instance with the address of your Rancher instance without protocol prefix, e.g. my-rancher.demo.dev

    Replace "your-rancher-token" with the bearerToken to be used. Its usually of the format Access Key: Secret Key e.g. "token-28kg6:gl5nqsq2hmxmdxr7fvcpfz2hh2krzvqff5w78kxr4tvc6r6x6s67t4"

    For further configuration options, see the configuration reference and the Rancher configuration options.

  3. Save the changes to the configuration by clicking and wait for the platform to restart.

Connect Rancher Projects to Platform Projects​

The Rancher integration can be enabled on a per-project basis. Subsequently, any virtual clusters within the project can be selectively imported into Rancher. Importing a virtual cluster means that it is available for use as a cluster within Rancher.

  1. In the Platform UI, click on the Projects Navigator in the top left side menu and then switch to the Project for which you wish to enable the integration. Click on the Projects Navigator again and click on .

  2. Click on Rancher and toggle the Enable Rancher Integration switch to enable synchronization for this project. Additional configuration options will appear.

  3. Add the Rancher Project ID and Rancher Cluster ID of the Rancher project you want to connect. Note that those are different from the project name and cluster name. To retrieve those, you can either extract them from the URL in the Rancher dashboard (go to your project page, the cluster id has a c-x-xxxx format and the project id has a p-xxxx format), or using the rancher CLI (select your cluster with rancher context switch and then rancher project list will the output the project as <cluster-id>:<project-id>).

  4. [Optional] Back in the Platform UI, toggle the Enable Member Synchronization switch if you wish to sync Rancher Project member roles into the Platform's Project member roles.

  5. Click to save the Project settings.

Finding your Rancher Project and Cluster IDs

To get the Rancher Cluster ID click on 'Cluster Management' in the left side menu in the Rancher UI, and then select the desired cluster, click on the ellipsis button on the right side and select View YAML. The metadata.name is the Cluster ID. To get the Rancher Project ID, in the 'Cluster Management' screen, click on the desired cluster and then Projects/Clusters on the top left side of the screen. Click the ellipsis button on the right side of the desired project name and select the View YAML option. The metadata.name is the Rancher Project ID.

Disabling Rancher Integration​

You may disable the Rancher integration at a per virtual cluster or per project level by toggling the same sliders used to enable it. Disabling the integration at the virtual cluster level simply removes it in Rancher. Disabling the integration at the project level removes all virtual clusters from Rancher, so be careful when disabling at this level!

Configuration Options​

The following configuration can be set on the projects.managementv1.loft.sh resource.

enabled required boolean false pro​

Enabled indicates if the Rancher Project Integration is enabled for this project.

projectRef required object pro​

ProjectRef defines references to rancher project, required for syncMembers and syncVirtualClusters.syncMembers

cluster required string pro​

Cluster defines the Rancher cluster ID Needs to be the same id within Loft

project required string pro​

Project defines the Rancher project ID

importVirtualClusters required object pro​

ImportVirtualClusters defines settings to import virtual clusters to Rancher on creation

roleMapping required object pro​

RoleMapping indicates an optional role mapping from a rancher project role to a rancher cluster role. Map to an empty role to exclude users and groups with that role from being synced.

syncMembers required object pro​

SyncMembers defines settings to sync Rancher project members to the loft project

enabled required boolean true pro​

Enabled indicates whether to sync rancher project members to the loft project.

roleMapping required object pro​

RoleMapping indicates an optional role mapping from a rancher role to a loft role. Map to an empty role to exclude users and groups with that role from being synced.