vcluster Documentation

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

What is vCluster? Copy Chapter

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 and Kubernetes AI Conformant — 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 Copy Chapter

# 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

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

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

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

🎮 Try in the Browser Copy Section

🎁 vCluster Free Tier Copy Section

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 →

🆕 What's New Copy Chapter

👉 Full Changelog

🎯 Use Cases Copy Chapter

🏗️ Architectures Copy Chapter

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 Copy Section

👉 Full Architecture Guide

Minimal Configuration Copy Section

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

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.

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

🔹 Private Nodes ^v0.27+ — 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.

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

🔹 vCluster Standalone ^v0.29+ — 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.

controlPlane:
  standalone:
    enabled: true
    joinNode:
      enabled: true
privateNodes:
  enabled: true

⚡ Auto Nodes ^v0.28+ — 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.

autoNodes:
  enabled: true
  nodeProvider: 
privateNodes:
  enabled: true

✨ Key Features Copy Chapter

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 Copy Chapter

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.

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 Copy Chapter

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

📚 Learn More Copy Chapter

🎤 Conference Talks

🎬 Community Voice

👉 YouTube Channel • Blog

🤝 Contributing Copy Chapter

We welcome contributions! Check out our Contributing Guide to get started.

🤝 Connect with us Copy Chapter

• 💬 Join our Slack community — 5K+ engineers
• 💼 Follow on LinkedIn — 28K+
• 🐦 Follow on X — 3.7K+
• 📺 Watch on YouTube
• 📝 Read the Blog
• 📅 Book a consultation

📜 License Copy Chapter

vCluster is licensed under the Apache 2.0 License.

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

vCluster development links

• vCluster repo
• vCluster open issues
• vCluster releases and release notes

vCluster resources Copy Chapter

• Website
• Documentation
• Blog
• Twitter
• Slack

Contribute to the docs Copy Chapter

Contributions from all users are encouraged.

Develop locally Copy Section

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 Copy Section

• Create a docs issue.
• Open a pull request.

  • Use the GitHub web UI
    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
    for specific guides.

The docs site uses Docusaurus. See
Contribute to the vCluster docs 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 Copy Section

npm run docusaurus docs:version:vcluster 0.22.0

Generate new Platform version Copy Section

npm run docusaurus docs:version:platform 4.3.0

Generate vCluster partials Copy Section

go run hack/vcluster/partials/main.go

Generate platform partials Copy Section

go run hack/platform/partials/main.go

Generate CLI documentation Copy Section

go run hack/vcluster-cli/main.go

See the CLI generator README for options.

Wrap glossary terms Copy Section

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

# 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