Start with the economics and the operating pressures that make multi-tenancy attractive, and risky.

The cost of one cluster per team

The cleanest way to keep teams apart is to give each one its own cluster. Nobody can disturb anybody, and mistakes are contained. But every cluster carries a fixed overhead: control plane machines, monitoring, logging, certificates, upgrades, security patching and people to run it all. With dozens of teams this becomes expensive and slow, and many clusters end up half empty, because each is sized for its peak.

What sharing buys

What sharing risks

Sharing creates three kinds of risk. Noisy neighbours are tenants that consume so much that others suffer. Snooping and tampering are tenants that read or change what belongs to others. Shared failure is when one tenant’s mistake, such as flooding the API server, harms everyone. A well-designed multi-tenant cluster limits all three risks, and the namespace is only the first of several tools.

Get the definition exactly right, because every design decision depends on it.

The definition

A namespace is a named scope inside a cluster. Most Kubernetes objects, such as Pods, Services, ConfigMaps, Secrets and Deployments, live inside exactly one namespace. Names only need to be unique within their namespace, so two teams can both have a Service called “web” without any clash. Many access rules and limits are attached to a namespace, which makes it the natural unit for handing out slices of a cluster.

What lives outside any namespace

Some objects are cluster-scoped. They belong to the whole cluster and cannot be placed in a namespace. This list is the main reason a namespace is not a complete boundary.

What a namespace does not give you

Before choosing any limit, decide who your tenants are and how much you trust them.

Who is a tenant?

A tenant is a group that uses a share of the cluster and should be kept somewhat apart from other groups. It might be a team in one company, a department, a project, a customer of a software service, or an environment such as testing. The right amount of isolation depends on who they are.

Soft and hard multi-tenancy

Soft multi-tenancy assumes tenants are friendly: different teams in the same organisation who share goals and can be held accountable. The aim is mostly to prevent accidents, such as one team using up all the memory or editing another team’s Deployment by mistake. Hard multi-tenancy assumes tenants may be hostile or run untrusted code: customers of a hosting platform, for example. The aim is to withstand deliberate attacks. Namespaces plus policies are a reasonable foundation for soft multi-tenancy. For hard multi-tenancy they are necessary but usually not sufficient.

The main tenancy models

flowchart TD
  Q["Who are your tenants?"] --> T{"Do you trust them to run code safely?"}
  T -- "Yes, same organisation" --> S["Namespaces with quotas, access and network rules"]
  T -- "Mostly, but different risk levels" --> N["Add dedicated node pools and stricter security profiles"]
  T -- "Not fully, may run untrusted code" --> R["Add sandboxed runtimes, consider virtual clusters"]
  T -- "No, hostile or regulated" --> C["Use a separate cluster per tenant"]
        

A single control never carries the weight. Namespace isolation is a stack of layers, each covering what the others cannot.

The six layers

A well-built tenant namespace combines several kinds of limit. Each answers a different question about what a tenant may do.

flowchart TD
  T["Tenant workload"] --> L1["Layer 1: quotas and default sizes"]
  L1 --> L2["Layer 2: access rules"]
  L2 --> L3["Layer 3: network rules"]
  L3 --> L4["Layer 4: Pod security profiles"]
  L4 --> L5["Layer 5: node placement and sandboxes"]
  L5 --> L6["Layer 6: control plane fairness"]
  L6 --> C[("Shared cluster")]
        

The next chapters take each layer in turn, starting with the most visible one: limits on how much a tenant may consume.

The main tool for capping how much of the cluster a tenant can claim.

What it is

A ResourceQuota is an object placed in a namespace that sets hard caps on the total amount of resources the whole namespace may use. When someone tries to create something that would push the total over the cap, the request is refused. Think of it as a monthly budget for the whole floor of the building.

What a quota can limit

Requests versus limits in a quota

Containers declare two numbers for CPU and memory. The request is what the scheduler reserves, a guaranteed minimum. The limit is the ceiling the container may not exceed. A quota can cap the total of requests, the total of limits, or both. Capping requests controls how much of the cluster’s capacity a tenant can reserve. Capping limits controls how far the tenant can burst. Most platforms cap both, because capping only one leaves a gap.

Scopes: quotas for particular kinds of Pod

A quota can apply only to a subset of Pods by using scopes. For instance, a scope can select long-running Pods separately from short-lived ones, or Pods with no declared sizes from Pods with them, or Pods of a particular priority class. This lets you give a tenant, say, a generous budget for batch Pods and a small budget for high-priority Pods, so that important capacity cannot all be taken by one team.

