## 1. Project Overview & Quickstart (loft-sh/vcluster)

---

## What is vCluster?

**vCluster** creates **Tenant Clusters** — fully isolated Kubernetes environments that run on top of a Control Plane Cluster or standalone on dedicated infrastructure or bare metal. Each tenant gets its own API server, CRDs, and RBAC, with a cluster experience indistinguishable from a dedicated Kubernetes cluster.

Built for production. Trusted in production. **40M+ Tenant Clusters deployed** by teams at Adobe, CoreWeave, NVIDIA, Lintasarta, Atlan, Deloitte, and hundreds of AI clouds, AI factories, and Fortune 500 platform organizations.

**[CNCF Certified Kubernetes — Distribution](https://www.cncf.io/training/certification/software-conformance/)** and **[Kubernetes AI Conformant](https://github.com/cncf/k8s-ai-conformance/tree/main/v1.35/vcluster-private-nodes)** — every Tenant Cluster is upstream Kubernetes with no vendor lock‑in, validated for portable AI/ML workloads (training, inference, agentic).

> **The public-cloud experience, on your own infrastructure.** Give every team the Kubernetes they need — with strict isolation, hardware-aware scheduling, and zero tenant sprawl — whether you run one region or 100K GPUs.



---

## 🚀 Quick Start

```bash
# Install vCluster CLI
brew install loft-sh/tap/vcluster

# Create a Tenant Cluster
vcluster create my-vcluster --namespace team-x

# Use kubectl as usual — you're now in your Tenant Cluster
kubectl get namespaces
```

**Prerequisites:** A running Kubernetes cluster and `kubectl` configured.

👉 **[Full Quickstart Guide](https://www.vcluster.com/docs/get-started)**

### 🐳 Run Locally with Docker — [vind](https://github.com/loft-sh/vind)

No Kubernetes cluster? Run vCluster directly on Docker with **vind** (vCluster in Docker) — like `kind`, but with the full vCluster feature set (UI, sleep/resume, LoadBalancer, image cache):

```bash
vcluster create my-vcluster --driver docker
kubectl get namespaces
```

### 🎮 Try in the Browser

[](https://killercoda.com/vcluster)

### 🎁 vCluster Free Tier

Real usage, not a gated demo. Unlimited Tenant Clusters up to 64 CPUs / 32 GPUs, plus the full vCluster Platform UI — for free. **[Get Started Free →](https://www.vcluster.com/free)**

---

## 🆕 What's New

| Version | Feature | Description |
|---------|---------|-------------|
| **v0.34** | [Multi-Region Platform & Standalone Snapshots](https://www.vcluster.com/releases/changelog/vcluster-platform-v49-vcluster-v034-multi-region-platform-snapshot-support) | Active/active vCluster Platform across regions (Route 53 + RDS), Standalone snapshots (S3 / OCI / local), first-class template parameters |
| **v0.33** | [Enterprise Reliability & Storage](https://github.com/loft-sh/vcluster/releases/tag/v0.33.0) | Automatic leaf-cert regeneration, Azure Blob snapshot destinations, workload-level sleep annotations |
| **v0.32** | [Docker Driver & DRA](https://github.com/loft-sh/vcluster/releases/tag/v0.32.0) | Run vCluster on Docker, Dynamic Resource Allocation (DRA) for GPU workloads, in-place pod resizing |
| **v0.31** | [Snapshots & Cross-Cluster APIs](https://github.com/loft-sh/vcluster/releases/tag/v0.31.0) | Expanded snapshot/restore lifecycle, PDBs for Tenant Cluster control planes, cross-cluster resource proxying |
| **v0.30** | [vCluster VPN & Netris Integration](https://www.vcluster.com/releases/en/changelog/platform-v45-and-vcluster-v030-secure-cloud-bursting-on-prem) | Tailscale-powered overlay networking and automated hardware isolation via Netris |
| **v0.27–v0.29** | [Architecture Foundations](https://www.vcluster.com/docs/vcluster/introduction/architecture/) | [Private Nodes](https://www.vcluster.com/docs/vcluster/deploy/worker-nodes/private-nodes) (v0.27, CNI/CSI isolation), [Auto Nodes](https://www.vcluster.com/docs/vcluster/deploy/worker-nodes/private-nodes/auto-nodes/) (v0.28, Karpenter autoscaling), [Standalone Mode](https://www.vcluster.com/docs/vcluster/deploy/control-plane/binary/) (v0.29, no Control Plane Cluster — dedicated infrastructure or bare metal) |

👉 **[Full Changelog](https://www.vcluster.com/releases)**

---

## 🎯 Use Cases

| Use Case | Description | Learn More |
|----------|-------------|------------|
| **AI Factory** | Run AI on-prem where your data and GPUs live. Give every team the GPU access they need without multiplying infrastructure. | [View →](https://www.vcluster.com/solutions/ai-factory) |
| **AI Cloud Providers** | Launch a hyperscaler-like Kubernetes experience for your GPU customers. Isolated, production-grade, in minutes. | [View →](https://www.vcluster.com/solutions/gpu-cloud-providers) |
| **Internal GPU Platform** | Maximize GPU utilization without sacrificing isolation. Self-service Kubernetes for AI/ML teams. | [View →](https://www.vcluster.com/solutions/internal-gpu-platform) |
| **Bare Metal Kubernetes** | Run production Kubernetes on bare metal with zero VMs. Isolation without expensive virtualization overhead. | [View →](https://www.vcluster.com/solutions/bare-metal-kubernetes) |
| **Software Vendors** | Ship Kubernetes-native products. Each customer gets their own isolated Tenant Cluster. | [View →](https://www.vcluster.com/solutions/software-vendors) |
| **Environments & Cost Savings** | Consolidate clusters, pause idle workloads with sleep mode, and cut Kubernetes cost at scale. | [View →](https://www.vcluster.com/cost-savings) |

---

## 🏗️ Architectures

vCluster supports multiple deployment architectures. Each builds on the previous, offering progressively stronger isolation — from dense shared infrastructure to fully standalone deployments on dedicated infrastructure or bare metal.

### Architecture Comparison

| | **Shared Nodes** | **Dedicated Nodes** | **Private Nodes** | **Standalone** |
|---|:---:|:---:|:---:|:---:|
| **Control Plane Cluster** | Required | Required | Required | Not Required |
| **Node Isolation** | ❌ | ✅ | ✅ | ✅ |
| **CNI/CSI Isolation** | ❌ | ❌ | ✅ | ✅ |
| **Bare Metal Ready** | — | — | ✅ | ✅ |
| **Best For** | Dev/test, density | Production tenants | Compliance, GPU | AI factories, edge |

👉 **[Full Architecture Guide](https://www.vcluster.com/docs/vcluster/introduction/architecture/)**

### Minimal Configuration


🔹 Shared Nodes — Maximum density, minimum cost
Tenant Clusters share the Control Plane Cluster's nodes. Workloads run as regular pods in a namespace.


```yaml
sync:
  fromHost:
    nodes:
      enabled: false  # Uses pseudo nodes
```


🔹 Dedicated Nodes — Isolated compute on labeled node pools
Tenant Clusters get their own set of labeled nodes on the Control Plane Cluster. Workloads are isolated but still managed by the Control Plane Cluster.


```yaml
sync:
  fromHost:
    nodes:
      enabled: true
      selector:
        labels:
          tenant: my-tenant
```


🔹 Private Nodes <sup>v0.27+</sup> — Full CNI/CSI isolation
External nodes join the Tenant Cluster directly with their own CNI, CSI, and networking stack. Complete workload isolation from the Control Plane Cluster.


```yaml
privateNodes:
  enabled: true
controlPlane:
  service:
    spec:
      type: NodePort
```


🔹 vCluster Standalone <sup>v0.29+</sup> — No Control Plane Cluster required
Run vCluster without any Control Plane Cluster. Deploy the Virtual Control Plane directly on bare metal or VMs. The highest level of isolation — vCluster becomes the cluster.


```yaml
controlPlane:
  standalone:
    enabled: true
    joinNode:
      enabled: true
privateNodes:
  enabled: true
```


⚡ Auto Nodes <sup>v0.28+</sup> — Karpenter-powered dynamic autoscaling
Automatically provision and deprovision private nodes based on workload demand. Works across public cloud, private cloud, hybrid, and bare metal environments.


```yaml
autoNodes:
  enabled: true
  nodeProvider: 
privateNodes:
  enabled: true
```


---

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| **🎛️ Isolated Virtual Control Plane** | Each Tenant Cluster gets its own API server, controller manager, and data store — complete Kubernetes API isolation |
| **🔗 Shared Platform Stack** *(Shared / Dedicated Nodes)* | Leverage the Control Plane Cluster's CNI, CSI, ingress, and other infrastructure — no duplicate platform components |
| **🔒 Strong Tenant Isolation** | Tenants get admin access inside their Tenant Cluster while having minimal permissions on the Control Plane Cluster |
| **🔄 Resource Syncing** *(Shared / Dedicated Nodes)* | Bidirectional sync of any Kubernetes resource — pods, services, secrets, configmaps, CRDs, and more |
| **💤 Sleep Mode** | Pause inactive Tenant Clusters to save resources. Instant wake when needed |
| **🖥️ Standalone Deployment** | Run without a Control Plane Cluster on dedicated infrastructure or bare metal — purpose-built for AI factories and on-prem GPU fleets |
| **🧩 Integrations** | Native support for cert-manager, external-secrets, KubeVirt, Istio, and metrics-server (host-side integrations apply in Shared / Dedicated Nodes modes) |
| **📊 High Availability** | Multiple replicas with leader election. Embedded etcd or external databases (PostgreSQL, MySQL, RDS) |

> *Shared Platform Stack, Resource Syncing, and host-cluster integrations apply only in **Shared** and **Dedicated Nodes** modes, where the Tenant Cluster shares the Control Plane Cluster's CNI, CSI, and platform stack. **Private Nodes** and **Standalone** deployments bring their own CNI, CSI, and platform components.*

---

## 🌐 The vCluster Platform

vCluster is the foundation of a broader platform for running production Kubernetes and AI infrastructure on your own hardware — from a single rack to 100K-GPU supercomputers.

| Product | What it does |
|---------|--------------|
| **[vCluster](https://www.vcluster.com)** | Tenant Clusters — Virtual Control Planes with API, data, and (optionally) network isolation |
| **[vNode](https://www.vnode.com/)** | Runtime-level isolation. Kernel-enforced boundaries (seccomp, cgroups, namespaces, AppArmor) without VM overhead |
| **[vMetal](https://www.vmetal.ai/)** | Zero-touch bare metal provisioning for GPU fleets. Turns GPU racks into a cloud platform |
| **[Netris](https://www.vcluster.com/solutions/netris-kubernetes-network-automation)** *(integration)* | Hardware-enforced network isolation via programmatic VLANs, VRFs, and ACLs |

Together these provide a complete foundation for AI factories — certified Kubernetes stacks, isolated Tenant Clusters, runtime workload sandboxing, and GPU infrastructure operations — the same pattern used to run production AI on hundreds of AI clouds and Fortune 500 on-prem platforms.

---

## 🏢 Trusted By



| [**Atlan**](https://www.vcluster.com/case-studies/atlan)100 → 1 clusters | [**Aussie Broadband**](https://www.vcluster.com/case-studies/aussie-broadband)99% faster provisioning | [**CoreWeave**](https://www.vcluster.com/case-studies/coreweave)GPU cloud at scale |
| --- | --- | --- |
| [**Lintasarta**](https://www.vcluster.com/case-studies/lintasarta)170+ Tenant Clusters in prod | [**Fortune 500 Insurance**](https://www.vcluster.com/case-studies/fortune-500-insurance-company)70% reduction in Kubernetes cost | [**Scanmetrix**](https://www.vcluster.com/case-studies/scanmetrix)99% faster deployments |
| [**Deloitte**](https://www.vcluster.com/case-studies/deloitte)Enterprise K8s platform | [**Ada**](https://www.vcluster.com/case-studies/ada-cx)10x Developer Productivity | [**Trade Connectors**](https://www.vcluster.com/case-studies/trade-connectors)50% reduction in K8s ops cost |



**Also used by:** NVIDIA, ABBYY, Precisely, Shipwire, and many more — with 50+ GPU clouds and Fortune 500s running vCluster in production.

👉 **[View All Case Studies](https://www.vcluster.com/case-studies)**

---

## 📚 Learn More


**🎤 Conference Talks**

| Event | Speaker | Title | Link |
|-------|---------|-------|------|
| KubeCon NA 2025 (Keynote) | Lukas Gentele | Autoscaling GPU Clusters Anywhere — Hyperscalers, Neoclouds & Baremetal | [Watch](https://www.youtube.com/watch?v=LGOELO-ah30) |
| Platform Engineering Day NA 2025 (Keynote) | Saiyam Pathak | AI-Ready Platforms: Scaling Teams Without Scaling Costs | [Watch](https://www.youtube.com/watch?v=sn5kIBS9Xfg) |
| Rejekts NA 2025 | Hrittik Roy, Saiyam Pathak | Beyond the Default Scheduler: Navigating GPU MultiTenancy in AI Era | [Watch](https://www.youtube.com/watch?v=tROp-nmNYxo) |
| KubeCon EU 2025 | Paco Xu, Saiyam Pathak | A Huge Cluster or Multi-Clusters? Identifying the Bottleneck | [Watch](https://www.youtube.com/watch?v=6l5zCt5QsdY) |
| HashiConf 2025 | Scott McAllister | GPU sharing done right: Secrets, security, and scaling with Vault and vCluster | [Watch](https://www.youtube.com/watch?v=zWx17azSqyU) |
| FOSDEM 2025 | Hrittik Roy, Saiyam Pathak | Accelerating CI Pipelines: Rapid Kubernetes Testing with vCluster | [Watch](https://archive.fosdem.org/2025/schedule/event/fosdem-2025-5569-accelerating-ci-pipelines-rapid-kubernetes-testing-with-vcluster/) |
| KubeCon India 2024 (Keynote) | Saiyam Pathak | From Outage To Observability: Lessons From a Kubernetes Meltdown | [Watch](https://www.youtube.com/watch?v=7JCZ688cWpY) |
| CNCF Book Club 2024 | Marc Boorshtein | Kubernetes - An Enterprise Guide (vCluster) | [Watch](https://www.youtube.com/watch?v=8vwnDlkkuJM) |
| KCD NYC 2024 | Lukas Gentele | Tenant Autonomy & Isolation In Multi-Tenant Kubernetes Clusters | [Watch](https://www.youtube.com/watch?v=AKJVLbXsUmE) |
| KubeCon EU 2023 | Ilia Medvedev, Kostis Kapelonis | How We Securely Scaled Multi-Tenancy with VCluster, Crossplane, and Argo CD | [Watch](https://www.youtube.com/watch?v=hFiHU6W4_z0) |
| KubeCon NA 2022 | Joseph Sandoval, Dan Garfield | How Adobe Planned For Scale With Argo CD, Cluster API, And VCluster | [Watch](https://www.youtube.com/watch?v=p8BluR5WT5w) |
| KubeCon NA 2022 | Whitney Lee, Mauricio Salatino | What a RUSH! Let's Deploy Straight to Production! | [Watch](https://www.youtube.com/watch?v=eJG7uIU9NpM) |
| TGI Kubernetes 2022 | TGI | TGI Kubernetes 188: vCluster | [Watch](https://www.youtube.com/watch?v=EaoxUDGpARE) |
| Mirantis Tech Talks 2022 | Mirantis | Multi-tenancy & Isolation using Virtual Clusters (vCluster) in K8s | [Watch](https://www.youtube.com/watch?v=CoqRXdJbCwY) |
| Solo Webinar 2022 | Rich Burroughs, Fabian Keller | Speed your Istio development environment with vCluster | [Watch](https://www.youtube.com/watch?v=b7OkYjvLf4Y) |
| KubeCon NA 2021 | Lukas Gentele | Beyond Namespaces: Virtual Clusters are the Future of Multi-Tenancy | [Watch](https://www.youtube.com/watch?v=QddWNqchD9I) |




**🎬 Community Voice**

| Channel | Speaker | Title | Link |
|---------|---------|-------|------|
| TeKanAid 2024 | TeKanAid | Getting Started with vCluster: Build Your IDP with Backstage, Crossplane, and ArgoCD | [Watch](https://www.youtube.com/watch?v=nIxl2PcEs-0) |
| Rawkode 2021 | David McKay, Lukas Gentele | Hands on Introduction to vCluster | [Watch](https://www.youtube.com/watch?v=IMdMvn2_LeI) |
| Kubesimplify 2021 | Saiyam Pathak, Lukas Gentele | Let's Learn vCluster | [Watch](https://www.youtube.com/watch?v=I4mztvnRCjs) |
| TechWorld with Nana 2021 | Nana | Build your Self-Service Kubernetes Platform with Virtual Clusters | [Watch](https://www.youtube.com/watch?v=tt7hope6zU0) |
| DevOps Toolkit 2021 | Viktor Farcic | How To Create Virtual Kubernetes Clusters | [Watch](https://www.youtube.com/watch?v=JqBjpvp268Y) |



👉 **[YouTube Channel](https://www.youtube.com/@vcluster)** • **[Blog](https://loft.sh/blog)**

---

## 🤝 Contributing

We welcome contributions! Check out our **[Contributing Guide](https://github.com/loft-sh/vcluster/blob/main/CONTRIBUTING.md)** to get started.

---

## 🤝 Connect with us

- 💬 Join our [Slack community](https://slack.loft.sh/) — 5K+ engineers
- 💼 Follow on [LinkedIn](https://www.linkedin.com/company/vcluster) — 28K+
- 🐦 Follow on [X](https://x.com/vcluster) — 3.7K+
- 📺 Watch on [YouTube](https://www.youtube.com/@vcluster)
- 📝 Read the [Blog](https://loft.sh/blog)
- 📅 Book a [consultation](https://start-chat.com/slack/Loft-Labs/NnQl1M)

---

## 📜 License

vCluster is licensed under the **[Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0)**.

---

## 2. Official Technical Reference & Guides (loft-sh/vcluster-docs)

# vCluster development links

- vCluster [repo](https://github.com/loft-sh/vcluster)
- vCluster [open issues](https://github.com/loft-sh/vcluster/issues)
- vCluster [releases and release notes](https://github.com/loft-sh/vcluster/releases)

## vCluster resources

- [Website](https://www.vcluster.com)
- [Documentation](https://www.vcluster.com/docs/)
- [Blog](https://loft.sh/blog)
- [Twitter](https://twitter.com/loft_sh)
- [Slack](https://slack.loft.sh/)

## Contribute to the docs

Contributions from all users are encouraged.

### Develop locally

1. Run `npm install`

    This will initially install all necessary dependencies.

2. Run `npm run start`

    This will continuously watch changes, build a development version and serve it locally.

### Other ways to contribute

- [Create a docs issue](https://github.com/loft-sh/vcluster-docs/issues).
- Open a pull request.
  - [Use the GitHub web UI](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui)
    to update a single page.
  - To update several pages or add new pages:
    - Fork the repo.
    - Clone your fork.
    - Ceate a local working branch.
    - Commit your changes.
    - Push your changes.
    - Create a pull request.

     See the GitHub [Pull requests documentation](https://docs.github.com/en/pull-requests)
     for specific guides.

The docs site uses Docusaurus. See
[Contribute to the vCluster docs](./CONTRIBUTING.md) for how to build the site locally.

Content locations:

- vcluster: vCluster content
- platform: vCluster Platform content

Shared content uses two folder conventions (goal — not yet fully enforced):

- `_partials/`: intended for auto-generated content. Do not hand-edit generated files — changes will be overwritten on the next generation run.
- `_fragments/`: manually written content shared across multiple pages. Safe to edit directly.

In practice, most `_partials/` content (e.g. all of `platform/_partials/`) is hand-maintained and safe to edit. The directories that are actually auto-generated are:

- `vcluster/_partials/config/` — vCluster config reference, generated by `hack/vcluster/partials/main.go`
- `platform/api/_partials/resources/` — Platform API reference, generated by `hack/platform/partials/main.go`
- `vcluster_versioned_docs/version-X.Y.Z/cli/` — CLI command docs, generated by `hack/vcluster-cli/main.go`

When in doubt, check `git log` on the file before editing.

### Generate new vCluster version

```bash
npm run docusaurus docs:version:vcluster 0.22.0
```

### Generate new Platform version

```bash
npm run docusaurus docs:version:platform 4.3.0
```

### Generate vCluster partials

```bash
go run hack/vcluster/partials/main.go
```

### Generate platform partials

```bash
go run hack/platform/partials/main.go
```

### Generate CLI documentation

```bash
go run hack/vcluster-cli/main.go
```

See the [CLI generator README](hack/vcluster-cli/README.md) for options.

### Wrap glossary terms

To automatically wrap glossary terms in MDX files with `<GlossaryTerm>` components:

```bash
# Wrap terms in a single file
npm run wrap-glossary vcluster/deploy/basics.mdx

# Wrap terms in all files in a directory (recursive)
npm run wrap-glossary vcluster/deploy/

# Or use the script directly
node scripts/wrap-glossary-terms.js platform/understand/
```

The script will:

- Only wrap terms that exist in `src/data/glossary.yaml`
- Only wrap the first occurrence of each term in a document
- Respect the glossary type setting (vcluster, platform, or both)
- Skip terms in front matter, code blocks, links, and HTML/JSX tags
- Preserve the original case of matched terms