Operations for managing VirtualMachineInstance (VMI) resources. A VirtualMachineInstance represents a running virtual machine and tracks its actual state.
openapi: 3.1.0
info:
title: KubeVirt Containerized Data Importer DataSources VirtualMachineInstances 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: VirtualMachineInstances
description: Operations for managing VirtualMachineInstance (VMI) resources. A VirtualMachineInstance represents a running virtual machine and tracks its actual state.
paths:
/apis/kubevirt.io/v1/namespaces/{namespace}/virtualmachineinstances:
get:
operationId: listNamespacedVirtualMachineInstance
summary: KubeVirt List VirtualMachineInstances
description: Returns all running VirtualMachineInstance resources in the specified namespace. Each VMI represents an active virtual machine process.
tags:
- VirtualMachineInstances
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/fieldSelector'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: List of VirtualMachineInstances
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachineInstanceList'
'401':
description: Unauthorized
'403':
description: Forbidden
/apis/kubevirt.io/v1/namespaces/{namespace}/virtualmachineinstances/{name}:
get:
operationId: readNamespacedVirtualMachineInstance
summary: KubeVirt Get a VirtualMachineInstance
description: Returns the specified VirtualMachineInstance including its phase, network interfaces, volumes, node assignment, and guest OS information.
tags:
- VirtualMachineInstances
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: VirtualMachineInstance details
content:
application/json:
schema:
$ref: '#/components/schemas/VirtualMachineInstance'
'401':
description: Unauthorized
'404':
description: VirtualMachineInstance not found
components:
schemas:
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
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
VirtualMachineInstance:
type: object
description: A running VirtualMachineInstance representing the actual state of an active virtual machine process in KubeVirt.
properties:
apiVersion:
type: string
enum:
- kubevirt.io/v1
kind:
type: string
enum:
- VirtualMachineInstance
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/VirtualMachineInstanceSpec'
status:
$ref: '#/components/schemas/VirtualMachineInstanceStatus'
VirtualMachineInstanceList:
type: object
description: List of VirtualMachineInstance resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/VirtualMachineInstance'
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.
VirtualMachineInstanceStatus:
type: object
description: Observed runtime status of a VirtualMachineInstance.
properties:
nodeName:
type: string
description: Node where the VMI is running.
guestOSInfo:
type: object
description: Information about the guest operating system.
properties:
name:
type: string
description: OS name reported by the guest agent.
version:
type: string
description: OS version.
id:
type: string
description: OS ID (e.g. 'rhel', 'ubuntu').
prettyName:
type: string
description: Human-readable OS name.
interfaces:
type: array
description: Network interfaces as reported by the guest agent.
items:
type: object
properties:
name:
type: string
mac:
type: string
ipAddress:
type: string
ipAddresses:
type: array
items:
type: string
phase:
type: string
description: Current lifecycle phase of the VMI.
enum:
- Pending
- Scheduling
- Scheduled
- Running
- Succeeded
- Failed
- Unknown
phaseTransitionTimestamps:
type: array
description: History of phase transitions with timestamps.
items:
type: object
properties:
phase:
type: string
phaseTransitionTimestamp:
type: string
format: date-time
migrationState:
type: object
description: Current migration state if the VMI is being migrated.
properties:
startTimestamp:
type: string
format: date-time
endTimestamp:
type: string
format: date-time
targetNode:
type: string
sourceNode:
type: string
completed:
type: boolean
failed:
type: boolean
conditions:
type: array
items:
type: object
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'.
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
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
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/