Refactor all Proxmox modules to use shared module_utils. (#4029) (#4164)

* Refactor Proxmox modules to use `module_utils`. * Fix tests. * Rename `node_check`. * Add `ignore_missing` to `get_vm`. * Refactor `proxmox` module. * Add changelog entry. * Add `choose_first_if_multiple` parameter for deprecation. (cherry picked from commit a61bdbadd5) Co-authored-by: Markus Reiter <me@reitermark.us>
2025-04-25 03:41:25 -07:00 · 2022-02-07 17:48:11 +01:00 · 2022-02-07 17:48:11 +01:00 · a678029bd2
commit a678029bd2
parent fab30c5e55
10 changed files with 849 additions and 1072 deletions
--- a/plugins/modules/cloud/misc/proxmox_snap.py
+++ b/plugins/modules/cloud/misc/proxmox_snap.py
@ -1,6 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-
+#
 # Copyright: (c) 2020, Jeffrey van Pelt (@Thulium-Drake) <jeff@vanpelt.one>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

@ -16,22 +16,6 @@ description:
  - Allows you to create/delete snapshots from instances in Proxmox VE cluster.
  - Supports both KVM and LXC, OpenVZ has not been tested, as it is no longer supported on Proxmox VE.
 options:
-  api_host:
-    description:
-      - The host of the Proxmox VE cluster.
-    required: true
-    type: str
-  api_user:
-    description:
-      - The user to authenticate with.
-    required: true
-    type: str
-  api_password:
-    description:
-      - The password to authenticate with.
-      - You can use PROXMOX_PASSWORD environment variable.
-    type: str
-    required: yes
  hostname:
    description:
      - The instance name.
@ -41,11 +25,6 @@ options:
      - The instance id.
      - If not set, will be fetched from PromoxAPI based on the hostname.
    type: str
-  validate_certs:
-    description:
-      - Enable / disable https certificate verification.
-    type: bool
-    default: no
  state:
    description:
     - Indicate desired state of the instance snapshot.
@ -83,6 +62,8 @@ notes:
  - Supports C(check_mode).
 requirements: [ "proxmoxer", "python >= 2.7", "requests" ]
 author: Jeffrey van Pelt (@Thulium-Drake)
+extends_documentation_fragment:
+    - community.general.proxmox.documentation
 '''

 EXAMPLES = r'''
@ -110,102 +91,76 @@ RETURN = r'''#'''
 import time
 import traceback

-PROXMOXER_IMP_ERR = None
-try:
-    from proxmoxer import ProxmoxAPI
-    HAS_PROXMOXER = True
-except ImportError:
-    PROXMOXER_IMP_ERR = traceback.format_exc()
-    HAS_PROXMOXER = False
-
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib, env_fallback
 from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)


-VZ_TYPE = None
+class ProxmoxSnapAnsible(ProxmoxAnsible):
+    def snapshot(self, vm, vmid):
+        return getattr(self.proxmox_api.nodes(vm['node']), vm['type'])(vmid).snapshot

-
-def get_vmid(proxmox, hostname):
-    return [vm['vmid'] for vm in proxmox.cluster.resources.get(type='vm') if 'name' in vm and vm['name'] == hostname]
-
-
-def get_instance(proxmox, vmid):
-    return [vm for vm in proxmox.cluster.resources.get(type='vm') if int(vm['vmid']) == int(vmid)]
-
-
-def snapshot_create(module, proxmox, vm, vmid, timeout, snapname, description, vmstate):
-    if module.check_mode:
-        return True
-
-    if VZ_TYPE == 'lxc':
-        taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.post(snapname=snapname, description=description)
-    else:
-        taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.post(snapname=snapname, description=description, vmstate=int(vmstate))
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+    def snapshot_create(self, vm, vmid, timeout, snapname, description, vmstate):
+        if self.module.check_mode:
            return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for creating VM snapshot. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])

-        time.sleep(1)
-    return False
+        if vm['type'] == 'lxc':
+            taskid = self.snapshot(vm, vmid).post(snapname=snapname, description=description)
+        else:
+            taskid = self.snapshot(vm, vmid).post(snapname=snapname, description=description, vmstate=int(vmstate))
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for creating VM snapshot. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])

+            time.sleep(1)
+        return False

-def snapshot_remove(module, proxmox, vm, vmid, timeout, snapname, force):
-    if module.check_mode:
-        return True
-
-    taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.delete(snapname, force=int(force))
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+    def snapshot_remove(self, vm, vmid, timeout, snapname, force):
+        if self.module.check_mode:
            return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for removing VM snapshot. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])

