Kubernetes Multi-Tenancy Architecture 2026: Namespaces, vCluster, and Hard Isolation
Every platform team eventually hits the same wall. Ten teams want to ship onto one cluster, the budget will not stretch to ten clusters, so you hand out namespaces and RBAC and call it tenancy. Six months later a tenant installs a CRD that collides with someone else’s operator, a runaway Job starves the scheduler, and a security review asks whether tenant A can read tenant B’s secrets. A sound Kubernetes multi-tenancy architecture starts from a plain fact: Kubernetes was built as a single-cluster orchestrator for cooperating workloads, and every isolation property beyond that is something you assemble.
In November 2026 the assembly kit is richer than it was. User namespaces are stable (Kubernetes 1.36), vCluster supports private nodes, Capsule and Kamaji have matured, and GPU sharing makes tenant density an economic necessity. This guide treats tenancy as five separable isolation dimensions, maps four concrete models onto them, and ends with a decision procedure you can defend in a design review.
What this covers: the isolation spectrum, the control-plane leak that namespaces cannot fix, soft-tenancy primitives with working manifests, vCluster internals and its node models, Capsule and Kamaji, kernel-level hardening, failure modes, and a selection matrix.
Last Updated: November 2026
Context and Background
Multi-tenancy means running workloads from distinct trust domains, such as teams, customers or environments, on shared infrastructure while preventing interference or observation beyond what policy allows. The official Kubernetes multi-tenancy documentation frames it as a trade: sharing saves cost and simplifies administration, but introduces security, fairness and noisy-neighbour challenges. It also distinguishes two common shapes, multiple teams inside one organisation, and multiple customers of a SaaS product, each with different trust assumptions.
Practitioners shorthand the trust question as soft versus hard tenancy. Soft tenancy assumes semi-trusted tenants, typically internal teams who make mistakes but do not attack each other. Hard tenancy assumes a tenant may be hostile or that one compromise must never reach another. The Kubernetes project has long preferred describing concrete mechanisms over the soft/hard labels, and so should you, because the labels hide the fact that isolation is not one property.
It decomposes into at least five dimensions:
- Control-plane isolation: can a tenant see or mutate another’s API objects, or degrade the shared API server?
- Network isolation: can pods reach across tenant boundaries?
- Node and kernel isolation: does a container escape on a shared node compromise neighbours?
- Data isolation: secrets, persistent volumes and etcd contents.
- Resource isolation: can one tenant exhaust CPU, memory, API request budget or scheduler attention?
A design that is excellent on network isolation can be wide open on kernel isolation, which is why a single “isolated: yes” box on a questionnaire means nothing. Hold this decomposition in mind; every model below is scored against it.
The state of the art as of this writing, from vendor and project documentation: Kubernetes 1.37.1 is the newest minor line, with 1.36 and 1.35 still supported (kubernetes.io/releases). The old SIG Multi-Tenancy repository, which produced the Hierarchical Namespace Controller and the Virtual Cluster proposal, is archived under kubernetes-retired, so the practical ecosystem now lives in independent projects: vCluster from Loft Labs (documentation lists v0.37 as current stable), Capsule (a CNCF Sandbox project from Clastix), and Kamaji, also from Clastix. Tenancy is also the other face of self-service: the contract you offer tenants is the platform, as we discuss in our piece on platform engineering golden paths and Crossplane maturity.
The Isolation Spectrum: Four Models, Five Dimensions
The right tenancy model is the weakest one that still satisfies your threat model. Trusted internal teams usually need namespaces plus guardrails. Tenants who need their own CRDs or cluster-admin need a virtual control plane. Tenants running untrusted code additionally need kernel isolation, and adversarial or regulated tenants justify dedicated nodes or whole clusters. Each step up buys isolation and costs efficiency and operational effort.

