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
- Helm v3.10.0+
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, Cluster API, etc. Read about our additional options in the deployment section of the docs.
Install the vCluster CLI.
- Homebrew
- Mac (Intel/AMD)
- Mac (Silicon/ARM)
- Linux (AMD)
- Linux (ARM)
- Download Binary
- Windows Powershell
brew install loft-sh/tap/vcluster-experimental
If you installed the CLI using
brew install vcluster
, you shouldbrew uninstall vcluster
and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/v0.20.0-beta.12/vcluster-darwin-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/v0.20.0-beta.12/vcluster-darwin-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/v0.20.0-beta.12/vcluster-linux-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/v0.20.0-beta.12/vcluster-linux-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
Download the binary for your platform from the GitHub Releases page and add this binary to your $PATH.
md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12';
Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/download/v0.20.0-beta.12/vcluster-windows-amd64.exe" -o $Env:APPDATA\vcluster\vcluster.exe;
$env:Path += ";" + $Env:APPDATA + "\vcluster";
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);Reboot RequiredYou may need to reboot your computer to use the CLI due to changes to the PATH variable (see below).
Check Environment Variable $PATHLine 4 of this install script adds the install directory
%APPDATA%\vcluster
to the$PATH
environment variable. This is only effective for the current Powershell session, i.e. when opening a new terminal window,vcluster
may not be found.Make sure to add the folder
%APPDATA%\vcluster
to thePATH
environment variable after installing vcluster CLI via Powershell. Afterward, a reboot might be necessary.Confirm that you've installed the correct version of the vCluster CLI.
vcluster --version
(Optional) Create a
vcluster.yaml
to configure your vCluster. Various configuration options can be configured prior to deploying your vCluster, but even without avcluster.yaml
, the vCluster can be deployed with a default configuration.Refer to the
vcluster.yaml
reference docs to explore all configuration options.vcluster.yaml configurationIf 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.Deploy vCluster using vCluster CLI. There are other methods to deploy vCluster, but this is the quickest way to get started.
- Default (No vcluster.yaml)
- With vcluster.yaml
vcluster create my-vcluster --namespace team-x
Include your
vcluster-yaml
config file.vcluster create my-vcluster --namespace team-x --values vcluster.yaml
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:
Disconnect from the current virtual cluster and switch back to the host context.
vcluster disconnect
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 30mLook 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.
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 20mYou 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.
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.
Modify
vcluster.yaml
so that vCluster creates the required Ingress resource.controlPlane:
ingress:
enabled: true
host: VCLUSTER_HOSTNAME
proxy:
extraSANs:
- VCLUSTER_HOSTNAMEReplace
VCLUSTER_HOSTNAME
with your vCluster instance's hostname.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.
Modify
vcluster.yaml
to sync the nodes from the host cluster to the virtual cluster.sync:
fromHost:
nodes:
enabled: trueReplace
VCLUSTER_HOSTNAME
with your vCluster instance's hostname.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.
Modify
vcluster.yaml
to sync the IngressClasses from the host cluster to the virtual cluster.sync:
fromHost:
ingressClasses:
enabled: trueReplace
VCLUSTER_HOSTNAME
with your vCluster instance's hostname.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.
Modify
vcluster.yaml
to sync the ingresses from the virtual cluster to the host cluster.sync:
toHost:
ingresses:
enabled: trueReplace
VCLUSTER_HOSTNAME
with your vCluster instance's hostname.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
.
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-serviceReplace
VCLUSTER_HOSTNAME
with your vCluster instance's hostname.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