Proxmox doc fragments (#1404)

* proxmox{,_kvm,_template}: import auth doc fragment * proxmox{,_kvm}: new common doc_fragment Share the parameters `pool`, `vmid` and `node`. * proxmox_template: sync node description * changelog_framgent
2024-09-14 20:13:21 +02:00 · 2020-12-02 16:08:07 +01:00 · 2020-12-02 16:08:07 +01:00 · d981f388fb
commit d981f388fb
parent 70ba401602
5 changed files with 32 additions and 130 deletions
--- a/changelogs/fragments/1404-proxmox-doc-fragments.yml
+++ 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).
--- 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
 '''
--- 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(),
--- 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 = '''
--- 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 = '''