Figure 1: The isolation spectrum, from namespace-only tenancy on the left of cost, through guardrailed namespaces, virtual clusters on shared nodes, virtual clusters with private nodes or sandboxed runtimes, to a dedicated cluster per tenant.
Figure 1 orders the models by blast radius. At the cheap end every tenant shares the API server, etcd, nodes, network and kernel, and you rely on policy objects to keep them apart. At the expensive end nothing is shared except the cloud account. The middle is where most real platforms live, and it is a continuum, not a ladder you must climb in order.
Why a single score is misleading
A useful habit is to draw the model as a matrix of dimension against mechanism. Namespaces with strong policy score well on resource and network isolation, poorly on control plane and kernel. A vCluster on shared nodes flips the control-plane column to strong while leaving the kernel column unchanged, because pods still run as ordinary containers on shared hosts. Private nodes fix the kernel column but cost you bin-packing. Dedicated clusters fix everything and multiply your operational surface by the tenant count.
Mixing is legitimate. A common production posture is a shared API server with strong RBAC and policy, combined with a gVisor or Kata node pool for tenants that run customer-supplied code. The goal is not purity; it is that every dimension has a defended answer.
The cost side of the spectrum
Isolation is paid for in three currencies: idle capacity, control-plane overhead, and humans. Dedicated clusters carry a control plane per tenant. Using an illustrative figure, a managed control plane costing on the order of seventy-odd dollars a month before any workers, multiplied by fifty tenants, is a few thousand dollars a year of pure overhead, trivial next to the staff time to patch, upgrade and observe fifty clusters. The real cost is operational: fifty upgrade windows, fifty certificate rotations, fifty sets of add-ons drifting apart. That is the argument for virtual and hosted control planes, which keep the fleet count low while giving each tenant a private API surface. Chargeback of whatever you build belongs next to it; see our guide to OpenCost allocation, showback and chargeback.
Soft Tenancy Primitives: What Namespaces Actually Give You
A namespace scopes names and is a target for RBAC, quota and policy. On its own it isolates almost nothing: two namespaces still share the API server, network, nodes and kernel. Isolation comes from the objects you attach. The baseline stack has five layers, shown in the admission path below.

