Deployment Basics
There are multiple ways to deploy and manage your vCluster. Review the different choices and choose the one that suits your needs.
Pre-Deployment 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 brand 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.
- Multi-Namespace Mode - Run the workloads on the host cluster in a different namespace from the namespace running the vCluster pod.
- Rootless Mode - Deploy the vCluster pod without root access to the host cluster.
Other Options
Backing Store Options
vCluster allows you to use either etcd or a relational database via KINE as a backend. This feature provides flexibility to vCluster operators. The available datastore options allow you to select a datastore that best fits your use case.
vCluster supports the following datastore options:
- Embedded SQLite (default with Persistent Volume)
- PostgreSQL
- MySQL
- MariaDB
- etcd
Changing the backing store of vCluster is not supported once deployed except for migrating from SQLite to embedded etcd.
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 wil use a persistent volume claim to store the data in. You can also instead use an emptyDir to store the virtual cluster data.
In order to use an emptyDir to store the data instead of a persistent volume, please 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 will be lost upon pod recreation.
This is a pro only feature, but allows you to deploy etcd within each vCluster that allows you to use HA (which embedded SQLite doesn't allow):
controlPlane:
backingStore:
etcd:
embedded:
enabled: true
This will deploy an etcd instance alongside vCluster that is used as a backing store:
controlPlane:
backingStore:
etcd:
deploy:
enabled: true
In its most common form, the option for MySQL and MariaDB 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 will attempt to create it.
In its most common form, the option for PostgreSQL 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 on these, please see https://godoc.org/github.com/lib/pq.
If you specify a database name and it does not exist, the server will attempt to create it.
vCluster Kubernetes Distribution Options
vCluster is able to use different Kubernetes distributions as a virtual cluster distribution.
After deploying your vCluster, changing the Kubernetes distribution of vCluster is not supported.
By default, the distribution of vCluster is vanilla Kubernetes and is the recommended distribution to use.
There are 2 other options of distributions for vCluster.
- k3s is a highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances.
- k0s is an all-inclusive Kubernetes distribution, which is configured with all of the features needed to build a Kubernetes cluster and packaged as a single binary for ease of use. Please note that dual stack networking is not supported with k0s, you will be able to deploy it on a dual stack host cluster, but it will not have all the dual stack features.
Pre-requisites
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
All of the deployment options deploy a vCluster called my-vcluster
into a namespace team-x
using the vCluster Helm chart. Each example expects a vcluster.yaml
, which is an optional configuration file. Refer to the vcluster.yaml
reference docs to explore all configuration options.
Since the vCluster v0.20 release is in beta, you need to specify the vCluster version as Helm doesn't deploy pre-releases automatically.
The vcluster.yaml
is optional, so feel free to update the example and remove the file.
- vCluster CLI
- Helm
- Terraform
- Argo CD
- Cluster API
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
Deploy vCluster.
vcluster create my-vcluster --namespace team-x --values vcluster.yaml
When the installation finishes, you are automatically connected to the virtual cluster. You Kubernetes context is updated to point to your new virtual cluster. You can run local
kubectl
commands for the new virtual cluster.
Create the "team-x" namespace.
kubectl create namespace team-x
Deploy vCluster using
helm upgrade
, which can be used to deploy a new vCluster or re-deploy an existing vCluster with newvcluster.yaml
values.helm upgrade --install my-vcluster vcluster \
--values vcluster.yaml \
--repo https://charts.loft.sh \
--namespace team-x \
--repository-config='' \
--version 0.20.0-beta.12
Create a
main.tf
file.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"
version = "0.20.0-beta.12"
values = [
file("${path.module}/vcluster.yaml")
]
}Install the required Helm provider.
terraform init
Generate a plan.
terraform plan
Verify that the provider can access your cluster and that the proposed changes are correct.
Deploy vCluster.
terraform apply
To deploy vCluster using ArgoCD, you need the following files:
vcluster.yaml
for your configuration options of your vCluster.my-vcluster-app.yaml
for your ArgoCDApplication
definition.
Create the ArgoCD
Application
filemy-vcluster-app.yaml
, which refers to the vCluster Helm chart.apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-vcluster
namespace: argocd
spec:
project: default
source:
chart: vcluster
repoURL: https://charts.loft.sh
targetRevision: 0.20.0-beta.12
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 and synchronize it with your configured cluster.
Install the
clusterctl
CLI.Install the vCluster provider.
clusterctl init --infrastructure vcluster:v0.2.0-alpha.2
Generate the required manifests and apply using
clusterctl generate cluster
andkubectl
.export CLUSTER_NAME=my-vcluster
export CLUSTER_NAMESPACE=team-x
export KUBERNETES_VERSION=1.29.3
export HELM_VALUES=$(awk '{printf "%s\\n", $0}' vcluster.yaml)
export CHART_VERSION=0.20.0-beta.12
kubectl create namespace ${CLUSTER_NAMESPACE}
clusterctl generate cluster ${CLUSTER_NAME} \
--infrastructure vcluster \
--kubernetes-version ${KUBERNETES_VERSION} \
--target-namespace ${CLUSTER_NAMESPACE} | kubectl apply -f -Execute the following command to wait for the vCluster custom resource to report a ready status.
kubectl wait --for=condition=ready vcluster -n $CLUSTER_NAMESPACE $CLUSTER_NAME --timeout=300s
Learn more about Cluster API Provider for vCluster.
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 a vCluster Platform, read more about how to deploy virtual clusters in the Platform.