Deploy vCluster

Before you begin

Admin permissions not required

One of the biggest benefits of vCluster compared to other virtual cluster approaches is that it does not require any special permissions. You can spin up a virtual cluster even if you do not have a cluster-admin role and only have access to deploy applications to one specific namespace.

Namespaces

Installation creates the namespace for vCluster if it does not yet exist. When you create namespaces within your virtual cluster, those resources are encapsulated within the vCluster namespace.

Create your virtual cluster

Create a virtual cluster my-vcluster in namespace vcluster-my-vcluster.

vcluster

Execute vcluster create my-cluster to create a new vCluster instance in namespace vcluster-my-vcluster. K3s is the default Kubernetes distribution.

When the installation finishes, you should see output similar to:

done Switched active kube context to vcluster_my-cluster
- Use `vcluster disconnect` to return to your previous kube context

vcluster create has config options for specific cases:

• Use --expose to create a vCluster in a remote cluster with an externally accessible LoadBalancer.

  vcluster create my-vcluster --expose

• Use -f to use an additional Helm values.yaml with extra chart options to deploy vCluster.

  vcluster create my-vcluster -f values.yaml

• Use --distro to specify either k0s or vanilla k8s as a backing virtual cluster.

  vcluster create my-vcluster --distro k8s

• Use --isolate to create an isolated environment for the vCluster workloads

  vcluster create my-vcluster --isolate

helm

You want vCluster to use K3s, so create a file called vcluster.yaml with the following contents:

vcluster:
  image: rancher/k3s:v1.29.1+k3s2    # Choose K3s version

Then, install the Helm chart, specifying vcluster.yaml for chart values:

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

kubectl

This installs vCluster with default values.

kubectl create namespace vcluster-my-vcluster
helm template my-vcluster vcluster --repo https://charts.loft.sh -n vcluster-my-vcluster | kubectl apply -f -

Contexts

In this guide, vCluster installation creates a new context that starts with "vcluster_my-cluster" and updates your kubeconfig file to point to that context.

• Execute vcluster connect my-cluster to connect to your vCluster context.
• Execute vcluster disconnect to switch back to your default (host) context.

Air-Gapped installation

If you want to deploy vCluster in an air-gapped environment, set the following option in the values.yaml used to deploy vCluster:

defaultImageRegistry: my-private-registry:5000/vcluster/

This tells vCluster to prepend the image registry to all images used by vCluster, such as syncer, K3s, and CoreDNS. For example, rancher/k3s:v1.29.1+k3s2 becomes `my-private-registry:5000/vcluster/rancher/k3s:v1.29.1+k3s2.

You can find a list of all needed images by vCluster in the file vcluster-images.txt at the releases page, as well as two scripts (download-images.sh & push-images.sh) to pull and push those to your private registry.

You can locate the Helm chart and values file for Kubernetes distro in the vCluster repo. Be sure to choose the tag that matches your vCluster version.