Data volumes

		Enterprise
Available in these plans	Free	Dev	Prod	Scale
VM Management with KubeVirt

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

KubeVirt DataVolume resources define the disk content that Containerized Data Importer (CDI) imports, clones, or creates for virtual machines. In vCluster Platform, administrators use DataVolumes to prepare reusable VM disks, inspect import progress, and understand which VMs depend on a disk.

Open the DataVolumes view from Virtual Machines > Data Volumes, or go directly to /virtual-machines/data-volumes.

When to use data volumes

Use DataVolumes when you need to:

• Import a VM disk from an HTTP, HTTPS, or registry source.
• Clone disk content from an existing PVC.
• Create a blank disk that a VM can format and use.
• Track the import, clone, or population status of a VM disk across connected KubeVirt clusters.
• Identify direct VM references and investigate other dependencies before changing or deleting a DataVolume.

Prerequisites

Before creating or using DataVolumes, make sure:

• The target Control Plane Cluster is connected to vCluster Platform.
• KubeVirt and CDI are installed on the target cluster, or the KubeVirt node provider is configured to deploy them.
• The user has permission to list, create, update, and delete datavolumes.cdi.kubevirt.io resources in the target namespace.
• Cross-namespace clones need additional RBAC. See Cross-namespace clones.
• The StorageClass used by the DataVolume can provision PVCs in the target cluster.
• Image URLs, registries, PVC sources, secrets, and certificates are reachable from CDI importer pods.

Create a standalone data volume

tip

Root disk DataVolumes for KubeVirt-backed Machines are usually generated automatically from image properties or an OS image. Use the steps below instead for secondary or manually managed disks.

The platform UI creates an administrator-managed DataVolume that a VM can reference directly.

1. Open Virtual Machines > Data Volumes.

2. Click .

3. Choose the target KubeVirt cluster and namespace.

4. Enter a name and storage size. Select one source type:

   • HTTP: import from an HTTP or HTTPS image URL.
   • Registry: import from a container registry URL such as docker://quay.io/containerdisks/ubuntu:22.04.
   • PVC: clone from an existing PVC.
   • Blank: create an empty disk.

5. Click and watch its lifecycle in the table.

See the CDI documentation for the full set of source types and import semantics.

The DataVolumes table shows the cluster, namespace, source type, requested storage, platform lifecycle status, and Used by machine. The Used by machine column lists VMs that reference the volume directly.

Before deleting a DataVolume

An empty Used by machine value doesn't mean a DataVolume is unused. A DataVolume can back persistent storage without currently being attached to a VM. Some DataVolumes also back tenant PVCs through the vCluster KubeVirt CSI driver instead of a VM template disk, a case this column can never detect. See Operational ownership for the full breakdown before you delete anything this column doesn't explain.

Cross-namespace clones

Cloning a PVC across namespaces needs RBAC beyond what's listed in Prerequisites. This applies whether the clone happens through the platform UI, kubectl, or the KubeVirt node provider's kubevirt.vcluster.com/image-datasource property. The identity performing the clone must be able to create datavolumes/source or pods in the source namespace. For DataVolumes the KubeVirt node provider synthesizes, that identity is the connected-cluster credentials the provider uses to reach the target cluster, not the identity of whoever created the Machine, NodeType, or NodeProvider.

Understand the data volume lifecycle

CDI reports the raw lifecycle in the DataVolume .status.phase field. vCluster Platform maps that to a simplified Status column that groups related CDI phases. Use the CDI phase when you troubleshoot with kubectl. Use the platform status when you scan the UI.

Platform status	Common CDI phases or signals	Meaning
Importing	ImportScheduled, ImportInProgress	CDI scheduled or started an image import.
Pending	Pending, PVCBound, clone phases, upload phases, WaitForFirstConsumer, PendingPopulation	CDI or the storage provider is preparing the PVC or waiting for scheduling.
Ready	Succeeded	CDI finished preparing the volume.
Failed	Failed or a Running condition with reason Error	CDI or the storage provider reported an error.
Paused	Paused	CDI paused the operation.
Terminating	metadata.deletionTimestamp is set	Kubernetes is deleting the DataVolume.
Unknown	Missing, empty, or unrecognized phase	The platform can't classify the lifecycle state.

For example, the UI can show Pending for a DataVolume whose CDI phase is WaitForFirstConsumer. That usually means the PVC waits for a VM pod to schedule before the storage provider binds it.

Create a reusable data source

Three resources work together to prepare and consume VM storage:

• DataSource: a reusable reference to prepared disk content.
• DataVolume: the request and lifecycle for creating or populating that content into a PVC.
• PersistentVolumeClaim: the storage a VM ultimately mounts.

