Architecture: Control Planes Inside Control Planes

The Components of a vCluster

A virtual cluster is a Kubernetes control plane packaged as a lightweight workload running inside the host cluster. When you create a vCluster, the following components are deployed into a single namespace on the host:

1. Virtual API Server
By default, vCluster uses k3s (a lightweight Kubernetes distribution) as its virtual API server. k3s is chosen because it bundles the API server and controller manager into a single binary with minimal overhead. This is the endpoint your tenant developers point their kubectl at.

2. Virtual Data Store
Instead of the full etcd that production clusters use, vCluster defaults to SQLite embedded inside the k3s process. SQLite is sufficient for storing the virtual cluster's state because the actual workload state lives in the host cluster. For larger or more critical virtual clusters, you can configure etcd or PostgreSQL as the backing store.

3. The Syncer
This is the most important component — covered in detail in the next section.

What the Tenant Sees

The tenant receives a kubeconfig file pointing to the virtual API server. From their perspective, listing namespaces shows a normal-looking cluster (default, kube-system, and their own namespaces), and checking their own permissions confirms they hold cluster-admin — entirely inside the virtual cluster.

They can create Namespaces, install CRDs, deploy operators, and configure RBAC — all without any platform team approval. None of these actions touch the host cluster's API server directly.

What the Virtual Cluster Does NOT Have

Critically, the virtual cluster has no worker nodes of its own. It borrows the worker nodes from the host cluster. The virtual API server will show nodes (synced from the host), but those nodes are shared physical infrastructure. This is the key architectural trade-off: control plane isolation is complete, but compute isolation is not.