Lightweight Kubernetes K3s
Lightweight Kubernetes (K3s) is a highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances. See the K3s docs for K3s' features.
To use K3s with default deployment options, add the following to your vcluster.yaml
config file:
controlPlane:
distro:
k3s:
enabled: true
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 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.30
- v1.29
- v1.28
Config reference​
k3s
required object pro​
K3S holds K3s relevant configuration.
k3s
required object pro​enabled
required boolean false pro​
Enabled specifies if the K3s distro should be enabled. Only one distro can be enabled at the same time.
enabled
required boolean false pro​token
required string pro​
Token is the K3s token to use. If empty, vCluster will choose one.
token
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​image
required object pro​
Image is the distro image
image
required object pro​registry
required string 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 pro​repository
required string rancher/k3s pro​
Repository is the repository of the container image, e.g. my-repo/my-image
repository
required string rancher/k3s pro​tag
required string v1.30.2-k3s1 pro​
Tag is the tag of the container image, e.g. latest
tag
required string v1.30.2-k3s1 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​