Bug 976570

Summary: [Docs] [Admin] custom properties per vnic / device using vdsm hooks
Product: Red Hat Enterprise Virtualization Manager Reporter: Zac Dover <zdover>
Component: DocumentationAssignee: Andrew Dahms <adahms>
Status: CLOSED CURRENTRELEASE QA Contact: Tahlia Richardson <trichard>
Severity: high Docs Contact:
Priority: high    
Version: 3.3.0CC: acathrow, amuller, danken, gklein, juwu, rlandman, trichard, yeylon
Target Milestone: ---Keywords: FutureFeature
Target Release: 3.3.1   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard: network
Fixed In Version: Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of: 967541 Environment:
Last Closed: 2014-07-22 04:22:00 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: Network RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Bug Depends On: 967541    
Bug Blocks:    

Description Zac Dover 2013-06-20 20:09:43 UTC
+++ This bug was initially created as a clone of Bug #967541 +++

This has docs impact in the Admin Guide:
https://documentation-devel.engineering.redhat.com/docs/en-US/Red_Hat_Enterprise_Virtualization/3.2/html-single/Administration_Guide/index.html#appe-VDSM_and_Hooks


--- Additional comment from Itamar Heim on 2013-05-27 08:01:22 EDT ---

while this is related to bug 893576, the custom property should be visible in other hooks, like start vm

Comment 1 Tim Hildred 2013-07-25 05:34:53 UTC
Hey Dan, I'm just trying to figure out how this affects the documentation, if at all. 

Itamar says this bug is related to BZ#976158, but I'm having a hard time understanding exactly what is being added. 

What changes when this feature has been added?

Previously, you couldn't .....

Now, you can ....

Comment 2 Assaf Muller 2013-09-24 08:45:27 UTC
http://www.ovirt.org/Features/Device_Custom_Properties

Previously you could only set custom properties for VMs, now you can custom properties for virtual NICs. These custom properties are then sent for each operation related to vNICs: hotplug nic, hot unplug nic, update device, VM creation (Via before_device_create, after_device_create), VM destroy (before_device_destroy, after_device_destroy) and migration verbs (The full list is below).

For example, previously if you wanted to do some operation on a VM's vNICs you could pass a custom property to the VM and before_vm_start would have the custom property exposed. However, you had no way to get down to a specific vNIC, you could only target all of them. Now you can add a custom property to a specific vNIC (Via the new vNIC profiles feature) and the custom property would only be sent to vNICs under that profile.

Section "B.4. Supported VDSM Events" needs to be updated with the new event names: after_device_create, after_device_destroy, after_device_migrate_destination, after_device_migrate_source, before_device_create, before_device_destroy, before_device_migrate_destination and before_device_migrate_source.

Additionally the following events are affected (And can have custom vNIC properties passed on to them): after_nic_hotplug, after_nic_hotunplug, after_update_device, before_nic_hotplug, before_nic_hotunplug, before_update_device.

Section "B.6. The VDSM Hook Domain XML Object" needs to be updated. before/after_update_device, before/after_device_create, before/after_device_destroy, before/after_device_migrate_source/destination all get the XML of the vNIC and not the entire VM's. Additionally, before/after_disk_hotplug, hotunplug get the XML of the disk as well (Unrelated to this feature).

Section "B.7. Defining Virtual Machine Custom Properties" needs to be updated with instructions how to define device custom properties. Detailed instructions are available here:
http://www.ovirt.org/Vdsm_Hooks#Device-level_hooks

Section "B.8. Setting Virtual Machine Custom Properties" needs to be updated with instructions regarding vNIC profiles and vNIC custom properties.

If you need any more information please let me know.

Comment 4 Tim Hildred 2013-10-28 00:05:31 UTC
Reassigning to Jodi Biddle (jbiddle) as I am no longer working on Red Hat Enterprise Virtualization documentation.

Comment 5 Zac Dover 2013-12-10 02:52:57 UTC
What to Do
----------

Make the changes suggested in Assaf Muller's excellent Comment 2, which I include here:

BEGIN QUOTE

Previously you could only set custom properties for VMs, now you can custom properties for virtual NICs. These custom properties are then sent for each operation related to vNICs: hotplug nic, hot unplug nic, update device, VM creation (Via before_device_create, after_device_create), VM destroy (before_device_destroy, after_device_destroy) and migration verbs (The full list is below).

For example, previously if you wanted to do some operation on a VM's vNICs you could pass a custom property to the VM and before_vm_start would have the custom property exposed. However, you had no way to get down to a specific vNIC, you could only target all of them. Now you can add a custom property to a specific vNIC (Via the new vNIC profiles feature) and the custom property would only be sent to vNICs under that profile.

Section "B.4. Supported VDSM Events" needs to be updated with the new event names: after_device_create, after_device_destroy, after_device_migrate_destination, after_device_migrate_source, before_device_create, before_device_destroy, before_device_migrate_destination and before_device_migrate_source.

Additionally the following events are affected (And can have custom vNIC properties passed on to them): after_nic_hotplug, after_nic_hotunplug, after_update_device, before_nic_hotplug, before_nic_hotunplug, before_update_device.

Section "B.6. The VDSM Hook Domain XML Object" needs to be updated. before/after_update_device, before/after_device_create, before/after_device_destroy, before/after_device_migrate_source/destination all get the XML of the vNIC and not the entire VM's. Additionally, before/after_disk_hotplug, hotunplug get the XML of the disk as well (Unrelated to this feature).

Section "B.7. Defining Virtual Machine Custom Properties" needs to be updated with instructions how to define device custom properties. Detailed instructions are available here:
http://www.ovirt.org/Vdsm_Hooks#Device-level_hooks

Section "B.8. Setting Virtual Machine Custom Properties" needs to be updated with instructions regarding vNIC profiles and vNIC custom properties.

END QUOTE

When those changes have been made, move this bug to ON_QA.

Comment 6 Andrew Dahms 2013-12-23 05:02:49 UTC
Requested changes have been made and an additional topic 26734 added to cover the new content.

Comment 7 Andrew Dahms 2014-01-24 03:51:13 UTC
Documentation Link
------------------------------
http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.3/html-single/Administration_Guide/index.html#Supported_VDSM_events

What Changed
------------------------------
The following topics were revised as outlined below:

Supported VDSM Events [ 8288-572849 ]

Added ten rows to the table, starting from before_device_create, to cover the new VDSM hooks.

The VDSM Hook Domain XML Object [ 8290-572855 ]

A new list was created showing the hooks that constitute exceptions.

Defining Custom Properties [ 8291-572859 ]

Updated the STDOUT from the engine-config commands in Step 1. and Step 3. of the procedure, and added a new example, Example 2., that outlines the Interface custom property.

Setting Custom Device Properties [ 26734 ]

Newly created; outlines how to add and remove custom device properties.

Updated revision history: [ 21114-572865 ]

NVR
------------------------------
Red_Hat_Enterprise_Virtualization-Administration_Guide-3.3-en-US-3.3-39

Moving to ON_QA.

Comment 8 Tahlia Richardson 2014-07-22 04:22:00 UTC
Peer reviewed.

All listed changes are visible in the doc. 

VERIFIED