Skip to main content

Using the Rancher Integration

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 one vCluster Platform project. You should not configure the Rancher project to multiple vCluster Platform projects as the integration will not work if you do so.

Using 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 on Rancher and toggle the Enable Rancher Integration switch to enable synchronization for this project. Additional configuration options will 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 on 'Cluster Management' in the left side menu, 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 Rancher UI, click on '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 on 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.

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.

Managing Virtual Clusters in Rancher UI​

Creating a virtual cluster in the Rancher UI​

  1. In the Rancher home page, click on 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 will take 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 on 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.

Deleting a virtual cluster in the Rancher UI​

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

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

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

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

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

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 the virtual cluster from the Rancher UI, but the virtual cluster is still running.

Disabling the integration at the project level removes all virtual clusters from Rancher, so be careful when disabling at this level.