A quota caps the total. A LimitRange shapes each individual container, Pod and claim.

What it is

A LimitRange is another namespace-level object. Where a quota controls the namespace total, a LimitRange controls the size of each individual thing. It can set default values for containers that did not declare any, minimum and maximum sizes that each container or Pod may have, and a maximum ratio between a container’s limit and request. It can also bound the size of each storage claim.

Why quotas and LimitRanges belong together

There is an important interaction. When a namespace has a quota on CPU or memory, every new container in it must declare its size, or the request is rejected, because the system cannot add up an unknown amount. Developers who forget to set sizes would hit confusing errors. A LimitRange with default values fills in sensible sizes automatically, so the quota can do its arithmetic and the developer’s workload is accepted.

What it does not do

Quotas and ranges are checked at one particular moment in a request’s life. Knowing when helps you predict their effects.

The gatekeepers in order

Every request to create or change an object passes through the API server in stages. First the caller is identified, then checked for permission, then the request passes through admission controllers: gatekeepers that can change or reject the request before it is stored. Defaults from a LimitRange are applied early, because they modify the object. Security profile checks and custom policies run as validators. The quota check runs near the end, so that it counts the object in its final form.

sequenceDiagram
  participant U as Tenant user
  participant A as API Server
  participant LR as LimitRange step
  participant PS as Security profile and policy checks
  participant RQ as Quota check
  participant E as Database
  U->>A: Create a Pod in the tenant namespace
  A->>A: Identify caller and check permission
  A->>LR: Fill in default sizes, check min and max
  LR-->>A: Pod now has sizes
  A->>PS: Check Pod settings against security rules
  PS-->>A: Allowed
  A->>RQ: Would the new total exceed the quota?
  RQ-->>A: Within budget, usage updated
  A->>E: Store the Pod
  E-->>U: Pod created
        

What this order means in practice

Defaults are added before the quota check, so an unsized container passes if the LimitRange gives it a size and the quota has room. A Pod that violates the security profile is rejected before it uses up any of the quota. A request rejected for exceeding the quota gets a clear message that names the resource and the numbers involved, which makes it easy to understand.

Where problems hide: controllers that create Pods

Users rarely create Pods directly. They create Deployments, Jobs and StatefulSets, which in turn create Pods through controllers. If the quota or a policy rejects the Pod, the error does not appear when the user applies the Deployment, since the Deployment itself is accepted. The error appears later, as an event on the controller’s child object, and the Deployment simply shows fewer Pods than wanted. This surprises many people: the apply succeeds, yet nothing runs, and the reason is hidden one level down in events.

Usage accounting and timing

The system keeps a running tally of used amounts. The tally is updated at admission and reconciled by a controller, so very rapid bursts of requests are checked consistently, but the reported usage may lag by moments. Deleting objects frees the budget after they are fully gone, not the instant a deletion is requested, which matters for Pods that take time to shut down.

Quotas control what you may reserve. What happens when tenants actually use the machines is a separate story.

Requests schedule, limits enforce

A container’s CPU and memory request is used by the scheduler when choosing a node: it reserves that amount on the node. The limit is enforced at runtime by the node. If a container exceeds its memory limit, it is killed. If it exceeds its CPU limit, it is slowed down, a behaviour called throttling. Requests are about fairness at placement time, limits are about protection at run time.

Quality of service classes

Based on how requests and limits are set, every Pod falls into one of three classes. This class decides who suffers first when a node runs short of memory.

Noisy neighbours on a shared node

Even with quotas, tenants whose Pods share a node can interfere with each other in ways that quotas do not measure. CPU limits protect from CPU overuse, but a tenant can still hammer the disk, saturate the network card, exhaust the number of processes allowed on the node, or fill the node’s temporary storage. These shared resources are harder to partition, and they are a common reason to give sensitive tenants their own nodes.

Quotas stop overuse. Access rules stop snooping and tampering.

The building blocks

Kubernetes uses role-based access control, usually shortened to RBAC. A Role lists permissions, such as “may read and create Pods” within one namespace. A RoleBinding attaches a role to people, groups or program identities, called service accounts, inside that namespace. There are cluster-wide versions of both, called ClusterRole and ClusterRoleBinding, whose effects span every namespace.

The standard pattern for tenants

Permissions that quietly break isolation

By default every Pod can talk to every other Pod. Network policies change that default.

The open-by-default network

