Proxmox Inventory: added new statuses for qemu (#4723) (#4775)

* added new statuses for qemu

* added document fragment

* lint fixes

* replaced f strings with %

* move the qmpstatus for qemu to a dedicated group

* added documentation to explain the new addition

* update changelog fragment to reflect the change correctly

* update changelog fragment to reflect the change correctly

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* added a switch to get the qemu extended status

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* groups created when qemu_extended_statuses is true and added tests to make sure they are there

* added test to make sure the groups are not present when qemu_extended_statuses is false

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit b556b142ec)

Co-authored-by: Ilija Matoski <ilijamt@gmail.com>

plugins/inventory/proxmox.py

@@ -92,9 +92,21 @@ DOCUMENTATION = '''
         default: proxmox_
         type: str
       want_facts:
-        description: Gather LXC/QEMU configuration facts.
+        description:
+          - Gather LXC/QEMU configuration facts.
+          - When I(want_facts) is set to C(true) more details about QEMU VM status are possible, besides the running and stopped states.
+            Currently if the VM is running and it is suspended, the status will be running and the machine will be in C(running) group,
+            but its actual state will be paused. See I(qemu_extended_statuses) for how to retrieve the real status.
         default: no
         type: bool
+      qemu_extended_statuses:
+        description:
+          - Requires I(want_facts) to be set to C(true) to function. This will allow you to differentiate betweend C(paused) and C(prelaunch)
+            statuses of the QEMU VMs.
+          - This introduces multiple groups [prefixed with I(group_prefix)] C(prelaunch) and C(paused).
+        default: no
+        type: bool
+        version_added: 5.1.0
       want_proxmox_nodes_ansible_host:
         version_added: 3.0.0
         description:
@@ -431,6 +443,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
     def _get_vm_status(self, properties, node, vmid, vmtype, name):
         ret = self._get_json("%s/api2/json/nodes/%s/%s/%s/status/current" % (self.proxmox_url, node, vmtype, vmid))
         properties[self._fact('status')] = ret['status']
+        properties[self._fact('qmpstatus')] = ret['qmpstatus']
 
     def _get_vm_snapshots(self, properties, node, vmid, vmtype, name):
         ret = self._get_json("%s/api2/json/nodes/%s/%s/%s/snapshot" % (self.proxmox_url, node, vmtype, vmid))
@@ -489,7 +502,8 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         name, vmid = item['name'], item['vmid']
 
         # get status, config and snapshots if want_facts == True
-        if self.get_option('want_facts'):
+        want_facts = self.get_option('want_facts')
+        if want_facts:
             self._get_vm_status(properties, node, vmid, ittype, name)
             self._get_vm_config(properties, node, vmid, ittype, name)
             self._get_vm_snapshots(properties, node, vmid, ittype, name)
@@ -503,10 +517,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         node_type_group = self._group('%s_%s' % (node, ittype))
         self.inventory.add_child(self._group('all_' + ittype), name)
         self.inventory.add_child(node_type_group, name)
-        if item['status'] == 'stopped':
-            self.inventory.add_child(self._group('all_stopped'), name)
-        elif item['status'] == 'running':
-            self.inventory.add_child(self._group('all_running'), name)
+
+        item_status = item['status']
+        if item_status == 'running':
+            if want_facts and ittype == 'qemu' and self.get_option('qemu_extended_statuses'):
+                # get more details about the status of the qemu VM
+                item_status = properties.get(self._fact('qmpstatus'), item_status)
+        self.inventory.add_child(self._group('all_%s' % (item_status, )), name)
 
         return name
 
@@ -528,10 +545,14 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
     def _populate(self):
 
         # create common groups
-        self.inventory.add_group(self._group('all_lxc'))
-        self.inventory.add_group(self._group('all_qemu'))
-        self.inventory.add_group(self._group('all_running'))
-        self.inventory.add_group(self._group('all_stopped'))
+        default_groups = ['lxc', 'qemu', 'running', 'stopped']
+
+        if self.get_option('qemu_extended_statuses'):
+            default_groups.extend(['prelaunch', 'paused'])
+
+        for group in default_groups:
+            self.inventory.add_group(self._group('all_%s' % (group)))
+
         nodes_group = self._group('nodes')
         self.inventory.add_group(nodes_group)
 
@@ -621,6 +642,9 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         if proxmox_password is None and (proxmox_token_id is None or proxmox_token_secret is None):
             raise AnsibleError('You must specify either a password or both token_id and token_secret.')
 
+        if self.get_option('qemu_extended_statuses') and not self.get_option('want_facts'):
+            raise AnsibleError('You must set want_facts to True if you want to use qemu_extended_statuses.')
+
         self.cache_key = self.get_cache_key(path)
         self.use_cache = cache and self.get_option('cache')
         self.host_filters = self.get_option('filters')