Deployment basics
There are multiple ways to deploy and manage your vCluster. Review the different choices and choose the one that suits your needs.
Predeployment configuration options​
Before deploying, it's recommended to review the set of configuration options that cannot be updated post deployment. These options require deploying a new vCluster instead of upgrading your vCluster with new options.
Topologies​
- High availability - Run multiple copies of vCluster components.
- Isolated workloads - Different options to isolate a workload in a vCluster.
- Isolated control plane - Run vCluster control plane in a host cluster different from the host cluster running workloads.
- Rootless mode - Deploy the vCluster pod without root access to the host cluster.
Other options​
Backing store options
vCluster supports etcd or a relational database (using KINE) as the backend.This feature provides flexibility to vCluster operators. The available data store options allow you to select a data store that fits your use case.
vCluster supports the following datastore options:
- Embedded SQLite (default with
PersistentVolume
(PV)) - PostgreSQL
- MySQL
- MariaDB
- etcd
After deploying your vCluster, there are limited migration paths to change your backing store. Review the backing store migration options before deploying.
Configuration options​
- Embedded SQLite (Default)
- Embedded SQLite (No PV)
- Embedded etcd
- Deployed etcd
- MySQL / MariaDB
- PostgreSQL
This is the default, so you don't need to configure anything. If you want to explicitly set this option, you can use:
controlPlane:
backingStore:
database:
embedded:
enabled: true
By default, vCluster stores its data in a PersistentVolumeClaim
(PVC).
Alternatively, you can use an emptyDir
volume to store virtual cluster data.
To use an emptyDir
to store the data instead of a PersistentVolume
, create a values.yaml
with the following contents:
controlPlane:
statefulSet:
persistence:
volumeClaim:
enabled: true
Then upgrade or recreate the vCluster with:
vcluster create my-vcluster -n my-vcluster --upgrade -f values.yaml
This method should only be used for testing purposes, as data is lost upon pod recreation.
This is an enterprise feature that allows you to deploy etcd within each vCluster to enable high availability (HA), which isn’t supported with embedded SQLite:
controlPlane:
backingStore:
etcd:
embedded:
enabled: true
This deploys an etcd instance outside of the vCluster control plane pod that is used as a backing store:
controlPlane:
backingStore:
etcd:
deploy:
enabled: true
The option for MySQL and MariaDB typically has the following format:
controlPlane:
backingStore:
database:
external:
enabled: true
dataSource: mysql://username:password@tcp(hostname:3306)/database-name
If you specify a database name and it does not exist, the server attempts to create it.
The option for PostgreSQL typically has the following format:
controlPlane:
backingStore:
database:
external:
enabled: true
dataSource: postgres://username:password@hostname:port/database-name
More advanced configuration parameters are available. For more information, see https://godoc.org/github.com/lib/pq.
If you specify a database name and it does not exist, the server attempts to create it.
vCluster Kubernetes distribution options
vCluster is deployed with its own Kubernetes distribution that does not need to match with the host cluster's distribution. For example, you can deploy virtual clusters with the K8s distro on top of EKS clusters.
After deploying your vCluster, changing the Kubernetes distribution of vCluster is not supported.
By default, the distribution of vCluster is vanilla Kubernetes (K8s) and is the recommended distribution to use.
Support for K0s and K3s is deprecated in vCluster v0.25
. K0s support is removed in v0.26
.
Migration to a supported Kubernetes distribution is recommended.
The following distributions are supported for virtual clusters:
- K8s: By default, vCluster uses vanilla Kubernetes. This is the recommended distribution.
- K3s: A lightweight, certified Kubernetes distribution designed for resource-constrained environments, remote locations, and IoT devices.
- K0s: A single-binary Kubernetes distribution with built-in cluster configuration. It can run on dual-stack host clusters but does not fully support dual-stack networking.
Host cluster compatibility​
vCluster supports specific Kubernetes versions on host clusters. For more information, see the Kubernetes compatibility matrix.
Prerequisites​
In order to deploy vcluster, you need the following:
- kubectl
- Helm v3.10.0+
- Access to a Kubernetes v1.28+ cluster with permissions to deploy applications into a namespace. This is considered the host cluster for the vCluster deployment.
Since vCluster runs as an application, vCluster can run on any host cluster regardless of OS or Kubernetes distribution. The Kubernetes distribution of vCluster does not need to match the Kubernetes distribution of the host cluster. For example,
you can select a vCluster with k8s
as the distro and run it on host cluster that's running EKS.
Deploy vCluster​
All of the deployment options below have the following assumptions:
- A
vcluster.yaml
is provided. Refer to thevcluster.yaml
reference docs to explore all configuration options. This file is optional and can be removed from the examples. - The vCluster is called
my-vcluster
. - The vCluster is be deployed into the
team-x
namespace.
If you're not sure which options to configure, you can update most settings later by upgrading your vCluster with an updated vcluster.yaml
.
However, some settings—such as the backing store—can only be set during the initial deployment and cannot be changed during an upgrade.
- vCluster CLI
- Helm
- Terraform
- Argo CD
- Cluster API
The vCluster CLI provides the most straightforward way to deploy and manage virtual clusters.
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/<VCLUSTER_VERSION>/vcluster-darwin-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
Replace
<VCLUSTER_VERSION>
with the version you want to download.curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/<VCLUSTER_VERSION>/vcluster-darwin-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
Replace
<VCLUSTER_VERSION>
with the version you want to download.curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/<VCLUSTER_VERSION>/vcluster-linux-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
Replace
<VCLUSTER_VERSION>
with the version you want to download.curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/download/<VCLUSTER_VERSION>/vcluster-linux-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster
Replace
<VCLUSTER_VERSION>
with the version you want to download.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/<VCLUSTER_VERSION>/vcluster-windows-amd64.exe" -o $Env:APPDATA\vcluster\vcluster.exe;
$env:Path += ";" + $Env:APPDATA + "\vcluster";
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);Replace
<VCLUSTER_VERSION>
with the version you want to download.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
Deploy vCluster:
Modify the following with your specific values to generate a copyable command:vcluster create my-vcluster --namespace team-x --values vcluster.yaml
noteAfter installation, vCluster automatically switches your Kubernetes context to the new virtual cluster. You can now run
kubectl
commands against the virtual cluster.
Helm provides fine-grained control over the deployment process and integrates well with existing Helm-based workflows.
Deploy vCluster using the
helm upgrade
command:Modify the following with your specific values to generate a copyable command:helm upgrade --install my-vcluster vcluster \
--values vcluster.yaml \
--repo https://charts.loft.sh \
--namespace team-x \
--repository-config='' \
--create-namespace
You can use Terraform to deploy vCluster as code with version control and state management.
Create a
main.tf
file to define your vCluster deployment using the Terraform Helm provider:provider "helm" {
kubernetes {
config_path = "~/.kube/config"
}
}
resource "helm_release" "my_vcluster" {
name = "my-vcluster"
namespace = "team-x"
create_namespace = true
repository = "https://charts.loft.sh"
chart = "vcluster"
# If you didn't create a vcluster.yaml, remove the values section.
values = [
file("${path.module}/vcluster.yaml")
]
}Install the required Helm provider and initialize Terraform:
terraform init
Generate a plan to preview the changes:
terraform plan
Review the plan output to verify connectivity and proposed changes.
Deploy vCluster:
terraform apply
ArgoCD deployment enables GitOps workflows for vCluster management, and provides automated deployment, drift detection, and declarative configuration management through Git repositories.
To deploy vCluster using ArgoCD, you need the following files:
vcluster.yaml
for your vCluster configuration options.<CLUSTER_NAME>-app.yaml
for your ArgoCDApplication
definition. Replace<CLUSTER_NAME>
with your actual cluster name.
Create the ArgoCD
Application
file<CLUSTER_NAME>-app.yaml
, which references the vCluster Helm chart:Modify the following with your specific values to generate a copyable command:apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-vcluster
namespace: argocd
spec:
project: default
source:
chart: vcluster
repoURL: https://charts.loft.sh
helm:
releaseName: my-vcluster
valueFiles:
- vcluster.yaml
destination:
server: https://kubernetes.default.svc
namespace: team-xCommit and push these files to your configured ArgoCD repository.
Sync your ArgoCD repository with your configured cluster:
Modify the following with your specific values to generate a copyable command:argocd app sync my-vcluster
Cluster API (CAPI) provides lifecycle management for Kubernetes clusters. The vCluster CAPI provider enables you to manage virtual clusters using the same declarative APIs and tooling used for physical clusters. For more details, see the Cluster API Provider for vCluster documentation.
Install the
clusterctl
CLI.Install the vCluster provider:
clusterctl init --infrastructure vcluster:v0.2.0
Export environment variables for the Cluster API provider to create the manifest. The manifest is applied to your Kubernetes cluster, which deploys a vCluster.
Modify the following with your specific values to generate a copyable command:export CLUSTER_NAME=my-vcluster
export CLUSTER_NAMESPACE=team-x
export VCLUSTER_YAML=$(awk '{printf "%s\n", $0}' vcluster.yaml)Create the namespace for the vCluster using the exported variable:
Modify the following with your specific values to generate a copyable command:kubectl create namespace team-x
Generate the required manifests and apply them using the exported variables:
Modify the following with your specific values to generate a copyable command:clusterctl generate cluster my-vcluster \
--infrastructure vcluster \
--target-namespace team-x \
| kubectl apply -f -Kubernetes versionThe Kubernetes version for the vCluster is not set at the CAPI provider command. Configure it in the
vcluster.yaml
file based on your Kubernetes distribution.Wait for vCluster to become ready by monitoring the vCluster custom resource status:
Modify the following with your specific values to generate a copyable command:kubectl wait --for=condition=ready vcluster -n team-x my-vcluster --timeout=300s
Deploy vCluster with the vCluster Platform​
Virtual clusters can be deployed as standalone virtual clusters on host clusters as described above, but there is also a vCluster Platform that is a UI to manage your virtual clusters, host clusters and other resources.
There are many features that are included as part of the vCluster Platform besides having a central management platform for virtual clusters.
If you already have vCluster Platform, learn how to deploy virtual clusters in the platform.