Out of the box, Kubernetes networking is flat and open. A Pod in one tenant’s namespace can reach Services in any other, using their predictable cluster DNS names. This means a compromised or curious workload can probe and attack neighbours’ services unless the network is restricted.

What a network policy is

A NetworkPolicy is a namespace-level object that describes which traffic is allowed to and from selected Pods. Policies are additive and permissive in nature: once any policy selects a Pod for a direction, only the traffic explicitly allowed for that direction is permitted. They are enforced by the cluster’s network plugin, so a plugin that supports them is required. Without one, the objects exist but have no effect.

The default-deny starting point

The standard approach for tenants is to begin with a policy that denies all incoming traffic to every Pod in the namespace, and often all outgoing traffic too. Then add narrow allow rules for what the tenant truly needs: traffic between its own Pods, access to cluster DNS, access to shared platform services, and access from the ingress layer. Everything else is blocked, including traffic to other tenants.

flowchart LR
  subgraph TA["Namespace: tenant A"]
    A1["Web Pod"] --> A2["API Pod"]
  end
  subgraph TB["Namespace: tenant B"]
    B1["Web Pod"] --> B2["API Pod"]
  end
  A1 -. "blocked by default deny" .-> B2
  B1 -. "blocked by default deny" .-> A2
  ING["Ingress layer"] --> A1
  ING --> B1
  DNS["Cluster DNS"] --- A1
  DNS --- B1
        

Details that trip people up

Stop dangerous workloads at the door, before they ever start.

Why Pod settings matter for isolation

A Pod specification can ask for dangerous powers. It can run as the machine’s administrator, share the node’s network, mount folders from the node’s own disk, or add extra kernel capabilities. A Pod using such settings can read other tenants’ data on the same node, or take over the node. Isolation between namespaces collapses if tenants may use these settings freely.

Pod Security Standards

Kubernetes defines three standard profiles, and a built-in admission feature can enforce them per namespace by reading labels on the namespace.

Three modes per profile

For each namespace you choose a profile and a mode. Enforce rejects Pods that violate the profile. Audit allows them but records the violation. Warn allows them but shows the user a warning. A common rollout is to start with audit and warn to find out what would break, fix workloads, and then turn on enforce.

Going beyond the built-in profiles

The standard profiles are broad. Organisations often need finer rules, such as “images must come from our registry,” “every Pod must have an owner label,” “no Service of type load balancer in this namespace,” or “limits must stay under a certain size.” The cluster supports policy engines and built-in declarative validation rules for this. Policy rules can be attached per namespace or per label, and they run at admission, in the same stage as the security profile checks.

When tenants should not share a machine, or at least not share a kernel.

Why the node is the weak point

All the layers so far work inside the Kubernetes API. But containers from different tenants that land on the same node share that node’s kernel, its disks and its network card. A kernel flaw, a container escape or a resource-hungry neighbour can cross namespace lines at this level. Where the risk is significant, you separate tenants physically or with stronger sandboxes.

Dedicated node pools with taints and labels

You can reserve a group of nodes for a tenant. The nodes get a taint, a marker that repels all Pods except those that carry a matching toleration. They also get a label, and the tenant’s Pods are required to select that label. Together the taint keeps others out and the label keeps the tenant’s Pods in. An admission rule can add the toleration and the selector automatically for every Pod in the tenant’s namespace, so tenants cannot forget or bypass it.

Sandboxed runtimes

Another approach is to keep sharing nodes but harden the boundary between containers. A RuntimeClass lets a Pod choose a different container runtime, such as one that runs each Pod inside a lightweight virtual machine or a user-space kernel. These sandboxes put an extra barrier between the container and the node’s kernel, which reduces the impact of a container escape. They cost some performance and compatibility, so they are usually applied to the least trusted workloads, not to everything.

All tenants share one API server and one database. A single noisy tenant can slow them all.

The shared brain

The API server handles every request from every tenant, and the cluster’s database stores every object. Their capacity is finite. A tenant program with a bug that polls or creates objects in a tight loop can swamp the API server, slowing deployments and controllers for everyone. A tenant that stores huge numbers of objects, or very large ones, can bloat the database and slow all reads and writes.

API priority and fairness

The API server includes a fairness system. Requests are classified into flows, for example by user, group or namespace, and assigned to priority levels. Each level has its own share of the server’s capacity and its own queues. When the server is busy, requests from a heavy flow wait in their own queue instead of pushing out other flows. Platform teams can define rules that give each tenant a flow of its own, so that one tenant’s burst only delays that tenant.

Capping object counts

