[PR #6852/7adb9985 backport][stable-7] [proxmox_vm_info] New module to retrieve virtual machines information from Proxmox VE API (#6897)

[proxmox_vm_info] New module to retrieve virtual machines information from Proxmox VE API (#6852)

* [proxmox_vm_info] New module to retrieve virtual machines information from Proxmox VE API

* Address review comments

* Fix seealso fragment

* Update plugins/modules/proxmox_vm_info.py

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

---------

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

Co-authored-by: Sergei Antipov <greendayonfire@gmail.com>

plugins/modules/proxmox.py

@@ -213,6 +213,8 @@ options:
     default: opportunistic
     version_added: 4.3.0
 author: Sergei Antipov (@UnderGreen)
+seealso:
+  - module: community.general.proxmox_vm_info
 extends_documentation_fragment:
   - community.general.proxmox.documentation
   - community.general.proxmox.selection

plugins/modules/proxmox_kvm.py

@@ -551,6 +551,8 @@ options:
       - compatibility
       - no_defaults
     version_added: "1.3.0"
+seealso:
+  - module: community.general.proxmox_vm_info
 extends_documentation_fragment:
   - community.general.proxmox.documentation
   - community.general.proxmox.selection

plugins/modules/proxmox_vm_info.py

@@ -0,0 +1,216 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2023, Sergei Antipov <greendayonfire at gmail.com>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = """
+---
+module: proxmox_vm_info
+short_description: Retrieve information about one or more Proxmox VE virtual machines
+version_added: 7.2.0
+description:
+  - Retrieve information about one or more Proxmox VE virtual machines.
+author: 'Sergei Antipov (@UnderGreen) <greendayonfire at gmail dot com>'
+options:
+  node:
+    description:
+      - Node where to get virtual machines info.
+    required: true
+    type: str
+  type:
+    description:
+      - Restrict results to a specific virtual machine(s) type.
+    type: str
+    choices:
+      - all
+      - qemu
+      - lxc
+    default: all
+  vmid:
+    description:
+      - Restrict results to a specific virtual machine by using its ID.
+    type: int
+  name:
+    description:
+      - Restrict results to a specific virtual machine by using its name.
+      - If multiple virtual machines have the same name then vmid must be used instead.
+    type: str
+extends_documentation_fragment:
+    - community.general.proxmox.documentation
+    - community.general.attributes
+    - community.general.attributes.info_module
+"""
+
+EXAMPLES = """
+- name: List all existing virtual machines on node
+  community.general.proxmox_vm_info:
+    api_host: proxmoxhost
+    api_user: root@pam
+    api_token_id: '{{ token_id | default(omit) }}'
+    api_token_secret: '{{ token_secret | default(omit) }}'
+    node: node01
+
+- name: List all QEMU virtual machines on node
+  community.general.proxmox_vm_info:
+    api_host: proxmoxhost
+    api_user: root@pam
+    api_password: '{{ password | default(omit) }}'
+    node: node01
+    type: qemu
+
+- name: Retrieve information about specific VM by ID
+  community.general.proxmox_vm_info:
+    api_host: proxmoxhost
+    api_user: root@pam
+    api_password: '{{ password | default(omit) }}'
+    node: node01
+    type: qemu
+    vmid: 101
+
+- name: Retrieve information about specific VM by name
+  community.general.proxmox_vm_info:
+    api_host: proxmoxhost
+    api_user: root@pam
+    api_password: '{{ password | default(omit) }}'
+    node: node01
+    type: lxc
+    name: lxc05.home.arpa
+"""
+
+RETURN = """
+proxmox_vms:
+    description: List of virtual machines.
+    returned: on success
+    type: list
+    elements: dict
+    sample:
+      [
+        {
+          "cpu": 0.258944410905281,
+          "cpus": 1,
+          "disk": 0,
+          "diskread": 0,
+          "diskwrite": 0,
+          "maxdisk": 34359738368,
+          "maxmem": 4294967296,
+          "mem": 35158379,
+          "name": "pxe.home.arpa",
+          "netin": 99715803,
+          "netout": 14237835,
+          "pid": 1947197,
+          "status": "running",
+          "type": "qemu",
+          "uptime": 135530,
+          "vmid": 100
+        },
+        {
+          "cpu": 0,
+          "cpus": 1,
+          "disk": 0,
+          "diskread": 0,
+          "diskwrite": 0,
+          "maxdisk": 0,
+          "maxmem": 536870912,
+          "mem": 0,
+          "name": "test1",
+          "netin": 0,
+          "netout": 0,
+          "status": "stopped",
+          "type": "qemu",
+          "uptime": 0,
+          "vmid": 101
+        }
+      ]
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.community.general.plugins.module_utils.proxmox import (
+    proxmox_auth_argument_spec,
+    ProxmoxAnsible,
+)
+
+
+class ProxmoxVmInfoAnsible(ProxmoxAnsible):
+    def get_qemu_vms(self, node, vmid=None):
+        try:
+            vms = self.proxmox_api.nodes(node).qemu().get()
+            for vm in vms:
+                vm["vmid"] = int(vm["vmid"])
+                vm["type"] = "qemu"
+            if vmid is None:
+                return vms
+            return [vm for vm in vms if vm["vmid"] == vmid]
+        except Exception as e:
+            self.module.fail_json(msg="Failed to retrieve QEMU VMs information: %s" % e)
+
+    def get_lxc_vms(self, node, vmid=None):
+        try:
+            vms = self.proxmox_api.nodes(node).lxc().get()
+            for vm in vms:
+                vm["vmid"] = int(vm["vmid"])
+            if vmid is None:
+                return vms
+            return [vm for vm in vms if vm["vmid"] == vmid]
+        except Exception as e:
+            self.module.fail_json(msg="Failed to retrieve LXC VMs information: %s" % e)
+
+
+def main():
+    module_args = proxmox_auth_argument_spec()
+    vm_info_args = dict(
+        node=dict(type="str", required=True),
+        type=dict(
+            type="str", choices=["lxc", "qemu", "all"], default="all", required=False
+        ),
+        vmid=dict(type="int", required=False),
+        name=dict(type="str", required=False),
+    )
+    module_args.update(vm_info_args)
+
+    module = AnsibleModule(
+        argument_spec=module_args,
+        required_together=[("api_token_id", "api_token_secret")],
+        required_one_of=[("api_password", "api_token_id")],
+        supports_check_mode=True,
+    )
+
+    proxmox = ProxmoxVmInfoAnsible(module)
+    node = module.params["node"]
+    type = module.params["type"]
+    vmid = module.params["vmid"]
+    name = module.params["name"]
+
+    result = dict(changed=False)
+
+    if proxmox.get_node(node) is None:
+        module.fail_json(msg="Node %s doesn't exist in PVE cluster" % node)
+
+    if not vmid and name:
+        vmid = int(proxmox.get_vmid(name, ignore_missing=False))
+
+    vms = None
+    if type == "lxc":
+        vms = proxmox.get_lxc_vms(node, vmid=vmid)
+    elif type == "qemu":
+        vms = proxmox.get_qemu_vms(node, vmid=vmid)
+    else:
+        vms = proxmox.get_qemu_vms(node, vmid=vmid) + proxmox.get_lxc_vms(
+            node, vmid=vmid
+        )
+
+    if vms or vmid is None:
+        result["proxmox_vms"] = vms
+        module.exit_json(**result)
+    else:
+        result["msg"] = "VM with vmid %s doesn't exist on node %s" % (vmid, node)
+        module.fail_json(**result)
+
+
+if __name__ == "__main__":
+    main()

tests/unit/plugins/modules/test_proxmox_vm_info.py

@@ -0,0 +1,314 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2023, Sergei Antipov <greendayonfire at gmail.com>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+import sys
+
+import pytest
+
+proxmoxer = pytest.importorskip("proxmoxer")
+mandatory_py_version = pytest.mark.skipif(
+    sys.version_info < (2, 7),
+    reason="The proxmoxer dependency requires python2.7 or higher",
+)
+
+from ansible_collections.community.general.plugins.modules import proxmox_vm_info
+from ansible_collections.community.general.tests.unit.compat.mock import patch
+from ansible_collections.community.general.tests.unit.plugins.modules.utils import (
+    AnsibleExitJson,
+    AnsibleFailJson,
+    ModuleTestCase,
+    set_module_args,
+)
+import ansible_collections.community.general.plugins.module_utils.proxmox as proxmox_utils
+
+NODE = "pve"
+LXC_VMS = [
+    {
+        "uptime": 47,
+        "maxswap": 536870912,
+        "diskread": 0,
+        "name": "test-lxc.home.arpa",
+        "status": "running",
+        "vmid": "102",
+        "type": "lxc",
+        "swap": 0,
+        "cpus": 2,
+        "mem": 29134848,
+        "maxdisk": 10737418240,
+        "diskwrite": 0,
+        "netin": 35729,
+        "netout": 446,
+        "pid": 1412780,
+        "maxmem": 536870912,
+        "disk": 307625984,
+        "cpu": 0,
+    },
+    {
+        "netin": 0,
+        "netout": 0,
+        "cpu": 0,
+        "maxmem": 536870912,
+        "disk": 0,
+        "name": "test1-lxc.home.arpa",
+        "diskread": 0,
+        "status": "stopped",
+        "vmid": "103",
+        "type": "lxc",
+        "swap": 0,
+        "uptime": 0,
+        "maxswap": 536870912,
+        "diskwrite": 0,
+        "cpus": 2,
+        "mem": 0,
+        "maxdisk": 10737418240,
+    },
+]
+QEMU_VMS = [
+    {
+        "vmid": 101,
+        "diskread": 0,
+        "status": "stopped",
+        "name": "test1",
+        "uptime": 0,
+        "diskwrite": 0,
+        "cpus": 1,
+        "mem": 0,
+        "maxdisk": 0,
+        "netout": 0,
+        "netin": 0,
+        "cpu": 0,
+        "maxmem": 536870912,
+        "disk": 0,
+    },
+    {
+        "netout": 4113,
+        "netin": 22738,
+        "pid": 1947197,
+        "maxmem": 4294967296,
+        "disk": 0,
+        "cpu": 0.0795350949559682,
+        "uptime": 41,
+        "vmid": 100,
+        "status": "running",
+        "diskread": 0,
+        "name": "pxe.home.arpa",
+        "cpus": 1,
+        "mem": 35315629,
+        "maxdisk": 34359738368,
+        "diskwrite": 0,
+    },
+]
+
+
+def get_module_args(type="all", vmid=None, name=None):
+    return {
+        "api_host": "host",
+        "api_user": "user",
+        "api_password": "password",
+        "node": NODE,
+        "type": type,
+        "vmid": vmid,
+        "name": name,
+    }
+
+
+def normalized_expected_vms_output(vms):
+    result = [vm.copy() for vm in vms]
+    for vm in result:
+        if "type" not in vm:
+            # response for QEMU VMs doesn't contain type field, adding it
+            vm["type"] = "qemu"
+        vm["vmid"] = int(vm["vmid"])
+    return result
+
+
+class TestProxmoxVmInfoModule(ModuleTestCase):
+    def setUp(self):
+        super(TestProxmoxVmInfoModule, self).setUp()
+        proxmox_utils.HAS_PROXMOXER = True
+        self.module = proxmox_vm_info
+        self.connect_mock = patch(
+            "ansible_collections.community.general.plugins.module_utils.proxmox.ProxmoxAnsible._connect",
+        ).start()
+        self.connect_mock.return_value.nodes.return_value.lxc.return_value.get.return_value = (
+            LXC_VMS
+        )
+        self.connect_mock.return_value.nodes.return_value.qemu.return_value.get.return_value = (
+            QEMU_VMS
+        )
+        self.connect_mock.return_value.nodes.get.return_value = [{"node": NODE}]
+
+    def tearDown(self):
+        self.connect_mock.stop()
+        super(TestProxmoxVmInfoModule, self).tearDown()
+
+    def test_module_fail_when_required_args_missing(self):
+        with pytest.raises(AnsibleFailJson) as exc_info:
+            set_module_args({})
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["msg"] == "missing required arguments: api_host, api_user, node"
+
+    def test_get_lxc_vms_information(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            set_module_args(get_module_args(type="lxc"))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["changed"] is False
+        assert result["proxmox_vms"] == LXC_VMS
+
+    def test_get_qemu_vms_information(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            expected_output = normalized_expected_vms_output(QEMU_VMS)
+            set_module_args(get_module_args(type="qemu"))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+
+    def test_get_all_vms_information(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            qemu_output = normalized_expected_vms_output(QEMU_VMS)
+            expected_output = qemu_output + LXC_VMS
+
+            set_module_args(get_module_args())
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+
+    def test_vmid_is_converted_to_int(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            expected_output = normalized_expected_vms_output(LXC_VMS)
+            set_module_args(get_module_args(type="lxc"))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+        assert isinstance(result["proxmox_vms"][0]["vmid"], int)
+
+    def test_get_specific_lxc_vm_information(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            vmid = 102
+            expected_output = [
+                vm
+                for vm in normalized_expected_vms_output(LXC_VMS)
+                if vm["vmid"] == vmid
+            ]
+            set_module_args(get_module_args(type="lxc", vmid=vmid))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+        assert len(result["proxmox_vms"]) == 1
+
+    def test_get_specific_qemu_vm_information(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            vmid = 100
+            expected_output = [
+                vm
+                for vm in normalized_expected_vms_output(QEMU_VMS)
+                if vm["vmid"] == vmid
+            ]
+            set_module_args(get_module_args(type="qemu", vmid=vmid))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+        assert len(result["proxmox_vms"]) == 1
+
+    def test_get_specific_vm_information(self):
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            vmid = 100
+            expected_output = [
+                vm
+                for vm in normalized_expected_vms_output(QEMU_VMS + LXC_VMS)
+                if vm["vmid"] == vmid
+            ]
+            set_module_args(get_module_args(type="all", vmid=vmid))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+        assert len(result["proxmox_vms"]) == 1
+
+    def test_get_specific_vm_information_by_using_name(self):
+        name = "test-lxc.home.arpa"
+        self.connect_mock.return_value.cluster.resources.get.return_value = [
+            {"name": name, "vmid": "102"}
+        ]
+
+        with pytest.raises(AnsibleExitJson) as exc_info:
+            expected_output = [
+                vm
+                for vm in normalized_expected_vms_output(QEMU_VMS + LXC_VMS)
+                if vm["name"] == name
+            ]
+            set_module_args(get_module_args(type="all", name=name))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["proxmox_vms"] == expected_output
+        assert len(result["proxmox_vms"]) == 1
+
+    def test_module_fail_when_vm_does_not_exist_on_node(self):
+        with pytest.raises(AnsibleFailJson) as exc_info:
+            vmid = 200
+            set_module_args(get_module_args(type="all", vmid=vmid))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["msg"] == "VM with vmid 200 doesn't exist on node pve"
+
+    def test_module_fail_when_qemu_request_fails(self):
+        self.connect_mock.return_value.nodes.return_value.qemu.return_value.get.side_effect = IOError(
+            "Some mocked connection error."
+        )
+        with pytest.raises(AnsibleFailJson) as exc_info:
+            set_module_args(get_module_args(type="qemu"))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert "Failed to retrieve QEMU VMs information:" in result["msg"]
+
+    def test_module_fail_when_lxc_request_fails(self):
+        self.connect_mock.return_value.nodes.return_value.lxc.return_value.get.side_effect = IOError(
+            "Some mocked connection error."
+        )
+        with pytest.raises(AnsibleFailJson) as exc_info:
+            set_module_args(get_module_args(type="lxc"))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert "Failed to retrieve LXC VMs information:" in result["msg"]
+
+    def test_module_fail_when_node_does_not_exist(self):
+        self.connect_mock.return_value.nodes.get.return_value = []
+        with pytest.raises(AnsibleFailJson) as exc_info:
+            set_module_args(get_module_args(type="all"))
+            self.module.main()
+
+        result = exc_info.value.args[0]
+        assert result["msg"] == "Node pve doesn't exist in PVE cluster"
+
+    def test_call_to_get_vmid_is_not_used_when_vmid_provided(self):
+        with patch(
+            "ansible_collections.community.general.plugins.module_utils.proxmox.ProxmoxAnsible.get_vmid"
+        ) as get_vmid_mock:
+            with pytest.raises(AnsibleExitJson):
+                vmid = 100
+                set_module_args(
+                    get_module_args(type="all", vmid=vmid, name="something")
+                )
+                self.module.main()
+
+        assert get_vmid_mock.call_count == 0