Skip to main content
Version: v0.25

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, there are limited migration paths to change your backing store. Review the backing store migration options before deploying.

Compatibility 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 supports specific Kubernetes versions on host clusters. For more information, see the Kubernetes compatibility matrix.

Configure Kubernetes version and image options​

When using the K8s distribution, you can configure the container image for the Kubernetes components. The K8s distribution deploys the API server, controller manager, and scheduler as a single container from the loft-sh/kubernetes repository.

You can customize the container image by specifying the registry, repository, and tag in your vCluster configuration:

vcluster.yaml
controlPlane:
  distro:
    k8s:
      image:
        registry: ghcr.io           # Default: ghcr.io (can be overridden globally with controlPlane.advanced.defaultImageRegistry)
        repository: loft-sh/kubernetes  # Default: loft-sh/kubernetes
        tag: v1.32.1                # Default: v1.32.1 (or matches host Kubernetes version)

The tag field specifies the Kubernetes version to use. By default, it uses v1.32.1 or matches the host cluster's Kubernetes version.

note

The controlPlane.distro.k8s.version field is deprecated. Use controlPlane.distro.k8s.image.tag instead to specify the Kubernetes version.

Config reference​

k8s required object ​

K8S holds K8s relevant configuration.

enabled required boolean false ​

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

version required string ​

[Deprecated] Version field is deprecated. Use controlPlane.distro.k8s.image.tag to specify the Kubernetes version instead.

apiServer required object ​

APIServer holds configuration specific to starting the api server.

enabled required boolean true ​

Enabled signals this container should be enabled.

command required string[] [] ​

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

extraArgs required string[] [] ​

ExtraArgs are additional arguments to pass to the distro binary.

controllerManager required object ​

ControllerManager holds configuration specific to starting the controller manager.

enabled required boolean true ​

Enabled signals this container should be enabled.

command required string[] [] ​

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

extraArgs required string[] [] ​

ExtraArgs are additional arguments to pass to the distro binary.

scheduler required object ​

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

command required string[] [] ​

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

extraArgs required string[] [] ​

ExtraArgs are additional arguments to pass to the distro binary.

image required object ​

Image is the distro image

registry required string ghcr.io ​

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 loft-sh/kubernetes ​

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

tag required string v1.32.1 ​

Tag is the tag of the container image, e.g. latest. If set to the default, it will use the host Kubernetes version.

imagePullPolicy required string ​

ImagePullPolicy is the pull policy for the distro image

env required object[] [] ​

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]] ​

Resources for the distro init container

securityContext required object {} ​

Security options can be used for the distro init container