Storage classes
By default, this is disabled.
StorageClass resources define how virtual clusters provision storage. They specify storage backends such as AWS EBS, Azure Disk, or GCP Persistent Disk, along with parameters such as performance tiers and replication settings.
By default, each virtual cluster needs its own StorageClass resources. StorageClass syncing allows virtual clusters to use StorageClass resources from the host cluster instead.
You can enable this feature to sync StorageClass resources from the host cluster to the virtual cluster. Add labels to StorageClass resources in your host cluster and configure vCluster to sync only those matching specific selectors. When you create a PersistentVolumeClaim that references a synced StorageClass, the host cluster uses that storage configuration. Common use cases include:
- Cost control: Restrict access to specific storage classes based on cost or performance characteristics.
- Compliance: Control which storage backends and configurations are available to virtual clusters.
- Multi-tenancy: Provide different storage options to different teams while preventing access to restricted storage types.
- Simplified management: Update storage class configurations in the host cluster rather than in each virtual cluster.
- Security: Control access to storage backends and encryption options.
Enable syncing​
When enabled, vCluster takes control of all StorageClass resources in the virtual cluster. It only allows StorageClass resources that are synced from the host cluster to exist.
This example configuration enables syncing all StorageClass resources from the host cluster to the virtual cluster:
sync:
fromHost:
storageClasses:
enabled: true
If you try to create the StorageClass resource directly in the virtual cluster, using for example kubectl create
or kubectl apply
, vCluster detects it and deletes it immediately. This prevents conflicts between locally-created StorageClass resources and those synced from the host cluster, ensuring that only StorageClass resources from the host cluster exist in the virtual cluster.
When enabled, StorageClass resource creation can only occur in the host cluster. Any StorageClass resources created in the virtual cluster will be deleted.
How syncing works​
When StorageClass syncing is enabled, vCluster can use a label selector to control which StorageClass, PersistentVolumeClaim and PersistentVolume resources are synchronized between the host and virtual clusters. This affects the resource types with separate unidirectional sync flows:
-
StorageClass resources (host → virtual): vCluster syncs StorageClass resources from the host cluster to the virtual cluster. You cannot create StorageClass resources directly in the virtual cluster. If a selector is defined, only StorageClass resources matching the selector will sync. If no selector is defined, all StorageClass resources are synced.
-
PersistentVolume and PersistentVolumeClaim resources (virtual → host): vCluster syncs PersistentVolume and PersistentVolumeClaim resources from the virtual cluster to the host cluster only if any of the following is true:
- No selector is defined for StorageClass syncing, which allows all PersistentVolume and PersistentVolumeClaim resources to sync regardless of the
storageClassName
. - The PersistentVolume's or PersistentVolumeClaim's
storageClassName
references a StorageClass resource that matches the selector and is synced from the host cluster. - The PersistentVolume and PersistentVolumeClaim has an empty
storageClassName
field.
- No selector is defined for StorageClass syncing, which allows all PersistentVolume and PersistentVolumeClaim resources to sync regardless of the
The same selector controls both sync flows. The selector determines which StorageClass resources are imported from the host cluster and which PersistentVolume and PersistentVolumeClaim resources can sync to the host cluster based on the referenced StorageClass resource.
Use selectors to filter​
Selectors provide precise control over which StorageClass resources get synced from the host cluster and which PersistentVolume and PersistentVolumeClaim resources gets synced to the host cluster. vCluster supports two types of selector criteria that follow standard Kubernetes label selector syntax.
Filter with matchLabels​
The matchLabels
selector defines exact label key-value pairs that must be present on an StorageClass for it to be synced. This provides straightforward filtering based on specific labels.
The following example syncs only StorageClass resources with a environment: development
label:
sync:
toHost:
persistentVolumes:
enabled: true
persistentVolumeClaims:
enabled: true
fromHost:
storageClasses:
enabled: true
selector:
matchLabels:
environment: development
Filter with matchExpressions​
The matchExpressions
selector allows more flexible, set-based filtering with support for multiple operators:
In
: Select all resources that has a specific key and the value is in the set of valuesNotIn
: Select all resources that has a specific key and the value is not in the set of valuesExists
: Select all resources including a label with the key; no values are checkedDoesNotExist
: Select all resources without a label with the key; no values are checked
The following example syncs StorageClass resources where the key of the label is kubernetes.io/storage.class
and the value of that label is either network-nas
or fast-sad
:
sync:
toHost:
persistentVolumes:
enabled: true
persistentVolumeClaims:
enabled: true
fromHost:
storageClasses:
enabled: true
selector:
matchExpressions:
- key: kubernetes.io/storage.class
operator: In
values:
- network-nas
- fast-sad
Combined filter criteria​
Label conditions are additive meaning all specified label conditions must match for the StorageClass resource to be selected to be synced. This means that if you define multiple matchLabels
and matchExpressions
, the StorageClass resource must satisfy all criteria to be synced to the virtual cluster.
The following example syncs StorageClass resources that match both label and expression criteria:
sync:
toHost:
persistentVolumes:
enabled: true
persistentVolumeClaims:
enabled: true
fromHost:
storageClasses:
enabled: true
selector:
matchLabels:
environment: development
matchExpressions:
- key: kubernetes.io/storage.class
operator: In
values:
- network-nas
- fast-sad
In this example, the StorageClass must have the following labels to sync to the virtual cluster:
environment: development
- Either
kubernetes.io/storage.class:network-nas
orkubernetes.io/storage.class:fast-sad
Sync behavior considerations​
Resource lifecycle​
Synced StorageClass resources function like any other Kubernetes resource in the virtual cluster. You
can view them with kubectl get storageclass
and reference them in your PersistentVolume and PersistentVolumeClaim resource
specifications with the storageClassName
field.
When you modify the StorageClass resource in the host cluster, vCluster re-evaluates whether it still matches the selector criteria. If the StorageClass continues to match, vCluster updates the corresponding resource in the virtual cluster to reflect the changes. If the StorageClass no longer matches the selector criteria, vCluster removes it from the virtual cluster.
The selector system acts as both a resource filter and a validation mechanism. As a resource filter, it ensures that vCluster creates only StorageClass resources matching the defined selector criteria. The selector also functions as a creation validation mechanism - when you create PersistentVolume and PersistentVolumeClaim resources in the virtual cluster, the resources can only reference StorageClass resources that exist in the virtual cluster.
Orphaned resources​
When vCluster removes a synced StorageClass from the virtual cluster due to selector changes or deletion from the host cluster, any PersistentVolume and PersistentVolumeClaim resources that reference it remain in the virtual and host clusters. These orphaned PersistentVolume and PersistentVolumeClaim resources stop receiving updates but vCluster does not automatically delete them to prevent unintended data loss. To remove these orphaned resources, you must delete them manually in the virtual and host clusters. This manual approach ensures that you maintain full control over resource cleanup and can verify that deletions are intentional.
Error handling and troubleshooting​
When the StorageClass resource doesn't match the selector criteria during evaluation, vCluster logs a warning in the syncer pod's output to help with troubleshooting and monitoring. This logging provides visibility into which resources are being filtered out and why.
When you creates the PersistentVolume or PersistentVolumeClaim resource that references a StorageClass not matching the selector criteria, several things occur to provide clear feedback:
- The PersistentVolume or PersistentVolumeClaim fails to sync to the host cluster
- vCluster records an event on the PersistentVolume or PersistentVolumeClaim resource in the virtual cluster
- The event indicates that the specified StorageClass is not available according to the current selector configuration
The error output appears as a Kubernetes event that you can view using kubectl describe
. The event message clearly states that the PersistentVolume or PersistentVolumeClaim resource was not synced because the referenced StorageClass does not match the defined selector criteria.
The error output looks like this:
vcluster-virtual-cluster-1:~$ kubectl describe pvc my-pvc
Name: my-pvc
Namespace: default
StorageClass: fast-sad
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning SyncWarning 10s pvc-syncer did not sync pvc "my-pvc" to host because it does not match the selector under 'sync.fromHost.storageClasses.selector'
Config reference​
storageClasses
required object pro​
StorageClasses defines if storage classes should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.
storageClasses
required object pro​enabled
required string|boolean auto pro​
Enabled defines if this option should be enabled.
enabled
required string|boolean auto pro​patches
required object[] pro​
Patches patch the resource according to the provided specification.
patches
required object[] pro​path
required string pro​
Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.
path
required string pro​expression
required string pro​
Expression transforms the value according to the given JavaScript expression.
expression
required string pro​reverseExpression
required string pro​
ReverseExpression transforms the value according to the given JavaScript expression.
reverseExpression
required string pro​reference
required object pro​
Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode
automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with
other names, in multi-namespace mode this will not translate the name.
reference
required object pro​apiVersion
required string pro​
APIVersion is the apiVersion of the referenced object.
apiVersion
required string pro​apiVersionPath
required string pro​
APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.
apiVersionPath
required string pro​kind
required string pro​
Kind is the kind of the referenced object.
kind
required string pro​kindPath
required string pro​
KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.
kindPath
required string pro​namePath
required string pro​
NamePath is the optional relative path to the reference name within the object.
namePath
required string pro​namespacePath
required string pro​
NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the
metadata.namespace path of the object.
namespacePath
required string pro​labels
required object pro​
Labels treats the path value as a labels selector.
labels
required object pro​selector
required object pro​
Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.
selector
required object pro​