proxmox_zone - new module (#176)

* proxmox_zone: new module for proxmox_zones

- List zones

* proxmox_zone: Create new zone

* proxmox_zone: Keep common parameter for all conditions

* proxmox_zone: Implement locking

* proxmox_zone: Added update_zone()

* proxmox_zone: added zone_absent()

* proxmox_zone: Added document and examples

* proxmox_zone: add missing exception handling for zone_preent()

* proxmox_zone: validate params

* proxmox_zone and proxmox module_utils

- Move sdn locking functions to proxmox module_utils

* proxmox_zone: Fix sanity issues

- Fix PEP8 issues
- Fix Doc issues for dnszone
- Add workaround for author string
- Add attribute check_mode and diff_mode
- Add no_log=False for lock_token as this is not a secret
- Add proxmox_zone to runtime.yml

* proxmox_zone: fix minor issues found during testing

* proxmox_zone: Add unit tests

* proxmox_zone: Add missing boolean conversion

* module_utils: Create new base class ProxmoxSdnAnsible()

- Move SDN locking methods from ProxmoxAnsible class to ProxmoxSdnAnsible
- Add ge_zones() method to ProxmoxSdnAnsible As we will be splitting
  zone module into zone and zone_info

* Create seprate proxmox_zone_info

- Split proxmox_zone and create proxmox_zone_info
- Rename variable type to zone_type

* proxmox_zone: Merge statepresent and update

* proxmox_zone:  Get lock just before making changes

- also fix minor issues in proxmox_zone,proxmox_zone_info, proxmox_sdn.

* Update unit tests for proxmox_zone & proxmox_zone_info

Author: JanaHoch

meta/runtime.yml

@@ -36,3 +36,5 @@ action_groups:
     - proxmox_user
     - proxmox_user_info
     - proxmox_vm_info
+    - proxmox_zone
+    - proxmox_zone_info

plugins/module_utils/proxmox_sdn.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025, Jana Hoch <[email protected]>
+# 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
+
+from typing import List, Dict
+
+from ansible_collections.community.proxmox.plugins.module_utils.proxmox import (
+    ansible_to_proxmox_bool,
+    ProxmoxAnsible
+)
+
+
+class ProxmoxSdnAnsible(ProxmoxAnsible):
+    """Base Class for All Proxmox SDN Classes"""
+
+    def __init__(self, module):
+        super(ProxmoxSdnAnsible, self).__init__(module)
+        self.module = module
+
+    def get_global_sdn_lock(self) -> str:
+        """Acquire global SDN lock. Needed for any changes under SDN.
+
+        :return: lock-token
+        """
+        try:
+            return self.proxmox_api.cluster().sdn().lock().post()
+        except Exception as e:
+            self.module.fail_json(
+                msg=f'Failed to acquire global sdn lock {e}'
+            )
+
+    def apply_sdn_changes_and_release_lock(self, lock: str, release_lock: bool = True) -> None:
+        """Apply all SDN changes done under a lock token.
+
+        :param lock: Global SDN lock token
+        :param release_lock: if True release lock after successfully applying changes
+        """
+        lock_params = {
+            'lock-token': lock,
+            'release-lock': ansible_to_proxmox_bool(release_lock)
+        }
+        try:
+            self.proxmox_api.cluster().sdn().put(**lock_params)
+        except Exception as e:
+            self.rollback_sdn_changes_and_release_lock(lock)
+            self.module.fail_json(
+                msg=f'Failed to apply sdn changes {e}. Rolling back all pending changes.'
+            )
+
+    def rollback_sdn_changes_and_release_lock(self, lock: str, release_lock: bool = True) -> None:
+        """Rollback all changes  done under a lock token.
+
+        :param lock: Global SDN lock token
+        :param release_lock: if True release lock after successfully rolling back changes
+        """
+        lock_params = {
+            'lock-token': lock,
+            'release-lock': ansible_to_proxmox_bool(release_lock)
+        }
+        try:
+            self.proxmox_api.cluster().sdn().rollback().post(**lock_params)
+        except Exception as e:
+            self.module.fail_json(
+                msg=f'Rollback attempt failed - {e}. Manually clear lock by deleting /etc/pve/sdn/.lock'
+            )
+
+    def release_lock(self, lock: str, force: bool = False) -> None:
+        """Release Global SDN lock
+
+        :param lock: Global SDN lock token
+        :param force: if true, allow releasing lock without providing the token
+        """
+        lock_params = {
+            'lock-token': lock,
+            'force': ansible_to_proxmox_bool(force)
+        }
+        try:
+            self.proxmox_api.cluster().sdn().lock().delete(**lock_params)
+        except Exception as e:
+            self.module.fail_json(
+                msg=f'Failed to release lock - {e}. Manually clear lock by deleting /etc/pve/sdn/.lock'
+            )
+
+    def get_zones(self, zone_type: str = None) -> List[Dict]:
+        """Get Proxmox SDN zones
+
+        :param zone_type: Filter zones based on type.
+        :return: list of all zones and their properties.
+        """
+        try:
+            return self.proxmox_api.cluster().sdn().zones().get(type=zone_type)
+        except Exception as e:
+            self.module.fail_json(
+                msg=f'Failed to retrieve zone information from cluster: {e}'
+            )