Skip to main content

StatefulSet

Supported Configurations
Running the control plane as a container with:

The vCluster control plane typically runs as a StatefulSet to ensure data persists across restarts. This setup uses a PersistentVolume for state storage. However, if you set statefulSet.persistence.volumeClaim.enabled: false or omit the statefulSet.persistence.volumeClaimTemplates configuration, vCluster defaults to deploying the control plane as a Deployment, which does not retain state across restarts.

Configure high availability​

Use the highAvailability settings to run multiple replicas of the vCluster control plane. One pod acts as the leader, while the others remain on standby:

  • If the leader pod crashes, becomes unhealthy, or restarts, another pod automatically takes over leadership.

  • The number of available replicas determines how quickly a new leader can be elected.

  • You can fine-tune the leader election process using the following settings:

    • leaseDuration: Maximum time a leader can hold leadership without renewal.
    • renewDeadline: Time a pod waits to renew its leadership before it gives up.
    • retryPeriod: Interval between retries when attempting to acquire or renew leadership.

Schedule virtual cluster pods​

You can configure how and where virtual cluster pods are scheduled within the Kubernetes cluster. Configure the scheduling field with the following options to control pod placement in the cluster:

  • nodeSelector
    Match specific node labels to guide the scheduler toward preferred nodes. Examples include:

    • Targeting nodes in a specific region
    • Selecting nodes with a specific architecture or machine class

  • affinity Set rules to control how pods are scheduled in relation to other pods.

    • Use anti-affinity (repel the pod) to keep virtual cluster pods on separate nodes. A common technique is to make virtual cluster pods repel each other so that they are not scheduled on the same nodes.This increases resiliency if a node is scaled down or replaced.
    • Use affinity (attract the pod) to group related pods together and reduce network latency for critical services.

  • tolerations
    Allow pods to run on nodes with specific taints. Use this to schedule virtual cluster pods on nodes that would otherwise reject them. A common pattern is to taint nodes for non-virtual-cluster workloads and configure virtual cluster pods to tolerate the taint. This keeps virtual clusters separate from critical workloads. See Taints and Tolerations for more information.

  • priorityClassName
    Set the pod’s priority to control scheduling order and preemption. See the Pod Priority and Preemption documentation for details.

  • podManagementPolicy Control how StatefulSets create and delete pods. See Pod Management Policies for details.

  • topologySpreadConstraints Spread pods evenly across zones, nodes, or other topology domains. See Pod Topology Spread Constraints and the comparison with podAffinity and podAntiAffinity for more information.

Reuse an existing PersistenceVolumeClaim​

You can pre-provision a PersistenceVolumeClaim, and then configure vCluster to use it.

To do this, set the existing claim name in the chart values controlPlane.statefulSet.persistence.dataVolume under persistenceVolumeClaim.claimName:

controlPlane:
  statefulSet:
    persistence:
      dataVolume:
        - name: data
          persistentVolumeClaim:
            claimName: my-existing-pvc

vCluster image options​

There are currently 3 vCluster image builds you can use in statefulSet.image.repository:

  • loft-sh/vcluster-pro: The default image for the Helm chart. This image works for all use cases.
  • loft-sh/vcluster-oss: An open source build of vCluster
  • loft-sh/vcluster: Deprecated. Use loft-sh/vcluster-oss instead.

Config reference​

statefulSet required object ​

StatefulSet defines options for vCluster statefulSet deployed by Helm.

highAvailability required object ​

HighAvailability holds options related to high availability.

replicas required integer 1 ​

Replicas is the amount of replicas to use for the statefulSet.

leaseDuration required integer 60 ​

LeaseDuration is the time to lease for the leader.

renewDeadline required integer 40 ​

RenewDeadline is the deadline to renew a lease for the leader.

retryPeriod required integer 15 ​

RetryPeriod is the time until a replica will retry to get a lease.

resources required object ​

Resources are the resource requests and limits for the statefulSet container.

limits required object map[ephemeral-storage:10Gi memory:4Gi] ​

Limits are resource limits for the container

requests required object map[cpu:200m ephemeral-storage:1Gi memory:256Mi] ​

Requests are minimal resources that will be consumed by the container

scheduling required object ​

Scheduling holds options related to scheduling.

nodeSelector required object {} ​

NodeSelector is the node selector to apply to the pod.

affinity required object {} ​

Affinity is the affinity to apply to the pod.

tolerations required object[] [] ​

Tolerations are the tolerations to apply to the pod.

priorityClassName required string ​

PriorityClassName is the priority class name for the the pod.

podManagementPolicy required string Parallel ​

PodManagementPolicy is the statefulSet pod management policy.

topologySpreadConstraints required object[] [] ​

TopologySpreadConstraints are the topology spread constraints for the pod.

security required object ​

Security defines pod or container security context.

podSecurityContext required object {} ​

PodSecurityContext specifies security context options on the pod level.

containerSecurityContext required object map[allowPrivilegeEscalation:false runAsGroup:0 runAsUser:0] ​

ContainerSecurityContext specifies security context options on the container level.

probes required object ​

Probes enables or disables the main container probes.

livenessProbe required object ​

