Skip to main content

Rancher Integration Guide

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

Prerequisites​

Before you begin, make sure you have the following:

  • A running vCluster.Pro Platform
  • A running Rancher Server
  • A Rancher API Bearer Token to allow the vCluster.Pro 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 vCluster.Pro 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 vCluster.Pro platform hostname without the protocal prefix, e.g. my-vcluster-platform.dev

Configure vCluster.Pro Platform​

Now we'll add the Rancher object to the vCluster.Pro Platform configuration in order to set up a global Rancher integration. This enables the vCluster.Pro 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 vCluster.Pro platform via Rancher.

  1. Log in to the vCluster.Pro 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 vCluster.Pro 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 vCluster.Pro 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 vCluster.Pro platform, 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.
  4. [Optional] Back in the vCluster.Pro platform UI, toggle the Enable Member Synchronization switch if you wish to sync Rancher Project member roles into the vCluster.Pro 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.

Using The Integration​

After configuring the Rancher integration, you can now create and delete virtual clusters from the Rancher UI. Additionally, you can also access the vCluster.Pro Platform directly from the Rancher UI.

Creating a virtual cluster​

  1. In the Rancher UI, click on .
  2. Enter a name for the virtual cluster and select the vCluster.Pro Project in which you wish to create the virtual cluster. Only projects which have the Rancher Integration enabled would be displayed in the list.
  3. Click which will redirect you to the vCluster.Pro Platform to complete the creation process. At this point, you can optionally select a template and click and then click on the Rancher configuration tab and slide the Add to Rancher toggle to enabled. Click to finish creating the virtual cluster.
  4. Navigate back to the Rancher UI and you should see the newly created virtual cluster available and in Activestate.

Deleting a virtual cluster​

  1. In the Rancher UI, click on the Delete icon for the virtual cluster you want to delete.
  2. You will be redirected to the platform's VirtualClusterInstance Page for confirmation.
  3. Click on the to confirm. The virtual cluster will be deleted from Rancher.

Importing virtual clusters into Rancher​

Once a project has Rancher integration enabled, virtual clusters within that project are eligible to be synced into Rancher. You can enable virtual cluster import into Rancher during the virtual cluster creation step, or by enabling this feature on existing virtual clusters.

  1. From the Projects Navigator in the left hand pane, switch to the desired Project and click on Virtual Clusters. Then click .
  2. In the popup, optionally select the virtual cluster template, then click the button.
  3. Click the Rancher configuration tab and slide the Add to Rancher toggle to enabled.
  4. Finish configuring anything else you'd like on your virtual cluster, then click.
Disabling Rancher Integration

You can disable the Rancher integration per virtual cluster or per project 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.

rancher required object ​

RancherIntegration holds information about Rancher Integration

enabled required boolean false ​

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

projectRef required object ​

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

cluster required string ​

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

project required string ​

Project defines the Rancher project ID

importVirtualClusters required object ​

ImportVirtualClusters defines settings to import virtual clusters to Rancher on creation

roleMapping required object ​

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 ​

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

enabled required boolean true ​

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

roleMapping required object ​

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.

Last updated on