Skip to main content
Version: v0.26 Stable

Lightweight Kubernetes K3s

Deprecation notice

Support for K3s is deprecated. Migration to a supported Kubernetes distribution is recommended.

Lightweight Kubernetes (K3s) is a highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances. For more information on features, see the K3s documentation.

To use K3s with default deployment options, add the following to your vcluster.yaml config file:

controlPlane:
  distro:
    k3s:
      enabled: true
warning

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

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 k3s 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.32
  • v1.31
  • v1.30

Config reference​

k3s required object ​

[Deprecated] K3S holds K3s relevant configuration.

enabled required boolean false ​

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

token required string ​

Token is the K3s token to use. If empty, vCluster will choose one.

image required object ​

Image is the distro image

registry required string ​

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 rancher/k3s ​

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

tag required string v1.32.1-k3s1 ​

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

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.