Create control plane

Limited vCluster Tenancy Configuration Support

This feature is only available for the following:

Running the control plane as a binary for vCluster Standalone, which uses private nodes.

Overview

When deploying vCluster Standalone, the assets required to install the control plane are located in the GitHub releases of vCluster.

Predeployment configuration options

Before deploying, it's recommended to review the set of configuration options that cannot be updated post deployment. These options require deploying a new vCluster instead of upgrading your vCluster with new options.

Control-plane options

• High availability - Run multiple control plane nodes
• CoreDNS - Currently only CoreDNS deployed by vCluster during startup is supported.
• Backing Store - Decide how the data of your cluster is stored, must be one of either embedded SQLite (the default) or embedded etcd.

Node Roles

Decide if the control plane node will also be a worker node or not. Once a node joins the cluster, the roles of the node cannot change.

Worker Nodes

With vCluster Standalone, worker node pools can only be private nodes. Since there is no host cluster, there is no concept of host nodes.

Prerequisites

• Access to a node that satisfies the node requirements

Install control plane node

Control Plane Node

All steps are performed on the control plane node.

1. Create directory for storing vCluster Standalone configuration.

   Create /etc/vcluster directory

   mkdir -p /etc/vcluster

   Save a basic vcluster.yaml configuration file for vCluster Standalone on the control plane node.

   Create a vcluster.yaml for vCluster Standalone with only one control plane node

   cat <<EOF > /etc/vcluster/vcluster.yaml
   controlPlane:
     standalone:
       enabled: true
       joinNode:
         enabled: true  # Optional: Control Plane node will also be considered a worker node
   privateNodes: # Required for adding additional worker nodes
     enabled: true
   EOF

   warning

   Adding additional control plane nodes will not be supported unless you follow the high availability steps for configuration.

2. Run the installation script on the control plane node:

   Install vCluster Standalone on control plane node

   export VCLUSTER_VERSION="v0.29.1"
   
   sudo su -
   curl -sfL https://github.com/loft-sh/vcluster/releases/download/${VCLUSTER_VERSION}/install-standalone.sh | sh -s -- --vcluster-name standalone

3. Check that the control plane node is ready.

   After installation, the kubeconfig is automatically configured on the control plane node. The kubectl context is set to interact with your new vCluster Standalone instance.

   Run these commands on the control plane node:

   Check node status

   kubectl get nodes

   Expected output:

   NAME               STATUS   ROLES                  AGE   VERSION
   ip-192-168-3-131   Ready    control-plane,master   11m   v1.32.1

   Verify cluster components are running

   kubectl get pods -A

   Pods should include:

   • Flannel: CNI for container networking
   • CoreDNS: DNS service for the cluster
   • KubeProxy: Network traffic routing and load balancing
   • Konnectivity: Secure control plane to worker node communication
   • Local Path Provisioner: Dynamic storage provisioning

Available flags to use in the install script

There are several flags available that can be added to the script.

Flag	Description
--vcluster-name	Name of the vCluster instance
--vcluster-version	Specific vCluster version to install
--config	Path to the vcluster.yaml configuration file
--skip-download	Skip downloading vCluster binary (use existing)
--skip-wait	Exit without waiting for vCluster to be ready
--extra-env	Additional environment variables for vCluster
--platform-access-key	Access key for vCluster Platform integration
--platform-host	vCluster Platform host URL
--platform-insecure	Skip TLS verification for Platform connection
--platform-instance-name	Instance name in vCluster Platform
--platform-project	Project name in vCluster Platform

Access your cluster

After installation, the kubeconfig is automatically configured on the control plane node. The kubectl context is set to interact with your new vCluster Standalone instance. If you decide to use vCluster Standalone as a host cluster for virtual clusters, then you can set your current kube context to the vCluster Standalone and create and interact with virtual clusters using vCluster CLI.

To access the cluster from other machines, copy the kubeconfig from /var/lib/vcluster/kubeconfig.yaml on the control plane node, then replace the server field with relevant IP or DNS to access the cluster. You can also configure vCluster to make external access easier.

The vCluster CLI is installed at /var/lib/vcluster/bin/vcluster-cli.