Quickstart Guide

Overview

This quickstart guide will take you from zero to a working virtual cluster in less than 5 minutes. You’ll install the vCluster CLI, create your first virtual cluster, connect to it, deploy a test workload, and clean up.

Prerequisites: You need a running Kubernetes cluster (v1.18+) with kubectl configured. Don’t have one? Try Minikube, Kind, or Docker Desktop.

Try Without Installing

No Kubernetes cluster available? Try vCluster instantly in your browser:

Try on Killercoda

Launch an interactive vCluster tutorial in your browser—no installation required

Step-by-Step Guide

Install the vCluster CLI

Install the vCluster CLI using your preferred package manager.

Homebrew (macOS/Linux)
Direct Download (Linux/macOS)
Windows

brew install loft-sh/tap/vcluster

# Download the latest release
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-$(uname -s)-$(uname -m)"

# Make it executable
chmod +x vcluster

# Move to your PATH
sudo mv vcluster /usr/local/bin/vcluster

Download the latest Windows release from GitHub Releases and add it to your PATH.Or use PowerShell:

# Download for Windows
md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12';
Invoke-WebRequest -UseBasicParsing ((Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/latest" -UseBasicParsing).Content -replace "(?ms).*<a href=`"([^`"]*vcluster-windows-amd64.exe)`".*","https://github.com`$1") -o $Env:APPDATA\vcluster\vcluster.exe;
$env:Path += ";"+$Env:APPDATA+"\vcluster";
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);

Verify the installation:

vcluster --version

For more installation methods, see the Installation Guide.

Verify Host Cluster Access

Ensure kubectl is configured and can access your Kubernetes cluster:

kubectl get nodes

You should see your cluster nodes. If not, configure kubectl to connect to your cluster first.

Example Output

NAME                 STATUS   ROLES           AGE   VERSION
kind-control-plane   Ready    control-plane   5m    v1.29.2

Create Your First Virtual Cluster

Create a virtual cluster named my-vcluster in the team-x namespace:

vcluster create my-vcluster --namespace team-x

The --namespace flag is optional. If omitted, vCluster creates a namespace named vcluster-{vcluster-name}.

What happens during creation:

vCluster creates the namespace if it doesn’t exist
Deploys the vCluster control plane via Helm
Waits for the virtual cluster to become ready
Automatically connects your kubectl to the new virtual cluster

Expected Output

info   Creating namespace team-x
info   Installing vCluster my-vcluster in namespace team-x with helm...

done ✓ Successfully created virtual cluster my-vcluster in namespace team-x
- Use 'vcluster connect my-vcluster --namespace team-x' to access the virtual cluster
- Use 'vcluster connect my-vcluster --namespace team-x -- kubectl get ns' to run a command directly

info   Switched active kube context to vcluster_my-vcluster_team-x_kind-kind

Troubleshooting: Creation Stuck or Fails

If the virtual cluster creation hangs or fails:Check pod status:

kubectl get pods -n team-x

View logs:

kubectl logs -n team-x -l app=vcluster -c syncer

Common issues:

Insufficient resources: Ensure your cluster has enough CPU/memory
Image pull errors: Check your internet connection and container registry access
RBAC issues: Verify you have permissions to create resources in the namespace

Explore Your Virtual Cluster

Your kubectl context is now pointing to the virtual cluster. Let’s explore it:

# List namespaces in the virtual cluster
kubectl get namespaces

Expected Output

NAME              STATUS   AGE
default           Active   1m
kube-system       Active   1m
kube-public       Active   1m
kube-node-lease   Active   1m

Notice that the virtual cluster has its own set of namespaces, completely isolated from the host cluster.

# View nodes (these are synced from the host or pseudo nodes)
kubectl get nodes

By default, vCluster uses “pseudo nodes” - virtual representations that don’t sync from the host. You can enable real node syncing in the configuration.

Deploy a Test Workload

Let’s deploy a simple nginx application to verify everything works:

# Create a deployment
kubectl create deployment nginx --image=nginx:latest

# Expose it as a service
kubectl expose deployment nginx --port=80 --target-port=80

# Check the deployment
kubectl get deployments
kubectl get pods
kubectl get services

Expected Output

# Deployments
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
nginx   1/1     1            1           10s

# Pods
NAME                     READY   STATUS    RESTARTS   AGE
nginx-7854ff8877-k9xjl   1/1     Running   0          10s

# Services
NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
kubernetes   ClusterIP   10.96.0.1       <none>        443/TCP   5m
nginx        ClusterIP   10.96.120.234   <none>        80/TCP    5s

These resources exist in your virtual cluster. Behind the scenes, the actual nginx pod runs on the host cluster’s nodes, but it’s completely managed through the virtual cluster’s API.

Want to see the synced resources on the host? Disconnect from the virtual cluster and check:

vcluster disconnect
kubectl get pods -n team-x

You’ll see the synced nginx pod with a modified name.

Test Cluster-Scoped Resources

One of vCluster’s key benefits is support for cluster-scoped resources. Let’s create a custom namespace:

# Create a namespace in the virtual cluster
kubectl create namespace my-app

# List namespaces
kubectl get namespaces

You now have a namespace inside your virtual cluster—something you couldn’t do with traditional namespace-based multi-tenancy.

# Deploy to your custom namespace
kubectl create deployment hello --image=nginx -n my-app
kubectl get pods -n my-app

Understand Context Switching

The vCluster CLI automatically manages your kubectl context. Let’s see how:

# View current context
kubectl config current-context

You’ll see something like vcluster_my-vcluster_team-x_kind-kind.

# Connect to the virtual cluster
vcluster connect my-vcluster --namespace team-x

The -- syntax lets you execute commands in the vCluster context without permanently switching. Perfect for scripts and CI/CD!

List Your Virtual Clusters

You can list all virtual clusters across namespaces:

vcluster list

Expected Output

NAME           NAMESPACE   STATUS    CONNECTED   AGE
my-vcluster    team-x      Running   True        5m

Use JSON output for scripting:

vcluster list --output json

Clean Up

When you’re done testing, delete the virtual cluster:

vcluster delete my-vcluster --namespace team-x

This removes:

The vCluster control plane
All synced resources on the host cluster
The namespace (if it was created by vCluster)

Expected Output

info   Delete vcluster my-vcluster in namespace team-x...
done ✓ Successfully deleted virtual cluster my-vcluster in namespace team-x

This permanently deletes the virtual cluster and all resources within it. Make sure you’ve backed up any important data.

What You’ve Learned

Congratulations! You’ve successfully:

✅ Installed the vCluster CLI
✅ Created a virtual Kubernetes cluster
✅ Connected to it with kubectl
✅ Deployed workloads to the virtual cluster
✅ Created cluster-scoped resources (namespaces)
✅ Managed contexts between host and virtual clusters
✅ Cleaned up resources

Next Steps

Now that you understand the basics, explore more advanced topics:

Architecture Deep Dive

Learn how vCluster works under the hood with different deployment modes

Configuration Options

Customize vCluster with values files, sync settings, and resource configurations

High Availability

Deploy production-ready vClusters with multiple replicas and external databases

Resource Syncing

Control which resources sync between virtual and host clusters

CLI Reference

Explore all available vCluster CLI commands and flags

Use Cases

Discover how organizations use vCluster for multi-tenancy, GPU platforms, and more

Common Workflows

Creating vClusters with Custom Configuration

Create a vcluster.yaml file to customize your virtual cluster:

vcluster.yaml

controlPlane:
  backingStore:
    etcd:
      embedded:
        enabled: true
  statefulSet:
    highAvailability:
      replicas: 3

sync:
  toHost:
    ingresses:
      enabled: true

Deploy with the configuration:

vcluster create production-vcluster -n production -f vcluster.yaml

Using Different Kubernetes Versions

Run a different Kubernetes version in your virtual cluster:

vcluster create k8s-1-28 --kubernetes-version 1.28 -n testing

Upgrading a Virtual Cluster

Upgrade an existing virtual cluster:

vcluster upgrade my-vcluster --namespace team-x

Quick Reference

Here’s a cheat sheet of common commands:

# Create a vCluster
vcluster create <name> --namespace <namespace>

# Connect to a vCluster
vcluster connect <name> --namespace <namespace>

# Disconnect from vCluster
vcluster disconnect

# List all vClusters
vcluster list

# Delete a vCluster
vcluster delete <name> --namespace <namespace>

# Pause a vCluster (save resources)
vcluster pause <name> --namespace <namespace>

# Resume a paused vCluster
vcluster resume <name> --namespace <namespace>

# Get vCluster info
vcluster info

Getting Help

Need assistance?

Command help: Run vcluster <command> --help for detailed usage
Documentation: Browse the complete documentation
Community Slack: Join 5K+ users for real-time help
GitHub Issues: Report bugs or request features on GitHub

Looking for enterprise features like SSO, multi-cluster management, and advanced RBAC? Check out Loft vCluster Platform.

Get Started

Architecture

Deployment

Operations

Resource Syncing

Use Cases

Security

Integrations

Overview

Try Without Installing

Try on Killercoda

Step-by-Step Guide

What You’ve Learned

Next Steps

Architecture Deep Dive

Configuration Options

High Availability

Resource Syncing

CLI Reference

Use Cases

Common Workflows

Creating vClusters with Custom Configuration

Using Different Kubernetes Versions

Upgrading a Virtual Cluster

Quick Reference

Getting Help

Build docs developers (and LLMs) love

Get Started

Architecture

Deployment

Operations

Resource Syncing

Use Cases

Security

Integrations

​Overview

​Try Without Installing

Try on Killercoda

​Step-by-Step Guide

​What You’ve Learned

​Next Steps

Architecture Deep Dive

Configuration Options

High Availability

Resource Syncing

CLI Reference

Use Cases

​Common Workflows

​Creating vClusters with Custom Configuration

​Using Different Kubernetes Versions

​Upgrading a Virtual Cluster

​Quick Reference

​Getting Help

Build docs developers (and LLMs) love

Overview

Try Without Installing

Step-by-Step Guide

What You’ve Learned

Next Steps

Common Workflows

Creating vClusters with Custom Configuration

Using Different Kubernetes Versions

Upgrading a Virtual Cluster

Quick Reference

Getting Help