Skip to main content
Version: v0.38 Stable

Private nodes quick start

You're building a platform where tenants need real hardware isolation. Think GPU workloads that can't share a node pool, regulated environments that require dedicated infrastructure, or AI cloud customers who expect hyperscaler-grade separation.

This guide shows you how to deploy a cluster backed by dedicated worker nodes. There's no cross-tenant scheduling, and each tenant gets a separate CNI and separate storage. At the end, you'll see exactly what is and isn't visible from the control plane cluster.

Private nodes require vCluster Platform. Free mode is supported, so no paid license is needed to get started.

Worker nodes connect to the control plane through vCluster VPN, which routes traffic through the Platform URL using WireGuard. Worker nodes only need outbound HTTPS access to Platform — no direct exposure of the control plane API is required.

Prerequisites​

You need a control plane cluster with vCluster Platform running on it.

You also need at least one Linux machine to join as a worker node.

  • Ubuntu 22.04 or 24.04 recommended
  • Root access on the worker node
  • Outbound HTTPS access to the Platform URL from the worker node

See the full node requirements.

Create the cluster​

Private nodes must be enabled at creation time

An existing cluster cannot be migrated from shared to private nodes. This configuration must be set when the cluster is first created.

  1. Make sure your kube context is pointed at the control plane cluster.

    kubectl config current-context
  2. Create a vcluster.yaml with private nodes and VPN enabled.

    vcluster.yaml
    privateNodes:
    enabled: true
    vpn:
    enabled: true

    networking:
    podCIDR: 10.64.0.0/16
    serviceCIDR: 10.128.0.0/16
    note

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

  3. Deploy the cluster with vcluster create.

    vcluster create my-vcluster --namespace team-x --values vcluster.yaml

    When deployment finishes, the CLI connects and switches your kube context into the cluster. The cluster has no worker nodes yet. Workloads cannot be scheduled until at least one node joins.

  4. Confirm the cluster is running with no nodes.

    kubectl get nodes

    Expected output:

    No resources found.

    This is expected. Private nodes join explicitly. The control plane is running. Compute comes next.

Join a worker node​

Modify the following with your specific values to replace on the whole page and generate copyable commands:
  1. Generate a join token with vcluster token create. Run this from your local machine with the kube context still inside the cluster.

    vcluster token create --expires=1h

    The output is a curl command to run on the worker node:

    curl -sfLk https://my-platform.example.com/node/join?token=<token> | sh -
  2. SSH into the worker node and run the join command as root.

    sudo su -
    curl -sfLk https://my-platform.example.com/node/join?token=<token> | sh -

    The script installs Kubernetes node components (containerd, kubelet) and the vcluster-vpn service, which establishes a WireGuard tunnel to the control plane through Platform. Output ends with:

    This node has joined the cluster:
    * Certificate signing request was sent to apiserver and a response was received.
    * The kubelet was informed of the new secure connection details.
  3. Back on your workstation, verify the node joined.

    kubectl get nodes

    Output is similar to:

    NAME STATUS ROLES AGE VERSION
    worker-node-1 Ready <none> 30s v1.36.6

Deploy a workload​

With a worker node ready, schedule a workload to confirm the cluster is fully operational.

kubectl create deployment hello --image=nginx
kubectl get pods --watch

The pod schedules onto worker-node-1. No other tenant can see this node or the workloads running on it.

The isolation boundary​

From the control plane cluster, the worker node that joined the cluster is not visible as a Kubernetes node:

vcluster disconnect
kubectl get nodes

The worker node does not appear here. It exists only within the cluster's namespace. No other cluster can schedule onto it. No operator on the control plane cluster can inspect its workloads through the Kubernetes API.

This is what makes private nodes the right model for GPU workloads. Each tenant gets hardware-level isolation without needing a separate physical cluster.

Clean up​

Reset the worker node before you delete the cluster. Platform stops serving the join script once the cluster is gone.

Connect to the cluster and generate a new join token:

vcluster connect my-vcluster --namespace team-x
vcluster token create --expires=10m

On the worker node, run the returned command as root with --reset-only, then stop the vcluster-vpn service. The --reset-only flag removes the node components but leaves vcluster-vpn running with this cluster's VPN state, which makes the next join to a new cluster hang.

sudo su -
curl -sfLk https://my-platform.example.com/node/join?token=<token> | sh -s -- --reset-only
systemctl disable --now vcluster-vpn
rm -f /etc/vcluster-vpn/config.json

Confirm the service stopped:

systemctl is-active vcluster-vpn

The output is inactive.

Delete the cluster:

vcluster disconnect
vcluster delete my-vcluster --namespace team-x

Next steps​

  • Auto Nodes automate worker node provisioning through Platform instead of joining manually.
  • Node-to-node VPN encrypts traffic between worker nodes, which helps in multi-cloud and cross-datacenter deployments.
  • Node requirements lists supported OS versions and system dependencies.
  • High availability adds control plane nodes for production.
  • The AI cloud provider guide covers the end-to-end architecture for GPU clouds.
Ready for production?

Work through Plan your cluster, ending with the production readiness checklist. If you're building a service for others, see what you can build. It covers every offering, from bare metal to managed Kubernetes and AI platforms.