Skip to main content

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.
  • Storage: You can use the host's storage classes without the need to create them in the virtual cluster.
  • Networking: vCluster syncs 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​

You need the following:

  • Access to a Kubernetes v1.26+ cluster with permissions to deploy applications into a namespace. This is the host cluster for vCluster deployment.
  • kubectl CLI

Deploy vCluster​

Deploy a vCluster instance called my-vcluster to namespace team-x. In this guide, we will use vCluster CLI, but there are multiple ways to deploy vCluster using other tools like Helm, Terraform, ArgoCD, ClusterAPI, etc. Read about our 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 configuration options can be configured prior to deploying your vCluster, but even without a vcluster.yaml, the vCluster can be deployed with a default configuration.

    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 options) that can only be defined during deployment and not changed during upgrade.

  3. Deploy vCluster using 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

    When the installation finishes, you are automatically connected to the virtual cluster and can run kubectl commands within the virtual cluster.

Use your virtual cluster​

Interacting with a virtual cluster is very similar to using a standard Kubernetes cluster.

Connect​

Connect to your virtual cluster and update your kube context to point to the virtual cluster:

vcluster connect my-vcluster --namespace team-x

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. Disconnect from the current virtual cluster and switch back to the host context.

    vcluster disconnect

  2. Check namespaces in the host cluster.

    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 for the nginx-deployment deployment.

    kubectl get deployments -n team-x

    Notice that this resource does NOT exist in the host cluster because it normally does not get synced from the virtual to the host cluster since its typically not required to run workloads on the host cluster.

  4. Now, look for the NGINX pods.

    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. The vCluster my-cluster-0 pod is the vCluster control plane.

K8s Resource Renaming

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.

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.

    controlPlane:
        ingress:
            enabled: true
            host: VCLUSTER_HOSTNAME
        proxy:
            extraSANs:
            - VCLUSTER_HOSTNAME

    Replace VCLUSTER_HOSTNAME with your vCluster instance's hostname.

  2. Apply your changes.

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

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
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.

    sync:
      fromHost:
        nodes:
          enabled: true

    Replace VCLUSTER_HOSTNAME with your vCluster instance's hostname.

  2. Apply your changes.

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

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
Sync ingress from host cluster to virtual cluster

If you want to use an ingress controller from the host cluster inside your virtual cluster, 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.

    sync:
      fromHost:
        ingressClasses:
          enabled: true

    Replace VCLUSTER_HOSTNAME with your vCluster instance's hostname.

  2. Apply your changes.

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

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
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

    Replace VCLUSTER_HOSTNAME with your vCluster instance's hostname.

  2. Apply your changes.

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

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
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

    Replace VCLUSTER_HOSTNAME with your vCluster instance's hostname.

  2. Apply your changes.

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

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.

Delete vCluster​

Deleting a vCluster instance also deletes all objects within 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