StorageClass Sync from Host (vCluster)
Overview
Your virtual cluster syncs StorageClass objects from the host cluster, so you can see and use the same storage classes available on the underlying infrastructure without needing to create them yourself. This sync is already enabled on your virtual cluster.
Prerequisites
This sync feature is only available on the vcluster-pro template, starting from v1.3.0. Virtual clusters on older template versions or the OSS/community template will not have this option — StorageClass sync will not appear as a config option and must not be assumed present.
Step 1: View the synced storage classes
Once enabled, run the usual command inside the virtual cluster:
kubectl get storageclass
The result will show the host cluster’s storage classes (same name, provisioner, and parameters as on the host) — not a vCluster-local copy with independent settings. If the host adds, removes, or changes a storage class, that change propagates into the vCluster automatically.
Step 2: Provision a PVC using a synced storage class
Selecting one of these storage classes in a PVC (storageClassName: <name>) always provisions the volume using the host cluster’s actual provisioner and parameters — there is no independent, vCluster-scoped version of that class. What you see is exactly what you get on the host.
If no storageClassName is set on a PVC, Kubernetes' default-class admission logic picks whichever synced class is marked default inside the virtual cluster. If you need a specific storage class, set storageClassName explicitly rather than relying on the default.
Step 3: Understand read-only behavior
Synced storage classes are read-only inside the vCluster:
- Any
kubectl edit,kubectl label,kubectl annotate, orkubectl deleteagainst a syncedStorageClasswill not be rejected outright, but the change is temporary — vCluster’s sync controller reconciles the object back to match the host’s version on its next pass. Don’t rely on any local modification persisting. - You cannot create your own
StorageClasswith the same name as a synced one to override it. - Creating storage classes with a different name still works normally (they simply won’t be synced anywhere).
Summary: dos and don’ts
| Topic | What you need to know |
|---|---|
| Viewing storage classes | kubectl get storageclass always reflects the host cluster’s storage classes, kept up to date automatically. |
| Using a listed storage class in a PVC | Setting storageClassName to one of the listed classes provisions storage via the host’s actual provisioner. |
Leaving storageClassName unset | The PVC falls back to whichever class is marked default — set storageClassName explicitly if you need a specific one. |
| Editing, labeling, or deleting a synced storage class | These are not permanent — the storage class is owned by the host and gets restored to match the host automatically. |
| Creating a storage class with the same name as a synced one | Not possible to override a synced storage class this way. |
| Creating a storage class with a different name | Fully supported — it stays local to your virtual cluster and is independent of the host. |