Overview

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

• The primary host cluster runs the vCluster Platform.
• Other host clusters connect to the primary host cluster and run the vCluster Platform Agent.
• The Platform coordinates and manages all connected host clusters through their agents.
• There are both vCluster Platform and vCluster Platform agent running on the primary host cluster. The vCluster Platform manages the primary host 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 host clusters that are managed by the vCluster Platform.

The agentValues behavior is as follows:

• By default, agentValues is an empty object {}.
• An empty agentValues list means that agents installed on connected host clusters will inherit the same configuration as the platform running on the primary host cluster.
• You can populate agentValues to override the default agent configuration globally for all connected host 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

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 will automatically install the vCluster Platform Agent in the cluster that is one's current context. If you want to connect a cluster that is not your current context, you can use the --context flag to specify the context of the cluster you want to connect.

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

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

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

warning

vCluster Platform exclusively supports the default secret backend for storing Helm releases. Alternative HELM_DRIVER configurations (such as configmap or sql) are not supported.

This command automatically installs the 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.

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