vCluster

A vCluster (virtual cluster) is a lightweight, fully functional Kubernetes cluster that runs inside a namespace of a host Kubernetes cluster, allowing teams to isolate workloads, run multiple virtual clusters in one physical cluster, and speed up development workflows.

History

vCluster was developed by Loft Labs as part of their mission to improve Kubernetes multi-tenancy and developer productivity. It addresses the overhead and inefficiencies of spinning up separate Kubernetes clusters for each user or environment.

Value Proposition

Traditional Kubernetes environments struggle with true multi-tenancy. Creating individual physical clusters for each user or team can be costly and complex to manage. vCluster provides:

• Cost-effective isolation without the need to spin up entire clusters.
• Faster development cycles by provisioning dev/test environments in seconds.
• Enhanced multi-tenancy with better resource sharing and security boundaries.

Key Features

• Runs inside a namespace: Each vCluster is created as a namespace within a host cluster.
• Kubernetes-native API: vClusters offer their own Kubernetes API server, making them feel like real clusters to kubectl and CI/CD tools.
• Custom sync control: Users can decide which resources are synced to the host cluster.
• Full Helm support: vClusters can be installed using Helm, making them easy to manage.

How vCluster Works

A vCluster typically runs its own API server and etcd instance (or an alternative like K3s) inside a namespace of a host Kubernetes cluster. From the outside, it behaves like a full Kubernetes cluster, but it shares the underlying infrastructure and kubelet of the host.

vClusters redirect API calls to their virtual control plane, and selected resources (like Pods) are synced back to the host cluster where they are actually scheduled.

Use Cases

• Isolated dev/test environments: Developers can spin up disposable clusters in seconds.
• CI/CD pipelines: Run e2e tests in isolated environments without provisioning full clusters.
• Multi-tenant SaaS: Host multiple customer environments securely in one physical cluster.
• Education and training: Provide each student or participant with their own vCluster.

How to Use vCluster

1. Install vCluster CLI

You’ll need the vCluster CLI to create and manage virtual clusters:

curl -s https://api.github.com/repos/loft-sh/vcluster/releases/latest | grep "browser_download_url.*linux.*amd64" | cut -d '"' -f 4 | wget -i -
chmod +x vcluster-linux-amd64
mv vcluster-linux-amd64 /usr/local/bin/vcluster

Mac and Windows binaries are also available.

2. Install a vCluster in Your Host Cluster

Using Helm (assuming Helm is installed):

vcluster create my-vcluster -n vcluster-namespace

This will:

• Create a namespace vcluster-namespace.
• Deploy a virtual Kubernetes control plane inside it.
• Configure your kubeconfig to point to the new vCluster.

3. Access and Work with the vCluster

After creation, you can interact with the vCluster like any real Kubernetes cluster:

kubectl config use-context my-vcluster
kubectl get pods -A

You can install apps, create namespaces, and deploy workloads inside the vCluster.

4. Delete the vCluster

When you’re done, clean up with:

vcluster delete my-vcluster -n vcluster-namespace

Challenges

• Networking complexity: Some Kubernetes network plugins may need tuning for full isolation.
• Performance limitations: Though lightweight, heavy workloads still consume real cluster resources.
• Learning curve: Developers unfamiliar with Kubernetes might need some ramp-up time.

Similar Concepts

• Namespace-based multi-tenancy: Lighter but lacks true isolation.
• Kubernetes-in-Kubernetes (KinD, Minikube): Local development environments not optimized for multi-user cloud use.
• KubeVirt: Runs full VMs inside Kubernetes, suited for legacy workloads.

References

• Loft Labs GitHub
• Kubernetes Multi-Tenancy Working Group