Skip to main content

Quickstart Guide

1. Download vcluster CLI#

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

curl -s -L "" | sed -nE 's!.*"([^"]*vcluster-darwin-amd64)".*!\1!p' | xargs -n 1 curl -L -o vcluster && chmod +x vcluster;
sudo mv vcluster /usr/local/bin;

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#

# Create a vcluster that can be accessed through port forwarding
vcluster create vcluster-1 -n host-namespace-1
# OR: Use --expose to create a vcluster with an externally accessible LoadBalancer
vcluster create vcluster-1 -n host-namespace-1 --expose
# OR: Use -f to use an additional helm values.yaml with extra chart options to deploy vcluster
vcluster create vcluster-1 -n host-namespace-1 -f values.yaml
# OR: Use --distro to specify either k0s or vanilla k8s as backing virtual cluster
vcluster create vcluster-1 -n host-namespace-1 --distro k8s

3. Use the vcluster#

vcluster connect creates a local kubeconfig file that references the vcluster.

# Create a kube config for the vcluster and optionally start port-forwarding to it (if --expose was not used)
vcluster connect vcluster-1 -n host-namespace-1
export KUBECONFIG=./kubeconfig.yaml
# 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 delete vcluster-1 -n host-namespace-1
# OR: delete the namespace as well
vcluster delete vcluster-1 -n host-namespace-1 --delete-namespace