To let multiple VMs reuse the same disk content without importing it more than once, wrap a DataVolume's PVC in a CDI DataSource. Import or clone the disk once into a DataVolume through the platform UI, then create a DataSource that points to the resulting PVC:

apiVersion: cdi.kubevirt.io/v1beta1
kind: DataSource
metadata:
  name: ubuntu-22-04
  namespace: golden-images
spec:
  source:
    pvc:
      name: ubuntu-root-disk
      namespace: golden-images

Reference the DataSource from a NodeProvider, NodeType, NodeClaim, or Machine with kubevirt.vcluster.com/image-datasource, the same property described in Import a root disk through a Machine.

vCluster Platform doesn't create or manage DataSource resources directly. Create and update them with kubectl, and treat them as long-lived golden images. Deleting the underlying DataVolume or PVC prevents new target DataVolumes from being populated and can interrupt clones that are still in progress. VMs whose target PVCs are already populated continue to use those independent volumes.

Use data volumes with node providers

The KubeVirt node provider can also synthesize a root-disk DataVolumeTemplate automatically when a Machine, NodeType, NodeProvider, or OS image sets kubevirt.vcluster.com/image-url or kubevirt.vcluster.com/image-datasource. That generated DataVolume appears in the DataVolumes table alongside any administrator-created volumes.

Import a root disk through a Machine

For VM-backed Machines and auto nodes, you usually do not need to create the root DataVolume manually. Instead, set image properties on the KubeVirt provider, node type, NodeClaim, Machine, or referenced OSImage.

apiVersion: management.loft.sh/v1
kind: NodeProvider
metadata:
  name: kubevirt-provider
spec:
  properties:
    kubevirt.vcluster.com/image-url: docker://quay.io/containerdisks/ubuntu:22.04
    kubevirt.vcluster.com/root-disk-size: 20Gi
  kubeVirt:
    clusterRef:
      cluster: kubevirt-host
      namespace: vcluster-platform
    virtualMachineTemplate:
      spec:
        template:
          spec:
            domain:
              resources:
                requests:
                  cpu: "2"
                  memory: 4Gi
    nodeTypes:
    - name: ubuntu
      maxCapacity: 10

The provider creates a root-disk DataVolumeTemplate, a volume, and a disk for the VM. HTTP and HTTPS image URLs become CDI http sources. docker:// image URLs become CDI registry sources.

To use a prepared CDI DataSource, set kubevirt.vcluster.com/image-datasource instead:

spec:
  properties:
    kubevirt.vcluster.com/image-datasource: golden-images/ubuntu-22-04
    kubevirt.vcluster.com/root-disk-size: 20Gi

Use <name> to reference a DataSource in the node provider namespace from spec.kubeVirt.clusterRef.namespace, or <namespace>/<name> to reference one in another namespace. Configure either kubevirt.vcluster.com/image-url or kubevirt.vcluster.com/image-datasource. If both are set, the provider uses the DataSource and ignores the URL and checksum.

See Cross-namespace clones for the RBAC a <namespace>/<name> reference requires.

Attach data volumes to VM templates

You can attach additional DataVolumes by adding a KubeVirt volume and disk to the VM template. Use dataVolumeTemplates for volumes that should be created with the VM, or reference an existing DataVolume by name.

Use dataVolumeTemplates for inline volumes:

spec:
  kubeVirt:
    virtualMachineTemplate:
      spec:
        dataVolumeTemplates:
        - metadata:
            name: tools-disk
          spec:
            source:
              blank: {}
            pvc:
              accessModes:
              - ReadWriteOnce
              resources:
                requests:
                  storage: 10Gi
        template:
          spec:
            domain:
              devices:
                disks:
                - name: tools-disk
                  disk:
                    bus: virtio
            volumes:
            - name: tools-disk
              dataVolume:
                name: tools-disk

When the KubeVirt node provider creates a VM from a template, it prefixes user-provided dataVolumeTemplates so DataVolume names stay unique for each node.

To attach a standalone DataVolume that already exists in the VM namespace, reference it from the VM template's volumes list:

spec:
  kubeVirt:
    virtualMachineTemplate:
      spec:
        template:
          spec:
            domain:
              devices:
                disks:
                - name: my-data-disk
                  disk:
                    bus: virtio
            volumes:
            - name: my-data-disk
              dataVolume:
                name: my-existing-datavolume

The referenced DataVolume must exist in the namespace where KubeVirt creates the VM. This is the path to use for DataVolumes created through the Data Volumes UI. Every VM created from this template references the same DataVolume and underlying PVC.

warning

DataVolumes created through the UI use ReadWriteOnce by default, which restricts read-write mounts to one node at a time. Only share a DataVolume when its access mode, storage provider, and workload support the intended concurrent access. When each VM needs an independent disk cloned from the same image, use a reusable DataSource instead.

