Skip to main content
Version: v0.38 Stable

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-onVersion
Metrics Serverv0.7.2
Flannelv0.26.7, with the Flannel CNI plugin v1.6.2-flannel1
kube-proxyThe cluster's Kubernetes version
MetalLBv0.15.2
Local Path Provisionerv0.0.31
KubeVirt CSI node pluginlatest, 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​

Supported Configurations
Running the control plane as a container with:

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.

Enable Metrics Server
deploy:
metricsServer:
enabled: true

CNI​

Supported Configurations
Running the control plane as a container with:

vCluster installs Flannel as the Container Network Interface (CNI) by default. You can disable it and install your own CNI.

Disable default Flannel CNI
deploy:
cni:
flannel:
enabled: false
User-managed component

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​

Supported Configurations
Running the control plane as a container with:

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.

Disable kube-proxy
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.

Custom kube-proxy config
deploy:
kubeProxy:
config:
mode: ipvs
ipvs:
scheduler: rr

Use extraArgs to pass additional flags directly to the kube-proxy binary.

MetalLB​

Supported Configurations
Running the control plane as a container with:

vCluster can install MetalLB into the cluster. Enable this with the following YAML:

Enable MetalLB
deploy:
metallb:
enabled: true
ipAddressPool:
addresses:
- 10.X.X.1-10.X.X.100 # your IPs here

Local path provisioner​

Supported Configurations
Running the control plane as a container with:

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.

Disable Local Path Provisioner
deploy:
localPathProvisioner:
enabled: false
User-managed component

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​

Supported Configurations
Running the control plane as a container with:

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.enabled is true, 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 DataVolume objects 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​

Enable the KubeVirt CSI driver
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.

Use a specific host StorageClass and disk bus
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 a Stack
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.name references a cluster-scoped StackTemplate.
  • template defines 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.