Skip to main content
Version: main 🚧

Deploy vCluster AddOns

Configure addons​

vCluster supports addons that extend the capabilities of your tenant cluster. You can configure these addons during deployment to adjust networking, observability, and other features for your environment and requirements.

Metrics Server​

Supported Configurations
Running the control plane as a container with:

vCluster can install the Kubernetes Metrics Server into the tenant 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 tenant 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 tenant 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.

Platform stacks​

When a tenant cluster is managed by vCluster Platform 4.12, vCluster 0.37 can request StackInstances through deploy.stacks. Each Stack deploys to the tenant 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​

deploy object ​

Deploy holds configuration for the deployment of vCluster.

kubeProxy object ​

KubeProxy holds dedicated kube proxy configuration.

enabled boolean true ​

Enabled defines if the kube proxy should be enabled.

image string ​

Image is the image for the kube-proxy.

imagePullPolicy string ​

ImagePullPolicy is the policy how to pull the image.

nodeSelector object {} ​

NodeSelector is the node selector for the kube-proxy.

priorityClassName string ​

PriorityClassName is the priority class name for the kube-proxy.

tolerations object[] [] ​

Tolerations is the tolerations for the kube-proxy.

extraEnv object[] [] ​

ExtraEnv is the extra environment variables for the kube-proxy.

extraArgs string[] [] ​

ExtraArgs are additional arguments to pass to the kube-proxy.

config object {} ​

Config is the config for the kube-proxy that will be merged into the default kube-proxy config. More information can be found here: https://kubernetes.io/docs/reference/config-api/kube-proxy-config.v1alpha1/#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration

metallb object ​

Metallb holds dedicated metallb configuration.

enabled boolean false ​

Enabled defines if metallb should be enabled.

controllerImage string ​

ControllerImage is the image for metallb controller.

speakerImage string ​

SpeakerImage is the image for metallb speaker.

ipAddressPool object ​

IPAddressPool is the IP address pool to use for metallb.

addresses string[] [] ​

Addresses is a list of IP addresses to use for the IP address pool.

l2Advertisement boolean true ​

L2Advertisement defines if L2 advertisement should be enabled for the IP address pool.

cni object ​

CNI holds dedicated CNI configuration.

flannel object ​

Flannel holds dedicated Flannel configuration.

enabled boolean true ​

Enabled defines if Flannel should be enabled.

image string ​

Image is the image for Flannel main container.

initImage string ​

InitImage is the image for Flannel init container.

imagePullPolicy string ​

ImagePullPolicy is the policy how to pull the image.

csi object ​

CSI holds dedicated CSI configuration.

kubeVirt object ​

KubeVirt holds dedicated kubevirt CSI configuration.

enabled boolean false ​

Enabled defines if kubevirt CSI should be enabled. This allows workloads within this virtual cluster to use persistent volumes that vCluster provisions within its own namespace in the host cluster and hot plugs into the kubevirt virtual machines that back the nodes of this virtual cluster. The virtual machines have to run within the same namespace as this virtual cluster and vCluster annotates the nodes with the virtual machine they run on, which the CSI node plugin needs. The volumes are provisioned as CDI data volumes, so CDI has to be installed within the host cluster. This is only supported in private nodes mode.

image string ​

Image is the image for the kubevirt CSI node plugin. The controller side is part of the vCluster control plane, so this is the only image that is deployed.

imagePullPolicy string ​

ImagePullPolicy is the policy how to pull the image.

hostLabels object {} ​

HostLabels are additional labels vCluster adds to the persistent volume claims it creates within the namespace of this virtual cluster in the host cluster.

storageClass object ​

StorageClass holds configuration for the storage class that is created within this virtual cluster.

enabled boolean true ​

Enabled defines if the storage class should be created within this virtual cluster.

name string kubevirt ​

Name is the name of the storage class.

default boolean true ​

Default defines if the storage class should be the default storage class of this virtual cluster. This is not allowed while deploy.localPathProvisioner is enabled, because that creates a default storage class as well and two default storage classes leave it to Kubernetes which provisioner a claim without a storage class ends up on.

hostStorageClassName string ​

HostStorageClassName is the storage class within the host cluster that is used to provision the volumes. If empty, the default storage class of the host cluster is used.

hostVolumeMode string ​

HostVolumeMode pins the volume mode of the volumes that are created within the host cluster. If empty, the storage profile CDI keeps for the storage class of the host cluster decides.

bus string scsi ​

Bus is the bus the volumes are attached with to the virtual machine.

localPathProvisioner object ​

LocalPathProvisioner holds dedicated local path provisioner configuration.

enabled boolean true ​

Enabled defines if LocalPathProvisioner should be enabled.

image string ​

Image is the image for local path provisioner.

imagePullPolicy string ​

ImagePullPolicy is the policy how to pull the image.

nodePath string ​

NodePath is the path on the node where to create the persistent volume directories.

ingressNginx object ​

IngressNginx holds dedicated ingress-nginx configuration. Deprecated: We do not deploy ingress nginx and the project is being deprecated.

enabled boolean false ​

Enabled defines if ingress-nginx should be enabled.

defaultIngressClass boolean true ​

DefaultIngressClass defines if the deployed ingress class should be the default ingress class.

metricsServer object ​

MetricsServer holds dedicated metrics server configuration.

enabled boolean false ​

Enabled defines if metrics server should be enabled.

volumeSnapshotController object ​

VolumeSnapshotController holds dedicated CSI snapshot-controller configuration. Deprecated: Removed in 0.36.0. Setting this value is rejected by the Helm chart; remove it from your config.

enabled boolean ​

Enabled defines if the CSI volumes snapshot-controller should be enabled.

argoCD object ​

ArgoCD holds dedicated configuration for argoCD Apps to deploy

