Skip to main content

Connect to and Use vCluster

Learning objectives​

  1. Connect to your vCluster instance.
  2. Run some kubectl commands inside of it.
  3. Learn what happens behind the scenes inside your vCluster's host namespace, which is part of the underlying host cluster.

Connect to your vCluster​

To connect to your cluster, run vcluster connect my-cluster. Output is similar to:

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

By default, the vCluster CLI connects to the virtual cluster either directly (on local Kubernetes distributions) or via port-forwarding for remote clusters. If you want to use vCluster on remote clusters without port-forwarding, you can take a look at other supported exposing methods.

Obtain the kubeconfig for your vCluster​

Instead of switching the current context you can also obtain its kubeconfig and write it to an output file via the following:

vcluster connect my-cluster --update-current=false --print > /tmp/vcluster.kubeconfig

Run kubectl commands​

A virtual cluster behaves the same way as a regular Kubernetes cluster. That means you can run any kubectl command. Since you are admin of this vCluster, you can even run commands like these:

kubectl get namespace
kubectl get pods -n kube-system

What happens in the host cluster​

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

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

Check that this deployment creates 2 pods inside the virtual cluster:

kubectl get pods -n demo-nginx

Output is similar to:

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-6d6565499c-2wfrd   1/1     Running   0          9s
nginx-deployment-6d6565499c-2blwr   1/1     Running   0          9s

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

To verify this, perform these steps:

  1. 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   11d
    vcluster-my-vcluster Active   9m17s
    kube-node-lease      Active   11d
    kube-public          Active   11d
    kube-system          Active   11d

    Notice that there is no namespace demo-nginx because this namespace only exists inside the virtual cluster.

    Everything that belongs to the virtual cluster always remains inside the vCluster's vcluster-my-vcluster namespace.

  3. Look for the NGINX deployment.

    Check to see if your deployment nginx-deployment is in the underlying host cluster.

    kubectl get deployments -n vcluster-my-cluster

    Output is similar to:

    No resources found in vcluster-my-cluster namespace.

    You see that there is no deployment nginx-deployment because that deployment only lives inside the virtual cluster.

  4. Look for the NGINX pods.

    The last thing to check is pods running inside the virtual cluster namespace:

    kubectl get pods -n vcluster-my-cluster

    Output is similar to:

    NAME                                                          READY   STATUS    RESTARTS   AGE
    coredns-68bdd584b4-9n8c4-x-kube-system-x-my-cluster           1/1     Running   0          129m
    my-cluster-0                                                  1/1     Running   0          129m
    nginx-deployment-6d6565499c-2blwr-x-demo-nginx-x-my-cluster   1/1     Running   0          7m25s
    nginx-deployment-6d6565499c-2wfrd-x-demo-nginx-x-my-cluster   1/1     Running   0          7m25s
    Renaming

    As you see in lines 4-5 of the output, the pod name is rewritten during the sync process since vCluster is mapping pods from namespaces inside the virtual cluster into one single host namespace in the underlying host cluster.

    The vCluster my-cluster-0 pod contains the virtual cluster’s API server and some additional tools. There’s also a CoreDNS pod, which vCluster uses, and the two NGINX pods.

    The host cluster has the nginx-deployment pods because the virtual cluster does not have separate nodes or a scheduler. Instead, the virtual cluster has a syncer that synchronizes resources from the virtual cluster to the underlying host namespace. The vCluster syncer process tells the underlying cluster to schedule workloads. This syncer process communicates with the API server of the host cluster to schedule the pods and keep track of their state. To prevent collisions, vCluster appends the name of the virtual cluster namespace the pods are running in and the name of the virtual cluster.

    Only very few resources and API server requests actually reach the underlying Kubernetes API server. Only workload-related resources (e.g. Pod) and networking-related resources (e.g. Service) need to be synchronized down to the host cluster since the vCluster does not have any nodes or network itself.

    The state of most objects running in the virtual cluster is stored in a database inside it. vCluster uses SQLite by default for that DB, but it can also use etcd or a few other options like PostgreSQL. But pods are scheduled in the host cluster.