Skip to main content
Version: v0.38 Stable

Security and tenant isolation

Every cluster vCluster creates is a separate Kubernetes environment with its own control plane, API, and RBAC. How far that isolation extends below the API depends on where tenant workloads run. On private nodes, each cluster gets dedicated machines. On shared nodes, tenants share the kernel and physical nodes of the control plane cluster.

This page explains the layers of tenant isolation and how they combine into isolation profiles. To configure and harden a deployment, see Secure vCluster deployments.

Isolation layers​

Tenant isolation isn't a single switch. Each layer below protects against a different kind of access, and the layers you need depend on how much you trust your tenants.

Control plane and API​

Each cluster runs its own API server, controller manager, and data store. Tenants connect to their cluster's API server, never to the control plane cluster's API. A tenant with cluster-admin in their cluster controls that cluster only. By default, the API server doesn't expose resources belonging to other tenants or the control plane cluster. Operators can deliberately expose selected control plane cluster resources through sync.fromHost, so that configuration is part of the security boundary.

This layer applies to every deployment. See Architecture for how the control plane is built.

Sync boundary​

On shared nodes, vCluster syncs selected resources, such as Pods, Services, and PersistentVolumeClaims, into the cluster's namespace on the control plane cluster so they can run there. vCluster translates their names and namespaces on the way, and creates only the resource types that the sync configuration enables. Each enabled type lets a tenant create real objects on the control plane cluster, so the sync configuration is a security setting.

The platform operator owns this boundary through vcluster.yaml or a Platform template. Tenants can't loosen it from inside their cluster. See Configure resource sync for what syncs by default.

Nodes​

The worker node model sets the strongest boundary between tenants:

  • Private nodes run a single cluster's workloads. Each cluster gets its own nodes, CNI, and CSI, and no other tenant's workloads share the kernel. This is the model for external, resale, regulated, and GPU tenants.
  • Shared nodes run workloads from many clusters on the control plane cluster's own nodes. Tenants keep control plane, API, and namespace isolation, but share the kernel and physical nodes. Use them for trusted tenants such as development, testing, and internal teams.

See Architecture for how each model works, and Decide whether tenants share hardware to choose between them.

Runtime​

vNode wraps each pod in a lightweight sandbox that uses Linux user namespaces, filesystem virtualization, and seccomp filtering. It needs no hypervisor or guest kernel, so workloads run at native speed. Use it for workloads that need elevated access, such as privileged containers, Docker-in-Docker, or user-supplied inference code. vNode works on shared and private nodes. See the vNode docs for what the sandbox contains.

Network​

On shared nodes, pods from every cluster share the control plane cluster's pod network. NetworkPolicy restricts traffic between them and vCluster's own components. vCluster creates these policies when you enable network policies in the policies section of vcluster.yaml, and the control plane cluster's CNI enforces them.

On private nodes, each cluster has its own pod network, and tenants write their own NetworkPolicies. The default CNI, Flannel, doesn't enforce NetworkPolicy, so install a CNI that does if tenants rely on them. See Networking for details.

Workload guardrails​

Policies limit what tenant workloads can do and consume. A Pod Security Standard blocks privileged and host-level pod configurations on any node model. On shared nodes, a ResourceQuota and LimitRange in the cluster's namespace cap the CPU, memory, and storage its workloads take from the control plane cluster. With the Scale plan, central admission control adds operator-defined admission webhooks that tenants can't remove.

Management access​

When clusters are created through vCluster Platform, templates decide which vcluster.yaml settings a tenant gets. A user who can edit vcluster.yaml freely can loosen sync settings or expose control plane cluster resources. So non-admin users should create clusters only from approved templates. Platform RBAC separates the administrators who define templates from the project users who consume them.

Isolation profiles​

The layers combine into four profiles, from the strongest boundary to the lightest:

ProfileBoundary between tenantsFits
Private nodes on dedicated bare metalSeparate physical servers, provisioned by vMetalGPU and PCIe device exclusivity, compliance, and sovereign deployments
Private nodesSeparate nodes, CNI, and CSI per cluster, optionally with vNodeExternal, resale, regulated, and other untrusted tenants
Shared nodes with vNodeShared nodes, with a runtime sandbox around each podTrusted tenants whose workloads need elevated access
Shared nodesShared nodes, kernel, and node networkTrusted tenants such as development, testing, CI/CD, and internal teams

Every profile keeps the control plane and API isolation layers. Configure a Pod Security Standard as an additional workload guardrail for each profile. The deployment security overview covers the controls for each profile.

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.

Next steps​

  • Secure vCluster deployments for the baseline configuration, hardening steps, and production checklist.
  • Shared-node hardening for the threat model and required settings before running trusted tenants on shared nodes.
  • Private nodes to deploy dedicated nodes for each cluster.
  • Policies to configure Pod Security Standards, quotas, network policies, and admission control.