Skip to main content

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:

warning

Changing the backing store of vCluster is not supported once deployed except for migrating from SQLite to embedded etcd.

Configuration Options​

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

The following distributions are supported for virtual clusters:

  • k8s: By default, the vCluster distribution is vanilla Kubernetes, which is the recommended distribution to use.
  • k3s: A highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances.
  • k0s: 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.

Note:

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 should work when deployed on a host cluster with the following supported Kubernetes versions:

  • v1.30
  • v1.29
  • v1.28

Pre-requisites​

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.

  1. Install the vCluster CLI.

    brew install loft-sh/tap/vcluster

    The binaries in the tap are signed using the Sigstore framework for enhanced security.

    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.

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.