Skip to main content
Version: main 🚧

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)
  • Port 8443 on the machine must be open to your workstation for API access
  • Install kubectl on your local workstation

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.37.3/install-standalone.sh \
      | sh -s -- --vcluster-name standalone
    note

    vCluster deploys Kubernetes v1.36.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.36.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 clusters.

Access the cluster from your workstation​

The kubeconfig file is stored at /var/lib/vcluster/kubeconfig.yaml on the control plane node. Copy the file to your workstation and update the cluster endpoint.

  1. On the control plane node, display the kubeconfig.

    cat /var/lib/vcluster/kubeconfig.yaml

  2. Save the output to a separate file on your workstation, such as ~/.kube/standalone.yaml, to avoid overwriting your existing configuration.

  3. Set the KUBECONFIG environment variable to use the new file in this session.

    export KUBECONFIG=~/.kube/standalone.yaml

  4. In the kubeconfig, update the server field, which defaults to https://localhost:8443. Replace <YOUR_MACHINE_IP> with the public IP address or DNS name of the control plane machine.

    server: https://<YOUR_MACHINE_IP>:8443

    The API server certificate covers the machine's primary IP address and hostname. If you connect through an address that isn't assigned to the machine, such as a NAT public IP or a DNS name, add it to the certificate. Otherwise kubectl fails with a TLS error. On the control plane node, add the address to controlPlane.proxy.extraSANs in /etc/vcluster/vcluster.yaml, creating the file if it doesn't exist.

    /etc/vcluster/vcluster.yaml
    controlPlane:
      proxy:
        extraSANs:
          - <YOUR_MACHINE_IP>

    Then restart vCluster to regenerate the certificate.

    systemctl restart vcluster

  5. 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 run clusters and vCluster Platform

Next steps​

Ready for production?

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