Figure 2: The request path a tenant workload takes. Authentication and RBAC gate access, admission applies Pod Security and policy, quota rejects over-budget requests, the scheduler honours taints and affinity, the runtime may be sandboxed, and the CNI enforces NetworkPolicy.
Figure 2 doubles as a debugging map: when a tenant complains a deployment failed, the rejection point tells you which layer said no. Quota rejections happen at admission, long before the scheduler sees the pod, which is why an over-quota Deployment shows ReplicaSet events rather than Pending pods.
RBAC scoping
Give each tenant a group bound by RoleBinding to a Role in its own namespaces. The discipline is never to bind tenants to ClusterRoles at cluster scope, since cluster-scoped permissions are exactly the leak. Binding a built-in ClusterRole such as edit through a namespaced RoleBinding is fine and common; it grants the verbs only within that namespace.
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: team-blue-edit
namespace: team-blue
subjects:
- kind: Group
name: oidc:team-blue
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: edit
apiGroup: rbac.authorization.k8s.io
Note what edit omits: it cannot modify Roles or RoleBindings, so tenants cannot escalate by granting themselves more. Note also what it includes: read access to Secrets in the namespace, so a pod-creation right is effectively secret-read, because a pod can mount any secret in its namespace. That is a design fact worth stating to auditors.
Quota and defaults
ResourceQuota caps aggregate consumption; LimitRange supplies defaults so a tenant who forgets requests and limits does not get unbounded pods.
apiVersion: v1
kind: ResourceQuota
metadata:
name: team-blue-quota
namespace: team-blue
spec:
hard:
requests.cpu: "20"
requests.memory: 64Gi
limits.cpu: "40"
limits.memory: 128Gi
pods: "100"
persistentvolumeclaims: "20"
services.loadbalancers: "2"
count/secrets: "200"
Quota does not cover everything. It does not limit API request rate (that is API Priority and Fairness), does not limit etcd object size beyond per-object limits, and does not stop a tenant from creating thousands of small ConfigMaps unless you add count/ entries. A worked illustration: a tenant with 100 pods each requesting 200m CPU is 20 cores, exactly the quota above, and the thirty-first pod of the next deployment fails at admission. Illustrative numbers, but the behaviour is how quota admission works.
Default-deny networking
Kubernetes networking is flat: every pod reaches every other pod unless a NetworkPolicy says otherwise, and only if the CNI enforces policy. Start from default deny on both directions, then allow.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: default-deny-all
namespace: team-blue
spec:
podSelector: {}
policyTypes: [Ingress, Egress]
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-dns-and-same-namespace
namespace: team-blue
spec:
podSelector: {}
policyTypes: [Ingress, Egress]
ingress:
- from:
- podSelector: {}
egress:
- to:
- podSelector: {}
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
podSelector:
matchLabels:
k8s-app: kube-dns
ports:
- { protocol: UDP, port: 53 }
- { protocol: TCP, port: 53 }
Two traps. First, denying egress without allowing DNS produces baffling timeouts. Second, standard NetworkPolicy has no cluster-wide default and no deny rules, so platform teams often layer a CNI-specific cluster policy such as Cilium or Calico global policies; Kubernetes SIG Network has been developing admin network policies for this purpose. Treat their status as something to verify against your CNI version, not an assumption.
Pod Security and policy as code
Pod Security Admission applies the privileged, baseline or restricted Pod Security Standard per namespace via labels. For untrusted tenants, restricted is the floor: it forbids privilege escalation, host namespaces, hostPath volumes and most capabilities.
kubectl label namespace team-blue \
pod-security.kubernetes.io/enforce=restricted \
pod-security.kubernetes.io/enforce-version=latest \
pod-security.kubernetes.io/warn=restricted
PSA is deliberately coarse. It cannot require labels, pin registries, forbid :latest, or demand limits. Rules like that go into a policy engine, and in 2026 you have a native option: ValidatingAdmissionPolicy with CEL runs in the API server without a webhook, which removes the availability risk of an external webhook. We cover both approaches in Pod Security Standards with Kyverno and Gatekeeper and ValidatingAdmissionPolicy and CEL. A tenant guardrail written natively looks like this:
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: require-limits
spec:
failurePolicy: Fail
matchConstraints:
resourceRules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
validations:
- expression: >-
object.spec.containers.all(c,
has(c.resources) && has(c.resources.limits) &&
has(c.resources.limits.memory))
message: "every container must set a memory limit"
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
name: require-limits-tenants
spec:
policyName: require-limits
validationActions: [Deny]
matchResources:
namespaceSelector:
matchLabels:
tenancy.example.com/managed: "true"
The binding’s namespace selector is the tenancy hook: label a namespace and it inherits the rule. This labelled-namespace pattern is the seed of everything Capsule productises.
The Control-Plane Ceiling: Where Namespaces Stop Working
Everything above operates inside a shared API server, and that is the ceiling. Every tenant’s objects live in the same etcd, are served by the same API server, and pass through the same admission webhooks and CRDs. Three concrete leaks follow, and each of them has caused real incidents in shared clusters.
Cluster-scoped resources have no namespace
CRDs, ClusterRoles, PriorityClasses, StorageClasses, IngressClasses, webhook configurations and PersistentVolumes are global. If tenant A may create a CRD, its kind exists for everyone. If two tenants want widgets.example.com at different schema versions, they cannot have both: there is one CRD object per cluster and the last write wins. This is the CRD conflict, and it is fatal for any model where tenants install their own operators, which in 2026 means most platform and data teams, since Helm charts for databases, ingress controllers and ML tooling routinely ship CRDs.
A related problem is CRD upgrades. Operators bump CRD schemas in lockstep with controller versions. Two tenants running different versions of the same operator will repeatedly overwrite each other’s CRD, and conversion webhooks pointing at one tenant’s controller will serve everyone. The only clean answers are to forbid tenants from installing CRDs (platform-owned operators only) or to give them a separate API server.
Admission webhooks are shared fate
A tenant-owned validating or mutating webhook with failurePolicy: Fail that goes unreachable blocks matching API writes cluster-wide, including controllers’ own status updates. Even a platform-owned webhook is a tenancy hazard: a slow webhook consumes the API server’s request budget for everyone. Native CEL policies avoid the network hop, which is a strong reason to prefer them for tenant guardrails.
Discovery and API budget leak
Namespaces partition object names, not the API surface. Tenants can list cluster-scoped names they are permitted to see, discover API groups and versions, and, more importantly, share the API server’s concurrency. API Priority and Fairness (APF) classifies requests into priority levels and flow-queues them so one noisy client cannot starve others, but its defaults are tuned for control-plane components, not tenants. A tenant controller with a tight reconcile loop and a broken cache can generate enough LIST traffic to push p99 latency up for the whole cluster. You can add a FlowSchema that places tenant service accounts in a lower priority level with its own shares, which is cheap insurance.
This is the precise gap virtual control planes exist to close. The question to ask of any tenancy product is simply: where does the tenant’s API server live, and what does it share with mine?
vCluster Architecture: A Private API Surface on Shared Infrastructure
vCluster runs a real, certified Kubernetes control plane inside a pod on a host cluster and gives each tenant that control plane instead of access to the host API. By default a syncer copies the tenant’s workloads down into one host namespace where the host scheduler places them. The tenant sees a private cluster with its own CRDs, namespaces and cluster-admin; the host sees ordinary pods.

