Skip to main content
Version: main 🚧

Quick Start Guide

Key Concepts​

  • vCluster Control Plane: Contains a Kubernetes API server, a controller manager, a data store mount, and the Syncer.
  • Syncing resources: vCluster runs your workloads by syncing pods from the virtual cluster to the host cluster.
  • Pod scheduling: By default, vCluster reuses the host cluster scheduler to schedule workloads, but you can enable the virtual cluster's scheduler.
  • Storage: You can use the host's storage classes without the need to create them in the virtual cluster by enabling them to sync from the host cluster to the virtual cluster.
  • Networking: vCluster can sync resources such as Service and Ingress resources from the virtual to the host cluster.
  • Nodes: By default, vCluster creates pseudo nodes for every pod spec.nodeName in the virtual cluster.

Before you begin​

In order to deploy vcluster, you need the following:

  • kubectl
  • Helm v3.10.0+
  • Access to a Kubernetes v1.28+ cluster with permissions to deploy applications into a namespace. This is considered the host cluster for the vCluster deployment.

Host Cluster Requirements

Since vCluster runs as an application, vCluster can run on any host cluster regardless of OS or Kubernetes distribution. The Kubernetes distribution of vCluster does not need to match the Kubernetes distribution of the host cluster. For example, you can select a vCluster with k8s as the distro and run it on host cluster that's running EKS.

Deploy vCluster​

Deploy a vCluster instance called my-vcluster to namespace team-x. This guide uses the vCluster CLI to deploy vCluster, but there are multiple ways to deploy vCluster using other tools like Helm, Terraform, ArgoCD, ClusterAPI, etc. Read about the additional options in the deployment section of the docs.

  1. Install the vCluster CLI.

     brew install loft-sh/tap/vcluster-experimental

    If you installed the CLI using brew install vcluster, you should brew uninstall vcluster and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version

  2. (Optional) Create a vcluster.yaml to configure your vCluster. Various options can be configured before deploying your vCluster, but even without a vcluster.yaml, a vCluster can be deployed with the default options.

    Refer to the vcluster.yaml reference docs to explore all configuration options.

    vcluster.yaml configuration

    If you aren't sure what options you want to configure, you can always upgrade your vCluster after deployment with an updated vcluster.yaml to change your configuration. There are some configuration options (e.g. backing store) that can only be defined during deployment and not changed during upgrade.

  3. Deploy vCluster using the vCluster CLI. There are other methods to deploy vCluster, but this is the quickest way to get started!

    vcluster create my-vcluster --namespace team-x

  4. Check out the namespaces in your virtual cluster. When the virtual cluster deployment finishes, your kube context is automatically updated to the virtual cluster. When you run kubectl commands, it will now be pointed at your virtual cluster instead of the original Kubernetes cluster.

    kubectl get namespaces # See the namespaces of your virtual cluster

Use your virtual cluster​

After immediately creating your virtual cluster, your kube context is updated to point to the virtual cluster and all these commands are directed at the virtual cluster.

Deploy resources inside the virtual cluster​

To illustrate what happens in the host cluster, create a namespace and deploy NGINX in the virtual cluster.

kubectl create namespace demo-nginx
kubectl create deployment ngnix-deployment -n demo-nginx --image=nginx -r 2

Check that this deployment creates two pods inside the virtual cluster.

kubectl get pods -n demo-nginx

View resources inside the host cluster​

Most resources inside your virtual cluster only exist in your virtual cluster and not in the host cluster.

To verify this, perform these steps:

  1. Switch your kube context from the virtual cluster to the host cluster by disconnecting.

    vcluster disconnect

  2. Check the namespaces in the host cluster to confirm you are in the correct kube context.

    kubectl get namespaces

    Output is similar to:

    NAME                 STATUS   AGE
    default              Active   35m
    kube-public          Active   35m
    kube-system          Active   35m
    team-x               Active   30m

  3. Look at all the deployments in the team-x namespace to see if the nginx-deployment deployment was deployed on the host cluster.

    kubectl get deployments -n team-x

    Notice that this deployment resource does not exist in the host cluster. By default, it does not get synced from the virtual cluster to the host cluster because it isn't required to run this workload in the host cluster.

  4. Now, look for the NGINX pods on the host cluster.

    kubectl get pods -n team-x

    Output is similar to:

    coredns-cb5ccc67f-kqwmx-x-kube-system-x-my-vcluster            1/1     Running   0          34m
    my-vcluster-0                                                  1/1     Running   0          34m
    nginx-deployment-6d6565499c-cbv4w-x-demo-nginx-x-my-vcluster   1/1     Running   0          20m
    nginx-deployment-6d6565499c-s7g8z-x-demo-nginx-x-my-vcluster   1/1     Running   0          20m

    You can see from the output that the the two NGINX pods exist in the host cluster. To prevent collisions, the pod names and their namespaces are rewritten by vCluster during the sync process from the virtual cluster to the host cluster.

    vCluster Control Plane

    The vCluster my-cluster-0 pod is also known as the vCluster control plane.

    When a local persistent storage is needed, a virtual cluster is deployed as a StatefulSet, which provides stable, unique pod identities including a persistent volume. StatefulSets ensure that each vCluster pod maintains a consistent network identity and, when configured, persistent storage. This is essential for vCluster’s internal data, as it utilizes Kine, a shim between Kubernetes and relational databases, along with an embedded SQLite database (state.db) to store state information.

    However when no local persistent storage is needed, as is in the case of external database, a virtual cluster is deployed as a Deployment.

    By default, vCluster does not persist data outside of its pods. Consequently, deleting a vCluster pod without persistent storage results in data loss. You can configure external backingStore to persist data outside of the pod.

