Skip to main content

Configuring Rancher in vCluster

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 Rancher integration enables organizations to:

  • Unify management of virtual clusters and regular clusters within Rancher.
  • 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 Platform.

Prerequisites​

Before you begin, make sure you have the following:

  • A running vCluster Platform
  • A running Rancher Server
  • A valid API key to Rancher server in the bearer token format. This API key allows vCluster Platform to access and perform actions in Rancher.
Bearer Token

The API key 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 when using the Rancher integration.

Limitations​

Only one Rancher server should be tied to one vCluster Platform. You should not configure the Rancher server to multiple vCluster Platform instances as this will result in a broken integration.

Install the vCluster Platform extension in Rancher​

  1. In the Rancher UI, click on the Extensions in the left side menu. 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 Platform.

Add labels to the Rancher local cluster​

Add a label to the local cluster, which is the cluster where Rancher is installed. This label will indicate to Rancher where to reach out to make vCluster Platform calls.

  1. In the left side nav menu, click on the Cluster Management. Click the on the ellipsis button of the local cluster. Select the Edit Config option.

  2. Click on the Labels & Annotations row and click on .

  3. Add loft.sh/loft-hostname for the label's key and your Platform hostname without the protocal prefix, for example, my-vcluster-platform.dev.

Configure vCluster Platform​

Update the configuration for vCluster Platform to add the Rancher object in order to enable the integration between vCluster Platform and Rancher. Adding it to the configuration with the bearer token enables vCluster Platform to communicate with Rancher via its API and perform the necessary actions required for syncing. This integration also enables SSO, so you can login to vCluster Platform via Rancher.

  1. Log in to vCluster Platform as an admin user and navigate to the Admin section in the leftside menu.

  2. Edit the configuration by adding the Rancher object with the following properties:

    auth:
      rancher:
        host: <RANCHER_SERVER_HOSTNAME>
        bearerToken: "<RANCHER_BEARER_TOKEN>"
        insecure: <true/false>
    Update the options with your Rancher server

    Replace <RANCHER_SERVER_HOSTNAME> with the address of your Rancher instance without the protocol prefix, for example, my-rancher.demo.dev

    Replace "<RANCHER_BEARER_TOKEN>" with the API key that was created in Rancher. The bearer token is the format of the Access Key and Secret Key in one string, for example, "token-28kg6:gl5nqsq2hmxmdxr7fvcpfz2hh2krzvqff5w78kxr4tvc6r6x6s67t4".

  3. Save the changes to the configuration by clicking and wait for the platform to restart.