# 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](https://loft.sh/) 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:

```none
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):

```none
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:

```none
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:

```none
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](https://github.com/loft-sh/vcluster)
- [Kubernetes Multi-Tenancy Working Group](https://github.com/kubernetes-sigs/multi-tenancy)