Figure 3: A tenant’s kubectl talks only to the virtual API server, backed by its own datastore. The syncer translates workload objects into a host namespace, the host scheduler places them on shared nodes, and status flows back to the virtual API.
Per the vCluster architecture documentation, the control plane consists of an API server, controller manager, a data store, the syncer and an optional scheduler, packaged into one container in a StatefulSet pod (a Deployment is also possible), with CoreDNS as a separate pod. The default backing store is embedded SQLite; external or embedded etcd, MySQL and PostgreSQL are alternatives. The virtual scheduler is off by default, meaning the host scheduler decides placement; enabling it lets the tenant use node labels, taints and drains against the virtual node view.
What the syncer actually does
The syncer is a reconciler pair. Going to the host, it takes pods and the resources they require (ConfigMaps, Secrets, Services, PVCs, optionally Ingress and Gateway API objects) and rewrites them into the host namespace with translated names, owner references and labels. Pod specs are modified: service account tokens are re-issued, names are suffixed, and host-side enforcement such as the host namespace’s Pod Security level, quota and NetworkPolicy still applies. Going from the host, it propagates pod status and events back, and can mirror host nodes into the virtual cluster either as fake nodes or real node objects, optionally filtered by label.
Two consequences matter. First, anything not synced exists only in the virtual cluster’s datastore. A tenant can create a thousand Deployments, ClusterRoles and CRDs, and the host sees only the pods that result. That is the isolation win: CRD conflicts, webhook outages and cluster-admin ambitions all become tenant-local. Second, the host namespace is your enforcement point. Quota on that namespace caps the tenant’s total footprint, a NetworkPolicy there fences its pods, and Pod Security labels there set a floor the tenant cannot override.
Tenancy models for worker nodes
The vCluster documentation distinguishes node models, and conflating them is the most common mistake in vCluster threat modelling:
- Shared nodes: tenant pods run on the host cluster’s nodes. This is the open-source default. Tenants share a kernel and nodes, so the docs do not treat it as a security boundary for untrusted tenants; it suits trusted teams, CI and dev environments.
- Dedicated nodes: a labelled subset of host nodes reserved for the tenant through node selectors. This scopes placement and noisy-neighbour behaviour but still does not add kernel isolation across tenants if nodes are shared with others in any layer.
- Private nodes: the tenant gets nodes that join its own control plane, with its own CNI and CSI. Only control-plane state is synced; workloads run directly on those nodes with no sync overhead. This suits GPU, regulated and untrusted tenants. Per the documentation, whether a given private-node capability is open source or part of the commercial platform should be checked for your version, since I could not verify the licensing split in this run.
- Standalone: a control-plane deployment option rather than a node model: a self-contained binary running on bare metal or VMs with no host Kubernetes dependency.
The practical reading: shared-node vCluster is a control-plane and developer-experience boundary, not a kernel boundary. If your threat model includes container escape, you either choose private nodes or you add runtime sandboxing and dedicated node pools underneath.
Configuration sketch
Field names change across vCluster releases, so treat this as a shape and validate it against your version’s values schema (documentation lists v0.37 as current stable in November 2026):
# vcluster.yaml sketch - verify against your release
controlPlane:
distro:
k8s:
enabled: true
backingStore:
etcd:
embedded:
enabled: true
statefulSet:
highAvailability:
replicas: 3
sync:
toHost:
pods:
enabled: true
ingresses:
enabled: true
fromHost:
nodes:
enabled: true
selector:
labels:
pool: tenant-blue
policies:
resourceQuota:
enabled: true
quota:
requests.cpu: 20
requests.memory: 64Gi
pods: 100
limitRange:
enabled: true
networkPolicy:
enabled: true
Create it with vcluster create tenant-blue -n vc-tenant-blue -f vcluster.yaml, then vcluster connect tenant-blue to obtain a kubeconfig. Because the tenant gets cluster-admin only over the virtual cluster, onboarding becomes a single command plus a values file, which is why this model composes well with GitOps.
Capsule, Kamaji, and the Alternatives
Virtual clusters are one answer to the control-plane problem. Two other projects solve neighbouring problems differently, and picking among them depends on whether the pain is namespace sprawl or API isolation.
Capsule: manageable soft tenancy
Capsule introduces a Tenant custom resource that groups namespaces under an owner and applies policy to all of them. Per the project site, a Tenant defines access and rules declaratively, TenantOwners can create ordinary namespaces without cluster-admin or a ticket, and Capsule applies configured quotas and policies and rejects requests outside the tenant’s rules. An optional Capsule Proxy filters list calls so owners see only their own namespaces, which solves the cluster-scoped listing leak for namespaces specifically. Capsule is a CNCF Sandbox project.
Capsule keeps one shared API server, so it does not fix CRD conflicts or webhook shared fate. It fixes the human problem: without it, every new namespace is a ticket, and policy drifts between namespaces. If your tenants are internal teams who consume platform-owned operators, Capsule on a hardened cluster is frequently all you need, and it is far cheaper to operate than a fleet of virtual clusters.
Kamaji: hosted control planes
Kamaji is an operator that runs each tenant cluster’s control plane as pods in a management cluster, using unmodified upstream Kubernetes components built with kubeadm. Worker nodes are separate, from bare metal, VMs or cloud instances, including hybrid setups. Compared with vCluster, Kamaji’s tenants get real separate nodes by design, so it is closer to a managed-Kubernetes-as-a-service model than to a lightweight virtual cluster. It fits when you are the “cloud provider” for many teams or customers and want cheap, fast control planes with genuine node isolation. It is heavier to onboard than a vCluster on shared nodes because you must provision and join workers.
Hierarchical namespaces and the retired SIG repo
The Hierarchical Namespace Controller let you nest namespaces and inherit RBAC and policy. The SIG Multi-Tenancy repository that housed it now sits under kubernetes-retired, so new designs should use Capsule, Kyverno generate rules or GitOps templating to achieve inheritance rather than depend on HNC.
Choosing between the three
| Need | Namespaces plus policy | Capsule | vCluster shared nodes | vCluster private nodes or Kamaji |
|---|---|---|---|---|
| Tenant-owned CRDs | No | No | Yes | Yes |
| Tenant cluster-admin | No | No | Virtual only | Virtual only |
| Self-service namespaces | Manual | Yes | Native | Native |
| Kernel isolation | No | No | No | Yes, node level |
| Control-plane overhead per tenant | None | None | Low, a pod or three | Low to moderate, plus nodes |
| Bin-packing efficiency | Best | Best | Good | Reduced |
Kernel, Node, and Data Isolation: The Layer Policy Cannot Reach
Every primitive so far operates above the kernel. By default, containers from every tenant on a node share the host kernel through the same runtime. A container escape, whether a runc vulnerability or a kernel privilege-escalation bug, lets a compromised pod reach every other pod scheduled on that node regardless of namespace, RBAC or NetworkPolicy. This is the dimension most often skipped in soft-tenancy designs, because nothing in the YAML you write for namespaces touches it.
Four mitigations in increasing strength
Dedicated node pools use taints and tolerations plus node affinity to keep a tenant’s pods on nodes only that tenant uses. An escape is then contained to the tenant’s own blast radius. It is simple and works with any runtime, but it fragments capacity: ten tenants each needing 1.3 nodes’ worth of load means ten tenants times two nodes, a worked example (illustrative) of 20 nodes where a shared pool would need about 13. The efficiency you went multi-tenant for evaporates.
# Pin a tenant to its pool and keep others off it
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
namespace: team-blue
spec:
replicas: 3
selector:
matchLabels: { app: api }
template:
metadata:
labels: { app: api }
spec:
nodeSelector:
pool: tenant-blue
tolerations:
- key: tenant
operator: Equal
value: blue
effect: NoSchedule
containers:
- name: api
image: registry.example.com/blue/api:1.4.2
Taints alone do not force placement and tolerations alone do not restrict it; you need both a taint on the node and a selector or affinity on the pod, and you need admission policy so tenants cannot add tolerations for someone else’s pool. The Kubernetes PodTolerationRestriction admission plugin or a CEL policy can enforce that.
User namespaces are the newest inexpensive win. With hostUsers: false in the pod spec, root inside the container maps to an unprivileged UID on the host. The Kubernetes documentation lists the feature as stable as of v1.36, first available in v1.28, and no longer disableable. It needs a runtime that supports it and a kernel with ID-mapped mount support; verify the minimums against your distribution. It does not make an escape impossible, but it turns many “container root equals host root” bugs into unprivileged ones. Our walkthrough of user namespaces, seccomp and RuntimeClass covers rollout detail. For tenants you do not fully trust, enforce hostUsers: false by policy in addition to the restricted Pod Security Standard.
gVisor interposes a user-space kernel, the Sentry, which intercepts syscalls so the application rarely touches the host kernel directly. It shrinks the attack surface at the cost of syscall-heavy workload performance and some compatibility gaps. Kata Containers runs each pod in a lightweight microVM with its own guest kernel, giving near-VM isolation with higher memory overhead and startup latency, and requires nested virtualisation or bare metal. Both integrate through RuntimeClass:
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
name: gvisor
handler: runsc
scheduling:
nodeSelector:
sandbox: gvisor
tolerations:
- key: sandbox
operator: Exists
---
apiVersion: v1
kind: Pod
metadata:
name: untrusted-job
namespace: customer-42
spec:
runtimeClassName: gvisor
hostUsers: false
containers:
- name: job
image: registry.example.com/customer/job:latest
The RuntimeClass scheduling block places sandboxed pods on capable nodes automatically, so tenants do not need node-selector knowledge. Pair it with a policy that mandates runtimeClassName for namespaces labelled untrusted. Runtime-level hardening and CVE response is its own discipline; see our notes on containerd, CRI-O and Podman hardening.
Confidential containers and dedicated hardware sit at the far end: hardware-rooted memory encryption for tenants who do not trust even the cloud operator. Reserve them for regulated data.
Data isolation
Kubernetes Secrets are base64 in etcd; enable encryption at rest with a KMS provider so a stolen etcd snapshot is not plaintext. With a shared etcd, one snapshot exposes every tenant, which is another argument for per-tenant datastores in virtual clusters. For persistent volumes, a PV is cluster-scoped and binds one-to-one to a PVC, so cross-tenant leakage usually comes from misconfigured reclaim policy, shared NFS exports, or hostPath. Use a StorageClass with reclaimPolicy: Delete for tenants, forbid hostPath via Pod Security, and prefer CSI drivers that support per-volume encryption. Pod identity matters too: with projected service account tokens and workload identity, bind cloud IAM roles per tenant namespace, never per node, or one tenant inherits the node role.
Noisy neighbours beyond CPU
Quota covers requests and limits, but contention hides elsewhere. CPU limits cause CFS throttling that can hurt latency even when the node is idle, a subject we analyse in Kubernetes CPU throttling and cgroup v2. Disk IOPS, network bandwidth, conntrack table entries, inode counts, and PIDs per node are shared resources with no namespace-level quota. Set podPidsLimit in kubelet configuration, use PriorityClasses so tenant batch work is preempted before platform components, and use topology spread to avoid concentrating one tenant on a single failure domain. GPUs add a new axis: whole-GPU allocation, MIG partitioning and time slicing give very different isolation, and Dynamic Resource Allocation is changing how claims are expressed, covered in our DRA GPU scheduling guide. Time slicing shares memory with no fault isolation; MIG gives hardware partitioning on supported GPUs. Treat shared GPU memory like shared kernel: a boundary only if you verified it.
Deeper Analysis: Failure Modes, Capacity, and a Worked Tenant Design
Theory is easy; the instructive part is how each model fails. Walk through a scenario: a platform with forty internal teams, a mix of stateless services and data tooling, plus a sandbox product that runs customer-submitted notebooks. Illustrative numbers throughout.
Blast-radius analysis by failure
| Failure | Namespaces plus policy | vCluster shared nodes | vCluster private nodes |
|---|---|---|---|
| Tenant deploys broken CRD | Affects all tenants | Tenant only | Tenant only |
| Tenant webhook down, failurePolicy Fail | Cluster-wide write outage | Tenant only | Tenant only |
| Container escape on node | All tenants on that node | All tenants on that node | Tenant only |
| Tenant LIST storm on API | Shared API degraded | Virtual API degraded, host mostly insulated | Same |
| Host API server outage | All down | Control planes may be running but pods not scheduled or synced | Workloads keep running, control plane state may stall |
| Misconfigured host NetworkPolicy | Lateral movement | Lateral movement | Per-tenant CNI contains it |
Read the vCluster column carefully: the virtual control plane sits on the host, so a host outage still hurts. With shared nodes, the host scheduler and syncer are on the critical path for every tenant pod. With private nodes, running pods keep running when the host control plane is unavailable, because workloads are not synced through it, though you lose the ability to change anything until recovery. Test this with a game day rather than trusting the diagram.
Capacity and the control-plane tax
A hosted or virtual control plane is not free. A vCluster control plane running k8s distro with embedded etcd and three replicas might reserve on the order of a CPU core and a couple of gigabytes of memory across the HA set at idle (illustrative; measure with your workloads, since object count dominates). For forty teams that is forty to a hundred cores reserved, small next to forty clusters’ worth of three control-plane VMs plus add-ons, yet not negligible. SQLite backing is fine for dev and CI vClusters that live minutes; use etcd or an external database for anything long-lived, and size for object count and watch fan-out, not pod count.
The syncer’s cost scales with synced objects. A tenant that creates ten thousand short-lived Jobs generates ten thousand pods and events on the host. Enforce quota on both the virtual cluster, where the tenant sees an understandable error, and the host namespace, where it is a backstop.
Upgrade and version skew
Virtual clusters bring their own Kubernetes version, which is a feature and a hazard. Tenants can run a newer or older API version than the host, up to the limits of the syncer’s compatibility, but each tenant is also now a cluster someone must patch. The vCluster documentation shows older minor lines at end-of-support status, so a fleet of forgotten tenant clusters is a real security liability. Make upgrade a platform operation: pin versions in Git, roll them on a schedule, and alert on any control plane more than two minors behind the host.
Observability and cost attribution
On shared nodes, metrics from the host see translated pod names and host namespaces, not tenant names. Label propagation from the syncer is essential for showback; confirm that labels you rely on for cost allocation survive translation. Logs and audit events have the same issue: the virtual API server writes its own audit log, so decide where tenant audit goes and who may read it. For the host cluster, audit the syncer’s service account carefully: it holds broad rights in each tenant host namespace, and compromising it is compromising every tenant’s workloads. Treat that as the crown-jewel identity of the platform.
A reference design for the scenario
For the forty internal teams, run one hardened host cluster, label namespaces by tenant, install Capsule for self-service namespaces, enforce Pod Security restricted and CEL policy, set default-deny network policy through your CNI, and give each team an APF FlowSchema. Teams that need their own operators get a vCluster on shared nodes, which costs a pod set and a host namespace. For the notebook sandbox, create a separate node pool with the gVisor RuntimeClass, hostUsers: false, egress denied except an allow-list, and tight ephemeral-storage and PID limits; or, if customers can be hostile and data is regulated, give each large customer a vCluster on private nodes. Finally, keep platform-owned components, ingress, DNS, the policy engine and observability, off tenant node pools and at higher PriorityClass.
Figure 4 below encodes that reasoning as a decision flow you can walk with a new tenant at intake.

