Skip to main content
Version: main 🚧

Quick Start Guide

This guide walks through deploying a tenant cluster, running a workload against it, and understanding the core isolation model.

For AI Cloud and GPU workloads

This guide deploys a tenant cluster using the Shared Nodes default, which is suitable for testing and development. For production GPU workloads, see Building a GPU cloud platform to choose the right deployment model for your use case.

How tenant clusters work

Before deploying a vCluster, it's important to understand the components of a tenant cluster and how they determine your isolation model.

  • Control plane: Contains a Kubernetes API server, a controller manager, and a data store. Runs on the Control Plane Cluster but is completely invisible to tenants.
  • Worker nodes: Worker nodes can be drawn from the Control Plane Cluster's node pool (shared nodes) or provisioned as dedicated private nodes.

Prerequisites​

Prerequisites depend on your deployment model. Pick your path before continuing.

  • kubectl
  • Helm v3.10.0+
  • Access to a Kubernetes v1.28+ cluster with permissions to deploy applications into a namespace. No cluster-admin or cluster-wide permissions are required. This cluster acts as the Control Plane Cluster for the tenant cluster deployment.

Deploy vCluster​

Install the vCluster CLI​

brew install loft-sh/tap/vcluster

The binaries in the tap are signed using the Sigstore framework for enhanced security.

Verify the CLI installed successfully.

vcluster --version

Output is similar to:

vCluster version 0.x.x

Deploy a tenant cluster​

Deploying to an existing Kubernetes cluster? Use the Kubernetes tab. Testing locally without a cluster? Use Docker (vind) — no Kubernetes required.


For this quickstart, you'll deploy a tenant cluster called my-vcluster to the namespace team-x on a Control Plane Cluster. This guide uses the vCluster CLI, but there are multiple ways to deploy vCluster using other tools like Helm, Terraform, ArgoCD, ClusterAPI, or similar. Read about the additional options in the deployment section of the docs.

  1. (Optional) If you want to customize how vCluster deploiys, create a vcluster.yaml. Various options can be configured before deploying your vCluster. Refer to the vcluster.yaml reference docs to explore all configuration options.

    Otherwise, continue without a vcluster.yaml file to deploy a vCluster with default 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. While most options can be configured later, some options can only be defined during the initial deployment. See pre-deployment configuration options for the full list.

  2. 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

  3. When the tenant cluster deployment finishes, your kube context automatically updates to point to the tenant cluster. Check the namespaces to confirm.

    kubectl get namespaces # See the namespaces of your tenant cluster

Use your tenant cluster​

Deploy a test workload and explore your running tenant cluster.

Deploy a test workload​

Deploy a namespace and workload to your tenant cluster. The next section shows how these resources relate to the Control Plane Cluster.

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

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

kubectl get pods -n demo-nginx

Output is similar to:

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-6d6565499c-cbv4w   1/1     Running   0          2m
nginx-deployment-6d6565499c-s7g8z   1/1     Running   0          2m

Understand resource isolation​

This step shows the core isolation guarantee: most resources in your tenant cluster remain invisible on the Control Plane Cluster. Only the pods required for scheduling are synced across.

To verify this, perform these steps:

  1. Switch your kube context from the tenant cluster back to the Control Plane Cluster by disconnecting.

    vcluster disconnect

  2. Check the namespaces on the Control Plane 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 the deployments in the team-x namespace to verify nginx-deployment was not synced to the Control Plane Cluster.

    kubectl get deployments -n team-x

    This deployment resource does not exist on the Control Plane Cluster. By default, Deployments are not synced from the tenant cluster to the Control Plane Cluster. Only the pods that need to be scheduled sync.

  4. Now look for the NGINX pods on the Control Plane 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

    The two NGINX pods exist on the Control Plane Cluster. vCluster rewrites pod names and namespaces during the sync process to prevent collisions.

    How vCluster stores state (StatefulSet vs Deployment)

    The my-vcluster-0 pod is the vCluster control plane.

    vCluster deploys as a StatefulSet when it needs local persistent storage. The StatefulSet provides stable pod identities and a persistent volume for Kine, vCluster's internal data store, which uses an embedded SQLite database (state.db).

    When you configure an external database, vCluster deploys as a Deployment instead.

    By default, vCluster does not persist data outside of its pods. Deleting a vCluster pod without persistent storage causes data loss. Configure an external backing store to persist data outside the pod.

Common configuration patterns​

Each example below shows a common configuration pattern. Apply any of them by modifying vcluster.yaml and redeploying. See the vcluster.yaml reference for the full list of options.

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 with 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 nodesPseudo NodesThe default node representation in a tenant cluster. vCluster creates pseudo nodes for each host node that has pods scheduled on it. Pseudo nodes have real values for name, CPU, architecture, and operating system, but all other fields are randomly generated. When no pods remain on a host node, vCluster deletes the corresponding pseudo node.Related: Syncer, Control Plane Cluster from the Control Plane Cluster to the tenant cluster. However, deploying a vCluster instance with 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 tenant cluster.

  1. Modify vcluster.yaml to sync the Nodes from the Control Plane Cluster to the tenant 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 the Control Plane Cluster to the tenant cluster

If you want to use an Ingress controller from the Control Plane Cluster inside your tenant cluster by syncing Ingress resources from the tenant cluster to the Control Plane Cluster, and allow the Control Plane Cluster IngressClasses to be viewable, enable IngressClass syncing from the Control Plane Cluster to the tenant cluster.

  1. Modify vcluster.yaml to sync the IngressClasses from the Control Plane Cluster to the tenant 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 the tenant cluster to the Control Plane Cluster

Create an Ingress in a tenant cluster to make a service in that tenant cluster available from a hostname/domain. Instead of having to run a separate Ingress controller in each tenant cluster, sync the Ingress resource to the Control Plane Cluster so that the tenant cluster can use a shared Ingress controller running in the Control Plane Cluster.

  1. Modify vcluster.yaml to sync the Ingresses from the tenant cluster to the Control Plane Cluster.

    sync:
      toHost:
        ingresses:
          enabled: true

  2. Apply your changes.

    vcluster create --upgrade my-vcluster -n team-x -f vcluster.yaml
Sync Services from the Control Plane Cluster to the tenant cluster

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

  1. Modify vcluster.yaml to sync the Services from the Control Plane Cluster to the tenant 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 a tenant cluster​

warning

Deleting a tenant cluster deletes all resources within the cluster and all associated state. This cannot be undone.

If the namespace on the Control Plane Cluster was created by the vCluster CLI, then that namespace is also deleted.

vcluster delete my-vcluster --namespace team-x

Next steps​