diff --git a/plugins/modules/proxmox.py b/plugins/modules/proxmox.py index fcd66c8e74..4c0220e6e5 100644 --- a/plugins/modules/proxmox.py +++ b/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 diff --git a/plugins/modules/proxmox_kvm.py b/plugins/modules/proxmox_kvm.py index 690ae5c750..238191f6a1 100644 --- a/plugins/modules/proxmox_kvm.py +++ b/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 diff --git a/plugins/modules/proxmox_vm_info.py b/plugins/modules/proxmox_vm_info.py new file mode 100644 index 0000000000..6713be0bbe --- /dev/null +++ b/plugins/modules/proxmox_vm_info.py @@ -0,0 +1,216 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright (c) 2023, Sergei Antipov +# 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) ' +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() diff --git a/tests/unit/plugins/modules/test_proxmox_vm_info.py b/tests/unit/plugins/modules/test_proxmox_vm_info.py new file mode 100644 index 0000000000..680de10b07 --- /dev/null +++ b/tests/unit/plugins/modules/test_proxmox_vm_info.py @@ -0,0 +1,314 @@ +# -*- coding: utf-8 -*- +# +# Copyright (c) 2023, Sergei Antipov +# 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