Skip to main content
Version: main 🚧

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 tenant cluster pods​

You can configure how and where tenant 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 tenant cluster pods on separate nodes. A common technique is to make tenant 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 tenant cluster pods on nodes that would otherwise reject them. A common pattern is to taint nodes for non-tenant-cluster workloads and configure tenant cluster pods to tolerate the taint. This keeps tenant 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 object ​

StatefulSet defines options for vCluster statefulSet deployed by Helm.

highAvailability object ​

HighAvailability holds options related to high availability.

replicas integer 1 ​

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

leaseDuration integer 60 ​

LeaseDuration is the time to lease for the leader.

renewDeadline integer 40 ​

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

retryPeriod integer 15 ​

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

resources object ​

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

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

Limits are resource limits for the container

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

Requests are minimal resources that will be consumed by the container

scheduling object ​

Scheduling holds options related to scheduling.

nodeSelector object {} ​

NodeSelector is the node selector to apply to the pod.

affinity object {} ​

Affinity is the affinity to apply to the pod.

tolerations object[] [] ​

Tolerations are the tolerations to apply to the pod.

priorityClassName string ​

PriorityClassName is the priority class name for the the pod.

podManagementPolicy string Parallel ​

PodManagementPolicy is the statefulSet pod management policy.

topologySpreadConstraints object[] [] ​

TopologySpreadConstraints are the topology spread constraints for the pod.

security object ​

Security defines pod or container security context.

podSecurityContext object {} ​

PodSecurityContext specifies security context options on the pod level.

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

ContainerSecurityContext specifies security context options on the container level.

probes object ​

Probes enables or disables the main container probes.

livenessProbe object ​

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

enabled boolean true ​

Enabled defines if this option should be enabled.

failureThreshold integer 60 ​

Number of consecutive failures for the probe to be considered failed

initialDelaySeconds integer 60 ​

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

timeoutSeconds integer 3 ​

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

periodSeconds integer 2 ​

Frequency (in seconds) to perform the probe

readinessProbe object ​

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

enabled boolean true ​

Enabled defines if this option should be enabled.

failureThreshold integer 60 ​

Number of consecutive failures for the probe to be considered failed

timeoutSeconds integer 3 ​

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

periodSeconds integer 2 ​

Frequency (in seconds) to perform the probe

startupProbe object ​

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

enabled boolean true ​

Enabled defines if this option should be enabled.

failureThreshold integer 300 ​

Number of consecutive failures allowed before failing the pod

timeoutSeconds integer 3 ​

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

periodSeconds integer 6 ​

Frequency (in seconds) to perform the probe

persistence object ​

Persistence defines options around persistence for the statefulSet.

volumeClaim object ​

VolumeClaim can be used to configure the persistent volume claim.

enabled 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 string[] [ReadWriteOnce] ​

AccessModes are the persistent volume claim access modes.

retentionPolicy string Retain ​

RetentionPolicy is the persistent volume claim retention policy.

size string 5Gi ​

Size is the persistent volume claim storage size.

storageClass string ​

StorageClass is the persistent volume claim storage class.

volumeClaimTemplates object[] [] ​

VolumeClaimTemplates defines the volumeClaimTemplates for the statefulSet

dataVolume object[] [] ​

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

binariesVolume 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 object[] [] ​

AddVolumes defines extra volumes for the pod

addVolumeMounts object[] ​

AddVolumeMounts defines extra volume mounts for the container

name string ​

This must match the Name of a Volume.

readOnly boolean ​

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

mountPath string ​

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

subPath string ​

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

mountPropagation 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 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 object {} ​

Annotations are extra annotations for this resource.

labels object {} ​

Labels are extra labels for this resource.

pods object ​

Additional labels or annotations for the statefulSet pods.

annotations object {} ​

Annotations are extra annotations for this resource.

labels object {} ​

Labels are extra labels for this resource.

image 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 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 string loft-sh/vcluster-pro ​

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

tag string ​

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

imagePullPolicy string ​

ImagePullPolicy is the policy how to pull the image.

workingDir string ​

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

command string[] [] ​

Command allows you to override the main command.

args string[] [] ​

Args allows you to override the main arguments.

env object[] [] ​

Env are additional environment variables for the statefulSet container.

dnsPolicy string ​

Set DNS policy for the pod.

dnsConfig object ​

Specifies the DNS parameters of a pod.

nameservers 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 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 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 string ​

Required.

value string ​

initContainers object[] [] ​

InitContainers are additional init containers for the statefulSet.

sidecarContainers object[] [] ​

SidecarContainers are additional sidecar containers for the statefulSet.

hostAliases object[] ​

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

ip string ​

hostnames string[] ​

runtimeClassName string ​

RuntimeClassName is the runtime class to set for the statefulSet pods.