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

warning

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)

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

Embedded SQLite (No PV)

By default, vCluster uses 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

Potential Data Loss

This method should only be used for testing purposes, as data is lost upon pod recreation.

Embedded Etcd

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

Deployed Etcd

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

MySQL / MariaDB

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.

Postgresql

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, 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 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.

warning

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.

Deprecation notice

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.

The Kubernetes distro of vCluster is completely independent of the Kubernetes distro of the host cluster. This means you can run vCluster using any supported Kubernetes distribution distribution regardless of the distribution type of the host cluster.

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.

Host Cluster Requirements

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:

1. A vcluster.yaml is provided. Refer to the vcluster.yaml reference docs to explore all configuration options. Note: This file is optional and can be removed from the examples.
2. The vCluster will be called my-vcluster.
3. The vCluster will be deployed into the team-x namespace.

vcluster.yaml configuration

If 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) that can only be defined during deployment and not changed during upgrade.

vCluster CLI

1. Install the vCluster CLI.

   Homebrew

    brew install loft-sh/tap/vcluster-experimental

   If you installed the CLI using brew install vcluster, you should brew uninstall vcluster and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.

   Mac (Intel/AMD)

   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.

   Mac (Silicon/ARM)

   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.

   Linux (AMD)

   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.

   Linux (ARM)

   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 Binary

   Download the binary for your platform from the GitHub Releases page and add this binary to your $PATH.

   Windows Powershell

   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 Required

   You may need to reboot your computer to use the CLI due to changes to the PATH variable (see below).

   Check Environment Variable $PATH

   Line 4 of this install script adds the install directory %APPDATA%\vcluster to the $PATHenvironment 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 the PATH 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

2. 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.

Helm

1. Deploy vCluster using helm upgrade command.

   helm upgrade --install my-vcluster vcluster \
   --values vcluster.yaml \
   --repo https://charts.loft.sh \
   --namespace team-x \
   --repository-config='' \
   --create-namespace

Terraform

1. 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"
   
     # If you didn't create a vcluster.yaml, remove the values section.
     values = [
       file("${path.module}/vcluster.yaml")
     ]
   }

2. Install the required Helm provider.

   terraform init

3. Generate a plan.

   terraform plan

   Verify that the provider can access your cluster and that the proposed changes are correct.

4. Deploy vCluster.

   terraform apply

Argo CD

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 ArgoCD Application definition.

1. Create the ArgoCD Application file my-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
       helm:
         releaseName: my-vcluster
         valueFiles:
           - vcluster.yaml
     destination:
       server: https://kubernetes.default.svc
       namespace: team-x

2. Commit and push these files to your configured ArgoCD repository.

3. Synchronize your ArgoCD repository with your configured cluster.

Cluster API

Learn more about Cluster API Provider for vCluster.

1. Install the clusterctl CLI.

2. Install the vCluster provider.

   clusterctl init --infrastructure vcluster:v0.2.0

3. Export environment variables to be used by the cluster API provider to create the manifest. The manifest is applied to your Kubernetes cluster, which will deploy a vCluster.

    export CLUSTER_NAME=my-vcluster
    export CLUSTER_NAMESPACE=team-x
    export VCLUSTER_YAML=$(awk '{printf "%s\\n", $0}' vcluster.yaml)

4. Create the namespace for the vCluster.

    kubectl create namespace ${CLUSTER_NAMESPACE}

5. Generate the required manifests and apply them.

    clusterctl generate cluster ${CLUSTER_NAME} \
      --infrastructure vcluster \
      --target-namespace ${CLUSTER_NAMESPACE} \
       | kubectl apply -f -

   Kubernetes Version

   The Kubernetes version for the vCluster is not set at the CAPI provider command. It is configured the vcluster.yaml file based on your Kubernetes distribution.

6. Wait for vCluster to come up by watching for the vCluster custom resource to report a ready status.

   kubectl wait --for=condition=ready vcluster -n $CLUSTER_NAMESPACE $CLUSTER_NAME --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 a vCluster Platform, read more about how to deploy virtual clusters in the Platform.