Enhance virt_install and virt_cloud_instance to support primary value attribute (ansible-collections#225)

- Added support for a special attribute `_value` and `value` to specify a primary value in the command line options.
- Updated the `_dict2options` function to prioritize `_value` over `value` and handle its formatting correctly.
- Reverted networks.source_opts parameter because it can be simplified by primary value attribute
- Added an example usage of PCI passthrough for a network device in the module documentation.

Author: thinkdoggie

changelogs/fragments/221-networks-source-opts.yaml

@@ -0,0 +1,3 @@
+minor_changes:
+  - virt_install - added support for primary value attribute (_value or value) in dynamic dict options that require a primary value alongside additional attributes.
+  - virt_cloud_instance - added support for primary value attribute (_value or value) in dynamic dict options that require a primary value alongside additional attributes.

changelogs/fragments/225-primary-value-support.yml

@@ -1301,19 +1301,12 @@ class ModuleDocFragment(object):
           - Specify the interface ROM BIOS configuration
           - The dictionary contains key/value pairs that define individual properties.
       source:
-        type: raw
-        description:
-          - Specify the source host interface.
-          - Can be either a string of IFACE name or a dictionary with detailed configuration.
-          - When provided as a string, use I(source_opts) to specify additional source properties.
-          - "Example as string: V(bond0)"
-          - "Example with source_opts: I(source=bond0) and I(source_opts={mode: bridge})"
-      source_opts:
         type: dict
         description:
-          - Additional options for the direct attached macvtap interface.
+          - Specify the details of the direct attached macvtap interface.
           - The dictionary contains key/value pairs that define individual properties.
-        version_added: '2.1.0'
+          - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
+          - "Example: I(source={value: bond0, mode: bridge})"
       target:
         type: dict
         description:
@@ -1391,6 +1384,7 @@ class ModuleDocFragment(object):
       - Attach a controller device to the guest.
       - The dictionary contains key/value pairs that define individual controller properties.
       - Examples include I(type=usb,model=none) to disable USB, or I(type=scsi,model=virtio-scsi) for VirtIO SCSI.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   controller_devices:
     type: list
     elements: dict
@@ -1406,6 +1400,7 @@ class ModuleDocFragment(object):
       - Attach an input device to the guest.
       - Input device types include mouse, tablet, or keyboard.
       - The dictionary contains key/value pairs that define individual input device properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   input_devices:
     type: list
     elements: dict
@@ -1420,6 +1415,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a physical host device to the guest.
       - The dictionary contains key/value pairs that define individual host device properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   host_devices:
     type: list
     elements: dict
@@ -1435,6 +1431,7 @@ class ModuleDocFragment(object):
       - Attach a virtual audio device to the guest.
       - The dictionary contains key/value pairs that define individual sound device properties.
       - Common properties include I(model) (e.g. V(ich6), V(ich9), V(ac97)).
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   sound_devices:
     type: list
     elements: dict
@@ -1449,6 +1446,7 @@ class ModuleDocFragment(object):
     description:
       - Configure host audio output for the guest's sound hardware.
       - The dictionary contains key/value pairs that define individual audio backend properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   audio_devices:
     type: list
     elements: dict
@@ -1463,6 +1461,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a virtual hardware watchdog device to the guest.
       - The dictionary contains key/value pairs that define individual watchdog properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   watchdog_devices:
     type: list
     elements: dict
@@ -1477,6 +1476,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a serial device to the guest with various redirection options.
       - The dictionary contains key/value pairs that define individual serial device properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   serial_devices:
     type: list
     elements: dict
@@ -1491,6 +1491,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a parallel device to the guest.
       - The dictionary contains key/value pairs that define individual parallel device properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   parallel_devices:
     type: list
     elements: dict
@@ -1505,6 +1506,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a communication channel device to connect the guest and host machine.
       - The dictionary contains key/value pairs that define individual channel properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   channel_devices:
     type: list
     elements: dict
@@ -1520,6 +1522,7 @@ class ModuleDocFragment(object):
       - Connect a text console between the guest and host.
       - The dictionary contains key/value pairs that define individual console properties.
       - Common properties include I(type) and I(target) for different console types.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   console_devices:
     type: list
     elements: dict
@@ -1534,6 +1537,7 @@ class ModuleDocFragment(object):
     description:
       - Specify what video device model will be attached to the guest.
       - The dictionary contains key/value pairs that define individual video device properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   video_devices:
     type: list
     elements: dict
@@ -1548,6 +1552,7 @@ class ModuleDocFragment(object):
     description:
       - Configure a virtual smartcard device.
       - The dictionary contains key/value pairs that define individual smartcard properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   smartcard_devices:
     type: list
     elements: dict
@@ -1563,6 +1568,7 @@ class ModuleDocFragment(object):
       - Add a redirected device for USB or other device redirection.
       - The dictionary contains key/value pairs that define individual redirection properties.
       - Common properties include I(bus=usb), I(type=tcp) or I(type=spicevmc).
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   redirected_devices:
     type: list
     elements: dict
@@ -1578,6 +1584,7 @@ class ModuleDocFragment(object):
       - Attach a virtual memory balloon device to the guest.
       - The dictionary contains key/value pairs that define individual memory balloon properties.
       - Common properties include I(model) (e.g. V(virtio), V(xen)).
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   memballoon_devices:
     type: list
     elements: dict
@@ -1592,6 +1599,7 @@ class ModuleDocFragment(object):
     description:
       - Configure a virtual TPM (Trusted Platform Module) device.
       - The dictionary contains key/value pairs that define individual TPM properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   tpm_devices:
     type: list
     elements: dict
@@ -1606,6 +1614,7 @@ class ModuleDocFragment(object):
     description:
       - Configure a virtual random number generator (RNG) device.
       - The dictionary contains key/value pairs that define individual RNG properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   rng_devices:
     type: list
     elements: dict
@@ -1620,6 +1629,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a panic notifier device to the guest.
       - The dictionary contains key/value pairs that define individual panic device properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   panic_devices:
     type: list
     elements: dict
@@ -1634,6 +1644,7 @@ class ModuleDocFragment(object):
     description:
       - Attach a shared memory device to the guest.
       - The dictionary contains key/value pairs that define individual shared memory properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   shmem_devices:
     type: list
     elements: dict
@@ -1648,6 +1659,7 @@ class ModuleDocFragment(object):
     description:
       - Configure a vsock host/guest interface.
       - The dictionary contains key/value pairs that define individual vsock properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   vsock_devices:
     type: list
     elements: dict
@@ -1662,6 +1674,7 @@ class ModuleDocFragment(object):
     description:
       - Add an IOMMU device to the guest.
       - The dictionary contains key/value pairs that define individual IOMMU properties.
+      - "You can use the special attribute I(value) to specify a primary value that appears before other properties in the command line."
   iommu_devices:
     type: list
     elements: dict

plugins/doc_fragments/virt_install.py

@@ -73,8 +73,25 @@ def _dict2options(obj, mapping, prefix=""):
     if not isinstance(obj, dict):
         return str(obj)
 
+    # Extract primary value if present
+    # Priority: _value takes precedence over value
+    primary_value = None
+    primary_key = None
+
+    if '_value' in obj:
+        primary_value = obj['_value']
+        primary_key = '_value'
+    elif 'value' in obj:
+        primary_value = obj['value']
+        primary_key = 'value'
+
+    # Create a copy of the dict without the primary key for processing
+    obj_copy = obj.copy()
+    if primary_key:
+        del obj_copy[primary_key]
+
     parts = []
-    for k, v in obj.items():
+    for k, v in obj_copy.items():
         if v is None:
             continue
 
@@ -122,7 +139,24 @@ def _dict2options(obj, mapping, prefix=""):
         else:
             parts.append("{}{}={}".format(prefix, name, str(v)))
 
-    if parts:
+    # Combine primary value with other parts
+    if primary_value is not None:
+        primary_str = str(primary_value)
+
+        # If we have a prefix, the primary value should be associated with it
+        # Remove trailing dot from prefix for the primary value assignment
+        if prefix:
+            prefix_without_dot = prefix.rstrip('.')
+            primary_part = "{}={}".format(prefix_without_dot, primary_str)
+        else:
+            # At root level, primary value stands alone
+            primary_part = primary_str
+
+        if parts:
+            return "{},{}".format(primary_part, ",".join(parts))
+        else:
+            return primary_part
+    elif parts:
         return ",".join(parts)
     else:
         return ""
@@ -524,7 +558,6 @@ def _build_network_options(self):
             network_mapping = {
                 'trust_guest_rx_filters': ('trustGuestRxFilters', None),
                 'state': ('link.state', None),
-                'source_opts': ('source', None),
             }
             for network in network_param:
                 self._add_parameter('--network',
@@ -776,19 +809,6 @@ def _validate_params(self):
                             msg="cloud_init.{} must be a string or dictionary, got {}".format(
                                 param_name, type(param_value).__name__))
 
-        if self.params.get('networks') is not None:
-            for idx, network in enumerate(self.params['networks']):
-                if network.get('source') is not None:
-                    source_value = network['source']
-                    if not isinstance(source_value, (str, dict)):
-                        self.module.fail_json(
-                            msg="networks[{}].source must be a string or dictionary, got {}".format(
-                                idx, type(source_value).__name__))
-
-                    if isinstance(source_value, dict) and network.get('source_opts') is not None:
-                        self.module.fail_json(
-                            msg="networks[{}].source and networks[{}].source_opts cannot both be dictionaries.")
-
     def _build_command(self):
         """Build the complete virt-install command"""
         self._validate_params()
@@ -1505,8 +1525,7 @@ def get_networks_args():
                 network=dict(type='str'),
                 bridge=dict(type='str'),
                 hostdev=dict(type='str'),
-                source=dict(type='raw'),
-                source_opts=dict(type='dict'),
+                source=dict(type='dict'),
                 mac=dict(type='dict', options=dict(address=dict(type='str'))),
                 mtu=dict(type='dict'),
                 state=dict(type='dict'),

plugins/module_utils/virt_install.py

@@ -283,6 +283,20 @@
     import: true
 
 
+# VM with PCI passthrough for a network device
+- name: Create VM with PCI network passthrough
+  community.libvirt.virt_install:
+    name: passthrough-vm
+    memory: 4096
+    vcpus: 4
+    disks:
+      - size: 30
+    osinfo:
+      name: ubuntu20.04
+    import: true
+    host_devices:
+      - value: "81:00.0"
+
 # Recreate existing VM
 - name: Recreate existing VM with new configuration
   community.libvirt.virt_install: