Quickstart Guide

1. Download vcluster CLI#

Use one of the following commands to download the vcluster CLI binary from GitHub:

Mac (Intel/AMD)
Mac (Silicon/ARM)
Linux (AMD)
Linux (ARM)
Windows Powershell

curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12';
Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-windows-amd64.exe" -o $Env:APPDATA\vcluster\vcluster.exe;
$env:Path += ";" + $Env:APPDATA + "\vcluster";
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);

Reboot Required

You may need to reboot your computer to use the CLI due to changes to the PATH variable (see below).

Check Environment Variable $PATH

Line 4 of this install script adds the install directory %APPDATA%\vcluster to the $PATH environment variable. This is only effective for the current Powershell session, i.e. when opening a new terminal window, vcluster may not be found.

Make sure to add the folder %APPDATA%\vcluster to the PATH environment variable after installing vcluster CLI via Powershell. Afterward, a reboot might be necessary.

Alternatively, you can download the binary for your platform from the GitHub Releases page and add this binary to your PATH.

To confirm that vcluster CLI is successfully installed, test via:

vcluster --version

2. Create a vcluster#

vcluster
helm
kubectl

# Create a new vcluster in namespace vcluster-my-vcluster
vcluster create my-vcluster

# OR: Use --expose to create a vcluster in a remote cluster with an externally accessible LoadBalancer
vcluster create my-vcluster --expose

# OR: Use -f to use an additional helm values.yaml with extra chart options to deploy vcluster
vcluster create my-vcluster -f values.yaml
    
# OR: Use --distro to specify either k0s or vanilla k8s as backing virtual cluster
vcluster create my-vcluster --distro k8s

# OR: Use --isolate to create an isolated environment for the vcluster workloads
vcluster create my-vcluster --isolate

Create file vcluster.yaml:

vcluster:
  image: rancher/k3s:v1.23.5-k3s1    # Choose k3s version

Then, install helm chart using vcluster.yaml for chart values:

helm upgrade --install my-vcluster vcluster \
  --values vcluster.yaml \
  --repo https://charts.loft.sh \
  --namespace host-namespace-1 \
  --repository-config=''

3. Use the vcluster#

# Run any kubectl, helm, etc. command in your vcluster
kubectl get namespace
kubectl get pods -n kube-system
kubectl create namespace demo-nginx
kubectl create deployment nginx-deployment -n demo-nginx --image=nginx
kubectl get pods -n demo-nginx

4. Cleanup#

vcluster
helm
kubectl

# switch the kube context back
vcluster disconnect

# OR: switch context back and delete vcluster
vcluster delete my-vcluster

The easiest option to delete a virtual cluster using kubectl is to delete the host namespace:

kubectl delete namespace vcluster-my-vcluster

In case you have multiple vclusters or any other resources in this namespace, you can also just delete the vcluster-related resources:

kubectl delete -n vcluster-my-vcluster serviceaccount vcluster-1
kubectl delete -n vcluster-my-vcluster role vcluster-1
kubectl delete -n vcluster-my-vcluster rolebinding vcluster-1
kubectl delete -n vcluster-my-vcluster service vcluster-1
kubectl delete -n vcluster-my-vcluster service vcluster-1-headless
kubectl delete -n vcluster-my-vcluster statefulset vcluster-1