Storage Options - vCluster

Storage configuration in vCluster controls how persistent data is managed, including volumes, storage classes, and snapshots for both the control plane and workloads.

Control Plane Persistence

controlPlane.statefulSet.persistence

object

Persistence configuration for the vCluster control plane StatefulSet.

Show properties

volumeClaim

object

Persistent volume claim configuration.

Show properties

enabled

string

default:"auto"

Enable persistent volume claim. auto determines based on distro and backing store.

true: Always create a PVC
false: Never create a PVC
auto: Automatically determine based on configuration

size

string

default:"5Gi"

Storage size for the PVC.

storageClass

string

Storage class name. If empty, uses the default storage class.

accessModes

array

default:"[\"ReadWriteOnce\"]"

Access modes for the PVC.

retentionPolicy

string

default:"Retain"

Volume retention policy when the StatefulSet is deleted.

volumeClaimTemplates

array

Additional volume claim templates for the StatefulSet.

addVolumes

array

Extra volumes for the pod.

addVolumes:
  - name: custom-config
    configMap:
      name: my-config

addVolumeMounts

array

Extra volume mounts for the container.

addVolumeMounts:
  - name: custom-config
    mountPath: /config
    readOnly: true

dataVolume

array

Override the default data volume. Only works if volumeClaim.enabled=false.

binariesVolume

array

Volume for distro-specific executables. This volume doesn’t need to be persistent.Default:

binariesVolume:
  - name: binaries
    emptyDir: {}

Etcd Persistence

controlPlane.backingStore.etcd.deploy.statefulSet.persistence

object

Persistence configuration for deployed etcd.

Show properties

volumeClaim

object

Persistent volume claim for etcd.

Show properties

enabled

boolean

default:"true"

Enable persistent volume claim for etcd.

size

string

default:"5Gi"

Storage size for etcd PVC.

storageClass

string

Storage class for etcd.

accessModes

array

default:"[\"ReadWriteOnce\"]"

Access modes for etcd PVC.

retentionPolicy

string

default:"Retain"

Retention policy for etcd volumes.

addVolumes

array

Extra volumes for etcd pods.

addVolumeMounts

array

Extra volume mounts for etcd containers.

Workload Storage Syncing

sync.toHost.persistentVolumeClaims

object

Sync PersistentVolumeClaims from virtual cluster to host.

Show properties

enabled

boolean

default:"true"

Enable PVC syncing to host cluster.

sync.toHost.persistentVolumes

object

Sync PersistentVolumes from virtual cluster to host.

Show properties

enabled

boolean

default:"false"

Enable PV syncing to host cluster.

sync.toHost.storageClasses

object

Sync StorageClasses from virtual cluster to host.

Show properties

enabled

boolean

default:"false"

Enable StorageClass syncing to host cluster.

sync.fromHost.storageClasses

object

Sync StorageClasses from host to virtual cluster.

Show properties

enabled

string

default:"auto"

Enable StorageClass syncing from host. auto enables when virtual scheduler is enabled.

Volume Snapshots

sync.toHost.volumeSnapshots

object

Sync VolumeSnapshots from virtual cluster to host.

Show properties

enabled

boolean

default:"false"

Enable VolumeSnapshot syncing.

sync.toHost.volumeSnapshotContents

object

Sync VolumeSnapshotContents from virtual cluster to host.

Show properties

enabled

boolean

default:"false"

Enable VolumeSnapshotContent syncing.

sync.fromHost.volumeSnapshotClasses

object

Sync VolumeSnapshotClasses from host to virtual cluster.

Show properties

enabled

boolean

default:"false"

Enable VolumeSnapshotClass syncing from host.

deploy.volumeSnapshotController

object

Deploy CSI volume snapshot controller.

Show properties

enabled

boolean

default:"false"

Enable deployment of volume snapshot controller.

rbac.enableVolumeSnapshotRules

object

Enable RBAC rules for volume snapshots.

Show properties

enabled

string

default:"auto"

Enable volume snapshot RBAC rules. auto enables when volume snapshot syncing is enabled.

CSI Storage

sync.fromHost.csiDrivers

object

Sync CSIDrivers from host to virtual cluster.

Show properties

enabled

string

default:"auto"

Enable CSIDriver syncing. auto enables when virtual scheduler is enabled.

sync.fromHost.csiNodes

object

Sync CSINodes from host to virtual cluster.

Show properties

enabled

string

default:"auto"

Enable CSINode syncing. auto enables when virtual scheduler is enabled.

sync.fromHost.csiStorageCapacities

object

Sync CSIStorageCapacities from host to virtual cluster.

Show properties

enabled

string

default:"auto"

Enable CSIStorageCapacity syncing. auto enables when virtual scheduler is enabled.

Local Path Provisioner

deploy.localPathProvisioner

object

Deploy local path provisioner for local storage.

Show properties

enabled

boolean

default:"true"

Enable local path provisioner deployment.

image

string

Image for local path provisioner.

