Installation Guide

Overview

This guide covers all methods for installing the vCluster CLI and deploying virtual clusters. The CLI is the primary tool for managing vClusters, though you can also use Helm directly for more control.

Prerequisites

System Requirements

Before installing vCluster, ensure you have:

Host Kubernetes Cluster

Kubernetes v1.18+ with kubectl configured

Helm (for Helm installation)

Helm v3.10.0+ installed locally

Resources

Minimum 2 CPU cores and 4GB RAM available

Permissions

Ability to create namespaces and deploy resources

Don’t have a Kubernetes cluster? Try Minikube, Kind, or Docker Desktop for local development.

Installing the vCluster CLI

The vCluster CLI (vcluster) is the recommended way to manage virtual clusters. Choose your installation method:

Homebrew (macOS and Linux)

The easiest method for macOS and Linux users:

Install via Homebrew

brew install loft-sh/tap/vcluster

Verify Installation

vcluster --version

Homebrew automatically manages updates. Run brew upgrade vcluster to get the latest version.

Direct Binary Download

Linux
macOS
Windows

Download and install the vCluster binary directly:

# Download the latest release for your architecture
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

# Verify installation
vcluster --version

Install Specific Version

To install a specific version instead of the latest:

VERSION="v0.30.0"
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/${VERSION}/vcluster-$(uname -s)-$(uname -m)"
chmod +x vcluster
sudo mv vcluster /usr/local/bin/vcluster

Download the binary for macOS:

# For Apple Silicon (M1/M2/M3)
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-arm64"

# For Intel Macs
# curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-amd64"

# Make it executable
chmod +x vcluster

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

# Verify installation
vcluster --version

macOS may show a security warning for unsigned binaries. Go to System Preferences → Security & Privacy to allow it, or use Homebrew instead.

Download the Windows binary:Option 1: Manual Download

Download the latest release from GitHub Releases
Look for vcluster-windows-amd64.exe
Rename to vcluster.exe
Add to your PATH or move to a directory in your PATH

Option 2: PowerShell Script

# Create directory
md -Force "$Env:APPDATA\vcluster"

# Download latest version
[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

# Add to PATH
$env:Path += ";"+$Env:APPDATA+"\vcluster"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User)

# Verify installation
vcluster --version

You may need to restart your terminal after adding vCluster to your PATH.

Build from Source

For developers or those wanting the latest development version:

Clone the Repository

git clone https://github.com/loft-sh/vcluster.git
cd vcluster

Install Build Dependencies

You’ll need:

Go 1.25+
Just (optional, for build tasks)
GoReleaser (for snapshot builds)

Build the CLI

Using Just (recommended):

just build-snapshot

Using Go directly:

go generate ./...
go build -o vcluster cmd/vclusterctl/main.go

Verify the Build

./dist/<ARCH>/vcluster version
# Or if built with Go directly:
./vcluster version

For detailed development instructions, see the Contributing Guide.

Deploying Virtual Clusters

Once you have the CLI installed, you can deploy virtual clusters using different methods:

Method 1: Using vCluster CLI (Recommended)

The CLI provides the simplest deployment experience:

# Basic deployment
vcluster create my-vcluster --namespace team-x

# With custom Kubernetes version
vcluster create my-vcluster --namespace team-x --kubernetes-version 1.28

# With custom values file
vcluster create my-vcluster --namespace team-x -f vcluster.yaml

# From a specific Helm chart version
vcluster create my-vcluster --namespace team-x --chart-version 0.30.0

Common CLI Flags

Flag	Description
`--namespace`	Namespace to deploy vCluster into (created if it doesn’t exist)
`--kubernetes-version`	Kubernetes version for the virtual cluster
`-f, --values`	Path to a values.yaml file for Helm configuration
`--set`	Set individual values (e.g., `--set sync.toHost.ingresses.enabled=true`)
`--chart-version`	Specific vCluster Helm chart version to install
`--connect`	Automatically connect after creation (default: true)
`--upgrade`	Upgrade if already exists
`--create-namespace`	Create namespace if it doesn’t exist (default: true)

Method 2: Direct Helm Installation

