Kubernetes distributions

By default, vCluster will use k3s as a virtual Kubernetes cluster, which is a highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances.

However, vCluster is not tied to a specific distribution and should work with all certified Kubernetes distributions. By default, we recommend using k3s, because it has a small footprint and is widely adopted, but if your use case requires a different k8s distribution, vCluster currently also supports k0s or vanilla k8s. If that is not enough, you can also add your custom Kubernetes distribution as outlined below.

k0s

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. vCluster supports k0s as a backing virtual Kubernetes cluster.

In order to use k0s as a backing cluster, create a vCluster with the following command:

vcluster create my-vcluster --distro k0s

Start using it:

kubectl get ns
...

Behind the scenes, a different helm chart will be deployed (vcluster-k0s), that holds specific configurations to support k0s. Check the github repository for all available chart options.

Vanilla k8s

When choosing this option, vCluster will deploy a separate etcd cluster, Kubernetes controller manager, and API server alongside the vCluster hypervisor.

In order to use vanilla k8s as a backing cluster, create a vCluster with the following command:

vcluster create my-vcluster --distro k8s

Connect to the vCluster and start using it:

kubectl get ns
...

Behind the scenes, a different helm chart will be deployed (vcluster-k8s), that holds specific configuration to support vanilla k8s. Check the GitHub repository for all available chart options.

Other Distributions

vCluster has no dependencies on any specific Kubernetes distribution, so you should be able to run it with most certified Kubernetes distributions. One requirement vCluster has, is that the distribution can be deployed without a scheduler and kubelet, meaning that vCluster just requires the API server, controller manager and data storage of the distribution.

For single binary distributions, such as k3s or k0s, extra bundled components can usually be disabled through flags, for multi binary distributions, such as vanilla k8s, you just need to deploy the virtual control plane with API server, controller manager and usually etcd. Most multi-binary distributions work by just overriding the images of the k8s chart in a values.yaml, e.g.:

api:
  image: custom-domain.com/custom-kube-apiserver:v1.21.5
controller:
  image: custom-domain.com/custom-kube-controller-manager:v1.21.5
etcd:
  image: custom-domain.com/custom-etcd:v3.4.16

And then deploy vCluster with:

vcluster create my-vcluster -n test --distro k8s -f values.yaml

If you want to create a separate chart for the Kubernetes distribution, a good starting point is to copy one of our distro charts and then modify it to work with your distribution. vCluster only needs the following information from the virtual Kubernetes distribution to function properly:

1. The API server central authority certificate (usually found at /pki/ca.crt)
2. The API server central authority key (usually found at /pki/ca.key)
3. An admin kube config to contact the virtual Kubernetes control plane (usually found at /pki/admin.conf)

For multi-binary distributions, vCluster can even create those with a pre-install hook as found in the k8s chart.

In general, if you need vCluster to support another Kubernetes distribution, we are always happy to help you or accept a pull request in our GitHub repository.