diff --git a/changelogs/fragments/1404-proxmox-doc-fragments.yml b/changelogs/fragments/1404-proxmox-doc-fragments.yml new file mode 100644 index 0000000000..3682d11421 --- /dev/null +++ b/changelogs/fragments/1404-proxmox-doc-fragments.yml @@ -0,0 +1,4 @@ +minor_changes: + - proxmox - improve and extract more common documentation (https://github.com/ansible-collections/community.general/pull/1404). + - proxmox_kvm - improve and extract more common documentation (https://github.com/ansible-collections/community.general/pull/1404). + - proxmox_template - improve documentation (https://github.com/ansible-collections/community.general/pull/1404). diff --git a/plugins/doc_fragments/proxmox.py b/plugins/doc_fragments/proxmox.py index 1d0490aa8b..165a78527a 100644 --- a/plugins/doc_fragments/proxmox.py +++ b/plugins/doc_fragments/proxmox.py @@ -42,4 +42,23 @@ options: type: bool default: no requirements: [ "proxmoxer", "requests" ] +''' + + SELECTION = r''' +options: + vmid: + description: + - Specifies the instance ID. + - If not set the next available ID will be fetched from ProxmoxAPI. + type: int + node: + description: + - Proxmox VE node on which to operate. + - Only required for I(state=present). + - For every other states it will be autodiscovered. + type: str + pool: + description: + - Add the new VM to the specified pool. + type: str ''' diff --git a/plugins/modules/cloud/misc/proxmox.py b/plugins/modules/cloud/misc/proxmox.py index 140d56f686..c26c3f77f6 100644 --- a/plugins/modules/cloud/misc/proxmox.py +++ b/plugins/modules/cloud/misc/proxmox.py @@ -14,52 +14,6 @@ description: - Starting in Ansible 2.1, it automatically detects containerization type (lxc for PVE 4, openvz for older) - From community.general 4.0.0 on, there will be no default values, see I(proxmox_default_behavior). options: - api_host: - description: - - the host of the Proxmox VE cluster - type: str - required: true - api_user: - description: - - the user to authenticate with - type: str - required: true - api_password: - description: - - the password to authenticate with - - you can use PROXMOX_PASSWORD environment variable - type: str - api_token_id: - description: - - Specify the token ID. - type: str - version_added: 1.3.0 - api_token_secret: - description: - - Specify the token secret. - type: str - version_added: 1.3.0 - vmid: - description: - - the instance id - - if not set, the next available VM ID will be fetched from ProxmoxAPI. - - 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' - node: - description: - - Proxmox VE node, when new VM will be created - - required only for C(state=present) - - for another states will be autodiscovered - type: str - pool: - description: - - Proxmox VE resource pool - type: str password: description: - the instance root password @@ -205,11 +159,10 @@ options: - compatibility - no_defaults version_added: "1.3.0" - -notes: - - Requires proxmoxer and requests modules on host. This modules can be installed with pip. -requirements: [ "proxmoxer", "python >= 2.7", "requests" ] author: Sergei Antipov (@UnderGreen) +extends_documentation_fragment: + - community.general.proxmox.documentation + - community.general.proxmox.selection ''' EXAMPLES = r''' @@ -510,7 +463,7 @@ def main(): api_token_id=dict(no_log=True), api_token_secret=dict(no_log=True), api_user=dict(required=True), - vmid=dict(required=False), + vmid=dict(type='int', required=False), validate_certs=dict(type='bool', default=False), node=dict(), pool=dict(), diff --git a/plugins/modules/cloud/misc/proxmox_kvm.py b/plugins/modules/cloud/misc/proxmox_kvm.py index 7fd2c203e1..c239a8b85d 100644 --- a/plugins/modules/cloud/misc/proxmox_kvm.py +++ b/plugins/modules/cloud/misc/proxmox_kvm.py @@ -32,31 +32,6 @@ options: - Pass arbitrary arguments to kvm. - This option is for experts only! type: str - api_host: - description: - - Specify the target host of the Proxmox VE cluster. - type: str - required: true - api_user: - description: - - Specify the user to authenticate with. - type: str - required: true - api_password: - description: - - Specify the password to authenticate with. - - You can use C(PROXMOX_PASSWORD) environment variable. - type: str - api_token_id: - description: - - Specify the token ID. - type: str - version_added: 1.3.0 - api_token_secret: - description: - - Specify the token secret. - type: str - version_added: 1.3.0 autostart: description: - Specify if the VM should be automatically restarted after crash (currently ignored in PVE API). @@ -301,12 +276,6 @@ options: - VMID for the clone. Used only with clone. - If newid is not set, the next available VM ID will be fetched from ProxmoxAPI. type: int - node: - description: - - Proxmox VE node, where the new VM will be created. - - Only required for C(state=present). - - For other states, it will be autodiscovered. - type: str numa: description: - A hash/dictionaries of NUMA topology. C(numa='{"key":"value", "key":"value"}'). @@ -343,10 +312,6 @@ options: - Keys allowed are - (parallel[n]) where 0 ≤ n ≤ 2. - Values allowed are - C("/dev/parport\d+|/dev/usb/lp\d+"). type: dict - pool: - description: - - Add the new VM to the specified pool. - type: str protection: description: - Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations. @@ -486,11 +451,6 @@ options: - Update of C(pool) is disabled. It needs an additional API endpoint not covered by this module. type: bool default: 'no' - validate_certs: - description: - - If C(no), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. - type: bool - default: 'no' vcpus: description: - Sets number of hotplugged vcpus. @@ -512,11 +472,6 @@ options: - C(size) is the size of the disk in GB. - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). type: dict - vmid: - description: - - Specifies the VM ID. Instead use I(name) parameter. - - If vmid is not set, the next available VM ID will be fetched from ProxmoxAPI. - type: int watchdog: description: - Creates a virtual hardware watchdog device. @@ -539,8 +494,9 @@ options: - compatibility - no_defaults version_added: "1.3.0" - -requirements: [ "proxmoxer", "requests" ] +extends_documentation_fragment: + - community.general.proxmox.documentation + - community.general.proxmox.selection ''' EXAMPLES = ''' diff --git a/plugins/modules/cloud/misc/proxmox_template.py b/plugins/modules/cloud/misc/proxmox_template.py index 541dc28efa..76228e9a44 100644 --- a/plugins/modules/cloud/misc/proxmox_template.py +++ b/plugins/modules/cloud/misc/proxmox_template.py @@ -15,39 +15,9 @@ short_description: management of OS templates in Proxmox VE cluster description: - allows you to upload/delete templates in Proxmox VE cluster options: - api_host: - description: - - the host of the Proxmox VE cluster - type: str - required: true - api_user: - description: - - the user to authenticate with - type: str - required: true - api_password: - description: - - the password to authenticate with - - you can use PROXMOX_PASSWORD environment variable - type: str - api_token_id: - description: - - Specify the token ID. - type: str - version_added: 1.3.0 - api_token_secret: - description: - - Specify the token secret. - type: str - version_added: 1.3.0 - validate_certs: - description: - - enable / disable https certificate verification - default: 'no' - type: bool node: description: - - Proxmox VE node, when you will operate with template + - Proxmox VE node on which to operate. type: str src: description: @@ -90,8 +60,8 @@ options: default: present notes: - Requires proxmoxer and requests modules on host. This modules can be installed with pip. -requirements: [ "proxmoxer", "requests" ] author: Sergei Antipov (@UnderGreen) +extends_documentation_fragment: community.general.proxmox.documentation ''' EXAMPLES = '''