For more control or integration with existing Helm workflows:

Add Helm Repository

helm repo add loft-sh https://charts.loft.sh
helm repo update

Install the Chart

# Basic installation
helm upgrade --install my-vcluster loft-sh/vcluster \
  --namespace team-x \
  --create-namespace

# With custom values
helm upgrade --install my-vcluster loft-sh/vcluster \
  --namespace team-x \
  --create-namespace \
  --values vcluster.yaml

Connect to the vCluster

After Helm installation, use the CLI to connect:

vcluster connect my-vcluster --namespace team-x

The Helm chart is the same whether you use vcluster create or helm install. The CLI just provides convenience wrappers.

Method 3: Docker Driver

For local development without Kubernetes:

# Create a vCluster using Docker driver
vcluster create my-vcluster --driver docker

# List Docker-based vClusters
vcluster list --driver docker

# Delete Docker-based vCluster
vcluster delete my-vcluster --driver docker

The Docker driver runs vCluster in Docker containers instead of Kubernetes pods. This is useful for local testing but not recommended for production.

Configuration Options

Basic Configuration Example

Create a vcluster.yaml file to customize your deployment:

vcluster.yaml

# Control plane configuration
controlPlane:
  backingStore:
    etcd:
      embedded:
        enabled: true
  statefulSet:
    image:
      tag: "1.29"  # Kubernetes version
    resources:
      limits:
        cpu: 2
        memory: 4Gi
      requests:
        cpu: 200m
        memory: 512Mi

# Resource syncing
sync:
  toHost:
    pods:
      enabled: true
    services:
      enabled: true
    secrets:
      enabled: true
    configMaps:
      enabled: true
    ingresses:
      enabled: true
    persistentVolumeClaims:
      enabled: true

  fromHost:
    nodes:
      enabled: false  # Use pseudo nodes

Deploy with this configuration:

vcluster create my-vcluster -n team-x -f vcluster.yaml

High Availability Configuration

For production deployments with HA:

vcluster-ha.yaml

controlPlane:
  backingStore:
    etcd:
      embedded:
        enabled: true
  statefulSet:
    highAvailability:
      replicas: 3
    resources:
      limits:
        cpu: 4
        memory: 8Gi
      requests:
        cpu: 500m
        memory: 1Gi

High availability requires at least 3 replicas and more cluster resources. Ensure your host cluster can support the additional load.

Verification Steps

After installation, verify everything is working:

Check vCluster Status

vcluster list

Your vCluster should show STATUS: Running and CONNECTED: True.

Verify Pods

# In the host cluster
kubectl get pods -n team-x

You should see the vCluster control plane pod running.

Test Virtual Cluster Access

# Connect to vCluster
vcluster connect my-vcluster -n team-x

# Run commands in the virtual cluster
kubectl get namespaces
kubectl create deployment nginx --image=nginx
kubectl get pods

Platform-Specific Notes

Local Kubernetes Clusters

Kind (Kubernetes in Docker)

Kind works great with vCluster:

# Create a Kind cluster
kind create cluster

# Create a vCluster
vcluster create my-vcluster -n test

If using custom Docker images during development:

# Build your custom vCluster image
docker build . -t my-vcluster:0.0.1

# Load into Kind
kind load docker-image my-vcluster:0.0.1

# Deploy with custom image
vcluster create my-vcluster -n test -f custom-image.yaml

Minikube

Minikube is fully supported:

# Start Minikube
minikube start

# Create vCluster
vcluster create my-vcluster -n test

For better performance, increase Minikube resources:

minikube start --cpus=4 --memory=8192

Docker Desktop

Enable Kubernetes in Docker Desktop settings, then:

# Verify Kubernetes is running
kubectl cluster-info

# Create vCluster
vcluster create my-vcluster -n test

Cloud Providers

Amazon EKS

vCluster works seamlessly with EKS:

# Configure kubectl for EKS
aws eks update-kubeconfig --name my-cluster --region us-west-2

# Create vCluster
vcluster create my-vcluster -n team-x

Consider using external databases for production:

controlPlane:
  backingStore:
    database:
      external:
        enabled: true
        dataSource: "postgres://user:pass@rds-endpoint:5432/vcluster"

