Connect a Cluster

The vCluster Platform supports managing multiple virtual clusters that run across different host clusters. A host cluster refers to the Kubernetes cluster where a virtual cluster is deployed. To enable management through the vCluster Platform, the vCluster Platform Agent must be installed on each host cluster you intend to manage. The installation can be performed through the vCluster Platform UI, CLI, or Helm.

UI

1. Go to the Clusters view using the menu on the left.

2. Click on the button on the right.

3. In the drawer that appears from the right, give your cluster a name in the Display Name field. Optionally give a name for the underlying kubernetes resource in the Kubernetes Name (ID), or leave it empty to have it autogenerated for you. Then click on the button.

4. In the section "Cluster Connection", please copy & execute the displayed vCluster CLI or Helm command

5. Please wait until vCluster Platform installs the agent in your connected cluster.

6. Once successful, you may create a space / virtual cluster in the newly connected cluster by using the displayed vCluster CLI command.

7. Click on the button to go to the Clusters view.

Connect a cluster

UI will generate a CLI command that can be used to connect the cluster. Make sure to check the CLI tab for working with the command.

CLI

1. When connecting a cluster from the vCluster CLI, you will need to provide a name for the cluster. This name will be used for the Cluster resource that gets created in Kubernetes. Optionally, you can use the display-name flag to specify a name for this cluster, when it gets displayed under the Clusters view in vCluster Platform.

   vcluster platform add cluster cluster-name --display-name [display-name]

   The above command automatically installs the vCluster Platform Agent in the cluster that corresponds to your current Kubernetes context. The host cluster where the vCluster Platform itself is deployed is automatically connected to the platform during installation. Therefore, this command should be executed in a different host cluster from the one where the vCluster Platform is running.

   By default, the vcluster-platform namespace is created automatically if it does not already exist on the cluster. The vCluster Platform Agent resources are deployed into this namespace. You can override this behavior by explicitly specifying a different namespace using the --namespace flag. If you want to connect a cluster that is not associated with your current Kubernetes context, use the --context flag to specify the context of the target cluster.

   info

   For more information about available CLI flags, refer to the CLI documentation.

   vcluster platform add cluster cluster-name --display-name [display-name] --context [context]

2. You can verify that the cluster is connected to the platform by running:

   vcluster platform list clusters

   and the expected output is:

           CLUSTER      |  AGE
   --------------------+--------
       cluster-name     | 7s
       host-cluster     | 10m4s   

   The host-cluster is the cluster name where the vCluster Platform is deployed.

platform login

Connect to the Platform: to use any vcluster platform command, you need to be connected to the platform. See authentication documentation for more details.

When you started the platform, you would have automatically connected to the platform when you ran vcluster platform start.

If you aren't sure if you are connected and already have a running platform, then you can login. Before running this command, be sure that your kubecontext is set to the cluster running the platform.

Login to the platform.

vcluster platform login

If your kubectl context is not set to the cluster with running platform, it's possible to login to the platform using the CLI and access key. If you haven't already, you need to create access key to be able to login to the platform.

Login to the platform using access key

vcluster platform login [platform-url] --access-key [access-key]

Helm

1. If you prefer to use Helm, you need to make sure that you have a valid Access Key.

   You can either reuse the CLI Access Key or create a new one by following the Access Key guide.

   • Reusing the CLI Access Key

     export ACCESS_KEY=$(vcluster platform access-key | jq -r .status.token)

   • Create new Access Key by following the Access Key guide.

     export ACCESS_KEY="[Newly Created Access Key]"

2. After that, you need to provide a name for the cluster.

   export CLUSTER_NAME="cluster-name"

3. Next, you must create the Cluster custom resource within the platform using the following code:

   cat <<EOF | kubectl apply -f -
   apiVersion: management.loft.sh/v1
   kind: Cluster
   metadata:
     name: $CLUSTER_NAME
   spec:
     displayName: $CLUSTER_NAME
     networkPeer: true
     managementNamespace: vcluster-platform
   EOF

4. Then, you need to set the Platform Host using the following code:

   export PLATFORM_HOST="YOUR_PLATFORM_HOST"

5. To get the Platform version, you should run the following command:

   export PLATFORM_VERSION=$(curl -s "https://$PLATFORM_HOST/version" | jq -r '.version | .[0:]')

6. To get the Cluster Connect token, you should run the following command:

   export CLUSTER_ACCESS_KEY=$(curl -s "https://$PLATFORM_HOST/kubernetes/management/apis/management.loft.sh/v1/clusters/$CLUSTER_NAME/accesskey" -H "Authorization: bearer $ACCESS_KEY")

7. Finally, you can connect the cluster using the following command:

   helm upgrade loft vcluster-platform --install \
     --repo https://charts.loft.sh/ \
     --version $PLATFORM_VERSION \
     --namespace vcluster-platform \
     --create-namespace \
     --set agentOnly=true \
     --set url=https://$PLATFORM_HOST \
     --set token=$(echo $CLUSTER_ACCESS_KEY | jq -r .accessKey) \
     --set additionalCA=$(echo $CLUSTER_ACCESS_KEY | jq -r .caCert) \
     --set insecure=$(echo $CLUSTER_ACCESS_KEY | jq -r .insecure)

   This command automatically installs the vCluster Platform Agent in the cluster that is your current context. However, if you want to connect a cluster that is not your current context, you can append the --kube-context flag to specify the context of the cluster you want to connect.

   You can also retrieve pre-configured agent values from your platform by appending the --values flag with the platform endpoint --values "https://$HOST/clusters/agent-values/$CLUSTER_NAME?token=$TOKEN".

   • $HOST — your vCluster Platform domain
   • $CLUSTER_NAME — the name you're assigning to the cluster being connected (e.g., cluster-name)
   • $TOKEN — the authentication token to access your vCluster Platform The endpoint returns an intelligently merged content of
   • Platform-level defaults configured in the agentValues field of your vCluster Platform Helm values
   • Cluster-specific overrides from the loft.sh/agent-values annotation (when present)

When connecting a new cluster, the user creates a new cluster resource and obtains a pre-shared key (PSK) that the user then uses to bootstrap the agent. The agent then utilizes this key to reach the control plane, authenticate itself, and establish a secure WireGuard-based, user-space tunnel.

If the agent cannot establish a direct WireGuard-based connection, the agents falls back to utilising the control plane as a Designated Encrypted Relay for Packets. The control plane relay is comparable to the same role as TURN servers in the ICE standard, using HTTPS streams (or WebSockets) and WireGuards keys instead.

info

If you encounter issues while configuring agent values or deploying it manually, you might want to take a look at the Cluster troubleshooting guide.