Imagine you are part of a team already running one Kubernetes cluster, and a second team asks for somewhere to deploy.
A cluster of their own is the simplest answer but might be the most expensive one.
Multi-tenancy is one of the solutions to this problem. You put both teams on the same cluster and build the boundaries between them yourself, out of namespaces, RBAC, network policies, and quotas.
When a tenant needs more separation than those give, tools like vCluster and Kamaji hand them an API server of their own while they keep running on your nodes.
Each team ends up with something that behaves like their own cluster, while underneath they are all still in the same one.
When you actually need Kubernetes multi-tenancy
There are multiple reasons why you might be looking into multi-tenancy, and cost is one of the most important. If any of these describe your situation, you should probably be considering it:
Implementing multi-tenancy has its trade-offs. You shrink your cloud invoice by spending your platform team's engineering hours instead. The trick is making sure those hardware savings are not quietly eaten up by the work of securing, managing, and maintaining all those tenant boundaries.
Choosing between the three multi-tenancy models
Once you know whether you need multi-tenancy, the next thing to settle is which kind you run. Three architectures trade isolation against cost and operational effort:
Figure 1: Namespace per tenant, where everything under the namespace is shared
Figure 2: Virtual control plane per tenant, separate API servers on shared nodes
Figure 3: Cluster per tenant, where nothing at all is shared
Three questions are usually enough to pick a model, and the first often decides it before you reach the other two:
- Would a tenant ever try to break out? Teams inside your own company are not attacking each other, so namespaces with RBAC and network policy hold up fine. Code you did not write and cannot audit is a different problem, because logical separation still leaves it sharing a kernel with everyone else.
- Does a tenant need to install their own CRDs, or run a different Kubernetes version? A CustomResourceDefinition is installed once for the entire cluster, so two tenants who need different versions of the same one cannot both be served. A yes here rules out namespace-per-tenant on its own, whatever else you do.
- What does it cost you when isolation fails? One team slowing another down costs you an afternoon. One customer reading another customer's data in a regulated industry costs you the contract.
If a tenant needs their own CRDs, you need at least a virtual control plane. If that tenant might also try to break out, the cost of a failure decides between a virtual control plane and a cluster of their own.
Soft and hard multi-tenancy, and where the line actually falls
Soft multi-tenancy
Soft multi-tenancy means tenants share one control plane and stay apart because policy keeps them apart. Four layers are involved in the work, and each one handles a different part of it:
- Namespaces scope object names, so two tenants can both have a Deployment called
api, and every other control attaches to the namespace - RBAC decides which API calls a tenant can make, so they can create pods in their own namespace and nowhere else
- Network policy decides which pods can reach which, so a pod in one tenant's namespace cannot open a connection to another tenant's
- Resource quotas cap what a tenant consumes, so one team cannot take the CPU and memory the others need
All four assume the tenant is not attacking you. They stop mistakes and they stop casual snooping.
What they do not stop is a container escape, because every tenant still runs on the same nodes and the same kernel, so an attacker who gets out of a container lands on a machine with other tenants' workloads already on it.
Hard multi-tenancy
Hard multi-tenancy means the boundaries are built as though the tenant is actively trying to break out. That kind of boundary needs a separation stronger than policy alone, and it comes through:
- The control plane. A virtual cluster gives each tenant their own API server and datastore, so their CRDs never touch anyone else's.
- The kernel. A sandboxed runtime such as gVisor or Kata Containers means an escape from the container does not land on the shared host kernel.
- The machine. Dedicated node pools with taints and node affinity keep a tenant's pods the only ones on those nodes.
- All of it. A separate cluster per tenant is the strongest option and the most expensive to run.
Most setups combine both hard and soft multi-tenancy. Ordinary tenants get a namespace with RBAC, network policy, and quotas, which is the soft half, and the ones that cannot share a machine get their own control plane or their own nodes, which is the hard half.
What a tenant is, and what each kind can do to you
The word "tenant" covers four different things, and each one brings a different threat model:
- A team inside your company. Nobody here is trying to break out, so what goes wrong is an accident, like someone opening a NodePort on a public node to debug something quickly and forgetting to close it. They need a namespace with RBAC and quotas, and not much else, because you can also just tell them what not to do.
- A customer running their own code. Assume some of them will try, since you cannot see what their code does, and telling them what not to do achieves nothing. They need separation that is built in rather than agreed, through a virtual control plane or nodes they do not share with anyone.
- An environment, such as dev or staging next to production. Nobody is trying to break out here. Production going down matters and dev going down does not, so the separation only needs to run one way. Cap what the dev and staging namespaces can use, so a load test there cannot take capacity production needs.
- One instance of your SaaS product. The risk is inconsistency as you scale rather than attack. Every instance comes from the same template, so the fiftieth customer's deployment matches the first and you are not debugging fifty variations.
Key challenges in Kubernetes multi-tenancy implementation
These problems come from how Kubernetes itself works, so you plan around them rather than fixing them:
- Cluster-scoped resources have no tenant dimension. Two tenants needing different versions of one CRD cannot both be served, which is what forces some teams off namespace-per-tenant entirely.
- Namespace count degrades the control plane eventually. Hundreds of namespaces, each with policies and bindings, put real load on the API server and etcd, and the failure is gradual rather than sudden.
- Isolation drifts across upgrades. A CNI upgrade that changes policy semantics, or a Kubernetes version that changes a default, can weaken a boundary without anyone editing a policy.
- Tooling is fragmented and moves. Hierarchical namespaces looked like a standard answer for years, and that repository was archived in April 2025, so anything built on it now inherits an unmaintained dependency.
- Tenants cannot see their own metrics without seeing everyone's. Prometheus scrapes the whole cluster and its query API has no notion of a tenant, so a per-tenant dashboard means a proxy in front that forces a namespace label onto every query, or a separate stack per tenant. This limitation is one of the clearer arguments for a virtual control plane, where the tenant runs their own stack.
- Attribution is genuinely hard. Splitting a shared node's cost across the tenants on it requires tooling you have to add.
Choosing a model and making it hold
Pick the model your tenants actually justify rather than the strongest one you can imagine needing. Once you have chosen, the work moves to the controls that enforce it, and our guide to Kubernetes tenant isolation covers each one in the order you would apply it.
Whichever tenant isolation model you land on, You can sign up and try it on a Rackspace Spot cluster with pricing starting at $0.01 an hour.
Frequently asked questions
What is multi-tenancy in Kubernetes?
Running workloads for multiple teams, customers, or environments on shared cluster infrastructure, separated by namespaces, RBAC, network policies, and quotas rather than by separate machines.
What's the difference between a single-tenant and a multi-tenant Kubernetes cluster?
A single-tenant cluster serves one team or customer, so the cluster edge is the boundary. A multi-tenant cluster shares one control plane and nodes, and every boundary inside it is something you configured.
What are the limitations of multi-tenant Kubernetes?
Cluster-scoped resources like CRDs and ClusterRoles exist once for everyone, tenants share a kernel unless you add sandboxing, and namespaces are globally listable, so tenants can see each other's namespace names.
What are the disadvantages of multi-tenancy?
One failure reaches more tenants, cost attribution is harder, and isolation depends on configuration staying correct across upgrades. The saving is real, and so is the operational burden of keeping the boundaries honest.
Is multi-tenancy good for SaaS platforms?
Usually yes, since running one cluster per customer rarely pays for itself. Start with namespace-per-customer, then add virtual control planes or dedicated nodes for customers whose contracts require stronger separation.
What's the difference between Kubernetes multi-tenancy and a multi-cluster architecture?
Multi-tenancy divides one cluster between tenants. Multi-cluster runs several clusters, whether for tenants, regions, or environments. Cluster-per-tenant is where the two overlap.