Version: main 🚧

Install the Rancher integration in vCluster

The vCluster Rancher integration uses an operator to connect tenant clusters to Rancher by creating a corresponding Rancher cluster resource for each tenant cluster. The operator runs on the Rancher local cluster and handles registration automatically. Rancher users don't need cluster management permissions to use this integration. The operator assigns Rancher cluster owner access to the tenant cluster creator, owners of the tenant cluster's project, and owners of the cluster where the tenant cluster is deployed. This setup allows tenant 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 before installing the vCluster Rancher Operator:

A Rancher instance installed in a cluster. Rancher refers to this cluster as the local cluster. Note that the Docker installation method is not supported for production use.
Admin permissions for the Rancher local cluster. You must be able to add Helm repositories and install charts there.
At least one connected downstream cluster where tenant clusters are deployed.

Network policies

If you are using network policies, Rancher Operator traffic into the virtual cluster control plane must be allowed.

vcluster.yaml
policies:
  networkPolicy:
    controlPlane:
      ingress:
        # Allow ingress traffic from the rancher-cluster-agent-install job pods.
        - from:
            - podSelector:
                matchExpressions:
                  - key: batch.kubernetes.io/job-name
                    operator: Exists
    workload:
      egress:
        # Allow workload egress traffic to the rancher server.
        # This example is allowing outgoing traffic to any address.
        # Depending on your use case, a more restrictive policy may be used.
        - to:
            - ipBlock:
                cidr: 0.0.0.0/0

Install the vCluster Rancher operator

In the Rancher UI, select the local cluster from the cluster overview.
In the sidebar, navigate to Apps → Repositories and click Create.
Set a repository name and use the following Index URL: https://charts.loft.sh
[Optional] If pre-release charts are needed, go to User Preferences, scroll to Charts, and enable Include Prerelease Versions.
In the sidebar, navigate to Apps → Charts and search for vCluster Rancher Operator.
Select the chart and follow the prompts to install it in the local cluster.
After installation, go to Workloads → Deployments and confirm the operator deployment 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 tenant cluster or change the vcluster.yaml, follow the same method used for installation. For example, if you used the Apps interface described above, update the application in the Rancher UI.

Additional operator configuration

Sync labels

Defining syncLabels in the operator's Helm values configures the syncing of labels from the vCluster's Service (which has the label app=vcluster) to the Rancher management cluster. For example:

syncLabels:
  excludeKeys:
    - no-sync/*
  includeKeys:
    - some-specific-label
    - labels-starting-with*

Fleet workspaces

The default fleet workspace is fleet-default, but you can override it by setting fleet.defaultWorkspace. For example:

fleet:
  defaultWorkspace: some-other-ws

You can also map projects to workspaces using the Kubernetes UID for the Rancher project:

fleet:
  projectUIDToWorkspaceMappings:
    a8732c55-e618-42dc-8f75-0964b0180a79: ws-1
    98abcc55-8341-c4dc-5531-902348b80321: ws-2

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 tenant clusters directly from the Rancher user interface. It provides a separate UI for managing tenant clusters and labels them 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

Open Rancher and go to Extensions in the left navigation. Click the ellipsis menu in the top-right corner and select Manage Repositories.
Click Create, enter a name for the repository, and set the Index URL to:
```
https://charts.loft.sh/
```
Click Create to save the repository.
Navigate to the Extensions page and click to the Available tab. Find vCluster Rancher Extension UI and click Install.
There are multiple entry points to create a tenant 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
Use the dropdown list to select the downstream cluster where the tenant 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/
```
Choose a vCluster chart version. Set the namespace and name for the new tenant cluster. Then click Create vCluster to deploy.
Navigate to vCluster List in the side menu. The new tenant cluster is displayed as a downstream cluster in Rancher.
Click the tenant 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.

Upgrade the vCluster Rancher extension UI

To upgrade the extension to a newer version, follow the Rancher extension update guide.

Remove virtual node resources

Since tenant clusters share physical nodes with the downstream cluster they run on, Rancher may count tenant cluster nodes toward your resource usage. To prevent this, use sync patches to zero out the CPU capacity reported by the tenant cluster's nodes.

Enterprise-Only Feature

This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

Add the following to your vcluster.yaml to zero out node CPU capacity:

vcluster.yaml
sync:
  fromHost:
    nodes:
      enabled: true
      patches:
        - path: status.capacity.cpu
          expression: '"0"'

To also hide CPU resources for the cluster in the Rancher cluster overview, patch allocatable CPU as well:

vcluster.yaml
sync:
  fromHost:
    nodes:
      enabled: true
      patches:
        - path: status.capacity.cpu
          expression: '"0"'
        - path: status.allocatable.cpu
          expression: '"0"'

note

This approach requires sync.fromHost.nodes.enabled: true and is not compatible with the virtual scheduler or hybrid scheduling, both of which rely on accurate node capacity information for scheduling decisions.

Uninstall the vCluster Rancher operator

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

In the Rancher UI, select the local cluster.
In the sidebar, navigate to Apps → Installed Apps.
Locate the vCluster Rancher Operator chart and delete it.

Prerequisites​

Network policies​

Install the vCluster Rancher operator​

Additional operator configuration​

Sync labels​

Fleet workspaces​

Use the vCluster Rancher extension UI​

Upgrade the vCluster Rancher extension UI​

Remove virtual node resources​

Uninstall the vCluster Rancher operator​