From cdf5a84ec5e575b4f5c9badec6b68b7f466956d6 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Tue, 24 Dec 2024 22:57:01 +1300 Subject: [PATCH 1/4] [prox ... pyth]*: normalize docs --- plugins/modules/proxmox.py | 71 ++++---- plugins/modules/proxmox_backup.py | 53 +++--- plugins/modules/proxmox_disk.py | 60 +++---- plugins/modules/proxmox_domain_info.py | 55 +++--- plugins/modules/proxmox_group_info.py | 51 +++--- plugins/modules/proxmox_kvm.py | 166 +++++++++--------- plugins/modules/proxmox_nic.py | 19 +- plugins/modules/proxmox_node_info.py | 127 +++++++------- plugins/modules/proxmox_pool.py | 11 +- plugins/modules/proxmox_pool_member.py | 9 +- plugins/modules/proxmox_snap.py | 24 +-- .../modules/proxmox_storage_contents_info.py | 7 +- plugins/modules/proxmox_storage_info.py | 29 ++- plugins/modules/proxmox_tasks_info.py | 119 +++++++------ plugins/modules/proxmox_template.py | 15 +- plugins/modules/proxmox_user_info.py | 159 +++++++++-------- plugins/modules/proxmox_vm_info.py | 7 +- plugins/modules/pubnub_blocks.py | 100 ++++------- plugins/modules/pulp_repo.py | 82 ++++----- plugins/modules/puppet.py | 45 +++-- plugins/modules/pushbullet.py | 96 +++++----- plugins/modules/pushover.py | 19 +- plugins/modules/python_requirements_info.py | 38 ++-- 23 files changed, 633 insertions(+), 729 deletions(-) diff --git a/plugins/modules/proxmox.py b/plugins/modules/proxmox.py index 52d5a849f32..3925eec0907 100644 --- a/plugins/modules/proxmox.py +++ b/plugins/modules/proxmox.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox short_description: Management of instances in Proxmox VE cluster description: @@ -26,28 +25,26 @@ options: password: description: - - the instance root password + - The instance root password. type: str hostname: description: - - the instance hostname - - required only for O(state=present) - - must be unique if vmid is not passed + - The instance hostname. + - Required only for O(state=present). + - Must be unique if vmid is not passed. type: str ostemplate: description: - - the template for VM creating - - required only for O(state=present) + - The template for VM creating. + - Required only for O(state=present). type: str disk: description: - - This option was previously described as "hard disk size in GB for instance" however several formats describing - a lxc mount are permitted. - - Older versions of Proxmox will accept a numeric value for size using the O(storage) parameter to automatically - choose which storage to allocate from, however new versions enforce the C(:) syntax. - - "Additional options are available by using some combination of the following key-value pairs as a - comma-delimited list C([volume=] [,acl=<1|0>] [,mountoptions=] [,quota=<1|0>] - [,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>] [,size=])." + - This option was previously described as "hard disk size in GB for instance" however several formats describing a lxc mount are permitted. + - Older versions of Proxmox will accept a numeric value for size using the O(storage) parameter to automatically choose which storage to + allocate from, however new versions enforce the C(:) syntax. + - Additional options are available by using some combination of the following key-value pairs as a comma-delimited list C([volume=] + [,acl=<1|0>] [,mountoptions=] [,quota=<1|0>] [,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>] [,size=]). - See U(https://pve.proxmox.com/wiki/Linux_Container) for a full description. - This option is mutually exclusive with O(storage) and O(disk_volume). type: str @@ -93,19 +90,19 @@ type: int cpus: description: - - numbers of allocated cpus for instance + - Number of allocated cpus for instance. type: int memory: description: - - memory size in MB for instance + - Memory size in MB for instance. type: int swap: description: - - swap memory size in MB for instance + - Swap memory size in MB for instance. type: int netif: description: - - specifies network interfaces for the container. As a hash/dictionary defining interfaces. + - Specifies network interfaces for the container. As a hash/dictionary defining interfaces. type: dict features: description: @@ -177,11 +174,11 @@ type: dict ip_address: description: - - specifies the address the container will be assigned + - Specifies the address the container will be assigned. type: str onboot: description: - - specifies whether a VM will be started during system bootup + - Specifies whether a VM will be started during system bootup. type: bool storage: description: @@ -199,15 +196,15 @@ version_added: 8.1.0 cpuunits: description: - - CPU weight for a VM + - CPU weight for a VM. type: int nameserver: description: - - sets DNS server IP address for a container + - Sets DNS server IP address for a container. type: str searchdomain: description: - - sets DNS search domain for a container + - Sets DNS search domain for a container. type: str tags: description: @@ -219,7 +216,7 @@ version_added: 6.2.0 timeout: description: - - timeout for operations + - Timeout for operations. type: int default: 30 update: @@ -232,8 +229,8 @@ description: - Forcing operations. - Can be used only with states V(present), V(stopped), V(restarted). - - with O(state=present) force option allow to overwrite existing container. - - with states V(stopped), V(restarted) allow to force stop instance. + - With O(state=present) force option allow to overwrite existing container. + - With states V(stopped), V(restarted) allow to force stop instance. type: bool default: false purge: @@ -247,14 +244,14 @@ version_added: 2.3.0 state: description: - - Indicate desired state of the instance - - V(template) was added in community.general 8.1.0. + - Indicate desired state of the instance. + - V(template) was added in community.general 8.1.0. type: str choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'template'] default: present pubkey: description: - - Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions + - Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions. type: str unprivileged: description: @@ -292,8 +289,8 @@ - Type of the clone created. - V(full) creates a full clone, and O(storage) must be specified. - V(linked) creates a linked clone, and the cloned container must be a template container. - - V(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not. - O(storage) may be specified, if not it will fall back to the default. + - V(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not. O(storage) may be specified, + if not it will fall back to the default. type: str choices: ['full', 'linked', 'opportunistic'] default: opportunistic @@ -306,9 +303,9 @@ - community.general.proxmox.documentation - community.general.proxmox.selection - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create new container with minimal options community.general.proxmox: vmid: 100 @@ -494,8 +491,8 @@ hostname: example.org ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz' features: - - nesting=1 - - mount=cifs,nfs + - nesting=1 + - mount=cifs,nfs - name: > Create a linked clone of the template container with id 100. The newly created container with be a @@ -599,7 +596,7 @@ api_password: 1q2w3e api_host: node1 state: absent -''' +""" import re import time diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py index 0db2c4ad0eb..71dbf07325b 100644 --- a/plugins/modules/proxmox_backup.py +++ b/plugins/modules/proxmox_backup.py @@ -10,8 +10,7 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_backup author: "Raphael Grieger (@IamLunchbox) " short_description: Start a VM backup in Proxmox VE cluster @@ -42,11 +41,9 @@ change_detection_mode: description: - Set the change detection mode (available from Proxmox VE 8.3). - - > - Is only used when backing up containers, - Proxmox silently ignores this option when applied to kvm guests. + - It is only used when backing up containers, Proxmox silently ignores this option when applied to kvm guests. type: str - choices: ["legacy", "data", "metadata"] + choices: ["legacy", "data", "metadata"] compress: description: - Enable additional compression of the backup archive. @@ -63,13 +60,9 @@ description: - Specify the description of the backup. - Needs to be a single line, newline and backslash need to be escaped as V(\\n) and V(\\\\) respectively. - - > - If you need variable interpolation, you can set the content as usual - through ansible jinja templating and/or let Proxmox substitute templates. - - > - Proxmox currently supports V({{cluster}}), V({{guestname}}), - V({{node}}), and V({{vmid}}) as templating variables. - Since this is also a jinja delimiter, you need to set these values as raw jinja. + - If you need variable interpolation, you can set the content as usual through ansible jinja templating and/or let Proxmox substitute templates. + - Proxmox currently supports V({{cluster}}), V({{guestname}}), V({{node}}), and V({{vmid}}) as templating variables. Since this is also + a jinja delimiter, you need to set these values as raw jinja. default: "{{guestname}}" type: str fleecing: @@ -93,13 +86,13 @@ description: - Determine which notification system to use. type: str - choices: ["auto","legacy-sendmail", "notification-system"] + choices: ["auto", "legacy-sendmail", "notification-system"] default: auto performance_tweaks: description: - Enable other performance-related settings. - Must be entered as a string, containing comma separated key-value pairs. - - "For example: V(max-workers=2,pbs-entries-max=2)." + - 'For example: V(max-workers=2,pbs-entries-max=2).' type: str pool: description: @@ -110,19 +103,14 @@ protected: description: - Marks backups as protected. - - > - "Might fail, when the PBS backend has verify enabled - due to this bug: U(https://bugzilla.proxmox.com/show_bug.cgi?id=4289)" + - '"Might fail, when the PBS backend has verify enabled due to this bug: U(https://bugzilla.proxmox.com/show_bug.cgi?id=4289)".' type: bool retention: description: - - > - Use custom retention options instead of those from the default cluster - configuration (which is usually V("keep-all")). + - Use custom retention options instead of those from the default cluster configuration (which is usually V("keep-all")). - Always requires Datastore.Allocate permission at the storage endpoint. - - > - Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore, - if an existing backup should be deleted target due to your specified timeframe. + - Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore, if an existing backup should be deleted target + due to your specified timeframe. - Deleting requires C(Datastore.Modify) or C(Datastore.Prune) permissions on the backup storage. type: str storage: @@ -153,9 +141,9 @@ - community.general.proxmox.actiongroup_proxmox - community.general.proxmox.documentation - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Backup all vms in the Proxmox cluster to storage mypbs community.general.proxmox_backup: api_user: root@pam @@ -204,9 +192,9 @@ vmids: - 100 - 101 -''' +""" -RETURN = r''' +RETURN = r""" backups: description: List of nodes and their task IDs. returned: on success @@ -223,13 +211,12 @@ type: str choices: ["unknown", "success", "failed"] upid: - description: > - Proxmox cluster UPID, which is needed to lookup task info. - Returns OK, when a cluster node did not create a task after being called, - e.g. due to no matching targets. + description: >- + Proxmox cluster UPID, which is needed to lookup task info. Returns OK, when a cluster node did not create a task after being called, for + example due to no matching targets. returned: on success type: str -''' +""" import time diff --git a/plugins/modules/proxmox_disk.py b/plugins/modules/proxmox_disk.py index a4a9dd87919..289933915e6 100644 --- a/plugins/modules/proxmox_disk.py +++ b/plugins/modules/proxmox_disk.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_disk short_description: Management of a disk of a Qemu(KVM) VM in a Proxmox VE cluster version_added: 5.7.0 @@ -38,31 +37,21 @@ description: - The disk key (V(unused[n]), V(ide[n]), V(sata[n]), V(scsi[n]) or V(virtio[n])) you want to operate on. - Disk buses (IDE, SATA and so on) have fixed ranges of V(n) that accepted by Proxmox API. - - > - For IDE: 0-3; - for SCSI: 0-30; - for SATA: 0-5; - for VirtIO: 0-15; - for Unused: 0-255. + - 'For IDE: 0-3; for SCSI: 0-30; for SATA: 0-5; for VirtIO: 0-15; for Unused: 0-255.' type: str required: true state: description: - Indicates desired state of the disk. - - > - O(state=present) can be used to create, replace disk or update options in existing disk. It will create missing - disk or update options in existing one by default. See the O(create) parameter description to control behavior - of this option. + - O(state=present) can be used to create, replace disk or update options in existing disk. It will create missing disk or update options + in existing one by default. See the O(create) parameter description to control behavior of this option. - Some updates on options (like O(cache)) are not being applied instantly and require VM restart. - - > - Use O(state=detached) to detach existing disk from VM but do not remove it entirely. - When O(state=detached) and disk is V(unused[n]) it will be left in same state (not removed). - - > - O(state=moved) may be used to change backing storage for the disk in bounds of the same VM - or to send the disk to another VM (using the same backing storage). - - > - O(state=resized) intended to change the disk size. As of Proxmox 7.2 you can only increase the disk size - because shrinking disks is not supported by the PVE API and has to be done manually. + - Use O(state=detached) to detach existing disk from VM but do not remove it entirely. When O(state=detached) and disk is V(unused[n]) it + will be left in same state (not removed). + - O(state=moved) may be used to change backing storage for the disk in bounds of the same VM or to send the disk to another VM (using the + same backing storage). + - O(state=resized) intended to change the disk size. As of Proxmox 7.2 you can only increase the disk size because shrinking disks is not + supported by the PVE API and has to be done manually. - To entirely remove the disk from backing storage use O(state=absent). type: str choices: ['present', 'resized', 'detached', 'moved', 'absent'] @@ -84,10 +73,8 @@ size: description: - Desired volume size in GB to allocate when O(state=present) (specify O(size) without suffix). - - > - New (or additional) size of volume when O(state=resized). With the V(+) sign - the value is added to the actual size of the volume - and without it, the value is taken as an absolute one. + - New (or additional) size of volume when O(state=resized). With the V(+) sign the value is added to the actual size of the volume and without + it, the value is taken as an absolute one. type: str bwlimit: description: @@ -176,8 +163,8 @@ import_from: description: - Import volume from this existing one. - - Volume string format - - C(:/) or C(/) + - Volume string format. + - V(:/) or V(/). - Attention! Only root can use absolute paths. - This parameter is mutually exclusive with O(size). - Increase O(timeout) parameter when importing large disk images or using slow storage. @@ -223,7 +210,7 @@ type: int iothread: description: - - Whether to use iothreads for this drive (only for SCSI and VirtIO) + - Whether to use iothreads for this drive (only for SCSI and VirtIO). type: bool mbps: description: @@ -262,10 +249,9 @@ description: - The ISO image to be mounted on the specified in O(disk) CD-ROM. - O(media=cdrom) needs to be specified for this option to work. - - "Image string format:" - - V(:iso/) to mount ISO. - - V(cdrom) to use physical CD/DVD drive. - - V(none) to unmount image from existent CD-ROM or create empty CD-ROM drive. + - Use V(:iso/) to mount ISO. + - Use V(cdrom) to access the physical CD/DVD drive. + - Use V(none) to unmount image from existent CD-ROM or create empty CD-ROM drive. type: str version_added: 8.1.0 queues: @@ -330,9 +316,9 @@ - community.general.proxmox.actiongroup_proxmox - community.general.proxmox.documentation - community.general.attributes -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create new disk in VM (do not rewrite in case it exists already) community.general.proxmox_disk: api_host: node1 @@ -437,9 +423,9 @@ media: cdrom iso_image: local:iso/favorite_distro_amd64.iso state: present -''' +""" -RETURN = ''' +RETURN = r""" vmid: description: The VM vmid. returned: success @@ -450,7 +436,7 @@ returned: always type: str sample: "Disk scsi3 created in VM 101" -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, diff --git a/plugins/modules/proxmox_domain_info.py b/plugins/modules/proxmox_domain_info.py index f3ff212bff4..d9836da2777 100644 --- a/plugins/modules/proxmox_domain_info.py +++ b/plugins/modules/proxmox_domain_info.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox_domain_info short_description: Retrieve information about one or more Proxmox VE domains version_added: 1.3.0 @@ -31,10 +30,10 @@ - community.general.proxmox.documentation - community.general.attributes - community.general.attributes.info_module -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List existing domains community.general.proxmox_domain_info: api_host: helldorado @@ -53,33 +52,33 @@ api_token_secret: "{{ token_secret | default(omit) }}" domain: pve register: proxmox_domain_pve -''' +""" -RETURN = ''' +RETURN = r""" proxmox_domains: - description: List of authentication domains. - returned: always, but can be empty - type: list - elements: dict - contains: - comment: - description: Short description of the realm. - returned: on success - type: str - realm: - description: Realm name. - returned: on success - type: str - type: - description: Realm type. - returned: on success - type: str - digest: - description: Realm hash. - returned: on success, can be absent - type: str -''' + description: List of authentication domains. + returned: always, but can be empty + type: list + elements: dict + contains: + comment: + description: Short description of the realm. + returned: on success + type: str + realm: + description: Realm name. + returned: on success + type: str + type: + description: Realm type. + returned: on success + type: str + digest: + description: Realm hash. + returned: on success, can be absent + type: str +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/proxmox_group_info.py b/plugins/modules/proxmox_group_info.py index eda1fe04d8a..f62d467af8d 100644 --- a/plugins/modules/proxmox_group_info.py +++ b/plugins/modules/proxmox_group_info.py @@ -9,13 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox_group_info short_description: Retrieve information about one or more Proxmox VE groups version_added: 1.3.0 description: - - Retrieve information about one or more Proxmox VE groups + - Retrieve information about one or more Proxmox VE groups. attributes: action_group: version_added: 9.0.0 @@ -31,10 +30,10 @@ - community.general.proxmox.documentation - community.general.attributes - community.general.attributes.info_module -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List existing groups community.general.proxmox_group_info: api_host: helldorado @@ -53,30 +52,30 @@ api_token_secret: "{{ token_secret | default(omit) }}" group: admin register: proxmox_group_admin -''' +""" -RETURN = ''' +RETURN = r""" proxmox_groups: - description: List of groups. - returned: always, but can be empty - type: list - elements: dict - contains: - comment: - description: Short description of the group. - returned: on success, can be absent - type: str - groupid: - description: Group name. - returned: on success - type: str - users: - description: List of users in the group. - returned: on success - type: list - elements: str -''' + description: List of groups. + returned: always, but can be empty + type: list + elements: dict + contains: + comment: + description: Short description of the group. + returned: on success, can be absent + type: str + groupid: + description: Group name. + returned: on success + type: str + users: + description: List of users in the group. + returned: on success + type: list + elements: str +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/proxmox_kvm.py b/plugins/modules/proxmox_kvm.py index 0c9904873d0..d495b08694c 100644 --- a/plugins/modules/proxmox_kvm.py +++ b/plugins/modules/proxmox_kvm.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_kvm short_description: Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster description: @@ -66,21 +65,21 @@ type: str bootdisk: description: - - 'Enable booting from specified disk. Format V((ide|sata|scsi|virtio\)\\d+).' + - Enable booting from specified disk. Format V((ide|sata|scsi|virtio\)\\d+). type: str cicustom: description: - - 'cloud-init: Specify custom files to replace the automatically generated ones at start.' + - 'Cloud-init: Specify custom files to replace the automatically generated ones at start.' type: str version_added: 1.3.0 cipassword: description: - - 'cloud-init: password of default user to create.' + - 'Cloud-init: password of default user to create.' type: str version_added: 1.3.0 citype: description: - - 'cloud-init: Specifies the cloud-init configuration format.' + - 'Cloud-init: Specifies the cloud-init configuration format.' - The default depends on the configured operating system type (V(ostype)). - We use the V(nocloud) format for Linux, and V(configdrive2) for Windows. type: str @@ -88,12 +87,12 @@ version_added: 1.3.0 ciupgrade: description: - - 'cloud-init: do an automatic package upgrade after the first boot.' + - 'Cloud-init: do an automatic package upgrade after the first boot.' type: bool version_added: 10.0.0 ciuser: description: - - 'cloud-init: username of default user to create.' + - 'Cloud-init: username of default user to create.' type: str version_added: 1.3.0 clone: @@ -110,13 +109,13 @@ type: str cpulimit: description: - - Specify if CPU usage will be limited. Value 0 indicates no CPU limit. - - If the computer has 2 CPUs, it has total of '2' CPU time + - Specify if CPU usage will be limited. Value V(0) indicates no CPU limit. + - If the computer has 2 CPUs, it has total of '2' CPU time. type: int cpuunits: description: - Specify CPU weight for a VM. - - You can disable fair-scheduler configuration by setting this to 0 + - You can disable fair-scheduler configuration by setting this to V(0). type: int delete: description: @@ -144,24 +143,22 @@ type: str format: description: - - V(format) is the drive's backing file's data format. Please refer to the Proxmox VE Administrator Guide, - section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest - version, tables 3 to 14) to find out format supported by the provided storage backend. + - V(format) is the drive's backing file's data format. Please refer to the Proxmox VE Administrator Guide, section Proxmox VE Storage + (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format supported by + the provided storage backend. type: str efitype: description: - V(efitype) indicates the size of the EFI disk. - V(2m) will allow for a 2MB EFI disk, which will be enough to persist boot order and new boot entries. - - V(4m) will allow for a 4MB EFI disk, which will additionally allow to store EFI keys in order to enable - Secure Boot + - V(4m) will allow for a 4MB EFI disk, which will additionally allow to store EFI keys in order to enable Secure Boot. type: str choices: - 2m - 4m pre_enrolled_keys: description: - - V(pre_enrolled_keys) indicates whether EFI keys for Secure Boot should be enrolled V(1) in the VM firmware - upon creation or not (0). + - V(pre_enrolled_keys) indicates whether EFI keys for Secure Boot should be enrolled V(1) in the VM firmware upon creation or not (0). - If set to V(1), Secure Boot will also be enabled by default when the VM is created. type: bool version_added: 4.5.0 @@ -174,14 +171,13 @@ format: description: - Target drive's backing file's data format. - - Used only with clone + - Used only with clone. - Use O(format=unspecified) and O(full=false) for a linked clone. - - Please refer to the Proxmox VE Administrator Guide, section Proxmox VE Storage (see - U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format - supported by the provided storage backend. + - Please refer to the Proxmox VE Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) + for the latest version, tables 3 to 14) to find out format supported by the provided storage backend. - Not specifying this option is equivalent to setting it to V(unspecified). type: str - choices: [ "cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified" ] + choices: ["cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified"] freeze: description: - Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution). @@ -190,7 +186,7 @@ description: - Create a full copy of all disk. This is always done when you clone a normal VM. - For VM templates, we try to create a linked clone by default. - - Used only with clone + - Used only with clone. type: bool default: true hookscript: @@ -202,11 +198,11 @@ description: - Specify a hash/dictionary of map host pci devices into guest. O(hostpci='{"key":"value", "key":"value"}'). - Keys allowed are - C(hostpci[n]) where 0 ≤ n ≤ N. - - Values allowed are - C("host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0""). - - The C(host) parameter is Host PCI device pass through. HOSTPCIID syntax is C(bus:dev.func) (hexadecimal numbers). - - C(pcie=boolean) C(default=0) Choose the PCI-express bus (needs the q35 machine model). - - C(rombar=boolean) C(default=1) Specify whether or not the device's ROM will be visible in the guest's memory map. - - C(x-vga=boolean) C(default=0) Enable vfio-vga device support. + - Values allowed are - V("host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0""). + - The C(host) parameter is Host PCI device pass through. HOSTPCIID syntax is V(bus:dev.func) (hexadecimal numbers). + - V(pcie=boolean) V(default=0) Choose the PCI-express bus (needs the q35 machine model). + - V(rombar=boolean) V(default=1) Specify whether or not the device's ROM will be visible in the guest's memory map. + - V(x-vga=boolean) V(default=0) Enable vfio-vga device support. - /!\ This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use with special care. type: dict hotplug: @@ -223,21 +219,21 @@ ide: description: - A hash/dictionary of volume used as IDE hard disk or CD-ROM. O(ide='{"key":"value", "key":"value"}'). - - Keys allowed are - C(ide[n]) where 0 ≤ n ≤ 3. - - Values allowed are - C("storage:size,format=value"). - - C(storage) is the storage identifier where to create the disk. - - 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). Please refer to the Proxmox VE - Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for - the latest version, tables 3 to 14) to find out format supported by the provided storage backend. + - Keys allowed are - V(ide[n]) where 0 ≤ n ≤ 3. + - Values allowed are - V("storage:size,format=value"). + - V(storage) is the storage identifier where to create the disk. + - V(size) is the size of the disk in GB. + - V(format) is the drive's backing file's data format. V(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator Guide, section + Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format + supported by the provided storage backend. type: dict ipconfig: description: - - 'cloud-init: Set the IP configuration.' + - 'Cloud-init: Set the IP configuration.' - A hash/dictionary of network ip configurations. O(ipconfig='{"key":"value", "key":"value"}'). - - Keys allowed are - C(ipconfig[n]) where 0 ≤ n ≤ network interfaces. - - Values allowed are - C("[gw=] [,gw6=] [,ip=] [,ip6=]"). - - 'cloud-init: Specify IP addresses and gateways for the corresponding interface.' + - Keys allowed are - V(ipconfig[n]) where 0 ≤ n ≤ network interfaces. + - Values allowed are - V("[gw=] [,gw6=] [,ip=] [,ip6=]"). + - 'Cloud-init: Specify IP addresses and gateways for the corresponding interface.' - IP addresses use CIDR notation, gateways are optional but they should be in the same subnet of specified IP address. - The special string 'dhcp' can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided. - For IPv6 the special string 'auto' can be used to use stateless autoconfiguration. @@ -265,7 +261,7 @@ machine: description: - Specifies the Qemu machine type. - - 'Type => V((pc|pc(-i440fx\)?-\\d+\\.\\d+(\\.pxe\)?|q35|pc-q35-\\d+\\.\\d+(\\.pxe\)?\)).' + - Type => V((pc|pc(-i440fx\)?-\\d+\\.\\d+(\\.pxe\)?|q35|pc-q35-\\d+\\.\\d+(\\.pxe\)?\)). type: str memory: description: @@ -294,7 +290,7 @@ type: str nameservers: description: - - 'cloud-init: DNS server IP address(es).' + - 'Cloud-init: DNS server IP address(es).' - If unset, PVE host settings are used. type: list elements: str @@ -307,7 +303,8 @@ - Model is one of C(e1000 e1000-82540em e1000-82544gc e1000-82545em i82551 i82557b i82559er ne2k_isa ne2k_pci pcnet rtl8139 virtio vmxnet3). - C(XX:XX:XX:XX:XX:XX) should be an unique MAC address. This is automatically generated if not specified. - The C(bridge) parameter can be used to automatically add the interface to a bridge device. The Proxmox VE standard bridge is called 'vmbr0'. - - Option C(rate) is used to limit traffic bandwidth from and to this interface. It is specified as floating point number, unit is 'Megabytes per second'. + - Option C(rate) is used to limit traffic bandwidth from and to this interface. It is specified as floating point number, unit is 'Megabytes + per second'. - If you specify no bridge, we create a kvm 'user' (NATed) network device, which provides DHCP and DNS services. type: dict newid: @@ -361,23 +358,23 @@ description: - A hash/dictionary of volume used as sata hard disk or CD-ROM. O(sata='{"key":"value", "key":"value"}'). - Keys allowed are - C(sata[n]) where 0 ≤ n ≤ 5. - - Values allowed are - C("storage:size,format=value"). + - Values allowed are - C("storage:size,format=value"). - C(storage) is the storage identifier where to create the disk. - 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). Please refer to the Proxmox VE - Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for - the latest version, tables 3 to 14) to find out format supported by the provided storage backend. + - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator Guide, section + Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format + supported by the provided storage backend. type: dict scsi: description: - A hash/dictionary of volume used as SCSI hard disk or CD-ROM. O(scsi='{"key":"value", "key":"value"}'). - Keys allowed are - C(scsi[n]) where 0 ≤ n ≤ 13. - - Values allowed are - C("storage:size,format=value"). + - Values allowed are - C("storage:size,format=value"). - C(storage) is the storage identifier where to create the disk. - 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). Please refer to the Proxmox VE - Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for - the latest version, tables 3 to 14) to find out format supported by the provided storage backend. + - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator Guide, section + Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format + supported by the provided storage backend. type: dict scsihw: description: @@ -386,7 +383,7 @@ choices: ['lsi', 'lsi53c810', 'virtio-scsi-pci', 'virtio-scsi-single', 'megasas', 'pvscsi'] searchdomains: description: - - 'cloud-init: Sets DNS search domain(s).' + - 'Cloud-init: Sets DNS search domain(s).' - If unset, PVE host settings are used. type: list elements: str @@ -407,20 +404,20 @@ type: int skiplock: description: - - Ignore locks + - Ignore locks. - Only root is allowed to use this option. type: bool smbios: description: - Specifies SMBIOS type 1 fields. - - "Comma separated, Base64 encoded (optional) SMBIOS properties:" - - V([base64=<1|0>] [,family=]) - - V([,manufacturer=]) - - V([,product=]) - - V([,serial=]) - - V([,sku=]) - - V([,uuid=]) - - V([,version=]) + - Comma separated, Base64 encoded (optional) SMBIOS properties:. + - V([base64=<1|0>] [,family=]). + - V([,manufacturer=]). + - V([,product=]). + - V([,serial=]). + - V([,sku=]). + - V([,uuid=]). + - V([,version=]). type: str snapname: description: @@ -432,7 +429,7 @@ type: int sshkeys: description: - - 'cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.' + - 'Cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.' type: str version_added: 1.3.0 startdate: @@ -449,7 +446,7 @@ state: description: - Indicates desired state of the instance. - - If V(current), the current state of the VM will be fetched. You can access it with C(results.status) + - If V(current), the current state of the VM will be fetched. You can access it with C(results.status). - V(template) was added in community.general 8.1.0. type: str choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'current', 'template'] @@ -473,7 +470,7 @@ target: description: - Target node. Only allowed if the original VM is on shared storage. - - Used only with clone + - Used only with clone. type: str tdf: description: @@ -512,7 +509,7 @@ - A hash/dictionary of USB devices for the VM. O(usb='{"key":"value", "key":"value"}'). - Keys allowed are - C(usb[n]) where 0 ≤ n ≤ N. - Values allowed are - C(host="value|spice",mapping="value",usb3="1|0"). - - host is either C(spice) or the USB id/port. + - Host is either C(spice) or the USB id/port. - Option C(mapping) is the mapped USB device name. - Option C(usb3) enables USB 3 support. type: dict @@ -520,16 +517,16 @@ update: description: - If V(true), the VM will be updated with new value. - - Because of the operations of the API and security reasons, I have disabled the update of the following parameters - O(net), O(virtio), O(ide), O(sata), O(scsi). Per example updating O(net) update the MAC address and C(virtio) create always new disk... - This security feature can be disabled by setting the O(update_unsafe) to V(true). + - Because of the operations of the API and security reasons, I have disabled the update of the following parameters O(net), O(virtio), O(ide), + O(sata), O(scsi). Per example updating O(net) update the MAC address and O(virtio) create always new disk... This security feature can + be disabled by setting the O(update_unsafe) to V(true). - Update of O(pool) is disabled. It needs an additional API endpoint not covered by this module. type: bool default: false update_unsafe: description: - - If V(true), do not enforce limitations on parameters O(net), O(virtio), O(ide), O(sata), O(scsi), O(efidisk0), and O(tpmstate0). - Use this option with caution because an improper configuration might result in a permanent loss of data (e.g. disk recreated). + - If V(true), do not enforce limitations on parameters O(net), O(virtio), O(ide), O(sata), O(scsi), O(efidisk0), and O(tpmstate0). Use this + option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated). type: bool default: false version_added: 8.4.0 @@ -545,13 +542,13 @@ virtio: description: - A hash/dictionary of volume used as VIRTIO hard disk. O(virtio='{"key":"value", "key":"value"}'). - - Keys allowed are - C(virtio[n]) where 0 ≤ n ≤ 15. - - Values allowed are - C("storage:size,format=value"). - - C(storage) is the storage identifier where to create the disk. - - 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). Please refer to the Proxmox VE - Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) - for the latest version, tables 3 to 14) to find out format supported by the provided storage backend. + - Keys allowed are - V(virtio[n]) where 0 ≤ n ≤ 15. + - Values allowed are - V("storage:size,format=value"). + - V(storage) is the storage identifier where to create the disk. + - V(size) is the size of the disk in GB. + - V(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator Guide, section + Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format + supported by the provided storage backend. type: dict watchdog: description: @@ -564,9 +561,9 @@ - community.general.proxmox.documentation - community.general.proxmox.selection - community.general.attributes -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create new VM with minimal options community.general.proxmox_kvm: api_user: root@pam @@ -846,7 +843,7 @@ cores: 8 memory: 16384 net: - net0: virtio,bridge=vmbr1 + net0: virtio,bridge=vmbr1 update: true update_unsafe: true @@ -886,10 +883,9 @@ node: sabrewulf hookscript: local:snippets/hookscript.pl update: true +""" -''' - -RETURN = ''' +RETURN = r""" vmid: description: The VM vmid. returned: success @@ -901,11 +897,11 @@ type: str sample: running msg: - description: A short message + description: A short message. returned: always type: str sample: "VM kropta with vmid = 110 is running" -''' +""" import re import time diff --git a/plugins/modules/proxmox_nic.py b/plugins/modules/proxmox_nic.py index 6e94ed0bb6d..bcf23bc5a1b 100644 --- a/plugins/modules/proxmox_nic.py +++ b/plugins/modules/proxmox_nic.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_nic short_description: Management of a NIC of a Qemu(KVM) VM in a Proxmox VE cluster version_added: 3.1.0 @@ -52,8 +51,8 @@ description: - The NIC emulator model. type: str - choices: ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b', 'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet', - 'rtl8139', 'virtio', 'vmxnet3'] + choices: ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b', 'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet', 'rtl8139', + 'virtio', 'vmxnet3'] default: virtio mtu: description: @@ -99,9 +98,9 @@ - community.general.proxmox.actiongroup_proxmox - community.general.proxmox.documentation - community.general.attributes -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create NIC net0 targeting the vm by name community.general.proxmox_nic: api_user: root@pam @@ -131,20 +130,20 @@ name: my_vm interface: net0 state: absent -''' +""" -RETURN = ''' +RETURN = r""" vmid: description: The VM vmid. returned: success type: int sample: 115 msg: - description: A short message + description: A short message. returned: always type: str sample: "Nic net0 unchanged on VM with vmid 103" -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible) diff --git a/plugins/modules/proxmox_node_info.py b/plugins/modules/proxmox_node_info.py index 51d8745c05b..e243862134a 100644 --- a/plugins/modules/proxmox_node_info.py +++ b/plugins/modules/proxmox_node_info.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox_node_info short_description: Retrieve information about one or more Proxmox VE nodes version_added: 8.2.0 @@ -25,10 +24,10 @@ - community.general.proxmox.documentation - community.general.attributes - community.general.attributes.info_module -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List existing nodes community.general.proxmox_node_info: api_host: proxmox1 @@ -37,69 +36,69 @@ api_token_id: "{{ token_id | default(omit) }}" api_token_secret: "{{ token_secret | default(omit) }}" register: proxmox_nodes -''' +""" -RETURN = ''' +RETURN = r""" proxmox_nodes: - description: List of Proxmox VE nodes. - returned: always, but can be empty - type: list - elements: dict - contains: - cpu: - description: Current CPU usage in fractional shares of this host's total available CPU. - returned: on success - type: float - disk: - description: Current local disk usage of this host. - returned: on success - type: int - id: - description: Identity of the node. - returned: on success - type: str - level: - description: Support level. Can be blank if not under a paid support contract. - returned: on success - type: str - maxcpu: - description: Total number of available CPUs on this host. - returned: on success - type: int - maxdisk: - description: Size of local disk in bytes. - returned: on success - type: int - maxmem: - description: Memory size in bytes. - returned: on success - type: int - mem: - description: Used memory in bytes. - returned: on success - type: int - node: - description: Short hostname of this node. - returned: on success - type: str - ssl_fingerprint: - description: SSL fingerprint of the node certificate. - returned: on success - type: str - status: - description: Node status. - returned: on success - type: str - type: - description: Object type being returned. - returned: on success - type: str - uptime: - description: Node uptime in seconds. - returned: on success - type: int -''' + description: List of Proxmox VE nodes. + returned: always, but can be empty + type: list + elements: dict + contains: + cpu: + description: Current CPU usage in fractional shares of this host's total available CPU. + returned: on success + type: float + disk: + description: Current local disk usage of this host. + returned: on success + type: int + id: + description: Identity of the node. + returned: on success + type: str + level: + description: Support level. Can be blank if not under a paid support contract. + returned: on success + type: str + maxcpu: + description: Total number of available CPUs on this host. + returned: on success + type: int + maxdisk: + description: Size of local disk in bytes. + returned: on success + type: int + maxmem: + description: Memory size in bytes. + returned: on success + type: int + mem: + description: Used memory in bytes. + returned: on success + type: int + node: + description: Short hostname of this node. + returned: on success + type: str + ssl_fingerprint: + description: SSL fingerprint of the node certificate. + returned: on success + type: str + status: + description: Node status. + returned: on success + type: str + type: + description: Object type being returned. + returned: on success + type: str + uptime: + description: Node uptime in seconds. + returned: on success + type: int +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/proxmox_pool.py b/plugins/modules/proxmox_pool.py index 5089ec3bef6..c53e394eeb2 100644 --- a/plugins/modules/proxmox_pool.py +++ b/plugins/modules/proxmox_pool.py @@ -8,7 +8,6 @@ __metaclass__ = type DOCUMENTATION = r""" ---- module: proxmox_pool short_description: Pool management for Proxmox VE cluster description: @@ -28,12 +27,12 @@ description: - The pool ID. type: str - aliases: [ "name" ] + aliases: ["name"] required: true state: description: - - Indicate desired state of the pool. - - The pool must be empty prior deleting it with O(state=absent). + - Indicate desired state of the pool. + - The pool must be empty prior deleting it with O(state=absent). choices: ['present', 'absent'] default: present type: str @@ -49,7 +48,7 @@ - community.general.attributes """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create new Proxmox VE pool community.general.proxmox_pool: api_host: node1 @@ -67,7 +66,7 @@ state: absent """ -RETURN = """ +RETURN = r""" poolid: description: The pool ID. returned: success diff --git a/plugins/modules/proxmox_pool_member.py b/plugins/modules/proxmox_pool_member.py index b26082f9758..bd32e94e426 100644 --- a/plugins/modules/proxmox_pool_member.py +++ b/plugins/modules/proxmox_pool_member.py @@ -8,7 +8,6 @@ __metaclass__ = type DOCUMENTATION = r""" ---- module: proxmox_pool_member short_description: Add or delete members from Proxmox VE cluster pools description: @@ -27,7 +26,7 @@ description: - The pool ID. type: str - aliases: [ "name" ] + aliases: ["name"] required: true member: description: @@ -44,7 +43,7 @@ type: str state: description: - - Indicate desired state of the pool member. + - Indicate desired state of the pool member. choices: ['present', 'absent'] default: present type: str @@ -55,7 +54,7 @@ - community.general.attributes """ -EXAMPLES = """ +EXAMPLES = r""" - name: Add new VM to Proxmox VE pool community.general.proxmox_pool_member: api_host: node1 @@ -93,7 +92,7 @@ state: absent """ -RETURN = """ +RETURN = r""" poolid: description: The pool ID. returned: success diff --git a/plugins/modules/proxmox_snap.py b/plugins/modules/proxmox_snap.py index 4f7b345b80f..57dad924137 100644 --- a/plugins/modules/proxmox_snap.py +++ b/plugins/modules/proxmox_snap.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_snap short_description: Snapshot management of instances in Proxmox VE cluster version_added: 2.0.0 @@ -35,8 +34,8 @@ type: str state: description: - - Indicate desired state of the instance snapshot. - - The V(rollback) value was added in community.general 4.8.0. + - Indicate desired state of the instance snapshot. + - The V(rollback) value was added in community.general 4.8.0. choices: ['present', 'absent', 'rollback'] default: present type: str @@ -51,7 +50,8 @@ - Allows to snapshot a container even if it has configured mountpoints. - Temporarily disables all configured mountpoints, takes snapshot, and finally restores original configuration. - If running, the container will be stopped and restarted to apply config changes. - - Due to restrictions in the Proxmox API this option can only be used authenticating as V(root@pam) with O(api_password), API tokens do not work either. + - Due to restrictions in the Proxmox API this option can only be used authenticating as V(root@pam) with O(api_password), API tokens do + not work either. - See U(https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/lxc/{vmid}/config) (PUT tab) for more details. default: false type: bool @@ -80,23 +80,23 @@ description: - Remove old snapshots if there are more than O(retention) snapshots. - If O(retention) is set to V(0), all snapshots will be kept. - - This is only used when O(state=present) and when an actual snapshot is created. - If no snapshot is created, all existing snapshots will be kept. + - This is only used when O(state=present) and when an actual snapshot is created. If no snapshot is created, all existing snapshots will + be kept. default: 0 type: int version_added: 7.1.0 notes: - Requires proxmoxer and requests modules on host. These modules can be installed with pip. -requirements: [ "proxmoxer", "requests" ] +requirements: ["proxmoxer", "requests"] author: Jeffrey van Pelt (@Thulium-Drake) extends_documentation_fragment: - community.general.proxmox.actiongroup_proxmox - community.general.proxmox.documentation - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create new container snapshot community.general.proxmox_snap: api_user: root@pam @@ -143,9 +143,9 @@ vmid: 100 state: rollback snapname: pre-updates -''' +""" -RETURN = r'''#''' +RETURN = r"""#""" import time diff --git a/plugins/modules/proxmox_storage_contents_info.py b/plugins/modules/proxmox_storage_contents_info.py index b777870e54c..e0e95565d7f 100644 --- a/plugins/modules/proxmox_storage_contents_info.py +++ b/plugins/modules/proxmox_storage_contents_info.py @@ -10,8 +10,7 @@ __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: proxmox_storage_contents_info short_description: List content from a Proxmox VE storage version_added: 8.2.0 @@ -51,7 +50,7 @@ """ -EXAMPLES = """ +EXAMPLES = r""" - name: List existing storages community.general.proxmox_storage_contents_info: api_host: helldorado @@ -65,7 +64,7 @@ """ -RETURN = """ +RETURN = r""" proxmox_storage_content: description: Content of of storage attached to a node. type: list diff --git a/plugins/modules/proxmox_storage_info.py b/plugins/modules/proxmox_storage_info.py index fd5a6ee0d8f..5b9b1b6aaa4 100644 --- a/plugins/modules/proxmox_storage_info.py +++ b/plugins/modules/proxmox_storage_info.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox_storage_info short_description: Retrieve information about one or more Proxmox VE storages version_added: 2.2.0 @@ -37,10 +36,10 @@ - community.general.attributes.info_module notes: - Storage specific options can be returned by this module, please look at the documentation at U(https://pve.proxmox.com/wiki/Storage). -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List existing storages community.general.proxmox_storage_info: api_host: helldorado @@ -69,10 +68,10 @@ api_token_secret: "{{ token_secret | default(omit) }}" storage: lvm2 register: proxmox_storage_lvm -''' +""" -RETURN = ''' +RETURN = r""" proxmox_storages: description: List of storage pools. returned: on success @@ -80,41 +79,41 @@ elements: dict contains: content: - description: Proxmox content types available in this storage + description: Proxmox content types available in this storage. returned: on success type: list elements: str digest: - description: Storage's digest + description: Storage's digest. returned: on success type: str nodes: - description: List of nodes associated to this storage + description: List of nodes associated to this storage. returned: on success, if storage is not local type: list elements: str path: - description: Physical path to this storage + description: Physical path to this storage. returned: on success type: str prune-backups: - description: Backup retention options + description: Backup retention options. returned: on success type: list elements: dict shared: - description: Is this storage shared + description: Is this storage shared. returned: on success type: bool storage: - description: Storage name + description: Storage name. returned: on success type: str type: - description: Storage type + description: Storage type. returned: on success type: str -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/proxmox_tasks_info.py b/plugins/modules/proxmox_tasks_info.py index 65a07566a88..574a9714277 100644 --- a/plugins/modules/proxmox_tasks_info.py +++ b/plugins/modules/proxmox_tasks_info.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_tasks_info short_description: Retrieve information about one or more Proxmox VE tasks version_added: 3.8.0 @@ -36,10 +35,10 @@ - community.general.proxmox.documentation - community.general.attributes - community.general.attributes.info_module -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List tasks on node01 community.general.proxmox_tasks_info: api_host: proxmoxhost @@ -60,66 +59,66 @@ task: 'UPID:node01:00003263:16167ACE:621EE230:srvreload:networking:root@pam:' node: node01 register: proxmox_tasks -''' +""" -RETURN = ''' +RETURN = r""" proxmox_tasks: - description: List of tasks. - returned: on success - type: list - elements: dict - contains: - id: - description: ID of the task. - returned: on success - type: str - node: - description: Node name. - returned: on success - type: str - pid: - description: PID of the task. - returned: on success - type: int - pstart: - description: pastart of the task. - returned: on success - type: int - starttime: - description: Starting time of the task. - returned: on success - type: int - type: - description: Type of the task. - returned: on success - type: str - upid: - description: UPID of the task. - returned: on success - type: str - user: - description: User that owns the task. - returned: on success - type: str - endtime: - description: Endtime of the task. - returned: on success, can be absent - type: int - status: - description: Status of the task. - returned: on success, can be absent - type: str - failed: - description: If the task failed. - returned: when status is defined - type: bool + description: List of tasks. + returned: on success + type: list + elements: dict + contains: + id: + description: ID of the task. + returned: on success + type: str + node: + description: Node name. + returned: on success + type: str + pid: + description: PID of the task. + returned: on success + type: int + pstart: + description: Pastart of the task. + returned: on success + type: int + starttime: + description: Starting time of the task. + returned: on success + type: int + type: + description: Type of the task. + returned: on success + type: str + upid: + description: UPID of the task. + returned: on success + type: str + user: + description: User that owns the task. + returned: on success + type: str + endtime: + description: Endtime of the task. + returned: on success, can be absent + type: int + status: + description: Status of the task. + returned: on success, can be absent + type: str + failed: + description: If the task failed. + returned: when status is defined + type: bool msg: - description: Short message. - returned: on failure - type: str - sample: 'Task: UPID:xyz:xyz does not exist on node: proxmoxnode' -''' + description: Short message. + returned: on failure + type: str + sample: 'Task: UPID:xyz:xyz does not exist on node: proxmoxnode' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.proxmox import ( diff --git a/plugins/modules/proxmox_template.py b/plugins/modules/proxmox_template.py index 876e8a6847f..c994eff1f83 100644 --- a/plugins/modules/proxmox_template.py +++ b/plugins/modules/proxmox_template.py @@ -9,12 +9,11 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox_template short_description: Management of OS templates in Proxmox VE cluster description: - - allows you to upload/delete templates in Proxmox VE cluster + - Allows you to upload/delete templates in Proxmox VE cluster. attributes: check_mode: support: none @@ -34,7 +33,7 @@ type: path url: description: - - URL to file to download + - URL to file to download. - Exactly one of O(src) or O(url) is required for O(state=present). type: str version_added: 10.1.0 @@ -68,7 +67,7 @@ default: false state: description: - - Indicate desired state of the template. + - Indicate desired state of the template. type: str choices: ['present', 'absent'] default: present @@ -80,9 +79,9 @@ - community.general.proxmox.actiongroup_proxmox - community.general.proxmox.documentation - community.general.attributes -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Upload new openvz template with minimal options community.general.proxmox_template: node: uk-mc02 @@ -148,7 +147,7 @@ storage: local content_type: vztmpl template: ubuntu-20.04-standard_20.04-1_amd64.tar.gz -''' +""" import os import time diff --git a/plugins/modules/proxmox_user_info.py b/plugins/modules/proxmox_user_info.py index 8680dec7ca5..a8da1ee30ac 100644 --- a/plugins/modules/proxmox_user_info.py +++ b/plugins/modules/proxmox_user_info.py @@ -9,13 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: proxmox_user_info short_description: Retrieve information about one or more Proxmox VE users version_added: 1.3.0 description: - - Retrieve information about one or more Proxmox VE users + - Retrieve information about one or more Proxmox VE users. attributes: action_group: version_added: 9.0.0 @@ -40,9 +39,9 @@ - community.general.proxmox.documentation - community.general.attributes - community.general.attributes.info_module -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List existing users community.general.proxmox_user_info: api_host: helldorado @@ -82,84 +81,84 @@ user: admin domain: pve register: proxmox_user_admin -''' +""" -RETURN = ''' +RETURN = r""" proxmox_users: - description: List of users. - returned: always, but can be empty - type: list - elements: dict - contains: - comment: - description: Short description of the user. - returned: on success - type: str - domain: - description: User's authentication realm, also the right part of the user ID. - returned: on success - type: str - email: - description: User's email address. - returned: on success - type: str - enabled: - description: User's account state. - returned: on success - type: bool - expire: - description: Expiration date in seconds since EPOCH. Zero means no expiration. - returned: on success - type: int - firstname: - description: User's first name. - returned: on success - type: str - groups: - description: List of groups which the user is a member of. - returned: on success - type: list - elements: str - keys: - description: User's two factor authentication keys. - returned: on success - type: str - lastname: - description: User's last name. - returned: on success - type: str - tokens: - description: List of API tokens associated to the user. - returned: on success - type: list - elements: dict - contains: - comment: - description: Short description of the token. - returned: on success - type: str - expire: - description: Expiration date in seconds since EPOCH. Zero means no expiration. - returned: on success - type: int - privsep: - description: Describe if the API token is further restricted with ACLs or is fully privileged. - returned: on success - type: bool - tokenid: - description: Token name. - returned: on success - type: str - user: - description: User's login name, also the left part of the user ID. - returned: on success - type: str - userid: - description: Proxmox user ID, represented as user@realm. - returned: on success - type: str -''' + description: List of users. + returned: always, but can be empty + type: list + elements: dict + contains: + comment: + description: Short description of the user. + returned: on success + type: str + domain: + description: User's authentication realm, also the right part of the user ID. + returned: on success + type: str + email: + description: User's email address. + returned: on success + type: str + enabled: + description: User's account state. + returned: on success + type: bool + expire: + description: Expiration date in seconds since EPOCH. Zero means no expiration. + returned: on success + type: int + firstname: + description: User's first name. + returned: on success + type: str + groups: + description: List of groups which the user is a member of. + returned: on success + type: list + elements: str + keys: + description: User's two factor authentication keys. + returned: on success + type: str + lastname: + description: User's last name. + returned: on success + type: str + tokens: + description: List of API tokens associated to the user. + returned: on success + type: list + elements: dict + contains: + comment: + description: Short description of the token. + returned: on success + type: str + expire: + description: Expiration date in seconds since EPOCH. Zero means no expiration. + returned: on success + type: int + privsep: + description: Describe if the API token is further restricted with ACLs or is fully privileged. + returned: on success + type: bool + tokenid: + description: Token name. + returned: on success + type: str + user: + description: User's login name, also the left part of the user ID. + returned: on success + type: str + userid: + description: Proxmox user ID, represented as user@realm. + returned: on success + type: str +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/proxmox_vm_info.py b/plugins/modules/proxmox_vm_info.py index e10b9dff6f4..36ddea9db8f 100644 --- a/plugins/modules/proxmox_vm_info.py +++ b/plugins/modules/proxmox_vm_info.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: proxmox_vm_info short_description: Retrieve information about one or more Proxmox VE virtual machines version_added: 7.2.0 @@ -71,7 +70,7 @@ - community.general.attributes.info_module """ -EXAMPLES = """ +EXAMPLES = r""" - name: List all existing virtual machines on node community.general.proxmox_vm_info: api_host: proxmoxhost @@ -108,7 +107,7 @@ config: current """ -RETURN = """ +RETURN = r""" proxmox_vms: description: List of virtual machines. returned: on success diff --git a/plugins/modules/pubnub_blocks.py b/plugins/modules/pubnub_blocks.py index 34098873a1e..598b6b5af3c 100644 --- a/plugins/modules/pubnub_blocks.py +++ b/plugins/modules/pubnub_blocks.py @@ -14,15 +14,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pubnub_blocks short_description: PubNub blocks management module description: - - "This module allows Ansible to interface with the PubNub BLOCKS - infrastructure by providing the following operations: create / remove, - start / stop and rename for blocks and create / modify / remove for event - handlers." + - 'This module allows Ansible to interface with the PubNub BLOCKS infrastructure by providing the following operations: create / remove, start + / stop and rename for blocks and create / modify / remove for event handlers.' author: - PubNub (@pubnub) - Sergey Mamontov (@parfeon) @@ -39,38 +36,33 @@ email: description: - Email from account for which new session should be started. - - "Not required if O(cache) contains result of previous module call (in - same play)." + - Not required if O(cache) contains result of previous module call (in same play). required: false type: str default: '' password: description: - Password which match to account to which specified O(email) belong. - - "Not required if O(cache) contains result of previous module call (in - same play)." + - Not required if O(cache) contains result of previous module call (in same play). required: false type: str default: '' cache: - description: > - In case if single play use blocks management module few times it is - preferred to enabled 'caching' by making previous module to share - gathered artifacts and pass them to this parameter. + description: >- + In case if single play use blocks management module few times it is preferred to enabled 'caching' by making previous module to share gathered + artifacts and pass them to this parameter. required: false type: dict default: {} account: description: - - "Name of PubNub account for from which O(application) will be used to - manage blocks." - - "User's account will be used if value not set or empty." + - Name of PubNub account for from which O(application) will be used to manage blocks. + - User's account will be used if value not set or empty. type: str default: '' application: description: - - "Name of target PubNub application for which blocks configuration on - specific O(keyset) will be done." + - Name of target PubNub application for which blocks configuration on specific O(keyset) will be done. type: str required: true keyset: @@ -80,8 +72,7 @@ required: true state: description: - - "Intended block state after event handlers creation / update process - will be completed." + - Intended block state after event handlers creation / update process will be completed. required: false default: 'present' choices: ['started', 'stopped', 'present', 'absent'] @@ -93,55 +84,45 @@ type: str description: description: - - Short block description which will be later visible on - admin.pubnub.com. Used only if block doesn't exists and won't change - description for existing block. + - Short block description which will be later visible on admin.pubnub.com. Used only if block doesn't exists and won't change description + for existing block. required: false type: str event_handlers: description: - - "List of event handlers which should be updated for specified block - O(name)." - - "Each entry for new event handler should contain: C(name), C(src), - C(channels), C(event). C(name) used as event handler name which can be - used later to make changes to it." + - List of event handlers which should be updated for specified block O(name). + - 'Each entry for new event handler should contain: V(name), V(src), V(channels), V(event). V(name) used as event handler name which can + be used later to make changes to it.' - C(src) is full path to file with event handler code. - - "C(channels) is name of channel from which event handler is waiting - for events." - - "C(event) is type of event which is able to trigger event handler: - C(js-before-publish), C(js-after-publish), C(js-after-presence)." - - "Each entry for existing handlers should contain C(name) (so target - handler can be identified). Rest parameters (C(src), C(channels) and - C(event)) can be added if changes required for them." - - "It is possible to rename event handler by adding C(changes) key to - event handler payload and pass dictionary, which will contain single key - C(name), where new name should be passed." - - "To remove particular event handler it is possible to set C(state) for - it to C(absent) and it will be removed." + - V(channels) is name of channel from which event handler is waiting for events. + - 'V(event) is type of event which is able to trigger event handler: V(js-before-publish), V(js-after-publish), V(js-after-presence).' + - Each entry for existing handlers should contain C(name) (so target handler can be identified). Rest parameters (C(src), C(channels) and + C(event)) can be added if changes required for them. + - It is possible to rename event handler by adding C(changes) key to event handler payload and pass dictionary, which will contain single + key C(name), where new name should be passed. + - To remove particular event handler it is possible to set C(state) for it to C(absent) and it will be removed. required: false default: [] type: list elements: dict changes: description: - - "List of fields which should be changed by block itself (doesn't - affect any event handlers)." - - "Possible options for change is: O(name)." + - List of fields which should be changed by block itself (does not affect any event handlers). + - 'Possible options for change is: O(name).' required: false default: {} type: dict validate_certs: description: - - "This key allow to try skip certificates check when performing REST API - calls. Sometimes host may have issues with certificates on it and this - will cause problems to call PubNub REST API." + - This key allow to try skip certificates check when performing REST API calls. Sometimes host may have issues with certificates on it and + this will cause problems to call PubNub REST API. - If check should be ignored V(false) should be passed to this parameter. required: false default: true type: bool -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Event handler create example. - name: Create single event handler community.general.pubnub_blocks: @@ -151,8 +132,7 @@ keyset: '{{ keyset_name }}' name: '{{ block_name }}' event_handlers: - - - src: '{{ path_to_handler_source }}' + - src: '{{ path_to_handler_source }}' name: '{{ handler_name }}' event: 'js-before-publish' channels: '{{ handler_channel }}' @@ -166,8 +146,7 @@ keyset: '{{ keyset_name }}' name: '{{ block_name }}' event_handlers: - - - name: '{{ handler_name }}' + - name: '{{ handler_name }}' event: 'js-after-publish' # Stop block and event handlers. @@ -199,8 +178,7 @@ name: '{{ block_name }}' state: present event_handlers: - - - src: '{{ path_to_handler_1_source }}' + - src: '{{ path_to_handler_1_source }}' name: '{{ event_handler_1_name }}' channels: '{{ event_handler_1_channel }}' event: 'js-before-publish' @@ -213,8 +191,7 @@ name: '{{ block_name }}' state: present event_handlers: - - - src: '{{ path_to_handler_2_source }}' + - src: '{{ path_to_handler_2_source }}' name: '{{ event_handler_2_name }}' channels: '{{ event_handler_2_channel }}' event: 'js-before-publish' @@ -226,17 +203,16 @@ keyset: '{{ keyset_name }}' name: '{{ block_name }}' state: started -''' +""" -RETURN = ''' +RETURN = r""" module_cache: description: - - Cached account information. In case if with single play module - used few times it is better to pass cached data to next module calls to speed + - Cached account information. In case if with single play module used few times it is better to pass cached data to next module calls to speed up process. type: dict returned: always -''' +""" import copy import os diff --git a/plugins/modules/pulp_repo.py b/plugins/modules/pulp_repo.py index c581fa31870..142c5f66f4c 100644 --- a/plugins/modules/pulp_repo.py +++ b/plugins/modules/pulp_repo.py @@ -10,8 +10,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pulp_repo author: "Joe Adams (@sysadmind)" short_description: Add or remove Pulp repos from a remote host @@ -35,78 +34,68 @@ type: str force_basic_auth: description: - - httplib2, the library used by the M(ansible.builtin.uri) module only sends - authentication information when a webservice responds to an initial - request with a 401 status. Since some basic auth services do not - properly send a 401, logins will fail. This option forces the sending of - the Basic authentication header upon initial request. + - C(httplib2), the library used by the M(ansible.builtin.uri) module only sends authentication information when a webservice responds to an + initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This option forces the + sending of the Basic authentication header upon initial request. type: bool default: false generate_sqlite: description: - - Boolean flag to indicate whether sqlite files should be generated during - a repository publish. + - Boolean flag to indicate whether sqlite files should be generated during a repository publish. required: false type: bool default: false feed_ca_cert: description: - - CA certificate string used to validate the feed source SSL certificate. - This can be the file content or the path to the file. + - CA certificate string used to validate the feed source SSL certificate. This can be the file content or the path to the file. type: str - aliases: [ importer_ssl_ca_cert ] + aliases: [importer_ssl_ca_cert] feed_client_cert: description: - - Certificate used as the client certificate when synchronizing the - repository. This is used to communicate authentication information to - the feed source. The value to this option must be the full path to the - certificate. The specified file may be the certificate itself or a - single file containing both the certificate and private key. This can be - the file content or the path to the file. + - Certificate used as the client certificate when synchronizing the repository. This is used to communicate authentication information to + the feed source. The value to this option must be the full path to the certificate. The specified file may be the certificate itself or + a single file containing both the certificate and private key. This can be the file content or the path to the file. type: str - aliases: [ importer_ssl_client_cert ] + aliases: [importer_ssl_client_cert] feed_client_key: description: - - Private key to the certificate specified in O(feed_client_cert), - assuming it is not included in the certificate file itself. This can be - the file content or the path to the file. + - Private key to the certificate specified in O(feed_client_cert), assuming it is not included in the certificate file itself. This can + be the file content or the path to the file. type: str - aliases: [ importer_ssl_client_key ] + aliases: [importer_ssl_client_key] name: description: - Name of the repo to add or remove. This correlates to repo-id in Pulp. required: true type: str - aliases: [ repo ] + aliases: [repo] proxy_host: description: - - Proxy url setting for the pulp repository importer. This is in the - format scheme://host. + - Proxy url setting for the pulp repository importer. This is in the format scheme://host. required: false - default: null + default: type: str proxy_port: description: - Proxy port setting for the pulp repository importer. required: false - default: null + default: type: str proxy_username: description: - Proxy username for the pulp repository importer. required: false - default: null + default: type: str proxy_password: description: - Proxy password for the pulp repository importer. required: false - default: null + default: type: str publish_distributor: description: - - Distributor to use when O(state=publish). The default is to - publish all distributors. + - Distributor to use when O(state=publish). The default is to publish all distributors. type: str pulp_host: description: @@ -124,8 +113,7 @@ type: str repoview: description: - - Whether to generate repoview files for a published repository. Setting - this to V(true) automatically activates O(generate_sqlite). + - Whether to generate repoview files for a published repository. Setting this to V(true) automatically activates O(generate_sqlite). required: false type: bool default: false @@ -141,24 +129,21 @@ default: true state: description: - - The repo state. A state of V(sync) will queue a sync of the repo. - This is asynchronous but not delayed like a scheduled sync. A state of - V(publish) will use the repository's distributor to publish the content. + - The repo state. A state of V(sync) will queue a sync of the repo. This is asynchronous but not delayed like a scheduled sync. A state + of V(publish) will use the repository's distributor to publish the content. default: present - choices: [ "present", "absent", "sync", "publish" ] + choices: ["present", "absent", "sync", "publish"] type: str url_password: description: - - The password for use in HTTP basic authentication to the pulp API. - If the O(url_username) parameter is not specified, the O(url_password) + - The password for use in HTTP basic authentication to the pulp API. If the O(url_username) parameter is not specified, the O(url_password) parameter will not be used. url_username: description: - The username for use in HTTP basic authentication to the pulp API. validate_certs: description: - - If V(false), SSL certificates will not be validated. This should only be - used on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. type: bool default: true wait_for_completion: @@ -167,14 +152,13 @@ type: bool default: false notes: - - This module can currently only create distributors and importers on rpm - repositories. Contributions to support other repo types are welcome. + - This module can currently only create distributors and importers on rpm repositories. Contributions to support other repo types are welcome. extends_documentation_fragment: - ansible.builtin.url - community.general.attributes -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a new repo with name 'my_repo' community.general.pulp_repo: name: my_repo @@ -197,15 +181,15 @@ name: my_old_repo repo_type: rpm state: absent -''' +""" -RETURN = ''' +RETURN = r""" repo: description: Name of the repo that the action was performed on. returned: success type: str sample: my_repo -''' +""" import json import os diff --git a/plugins/modules/puppet.py b/plugins/modules/puppet.py index 46326c667f4..cf4cfae47c0 100644 --- a/plugins/modules/puppet.py +++ b/plugins/modules/puppet.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: puppet short_description: Runs puppet description: @@ -66,11 +65,11 @@ version_added: 5.1.0 logdest: description: - - Where the puppet logs should go, if puppet apply is being used. - - V(all) will go to both C(console) and C(syslog). - - V(stdout) will be deprecated and replaced by C(console). + - Where the puppet logs should go, if puppet apply is being used. + - V(all) will go to both C(console) and C(syslog). + - V(stdout) will be deprecated and replaced by C(console). type: str - choices: [ all, stdout, syslog ] + choices: [all, stdout, syslog] default: stdout certname: description: @@ -94,7 +93,7 @@ type: str use_srv_records: description: - - Toggles use_srv_records flag + - Toggles use_srv_records flag. type: bool summarize: description: @@ -103,8 +102,8 @@ default: false waitforlock: description: - - The maximum amount of time C(puppet) should wait for an already running C(puppet) agent to finish before starting. - - If a number without unit is provided, it is assumed to be a number of seconds. Allowed units are V(m) for minutes and V(h) for hours. + - The maximum amount of time C(puppet) should wait for an already running C(puppet) agent to finish before starting. + - If a number without unit is provided, it is assumed to be a number of seconds. Allowed units are V(m) for minutes and V(h) for hours. type: str version_added: 9.0.0 verbose: @@ -119,27 +118,27 @@ default: false show_diff: description: - - Whether to print file changes details + - Whether to print file changes details. type: bool default: false environment_lang: description: - The lang environment to use when running the puppet agent. - - The default value, V(C), is supported on every system, but can lead to encoding errors if UTF-8 is used in the output - - Use V(C.UTF-8) or V(en_US.UTF-8) or similar UTF-8 supporting locales in case of problems. You need to make sure - the selected locale is supported on the system the puppet agent runs on. - - Starting with community.general 9.1.0, you can use the value V(auto) and the module will - try and determine the best parseable locale to use. + - The default value, V(C), is supported on every system, but can lead to encoding errors if UTF-8 is used in the output. + - Use V(C.UTF-8) or V(en_US.UTF-8) or similar UTF-8 supporting locales in case of problems. You need to make sure the selected locale is + supported on the system the puppet agent runs on. + - Starting with community.general 9.1.0, you can use the value V(auto) and the module will try and determine the best parseable locale to + use. type: str default: C version_added: 8.6.0 requirements: -- puppet + - puppet author: -- Monty Taylor (@emonty) -''' + - Monty Taylor (@emonty) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Run puppet agent and fail if anything goes wrong community.general.puppet: @@ -162,10 +161,10 @@ - name: Run puppet using a specific tags community.general.puppet: tags: - - update - - nginx + - update + - nginx skip_tags: - - service + - service - name: Wait 30 seconds for any current puppet runs to finish community.general.puppet: @@ -184,7 +183,7 @@ modulepath: /etc/puppet/modules:/opt/stack/puppet-modules:/usr/share/openstack-puppet/modules logdest: all manifest: /var/lib/example/puppet_step_config.pp -''' +""" import json import os diff --git a/plugins/modules/pushbullet.py b/plugins/modules/pushbullet.py index 673f30cc367..bfb84899bac 100644 --- a/plugins/modules/pushbullet.py +++ b/plugins/modules/pushbullet.py @@ -9,65 +9,59 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: "Willy Barro (@willybarro)" -requirements: [ pushbullet.py ] +requirements: [pushbullet.py] module: pushbullet short_description: Sends notifications to Pushbullet description: - - This module sends push notifications via Pushbullet to channels or devices. + - This module sends push notifications through Pushbullet to channels or devices. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - api_key: - type: str - description: - - Push bullet API token - required: true - channel: - type: str - description: - - The channel TAG you wish to broadcast a push notification, - as seen on the "My Channels" > "Edit your channel" at - Pushbullet page. - device: - type: str - description: - - The device NAME you wish to send a push notification, - as seen on the Pushbullet main page. - push_type: - type: str - description: - - Thing you wish to push. - default: note - choices: [ "note", "link" ] - title: - type: str - description: - - Title of the notification. - required: true - body: - type: str - description: - - Body of the notification, e.g. Details of the fault you're alerting. - url: - type: str - description: - - URL field, used when O(push_type=link). - + api_key: + type: str + description: + - Push bullet API token. + required: true + channel: + type: str + description: + - The channel TAG you wish to broadcast a push notification, as seen on the "My Channels" > "Edit your channel" at Pushbullet page. + device: + type: str + description: + - The device NAME you wish to send a push notification, as seen on the Pushbullet main page. + push_type: + type: str + description: + - Thing you wish to push. + default: note + choices: ["note", "link"] + title: + type: str + description: + - Title of the notification. + required: true + body: + type: str + description: + - Body of the notification, for example details of the fault you're alerting. + url: + type: str + description: + - URL field, used when O(push_type=link). notes: - - Requires pushbullet.py Python package on the remote host. - You can install it via pip with ($ pip install pushbullet.py). - See U(https://github.com/randomchars/pushbullet.py) -''' + - Requires C(pushbullet.py) Python package on the remote host. You can install it through C(pip) with C($ pip install pushbullet.py). + - See U(https://github.com/randomchars/pushbullet.py). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Sends a push notification to a device community.general.pushbullet: api_key: "ABC123abc123ABC123abc123ABC123ab" @@ -94,7 +88,7 @@ channel: my-awesome-channel title: ALERT! Signup service is down body: Error rate on signup service is over 90% for more than 2 minutes -''' +""" import traceback diff --git a/plugins/modules/pushover.py b/plugins/modules/pushover.py index f5493731fa9..ae57411531a 100644 --- a/plugins/modules/pushover.py +++ b/plugins/modules/pushover.py @@ -9,16 +9,13 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pushover -short_description: Send notifications via U(https://pushover.net) +short_description: Send notifications through U(https://pushover.net) description: - - Send notifications via pushover, to subscriber list of devices, and email - addresses. Requires pushover app on devices. + - Send notifications through pushover to subscriber list of devices and email addresses. Requires pushover app on devices. notes: - - You will require a pushover.net account to use this module. But no account - is required to receive messages. + - You will require a pushover.net account to use this module. But no account is required to receive messages. extends_documentation_fragment: - community.general.attributes attributes: @@ -53,7 +50,7 @@ - Message priority (see U(https://pushover.net) for details). required: false default: '0' - choices: [ '-2', '-1', '0', '1', '2' ] + choices: ['-2', '-1', '0', '1', '2'] device: type: str description: @@ -64,9 +61,9 @@ author: - "Jim Richardson (@weaselkeeper)" - "Bernd Arnold (@wopfel)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Send notifications via pushover.net community.general.pushover: msg: '{{ inventory_hostname }} is acting strange ...' @@ -90,7 +87,7 @@ user_key: baa5fe97f2c5ab3ca8f0bb59 device: admins-iPhone delegate_to: localhost -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.six.moves.urllib.parse import urlencode diff --git a/plugins/modules/python_requirements_info.py b/plugins/modules/python_requirements_info.py index 8e709440d1c..17432583e32 100644 --- a/plugins/modules/python_requirements_info.py +++ b/plugins/modules/python_requirements_info.py @@ -7,7 +7,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: python_requirements_info short_description: Show python path and assert dependency versions description: @@ -19,18 +19,17 @@ dependencies: type: list elements: str - description: > - A list of version-likes or module names to check for installation. - Supported operators: <, >, <=, >=, or ==. The bare module name like - V(ansible), the module with a specific version like V(boto3==1.6.1), or a - partial version like V(requests>2) are all valid specifications. + description: + - 'A list of version-likes or module names to check for installation. Supported operators: C(<), C(>), C(<=), C(>=), or C(==).' + - The bare module name like V(ansible), the module with a specific version like V(boto3==1.6.1), + or a partial version like V(requests>2) are all valid specifications. default: [] author: - Will Thames (@willthames) - Ryan Scott Brown (@ryansb) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Show python lib/site paths community.general.python_requirements_info: @@ -39,21 +38,21 @@ dependencies: - boto3>1.6 - botocore<2 -''' +""" -RETURN = ''' +RETURN = r""" python: - description: path to python version used + description: Path to the Python interpreter used. returned: always type: str sample: /usr/local/opt/python@2/bin/python2.7 python_version: - description: version of python + description: Version of Python. returned: always type: str sample: "2.7.15 (default, May 1 2018, 16:44:08)\n[GCC 4.2.1 Compatible Apple LLVM 9.1.0 (clang-902.0.39.1)]" python_version_info: - description: breakdown version of python + description: Breakdown version of Python. returned: always type: dict contains: @@ -84,25 +83,26 @@ sample: 0 version_added: 4.2.0 python_system_path: - description: List of paths python is looking for modules in + description: List of paths Python is looking for modules in. returned: always type: list sample: - /usr/local/opt/python@2/site-packages/ - /usr/lib/python/site-packages/ valid: - description: A dictionary of dependencies that matched their desired versions. If no version was specified, then RV(ignore:desired) will be null + description: A dictionary of dependencies that matched their desired versions. If no version was specified, then RV(ignore:desired) will be + null. returned: always type: dict sample: boto3: - desired: null + desired: installed: 1.7.60 botocore: desired: botocore<2 installed: 1.10.60 mismatched: - description: A dictionary of dependencies that did not satisfy the desired version + description: A dictionary of dependencies that did not satisfy the desired version. returned: always type: dict sample: @@ -110,13 +110,13 @@ desired: botocore>2 installed: 1.10.60 not_found: - description: A list of packages that could not be imported at all, and are not installed + description: A list of packages that could not be imported at all, and are not installed. returned: always type: list sample: - boto4 - requests -''' +""" import re import sys From 53bda89fee0daf149f7c03cef13b1e24ff2b1cce Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Wed, 25 Dec 2024 22:32:18 +1300 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: IamLunchbox <56757745+IamLunchbox@users.noreply.github.com> --- plugins/modules/proxmox_backup.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py index 71dbf07325b..b14dd529e81 100644 --- a/plugins/modules/proxmox_backup.py +++ b/plugins/modules/proxmox_backup.py @@ -107,9 +107,9 @@ type: bool retention: description: - - Use custom retention options instead of those from the default cluster configuration (which is usually V("keep-all")). + - Use custom retention options instead of those from the default cluster configuration (which is usually V("keep-all=1")). - Always requires Datastore.Allocate permission at the storage endpoint. - - Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore, if an existing backup should be deleted target + - Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore, if an existing backup should be deleted due to your specified timeframe. - Deleting requires C(Datastore.Modify) or C(Datastore.Prune) permissions on the backup storage. type: str From 3af17887b2df5befa5828be3e9594768acb2985c Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 26 Dec 2024 11:28:58 +1300 Subject: [PATCH 3/4] Update plugins/modules/pushbullet.py Co-authored-by: Felix Fontein --- plugins/modules/pushbullet.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/pushbullet.py b/plugins/modules/pushbullet.py index bfb84899bac..7ce6e6fd721 100644 --- a/plugins/modules/pushbullet.py +++ b/plugins/modules/pushbullet.py @@ -51,7 +51,7 @@ body: type: str description: - - Body of the notification, for example details of the fault you're alerting. + - Body of the notification, for example details of the fault you are alerting. url: type: str description: From b7168cd7683e6a95888a5f059d4aaeeab2eaf76c Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 26 Dec 2024 11:29:11 +1300 Subject: [PATCH 4/4] Update plugins/modules/pushbullet.py Co-authored-by: Felix Fontein --- plugins/modules/pushbullet.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/pushbullet.py b/plugins/modules/pushbullet.py index 7ce6e6fd721..32a659922a8 100644 --- a/plugins/modules/pushbullet.py +++ b/plugins/modules/pushbullet.py @@ -57,7 +57,7 @@ description: - URL field, used when O(push_type=link). notes: - - Requires C(pushbullet.py) Python package on the remote host. You can install it through C(pip) with C($ pip install pushbullet.py). + - Requires C(pushbullet.py) Python package on the remote host. You can install it through C(pip) with C(pip install pushbullet.py). - See U(https://github.com/randomchars/pushbullet.py). """