Skip to main content
Version: main 🚧

StatefulSet

Supported Configurations
Running the control plane as a container with:

The vCluster control plane runs as a StatefulSet when it keeps data of its own. That's the case with the default embedded SQLite backing store and with embedded etcd, which store state on a PersistentVolumeClaim. controlPlane.statefulSet.persistence.volumeClaim.enabled defaults to auto, which creates the claim only for those two backing stores.

The control plane runs as a Deployment instead when no claim is created and embedded etcd is off. That happens with a deployed etcd, external etcd, or external database backing store, which keep the data outside the control plane. It also happens if you set volumeClaim.enabled: false with embedded SQLite. The data then goes into an emptyDir volume and is lost when the pod is deleted or rescheduled.

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

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

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

To do this, turn off the generated claim and set the existing claim name in controlPlane.statefulSet.persistence.dataVolume under persistentVolumeClaim.claimName. dataVolume only works when volumeClaim.enabled is false. Otherwise vCluster also generates its own data claim.

controlPlane:
statefulSet:
persistence:
volumeClaim:
enabled: false
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​

For every field under controlPlane.statefulSet, see the controlPlane reference.