Skip to main content

​
Overview

The DataVolume class provides a declarative way to create and manage persistent volumes for virtual machines. It handles data import from various sources including HTTP, container registries, PVCs, and supports direct upload and blank disk creation.

​
Class Definition

from ocp_resources.datavolume import DataVolume

class DataVolume(NamespacedResource):
    api_group = NamespacedResource.ApiGroup.CDI_KUBEVIRT_IO

​
Constructor

​
source
string
deprecated
Source type for the DataVolume: "upload", "http", "pvc", "registry", or "blank". Use source_dict instead.
​
source_dict
dict
Dictionary defining the DataVolume source configuration. This is the recommended way to specify sources.
​
size
string
DataVolume size in Kubernetes resource format (e.g., "5Gi", "100Mi").
​
storage_class
string
Name of the StorageClass to use for the DataVolume.
​
url
string
URL for importing data when source is "http" or "registry".
​
content_type
string
Content type of the data: "kubevirt" or "archive".
​
access_modes
string
Access mode for the volume: "ReadWriteOnce" (RWO), "ReadOnlyMany" (ROX), or "ReadWriteMany" (RWX).
​
volume_mode
string
Volume mode: "Filesystem" or "Block".
​
cert_configmap
string
Name of ConfigMap containing TLS certificates for HTTPS sources.
​
secret
Secret
Secret object containing authentication credentials for the source.
​
hostpath_node
string
Node name to provision the DataVolume on (for hostPath storage).
​
source_pvc
string
Name of the source PVC when cloning from an existing PVC.
​
source_namespace
string
Namespace of the source PVC when cloning.
​
source_ref
dict
Indirect reference to a data source. Fields: kind (e.g., "DataSource"), name, namespace.
​
multus_annotation
string
Network attachment definition name for Multus networking.
​
bind_immediate_annotation
boolean
Request immediate binding even when StorageClass uses WaitForFirstConsumer.
​
preallocation
boolean
Enable disk space preallocation for better performance.
​
api_name
string
default:"pvc"
API to use for DataVolume: "pvc" or "storage". Default will change to "storage" in future releases.
​
checkpoints
list
List of DataVolumeCheckpoints for incremental snapshot operations.
​
final_checkpoint
boolean
Indicates if the current checkpoint is the final one.
​
priority_class_name
string
Priority class for the DataVolume import/clone pod.

​
Access Modes

The DataVolume.AccessMode class defines volume access modes:
  • RWO: ReadWriteOnce - can be mounted read-write by a single node
  • ROX: ReadOnlyMany - can be mounted read-only by many nodes
  • RWX: ReadWriteMany - can be mounted read-write by many nodes

​
Content Types

The DataVolume.ContentType class defines data content types:
  • KUBEVIRT: KubeVirt-specific disk image format
  • ARCHIVE: Archive file that needs to be extracted

​
Volume Modes

The DataVolume.VolumeMode class defines volume modes:
  • BLOCK: Raw block device
  • FILE: Filesystem volume

​
Status Values

The DataVolume.Status class provides constants for DataVolume states:
  • BLANK: Blank disk created
  • PVC_BOUND: PVC is bound
  • IMPORT_SCHEDULED: Import operation scheduled
  • ClONE_SCHEDULED: Clone operation scheduled
  • UPLOAD_SCHEDULED: Upload operation scheduled
  • IMPORT_IN_PROGRESS: Importing data
  • CLONE_IN_PROGRESS: Cloning from source
  • UPLOAD_IN_PROGRESS: Upload in progress
  • SNAPSHOT_FOR_SMART_CLONE_IN_PROGRESS: Creating snapshot for smart clone
  • SMART_CLONE_PVC_IN_PROGRESS: Smart clone in progress
  • UPLOAD_READY: Ready to receive upload
  • UNKNOWN: Status unknown
  • WAIT_FOR_FIRST_CONSUMER: Waiting for first consumer (WaitForFirstConsumer binding mode)
  • PENDING_POPULATION: Waiting for population to start

​
Methods

​
wait_for_dv_success()

Waits for the DataVolume to successfully complete provisioning.
​
timeout
int
default:"TIMEOUT_10MINUTES"
Maximum time to wait for success (default: 600 seconds).
​
failure_timeout
int
default:"TIMEOUT_2MINUTES"
Time to wait for non-Pending status (default: 120 seconds).
​
pvc_wait_for_bound_timeout
int
default:"TIMEOUT_1MINUTE"
Time to wait for PVC to reach Bound status (default: 60 seconds).
​
dv_garbage_collection_enabled
boolean
deprecated
Garbage collection flag (deprecated, removed in v4.19).
​
stop_status_func
callable
Optional function to check for failure conditions. If returns True, raises TimeoutExpiredError.
dv.wait_for_dv_success(timeout=600)

​
wait_deleted()

Waits for both the DataVolume and its associated PVC to be deleted.
​
timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait for deletion (default: 240 seconds).
dv.wait_deleted(timeout=300)

​
delete()

Deletes the DataVolume.
​
wait
boolean
default:"false"
Whether to wait for deletion to complete.
​
timeout
int
default:"TIMEOUT_4MINUTES"
Maximum time to wait for deletion.
​
body
dict
Optional deletion options body.
dv.delete(wait=True, timeout=240)

​
Properties

​
pvc

Returns the associated PersistentVolumeClaim object. 
pvc = dv.pvc
pvc.wait_for_status(status=PersistentVolumeClaim.Status.BOUND)

​
scratch_pvc

Returns the scratch PVC used during import/clone operations. 
scratch = dv.scratch_pvc

​
Usage Examples

from ocp_resources.datavolume import DataVolume
from ocp_resources.resource import get_client

client = get_client()

# Import from HTTP URL
dv = DataVolume(
    client=client,
    name="fedora-dv",
    namespace="default",
    source_dict={
        "http": {
            "url": "https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora-Cloud-Base-38-1.6.x86_64.qcow2"
        }
    },
    size="10Gi",
    storage_class="standard",
    access_modes=DataVolume.AccessMode.RWO,
    volume_mode=DataVolume.VolumeMode.FILE,
    content_type=DataVolume.ContentType.KUBEVIRT
)

dv.create()
dv.wait_for_dv_success(timeout=600)

VirtualMachine

Use DataVolumes as persistent disks for VMs

Virtual Machines Guide

Complete guide to working with virtual machines

​
Notes

The api_name parameter currently defaults to "pvc" but will change to "storage" in a future release. Explicitly set api_name="pvc" to maintain current behavior.
The source parameter is deprecated. Use source_dict instead for better flexibility and type safety.
DataVolumes with WaitForFirstConsumer binding mode will remain in WAIT_FOR_FIRST_CONSUMER status until a pod requests the volume. Use bind_immediate_annotation=True to bind immediately if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us