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.

Control Plane Options

Decide the various options of how you want your control plane deployed:

• High availability - Run multiple copies of vCluster components.
• Rootless mode - Deploy the vCluster pod without root access to the host cluster.
• Backing Store - Decide how the data of your cluster is stored.
  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

  warning

  After deploying your vCluster, there are limited migration paths to change your backing store. Review the backing store migration options before deploying.

  Backing store 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 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

  Potential data loss

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

  Embedded etcd

  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

  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

  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.

  PostgreSQL

  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.

Worker Nodes

Decide where you want your worker nodes to come from:

• Nodes from the host cluster - (Default) All worker nodes of the shared host cluster are used by the virtual cluster and all resources are synced to the single namespace that the vCluster is deployed on.
  • Syncing Namespaces - Resources are synced to mapped namespaces on the host cluster.
  • Isolated workloads - Different options to isolate a workload in a vCluster.
• Private Nodes - Enable adding individual nodes to the virtual cluster.

Prerequisites

Prerequisites depend on your deployment model. Pick your path before continuing.

Kubernetes Cluster

• kubectl
• Helm v3.10.0+
• Access to a Kubernetes v1.28+ cluster with permissions to deploy applications into a namespace. No cluster-admin or cluster-wide permissions are required. This cluster acts as the Control Plane Cluster for the tenant cluster deployment.

Docker (vind)

• kubectl
• Docker installed and running

No Kubernetes cluster required.

Detailed instructions are provided for specific Control Plane Cluster environments: EKS, AKS, GKE, and OpenShift.

Deploy vCluster

YAML configuration

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 what type of worker nodes or the backing store — can only be set during the initial deployment and cannot be changed during an upgrade.

All of the deployment options below have the following assumptions:

• A vcluster.yaml is provided. Refer to the vcluster.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.

vCluster CLI

The vCluster CLI provides the most straightforward way to deploy and manage virtual clusters.

1. Install the vCluster CLI:

   Homebrew

   brew install loft-sh/tap/vcluster

   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/latest/download/vcluster-darwin-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

   Mac (Silicon/ARM)

   curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

   Linux (AMD)

   curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-linux-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

   Linux (ARM)

   curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-linux-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

   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/latest/download/vcluster-windows-amd64.exe" -o $Env:APPDATA\vcluster\vcluster.exe;
   $env:Path += ";" + $Env:APPDATA + "\vcluster";
   [Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);

   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.

   Verify the CLI installed successfully.

   vcluster --version

   Output is similar to:

   vCluster version 0.x.x

2. Deploy vCluster:

   Modify the following with your specific values to generate a copyable command:

   CLUSTER NAME

   NAMESPACE

   CONFIG FILE

   vcluster create my-vcluster --namespace team-x --values vcluster.yaml

   note

   After installation, vCluster automatically switches your Kubernetes context to the new virtual cluster. You can now run kubectl commands against the virtual cluster.

Helm

Helm provides fine-grained control over the deployment process and integrates well with existing Helm-based workflows.

1. Deploy vCluster using the helm upgrade command:

   Modify the following with your specific values to generate a copyable command:

   CLUSTER NAME

   CONFIG FILE

   NAMESPACE

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

Terraform

You can use Terraform to deploy vCluster as code with version control and state management.

