How KubeZoo Enables Lightweight Multi‑Tenant Kubernetes Clusters

Kubernetes Multi‑Tenant Models

Kubernetes has become the operating system of the cloud era, and the community defines three multi‑tenant models: Namespaces as a Service , where multiple tenants share a cluster but are confined to separate namespaces; and Clusters as a Service and Control‑planes as a Service , which give each tenant an independent master and full control‑plane isolation.

Namespaces as a Service – tenants share a cluster, can only use namespace‑scoped resources, and have limited API compatibility.

Clusters as a Service / Control‑planes as a Service – each tenant gets a dedicated master (via Cluster API or Virtual Cluster), providing full isolation but incurring high resource and operational costs.

Why a New Lightweight Solution Is Needed

The existing models have drawbacks: namespace‑as‑a‑service cannot use cluster‑scope resources such as CRDs, requiring admin coordination; full control‑plane isolation adds significant overhead and reduces resource efficiency; and many scenarios involve a large number of small tenants that need instant, low‑cost cluster access.

Lightweight Multi‑Tenant Solution KubeZoo

KubeZoo is a gateway service deployed in front of the API Server. It intercepts all tenant API requests, injects tenant‑specific metadata, forwards the request to the backend API Server, and rewrites the response for the tenant. This design provides a per‑tenant view of a dedicated Kubernetes cluster while sharing a single control plane.

Key Features of KubeZoo

Strong tenant isolation : each request is mapped to a distinct namespace or cluster‑scope object, ensuring no interference between tenants.

High efficiency : adding a new tenant only creates a Tenant object; no new control‑plane is needed, enabling second‑level cluster creation.

Lightweight resource usage : all tenants share a single backend control plane, achieving high resource utilization and low operational cost.

Technical Details

Tenant Management

KubeZoo runs as a specialized API Server with its own metadata store (typically etcd). When an administrator creates a Tenant object, a TenantController issues a certificate containing the tenant ID and generates a Kubeconfig stored in the object's annotation. The controller also creates a namespace, Role, and RoleBinding for the tenant.

Tenant Request Conversion

KubeZoo distinguishes between admin and tenant requests. For tenant requests it validates the certificate, extracts the tenant ID, and uses the Tenant RestStorage to rewrite the request before forwarding it to the backend API Server. Responses are similarly processed before returning to the tenant.

API Object Conversion

Resources are divided into namespace‑level and cluster‑level objects. Namespace‑level objects have their namespace rewritten; cluster‑level objects have their names rewritten to avoid naming conflicts. KubeZoo also supports custom CRDs, isolating tenant‑specific CRDs while allowing shared system‑level CRDs with controlled access.

Tenant Request Fairness

KubeZoo adopts the API Server’s priority‑and‑fairness mechanism: each tenant gets a FlowSchema and a corresponding PriorityLevel, ensuring that no single tenant can monopolize gateway or cluster resources.

Tenant Network Isolation (VPC)

Two scenarios are considered: (1) tenants from the same organization can share a flat network; (2) in public‑cloud or high‑security contexts, each tenant receives a dedicated VPC and subnet, with pods synchronized via Virtual Kubelet, ensuring inter‑tenant network isolation.

Summary

KubeZoo is a protocol‑conversion based Kubernetes multi‑tenant gateway. Compared with existing solutions, it is lightweight, offers near‑instant tenant cluster creation, and provides strong isolation while maintaining high resource utilization and low operational cost, making it ideal for environments with massive small tenants.