Skip to main content

vCluster Integration

vCluster provides control-plane-level isolation. vNode adds node-level isolation on top. Together they deliver full-stack tenant isolation. Each tenant gets a dedicated control plane and a hardened workload sandbox on shared nodes.

Two layers of isolation​

A shared Kubernetes cluster exposes two places where tenants can interfere with each other.

Control plane. Tenants that share an API server and etcd can read each other's secrets, modify each other's resources, and exhaust API capacity. vCluster eliminates this by giving each tenant a dedicated API server and etcd. Tenants interact with their own cluster and have no visibility into the host cluster or other tenants.

Worker nodes. Even with dedicated control planes, tenant pods still run on shared worker nodes. A container escape gives an attacker access to the host, where they can read other tenants' pod filesystems, processes, and secrets. vNode eliminates this by wrapping each tenant's pods in a hardened sandbox. A container escape reaches the vNode boundary, not the host.

The stack looks like this when both layers are active:

vCluster and vNode layer stackTenant vCluster control planes sit above a shared worker node where vNode sandboxes wrap each tenant's pods.Control-plane isolationAttack surface: Kubernetes API server and etcdWorker nodesAttack surface: container escape on a shared worker nodeTenant A vClusterAPI serveretcdTenant B vClusterAPI serveretcdShared worker nodevNode sandbox(Tenant A namespace)vNode sandbox(Tenant B namespace)PodPodPodPodTenant A workloads stop at the vNode boundaryTenant B workloads stop at the vNode boundaryvCluster schedules tenant pods

vCluster isolates each tenant's control plane, while vNode isolates the tenant's pods on shared worker nodes.

How they integrate​

vNode operates at the container runtime layer, below the Kubernetes API. It is registered as a Kubernetes RuntimeClass (vnode or vnode-launcher). Tenant clusters can reference this RuntimeClass in pod specs, or set it as the cluster-wide default in the vCluster configuration. When configured as the default, workload manifests do not need to change.

To reference the RuntimeClass explicitly on individual workloads, add runtimeClassName: vnode to the pod spec:

spec:
  runtimeClassName: vnode

vCluster schedules workloads as normal. The vNode runtime intercepts at the containerd layer, not at the Kubernetes API layer.

Deployment mode and vCluster topology​

vNode's default per-namespace isolation mode aligns naturally with a standard vCluster topology. Each tenant cluster's pods land in their own namespace on the host cluster. One vNode runs per namespace per node, which means one vNode per tenant cluster per node. Pods in the same tenant cluster can see each other's processes inside the vNode sandbox, as they would in a normal cluster.

If tenant clusters share namespaces on the host, or if workloads require stronger pod-level boundaries, switch to per-pod mode. Set VNODE_PER_POD=true on the vNode DaemonSet. Every pod then gets its own isolated sandbox, regardless of namespace.

Why both layers matter​

Neither layer alone provides full tenant isolation.

  • vCluster without vNode. Tenants have separate control planes but share node-level risk. A container escape reaches the host.
  • vNode without vCluster. Workloads are sandboxed at the node level, but tenants share a Kubernetes API. Tenant resources remain visible to each other.
  • vCluster with vNode. Both the control plane and node layers are isolated. Tenant workloads are isolated across the Kubernetes API, etcd, process, filesystem, and host-node boundaries.