1. 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")
     ]
   }

   Helm Provider Version

   This configuration uses the Terraform Helm provider v3.x syntax where kubernetes is defined as an argument (kubernetes = {). If you're using Helm provider v2.x, use the block syntax instead (kubernetes {). To use v3.x, ensure your provider version is at least v3.0.0.

2. Install the required Helm provider and initialize Terraform:

   terraform init

3. Generate a plan to preview the changes:

   terraform plan

   
   

   Review the plan output to verify connectivity and proposed changes.

4. Deploy vCluster:

   terraform apply

ArgoCD

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 ArgoCD Application definition. Replace <CLUSTER_NAME> with your actual cluster name.

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

   CLUSTER NAME

   NAMESPACE

   ---
   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. Sync your ArgoCD repository with your configured cluster:

   Modify the following with your specific values to generate a copyable command:

   CLUSTER NAME

   argocd app sync my-vcluster

Flux

1. Create a HelmRepository source in the Git repository that Flux monitors, so Flux can fetch the vCluster Helm charts automatically. In this example, the related files are stored under the clusters folder. Save the following file as clusters/sources/vcluster-repository.yaml:

   Modify the following with your specific values to generate a copyable command:

   REPOSITORY NAME

   FLUX NAMESPACE

   ---
   apiVersion: source.toolkit.fluxcd.io/v1
   kind: HelmRepository
   metadata:
     name: vcluster
     namespace: flux-system
   spec:
     interval: 1h
     url: https://charts.loft.sh

2. The vCluster will be deployed into the namespace team-x of the host cluster. If this namespace doesn’t already exist, create it with:

   Modify the following with your specific values to generate a copyable command:

   NAMESPACE

   kubectl create namespace team-x

3. Create a vCluster HelmRelease file in your Git repository. This HelmRelease tells Flux how to deploy a vCluster in your Kubernetes cluster using the configured Helm charts in Step 1. Save the following file as clusters/production/vcluster-demo.yaml:

   Modify the following with your specific values to generate a copyable command:

   RELEASE NAME

   NAMESPACE

   REPOSITORY NAME

   FLUX NAMESPACE

   SECRET NAME

   ---
   apiVersion: helm.toolkit.fluxcd.io/v2
   kind: HelmRelease
   metadata:
     name: vcluster-demo
     namespace: team-x
   spec:
     interval: 10m
     chart:
       spec:
         chart: vcluster
         version: "0.28.x"
         sourceRef:
           kind: HelmRepository
           name: vcluster
           namespace: flux-system
     values:
       # Configure TLS SAN for the certificate
       controlPlane:
         proxy:
           extraSANs:
             - "vcluster-demo.team-x.svc.cluster.local"
         coredns:
           enabled: true
   
       exportKubeConfig:
         # Set a meaningful context name
         context: default
         # Use a server URL that matches the TLS SAN
         server: https://vcluster-demo.team-x.svc.cluster.local:443
         # Skip TLS verification when Flux connects to the vCluster
         insecure: true
         # Specify the secret where the KubeConfig is stored
         secret:
           name: vcluster-flux-kubeconfig
       sync:
         toHost:
           ingresses:
             enabled: true

   The content in vcluster.yaml should be placed under the values.

   Unlike ArgoCD, Flux requires the KubeConfig secret to be able to access the vCluter's API server and deploy to vCluster. The exportKubeConfig configuration under values:

   • Exports the virtual cluster KubeConfig as a Secret in the host namespace
   • Makes the Secret available for Flux to use with the spec.kubeConfig field
   • Uses a server URL that is accessible from the Flux controllers (replace vcluster-name and team-x with your actual values)
   • Sets insecure: true to automatically skip TLS certificate verification
   • Adds a TLS SAN (Subject Alternative Name) that matches the server URL, which helps prevent certificate verification errors
   KubeConfig Secret key

   The vCluster exportKubeConfig configuration creates a Secret with the KubeConfig data stored under the key config. When referring to this Secret in Flux resources, you must specify this key in the secretRef.key field, as shown in the examples below.

   Modify the following with your specific values to generate a copyable command:

   SECRET NAME

   # In Flux HelmRelease
   spec:
   kubeConfig:
     secretRef:
       name: vcluster-flux-kubeconfig
       key: config  # Must match the key used in the vCluster-generated Secret

   Certificate verification considerations

   When using vCluster with Flux, proper TLS certificate configuration is essential:

   1. Set exportKubeConfig.insecure: true in your vCluster configuration
   2. Configure proper TLS SANs with the --tls-san flag in vCluster configuration
   3. Ensure the server URL matches the certificate's SAN

   Modify the following with your specific values to generate a copyable command:

   RELEASE NAME

   NAMESPACE

   
   # In your vCluster configuration
   controlPlane:
   proxy:
     extraSANs:
       - "vcluster-demo.team-x.svc.cluster.local"
   
   exportKubeConfig:
   server: https://vcluster-demo.team-x.svc.cluster.local:443
   insecure: true

4. After adding the HelmRelease and any supporting files to your Git repository, commit and push them:

   Modify the following with your specific values to generate a copyable command:

   FOLDER NAME

   git add clusters/
   git commit -m "Add vCluster demo configuration"
   git push

   Once the changes are pushed, Flux will automatically detect them and deploy the vCluster according to the configuration in your repository.

Cluster API

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.

1. Install the clusterctl CLI.

2. Install the vCluster provider:

   clusterctl init --infrastructure vcluster:v0.2.0

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

   CLUSTER NAME

   NAMESPACE

   CONFIG FILE

   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 using the exported variable:

   Modify the following with your specific values to generate a copyable command:

   CLUSTER NAMESPACE

   kubectl create namespace team-x

5. Generate the required manifests and apply them using the exported variables:

   Modify the following with your specific values to generate a copyable command:

   CLUSTER NAME

   CLUSTER NAMESPACE

   clusterctl generate cluster my-vcluster \
     --infrastructure vcluster \
     --target-namespace team-x \
   | kubectl apply -f -

   Kubernetes version

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

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

   CLUSTER NAMESPACE

   CLUSTER NAME

   kubectl wait --for=condition=ready vcluster -n team-x my-vcluster --timeout=300s

Deploy with vCluster Platform

Tenant clusters can be deployed directly as described above, or managed centrally through vCluster Platform — a management UI for tenant clusters, access control, and lifecycle operations.

There are many features included as part of vCluster Platform beyond central management.

If you already have vCluster Platform, learn how to deploy tenant clusters in the platform.