Skip to main content
Version: main 🚧

Use the Rancher integration

Outdated content

This guide describes a legacy integration method for Rancher and is outdated. For current install instructions and supported workflows, see the Install Rancher documentation in the vCluster section.

Once Rancher is configured on vCluster Platform, virtual clusters can be imported into Rancher and started using as a cluster in Rancher. In order to enable this integration on each virtual cluster, the vCluster Platform project must be enabled with the Rancher integration first.

Enable Rancher integration on a vCluster platform project​

Limitations​

Only one Rancher project can be connected to a single vCluster Platform project. You should not configure a Rancher project to connect to multiple vCluster Platform projects, as the integration does not work in that case.

Use the UI​

Before being able to enable virtual clusters with the Rancher integration, it must be enabled on the project. When vCluster Platform projects are enabled with Rancher integration, a label loft.sh/loft-project-name: <VCLUSTER_PLATFORM_PROJECT_NAME> is added to the Rancher project resource.

  1. In the settings of a project, click Rancher and toggle the Enable Rancher Integration switch to enable synchronization for this project. Additional configuration options appear.

  2. Input the Rancher Project ID and Rancher Cluster ID of the Rancher project you want to connect. Note that these are the IDs and are different from the project name and cluster name. The cluster ID has a c-x-xxxx format and the project ID has a p-xxxx format.

  3. [Optional] Toggle the Enable Member Synchronization switch if you wish to sync the Rancher project member roles into vCluster Platform's project member roles.

  4. Click to save the vCluster Platform project settings.

Finding your Rancher Project and Cluster IDs

To find the Rancher Cluster ID, in the Rancher UI, click 'Cluster Management' in the left side menu, and then select the desired cluster, click 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 Rancher UI, click 'Cluster Management' in the left side menu, click on the cluster that has the project you want to connect to. In the cluster explorer, click Projects/Namespaces in the cluster navigation. 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.

Configure on the project resource​

If you are creating a project resource into vCluster Platform directly, you can configure the Rancher integration directly on the projects.managementv1.loft.sh resource.

enabled required boolean 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 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.

Manage virtual clusters in Rancher UI​

Create a virtual cluster in the Rancher UI​

  1. In the Rancher home page, click the button.

  2. Enter a name for the virtual cluster and select the Rancher project in which you wish to create the virtual cluster. Only those projects which have the Rancher Integration enabled are displayed in the list.

  3. Click the button which takes you to the Create VirtualClusterInstance page in the vCluster Platform to get ready to create a virtual cluster.

  4. Click the Rancher configuration tab.

  5. Slide the Add to Rancher toggle to enable.

  6. Click the button once you have configured the rest of the virtual cluster as per your preference.

  7. Navigate back to the Rancher UI and the virtual cluster should be available and in Active state.

Delete a virtual cluster in the Rancher UI​

  1. In the Rancher home page, click the Delete icon for the virtual cluster you want to delete.

  2. You are re-directed to the VirtualClusterInstance Page in the vCluster Platform UI for confirmation.

  3. Click the to confirm in the vCluster Platform UI. The virtual cluster is deleted from Rancher.

Import virtual clusters into Rancher through vCluster platform UI​

Once a vCluster Platform project has the Rancher integration enabled, virtual clusters within that project are eligible to be synced into Rancher as an imported cluster in Rancher UI. In the vCluster Platform UI, you can enable virtual cluster import into Rancher during the virtual cluster creation step, or by enabling this feature on existing virtual clusters.

Make Sure Your Project Has Rancher Enabled

If the project does not have Rancher integration enabled, you do not see the "Add to Rancher" options in the virtual cluster configuration.

  1. In the vCluster Platform UI, select a project that has Rancher integration enabled.

  2. Click on Virtual Clusters and the button.

  3. In the popup, optionally select the virtual cluster template, then click the button.

  4. Click the Rancher configuration tab.

  5. Slide the Add to Rancher slider to enabled.

  6. Finish configuring anything else you'd like on your virtual cluster, then click the button. The virtual cluster is created in vCluster Platform and imported into Rancher.

Hide nodes in rancher​

Since virtual clusters are not using physical nodes, you can hide the nodes from Rancher in order for the virtual nodes to not be counted in your Rancher node count. In order to hide the nodes of your virtual cluster, you need to enable the Rancher nodeless plugin on the virtual cluster.

Add the plugin to your vcluster.yaml configuration.

plugins:
  rancher:
    image: ghcr.io/loft-sh/rancher-nodeless-plugin:0.0.5
Use Templates for plugins

You can enforce that all virtual clusters enable the plugin by enforcing template usage in the project.

Turn off rancher integration​

You may turn off the Rancher integration at a per virtual cluster or per project level by toggling the same sliders used to enable it. Turning off the integration at the virtual cluster level simply removes the virtual cluster from the Rancher UI, but the virtual cluster is still running.

Turning off the integration at the project level removes all virtual clusters from Rancher, so be careful when turning off at this level.