---
title: Connect to and Use vCluster
sidebar_label: 3. Use vCluster
---

## Learning objectives

1. [Connect to your vCluster instance](#connect-to-your-vcluster).
1. [Run some `kubectl` commands inside of it](#run-kubectl-commands).
1. [Learn what happens](#what-happens-in-the-host-cluster) 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:

```bash
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](../using-vclusters/access.mdx).

### 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:

```bash
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:

```bash
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:

```bash
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:

```bash
kubectl get pods -n demo-nginx
```

Output is similar to:

```bash
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.

   ```bash
   vcluster disconnect
   ```

1. Check namespaces in the host cluster.

   ```bash
   kubectl get namespaces
   ```

   Output is similar to:

   ```bash {3}
   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.

1. Look for the NGINX deployment.

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

   ```bash
   kubectl get deployments -n vcluster-my-cluster
   ```

   Output is similar to:

   ```bash
   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.

1. Look for the NGINX pods.

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

   ```bash
   kubectl get pods -n vcluster-my-cluster
   ```

   Output is similar to:

   ```bash {4-5}
   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
   ```

   :::info 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.





