[PR #9225/d71ba0fa backport][stable-10] Proxmox module refactoring

[patchback]

This is a backport of PR #9225 as merged into main (d71ba0f).

SUMMARY

This pull request refactors the historically grown proxmox module.
The control flow was very opaque with some redundant checks and - most recently - features that were only introduced in parts of the module when they intended to target the whole module (see #9065).
This refactor aims to make the module more readable and more easily extendable.

Additionally, this request contains various bug fixes:

• From proxmox: Handling of disk_volume variable is broken #9065: The disk_volume key is now properly parsed and passed on to the API
• From not possible to add lxc mount point as bind #8982: It is now possible to add bind-only mount points again.
• From proxmox: state=template is not idempotent (for LXCs) #8811: Converting an LXC to a template is now idempotent.
• From Update of LXC Containers does not work (Mounts/Memory/etc.) #9055: The default value of update=False is now deprecated and will be changed to update=True in version 11.0.0
• In the proxmox utils module: The parameter choose_first_if_multiple of get_vmid is now used correctly, causing the function to return the first of multiple matches instead of failing.

ISSUE TYPE

• Bugfix Pull Request
• Refactoring Pull Request

COMPONENT NAME

proxmox

ADDITIONAL INFORMATION

The following playbook should run correctly on both the old and refactored versions of this module, but the template creation will not be idempotent on the old version:

---
- name: Check proxmox LXC module
  hosts: pve
  become: false
  gather_facts: false
  tasks:
    - name: Create LXC
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        ostemplate: local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst
        disk: local-lvm:8
        tags: test1,test3,debian
      register: create_res

    - name: Sleep for 5 seconds and continue with play
      ansible.builtin.wait_for:
        timeout: 5
      delegate_to: localhost

    - name: Check Creation Idempotency
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        ostemplate: local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst
        disk: local-lvm:8
        tags: test1,test3,debian
      register: check_res
      failed_when: check_res.changed

    - name: Update LXC config [new - create volumes]
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        cores: 1
        vmid: "{{ create_res.vmid | int }}"
        disk_volume:
          storage: local-lvm
          size: 14
        mount_volumes:
          - id: mp0
            storage: local-lvm
            size: 3
            mountpoint: /mnt/test
        update: true

    - name: Update LXC config [new - explicit volumes]
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        cores: 1
        vmid: "{{ create_res.vmid }}"
        disk_volume:
          storage: local-lvm
          volume: "vm-{{ create_res.vmid }}-disk-0"
          size: 14
        mount_volumes:
          - id: mp0
            storage: local-lvm
            volume: "vm-{{ create_res.vmid }}-disk-1"
            size: 3
            mountpoint: /mnt/test
        update: true

    - name: Update LXC config [old - implicit volumes]
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        cores: 1
        vmid: "{{ create_res.vmid }}"
        disk: local-lvm:14
        mounts: '{"mp0":"local-lvm:3,mp=/mnt/test"}'
        update: true

    - name: Update LXC config [old - explicit volumes]
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        cores: 1
        vmid: "{{ create_res.vmid }}"
        disk: "local-lvm:vm-{{ create_res.vmid }}-disk-0,size=14G"
        mounts: '{"mp0":"local-lvm:vm-{{ create_res.vmid }}-disk-1,size=3G,mp=/mnt/test"}'
        update: true

    - name: Update LXC config [tags]
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node
        cores: 1
        vmid: "{{ create_res.vmid }}"
        disk: "local-lvm:vm-{{ create_res.vmid }}-disk-0,size=14G"
        mounts: '{"mp0":"local-lvm:vm-{{ create_res.vmid }}-disk-1,size=3G,mp=/mnt/test"}'
        tags: test1,test2,debian
        update: true

    - name: Start LXC
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: started

    - name: Check Starting Idempotency
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: started
      retries: 1
      delay: 10
      register: check_res
      failed_when: check_res.changed

    - name: Restart LXC
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: restarted

    - name: Stop LXC
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: stopped

    - name: Check Stopping Idempotency
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: stopped
      retries: 1
      delay: 10
      register: check_res
      failed_when: check_res.changed

    - name: Convert LXC to Template
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: template

    - name: Check Template Idempotency
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: template
      retries: 1
      delay: 10
      register: check_res
      failed_when: check_res.changed

    - name: Remove LXC
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: absent

    - name: Check Removal Idempotency
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: "{{ create_res.vmid }}"
        state: absent
      retries: 1
      delay: 10
      register: check_res
      failed_when: check_res.changed

    - name: Create new LXC [With storage + disk] (should fail)
      community.general.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: node01
        hostname: test-node-2
        ostemplate: local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst
        cores: 1
        disk: 6
        storage: local-lvm
      ignore_errors: true

[ansibullbot]

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