Object count quotas protect the database. Limits on the number of ConfigMaps, Secrets, Pods, Services, Jobs and claims stop runaway automation from creating millions of small objects. Finished Jobs and their Pods can pile up, so counting limits and automatic clean-up settings help keep the database lean.

Shared extension points

A hard quota is simple but rigid. Here is how platforms add flexibility.

The rigidity of fixed caps

A ResourceQuota is a hard wall. If tenant A is idle and tenant B needs more, B still cannot exceed its own cap, even though the cluster is half empty. Conversely, if every tenant is given a generous cap, the sum exceeds real capacity and the first tenants to claim resources win. Neither extreme is ideal. Many platforms want guaranteed minimums, with the ability to borrow idle capacity from others.

Priorities and preemption

Priority classes let important Pods outrank others. When the cluster is full, a high-priority Pod can cause lower-priority Pods to be evicted to make room. Combined with quotas scoped to a priority class, a platform can say: “each tenant may run a small amount of high-priority work, and any amount of low-priority batch work that can be preempted.” This gives soft guarantees without wasting idle capacity.

Queueing systems with borrowing

For batch and machine learning platforms, a family of queueing tools sits in front of the scheduler. Tenants submit jobs to queues that have a nominal share of resources, and queues may borrow unused share from others within a group, then give it back when owners need it. The queueing layer decides when a whole job is allowed to start, and the ordinary scheduler places its Pods. This provides fairness and good utilisation that static quotas cannot.

Tools that package the layers together so you do not hand-build every tenant.

The problem with hand-built tenants

Each tenant needs a namespace, a quota, a limit range, access bindings, network policies, security labels and node placement rules. Creating these by hand is slow and error-prone, and tenants with more than one namespace multiply the work. Differences creep in, and some tenant ends up without a default-deny policy. Automation and tenancy frameworks reduce this risk.

Hierarchical namespaces

A hierarchy lets one namespace be the parent of others, with policies such as access rules and network rules flowing down from parent to child automatically. A team can then create sub-namespaces for its own projects and environments without involving the platform team each time, while inheriting the team’s guardrails. This is especially useful where one tenant owns many namespaces.

Tenant abstractions

Some projects add a tenant object that groups several namespaces and applies shared quotas, access rules, network rules and policies across them. Instead of one quota per namespace, the tenant has a total budget that its namespaces share. Tenant owners may create their own namespaces within limits, and the framework stamps each with the standard guardrails.

Virtual clusters

A virtual cluster gives each tenant its own API server and its own set of cluster-scoped objects, running as a workload inside the shared host cluster. The tenant sees what looks like a full cluster, where they can install their own definitions and create their own namespaces, while their Pods actually run on the shared nodes, mapped into a host namespace. This restores a lot of tenant freedom and protects the host’s control plane, at the cost of more components and some compatibility questions.

flowchart TD
  H["Shared host cluster"] --> NS1["Tenant A host namespace"]
  H --> NS2["Tenant B host namespace"]
  NS1 --> V1["Virtual control plane for tenant A"]
  NS2 --> V2["Virtual control plane for tenant B"]
  V1 --> P1["Tenant A Pods run on shared nodes"]
  V2 --> P2["Tenant B Pods run on shared nodes"]
        

The same ordered steps, every time, produce a tenant that is safe from its first minute.

Offboarding is part of the blueprint

When a tenant leaves, deleting the namespace removes the objects inside it, but cluster-scoped leftovers remain: volumes with a retain policy, cluster-level bindings, node pool labels and external resources created by the tenant’s workloads. Keep a checklist for offboarding, and make sure data is exported or deleted deliberately, because namespace deletion can be slow and can hang on objects that block removal.

How different kinds of organisations apply the layers in practice.

More tenants means more objects, more policies and more traffic through the same control plane.

What grows with the number of tenants

Each namespace adds objects: quotas, ranges, policies, bindings and service accounts. Each tenant adds workloads, which add Pods, Services and watch connections from controllers and monitoring. Network policies are translated by the network plugin into rules on every node, so many policies increase per-node work. Quota and policy evaluation add a small cost to each request.

The blast radius question

Whatever the performance numbers say, a single shared cluster has a single blast radius. A faulty upgrade, a misconfigured global policy or a control plane outage affects every tenant at once. Many organisations choose several medium clusters, each hosting a group of tenants, as a balance between the efficiency of sharing and the safety of separation.

A realistic list of gaps, so you can close them or accept them knowingly.

Residual risks, even with every layer in place

Protecting the guardrails themselves

