Skip to main content
Version: v0.29 Stable

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
  • Core DNS - 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​

Install Control Plane Node​

Control Plane Node

All steps are perfomed on the control plane node.

  1. 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.0"

    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.

FlagDescription
--vcluster-nameName of the vCluster instance
--vcluster-versionSpecific vCluster version to install
--configPath to the vcluster.yaml configuration file
--skip-downloadSkip downloading vCluster binary (use existing)
--skip-waitExit without waiting for vCluster to be ready
--extra-envAdditional environment variables for vCluster
--platform-access-keyAccess key for vCluster Platform integration
--platform-hostvCluster Platform host URL
--platform-insecureSkip TLS verification for Platform connection
--platform-instance-nameInstance name in vCluster Platform
--platform-projectProject name in vCluster Platform

Accessing 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 in order 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.