community.general/plugins/modules/proxmox_backup_info.py

#!/usr/bin/python
# -*- coding: utf-8 -*-
#
# Copyright (c) 2024 Marzieh Raoufnezhad <raoufnezhad at gmail.com>
# Copyright (c) 2024 Maryam Mayabi <mayabi.ahm 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_backup_info

short_description: Retrieve information on Proxmox scheduled backups

version_added: 10.3.0

description:
  - Retrieve information such as backup times, VM name, VM ID, mode, backup type, and backup schedule using the Proxmox Server API.

author:
  - "Marzieh Raoufnezhad (@raoufnezhad) <raoufnezhad@gmail.com>"
  - "Maryam Mayabi (@mmayabi) <mayabi.ahm@gmail.com>"

options:
  vm_name:
    description:
      - The name of the Proxmox VM.
      - If defined, the returned list will contain backup jobs that have been parsed and filtered based on O(vm_name) value.
      - Mutually exclusive with O(vm_id) and O(backup_jobs).
    type: str
  vm_id:
    description:
      - The ID of the Proxmox VM.
      - If defined, the returned list will contain backup jobs that have been parsed and filtered based on O(vm_id) value.
      - Mutually exclusive with O(vm_name) and O(backup_jobs).
    type: str
  backup_jobs:
    description:
      - If V(true), the module will return all backup jobs information.
      - If V(false), the module will parse all backup jobs based on VM IDs and return a list of VMs' backup information.
      - Mutually exclusive with O(vm_id) and O(vm_name).
    default: false
    type: bool

extends_documentation_fragment:
  - community.general.proxmox.documentation
  - community.general.attributes
  - community.general.attributes.info_module
  - community.general.proxmox.actiongroup_proxmox
"""

EXAMPLES = """
- name: Print all backup information by VM ID and VM name
  community.general.proxmox_backup_info:
    api_user: 'myUser@pam'
    api_password: '*******'
    api_host: '192.168.20.20'

- name: Print Proxmox backup information for a specific VM based on its name
  community.general.proxmox_backup_info:
    api_user: 'myUser@pam'
    api_password: '*******'
    api_host: '192.168.20.20'
    vm_name: 'mailsrv'

- name: Print Proxmox backup information for a specific VM based on its VM ID
  community.general.proxmox_backup_info:
    api_user: 'myUser@pam'
    api_password: '*******'
    api_host: '192.168.20.20'
    vm_id: '150'

- name: Print Proxmox all backup job information
  community.general.proxmox_backup_info:
    api_user: 'myUser@pam'
    api_password: '*******'
    api_host: '192.168.20.20'
    backup_jobs: true
"""

RETURN = """
---
backup_info:
  description: The return value provides backup job information based on VM ID or VM name, or total backup job information.
  returned: on success, but can be empty
  type: list
  elements: dict
  contains:
    bktype:
      description: The type of the backup.
      returned: on success
      type: str
      sample: vzdump
    enabled:
      description: V(1) if backup is enabled else V(0).
      returned: on success
      type: int
      sample: 1
    id:
      description: The backup job ID.
      returned: on success
      type: str
      sample: backup-83831498-c631
    mode:
      description: The backup job mode such as snapshot.
      returned: on success
      type: str
      sample: snapshot
    next-run:
      description: The next backup time.
      returned: on success
      type: str
      sample: "2024-12-28 11:30:00"
    schedule:
      description: The backup job schedule.
      returned: on success
      type: str
      sample: "sat 15:00"
    storage:
      description: The backup storage location.
      returned: on success
      type: str
      sample: local
    vm_name:
      description: The VM name.
      returned: on success
      type: str
      sample: test01
    vmid:
      description: The VM ID.
      returned: on success
      type: str
      sample: "100"
"""

from datetime import datetime
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible_collections.community.general.plugins.module_utils.proxmox import (
    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)


class ProxmoxBackupInfoAnsible(ProxmoxAnsible):

    # Get all backup information
    def get_jobs_list(self):
        try:
            backupJobs = self.proxmox_api.cluster.backup.get()
        except Exception as e:
            self.module.fail_json(msg="Getting backup jobs failed: %s" % e)
        return backupJobs

    # Get VM information
    def get_vms_list(self):
        try:
            vms = self.proxmox_api.cluster.resources.get(type='vm')
        except Exception as e:
            self.module.fail_json(msg="Getting VMs info from cluster failed: %s" % e)
        return vms

    # Get all backup information by VM ID and VM name
    def vms_backup_info(self):
        backupList = self.get_jobs_list()
        vmInfo = self.get_vms_list()
        bkInfo = []
        for backupItem in backupList:
            nextrun = datetime.fromtimestamp(backupItem['next-run'])
            vmids = backupItem['vmid'].split(',')
            for vmid in vmids:
                for vm in vmInfo:
                    if vm['vmid'] == int(vmid):
                        vmName = vm['name']
                        break
                bkInfoData = {'id': backupItem['id'],
                              'schedule': backupItem['schedule'],
                              'storage': backupItem['storage'],
                              'mode': backupItem['mode'],
                              'next-run': nextrun.strftime("%Y-%m-%d %H:%M:%S"),
                              'enabled': backupItem['enabled'],
                              'bktype': backupItem['type'],
                              'vmid': vmid,
                              'vm_name': vmName}
                bkInfo.append(bkInfoData)
        return bkInfo

    # Get proxmox backup information for a specific VM based on its VM ID or VM name
    def specific_vmbackup_info(self, vm_name_id):
        fullBackupInfo = self.vms_backup_info()
        vmBackupJobs = []
        for vm in fullBackupInfo:
            if (vm["vm_name"] == vm_name_id or vm["vmid"] == vm_name_id):
                vmBackupJobs.append(vm)
        return vmBackupJobs


def main():
    # Define module args
    args = proxmox_auth_argument_spec()
    backup_info_args = dict(
        vm_id=dict(type='str'),
        vm_name=dict(type='str'),
        backup_jobs=dict(type='bool', default=False)
    )
    args.update(backup_info_args)

    module = AnsibleModule(
        argument_spec=args,
        mutually_exclusive=[('backup_jobs', 'vm_id', 'vm_name')],
        supports_check_mode=True
    )

    # Define (init) result value
    result = dict(
        changed=False
    )

    # Check if proxmoxer exist
    if not HAS_PROXMOXER:
        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)

    # Start to connect to proxmox to get backup data
    proxmox = ProxmoxBackupInfoAnsible(module)
    vm_id = module.params['vm_id']
    vm_name = module.params['vm_name']
    backup_jobs = module.params['backup_jobs']

    # Update result value based on what requested (module args)
    if backup_jobs:
        result['backup_info'] = proxmox.get_jobs_list()
    elif vm_id:
        result['backup_info'] = proxmox.specific_vmbackup_info(vm_id)
    elif vm_name:
        result['backup_info'] = proxmox.specific_vmbackup_info(vm_name)
    else:
        result['backup_info'] = proxmox.vms_backup_info()

    # Return result value
    module.exit_json(**result)


if __name__ == '__main__':
    main()