CDI, the Containerized Data Importer, is a Kubernetes sub-project of KubeVirt that manages the import, upload, cloning, and lifecycle of virtual machine disk images as Kubernetes PersistentVolumeClaims (PVCs). It provides a custom resource called DataVolume (DV) that abstracts the process of getting VM disk content into a PVC and keeping it ready for use by a KubeVirt virtual machine. Without CDI, teams running VMs on Kubernetes would need to manually provision and populate disk PVCs before a VM could start.
CDI was originally created to solve the disk provisioning problem for VMs on Kubernetes: VM images are typically large binary files (qcow2, raw, VMDKs) stored in registries or object storage, not in Kubernetes-native formats. CDI provides controllers that understand these formats, can fetch and convert them, and can populate PVCs that KubeVirt VMs then boot from. Over time, CDI expanded to handle VM disk cloning, upload from local sources, and the storage coordination required for live VM migration.
The DataVolume Custom Resource
The DataVolume is CDI’s primary abstraction. A DataVolume spec declares a source (where disk content comes from) and a PVC template (what storage to provision). CDI’s controller watches for DataVolume objects and orchestrates the work of creating the PVC and populating it.
Supported DataVolume sources include:
- HTTP/HTTPS: import a disk image from a web URL
- S3/object storage: pull a disk image from an S3-compatible bucket
- Container registry: pull a disk image bundled in a container image layer
- Upload: accept a disk image pushed directly via the CDI upload proxy
- Clone: copy an existing PVC’s contents into a new PVC (used for VM template instantiation)
- Blank: create an empty disk of a specified size
CDI handles format detection and conversion automatically. A qcow2 image fetched from HTTP is converted to a raw block device format as it is written to the target PVC. This means VMs always boot from raw block devices regardless of the source image format.
CDI and Live VM Migration
Live migration is one of the most operationally important use cases for CDI in a Kubernetes environment. When KubeVirt initiates a live migration, the VM must be moved from one node to another while continuing to run. The storage layer must support this transition.
CDI coordinates the storage side of live migration: it provisions a target PVC on the destination node, handles the disk data copy (either via storage-level clone or data transfer), and signals KubeVirt when the target disk is ready for the VM’s memory and CPU state to be transferred. The specific mechanism depends on the storage access mode:
- ReadWriteMany (RWX) block volumes: both source and destination nodes can mount the same PVC simultaneously. No data copy is needed; migration transfers only CPU and memory state.
- ReadWriteOnce (RWO) volumes: CDI must copy the disk contents to a new PVC on the destination node before migration can proceed.
For live migration to work efficiently, block storage must support RWX mode or provide fast clone operations. Simplyblock provides RWX block volumes, enabling live migration without a disk copy. This is the recommended configuration for Red Hat® OpenShift® Virtualization environments where VM live migration must complete quickly without extended disk transfer windows.
🚀 Running KubeVirt VMs on OpenShift and need fast live migration? Simplyblock provides ReadWriteMany block volumes for zero-copy live migration and instant CDI clone operations. 👉 See OpenShift Virtualization storage
CDI and Volume Snapshots
CDI integrates with the Kubernetes CSI VolumeSnapshot API to create VM disk snapshots. A DataVolume can be cloned from a VolumeSnapshot, which enables rapid VM template instantiation: take a snapshot of a golden OS disk, then clone it for each new VM without transferring the full disk image for each instance. This is particularly valuable for automated VM provisioning at scale.
The snapshot-to-DataVolume flow depends on the underlying storage providing fast copy-on-write (CoW) snapshots. On slow storage that implements snapshots as full copies, each clone operation transfers the full disk size and takes minutes. On simplyblock, snapshots are instant CoW operations and clones are provisioned immediately, making template-based VM provisioning effectively instantaneous regardless of disk size.
CDI Architecture
CDI runs as a set of controllers inside the Kubernetes cluster:
- CDI controller: watches DataVolume objects and drives their lifecycle (Pending, ImportScheduled, Importing, Succeeded, etc.)
- CDI importer pod: a temporary pod spawned for each import operation, responsible for fetching and writing disk data to the target PVC
- CDI upload proxy: a service that accepts disk image uploads from outside the cluster and proxies them to the appropriate importer pod
- CDI API server: validates DataVolume objects and provides upload token generation
The importer pod runs on the node where the target PVC will be mounted, which ensures the data write path is local to the storage attachment point. CDI is installed as an operator and managed via a CDI custom resource at the cluster level.
How Simplyblock Works with CDI
Simplyblock’s CSI driver supports the full set of storage operations CDI relies on: dynamic PVC provisioning, ReadWriteMany block volumes, instant CoW cloning via the CSI clone API, and VolumeSnapshot creation and restoration.
For DataVolume import operations, simplyblock provisions the target PVC via standard dynamic provisioning. The importer pod writes disk data to the PVC over NVMe/TCP, with simplyblock delivering the sub-millisecond write latency and high throughput that makes large disk imports complete quickly.
For live migration via RWX volumes, simplyblock allows both the source and destination nodes to mount the same block PVC simultaneously. KubeVirt’s migration controller transfers the VM’s CPU and memory state while the disk remains accessible from both nodes. After migration completes, the source node detaches from the PVC and the VM continues running on the destination node.
See the KubeVirt storage and OpenShift Virtualization storage pages for full architecture details on how simplyblock integrates with CDI in production KubeVirt deployments.
Related Terms
CDI sits at the intersection of KubeVirt, Kubernetes storage, and virtual machine lifecycle management.
- What Is KubeVirt Storage
- OpenShift Virtualization
- VM Live Migration
- CSI Snapshot Architecture
- Kubernetes Access Modes
Questions and Answers
What is the difference between a DataVolume and a PersistentVolumeClaim in KubeVirt?
A PersistentVolumeClaim is a standard Kubernetes storage request. A DataVolume is a CDI abstraction that wraps a PVC with a source specification and an import lifecycle. When CDI processes a DataVolume, it creates a PVC as the backing storage and populates it with the specified disk content. Once the DataVolume reaches the Succeeded phase, the underlying PVC contains the ready-to-use VM disk and KubeVirt can attach it to a VirtualMachineInstance.
Does CDI work with any Kubernetes CSI storage provider?
CDI works with any CSI provider that supports dynamic PVC provisioning. However, specific CDI features have additional requirements: live migration via RWX requires the CSI driver to support ReadWriteMany block volumes; snapshot-based cloning requires VolumeSnapshot API support; and upload operations require the importer pod to be able to mount and write to the provisioned PVC. Not all CSI drivers support all of these capabilities.
How does CDI handle VM disk images larger than the available memory on import nodes?
CDI’s importer pod streams disk images directly to the PVC as they are fetched, without loading the entire image into memory. Format conversion (qcow2 to raw) is also performed in a streaming fashion. This means CDI can import disk images much larger than the available RAM on the import node, bounded only by the throughput of the network and storage backend.
Can CDI clone a VM disk between different storage classes?
Yes. A DataVolume clone can specify a target PVC in a different StorageClass than the source. CDI handles the data transfer between storage backends. However, cross-StorageClass clones cannot use the fast CSI-native clone path (which requires the same storage backend on source and destination) and fall back to a host-assisted copy where the importer pod reads the source and writes to the target.
What happens to CDI during a KubeVirt upgrade?
CDI is versioned independently of KubeVirt and has its own upgrade lifecycle managed by the CDI operator. Upgrading KubeVirt does not automatically upgrade CDI, and the two have compatibility matrices that should be respected. In Red Hat® OpenShift® Virtualization, both CDI and KubeVirt are managed by the OpenShift Virtualization operator, which coordinates their versions as part of the OpenShift Virtualization release.