Most of them are outdated, but provide historical design context.
They are not user documentation and should not be treated as such.
Documentation is available here.
Stable Device Addresses
This document describes the design for the stable Device addresses feature.
In the term Device we include PCI, VirtIO Serial, SCSI, IDE, CCID and actually anything libvirt supports.
Allow devices in guest virtual machines to retain the same device address allocations as other devices are added or removed from the guest configuration. This is particularly important for Windows guests in order to prevent warnings or reactivation when device addresses change.
This feature is supported by libvirt and should be implemented by oVirt Engine and VDSM.
When creating a VM, QEMU allocates device addresses to the guest devices, these addresses are being reported by libvirt to VDSM and VDSM should report it back to oVirt Engine. oVirt Engine should persist the device addresses and report it as part of the VM configuration on the next run. If a change to the VM devices occurred oVirt Engine should detect the change and persist the new device addresses.
- Feature owner: Eli Mesika (emesika)
- GUI Component owner: Not Relevant
- REST Component owner: Not Relevant
- Engine Component owner: Eli Mesika (emesika)
- QA Owner: Yaniv Kaul (ykaul)
- Target Release: 3.1
- Status: Done
- Last updated date: Wed Mar 14 2012
- Email: email@example.com
The general implementation concepts are:
- The ‘create’ verb should get a new parameter in the XML describing the device addresses of the VM. This parameter is optional and if not given VDSM should learn the device addresses from libvirt.
- The device addresses are not being parsed by oVirt Engine, they are persisted as is without manipulations of the data.
- The ‘getAllVmStats’ verb should report the hash of the device addresses of the VMS.
- If a change is detected by RHEVM to the device addresses (the reported hash was changed), it should query VDSM for the full VM configuration by using the ‘list’ verb with the ‘long’ format and the list of changed VMs.
- The list verb should report the device addresses as part of the VM configuration.
- Export - the device addresses should be part of the exported configuration of the VM.
- Import - the device addresses should be part of the imported configuration of the VM.
- The ‘list’ verb reports the full configuration of all the VMs on the host. This verb was extended to support a given list of VMs to avoid the overhead of reporting all VMs configuration while only a small group is needed.
Feature is not exposed currently to the GUI.
REST Design (Modeling)
Feature is not exposed currently to the REST API.
This section describes the backend design for this feature.
Old API will be supported for Clusters with Compatibility Version under 3.1 Sample:
New API will be used for Clusters with Compatibility Version 3.1 or upper
VDSM will distinguish if a new format or old format was sent according to existence/absence of the ‘devices’ key
DB Design New table vm_device: device_id -- Unique identifier of the VM device vm_id -- The VM/Template id (FK of vm_static) type -- The type (for example : disk, interface etc.) device -- The device (for example : floppy, cdrom etc.) address -- The device address as a string boot_order -- The device boot order spec_params -- The device special parameters, for example ('display': 'vnc') is_managed -- Indicates if the device is managed is_plugged -- Indicates if device is plugable is_readonly -- Indicates if device is read-only.
Adding a column to vm_dynamic:
hash -- holds the md5 like hash indicating a change
Generation CRUD SPs for the new vm_device table Modify all relevant views & SP to have the hash field.
In order to prevent data duplication we will tend to upgrade some old data to new format and still be backward compatible. Examples : boot order,floppy/CDROM as a disk …
We will keep a hash the database, the hash will enable us distinguish when a change occurs, if hash changed we have to get the new full structured data using the List (full) verb and save it to the database.
We will use cluster level decision, since we will have to support migration from host to host in the same Cluster. New API for both sending (create) and receiving (get*VmStats, List) information will use VM parameters as a structured dictionary
Upon VM creation , send structure with empty string in missing information (addresses etc.) Otherwise, fill structure with persistent values and send it to VDSM
refreshVdsRunTimeInfo is called
GetAllVMStats is called For each VM info if (hash from vdsm hash from db) add VM to changed-vm-list next if (changed-vm-list length > 0) Issue a call to vdsm list command with 'long' & changed-vm-list For each VM in list persist all changed data in db. update hash for VM in db next end
 New vdsm list command syntax allows that :
