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.
openapi: 3.1.0
info:
title: KubeVirt Containerized Data Importer DataSources DataVolumes 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
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: 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.
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
components:
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'
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
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.
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
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
DataVolumeList:
type: object
description: List of DataVolume resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/DataVolume'
parameters:
labelSelector:
name: labelSelector
in: query
required: false
description: Label 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
namespace:
name: namespace
in: path
required: true
description: The Kubernetes namespace.
schema:
type: string
fieldSelector:
name: fieldSelector
in: query
required: false
description: Field selector to filter resources.
schema:
type: string
name:
name: name
in: path
required: true
description: The name of the resource.
schema:
type: string
externalDocs:
description: CDI Documentation
url: https://kubevirt.io/user-guide/storage/containerized_data_importer/