[feat] proxmox_snap: snapshot containers with configured mountpoints

[nxet]

SUMMARY

This PR adds a new parameter unbind to the proxmox_snap module, which allows to take snapshots of containers with configured mount points, bypassing the Proxmox limit by temporarily disabling the configuration before the snapshot.

There is also a small improvement in how the API tasks are checked.
A new api_task_ok helper is provided in the module_utils.proxmox.ProxmoxAnsible class, and used across the proxmox modules to standardize how pending tasks are checked.

ISSUE TYPE

• Feature Pull Request

COMPONENT NAME

community.general.proxmox_snap

ADDITIONAL INFORMATION

proxmox_snap

The mountpoint-specific config API endpoint mp[n] is unfortunately (from an implementation pov, of course it's only logical) restricted to root@pam authenticating with password. Tokens will not work, at least I couldn't get them to work. More info here, PUT tab.
This limit is not enforced when deleting the mounts config though, which means bad credentials would allow to remove the mount points BUT fail at reconfig, leaving the container in a misconfigured state. This behavior is properly commented in-code, documented, and the implementation checks if the user provided the correct authentication parameters, eventually failing before running any task.

Mainly to improve readability, two new helpers start_instance and shutdown_instance have been introduced, as well as internal helpers to get and manipulate the mountpoints configuration (_container_mp_{get,disable,restore}).

Changes to the container's mountpoints config require shutting down the machine. The state of the container (running or not) is stored before applying any changes, and restored after the snapshot if necessary. This behavior is also properly documented.

Finally the new logic tries to gracefully handle timeouts during the snapshot, by restoring the original config and state regardless of the successful execution of the API task.

api_task_ok
There could be some room for improvement, providing a wait_api_task helper to also abstract the while timeout: blocks across the modules, but it would have been out of scope for this PR.

Test Playbook

---

#
# requirements:
#   - create `/tmp/foo` and `/tmp/bar` on the target proxmox node
#

- hosts: localhost

  vars_prompt:
    - name: proxmox_root_pass
      prompt: "Enter Proxmox password"
      private: true

  tasks:

    - name: Create new container with minimal options
      community.general.proxmox:
        vmid: 100
        node: px10
        api_user: root@pam
        api_password: "{{ proxmox_root_pass }}"
        api_host: px10.example.com
        password: 123456
        hostname: test
        ostemplate: 'local:vztmpl/alpine-3.16-default_20220622_amd64.tar.xz'
        mounts:
          mp0: /tmp/foo,mp=/tmp/foo
          mp1: /tmp/bar,mp=/tmp/bar

    - name:
      community.general.proxmox_snap:
        vmid: 100
        api_user: root@pam
        api_password: "{{ proxmox_root_pass }}"
        api_host: px10.example.com
        state: present
        snapname: "test_{{ '%Y%m%d%H%M' | strftime }}"
        unbind: true

...

[ansibullbot]

cc @Ajpantuso @Thulium-Drake @UnderGreen @helldorado @joshainglis @karmab @tleguern
click here for bot help

[felixfontein]

Thanks for your contribution! I've added some first comments. Can you please add a changelog fragment? Thanks.

[nxet]

The last two commits address the remarks above, specifically:

• add changelog fragment, for both the unbind param and the api_task_ok helper
• improve the api_task_ok logic
• fix tag error in documentation
• add version_added tag to the unbind param docs
• fix formatting errors

[nxet]

Great to see all tests are passing, looking forward to the release!

The commit history obviously requires a rebase, will you take care of it when merging?
Should I do it myself and push the changes?
As you can see I'm not very active on Github, and I'm not sure about the required next steps.
Thanks for your understanding, and for all the suggestions during code review.

Just wanted to add that I'm super happy to be contributing to Ansible!
I'm beyond honored to have my small PR merged to such a massive software suite.

[felixfontein]

Besides the following point, this looks good to me. I cannot really test this, but the code changes look good to me (i.e. they don't seem to break something that already worked) and since none of the maintainers reacted so far, I guess nobody objects. I'll merge this in a couple of days (assuming the below modification has been done).