applications object[] ​

Applications specifies the applications to deploy. This requires the argo cd integration to be enabled.

name string ​

Name specifies the stable identifier of the argo cd application. It is used to derive generated ArgoCDApplication resource names and the final Argo CD application name.

displayName string ​

DisplayName specifies the display name of the argo cd application.

target string ​

Target specifies the target of the argo cd application. This can be "vCluster" or "host". Defaults to "vCluster".

inline object ​

Inline specifies the inline argo cd application definition. This requires the argo cd integration to be enabled.

template object ​

Template specifies the argo cd application template to use. This requires the argo cd integration to be enabled.

name string ​

Name specifies the name of the argo cd application template

parameters object ​

Parameters specifies the parameters to pass to the argo cd application template.

stacks object[] ​

Stack holds dedicated configuration for stacks to deploy

name string ​

Name specifies the stable identifier of the stack.

displayName string ​

DisplayName specifies the display name of the stack.

description string ​

Description describes the stack.

template object ​

Template defines the stack inline: parameter declarations and tasks, the same payload a StackTemplate carries. Mutually exclusive with TemplateRef.

parameters object[] ​

Parameters declares the parameters the tasks may reference as {{ .Values.variable }}. Values are supplied by the stack's parameters field.

variable string ​

Variable is the path of the variable. Can be foo or foo.bar for nested objects.

label string ​

Label is the label to show for this parameter

description string ​

Description is the description to show for this parameter

type string ​

Type of the parameter. Can be one of: string, multiline, boolean, number and password

options string[] ​

Options is a slice of strings, where each string represents a mutually exclusive choice.

min integer ​

Min is the minimum number if type is number

max integer ​

Max is the maximum number if type is number

required boolean ​

Required specifies if this parameter is required

defaultValue string ​

DefaultValue is the default value if none is specified

placeholder string ​

Placeholder shown in the UI

invalidation string ​

Invalidation regex that if matched will reject the input

validation string ​

Validation regex that if matched will allow the input

section string ​

Section where this app should be displayed. Apps with the same section name will be grouped together

tasks object[] ​

Tasks defines the stack DAG.

name string ​

Name specifies the stable identifier of the task. DNS-label-safe, unique within the stack.

dependsOn string[] ​

DependsOn lists task names that must be healthy before this task starts.

argoCDApplication object ​

ArgoCDApplication specifies the argo cd application this task deploys. Exactly one of ArgoCDApplication or App must be set.

template object ​

Template specifies the inline argo cd application template definition. Mutually exclusive with TemplateRef.

templateRef object ​

TemplateRef references an ArgoCDApplicationTemplate (per-application blueprint) by name. Mutually exclusive with Template.

name string ​

Name of the ArgoCDApplicationTemplate.

parameters object ​

Parameters supplies values to the referenced template's declared parameters. Only valid with TemplateRef; values for an inline template belong in the definition.

app object ​

App specifies the platform app this task deploys. Exactly one of ArgoCDApplication or App must be set.

template object ​

Template specifies the inline app definition, with metadata and a spec that carries the chart plus a few instance fields (displayName, description, releaseName). Mutually exclusive with TemplateRef.

templateRef object ​

TemplateRef references a named app by name and version. Mutually exclusive with Template.

name string ​

Name of the app to reference.

version string ​

Version of the app to deploy. If empty, the latest version is deployed.

parameters object ​

Parameters supplies values to the referenced app. Only valid with TemplateRef; values for an inline template belong in the definition.

timeout string ​

Timeout bounds how long this task may take to become healthy, overriding defaults.taskTimeout. Go duration string, for example "10m".

outputs object[] ​

Outputs declares values captured from this task's deployed resources that later tasks reference as {{ .Outputs.task.name }}.

name string ​

Name identifies the output. Letters and digits only, unique within the task.

fromSecret object ​

FromSecret reads the value from a Secret key on the destination cluster. Exactly one of fromSecret or fromResource must be set.

namespace string ​

Namespace of the Secret. Must be a namespace this stack deploys into.

name string ​

Name of the Secret.

key string ​

Key inside the Secret's data.

fromResource object ​

FromResource reads a single field from a resource on the destination cluster. Exactly one of fromSecret or fromResource must be set.

apiVersion string ​

APIVersion of the resource, e.g. "v1" or "apps/v1".

kind string ​

Kind of the resource, e.g. "Service".

namespace string ​

Namespace of the resource. Must be a namespace this stack deploys into; cluster-scoped resources cannot be read.

name string ​

Name of the resource.

jsonPath string ​

JSONPath selects the field, in the kubectl template syntax, e.g. "{.spec.clusterIP}". It must select exactly one scalar value.

publishedOutputs object[] ​

PublishedOutputs selects which captured task outputs the stack exposes to its users, under a public name. They are read through the stack instance's outputs subresource.

name string ​

Name specifies the public name of the output. Unique within the stack; it may differ from the task output's name.

fromTask object ​

FromTask selects which task output to publish. It must name an existing task and one of its declared outputs.

task string ​

Task specifies the task name.

output string ​

Output specifies the output name declared on that task.

templateRef object ​

TemplateRef references a cluster-scoped StackTemplate to resolve the tasks from. Mutually exclusive with Template.

name string ​

Name specifies the name of the StackTemplate to reference.

parameters object ​

Parameters specifies the values the template's tasks reference. Values the template does not declare are still available to tasks, but get no default and are not validated.

defaults object ​

Defaults are applied to all tasks unless overridden per-task.

taskTimeout string ​

TaskTimeout is the default per-task timeout as a Go duration (e.g. "10m").

prunePolicy string ​

PrunePolicy controls what happens to an application whose task is removed from the resolved set. One of "Retain" (default) or "Prune".