-        time.sleep(1)
-    return False
+        taskid = self.snapshot(vm, vmid).delete(snapname, force=int(force))
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for removing VM snapshot. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])

-
-def setup_api(api_host, api_user, api_password, validate_certs):
-    api = ProxmoxAPI(api_host, user=api_user, password=api_password, verify_ssl=validate_certs)
-    return api
+            time.sleep(1)
+        return False


 def main():
+    module_args = proxmox_auth_argument_spec()
+    snap_args = dict(
+        vmid=dict(required=False),
+        hostname=dict(),
+        timeout=dict(type='int', default=30),
+        state=dict(default='present', choices=['present', 'absent']),
+        description=dict(type='str'),
+        snapname=dict(type='str', default='ansible_snap'),
+        force=dict(type='bool', default='no'),
+        vmstate=dict(type='bool', default='no'),
+    )
+    module_args.update(snap_args)
+
    module = AnsibleModule(
-        argument_spec=dict(
-            api_host=dict(required=True),
-            api_user=dict(required=True),
-            api_password=dict(no_log=True, required=True, fallback=(env_fallback, ['PROXMOX_PASSWORD'])),
-            vmid=dict(required=False),
-            validate_certs=dict(type='bool', default='no'),
-            hostname=dict(),
-            timeout=dict(type='int', default=30),
-            state=dict(default='present', choices=['present', 'absent']),
-            description=dict(type='str'),
-            snapname=dict(type='str', default='ansible_snap'),
-            force=dict(type='bool', default='no'),
-            vmstate=dict(type='bool', default='no'),
-        ),
+        argument_spec=module_args,
        supports_check_mode=True
    )

-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'),
-                         exception=PROXMOXER_IMP_ERR)
+    proxmox = ProxmoxSnapAnsible(module)

    state = module.params['state']
-    api_user = module.params['api_user']
-    api_host = module.params['api_host']
-    api_password = module.params['api_password']
    vmid = module.params['vmid']
-    validate_certs = module.params['validate_certs']
    hostname = module.params['hostname']
    description = module.params['description']
    snapname = module.params['snapname']
@ -213,37 +168,21 @@ def main():
    force = module.params['force']
    vmstate = module.params['vmstate']

-    try:
-        proxmox = setup_api(api_host, api_user, api_password, validate_certs)
-
-    except Exception as e:
-        module.fail_json(msg='authorization on proxmox cluster failed with exception: %s' % to_native(e))
-
    # If hostname is set get the VM id from ProxmoxAPI
    if not vmid and hostname:
-        hosts = get_vmid(proxmox, hostname)
-        if len(hosts) == 0:
-            module.fail_json(msg="Vmid could not be fetched => Hostname does not exist (action: %s)" % state)
-        vmid = hosts[0]
+        vmid = proxmox.get_vmid(hostname, choose_first_if_multiple=True)
    elif not vmid:
        module.exit_json(changed=False, msg="Vmid could not be fetched for the following action: %s" % state)

-    vm = get_instance(proxmox, vmid)
-
-    global VZ_TYPE
-    VZ_TYPE = vm[0]['type']
+    vm = proxmox.get_vm(vmid)

    if state == 'present':
        try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
-
-            for i in getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.get():
+            for i in proxmox.snapshot(vm, vmid).get():
                if i['name'] == snapname:
                    module.exit_json(changed=False, msg="Snapshot %s is already present" % snapname)

-            if snapshot_create(module, proxmox, vm, vmid, timeout, snapname, description, vmstate):
+            if proxmox.snapshot_create(vm, vmid, timeout, snapname, description, vmstate):
                if module.check_mode:
                    module.exit_json(changed=False, msg="Snapshot %s would be created" % snapname)
                else:
@ -254,13 +193,9 @@ def main():

    elif state == 'absent':
        try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
-
            snap_exist = False

-            for i in getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.get():
+            for i in proxmox.snapshot(vm, vmid).get():
                if i['name'] == snapname:
                    snap_exist = True
                    continue
@ -268,7 +203,7 @@ def main():
            if not snap_exist:
                module.exit_json(changed=False, msg="Snapshot %s does not exist" % snapname)
            else:
-                if snapshot_remove(module, proxmox, vm, vmid, timeout, snapname, force):
+                if proxmox.snapshot_remove(vm, vmid, timeout, snapname, force):
                    if module.check_mode:
                        module.exit_json(changed=False, msg="Snapshot %s would be removed" % snapname)
                    else: