Deploy add-ons
Configure addons​
vCluster supports addons that extend the capabilities of your cluster. You can configure these addons during deployment to adjust networking, observability, and other features for your environment and requirements.
Deployed versions​
vCluster v0.38 deploys the following add-on versions:
| Add-on | Version |
|---|---|
| Metrics Server | v0.7.2 |
| Flannel | v0.26.7, with the Flannel CNI plugin v1.6.2-flannel1 |
| kube-proxy | The cluster's Kubernetes version |
| MetalLB | v0.15.2 |
| Local Path Provisioner | v0.0.31 |
| KubeVirt CSI node plugin | latest, because the KubeVirt project publishes no versioned tags for this image. The node driver registrar is v2.17.0 and the liveness probe is v2.19.0. |
vCluster doesn't check add-on versions. If you override an add-on image, the combination isn't tested, and you're responsible for its compatibility.
Metrics server​
vCluster can install the Kubernetes Metrics Server into the cluster. Enable it when you need kubectl top output or want the Horizontal Pod Autoscaler to use CPU and memory metrics.
deploy:
metricsServer:
enabled: true
CNI​
vCluster installs Flannel as the Container Network Interface (CNI) by default. You can disable it and install your own CNI.
deploy:
cni:
flannel:
enabled: false
When you disable Flannel, you are responsible for installing and operating a CNI in the cluster. vCluster support does not cover the configuration or behavior of user-managed CNI installations.
Kube proxy​
vCluster installs kube-proxy by default to configure services on worker nodes. If your CNI implements its own service proxy (for example, Cilium in kube-proxy replacement mode), you can disable it.
deploy:
kubeProxy:
enabled: false
To customize kube-proxy behavior without disabling it, use the config field. Values merge into the default KubeProxyConfiguration. See the Kubernetes kube-proxy config API reference for available fields.
deploy:
kubeProxy:
config:
mode: ipvs
ipvs:
scheduler: rr
Use extraArgs to pass additional flags directly to the kube-proxy binary.
MetalLB​
vCluster can install MetalLB into the cluster. Enable this with the following YAML:
deploy:
metallb:
enabled: true
ipAddressPool:
addresses:
- 10.X.X.1-10.X.X.100 # your IPs here
Local path provisioner​
vCluster installs the Local Path Provisioner by default to provide a default StorageClass for stateful workloads. If you bring your own storage solution, you can disable it.
deploy:
localPathProvisioner:
enabled: false
When you disable the Local Path Provisioner and replace it with your own StorageClass, vCluster support does not cover your storage configuration. Replacing the provisioner does not affect existing PersistentVolumes, However, new PersistentVolumeClaims do not bind until a replacement provisioner is available.
KubeVirt CSI​
vCluster can deploy a KubeVirt CSI driver into the cluster. It provisions PersistentVolumes as CDI DataVolumes in the vCluster's namespace on the control plane cluster. It then hot-plugs them into the KubeVirt virtual machines backing the cluster's private nodes. This is a storage integration, unrelated to the KubeVirt integration, which syncs KubeVirt VM resources from the cluster to the control plane cluster. See How this differs from KubeVirt CSI for the distinction.
Prerequisites​
- Private nodes enabled. KubeVirt CSI is rejected when
controlPlane.standalone.enabledistrue, since volumes are provisioned in a control-plane-cluster namespace that standalone deployments don't have. - KubeVirt Containerized Data Importer (CDI) installed on the control plane cluster. Volumes are provisioned as CDI
DataVolumeobjects rather than plain PersistentVolumeClaims, because KubeVirt's volume hot-plug expects CDI to have already created the underlying disk image. - The private nodes backing this cluster must be KubeVirt virtual machines in the same namespace as the cluster. You can provision them through a KubeVirt node provider and auto nodes. The controller first matches a virtual machine to a node by name, then falls back to matching internal IP addresses. It retries until a matching virtual machine is available. The driver doesn't create virtual machines itself.
Enable KubeVirt CSI​
deploy:
# Disable the default Local Path Provisioner to avoid two default StorageClasses.
localPathProvisioner:
enabled: false
csi:
kubeVirt:
enabled: true
Storage class behavior​
By default, vCluster creates a StorageClass named kubevirt inside the cluster and marks it as the default StorageClass. Disable either behavior with storageClass.enabled: false or storageClass.default: false. A default KubeVirt CSI StorageClass conflicts with Local path provisioner, since both would create a default StorageClass in the cluster. Disable one of them if you enable the other.
deploy:
csi:
kubeVirt:
enabled: true
storageClass:
name: kubevirt-fast
# Keep the Local Path Provisioner as the cluster's default.
default: false
hostStorageClassName: fast-ssd
bus: virtio
Leave hostStorageClassName empty to use the control plane cluster's default StorageClass for the underlying CDI DataVolume. bus defaults to scsi and is passed through to KubeVirt's disk configuration as-is. vCluster doesn't validate it, so any bus your KubeVirt installation supports (for example virtio, sata, or scsi) is accepted.
Platform stacks​
When a cluster is managed by vCluster Platform v4.12 or later, vCluster v0.37 or later can request StackInstances through deploy.stacks. Each Stack deploys to the cluster after Platform creates it.
deploy:
stacks:
- name: observability
# Resolve a StackTemplate from vCluster Platform.
templateRef:
name: observability
parameters:
retention: 7d
# Keep children when a later template removes their tasks.
prunePolicy: Retain
Each entry requires a stable name and exactly one definition source:
templateRef.namereferences a cluster-scoped StackTemplate.templatedefines the parameters, tasks, and published outputs inline.
The optional parameters map supplies .Values used by the tasks. defaults.taskTimeout sets the default task timeout. prunePolicy is Retain by default and can be set to Prune.
This field requires vCluster Platform. The Platform UI hides the Stacks form for vCluster versions that don't support it. See Use a Stack for the user workflow and status model.
Control plane components​
CoreDNS and Konnectivity are control plane components, not deploy addons. Configure them under controlPlane in your vcluster.yaml:
- CoreDNS: see CoreDNS configuration
- Konnectivity: configure or disable under
controlPlane.advanced.konnectivity
Config reference​
For every field under deploy, see the deploy reference.