Documentation

KubeCell overview

KubeCell gives every developer an isolated Kubernetes cluster — a VirtualCluster — on shared physical hosts. A single management cluster holds the desired state; each Cell host runs the workloads. Developers get a standard, kubectl-compatible K3s API with hard CPU, memory, and GPU quotas, persistent storage, and automatically published kubeconfigs.

What KubeCell is

• A small operator with exactly four CRDs: Cell, VirtualNodeClass, VirtualClusterPlan, and VirtualCluster.
• A composition layer over upstream projects — K3s, K3k, TopoLVM, Traefik, and Open Cluster Management (OCM) — integrated through public APIs only.
• A quota and isolation system: every child cluster maps to a host namespace with ResourceQuota, LimitRange, NetworkPolicy, and admission rules that reject privileged workloads and hostPath volumes.
• An inventory and feasibility system: Cells report live capacity, and Plans tell you whether a request can be satisfied before anything is created.

What KubeCell is not

• Not a second scheduler, device allocator, kubelet, CNI, CSI, or Device Plugin. Those stay upstream.
• Not a namespace-with-labels product. A child cluster has its own API server, control plane, and data volume.
• Not a strong-adversary multi-tenancy boundary. Developer credentials are child-cluster admin kubeconfigs, which is a deliberate trusted-network trade-off.
• Not a horizontal autoscaler for child clusters: each child exposes exactly one logical node named kubelet. You scale by switching quota tiers.

The mental model in four objects

Architecture at a glance

Three layers, one direction of control. The management plane declares intent; the host executes it; the child cluster is the product.

The controller never connects to a host directly. It applies two declarative work objects per cluster through the hub and reads host state back the same way. See technical principles for the full control flow.

Design principles worth remembering

• Intent-only specs. Human-authored manifests declare which Cell and which quota tier. Versions, ports, reservations, and security baselines are platform constants and never enter the CRDs.
• One safe value means no field. If a setting has exactly one safe value, exposing it would only create drift, so it stays out of the API.
• Observed state beats declared state. Allocatable capacity reported by the host is the source of truth; declarations are upper bounds and never inflate inventory.
• Reconciliation is idempotent. Failed steps are retried by re-rendering from the resolution snapshot, never by patching host state in place.
• Built on upstream components. K3s, K3k, TopoLVM, and OCM are used unmodified through their public APIs, so upstream fixes and behavior apply directly.

Who should read what

Project status

The API shape, controllers, installer, and the first end-to-end loop are implemented. The feature matrix (PVC, networking, hostPath rejection, interaction, cascading deletion, accelerator allocation, Ingress) and release hardening are in progress. Track the work in TODOS.md and report bugs through GitHub issues.