Control Plane Configuration

The control plane configuration defines how vCluster’s core components are deployed and managed, including the Kubernetes distribution, backing store, networking, and resource allocation.

Distro Configuration

controlPlane.distro.k8s

object

Kubernetes distribution configuration. Only one distro can be enabled at a time.

Show properties

enabled

boolean

default:"false"

Enable the K8s distro.

version

string

Kubernetes version to use (e.g., v1.35.0).

image

object

Container image configuration.

Show properties

registry

string

default:"ghcr.io"

Registry of the container image.

repository

string

default:"loft-sh/kubernetes"

Repository of the container image.

tag

string

default:"v1.35.0"

Tag of the container image.

apiServer

object

API server configuration.

Show properties

enabled

boolean

default:"true"

Enable the API server.

command

array

Override the command to start the API server binary.

extraArgs

array

Additional arguments to pass to the API server.

controllerManager

object

Controller manager configuration.

Show properties

enabled

boolean

default:"true"

Enable the controller manager.

command

array

Override the command to start the controller manager binary.

extraArgs

array

Additional arguments to pass to the controller manager.

scheduler

object

Scheduler configuration.

Show properties

enabled

boolean

default:"false"

Enable the virtual cluster scheduler.

command

array

Override the command to start the scheduler binary.

extraArgs

array

Additional arguments to pass to the scheduler.

env

array

Extra environment variables for the main container (not init container).

resources

object

Resource requests and limits for the distro init container.

Show properties

limits.cpu

string

default:"100m"

CPU limit.

limits.memory

string

default:"256Mi"

Memory limit.

requests.cpu

string

default:"40m"

CPU request.

requests.memory

string

default:"64Mi"

Memory request.

Backing Store

controlPlane.backingStore

object

Configure which backing store to use for the virtual cluster.

Show properties

database.embedded

object

Embedded SQLite database configuration.

Show properties

enabled

boolean

default:"false"

Use embedded SQLite database.

extraArgs

array

Additional arguments to pass to Kine.

database.external

object

External database configuration (MySQL, PostgreSQL).

Show properties

enabled

boolean

default:"false"

Use external database.

dataSource

string

Kine data source connection string.

MySQL: mysql://username:password@tcp(hostname:3306)/vcluster
PostgreSQL: postgres://username:password@hostname:5432/vcluster

identityProvider

string

Identity provider for temporary authentication tokens (e.g., aws for RDS IAM).

certFile

string

Path to TLS certificate file.

keyFile

string

Path to TLS key file.

caFile

string

Path to CA certificate file.

etcd.embedded

object

Embedded etcd configuration.

Show properties

enabled

boolean

default:"false"

Use embedded etcd.

migrateFromDeployedEtcd

boolean

default:"false"

Migrate from deployed external etcd to embedded etcd.

extraArgs

array

Additional arguments to pass to etcd.

etcd.deploy

object

Deploy external etcd as a StatefulSet.

Show properties

enabled

boolean

default:"false"

Deploy external etcd.

statefulSet

object

StatefulSet configuration for etcd.

StatefulSet Configuration

controlPlane.statefulSet

object

Configure the vCluster control plane StatefulSet.

Show properties

image

object

Container image for the control plane.

Show properties

registry

string

default:"ghcr.io"

Container registry.

repository

string

default:"loft-sh/vcluster-pro"

Image repository. Use loft-sh/vcluster-oss for pure OSS build.

tag

string

Image tag (defaults to chart app version).

resources

object

Resource requests and limits.

Show properties

limits.cpu

string

CPU limit.

limits.memory

string

default:"4Gi"

Memory limit.

limits.ephemeral-storage

string

default:"10Gi"

Ephemeral storage limit.

requests.cpu

string

default:"200m"

CPU request.

requests.memory

string

default:"256Mi"

Memory request.

requests.ephemeral-storage

string

default:"1Gi"

Ephemeral storage request.

highAvailability

object

High availability configuration.

Show properties

replicas

number

default:"1"

Number of control plane replicas.

leaseDuration

number

default:"60"

Leader election lease duration (seconds).

renewDeadline

number

default:"40"

Leader election renew deadline (seconds).

retryPeriod

number

default:"15"

Leader election retry period (seconds).

persistence

object

Persistence configuration.

Show properties

volumeClaim.enabled

string

default:"auto"

Enable persistent volume claim. auto determines based on distro and options.

volumeClaim.size

string

default:"5Gi"

Storage size.

volumeClaim.storageClass

string

Storage class name.

volumeClaim.retentionPolicy

string

default:"Retain"

Volume retention policy.

probes

object

Container health probes.

Show properties

livenessProbe.enabled

boolean

default:"true"

Enable liveness probe.

readinessProbe.enabled

boolean

default:"true"

Enable readiness probe.

startupProbe.enabled

boolean

default:"true"

Enable startup probe.

CoreDNS Configuration

controlPlane.coredns

object

CoreDNS deployment configuration.

Show properties

enabled

boolean

default:"true"

Enable CoreDNS.

embedded

boolean

default:"false"

Run CoreDNS embedded within the control plane (PRO feature).

deployment.replicas

number

default:"1"

Number of CoreDNS replicas.

deployment.resources

object

Resource requests and limits for CoreDNS.

Service and Ingress

controlPlane.service

object

Control plane service configuration.

Show properties

enabled

boolean

default:"true"

Enable the control plane service.

spec.type

string

default:"ClusterIP"

Service type (ClusterIP, NodePort, LoadBalancer).

controlPlane.ingress

object

Control plane ingress configuration.

Show properties

enabled

boolean

default:"false"

Enable ingress for the control plane.

host

string

default:"my-host.com"

Hostname where vCluster will be reachable.

pathType

string

default:"ImplementationSpecific"

Ingress path type.

Example: External Database

controlPlane:
  backingStore:
    database:
      external:
        enabled: true
        dataSource: postgres://vcluster:[email protected]:5432/vcluster
        certFile: /certs/client-cert.pem
        keyFile: /certs/client-key.pem
        caFile: /certs/ca.pem

Example: High Availability

controlPlane:
  statefulSet:
    highAvailability:
      replicas: 3
      leaseDuration: 60
      renewDeadline: 40
      retryPeriod: 15
    resources:
      limits:
        cpu: 2
        memory: 8Gi
      requests:
        cpu: 500m
        memory: 1Gi

Example: Custom Kubernetes Version

controlPlane:
  distro:
    k8s:
      enabled: true
      version: v1.30.0
      image:
        registry: ghcr.io
        repository: loft-sh/kubernetes
        tag: v1.30.0
      scheduler:
        enabled: true

See Storage Options for persistence configuration
See Networking Options for service and DNS settings
See Values Reference for all configuration options

Reference

​Distro Configuration

​Backing Store

​StatefulSet Configuration

​CoreDNS Configuration

​Service and Ingress

​Example: External Database

​Example: High Availability

​Example: Custom Kubernetes Version

​Related Configuration

Build docs developers (and LLMs) love

Distro Configuration

Backing Store

StatefulSet Configuration

CoreDNS Configuration

Service and Ingress

Example: External Database

Example: High Availability

Example: Custom Kubernetes Version

Related Configuration