Skip to main content

Get started

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. The installation instructions use vCluster CLI, but there are other installation options as well.

  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.

    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. (Optional) Configure vCluster with vcluster.yaml.

    By default, vCluster uses vanilla Kubernetes as the Kubernetes distribution for the virtual cluster. If you want to change the Kubernetes distribution, you must change it before you deploy vCluster. Create a file called vcluster.yaml and configure the distribution. This example configures a different Kubernetes distribution (i.e K3s).

    controlPlane:
    distro:
    k3s:
    enabled: true

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

  3. Deploy vCluster

    1. Create the "team-x" namespace.

      kubectl create namespace team-x
    2. Deploy vCluster.

      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:

vcluster connect my-vcluster --namespace team-x

Disconnect from your virtual cluster and switch back to the original kube context:

vcluster disconnect

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

Note: 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 approach 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 VCLUSTER_NAMESPACE -f vcluster.yaml

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
    • VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

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.

    sync:
    fromHost:
    nodes:
    enabled: true
  2. Apply your changes.

    vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
    • VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Sync ingress from host to virtual

If you want to use an ingress controller from the host cluster inside your virtual cluster, enable IngressClass syncing from host to virtual cluster.

  1. Modify vcluster.yaml.

    sync:
    fromHost:
    ingressClasses:
    enabled: true
  2. Apply your changes.

    vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
    • VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Sync ingress from virtual to host

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.

    sync:
    toHost:
    ingresses:
    enabled: true
  2. Apply your changes.

    vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
    • VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Sync services from host 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.

    replicateServices:
    fromHost:
    - from: my-host-namespace/my-host-service
    to: team-x/my-virtual-service
  2. Apply your changes.

    vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml

    Replace:

    • VCLUSTER_NAME with your vCluster instance name.
    • VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Delete vCluster

Resources inside 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.

To delete a vCluster using the CLI:

vcluster delete my-vcluster --namespace team-x