REST API for the Containerized Data Importer (CDI), which provides facilities for importing and cloning virtual machine disk images into PersistentVolumeClaims for use as KubeVirt VM disks. The CDI API includes DataVolume, DataSource, and StorageProfile resources for managing data import pipelines.
openapi: 3.1.0
info:
title: KubeVirt Containerized Data Importer API
description: >-
The KubeVirt Containerized Data Importer (CDI) API provides Kubernetes CRD
endpoints for managing virtual machine disk image import and cloning
pipelines. CDI introduces DataVolume, DataSource, and StorageProfile
resources that automate importing VM disk images from HTTP, S3, OCI
registries, and other sources into PersistentVolumeClaims ready for
use as KubeVirt VM disks.
version: '1.59.0'
contact:
name: KubeVirt Community
url: https://kubevirt.io/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
description: CDI Documentation
url: https://kubevirt.io/user-guide/storage/containerized_data_importer/
servers:
- url: https://{kubernetes-api-server}
description: Kubernetes API server
variables:
kubernetes-api-server:
default: localhost:6443
description: Address of the Kubernetes API server
tags:
- name: DataSources
description: >-
Operations for managing DataSource resources. A DataSource references an
existing DataVolume or VolumeSnapshot as a source for cloning into new
DataVolumes.
- name: DataVolumes
description: >-
Operations for managing DataVolume resources. A DataVolume is a managed
PersistentVolumeClaim with an integrated import/clone pipeline that
automatically populates the volume from a specified source.
- name: StorageProfiles
description: >-
Operations for managing StorageProfile resources. StorageProfiles describe
the capabilities of a StorageClass and provide default clone and access
mode strategies.
paths:
/apis/cdi.kubevirt.io/v1beta1/namespaces/{namespace}/datavolumes:
get:
operationId: listNamespacedDataVolume
summary: KubeVirt List DataVolumes in a namespace
description: >-
Returns all DataVolume resources in the specified namespace. Each
DataVolume tracks the progress of importing or cloning a VM disk image
into a PersistentVolumeClaim.
tags:
- DataVolumes
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/fieldSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: List of DataVolumes
content:
application/json:
schema:
$ref: '#/components/schemas/DataVolumeList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedDataVolume
summary: KubeVirt Create a DataVolume
description: >-
Creates a new DataVolume that will automatically import or clone disk
image data from the specified source into a managed PVC. Supports
importing from HTTP(S) endpoints, S3 buckets, OCI container registries,
existing PVCs, and VolumeSnapshots.
tags:
- DataVolumes
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataVolume'
responses:
'201':
description: DataVolume created
content:
application/json:
schema:
$ref: '#/components/schemas/DataVolume'
'400':
description: Invalid DataVolume specification
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: DataVolume already exists
/apis/cdi.kubevirt.io/v1beta1/namespaces/{namespace}/datavolumes/{name}:
get:
operationId: readNamespacedDataVolume
summary: KubeVirt Get a DataVolume
description: >-
Returns the specified DataVolume including its import progress, phase,
and associated PVC status.
tags:
- DataVolumes
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: DataVolume details
content:
application/json:
schema:
$ref: '#/components/schemas/DataVolume'
'401':
description: Unauthorized
'404':
description: DataVolume not found
put:
operationId: replaceNamespacedDataVolume
summary: KubeVirt Replace a DataVolume
description: >-
Replaces the entire DataVolume resource specification.
tags:
- DataVolumes
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataVolume'
responses:
'200':
description: DataVolume updated
content:
application/json:
schema:
$ref: '#/components/schemas/DataVolume'
'400':
description: Invalid specification
'401':
description: Unauthorized
'404':
description: DataVolume not found
delete:
operationId: deleteNamespacedDataVolume
summary: KubeVirt Delete a DataVolume
description: >-
Deletes the DataVolume and its managed PersistentVolumeClaim.
tags:
- DataVolumes
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: DataVolume deleted
'401':
description: Unauthorized
'404':
description: DataVolume not found
/apis/cdi.kubevirt.io/v1beta1/namespaces/{namespace}/datasources:
get:
operationId: listNamespacedDataSource
summary: KubeVirt List DataSources in a namespace
description: >-
Returns all DataSource resources in the specified namespace. DataSources
reference DataVolumes or VolumeSnapshots that can be used as clone sources.
tags:
- DataSources
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: List of DataSources
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceList'
'401':
description: Unauthorized
post:
operationId: createNamespacedDataSource
summary: KubeVirt Create a DataSource
description: >-
Creates a DataSource that points to a DataVolume or VolumeSnapshot as a
reusable clone source for new DataVolumes.
tags:
- DataSources
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
responses:
'201':
description: DataSource created
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'400':
description: Invalid DataSource specification
'401':
description: Unauthorized
/apis/cdi.kubevirt.io/v1beta1/namespaces/{namespace}/datasources/{name}:
get:
operationId: readNamespacedDataSource
summary: KubeVirt Get a DataSource
description: >-
Returns the specified DataSource including its source reference and ready status.
tags:
- DataSources
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: DataSource details
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'401':
description: Unauthorized
'404':
description: DataSource not found
delete:
operationId: deleteNamespacedDataSource
summary: KubeVirt Delete a DataSource
description: Deletes the specified DataSource resource.
tags:
- DataSources
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: DataSource deleted
'401':
description: Unauthorized
'404':
description: DataSource not found
/apis/cdi.kubevirt.io/v1beta1/storageprofiles:
get:
operationId: listStorageProfiles
summary: KubeVirt List StorageProfiles
description: >-
Returns all StorageProfile resources in the cluster. StorageProfiles are
automatically created by CDI for each StorageClass and describe its
supported access modes and recommended clone strategies.
tags:
- StorageProfiles
parameters:
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: List of StorageProfiles
content:
application/json:
schema:
$ref: '#/components/schemas/StorageProfileList'
'401':
description: Unauthorized
/apis/cdi.kubevirt.io/v1beta1/storageprofiles/{name}:
get:
operationId: readStorageProfile
summary: KubeVirt Get a StorageProfile
description: >-
Returns the specified StorageProfile including its claimed PVC properties,
data import cron source format, and clone strategy.
tags:
- StorageProfiles
parameters:
- $ref: '#/components/parameters/name'
responses:
'200':
description: StorageProfile details
content:
application/json:
schema:
$ref: '#/components/schemas/StorageProfile'
'401':
description: Unauthorized
'404':
description: StorageProfile not found
patch:
operationId: patchStorageProfile
summary: KubeVirt Update a StorageProfile
description: >-
Partially updates a StorageProfile to configure custom clone strategies
or override default access modes for this StorageClass.
tags:
- StorageProfiles
parameters:
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/merge-patch+json:
schema:
type: object
responses:
'200':
description: StorageProfile updated
content:
application/json:
schema:
$ref: '#/components/schemas/StorageProfile'
'401':
description: Unauthorized
'404':
description: StorageProfile not found
components:
parameters:
namespace:
name: namespace
in: path
required: true
description: The Kubernetes namespace.
schema:
type: string
name:
name: name
in: path
required: true
description: The name of the resource.
schema:
type: string
labelSelector:
name: labelSelector
in: query
required: false
description: Label selector to filter resources.
schema:
type: string
fieldSelector:
name: fieldSelector
in: query
required: false
description: Field selector to filter resources.
schema:
type: string
limit:
name: limit
in: query
required: false
description: Maximum number of results per page.
schema:
type: integer
minimum: 1
continueToken:
name: continue
in: query
required: false
description: Pagination continuation token.
schema:
type: string
schemas:
DataVolume:
type: object
description: >-
A CDI DataVolume providing a managed PVC with automated import or clone
pipeline. Integrates with KubeVirt to provision VM disk images from
various sources.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
enum:
- cdi.kubevirt.io/v1beta1
kind:
type: string
enum:
- DataVolume
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/DataVolumeSpec'
status:
$ref: '#/components/schemas/DataVolumeStatus'
DataVolumeSpec:
type: object
description: Specification of a DataVolume.
properties:
source:
$ref: '#/components/schemas/DataVolumeSource'
sourceRef:
type: object
description: Reference to a DataSource providing the import source.
properties:
kind:
type: string
enum:
- DataSource
namespace:
type: string
name:
type: string
pvc:
type: object
description: PVC spec for the managed PersistentVolumeClaim.
properties:
accessModes:
type: array
items:
type: string
enum:
- ReadWriteOnce
- ReadWriteMany
- ReadOnlyMany
resources:
type: object
properties:
requests:
type: object
additionalProperties:
type: string
storageClassName:
type: string
volumeMode:
type: string
enum:
- Block
- Filesystem
storage:
type: object
description: >-
Simplified storage spec. CDI automatically selects access modes
and volume mode based on the StorageProfile.
properties:
resources:
type: object
properties:
requests:
type: object
additionalProperties:
type: string
storageClassName:
type: string
accessModes:
type: array
items:
type: string
volumeMode:
type: string
priorityClassName:
type: string
description: PriorityClass for the import pod.
contentType:
type: string
description: Type of content being imported.
enum:
- kubevirt
- archive
preallocation:
type: boolean
description: If true, preallocates disk space on creation.
checkpoints:
type: array
description: Checkpoints for multi-stage import.
items:
type: object
finalCheckpoint:
type: boolean
description: Whether this is the final checkpoint in a multi-stage import.
DataVolumeSource:
type: object
description: >-
Source configuration for the DataVolume import. Exactly one source type
should be specified.
properties:
http:
type: object
description: Import from an HTTP(S) URL.
required:
- url
properties:
url:
type: string
format: uri
description: HTTP(S) URL of the disk image to import.
secretRef:
type: string
description: Secret containing HTTP authentication credentials.
certConfigMap:
type: string
description: ConfigMap containing CA certificates for HTTPS.
extraHeaders:
type: array
description: Extra HTTP headers for the import request.
items:
type: string
secretExtraHeaders:
type: array
description: Secret references for sensitive HTTP headers.
items:
type: string
s3:
type: object
description: Import from an S3-compatible object store.
required:
- url
properties:
url:
type: string
format: uri
description: S3 URL (s3://) of the disk image.
secretRef:
type: string
description: Secret with AWS credentials.
certConfigMap:
type: string
description: ConfigMap with CA certificates.
registry:
type: object
description: Import from an OCI container registry.
properties:
url:
type: string
description: OCI registry URL of the container disk image.
secretRef:
type: string
description: Secret with registry authentication.
certConfigMap:
type: string
pullMethod:
type: string
enum:
- pod
- node
pvc:
type: object
description: Clone from an existing PersistentVolumeClaim.
required:
- name
properties:
name:
type: string
description: Name of the source PVC.
namespace:
type: string
description: Namespace of the source PVC.
snapshot:
type: object
description: Clone from a VolumeSnapshot.
required:
- name
properties:
name:
type: string
description: Name of the VolumeSnapshot.
namespace:
type: string
description: Namespace of the VolumeSnapshot.
upload:
type: object
description: >-
Receive an upload via the CDI upload proxy. Used with
virtctl image-upload to push disk images directly.
blank:
type: object
description: Create an empty disk volume with no pre-populated data.
imageio:
type: object
description: Import from an oVirt ImageIO endpoint.
properties:
url:
type: string
secretRef:
type: string
certConfigMap:
type: string
diskId:
type: string
vddk:
type: object
description: Import from VMware using VDDK for VM migration.
properties:
url:
type: string
secretRef:
type: string
uuid:
type: string
thumbprint:
type: string
backingFile:
type: string
initImageURL:
type: string
DataVolumeStatus:
type: object
description: Observed status of a DataVolume import pipeline.
properties:
phase:
type: string
description: Current phase of the DataVolume import.
enum:
- Pending
- PVCBound
- ImportScheduled
- ImportInProgress
- CloneScheduled
- CloneInProgress
- SnapshotForSmartCloneInProgress
- SmartClonePVCInProgress
- CSICloneInProgress
- UploadScheduled
- UploadReady
- WaitForFirstConsumer
- Paused
- Succeeded
- Failed
- Unknown
progress:
type: string
description: Import progress percentage (e.g. '42.00%').
restartCount:
type: integer
format: int32
description: Number of times the import pod has been restarted.
claimName:
type: string
description: Name of the managed PersistentVolumeClaim.
conditions:
type: array
description: Conditions describing the DataVolume state.
items:
type: object
DataVolumeList:
type: object
description: List of DataVolume resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/DataVolume'
DataSource:
type: object
description: >-
A CDI DataSource referencing a DataVolume or VolumeSnapshot as a
reusable source for cloning into new DataVolumes.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
enum:
- cdi.kubevirt.io/v1beta1
kind:
type: string
enum:
- DataSource
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
type: object
description: DataSource specification.
properties:
source:
type: object
description: Reference to the clone source.
properties:
pvc:
type: object
description: PVC clone source reference.
properties:
name:
type: string
namespace:
type: string
snapshot:
type: object
description: VolumeSnapshot clone source reference.
properties:
name:
type: string
namespace:
type: string
status:
type: object
description: DataSource readiness status.
properties:
conditions:
type: array
items:
type: object
source:
type: object
description: Resolved source reference.
DataSourceList:
type: object
description: List of DataSource resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/DataSource'
StorageProfile:
type: object
description: >-
A CDI StorageProfile describing the capabilities and recommended
configuration for a specific Kubernetes StorageClass.
properties:
apiVersion:
type: string
enum:
- cdi.kubevirt.io/v1beta1
kind:
type: string
enum:
- StorageProfile
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
type: object
description: StorageProfile specification with user-overridable settings.
properties:
claimPropertySets:
type: array
description: >-
Access mode and volume mode combinations to use when creating
PVCs from this StorageClass.
items:
type: object
properties:
accessModes:
type: array
items:
type: string
volumeMode:
type: string
enum:
- Block
- Filesystem
cloneStrategy:
type: string
description: >-
Preferred clone strategy for this StorageClass. 'copy' uses pod-based
copy, 'snapshot' uses VolumeSnapshot, 'csi-clone' uses CSI clone.
enum:
- copy
- snapshot
- csi-clone
dataImportCronSourceFormat:
type: string
description: Source format used by DataImportCron.
enum:
- pvc
- snapshot
status:
type: object
description: Observed StorageProfile status.
properties:
storageClass:
type: string
description: Name of the associated StorageClass.
provisioner:
type: string
description: CSI provisioner name.
claimPropertySets:
type: array
description: Detected PVC property sets.
items:
type: object
cloneStrategy:
type: string
description: Detected clone strategy.
dataImportCronSourceFormat:
type: string
StorageProfileList:
type: object
description: List of StorageProfile resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/StorageProfile'
ObjectMeta:
type: object
description: Standard Kubernetes object metadata.
required:
- name
properties:
name:
type: string
description: Name of the resource.
namespace:
type: string
description: Namespace the resource belongs to.
labels:
type: object
additionalProperties:
type: string
annotations:
type: object
additionalProperties:
type: string
resourceVersion:
type: string
uid:
type: string
creationTimestamp:
type: string
format: date-time