Kubernetes distro
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.
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.
k8s
required object pro​enabled
required boolean false pro​
Enabled specifies if the K8s distro should be enabled. Only one distro can be enabled at the same time.
enabled
required boolean false pro​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).
version
required string pro​apiServer
required object pro​
APIServer holds configuration specific to starting the api server.
apiServer
required object pro​enabled
required boolean true pro​
Enabled signals this container should be enabled.
enabled
required boolean true pro​image
required object pro​
Image is the distro image
image
required object pro​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.
registry
required string registry.k8s.io pro​repository
required string kube-apiserver pro​
Repository is the repository of the container image, e.g. my-repo/my-image
repository
required string kube-apiserver pro​tag
required string v1.30.2 pro​
Tag is the tag of the container image, e.g. latest
tag
required string v1.30.2 pro​imagePullPolicy
required string pro​
ImagePullPolicy is the pull policy for the distro image
imagePullPolicy
required string pro​command
required string[] [] pro​
Command is the command to start the distro binary. This will override the existing command.
command
required string[] [] pro​extraArgs
required string[] [] pro​
ExtraArgs are additional arguments to pass to the distro binary.
extraArgs
required string[] [] pro​controllerManager
required object pro​
ControllerManager holds configuration specific to starting the controller manager.
controllerManager
required object pro​enabled
required boolean true pro​
Enabled signals this container should be enabled.
enabled
required boolean true pro​image
required object pro​
Image is the distro image
image
required object pro​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.
registry
required string registry.k8s.io pro​repository
required string kube-controller-manager pro​
Repository is the repository of the container image, e.g. my-repo/my-image
repository
required string kube-controller-manager pro​tag
required string v1.30.2 pro​
Tag is the tag of the container image, e.g. latest
tag
required string v1.30.2 pro​imagePullPolicy
required string pro​
ImagePullPolicy is the pull policy for the distro image
imagePullPolicy
required string pro​command
required string[] [] pro​
Command is the command to start the distro binary. This will override the existing command.
command
required string[] [] pro​extraArgs
required string[] [] pro​
ExtraArgs are additional arguments to pass to the distro binary.
extraArgs
required string[] [] pro​scheduler
required object pro​
Scheduler holds configuration specific to starting the scheduler. Enable this via controlPlane.advanced.virtualScheduler.enabled
scheduler
required object pro​image
required object pro​
Image is the distro image
image
required object pro​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.
registry
required string registry.k8s.io pro​repository
required string kube-scheduler pro​
Repository is the repository of the container image, e.g. my-repo/my-image
repository
required string kube-scheduler pro​tag
required string v1.30.2 pro​
Tag is the tag of the container image, e.g. latest
tag
required string v1.30.2 pro​imagePullPolicy
required string pro​
ImagePullPolicy is the pull policy for the distro image
imagePullPolicy
required string pro​command
required string[] [] pro​
Command is the command to start the distro binary. This will override the existing command.
command
required string[] [] pro​extraArgs
required string[] [] pro​
ExtraArgs are additional arguments to pass to the distro binary.
extraArgs
required string[] [] pro​env
required object[] [] pro​
Env are extra environment variables to use for the main container and NOT the init container.
env
required object[] [] pro​resources
required object map[limits:map[cpu:100m memory:256Mi] requests:map[cpu:40m memory:64Mi]] pro​
Resources for the distro init container
resources
required object map[limits:map[cpu:100m memory:256Mi] requests:map[cpu:40m memory:64Mi]] pro​securityContext
required object {} pro​
Security options can be used for the distro init container
securityContext
required object {} pro​