Version: main 🚧

Connect a Cluster

		Enterprise
Available in these plans	Free	Dev	Prod	Scale
Connected Clusters

vCluster Platform manages tenant clusters that run across one or more connected clusters. A connected cluster is a Kubernetes cluster that serves as a Control Plane Cluster, where tenant cluster control planes run. To enable management through vCluster Platform, the vCluster Platform agent must be installed on each cluster you intend to manage. The installation can be performed through the vCluster Platform UI, CLI, or Helm.

Control Plane Cluster access

Direct access to a Control Plane Cluster grants broad permissions to platform resources and tenant clusters running on it. Grant this access only to privileged platform administrators. Unprivileged users should access tenant clusters directly rather than through the Control Plane Cluster or its pods.

UI
CLI
Helm

Go to Infrastructure > Control Plane Clusters.
Click .
Give your cluster a name in Display Name. Optionally, give a name for the underlying kubernetes resource in the Cluster ID field, or leave it empty to autogenerate one. Then click .
Copy & execute the displayed vCluster CLI or Helm command.
Wait until vCluster Platform installs the agent in your connected cluster.
Once successful, use the displayed CLI command to create a space / virtual cluster in the newly connected cluster.
Click to go to the Control Plane 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.

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 control plane cluster where vCluster Platform itself is deployed is automatically connected to the platform during installation. Therefore, this command should be executed in a different cluster from the one where 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]
```

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]

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]"
```
After that, you need to provide a name for the cluster.
```
export CLUSTER_NAME="cluster-name"
```

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

Then, you need to set the Platform Host using the following code:
```
export PLATFORM_HOST="YOUR_PLATFORM_HOST"
```

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

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

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")

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.