Operations for managing VirtualMachine (VM) resources. A VirtualMachine defines the desired state and configuration of a virtual machine, providing lifecycle management and persistence across restarts.
openapi: 3.1.0
info:
title: KubeVirt Containerized Data Importer DataSources VirtualMachines 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: VirtualMachines
description: Operations for managing VirtualMachine (VM) resources. A VirtualMachine defines the desired state and configuration of a virtual machine, providing lifecycle management and persistence across restarts.
paths:
/apis/kubevirt.io/v1/namespaces/{namespace}/virtualmachines:
get:
operationId: listNamespacedVirtualMachine
summary: KubeVirt List VirtualMachines in a namespace
description: Returns all VirtualMachine resources in the specified namespace. Each VirtualMachine defines a desired VM configuration and controls whether the VM is running or stopped.
tags:
- VirtualMachines
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 VirtualMachines
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachineList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedVirtualMachine
summary: KubeVirt Create a VirtualMachine
description: Creates a new VirtualMachine resource defining the VM's CPU, memory, disk, network configuration, and run strategy. KubeVirt will create a VirtualMachineInstance when the VM is started.
tags:
- VirtualMachines
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachine'
responses:
'201':
description: VirtualMachine created
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachine'
'400':
description: Invalid VirtualMachine specification
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: VirtualMachine already exists
/apis/kubevirt.io/v1/namespaces/{namespace}/virtualmachines/{name}:
get:
operationId: readNamespacedVirtualMachine
summary: KubeVirt Get a VirtualMachine
description: Returns the specified VirtualMachine resource including its current status, run strategy, and associated VirtualMachineInstance reference.
tags:
- VirtualMachines
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: VirtualMachine details
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachine'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: VirtualMachine not found
put:
operationId: replaceNamespacedVirtualMachine
summary: KubeVirt Replace a VirtualMachine
description: Replaces the entire VirtualMachine resource. Changes to the template take effect on the next VM start or restart.
tags:
- VirtualMachines
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachine'
responses:
'200':
description: VirtualMachine updated
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachine'
'400':
description: Invalid specification
'401':
description: Unauthorized
'404':
description: VirtualMachine not found
patch:
operationId: patchNamespacedVirtualMachine
summary: KubeVirt Partially update a VirtualMachine
description: Applies a partial update to the VirtualMachine using JSON Merge Patch or Strategic Merge Patch.
tags:
- VirtualMachines
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/merge-patch+json:
schema:
type: object
responses:
'200':
description: VirtualMachine patched
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachine'
'400':
description: Invalid patch
'401':
description: Unauthorized
'404':
description: VirtualMachine not found
delete:
operationId: deleteNamespacedVirtualMachine
summary: KubeVirt Delete a VirtualMachine
description: Deletes the VirtualMachine resource. If the VM is running, it will be stopped first.
tags:
- VirtualMachines
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: VirtualMachine deleted
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: VirtualMachine not found
components:
schemas:
VirtualMachineStatus:
type: object
description: Observed status of a VirtualMachine.
properties:
ready:
type: boolean
description: Whether the VM is ready to accept connections.
created:
type: boolean
description: Whether the VMI has been created.
printableStatus:
type: string
description: Human-readable status string.
enum:
- Stopped
- Provisioning
- Starting
- Running
- Paused
- Migrating
- Stopping
- Terminating
- CrashLoopBackOff
- Unknown
- WaitingForVolumeBinding
conditions:
type: array
description: Conditions describing the VM's current state.
items:
type: object
properties:
type:
type: string
status:
type: string
reason:
type: string
message:
type: string
lastTransitionTime:
type: string
format: date-time
volumeSnapshotStatuses:
type: array
description: Snapshot status of attached volumes.
items:
type: object
VirtualMachine:
type: object
description: A KubeVirt VirtualMachine resource defining the desired configuration and lifecycle of a virtual machine. Provides persistent VM definition with start/stop control.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
enum:
- kubevirt.io/v1
kind:
type: string
enum:
- VirtualMachine
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/VirtualMachineSpec'
status:
$ref: '#/components/schemas/VirtualMachineStatus'
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
description: Labels for organizing and selecting resources.
annotations:
type: object
additionalProperties:
type: string
description: Non-identifying metadata.
resourceVersion:
type: string
uid:
type: string
creationTimestamp:
type: string
format: date-time
VirtualMachineSpec:
type: object
description: Specification of a VirtualMachine.
properties:
running:
type: boolean
description: Mutually exclusive with runStrategy. If true, the VM should be running. Deprecated in favor of runStrategy.
runStrategy:
type: string
description: Controls when the VM is running. 'Always' restarts after crash, 'RerunOnFailure' only restarts on failure, 'Manual' requires explicit start/stop, 'Halted' keeps the VM stopped.
enum:
- Always
- RerunOnFailure
- Manual
- Halted
- Once
template:
$ref: '#/components/schemas/VirtualMachineInstanceTemplateSpec'
dataVolumeTemplates:
type: array
description: DataVolume templates to create alongside the VM. These are automatically managed by KubeVirt as part of the VM lifecycle.
items:
type: object
VirtualMachineInstanceTemplateSpec:
type: object
description: Template for creating a VirtualMachineInstance.
properties:
metadata:
type: object
description: Labels and annotations for the VMI.
spec:
$ref: '#/components/schemas/VirtualMachineInstanceSpec'
Disk:
type: object
description: A virtual disk device attached to the VM.
required:
- name
properties:
name:
type: string
description: Name of the disk, must match a volume name.
bootOrder:
type: integer
description: Boot order for this disk (lower numbers boot first).
minimum: 1
disk:
type: object
description: Virtio disk configuration.
properties:
bus:
type: string
enum:
- virtio
- sata
- scsi
- ide
cdrom:
type: object
description: CD-ROM device configuration.
properties:
bus:
type: string
enum:
- virtio
- sata
- scsi
readonly:
type: boolean
lun:
type: object
description: LUN device configuration.
properties:
bus:
type: string
VirtualMachineInstanceSpec:
type: object
description: Specification of the virtual machine hardware and guest configuration.
properties:
domain:
$ref: '#/components/schemas/DomainSpec'
networks:
type: array
description: Network interfaces to attach to the VM.
items:
$ref: '#/components/schemas/Network'
volumes:
type: array
description: Volumes to attach to the VM.
items:
$ref: '#/components/schemas/Volume'
affinity:
type: object
description: Kubernetes affinity rules for pod scheduling.
tolerations:
type: array
description: Kubernetes tolerations for node scheduling.
items:
type: object
nodeSelector:
type: object
additionalProperties:
type: string
description: Node selector constraints for VM placement.
hostname:
type: string
description: Hostname to set in the guest OS.
subdomain:
type: string
description: Subdomain for the VM's DNS entry.
terminationGracePeriodSeconds:
type: integer
description: Grace period in seconds before forceful VM termination.
minimum: 0
evictionStrategy:
type: string
description: Controls how the VM behaves during node eviction. 'LiveMigrate' migrates instead of stopping.
enum:
- LiveMigrate
- None
Interface:
type: object
description: A virtual network interface device.
required:
- name
properties:
name:
type: string
description: Name of the interface, must match a network name.
model:
type: string
description: Network interface model type. 'virtio' is recommended for best performance.
enum:
- virtio
- e1000
- e1000e
- rtl8139
masquerade:
type: object
description: NAT masquerade networking mode.
bridge:
type: object
description: Bridge networking mode, connected to a host bridge.
sriov:
type: object
description: SR-IOV passthrough networking mode.
macAddress:
type: string
description: Fixed MAC address for the interface.
pattern: ^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$
ports:
type: array
description: Port forwarding rules for masquerade interfaces.
items:
type: object
properties:
name:
type: string
port:
type: integer
minimum: 1
maximum: 65535
protocol:
type: string
enum:
- TCP
- UDP
Volume:
type: object
description: A storage volume to attach to a disk device.
required:
- name
properties:
name:
type: string
description: Name of the volume, referenced by disk name.
containerDisk:
type: object
description: OCI container image used as a disk.
properties:
image:
type: string
description: OCI image reference containing the disk image.
imagePullPolicy:
type: string
enum:
- Always
- Never
- IfNotPresent
dataVolume:
type: object
description: DataVolume (CDI) as a disk source.
properties:
name:
type: string
description: Name of the DataVolume resource.
persistentVolumeClaim:
type: object
description: Kubernetes PersistentVolumeClaim as a disk source.
properties:
claimName:
type: string
description: Name of the PVC.
readOnly:
type: boolean
cloudInitNoCloud:
type: object
description: Cloud-init NoCloud data source for guest initialization.
properties:
userData:
type: string
description: Cloud-init user-data as a string.
networkData:
type: string
description: Cloud-init network-config as a string.
cloudInitConfigDrive:
type: object
description: Cloud-init Config Drive data source.
properties:
userData:
type: string
networkData:
type: string
sysprep:
type: object
description: Windows Sysprep answer file source.
properties:
configMap:
type: object
properties:
name:
type: string
emptyDisk:
type: object
description: Ephemeral empty disk created for the VM.
properties:
capacity:
type: string
description: Disk capacity in Kubernetes resource quantity format.
hostDisk:
type: object
description: Host filesystem path as a disk.
properties:
path:
type: string
description: Absolute path on the host.
type:
type: string
enum:
- DiskOrCreate
- Disk
Network:
type: object
description: A network to attach a VM interface to.
required:
- name
properties:
name:
type: string
description: Name of the network, referenced by interface name.
pod:
type: object
description: Default pod network configuration.
properties:
vmNetworkCIDR:
type: string
description: CIDR for the VM network in masquerade mode.
multus:
type: object
description: Multus CNI network attachment.
properties:
networkName:
type: string
description: Name of the NetworkAttachmentDefinition.
default:
type: boolean
description: If true, this is the default network.
DomainSpec:
type: object
description: Virtual hardware configuration for the VM guest.
properties:
cpu:
type: object
description: CPU configuration for the VM.
properties:
cores:
type: integer
description: Number of CPU cores.
minimum: 1
sockets:
type: integer
description: Number of CPU sockets.
minimum: 1
threads:
type: integer
description: Number of CPU threads per core.
minimum: 1
model:
type: string
description: CPU model to emulate, e.g. 'host-model' or 'Westmere'.
dedicatedCpuPlacement:
type: boolean
description: If true, requests dedicated CPU pinning via CPU Manager.
features:
type: array
description: CPU feature flags to enable or disable.
items:
type: object
properties:
name:
type: string
policy:
type: string
enum:
- force
- require
- optional
- disable
- forbid
memory:
type: object
description: Memory configuration for the VM.
properties:
guest:
type: string
description: Amount of memory for the guest OS in Kubernetes resource quantity format, e.g. '2Gi', '512Mi'.
hugepages:
type: object
description: Huge pages configuration.
properties:
pageSize:
type: string
description: Size of huge pages, e.g. '2Mi' or '1Gi'.
devices:
type: object
description: Virtual device configuration.
properties:
disks:
type: array
description: Disk devices attached to the VM.
items:
$ref: '#/components/schemas/Disk'
interfaces:
type: array
description: Network interface devices.
items:
$ref: '#/components/schemas/Interface'
rng:
type: object
description: Random number generator device configuration.
watchdog:
type: object
description: Hardware watchdog device configuration.
features:
type: object
description: Hardware feature flags for the VM.
properties:
acpi:
type: object
description: ACPI configuration.
smm:
type: object
description: System Management Mode configuration.
hyperv:
type: object
description: Hyper-V enlightenments for Windows VMs.
firmware:
type: object
description: Firmware configuration for the VM.
properties:
bootloader:
type: object
description: Bootloader configuration (BIOS or UEFI).
properties:
bios:
type: object
description: BIOS bootloader.
efi:
type: object
description: EFI/UEFI bootloader.
properties:
secureBoot:
type: boolean
description: If true, enables Secure Boot.
serial:
type: string
description: Serial number to expose to the guest.
uuid:
type: string
format: uuid
description: SMBIOS UUID for the VM.
machine:
type: object
description: Machine type configuration.
properties:
type:
type: string
description: Machine type, e.g. 'q35' or 'pc-q35-rhel8.4.0'.
VirtualMachineList:
type: object
description: List of VirtualMachine resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/VirtualMachine'
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 of the resource.
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/