KubeVirt · Schema
KubeVirt VirtualMachine
Schema for the KubeVirt VirtualMachine custom resource. A VirtualMachine defines the desired configuration and lifecycle management for a virtual machine running on Kubernetes, including CPU, memory, disks, networking, and run strategy.
Cloud NativeIncubatingKubernetesMigrationVirtual MachinesVirtualization
Properties
| Name | Type | Description |
|---|---|---|
| apiVersion | string | API version of the VirtualMachine resource. |
| kind | string | Resource kind. |
| metadata | object | |
| spec | object | |
| status | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://kubevirt.io/schemas/virtualmachine.json",
"title": "KubeVirt VirtualMachine",
"description": "Schema for the KubeVirt VirtualMachine custom resource. A VirtualMachine defines the desired configuration and lifecycle management for a virtual machine running on Kubernetes, including CPU, memory, disks, networking, and run strategy.",
"type": "object",
"required": ["apiVersion", "kind", "metadata", "spec"],
"properties": {
"apiVersion": {
"type": "string",
"description": "API version of the VirtualMachine resource.",
"const": "kubevirt.io/v1"
},
"kind": {
"type": "string",
"description": "Resource kind.",
"const": "VirtualMachine"
},
"metadata": {
"$ref": "#/$defs/ObjectMeta"
},
"spec": {
"$ref": "#/$defs/VirtualMachineSpec"
},
"status": {
"$ref": "#/$defs/VirtualMachineStatus"
}
},
"$defs": {
"VirtualMachineSpec": {
"type": "object",
"description": "Specification of a VirtualMachine defining its configuration and lifecycle policy.",
"properties": {
"runStrategy": {
"type": "string",
"description": "Controls when the VM is running. 'Always' restarts automatically after crash. 'RerunOnFailure' restarts only on non-zero exit. 'Manual' requires explicit start/stop commands. 'Halted' keeps the VM stopped. 'Once' runs the VM once and stops it after completion.",
"enum": ["Always", "RerunOnFailure", "Manual", "Halted", "Once"]
},
"running": {
"type": "boolean",
"description": "Deprecated in favor of runStrategy. If true, the VM should be running."
},
"template": {
"$ref": "#/$defs/VirtualMachineInstanceTemplateSpec"
},
"dataVolumeTemplates": {
"type": "array",
"description": "DataVolume templates managed as part of this VM's lifecycle.",
"items": {
"type": "object"
}
}
}
},
"VirtualMachineInstanceTemplateSpec": {
"type": "object",
"description": "Template for the VirtualMachineInstance created by this VM.",
"properties": {
"metadata": {
"type": "object",
"description": "Labels and annotations to apply to the VMI."
},
"spec": {
"$ref": "#/$defs/VirtualMachineInstanceSpec"
}
}
},
"VirtualMachineInstanceSpec": {
"type": "object",
"description": "Specification of the virtual machine hardware and guest OS configuration.",
"properties": {
"domain": {
"$ref": "#/$defs/DomainSpec"
},
"networks": {
"type": "array",
"description": "Networks to attach VM interfaces to.",
"items": {
"$ref": "#/$defs/Network"
}
},
"volumes": {
"type": "array",
"description": "Storage volumes to attach as VM disks.",
"items": {
"$ref": "#/$defs/Volume"
}
},
"hostname": {
"type": "string",
"description": "Hostname to configure inside the guest OS.",
"maxLength": 63,
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
},
"terminationGracePeriodSeconds": {
"type": "integer",
"description": "Seconds to wait for clean shutdown before forcing VM termination.",
"minimum": 0
},
"evictionStrategy": {
"type": "string",
"description": "Behavior when the node is evicted. 'LiveMigrate' migrates the VM instead of stopping it.",
"enum": ["LiveMigrate", "None"]
},
"nodeSelector": {
"type": "object",
"description": "Node label selector for VM placement.",
"additionalProperties": {
"type": "string"
}
},
"priorityClassName": {
"type": "string",
"description": "PriorityClass name controlling scheduling priority."
}
}
},
"DomainSpec": {
"type": "object",
"description": "Virtual hardware configuration for the VM guest domain.",
"properties": {
"cpu": {
"type": "object",
"description": "CPU configuration for the VM.",
"properties": {
"cores": {
"type": "integer",
"description": "Number of CPU cores per socket.",
"minimum": 1
},
"sockets": {
"type": "integer",
"description": "Number of CPU sockets.",
"minimum": 1
},
"threads": {
"type": "integer",
"description": "Number of hardware threads per core.",
"minimum": 1
},
"model": {
"type": "string",
"description": "CPU model to emulate. Use 'host-model' or 'host-passthrough' to expose host CPU features."
},
"dedicatedCpuPlacement": {
"type": "boolean",
"description": "Request dedicated CPU pinning via Kubernetes CPU Manager for real-time workloads."
},
"isolateEmulatorThread": {
"type": "boolean",
"description": "If true, allocates an extra CPU for the QEMU emulator thread."
}
}
},
"memory": {
"type": "object",
"description": "Memory configuration for the VM.",
"properties": {
"guest": {
"type": "string",
"description": "Memory allocated to the guest OS in Kubernetes resource format.",
"examples": ["2Gi", "512Mi", "4G"]
},
"hugepages": {
"type": "object",
"description": "Huge pages configuration for low-latency memory access.",
"properties": {
"pageSize": {
"type": "string",
"description": "Huge page size.",
"enum": ["2Mi", "1Gi"]
}
}
}
}
},
"devices": {
"type": "object",
"description": "Virtual device configuration for the guest.",
"properties": {
"disks": {
"type": "array",
"description": "Disk devices attached to the VM.",
"items": {
"$ref": "#/$defs/Disk"
}
},
"interfaces": {
"type": "array",
"description": "Network interface devices.",
"items": {
"$ref": "#/$defs/Interface"
}
},
"autoattachPodInterface": {
"type": "boolean",
"description": "If false, the default pod network interface is not attached."
},
"autoattachSerialConsole": {
"type": "boolean",
"description": "If false, the serial console is not attached."
},
"autoattachGraphicsDevice": {
"type": "boolean",
"description": "If false, the default VGA graphics device is not attached."
},
"rng": {
"type": "object",
"description": "VirtIO random number generator device."
},
"blockMultiQueue": {
"type": "boolean",
"description": "If true, enables multi-queue for block devices."
},
"networkInterfaceMultiQueue": {
"type": "boolean",
"description": "If true, enables multi-queue for network interfaces."
}
}
},
"firmware": {
"type": "object",
"description": "Firmware configuration for the guest.",
"properties": {
"bootloader": {
"type": "object",
"description": "Bootloader configuration.",
"properties": {
"bios": {
"type": "object",
"description": "Legacy BIOS bootloader."
},
"efi": {
"type": "object",
"description": "EFI/UEFI bootloader.",
"properties": {
"secureBoot": {
"type": "boolean",
"description": "Enable UEFI Secure Boot."
}
}
}
}
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "SMBIOS UUID for the VM."
},
"serial": {
"type": "string",
"description": "SMBIOS serial number exposed to the guest."
}
}
},
"machine": {
"type": "object",
"description": "Machine type configuration.",
"properties": {
"type": {
"type": "string",
"description": "QEMU machine type.",
"examples": ["q35", "pc-q35-rhel9.2.0"]
}
}
},
"features": {
"type": "object",
"description": "Emulated hardware feature flags.",
"properties": {
"acpi": {
"type": "object",
"description": "ACPI support."
},
"smm": {
"type": "object",
"description": "System Management Mode."
},
"hyperv": {
"type": "object",
"description": "Hyper-V enlightenments for improved Windows VM performance."
}
}
}
}
},
"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 in the spec.volumes list."
},
"bootOrder": {
"type": "integer",
"description": "Boot priority for this disk (1 is highest priority).",
"minimum": 1
},
"disk": {
"type": "object",
"description": "VirtIO or emulated disk device.",
"properties": {
"bus": {
"type": "string",
"description": "Disk bus type.",
"enum": ["virtio", "sata", "scsi", "ide"]
},
"pciAddress": {
"type": "string",
"description": "PCI address for the disk device."
}
}
},
"cdrom": {
"type": "object",
"description": "CD-ROM device.",
"properties": {
"bus": {
"type": "string",
"enum": ["virtio", "sata", "scsi"]
},
"readonly": {
"type": "boolean",
"description": "If true, the CD-ROM is read-only."
}
}
},
"lun": {
"type": "object",
"description": "LUN device for passthrough storage.",
"properties": {
"bus": {
"type": "string",
"enum": ["scsi"]
}
}
},
"io": {
"type": "string",
"description": "I/O mode for this disk.",
"enum": ["native", "threads", "io_uring"]
},
"cache": {
"type": "string",
"description": "Disk cache mode.",
"enum": ["writethrough", "writeback", "none"]
},
"dedicatedIOThread": {
"type": "boolean",
"description": "If true, uses a dedicated I/O thread for this disk."
}
}
},
"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 in spec.networks."
},
"model": {
"type": "string",
"description": "NIC model type. virtio is recommended for performance.",
"enum": ["virtio", "e1000", "e1000e", "rtl8139"]
},
"macAddress": {
"type": "string",
"description": "Fixed MAC address for this interface.",
"pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"
},
"masquerade": {
"type": "object",
"description": "NAT masquerade networking. Default mode for pod network."
},
"bridge": {
"type": "object",
"description": "Bridge networking connecting to a host bridge interface."
},
"sriov": {
"type": "object",
"description": "SR-IOV network passthrough for high-performance networking."
},
"binding": {
"type": "object",
"description": "Custom network binding plugin reference.",
"properties": {
"name": {
"type": "string",
"description": "Name of the binding plugin."
}
}
},
"ports": {
"type": "array",
"description": "Port forwarding rules (masquerade mode only).",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the port forwarding rule."
},
"port": {
"type": "integer",
"description": "Port number to forward.",
"minimum": 1,
"maximum": 65535
},
"protocol": {
"type": "string",
"description": "Protocol to forward.",
"enum": ["TCP", "UDP"]
}
}
}
}
}
},
"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 the interface name."
},
"pod": {
"type": "object",
"description": "Default pod network (cluster-internal).",
"properties": {
"vmNetworkCIDR": {
"type": "string",
"description": "CIDR for the VM's internal network in masquerade mode."
}
}
},
"multus": {
"type": "object",
"description": "Secondary network via Multus CNI.",
"required": ["networkName"],
"properties": {
"networkName": {
"type": "string",
"description": "Name of the NetworkAttachmentDefinition resource."
},
"default": {
"type": "boolean",
"description": "If true, this Multus network is the default network."
}
}
}
}
},
"Volume": {
"type": "object",
"description": "A storage volume providing disk data for a VM disk device.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Name of the volume, referenced by the disk name."
},
"containerDisk": {
"type": "object",
"description": "OCI container image used as an ephemeral disk.",
"required": ["image"],
"properties": {
"image": {
"type": "string",
"description": "OCI image reference containing the disk image.",
"examples": ["quay.io/containerdisks/fedora:latest"]
},
"imagePullPolicy": {
"type": "string",
"enum": ["Always", "Never", "IfNotPresent"]
}
}
},
"dataVolume": {
"type": "object",
"description": "CDI DataVolume providing the disk data.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Name of the DataVolume resource."
}
}
},
"persistentVolumeClaim": {
"type": "object",
"description": "Kubernetes PVC used directly as a disk.",
"required": ["claimName"],
"properties": {
"claimName": {
"type": "string",
"description": "Name of the PersistentVolumeClaim."
},
"readOnly": {
"type": "boolean",
"description": "If true, mounts the PVC read-only."
}
}
},
"cloudInitNoCloud": {
"type": "object",
"description": "Cloud-init NoCloud configuration disk.",
"properties": {
"userData": {
"type": "string",
"description": "Cloud-init user-data script or config."
},
"networkData": {
"type": "string",
"description": "Cloud-init network-config data."
},
"userDataSecretRef": {
"type": "object",
"description": "Secret reference for user-data.",
"properties": {
"name": {
"type": "string"
}
}
}
}
},
"cloudInitConfigDrive": {
"type": "object",
"description": "Cloud-init Config Drive configuration disk.",
"properties": {
"userData": {
"type": "string"
},
"networkData": {
"type": "string"
}
}
},
"emptyDisk": {
"type": "object",
"description": "Ephemeral empty disk created for the VM lifetime.",
"required": ["capacity"],
"properties": {
"capacity": {
"type": "string",
"description": "Disk capacity in Kubernetes resource quantity format.",
"examples": ["20Gi", "100Gi"]
}
}
},
"sysprep": {
"type": "object",
"description": "Windows Sysprep answer file disk.",
"properties": {
"configMap": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the ConfigMap with Sysprep data."
}
}
},
"secret": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
},
"VirtualMachineStatus": {
"type": "object",
"description": "Observed status of a VirtualMachine.",
"properties": {
"printableStatus": {
"type": "string",
"description": "Human-readable VM status string.",
"enum": [
"Stopped",
"Provisioning",
"Starting",
"Running",
"Paused",
"Migrating",
"Stopping",
"Terminating",
"CrashLoopBackOff",
"Unknown",
"WaitingForVolumeBinding"
]
},
"ready": {
"type": "boolean",
"description": "Whether the VM is ready and accepting connections."
},
"created": {
"type": "boolean",
"description": "Whether a VirtualMachineInstance has been created."
},
"conditions": {
"type": "array",
"description": "Status conditions for the VM.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"status": {
"type": "string",
"enum": ["True", "False", "Unknown"]
},
"reason": {
"type": "string"
},
"message": {
"type": "string"
},
"lastTransitionTime": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"ObjectMeta": {
"type": "object",
"description": "Standard Kubernetes object metadata.",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "Name of the VirtualMachine resource.",
"maxLength": 253
},
"namespace": {
"type": "string",
"description": "Namespace the VirtualMachine belongs to."
},
"labels": {
"type": "object",
"description": "Labels for organizing and selecting the VM.",
"additionalProperties": {
"type": "string"
}
},
"annotations": {
"type": "object",
"description": "Non-identifying metadata for the VM.",
"additionalProperties": {
"type": "string"
}
}
}
}
},
"examples": [
{
"apiVersion": "kubevirt.io/v1",
"kind": "VirtualMachine",
"metadata": {
"name": "fedora-vm",
"namespace": "default",
"labels": {
"app": "fedora-vm"
}
},
"spec": {
"runStrategy": "Always",
"template": {
"spec": {
"domain": {
"cpu": {
"cores": 2,
"sockets": 1,
"threads": 1
},
"memory": {
"guest": "4Gi"
},
"devices": {
"disks": [
{
"name": "rootdisk",
"disk": {
"bus": "virtio"
},
"bootOrder": 1
},
{
"name": "cloudinitdisk",
"disk": {
"bus": "virtio"
}
}
],
"interfaces": [
{
"name": "default",
"model": "virtio",
"masquerade": {}
}
]
}
},
"networks": [
{
"name": "default",
"pod": {}
}
],
"volumes": [
{
"name": "rootdisk",
"dataVolume": {
"name": "fedora-dv"
}
},
{
"name": "cloudinitdisk",
"cloudInitNoCloud": {
"userData": "#cloud-config\npassword: fedora\nchpasswd: { expire: False }"
}
}
]
}
},
"dataVolumeTemplates": [
{
"metadata": {
"name": "fedora-dv"
},
"spec": {
"source": {
"registry": {
"url": "docker://quay.io/containerdisks/fedora:38"
}
},
"storage": {
"resources": {
"requests": {
"storage": "20Gi"
}
}
}
}
}
]
}
}
]
}