Explore Features​

Configure features in a vcluster.yaml file. These examples show you how to configure some popular features. See the vcluser.yaml configuration reference for how to configure additional features.

Expose the vCluster control plane

There are multiple ways of granting access to the vCluster control plane for external applications like kubectl. The following example uses an Ingress, but you can also do it via ServiceAccount, LoadBalancer, and NodePort.

  1. Modify vcluster.yaml so that vCluster creates the required Ingress resource.

    vcluster.yaml ingress configuration
    controlPlane:
        ingress:
            enabled: true
            host: $VCLUSTER_HOSTNAME
        proxy:
            extraSANs:
            - $VCLUSTER_HOSTNAME

    Replace $VCLUSTER_HOSTNAME with the hostname of the vCluster instance.

  2. Apply your changes.

    vcluster create --upgrade my-vcluster -n team-x -f vcluster.yaml
Show real nodes

By default, vCluster syncs pseudo nodes from the host cluster to the virtual cluster. However, deploying a vCluster instance via the CLI on a local Kubernetes cluster automatically enables real node syncing, so you would not see a difference in this context.

Pseudo nodes only have real values for the CPU, architecture, and operating system, while everything else is randomly generated. Therefore, for use cases requiring real node information, you can opt to sync the real nodes into the virtual cluster.

  1. Modify vcluster.yaml to sync the nodes from the host cluster to the virtual cluster.

    vcluster.yaml node sync configuration
    sync:
      fromHost:
        nodes:
          enabled: true

  2. Apply your changes.

    vcluster create --upgrade my-vcluster -n team-x -f vcluster.yaml
Sync ingress classes from host cluster to virtual cluster

If you want to use an ingress controller from the host cluster inside your virtual cluster by syncing Ingress resources from the virtual cluster to host cluster, and allow the host cluster IngressClasses to be viewable, enable IngressClass syncing from the host cluster to virtual cluster.

  1. Modify vcluster.yaml to sync the IngressClasses from the host cluster to the virtual cluster.

    vcluster.yaml ingress class sync configuration
    sync:
      fromHost:
        ingressClasses:
          enabled: true

  2. Apply your changes.

    vcluster create --upgrade my-vcluster -n team-x -f vcluster.yaml
Sync ingress from virtual cluster to host cluster

Create an ingress in a virtual cluster to make a service in that virtual cluster available via a hostname/domain. Instead of having to run a separate ingress controller in each virtual cluster, sync the ingress resource to the host cluster so that the virtual cluster can use a shared ingress controller running in the host cluster.

  1. Modify vcluster.yaml to sync the ingresses from the virtual cluster to the host cluster.

    sync:
      toHost:
        ingresses:
          enabled: true

  2. Apply your changes.

    vcluster create --upgrade my-vcluster -n team-x -f vcluster.yaml
Sync services from host cluster to virtual cluster

In this example, you map a service my-host-service in the namespace my-host-namespace to the virtual cluster service my-virtual-service inside the virtual cluster namespace team-x.

  1. Modify vcluster.yaml to sync the ingresses from the virtual cluster to the host cluster.

    replicateServices:
      fromHost:
        - from: my-host-namespace/my-host-service
          to: team-x/my-virtual-service

  2. Apply your changes.

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

Delete vCluster​

Deleting a vCluster also deletes all resources within the virtual cluster and all states related to the vCluster. If the namespace on the host cluster was created by the vCluster CLI, then that namespace is also deleted.

vcluster delete my-vcluster --namespace team-x