Google GKE

# Get GKE credentials
gcloud container clusters get-credentials my-cluster --region us-central1

# Create vCluster
vcluster create my-vcluster -n team-x

Azure AKS

# Get AKS credentials
az aks get-credentials --resource-group myResourceGroup --name myAKSCluster

# Create vCluster
vcluster create my-vcluster -n team-x

Upgrading vCluster

Upgrade the CLI

Homebrew
Manual

brew upgrade vcluster

Upgrade a Virtual Cluster

# Upgrade to latest version
vcluster upgrade my-vcluster --namespace team-x

# Upgrade to specific version
vcluster upgrade my-vcluster --namespace team-x --chart-version 0.30.0

# Upgrade with new values
vcluster upgrade my-vcluster --namespace team-x -f new-values.yaml

Always test upgrades in a non-production environment first. Review the changelog for breaking changes.

Troubleshooting

CLI Installation Issues

Problem: command not found: vclusterSolution:

Verify the binary is in your PATH: echo $PATH
Check installation location: which vcluster
Restart your terminal after installation
On macOS, check Security & Privacy settings for unsigned binaries

Helm Version Errors

Problem: Error: Helm version 3.10.0 or higher is requiredSolution:

# Check Helm version
helm version

# Upgrade Helm
# macOS/Linux
brew upgrade helm

# Or download from https://github.com/helm/helm/releases

Pod Creation Stuck

Problem: vCluster pod remains in Pending or ContainerCreatingSolution:

# Check pod events
kubectl describe pod -n team-x -l app=vcluster

# Common causes:
# - Insufficient cluster resources
# - Image pull errors
# - PVC provisioning issues

# Check node resources
kubectl top nodes

Connection Issues

Problem: Cannot connect to vCluster after creationSolution:

# Check vCluster status
vcluster list

# Manually connect
vcluster connect my-vcluster -n team-x

# Check kubeconfig
kubectl config get-contexts

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

Next Steps

Now that you have vCluster installed:

Quickstart Guide

Create your first virtual cluster in under 5 minutes

Configuration Reference

Explore all configuration options for customizing vClusters

Architecture Guide

Understand different deployment architectures

CLI Reference

Learn all vCluster CLI commands and options

Additional Resources

Helm Chart README: Detailed Helm chart documentation
GitHub Releases: Download specific versions and view changelogs
Contributing Guide: Build and contribute to vCluster
Community Slack: Get help from the community

For enterprise deployments with SSO, audit logs, and centralized management, explore Loft vCluster Platform.

Get Started

Architecture

Deployment

Operations

Resource Syncing

Use Cases

Security

Integrations

​Overview

​Prerequisites

​System Requirements

Host Kubernetes Cluster

Helm (for Helm installation)

Resources

Permissions

​Installing the vCluster CLI

​Homebrew (macOS and Linux)

​Direct Binary Download

​Build from Source

​Deploying Virtual Clusters

​Method 1: Using vCluster CLI (Recommended)

​Method 2: Direct Helm Installation

​Method 3: Docker Driver

​Configuration Options

​Basic Configuration Example

​High Availability Configuration

​Verification Steps

​Platform-Specific Notes

​Local Kubernetes Clusters

​Cloud Providers

​Upgrading vCluster

​Upgrade the CLI

​Upgrade a Virtual Cluster

​Troubleshooting

​Next Steps

Quickstart Guide

Configuration Reference

Architecture Guide

CLI Reference

​Additional Resources

Overview

Prerequisites

System Requirements

Installing the vCluster CLI

Homebrew (macOS and Linux)

Direct Binary Download

Build from Source

Deploying Virtual Clusters

Method 1: Using vCluster CLI (Recommended)

Method 2: Direct Helm Installation

Method 3: Docker Driver

Configuration Options

Basic Configuration Example

High Availability Configuration

Verification Steps

Platform-Specific Notes

Local Kubernetes Clusters

Cloud Providers

Upgrading vCluster

Upgrade the CLI

Upgrade a Virtual Cluster

Troubleshooting

Next Steps

Additional Resources