LivenessProbe specifies if the liveness probe for the container should be enabled

enabled required boolean true ​

Enabled defines if this option should be enabled.

failureThreshold required integer 60 ​

Number of consecutive failures for the probe to be considered failed

initialDelaySeconds required integer 60 ​

Time (in seconds) to wait before starting the liveness probe

timeoutSeconds required integer 3 ​

Maximum duration (in seconds) that the probe will wait for a response.

periodSeconds required integer 2 ​

Frequency (in seconds) to perform the probe

readinessProbe required object ​

ReadinessProbe specifies if the readiness probe for the container should be enabled

enabled required boolean true ​

Enabled defines if this option should be enabled.

failureThreshold required integer 60 ​

Number of consecutive failures for the probe to be considered failed

timeoutSeconds required integer 3 ​

Maximum duration (in seconds) that the probe will wait for a response.

periodSeconds required integer 2 ​

Frequency (in seconds) to perform the probe

startupProbe required object ​

StartupProbe specifies if the startup probe for the container should be enabled

enabled required boolean true ​

Enabled defines if this option should be enabled.

failureThreshold required integer 300 ​

Number of consecutive failures allowed before failing the pod

timeoutSeconds required integer 3 ​

Maximum duration (in seconds) that the probe will wait for a response.

periodSeconds required integer 6 ​

Frequency (in seconds) to perform the probe

persistence required object ​

Persistence defines options around persistence for the statefulSet.

volumeClaim required object ​

VolumeClaim can be used to configure the persistent volume claim.

enabled required string|boolean auto ​

Enabled enables deploying a persistent volume claim. If auto, vCluster will automatically determine based on the chosen distro and other options if this is required.

accessModes required string[] [ReadWriteOnce] ​

AccessModes are the persistent volume claim access modes.

retentionPolicy required string Retain ​

RetentionPolicy is the persistent volume claim retention policy.

size required string 5Gi ​

Size is the persistent volume claim storage size.

storageClass required string ​

StorageClass is the persistent volume claim storage class.

volumeClaimTemplates required object[] [] ​

VolumeClaimTemplates defines the volumeClaimTemplates for the statefulSet

dataVolume required object[] [] ​

Allows you to override the dataVolume. Only works correctly if volumeClaim.enabled=false.

binariesVolume required object[] [map[emptyDir:map[] name:binaries]] ​

BinariesVolume defines a binaries volume that is used to retrieve distro specific executables to be run by the syncer controller. This volume doesn't need to be persistent.

addVolumes required object[] [] ​

AddVolumes defines extra volumes for the pod

addVolumeMounts required object[] ​

AddVolumeMounts defines extra volume mounts for the container

name required string ​

This must match the Name of a Volume.

readOnly required boolean ​

Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false.

mountPath required string ​

Path within the container at which the volume should be mounted. Must not contain ':'.

subPath required string ​

Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root).

mountPropagation required string ​

mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10.

subPathExpr required string ​

Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive.

EnableServiceLinks for the StatefulSet pod

annotations required object {} ​

Annotations are extra annotations for this resource.

labels required object {} ​

Labels are extra labels for this resource.

pods required object ​

Additional labels or annotations for the statefulSet pods.

annotations required object {} ​

Annotations are extra annotations for this resource.

labels required object {} ​

Labels are extra labels for this resource.

image required object ​

Image is the image for the controlPlane statefulSet container It defaults to the vCluster pro repository that includes the optional pro modules that are turned off by default. If you still want to use the pure OSS build, set the repository to 'loft-sh/vcluster-oss'.

registry required string ghcr.io ​

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.

repository required string loft-sh/vcluster-pro ​

Repository is the repository of the container image, e.g. my-repo/my-image

tag required string ​

Tag is the tag of the container image, and is the default version.

imagePullPolicy required string ​

ImagePullPolicy is the policy how to pull the image.

workingDir required string ​

WorkingDir specifies in what folder the main process should get started.

command required string[] [] ​

Command allows you to override the main command.

args required string[] [] ​

Args allows you to override the main arguments.

env required object[] [] ​

Env are additional environment variables for the statefulSet container.

dnsPolicy required string ​

Set DNS policy for the pod.

dnsConfig required object ​

Specifies the DNS parameters of a pod.

nameservers required string[] ​

A list of DNS name server IP addresses. This will be appended to the base nameservers generated from DNSPolicy. Duplicated nameservers will be removed.

searches required string[] ​

A list of DNS search domains for host-name lookup. This will be appended to the base search paths generated from DNSPolicy. Duplicated search paths will be removed.

options required object[] ​

A list of DNS resolver options. This will be merged with the base options generated from DNSPolicy. Duplicated entries will be removed. Resolution options given in Options will override those that appear in the base DNSPolicy.

name required string ​

Required.

value required string ​

initContainers required object[] [] ​

InitContainers are additional init containers for the statefulSet.

sidecarContainers required object[] [] ​

SidecarContainers are additional sidecar containers for the statefulSet.

hostAliases required object[] ​

HostAliases allows you to add custom entries to the /etc/hosts file of each Pod created.

ip required string ​

hostnames required string[] ​