Skip to main content
Version: main 🚧

Worker nodes

Worker nodes run a cluster's workloads, separately from its control plane. vCluster gets them in one of two ways, and you choose before you create the cluster.

ModelWhere the nodes come fromIsolationLicense
Private nodesMachines that join one cluster and nothing elseNodes, kernel, CNI, and CSI dedicated to the clusterFree tier or higher for a pod-based control plane. Standalone and vind include them.
Shared nodesThe control plane cluster's own nodes, shared by the clusters that run thereControl plane, API, and namespace isolation. Tenants share the kernel.No license needed. The default for a pod-based control plane.

For a customer-facing offering, the model is a security boundary decision. See Decide whether tenants share hardware to decide.

Private nodes​

Private nodes join a single cluster. Each cluster runs its own CNI and CSI on them, and no other tenant's workloads share their kernel. Use them for external or regulated tenants, GPU workloads, and anything that needs dedicated infrastructure.

Nodes join in one of two ways:

  • Join nodes yourself. Provision machines with your own tooling and join each one with a token. See Join manually provisioned nodes.
  • Let Auto Nodes provision them. A vCluster Platform node provider provisions nodes based on the cluster's resource needs. See Auto Nodes.

vCluster Standalone and vind always use private nodes, because there's no control plane cluster whose nodes they could share. Both include private nodes without a license.

For a control plane that runs as pods, private nodes need the Free tier or higher. Auto Nodes with the KubeVirt, Terraform, and Cluster API node providers is also available from the Free tier. The Metal3 and NICo providers need the Scale tier.

To set up private nodes, see Private nodes.

Shared nodes​

Shared nodes are the default when the control plane runs as pods on a Kubernetes cluster, and they need no license. A cluster's workloads run on the control plane cluster's nodes, alongside other clusters, optionally pinned to a labeled subset of those nodes. Use them for trusted tenants such as development, testing, CI/CD, and internal teams.

Shared nodes are for trusted tenants

Shared nodes are a supported, common model for trusted tenants. They give each tenant control-plane, API, and namespace isolation, but tenant workloads share the same kernel and physical nodes. They aren't a security boundary for untrusted tenants with Kubernetes access or arbitrary workload execution. Good fits are development, testing, CI/CD, and internal engineering teams.

Use private nodes for external, resale, regulated, or otherwise untrusted tenant offerings, optionally with vNode for runtime isolation.

NetworkPolicy is an added isolation layer worth enabling even for trusted tenants. vCluster can create the policies for you through policies.networkPolicy, and your control plane cluster's CNI enforces them. Confirm your CNI supports enforcement, since some accept NetworkPolicy resources without acting on them. See the security baseline.

If you accept shared nodes for a trusted-tenant use case, follow the shared-node hardening guide as the required next step.

To set up shared nodes, see Nodes from the control plane cluster.

Set the model​

privateNodes.enabled in vcluster.yaml selects the model. Set it to true for private nodes, or leave it unset for shared nodes. Choose before you create the cluster, because the worker node model is part of the cluster's design, not a setting you tune later.