imagePullPolicy

string

Image pull policy.

nodePath

string

Path on the node where persistent volume directories are created.

Example: Control Plane with Custom Storage

controlPlane:
  statefulSet:
    persistence:
      volumeClaim:
        enabled: true
        size: 20Gi
        storageClass: fast-ssd
        retentionPolicy: Retain

Example: Etcd with Persistent Storage

controlPlane:
  backingStore:
    etcd:
      deploy:
        enabled: true
        statefulSet:
          persistence:
            volumeClaim:
              enabled: true
              size: 10Gi
              storageClass: fast-storage

Example: Enable Volume Snapshots

# Enable volume snapshot syncing
sync:
  toHost:
    volumeSnapshots:
      enabled: true
    volumeSnapshotContents:
      enabled: true
  fromHost:
    volumeSnapshotClasses:
      enabled: true

# Deploy snapshot controller
deploy:
  volumeSnapshotController:
    enabled: true

# Enable RBAC rules
rbac:
  enableVolumeSnapshotRules:
    enabled: true

Example: Custom Volumes and Mounts

controlPlane:
  statefulSet:
    persistence:
      addVolumes:
        - name: custom-ca-certs
          secret:
            secretName: ca-certificates
        - name: config-volume
          configMap:
            name: vcluster-config
      
      addVolumeMounts:
        - name: custom-ca-certs
          mountPath: /etc/ssl/certs/custom
          readOnly: true
        - name: config-volume
          mountPath: /etc/vcluster
          readOnly: true

Example: Sync StorageClasses

# Sync storage classes from host to virtual cluster
sync:
  fromHost:
    storageClasses:
      enabled: true
    csiDrivers:
      enabled: true
    csiNodes:
      enabled: true
    csiStorageCapacities:
      enabled: true

# Enable virtual scheduler to use host storage
controlPlane:
  distro:
    k8s:
      scheduler:
        enabled: true

Example: Local Path Provisioner Configuration

deploy:
  localPathProvisioner:
    enabled: true
    image: rancher/local-path-provisioner:v0.0.24
    imagePullPolicy: IfNotPresent
    nodePath: /var/lib/vcluster-storage

Use Cases

High Availability with Persistent Storage

controlPlane:
  statefulSet:
    highAvailability:
      replicas: 3
    persistence:
      volumeClaim:
        enabled: true
        size: 20Gi
        storageClass: replicated-ssd

Ephemeral Storage Only

controlPlane:
  statefulSet:
    persistence:
      volumeClaim:
        enabled: false
      dataVolume:
        - name: data
          emptyDir: {}

Enable All Storage Features

sync:
  toHost:
    persistentVolumeClaims:
      enabled: true
    persistentVolumes:
      enabled: true
    storageClasses:
      enabled: true
    volumeSnapshots:
      enabled: true
    volumeSnapshotContents:
      enabled: true
  fromHost:
    storageClasses:
      enabled: true
    volumeSnapshotClasses:
      enabled: true
    csiDrivers:
      enabled: true
    csiNodes:
      enabled: true
    csiStorageCapacities:
      enabled: true

deploy:
  volumeSnapshotController:
    enabled: true

rbac:
  enableVolumeSnapshotRules:
    enabled: true

Important Notes

Backing Store Selection: The choice between embedded database, external database, or etcd affects persistence requirements:
- Embedded database (SQLite): Requires persistent volume
- External database: No local persistence needed for data (only for binaries)
- Etcd: Requires persistent volume for etcd pods
Volume Claim Templates: Cannot be modified after initial creation. Plan your storage requirements carefully.
Storage Class Changes: Changing storage classes requires manual PVC migration.
Retention Policy: Set to Retain to preserve data after vCluster deletion.

See Control Plane for backing store configuration
See Sync Configuration for PVC syncing options
See Values Reference for all options

Reference

Documentation Index

​Control Plane Persistence

​Etcd Persistence

​Workload Storage Syncing

​Volume Snapshots

​CSI Storage

​Local Path Provisioner

​Example: Control Plane with Custom Storage

​Example: Etcd with Persistent Storage

​Example: Enable Volume Snapshots

​Example: Custom Volumes and Mounts

​Example: Sync StorageClasses

​Example: Local Path Provisioner Configuration

​Use Cases

​High Availability with Persistent Storage

​Ephemeral Storage Only

​Enable All Storage Features

​Important Notes

​Related Configuration

Build docs developers (and LLMs) love

Control Plane Persistence

Etcd Persistence

Workload Storage Syncing

Volume Snapshots

CSI Storage

Local Path Provisioner

Example: Control Plane with Custom Storage

Example: Etcd with Persistent Storage

Example: Enable Volume Snapshots

Example: Custom Volumes and Mounts

Example: Sync StorageClasses

Example: Local Path Provisioner Configuration

Use Cases

High Availability with Persistent Storage

Ephemeral Storage Only

Enable All Storage Features

Important Notes

Related Configuration