Kubernetes distro

info

vCluster uses Kubernetes as the default distribution for the virtual cluster.

By default, vCluster uses an embedded SQLite as the backing store when you use the K8s distribution.

warning

After deploying your vCluster, changing the Kubernetes distribution of vCluster is not supported.

Compatiblity matrix

Host cluster compatibility

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

vCluster should work when deployed on a host cluster with the following supported Kubernetes versions:

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

Kubernetes Compatibility Matrix:

The following matrix shows the compatibility between host and virtual clusters when both are using vanilla Kubernetes. It indicates which versions of vanilla Kubernetes on the host cluster support which versions of vanilla Kubernetes on the virtual cluster.

Host K8s ↓ / vCluster k8s →	v1.30	v1.29	v1.28
v1.30	✅	🆗	🆗
v1.29	🆗	✅	🆗
v1.28	🆗	🆗	✅

Legend:

✅ : Tested and verified

🆗 : likely compatible

Config reference

k8s required object pro

K8S holds K8s relevant configuration.

enabled required boolean false pro

Enabled specifies if the K8s distro should be enabled. Only one distro can be enabled at the same time.

version required string pro

Version specifies k8s components (scheduler, kube-controller-manager & apiserver) version. It is a shortcut for controlPlane.distro.k8s.apiServer.image.tag, controlPlane.distro.k8s.controllerManager.image.tag and controlPlane.distro.k8s.scheduler.image.tag If e.g. controlPlane.distro.k8s.version is set to v1.30.1 and controlPlane.distro.k8s.scheduler.image.tag (or controlPlane.distro.k8s.controllerManager.image.tag or controlPlane.distro.k8s.apiServer.image.tag) is set to v1.31.0, value from controlPlane.distro.k8s.(controlPlane-component).image.tag will be used (where (controlPlane-component is apiServer, controllerManager and scheduler).

apiServer required object pro

APIServer holds configuration specific to starting the api server.

enabled required boolean true pro

Enabled signals this container should be enabled.

image required object pro

Image is the distro image

registry required string registry.k8s.io pro

Registry is the registry of the container image, e.g. my-registry.com or ghcr.io. This setting can be globally overridden via the controlPlane.advanced.defaultImageRegistry option. Empty means docker hub.

repository required string kube-apiserver pro

Repository is the repository of the container image, e.g. my-repo/my-image

tag required string v1.30.2 pro

Tag is the tag of the container image, e.g. latest

imagePullPolicy required string pro

ImagePullPolicy is the pull policy for the distro image

command required string[] [] pro

Command is the command to start the distro binary. This will override the existing command.

extraArgs required string[] [] pro

ExtraArgs are additional arguments to pass to the distro binary.

controllerManager required object pro

ControllerManager holds configuration specific to starting the controller manager.

enabled required boolean true pro

Enabled signals this container should be enabled.

image required object pro

Image is the distro image

registry required string registry.k8s.io pro

Registry is the registry of the container image, e.g. my-registry.com or ghcr.io. This setting can be globally overridden via the controlPlane.advanced.defaultImageRegistry option. Empty means docker hub.

repository required string kube-controller-manager pro

Repository is the repository of the container image, e.g. my-repo/my-image

tag required string v1.30.2 pro

Tag is the tag of the container image, e.g. latest

imagePullPolicy required string pro

ImagePullPolicy is the pull policy for the distro image

command required string[] [] pro

Command is the command to start the distro binary. This will override the existing command.

extraArgs required string[] [] pro

ExtraArgs are additional arguments to pass to the distro binary.

scheduler required object pro

Scheduler holds configuration specific to starting the scheduler. Enable this via controlPlane.advanced.virtualScheduler.enabled

image required object pro

Image is the distro image

registry required string registry.k8s.io pro

Registry is the registry of the container image, e.g. my-registry.com or ghcr.io. This setting can be globally overridden via the controlPlane.advanced.defaultImageRegistry option. Empty means docker hub.

repository required string kube-scheduler pro

Repository is the repository of the container image, e.g. my-repo/my-image

tag required string v1.30.2 pro

Tag is the tag of the container image, e.g. latest

imagePullPolicy required string pro

ImagePullPolicy is the pull policy for the distro image

command required string[] [] pro

Command is the command to start the distro binary. This will override the existing command.

extraArgs required string[] [] pro

ExtraArgs are additional arguments to pass to the distro binary.

env required object[] [] pro

Env are extra environment variables to use for the main container and NOT the init container.

resources required object map[limits:map[cpu:100m memory:256Mi] requests:map[cpu:40m memory:64Mi]] pro

Resources for the distro init container

securityContext required object {} pro

Security options can be used for the distro init container