vdsClient 0 list –help list
[view] [vms:vmId1,vmId2] Lists all available machines on the specified server. Optional vms list, should start with 'vms:' and follow with 'vmId1,vmId2,...' Optional views: "long" all available configuration info (Default). "table" table output with the fields: vmId, vmName, Status and IP. "ids" all vmIds.
OVFWriter should be extended to write the information retrieved in the new structure from VDSM to the OVF file. Change should be coordinated with OVF team.
OVFReader should be extended to read the information retrieved in the new structure from VDSM from the OVF file.
VM/vm_dynamic entities should have additional hash properties New VmDevice BE and VmDeviceDAO to handle all changes on vm_device
Unmanaged Device will be supported in the new format and will include all unhandled devices as sound/controller/etc and future devices. Those devices will be persistent and will have Type , SubType (device specific) and an Address. For 3.1 an unmanaged Device is not exposed to any GUI/REST API. Unmanaged devices are passed to vdsm inside a Custom property. VDSM in it turn is passing this as is for possible hook processing.
Floppy / CDROM
Floppy and CDROM will be typed as disk where its subtype is ‘floppy’ or ‘cdrom’
Boot order is a device property (just for subgroup of all available devices), We should add and persist boot order to all relevant entities
Managed and un-managed devices
In general, each device that backend knows to recognize by itself is a managed device (its is_managed flag in vm_device is set to true) Each device that we are learning via vdsm is considered as un-managed device. There is one exception for this rule, we will handle a SpecialManagedDevices white-list in vdc-options. This list will include a list of
Action Table Map
The following table summarizes the possible scenarios when getting data from VDSM and comparing it with backend data stored in the database
Note also that if a device is sent by backend but VDSM don’t get it from libvirt, it will not be returned by VDSM to the backend.
Attach /Detach and Plug/Unplug will update vm_device in the appropriate commands as follows: Attach /Detach - Add/Remove from vm_device Plug/Unplug - Set/Reset address field of the device in vm_device
Adding support for hash parameter in Create. Return the hash value for each VM when calling GetAllVMStats. Return the full VM structure for each VM when calling List with ‘long’ format Enable to pass additional parameter specifying VM ids.
Add tests for new VM device DAL Modify all tests to track new added properties
Verify that all new Device DAO tests pass Verify that all VM DAO tests pass Verify that all Disk DAO and Disk VM mapping DAO tests pass Test both old & new OVFs for export/import
This feature requires pre-integration since we have to play with devices on various VM configuration. Extensive check of Import/Export of both new & old formats. In addition backward compatibility should be tested as well in order to verify that 3.0 VMs preserve and restore all properties under the new implementation.
Design check list
This section describes issues that might need special consideration when writing this feature. Better sooner than later :-)
1. Installer / Upgrader a. .... 1. DB Upgrade a. Add hash & domxml new columns to vm_dynamic. 1. MLA a. .... 1. Migrate a. ... 1. Compatibility levels a. Supported DC versions .... a. Supported Cluster versions .... 1. Backward compatibility issues 1. API changes (changes required in the API between components (GUI/REST Backend VDSM libvirt)) a. Backend VDSM (See VDSM section) 1. .... 1. Effected features - Other features that might be effected by the change (workflow changes, utilities, ...) a. ..... 1. Performance requirements / tests a. Is there a special performance requirement for this feature? a. Are there special performance tests we want to make on this feature? 1. Test cases a. Describe here the basic test cases for the feature 1. Feature tracker bugs 1. References a. Bugzilla https://bugzilla.redhat.com/show_bug.cgi?id=745274 a. Mailing lists a. Other relevant wiki pages http://fedoraproject.org/wiki/Features/KVM_Stable_PCI_Addresses a. Other relevant technical documents
1. Direct LUN considerations. 2. What happens to a Hot Plug device if the Cluster is downgraded from 3.1 to 3.0 ? 3. Regarding boot sequence: We currently have default boot sequence in the template level. The question is how this is handled in moving from 3.0 to 3.1 and vice verse a) 3.0 to 3.1 - we will have to write the logic that tries to match the conversion from current Enum BootSequence value to the new format b) 3.1 to 3.0 - we have a problem here either we : I) Do Best Effort and covert to the closet BootSequence Enum II)or , we can store the templates default boot sequence in the vm_device table as well
Known Issues / Risks
Main issues are backward compatibility and affect of new 3.1 features.
Manage internal unique index for ‘iface’ virtio’ or ‘ide’ Same ordering as in old format should be kept in order to support 3.0 VMs that starts to run on 3.1 cluster When a VM that run perviously on 3.0 cluster starts to run for the first time on a 3.1 cluster, we must send its devices in the same order to VDSM, if this is not done, libvirt can not guarantee that devices will preserve their addresses. We currently maintain an index only for Floppy (index 0) and CD (index 2)
Hot Plug Disk/Nic
Since managing this is via backend, we always assume that we get the exact Disk/Nic number as we know already. In case that we got a device that is not recognized (even if it a Hot Plug) , it will be handled as a unmanaged Device
We should support and persist an optional disk , this is implemented as a new attribute of the disk entry in the API. Optional flag is passed as static false in 3.1
Direct LUN enables adding a block device to the system either by its GUID or UUID TBD
This 3.1 feature does not affect directly the Stable Device Addresses feature, however, it does affect the import/export and the OVF structure. Details about that will be added as part of 3.1 snapshot changes documentation.
1. OVF Documentation 2. Release Notes