All the layers rely on objects that live in or near the tenant namespace: quotas, policies, role bindings and labels. If a tenant can edit or delete them, the protection vanishes. Make sure tenant roles can neither modify nor delete these objects, and use admission rules to protect the security-relevant labels on namespaces.

Audit and detection

Turn on audit logging and keep it long enough for investigations. Alert on attempts to create cluster-scoped objects from tenant identities, on changes to quotas and policies, on creation of privileged Pods that were denied, and on cross-namespace access attempts. Regular scans that compare each tenant namespace against the blueprint will reveal drift early.

Tenants need to see their usage, and operators need to see who is close to a limit.

What to measure per tenant

Chargeback and showback

Because quotas and labels tie usage to a tenant, you can report cost per tenant. Showback shows each tenant what they consume and what it costs. Chargeback actually bills them. Both depend on consistent ownership labels on every namespace and workload, which is another reason to enforce labels at admission. Shared overhead, such as the control plane and monitoring, is usually split by an agreed formula.

Where tenants look when something fails

The same few messages account for most support requests. Learn to decode them.

A path for “my workload is not running”

Habits that keep shared clusters calm and fair.

Patterns that work

Failures that appear again and again in shared clusters.

An honest balance sheet for namespace-based multi-tenancy.

Choosing between sharing and separating

Questions that beginners and experienced engineers keep asking.

Not by itself. It scopes names and is a convenient place to attach access rules, quotas and policies, but with no policies attached, tenants can reach each other’s services and use the whole cluster. Security comes from the layers you add.

A quota caps the total amount of resources and objects in a namespace. A LimitRange sets defaults and minimum and maximum sizes for each individual container, Pod or claim. You normally need both: one to bound the whole, the other to shape the parts.

Because the namespace has a quota on those resources, and the system cannot add up a container with no declared size. Either set sizes on your containers, or ask for a LimitRange that supplies defaults.

No. Quotas are checked when objects are created or changed. Existing Pods keep running. Only new creations that would exceed the lowered cap are refused.

The Deployment object itself was accepted, but the Pods created on its behalf were refused by a quota or policy. The refusal appears as events on the ReplicaSet or namespace, not as an error on the apply.

Yes. Kubernetes networking is open by default. Use network policies, with a default-deny starting point, and a network plugin that enforces them, to block cross-tenant traffic.

No. A quota is a ceiling, not a reservation. If the cluster is full, a tenant within its quota can still have Pods stay pending. Guarantees need capacity planning, priorities, dedicated node pools or queueing systems with nominal shares.

Use the API priority and fairness settings to give heavy tenants their own flows, cap object counts with quotas, scope webhooks and controllers narrowly, and teach tenants efficient access patterns. For strict protection, give the tenant a virtual or separate cluster.

Not with namespaces alone. Add sandboxed runtimes, dedicated nodes, strict egress rules, strong resource caps and tight Pod security profiles, and consider a separate cluster for the highest-risk customers.

A virtual cluster gives each tenant its own API server and cluster-scoped objects, running inside a shared host cluster. Use them when tenants need freedom to install definitions or create namespaces, or when you want to shield the host’s control plane. They do not by themselves isolate the nodes and kernel.

There is no single number, since it depends on how many objects each namespace holds, the size of the control plane and the load. Large clusters run thousands of namespaces, but practical limits come from total object counts, watchers and request rates, so measure your own setup.

Identity and cost labels, Pod security profile labels, a quota and a LimitRange, default-deny network policies with the needed allow rules, namespace-scoped access bindings for the tenant’s groups, locked-down service accounts, and monitoring wiring. Create them from a template and test the result.

Multi-tenancy lets many teams or customers share one Kubernetes cluster to save cost and effort, but a namespace alone is only a naming scope. Isolation appears when you attach layers to it. Quotas cap the totals of CPU, memory, storage and object counts, and LimitRanges set defaults and per-object bounds, with quota checks happening at admission when objects are created. Access rules confine people and programs to their own namespace, network policies close the open network, Pod security profiles and admission policies block dangerous settings, and dedicated nodes or sandboxed runtimes separate tenants at the machine level. Fairness settings and object count caps protect the shared control plane. Frameworks, hierarchies, queues and virtual clusters package or extend these layers for larger or riskier setups.

Return to the office building from the start. The floor number on the door is only a label. The security comes from the electricity cap, the locked doors, the badge rules, the building code and the guards at reception, all set up the same way for every new tenant and checked regularly. Decide honestly how much you trust your tenants, build the layers to match, create each tenant from a tested template, and a shared cluster becomes both economical and safe.