Skip to main content

Standalone Quick Start

The first problem is always the same. To run vCluster, you need a Kubernetes cluster. But getting a Kubernetes cluster onto bare metal normally requires another tool first. vCluster Standalone breaks this loop. It installs a complete Kubernetes control plane directly on a Linux machine as a binary, with no existing distribution required.

This guide takes you from a bare Linux machine to a fully functional Kubernetes cluster that you can go on to use as a Control Plane Cluster in about two minutes. No Helm, no CLI, no existing Kubernetes required.

Prerequisites​

  • A Linux machine (bare metal or VM) meeting the node requirements
    • Ubuntu 22.04 or 24.04 recommended
    • Root access required
    • Outbound internet access for image pulls
  • The machine must be reachable from your local workstation (SSH access)

Install vCluster Standalone​

Run these commands on the control plane machine as root.

  1. Switch to root.

    sudo su -

  2. Run the installer.

    Modify the following with your specific values to generate a copyable command:
    curl -sfL https://github.com/loft-sh/vcluster/releases/download/v0.34.0/install-standalone.sh \
      | sh -s -- --vcluster-name standalone
    note

    vCluster deploys Kubernetes v1.35.0 by default. To use a different version, set controlPlane.distro.k8s.image.tag in your vcluster.yaml.

    The installer downloads Kubernetes binaries, configures the control plane, and writes a kubeconfig to /var/lib/vcluster/kubeconfig.yaml. Installation takes about 2 minutes.

  3. Verify the control plane node is ready.

    kubectl get nodes

    Output is similar to:

    NAME                  STATUS   ROLES                  AGE   VERSION
    vcluster-standalone   Ready    control-plane,master   88s   v1.35.0

Your machine is now a single-node Kubernetes cluster. This is the Control Plane Cluster. Worker nodes join separately as private nodes when you provision tenant clusters.

Access the cluster from your workstation​

The kubeconfig is written to /var/lib/vcluster/kubeconfig.yaml on the control plane node. Copy it to your local machine and update the server address.

# On the control plane node — print the kubeconfig
cat /var/lib/vcluster/kubeconfig.yaml

Copy the output to ~/.kube/config on your workstation. Replace the server: value with the machine's public IP or DNS name:

server: https://<YOUR_MACHINE_IP>:6443

Verify access from your workstation:

kubectl get nodes

What you have now​

  • A bare-metal or VM-based Kubernetes cluster running as a vCluster Standalone instance
  • A Control Plane Cluster ready to host tenant clusters and vCluster Platform

Next steps​

Ready for production?

See Build for Production to find the path that matches what you're building.