Figure 4: A selection flow. Trusted tenants without CRD needs stay on guarded namespaces; those needing CRDs or admin move to a virtual cluster; untrusted tenants running arbitrary code require private nodes or a sandboxed runtime plus user namespaces; regulated tenants may need dedicated clusters.
The flow is deliberately short. It asks about trust and about arbitrary code, because those two answers move you across the kernel boundary, while CRD and admin needs move you across the control-plane boundary. Two questions, two boundaries.
Trade-offs, Gotchas, and What Goes Wrong
Virtual clusters are not a security panacea. The most dangerous misunderstanding is “vCluster means hard multi-tenancy”. On shared nodes it gives control-plane isolation only; the kernel, node network and host component fate are shared. The vendor’s own node-model documentation says as much. If you tell an auditor “tenants are isolated by virtual clusters” without naming the node model, you have made a claim you cannot defend.
Defence in depth means more things to keep consistent. Every layer you add, Capsule on top of policy on top of vCluster on top of gVisor, is another component to upgrade and another place for configuration drift. The failure mode is rarely a clever attack; it is a namespace that missed a label, so the policy binding never matched and a tenant got privileged pods for six weeks. Prefer policy that fails closed on unlabelled namespaces, and audit label coverage continuously.
Quota and policy create friction that tenants route around. Tight defaults without a self-service exception path push teams to ask for dedicated clusters, which defeats consolidation. Publish the limits, provide a request flow, and measure how often exceptions are granted.
Sandboxes have compatibility costs. gVisor does not implement every syscall or /proc and /sys behaviour; some eBPF tooling, certain filesystems and GPU workloads will not run inside it. Kata needs virtualisation support, which many cloud VM types do not expose without bare metal or nested virtualisation. Discover this in a pilot, not in a customer incident.
Operator sprawl in shared control planes. If tenants share a cluster and platform teams install every operator for them, the API server’s CRD count and watch load climb. Large CRD counts raise API server memory and discovery latency. This is a legitimate reason to push heavy-operator tenants into their own virtual clusters.
Shared ingress and DNS remain shared fate. A single ingress controller, now a retiring-and-migrating component for many teams (see our Gateway API migration playbook), is a tenancy boundary of its own: one tenant’s malformed Ingress snippet or annotation can affect the shared proxy. Disable annotation-based configuration snippets for tenants, or give tenants their own gateway instances.
Anti-patterns to retire:
- Handing tenants ClusterRoleBindings “temporarily”.
- Relying on namespace names as a security boundary in policy matches.
- Assuming NetworkPolicy works without verifying that your CNI enforces it.
- Running tenant-owned webhooks with
failurePolicy: Fail. - Sharing one service-account token mount across tenants through node-level IAM.
- Treating a vCluster fleet as set-and-forget.
Practical Recommendations
Start from the threat model, not from the product. Write one paragraph per tenant class stating who they are, what code they run, what data they touch and what regulators care. Then pick the cheapest model that covers every one of the five dimensions for that class, and document the dimensions you are knowingly leaving weak.
For internal teams on cooperative terms, a hardened shared cluster plus Capsule gets you most of the value at the lowest operational cost. Add vCluster the day a team needs CRDs, a different Kubernetes version, or cluster-admin, rather than preemptively. For anything running customer or third-party code, assume escape is possible: use private nodes or a sandbox runtime on a dedicated pool, with user namespaces on. For regulated workloads, price dedicated clusters honestly against private-node virtual clusters, because fleet tooling has made the gap narrower than it used to be.
Invest early in the unglamorous parts: tenant onboarding as code, label hygiene, version pinning of every virtual control plane, per-tenant cost attribution, and a documented exit path from each model to the next. Run a tenancy game day twice a year: break a webhook, flood the API, kill the host control plane and attempt a lateral move, then record what actually happened.
Checklist before admitting a tenant:
- [ ] Trust level and data classification written down and signed off.
- [ ] Dedicated tenant identity group; no cluster-scoped RBAC bindings.
- [ ] Pod Security
restrictedenforced; policy bindings verified by test pod. - [ ] ResourceQuota, LimitRange and PID limits set; APF FlowSchema assigned.
- [ ] Default-deny ingress and egress verified with a connectivity test, DNS allowed.
- [ ] Node model chosen; sandbox RuntimeClass and
hostUsers: falseif untrusted. - [ ] Secrets encrypted at rest; cloud IAM bound per tenant, not per node.
- [ ] Cost labels survive any translation layer; showback visible to the tenant.
- [ ] Virtual control-plane version pinned and on an upgrade schedule.
- [ ] Offboarding procedure tested: namespaces, volumes, DNS records and credentials all removed.
Frequently Asked Questions
Is a Kubernetes namespace a security boundary?
Not by itself. A namespace scopes names and gives RBAC, quota and policy something to attach to, but tenants still share the API server, etcd, network and kernel. It becomes a useful soft boundary only when you add RBAC scoping, ResourceQuota, default-deny NetworkPolicy and Pod Security Admission, and even then it does not protect against container escape or cluster-scoped resource conflicts such as CRDs. For untrusted tenants, add sandboxed runtimes or separate nodes.
What is the difference between vCluster and Capsule?
Capsule keeps one shared API server and adds a Tenant resource that groups namespaces, lets owners self-serve them, and applies quotas and policies automatically. vCluster instead gives each tenant its own virtual control plane with separate CRDs, cluster-admin and datastore. Capsule makes soft tenancy manageable at scale; vCluster provides control-plane isolation. Neither isolates the kernel on shared nodes, so untrusted tenants still need sandboxing or dedicated nodes.
Does vCluster provide hard multi-tenancy?
Only partly, depending on the node model. On the default shared-node model, the control plane is isolated but pods run on shared hosts with a shared kernel, so vCluster’s documentation does not treat it as a boundary for untrusted tenants. With private nodes, each tenant has its own nodes, CNI and CSI, which is much closer to hard isolation. Validate which features your edition includes before relying on them.
When should I use dedicated clusters instead of virtual ones?
Choose a cluster per tenant when regulation or contract demands physical separation, when tenants need different cloud accounts, networks or compliance scopes, or when blast-radius requirements outweigh cost. Fleet tooling and hosted control planes have narrowed the cost gap, so compare against private-node virtual clusters or Kamaji first. If you do pick dedicated clusters, standardise provisioning and upgrades from day one or you will inherit fleet drift.
Are gVisor and Kata worth the overhead for multi-tenant clusters?
For tenants running untrusted or customer-supplied code, yes: they cut the shared-kernel attack surface that policies cannot reach. gVisor adds syscall overhead and compatibility gaps; Kata costs more memory and startup time and needs virtualisation support. For trusted internal workloads, user namespaces with the restricted Pod Security profile and seccomp are usually enough. Pilot both with your real workloads, since overhead is highly workload-dependent.
How do I stop one tenant from exhausting the API server?
Use API Priority and Fairness: create FlowSchemas that map tenant service accounts to a lower priority level with limited concurrency shares, so their LIST and WATCH storms queue instead of starving system components. Add client-side rate limits in tenant controllers, avoid unbounded list calls, and cap object counts with quota. A virtual cluster moves tenant traffic to its own API server and shields the host further.
Further Reading
- Pod Security Standards, Kyverno and Gatekeeper hardening: the policy layer for every tenant namespace.
- User namespaces, seccomp and RuntimeClass: the kernel-hardening layer this guide depends on.
- ValidatingAdmissionPolicy and CEL: webhook-free tenant guardrails.
- Platform engineering golden paths and Crossplane: tenancy as a platform contract.
- OpenCost allocation and chargeback: attributing shared-cluster cost to tenants.
- Kubernetes multi-tenancy documentation and user namespaces reference.
- vCluster architecture documentation and Capsule project.
By Riju — about
