Skip to main content
Version: main 🚧

Install the Rancher integration

The vCluster Rancher integration uses an operator to connect virtual clusters to Rancher by creating a corresponding Rancher cluster resource for each virtual cluster. The operator runs in the local cluster and handles registration automatically. Rancher users do not need cluster management permissions to use this integration. The operator assigns Rancher cluster owner access to the virtual cluster creator, owners of the virtual cluster's project, and owners of the virtual cluster's host cluster. This setup allows virtual clusters to appear and behave like managed clusters in Rancher.

This guide explains how to install the vCluster Rancher Operator.

Prerequisites​

Ensure you have the following prerequisites before installing the vCluster Rancher Operator:

  • Admin permissions for the local cluster. You must be able to add Helm repositories and install charts in the local cluster.
  • A running Rancher local cluster selected for installation
  • vCluster installed and at least one connected downstream cluster where virtual cluster are to be deployed.

Install the vCluster Rancher Operator​

  1. In the Rancher UI, select the local cluster from the cluster overview.

  2. In the sidebar, navigate to Apps → Repositories and click Create.

  3. Set a repository name and use the following Index URL: https://charts.loft.sh

  4. [Optional] If pre-release charts are needed, go to User Preferences, scroll to Charts, and enable Include Prerelease Versions.

  5. In the sidebar, navigate to Apps → Charts and search for vCluster Rancher Operator.

  6. Select the chart and follow the prompts to install it in the local cluster.

  7. After installation, go to Workloads → Deployments and confirm that the deployment vcluster-rancher-operator is active.

After it is installed, the operator automatically registers any vCluster in Rancher. It creates a corresponding Rancher cluster, sets up the connection, and grants cluster owner permissions to relevant users.

To update the virtual cluster, or make changes to the vcluster.yaml, follow the same method that was used for installation. For example if you used the Apps interface as described above, you can simply update the application within the Rancher UI.

Use the vCluster Rancher Extension UI​

Optionally, you can install the vCluster Rancher Extension UI to enable a more tailored user experience in Rancher. The vCluster Rancher Extension UI allows you to deploy virtual clusters directly from the Rancher user interface. It provides a separate UI for managing virtual clusters and a user experience more tailored to virtual clusters. The extension also labels virtual clusters in the Rancher Cluster Dashboard so you can distinguish them from physical clusters.

Requirements

Ensure your environment meets the following version requirements:

  • Rancher version ≥ 2.10
  • Rancher UI Extensions version ≥ 3.0 and < 4.0
  • Node.js version ≥ 20

  1. Open Rancher and go to Extensions in the left navigation. Click the ellipsis menu (...) in the top-right corner and select Manage Repositories.

  2. Click Create, enter a name for the repository, and set the Index URL to:

    https://charts.loft.sh/

    Click Create to save the repository.

  3. Navigate to the Extensions page and click to the Available tab. Find vCluster Rancher Extension UI and click Install.

  4. There are multiple entry points to create a virtual cluster:

    • From the Rancher home page: click Create vCluster
    • From the Cluster Management view: click Create Cluster
    • From the vCluster List (left menu): click Create vCluster

  5. Use the dropdown list to select the host cluster where the virtual cluster is deployed.

    If the Loft repository is not available in the target cluster, Rancher prompts you to add it:

    • Select Automatic to let Rancher configure it.
    • Or select Manual, click Create, and enter:
    Index URL: https://charts.loft.sh/

  6. Choose a vCluster chart version. Set the namespace and name for the new virtual cluster. Then Click Create vCluster to deploy.

  7. Navigate to vCluster List in the side menu. The new virtual cluster is displayed as a downstream cluster in Rancher.

  8. Click the virtual cluster in the list to access it in the Cluster Explorer. From here, you can manage workloads, namespaces, and configuration as you would with any other cluster.

Uninstall the vCluster Rancher Operator​

To remove the Rancher integration, uninstall the vCluster Rancher Operator from the local cluster. Deleting the operator stops new virtual cluster from appearing in Rancher, but does not remove any existing virtual clusters.

  1. In the Rancher UI, select the local cluster.

  2. In the sidebar, navigate to Apps → Installed Apps.

  3. Locate the vCluster Rancher Operator chart and delete it.