Operational ownership

DataVolumes are namespaced resources on connected KubeVirt clusters, not vCluster Platform resources. vCluster Platform gives administrators a UI for the connected KubeVirt clusters, but CDI owns the import and PVC population process. KubeVirt owns DataVolumes created from a VM's dataVolumeTemplates, and those resources usually follow the VM lifecycle.

Use this ownership model:

Owner	Responsibility
Platform administrator	Create reusable DataVolumes, choose storage classes, configure image sources, and control RBAC.
vCluster Platform	Lists DataVolumes, creates administrator-requested DataVolumes, shows platform lifecycle status and directly referencing VMs, and generates root-disk templates from KubeVirt image properties.
vCluster KubeVirt CSI driver	Creates host-cluster DataVolumes to back tenant PVCs and removes them according to the tenant PV reclaim lifecycle.
CDI	Imports, clones, uploads, or populates PVC content and reports DataVolume phase and conditions.
KubeVirt	Creates DataVolumes from VM templates and attaches the resulting PVCs to VMs.
Storage provider	Provisions PVCs and enforces access modes, binding mode, expansion, and quota.

Some DataVolumes in this list back tenant-cluster PVCs rather than a VM template disk. The vCluster KubeVirt CSI driver creates one on the host cluster for each such PVC and hot-plugs the resulting PVC into the VM backing the selected tenant node. Because the VM references the PVC directly rather than the DataVolume, Used by machine never shows these VMs, even while the PVC is attached. Treat these the same as any other DataVolume you didn't create yourself.

Before deleting a DataVolume, check the Used by machine column and inspect its metadata:

kubectl get datavolume -n vcluster-platform my-data-volume -o yaml

The column only detects direct VM references, so an empty value doesn't mean that the volume is unused. A DataVolume with the csi.kubevirt.io/vcluster-claim annotation backs the named PVC inside a vCluster. The vcluster.loft.sh/managed-by label also indicates that a vCluster manages the resource. Do not delete these DataVolumes directly from the platform UI or host cluster. Manage their lifecycle through the corresponding tenant PVC and PV reclaim policy instead.

Deleting any DataVolume or its PVC while a VM or tenant PVC depends on it can prevent workloads from starting, detach required disk content, or cause data loss.

Troubleshoot data volumes

Import is stuck or slow

Check the raw CDI phase and DataVolume conditions in the namespace where the DataVolume was created:

kubectl get datavolume -n vcluster-platform
kubectl describe datavolume -n vcluster-platform ubuntu-root-disk

If the phase stays ImportScheduled, ImportInProgress, WaitForFirstConsumer, or PendingPopulation, inspect CDI importer pods and PVC events.

kubectl get pods -n vcluster-platform -l cdi.kubevirt.io
kubectl describe pvc -n vcluster-platform ubuntu-root-disk

Common causes are an unreachable image URL, missing registry credentials, an invalid certificate ConfigMap, storage quota, an unavailable StorageClass, or a StorageClass with WaitForFirstConsumer binding that needs the VM pod to schedule before the PVC binds.

Data source can't be resolved

If a VM or Machine uses kubevirt.vcluster.com/image-datasource, verify the DataSource exists in the expected namespace:

kubectl get datasource -A
kubectl describe datasource -n golden-images ubuntu-22-04

Use name for a DataSource in the node provider namespace from spec.kubeVirt.clusterRef.namespace, and use namespace/name to select a different namespace explicitly. Also confirm the referenced DataSource points to a valid PVC or VolumeSnapshot. For a cross-namespace clone, verify that the connected-cluster credentials the KubeVirt node provider uses can create datavolumes/source or pods in the DataSource namespace.

Virtual machine console opens but the guest doesn't boot

Inspect the VM's disks and DataVolumes:

kubectl get vm -n vcluster-platform my-vm -o yaml
kubectl get datavolume -n vcluster-platform

The root disk must be present in both spec.template.spec.domain.devices.disks and spec.template.spec.volumes. For provider-generated root disks, kubevirt.vcluster.com/root-disk-size is required whenever kubevirt.vcluster.com/image-url or kubevirt.vcluster.com/image-datasource is set. If the image boots but does not join a tenant cluster, make sure the guest image supports cloudInitNoCloud.

Data volume fails

Describe the DataVolume and review CDI importer logs:

kubectl describe datavolume -n vcluster-platform ubuntu-root-disk
kubectl logs -n vcluster-platform -l cdi.kubevirt.io

Failures usually point to source access, authentication, checksum mismatch, unsupported image format, insufficient storage, or storage provider errors. After correcting the source or storage issue, recreate the DataVolume if CDI cannot retry the failed import.