Overview

When a vCluster Platform is deployed on a control plane cluster (or, primary control plane cluster), it can act as a centralized control plane. Other control plane clusters can connect to the vCluster Platform running on the primary control plane cluster and be managed by it. In this architecture:

• The primary control plane cluster runs the vCluster Platform.
• Other control plane clusters connect to the primary control plane cluster and run the vCluster Platform Agent.
• The Platform coordinates and manages all connected control plane clusters through their agents.
• There are both vCluster Platform and vCluster Platform agent running on the primary control plane cluster. The vCluster Platform manages the primary control plane cluster through its vCluster Platform Agent as well.

Agent settings are the content in the values.yaml under the agentValues. It controls the behavior of vCluster Platform Agents installed in the control plane clusters that are managed by the vCluster Platform.

The agentValues behavior is as follows:

• By default, agentValues is an empty object {}.
• An empty agentValues object means that agents installed on connected control plane clusters will inherit the same configuration as the platform running on the primary control plane cluster.
• You can populate agentValues to override the default agent configuration globally for all connected control plane clusters.

Connect to platform

A new cluster can be connected to the platform through the UI or CLI:

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.

Find agent pods

The platform agent runs as a pod in each connected cluster. Locate agent pods to verify connectivity and troubleshoot issues:

Modify the following with your specific values to generate a copyable command:

MANAGEMENT_NAMESPACE

List agent pods

kubectl get pods -n vcluster-platform -l app=loft

Example output:

NAME                   READY   STATUS    RESTARTS   AGE
loft-d6c6d5576-7kqwx   1/1     Running   0          9d

Retrieve agent values

For a platform instance on host nimbus.vcluster.cloud with a connected cluster named staging, the following table shows how to retrieve agent values for each tier. Use these endpoints to determine current agent configuration or to layer values instead of overriding them.

You can specify multiple values files:

--values=https://<platform-config-endpoint> --values=https://<cluster-annotation-endpoint>

An access key is required for authentication.

Host	Cluster Name	Source	Request	Response
nimbus.vcluster.cloud	staging	none	https://nimbus.vcluster.cloud/clusters/staging?token=access-key	Current agent values
nimbus.vcluster.cloud	staging	platform-config	https://nimbus.vcluster.cloud/clusters/staging?token=access-key&source=platform-config	Content of agentValues section in platform config
nimbus.vcluster.cloud	staging	cluster-annotation	https://nimbus.vcluster.cloud/clusters/staging?token=access-key&source=cluster-annotation	Value of the loft.sh/agent-values annotation on the Cluster Object