From 2a2a9661d919d26f125bf8fcb4fdfef36162825c Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Sat, 28 Dec 2024 02:29:15 +1300 Subject: [PATCH] [ab]*.py: normalize docs (#9421) * [ab]*.py: normalize docs * Update plugins/modules/atomic_image.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- plugins/modules/aerospike_migrations.py | 204 ++-- plugins/modules/airbrake_deployment.py | 31 +- plugins/modules/aix_devices.py | 35 +- plugins/modules/aix_filesystem.py | 25 +- plugins/modules/aix_inittab.py | 87 +- plugins/modules/aix_lvg.py | 35 +- plugins/modules/aix_lvol.py | 47 +- plugins/modules/alerta_customer.py | 13 +- plugins/modules/ali_instance.py | 995 +++++++++--------- plugins/modules/ali_instance_info.py | 567 +++++----- plugins/modules/alternatives.py | 44 +- plugins/modules/android_sdk.py | 69 +- plugins/modules/ansible_galaxy_install.py | 90 +- plugins/modules/apache2_mod_proxy.py | 211 ++-- plugins/modules/apache2_module.py | 144 ++- plugins/modules/apk.py | 44 +- plugins/modules/apt_repo.py | 29 +- plugins/modules/apt_rpm.py | 33 +- plugins/modules/archive.py | 113 +- plugins/modules/atomic_container.py | 114 +- plugins/modules/atomic_host.py | 52 +- plugins/modules/atomic_image.py | 82 +- plugins/modules/awall.py | 25 +- plugins/modules/beadm.py | 153 ++- plugins/modules/bearychat.py | 27 +- plugins/modules/bigpanda.py | 26 +- plugins/modules/bitbucket_access_key.py | 15 +- .../modules/bitbucket_pipeline_key_pair.py | 15 +- .../modules/bitbucket_pipeline_known_host.py | 18 +- .../modules/bitbucket_pipeline_variable.py | 19 +- plugins/modules/bootc_manage.py | 46 +- plugins/modules/bower.py | 30 +- plugins/modules/btrfs_info.py | 113 +- plugins/modules/btrfs_subvolume.py | 266 +++-- plugins/modules/bundler.py | 59 +- plugins/modules/bzr.py | 68 +- 36 files changed, 1931 insertions(+), 2013 deletions(-) diff --git a/plugins/modules/aerospike_migrations.py b/plugins/modules/aerospike_migrations.py index 1eee5b1a2f..69da5c879a 100644 --- a/plugins/modules/aerospike_migrations.py +++ b/plugins/modules/aerospike_migrations.py @@ -9,15 +9,13 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: aerospike_migrations short_description: Check or wait for migrations between nodes description: - - This can be used to check for migrations in a cluster. - This makes it easy to do a rolling upgrade/update on Aerospike nodes. - - If waiting for migrations is not desired, simply just poll until - port 3000 if available or asinfo -v status returns ok + - This can be used to check for migrations in a cluster. This makes it easy to do a rolling upgrade/update on Aerospike + nodes. + - If waiting for migrations is not desired, simply just poll until port 3000 if available or C(asinfo -v status) returns ok. author: "Albert Autin (@Alb0t)" extends_documentation_fragment: - community.general.attributes @@ -27,92 +25,84 @@ attributes: diff_mode: support: none options: - host: - description: - - Which host do we use as seed for info connection - required: false - type: str - default: localhost - port: - description: - - Which port to connect to Aerospike on (service port) - required: false - type: int - default: 3000 - connect_timeout: - description: - - How long to try to connect before giving up (milliseconds) - required: false - type: int - default: 1000 - consecutive_good_checks: - description: - - How many times should the cluster report "no migrations" - consecutively before returning OK back to ansible? - required: false - type: int - default: 3 - sleep_between_checks: - description: - - How long to sleep between each check (seconds). - required: false - type: int - default: 60 - tries_limit: - description: - - How many times do we poll before giving up and failing? - default: 300 - required: false - type: int - local_only: - description: - - Do you wish to only check for migrations on the local node - before returning, or do you want all nodes in the cluster - to finish before returning? - required: true - type: bool - min_cluster_size: - description: - - Check will return bad until cluster size is met - or until tries is exhausted - required: false - type: int - default: 1 - fail_on_cluster_change: - description: - - Fail if the cluster key changes - if something else is changing the cluster, we may want to fail - required: false - type: bool - default: true - migrate_tx_key: - description: - - The metric key used to determine if we have tx migrations - remaining. Changeable due to backwards compatibility. - required: false - type: str - default: migrate_tx_partitions_remaining - migrate_rx_key: - description: - - The metric key used to determine if we have rx migrations - remaining. Changeable due to backwards compatibility. - required: false - type: str - default: migrate_rx_partitions_remaining - target_cluster_size: - description: - - When all aerospike builds in the cluster are greater than - version 4.3, then the C(cluster-stable) info command will be used. - Inside this command, you can optionally specify what the target - cluster size is - but it is not necessary. You can still rely on - min_cluster_size if you don't want to use this option. - - If this option is specified on a cluster that has at least 1 - host <4.3 then it will be ignored until the min version reaches - 4.3. - required: false - type: int -''' -EXAMPLES = ''' + host: + description: + - Which host do we use as seed for info connection. + required: false + type: str + default: localhost + port: + description: + - Which port to connect to Aerospike on (service port). + required: false + type: int + default: 3000 + connect_timeout: + description: + - How long to try to connect before giving up (milliseconds). + required: false + type: int + default: 1000 + consecutive_good_checks: + description: + - How many times should the cluster report "no migrations" consecutively before returning OK back to ansible? + required: false + type: int + default: 3 + sleep_between_checks: + description: + - How long to sleep between each check (seconds). + required: false + type: int + default: 60 + tries_limit: + description: + - How many times do we poll before giving up and failing? + default: 300 + required: false + type: int + local_only: + description: + - Do you wish to only check for migrations on the local node before returning, or do you want all nodes in the cluster + to finish before returning? + required: true + type: bool + min_cluster_size: + description: + - Check will return bad until cluster size is met or until tries is exhausted. + required: false + type: int + default: 1 + fail_on_cluster_change: + description: + - Fail if the cluster key changes if something else is changing the cluster, we may want to fail. + required: false + type: bool + default: true + migrate_tx_key: + description: + - The metric key used to determine if we have tx migrations remaining. Changeable due to backwards compatibility. + required: false + type: str + default: migrate_tx_partitions_remaining + migrate_rx_key: + description: + - The metric key used to determine if we have rx migrations remaining. Changeable due to backwards compatibility. + required: false + type: str + default: migrate_rx_partitions_remaining + target_cluster_size: + description: + - When all aerospike builds in the cluster are greater than version 4.3, then the C(cluster-stable) info command will + be used. Inside this command, you can optionally specify what the target cluster size is - but it is not necessary. + You can still rely on O(min_cluster_size) if you do not want to use this option. + - If this option is specified on a cluster that has at least one host <4.3 then it will be ignored until the min version + reaches 4.3. + required: false + type: int +""" + +EXAMPLES = r""" # check for migrations on local node - name: Wait for migrations on local node before proceeding community.general.aerospike_migrations: @@ -132,13 +122,13 @@ EXAMPLES = ''' - name: Install dependencies ansible.builtin.apt: name: - - python - - python-pip - - python-setuptools + - python + - python-pip + - python-setuptools state: latest - name: Setup aerospike ansible.builtin.pip: - name: aerospike + name: aerospike # check for migrations every (sleep_between_checks) # If at least (consecutive_good_checks) checks come back OK in a row, then return OK. # Will exit if any exception, which can be caused by bad nodes, @@ -147,13 +137,13 @@ EXAMPLES = ''' # Tries Limit * Sleep Between Checks * delay * retries - name: Wait for aerospike migrations community.general.aerospike_migrations: - local_only: true - sleep_between_checks: 1 - tries_limit: 5 - consecutive_good_checks: 3 - fail_on_cluster_change: true - min_cluster_size: 3 - target_cluster_size: 4 + local_only: true + sleep_between_checks: 1 + tries_limit: 5 + consecutive_good_checks: 3 + fail_on_cluster_change: true + min_cluster_size: 3 + target_cluster_size: 4 register: migrations_check until: migrations_check is succeeded changed_when: false @@ -161,14 +151,14 @@ EXAMPLES = ''' retries: 120 - name: Another thing ansible.builtin.shell: | - echo foo + echo foo - name: Reboot ansible.builtin.reboot: -''' +""" -RETURN = ''' +RETURN = r""" # Returns only a success/failure result. Changed is always false. -''' +""" import traceback diff --git a/plugins/modules/airbrake_deployment.py b/plugins/modules/airbrake_deployment.py index bad1b2c9d4..3a93a16ee0 100644 --- a/plugins/modules/airbrake_deployment.py +++ b/plugins/modules/airbrake_deployment.py @@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: airbrake_deployment author: -- "Bruce Pennypacker (@bpennypacker)" -- "Patrick Humpal (@phumpal)" + - "Bruce Pennypacker (@bpennypacker)" + - "Patrick Humpal (@phumpal)" short_description: Notify airbrake about app deployments description: - - Notify airbrake about app deployments (see U(https://airbrake.io/docs/api/#deploys-v4)). + - Notify airbrake about app deployments (see U(https://airbrake.io/docs/api/#deploys-v4)). extends_documentation_fragment: - community.general.attributes attributes: @@ -28,7 +27,7 @@ attributes: options: project_id: description: - - Airbrake PROJECT_ID + - Airbrake PROJECT_ID. required: true type: str version_added: '0.2.0' @@ -40,27 +39,27 @@ options: version_added: '0.2.0' environment: description: - - The airbrake environment name, typically 'production', 'staging', etc. + - The airbrake environment name, typically v(production), V(staging), and so on. required: true type: str user: description: - - The username of the person doing the deployment + - The username of the person doing the deployment. required: false type: str repo: description: - - URL of the project repository + - URL of the project repository. required: false type: str revision: description: - - A hash, number, tag, or other identifier showing what revision from version control was deployed + - A hash, number, tag, or other identifier showing what revision from version control was deployed. required: false type: str version: description: - - A string identifying what version was deployed + - A string identifying what version was deployed. required: false type: str version_added: '1.0.0' @@ -72,16 +71,16 @@ options: type: str validate_certs: description: - - If V(false), SSL certificates for the target url will not be validated. This should only be used - on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates for the target url will not be validated. This should only be used on personally controlled + sites using self-signed certificates. required: false default: true type: bool requirements: [] -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Notify airbrake about an app deployment community.general.airbrake_deployment: project_id: '12345' @@ -98,7 +97,7 @@ EXAMPLES = ''' user: ansible revision: 'e54dd3a01f2c421b558ef33b5f79db936e2dcf15' version: '0.2.0' -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url diff --git a/plugins/modules/aix_devices.py b/plugins/modules/aix_devices.py index a0f3cf48d9..68dbfb72d2 100644 --- a/plugins/modules/aix_devices.py +++ b/plugins/modules/aix_devices.py @@ -8,14 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: -- Kairo Araujo (@kairoaraujo) + - Kairo Araujo (@kairoaraujo) module: aix_devices short_description: Manages AIX devices description: -- This module discovers, defines, removes and modifies attributes of AIX devices. + - This module discovers, defines, removes and modifies attributes of AIX devices. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,35 +25,35 @@ attributes: options: attributes: description: - - A list of device attributes. + - A list of device attributes. type: dict device: description: - - The name of the device. - - V(all) is valid to rescan C(available) all devices (AIX cfgmgr command). + - The name of the device. + - V(all) is valid to rescan C(available) all devices (AIX C(cfgmgr) command). type: str force: description: - - Forces action. + - Forces action. type: bool default: false recursive: description: - - Removes or defines a device and children devices. + - Removes or defines a device and children devices. type: bool default: false state: description: - - Controls the device state. - - V(available) (alias V(present)) rescan a specific device or all devices (when O(device) is not specified). - - V(removed) (alias V(absent) removes a device. - - V(defined) changes device to Defined state. + - Controls the device state. + - V(available) (alias V(present)) rescan a specific device or all devices (when O(device) is not specified). + - V(removed) (alias V(absent) removes a device. + - V(defined) changes device to Defined state. type: str - choices: [ available, defined, removed ] + choices: [available, defined, removed] default: available -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Scan new devices community.general.aix_devices: device: all @@ -126,9 +125,9 @@ EXAMPLES = r''' attributes: alias4: 10.0.0.100,255.255.255.0 state: available -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/aix_filesystem.py b/plugins/modules/aix_filesystem.py index 4a3775c672..8934d583ff 100644 --- a/plugins/modules/aix_filesystem.py +++ b/plugins/modules/aix_filesystem.py @@ -9,15 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - Kairo Araujo (@kairoaraujo) module: aix_filesystem short_description: Configure LVM and NFS file systems for AIX description: - - This module creates, removes, mount and unmount LVM and NFS file system for - AIX using C(/etc/filesystems). + - This module creates, removes, mount and unmount LVM and NFS file system for AIX using C(/etc/filesystems). - For LVM file systems is possible to resize a file system. extends_documentation_fragment: - community.general.attributes @@ -60,7 +58,7 @@ options: description: - Set file system permissions. V(rw) (read-write) or V(ro) (read-only). type: str - choices: [ ro, rw ] + choices: [ro, rw] default: rw mount_group: description: @@ -84,9 +82,8 @@ options: description: - Specifies the file system size. - For already V(present) it will be resized. - - 512-byte blocks, Megabytes or Gigabytes. If the value has M specified - it will be in Megabytes. If the value has G specified it will be in - Gigabytes. + - 512-byte blocks, Megabytes or Gigabytes. If the value has M specified it will be in Megabytes. If the value has G + specified it will be in Gigabytes. - If no M or G the value will be 512-byte blocks. - If "+" is specified in begin of value, the value will be added. - If "-" is specified in begin of value, the value will be removed. @@ -101,7 +98,7 @@ options: - V(mounted) checks if the file system is mounted or mount the file system. - V(unmounted) check if the file system is unmounted or unmount the file system. type: str - choices: [ absent, mounted, present, unmounted ] + choices: [absent, mounted, present, unmounted] default: present vg: description: @@ -109,9 +106,9 @@ options: type: str notes: - For more O(attributes), please check "crfs" AIX manual. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create filesystem in a previously defined logical volume. community.general.aix_filesystem: device: testlv @@ -166,9 +163,9 @@ EXAMPLES = r''' filesystem: /newfs rm_mount_point: true state: absent -''' +""" -RETURN = r''' +RETURN = r""" changed: description: Return changed for aix_filesystems actions as true or false. returned: always @@ -177,7 +174,7 @@ msg: description: Return message regarding the action. returned: always type: str -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils._mount import ismount diff --git a/plugins/modules/aix_inittab.py b/plugins/modules/aix_inittab.py index 79336bab8d..0c32f91e7f 100644 --- a/plugins/modules/aix_inittab.py +++ b/plugins/modules/aix_inittab.py @@ -8,16 +8,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - - Joris Weijters (@molekuul) + - Joris Weijters (@molekuul) module: aix_inittab -short_description: Manages the inittab on AIX +short_description: Manages the C(inittab) on AIX description: - - Manages the inittab on AIX. + - Manages the C(inittab) on AIX. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -26,56 +25,56 @@ attributes: options: name: description: - - Name of the inittab entry. + - Name of the C(inittab) entry. type: str required: true - aliases: [ service ] + aliases: [service] runlevel: description: - - Runlevel of the entry. + - Runlevel of the entry. type: str required: true action: description: - - Action what the init has to do with this entry. + - Action what the init has to do with this entry. type: str choices: - - boot - - bootwait - - hold - - initdefault - - 'off' - - once - - ondemand - - powerfail - - powerwait - - respawn - - sysinit - - wait + - boot + - bootwait + - hold + - initdefault + - 'off' + - once + - ondemand + - powerfail + - powerwait + - respawn + - sysinit + - wait command: description: - - What command has to run. + - What command has to run. type: str required: true insertafter: description: - - After which inittabline should the new entry inserted. + - After which inittabline should the new entry inserted. type: str state: description: - - Whether the entry should be present or absent in the inittab file. + - Whether the entry should be present or absent in the inittab file. type: str - choices: [ absent, present ] + choices: [absent, present] default: present notes: - The changes are persistent across reboots. - You need root rights to read or adjust the inittab with the C(lsitab), C(chitab), C(mkitab) or C(rmitab) commands. - Tested on AIX 7.1. requirements: -- itertools -''' + - itertools +""" -EXAMPLES = ''' +EXAMPLES = r""" # Add service startmyservice to the inittab, directly after service existingservice. - name: Add startmyservice to inittab community.general.aix_inittab: @@ -105,25 +104,25 @@ EXAMPLES = ''' command: echo hello state: absent become: true -''' +""" -RETURN = ''' +RETURN = r""" name: - description: Name of the adjusted inittab entry - returned: always - type: str - sample: startmyservice + description: Name of the adjusted C(inittab) entry. + returned: always + type: str + sample: startmyservice msg: - description: Action done with the inittab entry - returned: changed - type: str - sample: changed inittab entry startmyservice + description: Action done with the C(inittab) entry. + returned: changed + type: str + sample: changed inittab entry startmyservice changed: - description: Whether the inittab changed or not - returned: always - type: bool - sample: true -''' + description: Whether the C(inittab) changed or not. + returned: always + type: bool + sample: true +""" # Import necessary libraries try: diff --git a/plugins/modules/aix_lvg.py b/plugins/modules/aix_lvg.py index 2892a68ad9..29c0b7d3f9 100644 --- a/plugins/modules/aix_lvg.py +++ b/plugins/modules/aix_lvg.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - Kairo Araujo (@kairoaraujo) module: aix_lvg @@ -26,43 +25,43 @@ attributes: options: force: description: - - Force volume group creation. + - Force volume group creation. type: bool default: false pp_size: description: - - The size of the physical partition in megabytes. + - The size of the physical partition in megabytes. type: int pvs: description: - - List of comma-separated devices to use as physical devices in this volume group. - - Required when creating or extending (V(present) state) the volume group. - - If not informed reducing (V(absent) state) the volume group will be removed. + - List of comma-separated devices to use as physical devices in this volume group. + - Required when creating or extending (V(present) state) the volume group. + - If not informed reducing (V(absent) state) the volume group will be removed. type: list elements: str state: description: - - Control if the volume group exists and volume group AIX state varyonvg V(varyon) or varyoffvg V(varyoff). + - Control if the volume group exists and volume group AIX state varyonvg V(varyon) or varyoffvg V(varyoff). type: str - choices: [ absent, present, varyoff, varyon ] + choices: [absent, present, varyoff, varyon] default: present vg: description: - - The name of the volume group. + - The name of the volume group. type: str required: true vg_type: description: - - The type of the volume group. + - The type of the volume group. type: str - choices: [ big, normal, scalable ] + choices: [big, normal, scalable] default: normal notes: -- AIX will permit remove VG only if all LV/Filesystems are not busy. -- Module does not modify PP size for already present volume group. -''' + - AIX will permit remove VG only if all LV/Filesystems are not busy. + - Module does not modify PP size for already present volume group. +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a volume group datavg community.general.aix_lvg: vg: datavg @@ -86,9 +85,9 @@ EXAMPLES = r''' vg: rootvg pvs: hdisk1 state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/aix_lvol.py b/plugins/modules/aix_lvol.py index 7d0fb1ee09..5e34d0697b 100644 --- a/plugins/modules/aix_lvol.py +++ b/plugins/modules/aix_lvol.py @@ -9,10 +9,9 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - - Alain Dejoux (@adejoux) + - Alain Dejoux (@adejoux) module: aix_lvol short_description: Configure AIX LVM logical volumes description: @@ -27,58 +26,58 @@ attributes: options: vg: description: - - The volume group this logical volume is part of. + - The volume group this logical volume is part of. type: str required: true lv: description: - - The name of the logical volume. + - The name of the logical volume. type: str required: true lv_type: description: - - The type of the logical volume. + - The type of the logical volume. type: str default: jfs2 size: description: - - The size of the logical volume with one of the [MGT] units. + - The size of the logical volume with one of the [MGT] units. type: str copies: description: - - The number of copies of the logical volume. - - Maximum copies are 3. + - The number of copies of the logical volume. + - Maximum copies are 3. type: int default: 1 policy: description: - - Sets the interphysical volume allocation policy. - - V(maximum) allocates logical partitions across the maximum number of physical volumes. - - V(minimum) allocates logical partitions across the minimum number of physical volumes. + - Sets the interphysical volume allocation policy. + - V(maximum) allocates logical partitions across the maximum number of physical volumes. + - V(minimum) allocates logical partitions across the minimum number of physical volumes. type: str - choices: [ maximum, minimum ] + choices: [maximum, minimum] default: maximum state: description: - - Control if the logical volume exists. If V(present) and the - volume does not already exist then the O(size) option is required. + - Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option + is required. type: str - choices: [ absent, present ] + choices: [absent, present] default: present opts: description: - - Free-form options to be passed to the mklv command. + - Free-form options to be passed to the mklv command. type: str default: '' pvs: description: - - A list of physical volumes, for example V(hdisk1,hdisk2). + - A list of physical volumes, for example V(hdisk1,hdisk2). type: list elements: str default: [] -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a logical volume of 512M community.general.aix_lvol: vg: testvg @@ -90,7 +89,7 @@ EXAMPLES = r''' vg: testvg lv: test2lv size: 512M - pvs: [ hdisk1, hdisk2 ] + pvs: [hdisk1, hdisk2] - name: Create a logical volume of 512M mirrored community.general.aix_lvol: @@ -124,15 +123,15 @@ EXAMPLES = r''' vg: testvg lv: testlv state: absent -''' +""" -RETURN = r''' +RETURN = r""" msg: type: str description: A friendly message describing the task result. returned: always sample: Logical volume testlv created. -''' +""" import re diff --git a/plugins/modules/alerta_customer.py b/plugins/modules/alerta_customer.py index 5e1a5f86c4..fc5ce32d5c 100644 --- a/plugins/modules/alerta_customer.py +++ b/plugins/modules/alerta_customer.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: alerta_customer short_description: Manage customers in Alerta version_added: 4.8.0 @@ -18,7 +17,7 @@ description: author: Christian Wollinger (@cwollinger) seealso: - name: API documentation - description: Documentation for Alerta API + description: Documentation for Alerta API. link: https://docs.alerta.io/api/reference.html#customers extends_documentation_fragment: - community.general.attributes @@ -60,11 +59,11 @@ options: - Whether the customer should exist or not. - Both O(customer) and O(match) identify a customer that should be added or removed. type: str - choices: [ absent, present ] + choices: [absent, present] default: present -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Create customer community.general.alerta_customer: alerta_url: https://alerta.example.com @@ -83,7 +82,7 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" msg: description: - Success or failure message. diff --git a/plugins/modules/ali_instance.py b/plugins/modules/ali_instance.py index 087dc64b6d..608e1060fc 100644 --- a/plugins/modules/ali_instance.py +++ b/plugins/modules/ali_instance.py @@ -24,243 +24,240 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ali_instance -short_description: Create, Start, Stop, Restart or Terminate an Instance in ECS; Add or Remove Instance to/from a Security Group +short_description: Create, Start, Stop, Restart or Terminate an Instance in ECS; Add or Remove Instance to/from a Security + Group description: - - Create, start, stop, restart, modify or terminate ecs instances. - - Add or remove ecs instances to/from security group. + - Create, start, stop, restart, modify or terminate ECS instances. + - Add or remove ecs instances to/from security group. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - state: - description: - - The state of the instance after operating. - default: 'present' - choices: ['present', 'running', 'stopped', 'restarted', 'absent'] - type: str - availability_zone: - description: - - Aliyun availability zone ID in which to launch the instance. - If it is not specified, it will be allocated by system automatically. - aliases: ['alicloud_zone', 'zone_id'] - type: str - image_id: - description: - - Image ID used to launch instances. Required when O(state=present) and creating new ECS instances. - aliases: ['image'] - type: str - instance_type: - description: - - Instance type used to launch instances. Required when O(state=present) and creating new ECS instances. - aliases: ['type'] - type: str - security_groups: - description: - - A list of security group IDs. - aliases: ['group_ids'] - type: list - elements: str - vswitch_id: - description: - - The subnet ID in which to launch the instances (VPC). - aliases: ['subnet_id'] - type: str - instance_name: - description: - - The name of ECS instance, which is a string of 2 to 128 Chinese or English characters. It must begin with an - uppercase/lowercase letter or a Chinese character and can contain numerals, ".", "_" or "-". - It cannot begin with http:// or https://. - aliases: ['name'] - type: str + state: description: - description: - - The description of ECS instance, which is a string of 2 to 256 characters. It cannot begin with http:// or https://. - type: str - internet_charge_type: - description: - - Internet charge type of ECS instance. - default: 'PayByBandwidth' - choices: ['PayByBandwidth', 'PayByTraffic'] - type: str - max_bandwidth_in: - description: - - Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second). - default: 200 - type: int - max_bandwidth_out: - description: - - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second). - Required when O(allocate_public_ip=true). Ignored when O(allocate_public_ip=false). - default: 0 - type: int - host_name: - description: - - Instance host name. Ordered hostname is not supported. - type: str - unique_suffix: - description: - - Specifies whether to add sequential suffixes to the host_name. - The sequential suffix ranges from 001 to 999. - default: false - type: bool - version_added: '0.2.0' - password: - description: - - The password to login instance. After rebooting instances, modified password will take effect. - type: str - system_disk_category: - description: - - Category of the system disk. - default: 'cloud_efficiency' - choices: ['cloud_efficiency', 'cloud_ssd'] - type: str - system_disk_size: - description: - - Size of the system disk, in GB. The valid values are 40~500. - default: 40 - type: int - system_disk_name: - description: - - Name of the system disk. - type: str - system_disk_description: - description: - - Description of the system disk. - type: str - count: - description: - - The number of the new instance. An integer value which indicates how many instances that match O(count_tag) - should be running. Instances are either created or terminated based on this value. - default: 1 - type: int - count_tag: - description: - - O(count) determines how many instances based on a specific tag criteria should be present. - This can be expressed in multiple ways and is shown in the EXAMPLES section. - The specified count_tag must already exist or be passed in as the O(tags) option. - If it is not specified, it will be replaced by O(instance_name). - type: str - allocate_public_ip: - description: - - Whether allocate a public ip for the new instance. - default: false - aliases: [ 'assign_public_ip' ] - type: bool - instance_charge_type: - description: - - The charge type of the instance. - choices: ['PrePaid', 'PostPaid'] - default: 'PostPaid' - type: str - period: - description: - - The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid). - - The valid value are [1-9, 12, 24, 36]. - default: 1 - type: int - auto_renew: - description: - - Whether automate renew the charge of the instance. - type: bool - default: false - auto_renew_period: - description: - - The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true). - choices: [1, 2, 3, 6, 12] - type: int - instance_ids: - description: - - A list of instance ids. It is required when need to operate existing instances. - If it is specified, O(count) will lose efficacy. - type: list - elements: str - force: - description: - - Whether the current operation needs to be execute forcibly. - default: false - type: bool - tags: - description: - - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"}) - aliases: ["instance_tags"] - type: dict - version_added: '0.2.0' - purge_tags: - description: - - Delete any tags not specified in the task that are on the instance. - If True, it means you have to specify all the desired tags on each task affecting an instance. - default: false - type: bool - version_added: '0.2.0' - key_name: - description: - - The name of key pair which is used to access ECS instance in SSH. - required: false - type: str - aliases: ['keypair'] - user_data: - description: - - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance. - It only will take effect when launching the new ECS instances. - required: false - type: str - ram_role_name: - description: - - The name of the instance RAM role. - type: str - version_added: '0.2.0' - spot_price_limit: - description: - - The maximum hourly price for the preemptible instance. This parameter supports a maximum of three decimal - places and takes effect when the SpotStrategy parameter is set to SpotWithPriceLimit. - type: float - version_added: '0.2.0' - spot_strategy: - description: - - The bidding mode of the pay-as-you-go instance. This parameter is valid when InstanceChargeType is set to PostPaid. - choices: ['NoSpot', 'SpotWithPriceLimit', 'SpotAsPriceGo'] - default: 'NoSpot' - type: str - version_added: '0.2.0' - period_unit: - description: - - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid). - choices: ['Month', 'Week'] - default: 'Month' - type: str - version_added: '0.2.0' - dry_run: - description: - - Specifies whether to send a dry-run request. - - If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the - required parameters are set, and validates the request format, service permissions, and available ECS instances. - If the validation fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned. - - If O(dry_run=false), A request is sent. If the validation succeeds, the instance is created. - default: false - type: bool - version_added: '0.2.0' - include_data_disks: - description: - - Whether to change instance disks charge type when changing instance charge type. - default: true - type: bool - version_added: '0.2.0' + - The state of the instance after operating. + default: 'present' + choices: ['present', 'running', 'stopped', 'restarted', 'absent'] + type: str + availability_zone: + description: + - Aliyun availability zone ID in which to launch the instance. If it is not specified, it will be allocated by system + automatically. + aliases: ['alicloud_zone', 'zone_id'] + type: str + image_id: + description: + - Image ID used to launch instances. Required when O(state=present) and creating new ECS instances. + aliases: ['image'] + type: str + instance_type: + description: + - Instance type used to launch instances. Required when O(state=present) and creating new ECS instances. + aliases: ['type'] + type: str + security_groups: + description: + - A list of security group IDs. + aliases: ['group_ids'] + type: list + elements: str + vswitch_id: + description: + - The subnet ID in which to launch the instances (VPC). + aliases: ['subnet_id'] + type: str + instance_name: + description: + - The name of ECS instance, which is a string of 2 to 128 Chinese or English characters. It must begin with an uppercase/lowercase + letter or a Chinese character and can contain numerals, V(.), V(_) or V(-). It cannot begin with V(http://) or V(https://). + aliases: ['name'] + type: str + description: + description: + - The description of ECS instance, which is a string of 2 to 256 characters. It cannot begin with V(http://) or V(https://). + type: str + internet_charge_type: + description: + - Internet charge type of ECS instance. + default: 'PayByBandwidth' + choices: ['PayByBandwidth', 'PayByTraffic'] + type: str + max_bandwidth_in: + description: + - Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second). + default: 200 + type: int + max_bandwidth_out: + description: + - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second). Required when O(allocate_public_ip=true). + Ignored when O(allocate_public_ip=false). + default: 0 + type: int + host_name: + description: + - Instance host name. Ordered hostname is not supported. + type: str + unique_suffix: + description: + - Specifies whether to add sequential suffixes to the host_name. The sequential suffix ranges from 001 to 999. + default: false + type: bool + version_added: '0.2.0' + password: + description: + - The password to login instance. After rebooting instances, modified password will take effect. + type: str + system_disk_category: + description: + - Category of the system disk. + default: 'cloud_efficiency' + choices: ['cloud_efficiency', 'cloud_ssd'] + type: str + system_disk_size: + description: + - Size of the system disk, in GB. The valid values are V(40)~V(500). + default: 40 + type: int + system_disk_name: + description: + - Name of the system disk. + type: str + system_disk_description: + description: + - Description of the system disk. + type: str + count: + description: + - The number of the new instance. An integer value which indicates how many instances that match O(count_tag) should + be running. Instances are either created or terminated based on this value. + default: 1 + type: int + count_tag: + description: + - O(count) determines how many instances based on a specific tag criteria should be present. This can be expressed in + multiple ways and is shown in the EXAMPLES section. The specified count_tag must already exist or be passed in as + the O(tags) option. If it is not specified, it will be replaced by O(instance_name). + type: str + allocate_public_ip: + description: + - Whether allocate a public IP for the new instance. + default: false + aliases: ['assign_public_ip'] + type: bool + instance_charge_type: + description: + - The charge type of the instance. + choices: ['PrePaid', 'PostPaid'] + default: 'PostPaid' + type: str + period: + description: + - The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid). + - The valid value are [V(1-9), V(12), V(24), V(36)]. + default: 1 + type: int + auto_renew: + description: + - Whether automate renew the charge of the instance. + type: bool + default: false + auto_renew_period: + description: + - The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true). + choices: [1, 2, 3, 6, 12] + type: int + instance_ids: + description: + - A list of instance ids. It is required when need to operate existing instances. If it is specified, O(count) will + lose efficacy. + type: list + elements: str + force: + description: + - Whether the current operation needs to be execute forcibly. + default: false + type: bool + tags: + description: + - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"}). + aliases: ["instance_tags"] + type: dict + version_added: '0.2.0' + purge_tags: + description: + - Delete any tags not specified in the task that are on the instance. If V(true), it means you have to specify all the + desired tags on each task affecting an instance. + default: false + type: bool + version_added: '0.2.0' + key_name: + description: + - The name of key pair which is used to access ECS instance in SSH. + required: false + type: str + aliases: ['keypair'] + user_data: + description: + - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance. It + only will take effect when launching the new ECS instances. + required: false + type: str + ram_role_name: + description: + - The name of the instance RAM role. + type: str + version_added: '0.2.0' + spot_price_limit: + description: + - The maximum hourly price for the preemptible instance. This parameter supports a maximum of three decimal places and + takes effect when the SpotStrategy parameter is set to SpotWithPriceLimit. + type: float + version_added: '0.2.0' + spot_strategy: + description: + - The bidding mode of the pay-as-you-go instance. This parameter is valid when O(instance_charge_type=PostPaid). + choices: ['NoSpot', 'SpotWithPriceLimit', 'SpotAsPriceGo'] + default: 'NoSpot' + type: str + version_added: '0.2.0' + period_unit: + description: + - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid). + choices: ['Month', 'Week'] + default: 'Month' + type: str + version_added: '0.2.0' + dry_run: + description: + - Specifies whether to send a dry-run request. + - If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the required + parameters are set, and validates the request format, service permissions, and available ECS instances. If the validation + fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned. + - If O(dry_run=false), a request is sent. If the validation succeeds, the instance is created. + default: false + type: bool + version_added: '0.2.0' + include_data_disks: + description: + - Whether to change instance disks charge type when changing instance charge type. + default: true + type: bool + version_added: '0.2.0' author: - - "He Guimin (@xiaozhu36)" + - "He Guimin (@xiaozhu36)" requirements: - - "Python >= 3.6" - - "footmark >= 1.19.0" + - "Python >= 3.6" + - "footmark >= 1.19.0" extends_documentation_fragment: - - community.general.alicloud - - community.general.attributes -''' + - community.general.alicloud + - community.general.attributes +""" -EXAMPLES = ''' +EXAMPLES = r""" # basic provisioning example vpc network - name: Basic provisioning example hosts: localhost @@ -298,7 +295,7 @@ EXAMPLES = ''' internet_charge_type: '{{ internet_charge_type }}' max_bandwidth_out: '{{ max_bandwidth_out }}' tags: - Name: created_one + Name: created_one host_name: '{{ host_name }}' password: '{{ password }}' @@ -316,11 +313,11 @@ EXAMPLES = ''' internet_charge_type: '{{ internet_charge_type }}' max_bandwidth_out: '{{ max_bandwidth_out }}' tags: - Name: created_one - Version: 0.1 + Name: created_one + Version: 0.1 count: 2 count_tag: - Name: created_one + Name: created_one host_name: '{{ host_name }}' password: '{{ password }}' @@ -348,278 +345,278 @@ EXAMPLES = ''' alicloud_region: '{{ alicloud_region }}' instance_ids: '{{ instance_ids }}' security_groups: '{{ security_groups }}' -''' +""" -RETURN = ''' +RETURN = r""" instances: - description: List of ECS instances - returned: always - type: complex - contains: - availability_zone: - description: The availability zone of the instance is in. - returned: always - type: str - sample: cn-beijing-a - block_device_mappings: - description: Any block device mapping entries for the instance. - returned: always - type: complex - contains: - device_name: - description: The device name exposed to the instance (for example, /dev/xvda). - returned: always - type: str - sample: /dev/xvda - attach_time: - description: The time stamp when the attachment initiated. - returned: always - type: str - sample: "2018-06-25T04:08:26Z" - delete_on_termination: - description: Indicates whether the volume is deleted on instance termination. - returned: always - type: bool - sample: true - status: - description: The attachment state. - returned: always - type: str - sample: in_use - volume_id: - description: The ID of the cloud disk. - returned: always - type: str - sample: d-2zei53pjsi117y6gf9t6 - cpu: - description: The CPU core count of the instance. - returned: always - type: int - sample: 4 - creation_time: - description: The time the instance was created. - returned: always - type: str - sample: "2018-06-25T04:08Z" - description: - description: The instance description. - returned: always - type: str - sample: "my ansible instance" - eip: - description: The attribution of EIP associated with the instance. - returned: always - type: complex - contains: - allocation_id: - description: The ID of the EIP. - returned: always - type: str - sample: eip-12345 - internet_charge_type: - description: The internet charge type of the EIP. - returned: always - type: str - sample: "paybybandwidth" - ip_address: - description: EIP address. - returned: always - type: str - sample: 42.10.2.2 - expired_time: - description: The time the instance will expire. - returned: always - type: str - sample: "2099-12-31T15:59Z" - gpu: - description: The attribution of instance GPU. - returned: always - type: complex - contains: - amount: - description: The count of the GPU. - returned: always - type: int - sample: 0 - spec: - description: The specification of the GPU. - returned: always - type: str - sample: "" - host_name: - description: The host name of the instance. - returned: always - type: str - sample: iZ2zewaoZ - id: - description: Alias of instance_id. - returned: always - type: str - sample: i-abc12345 - instance_id: - description: ECS instance resource ID. - returned: always - type: str - sample: i-abc12345 - image_id: - description: The ID of the image used to launch the instance. - returned: always - type: str - sample: m-0011223344 - inner_ip_address: - description: The inner IPv4 address of the classic instance. - returned: always - type: str - sample: 10.0.0.2 - instance_charge_type: - description: The instance charge type. - returned: always - type: str - sample: PostPaid - instance_name: - description: The name of the instance. - returned: always - type: str - sample: my-ecs - instance_type: - description: The instance type of the running instance. - returned: always - type: str - sample: ecs.sn1ne.xlarge - instance_type_family: - description: The instance type family of the instance belongs. - returned: always - type: str - sample: ecs.sn1ne - internet_charge_type: - description: The billing method of the network bandwidth. - returned: always - type: str - sample: PayByBandwidth - internet_max_bandwidth_in: - description: Maximum incoming bandwidth from the internet network. - returned: always - type: int - sample: 200 - internet_max_bandwidth_out: - description: Maximum incoming bandwidth from the internet network. - returned: always - type: int - sample: 20 - io_optimized: - description: Indicates whether the instance is optimized for EBS I/O. - returned: always - type: bool - sample: false - memory: - description: Memory size of the instance. - returned: always - type: int - sample: 8192 - network_interfaces: - description: One or more network interfaces for the instance. - returned: always - type: complex - contains: - mac_address: - description: The MAC address. - returned: always - type: str - sample: "00:11:22:33:44:55" - network_interface_id: - description: The ID of the network interface. - returned: always - type: str - sample: eni-01234567 - primary_ip_address: - description: The primary IPv4 address of the network interface within the vswitch. - returned: always - type: str - sample: 10.0.0.1 - osname: - description: The operation system name of the instance owned. - returned: always - type: str - sample: CentOS - ostype: - description: The operation system type of the instance owned. - returned: always - type: str - sample: linux - private_ip_address: - description: The IPv4 address of the network interface within the subnet. - returned: always - type: str - sample: 10.0.0.1 - public_ip_address: - description: The public IPv4 address assigned to the instance or eip address - returned: always - type: str - sample: 43.0.0.1 - resource_group_id: - description: The id of the resource group to which the instance belongs. - returned: always - type: str - sample: my-ecs-group - security_groups: - description: One or more security groups for the instance. - returned: always - type: list - elements: dict - contains: - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-0123456 - group_name: - description: The name of the security group. - returned: always - type: str - sample: my-security-group - status: - description: The current status of the instance. - returned: always - type: str - sample: running - tags: - description: Any tags assigned to the instance. - returned: always - type: dict - sample: - user_data: - description: User-defined data. - returned: always - type: dict - sample: - vswitch_id: - description: The ID of the vswitch in which the instance is running. - returned: always - type: str - sample: vsw-dew00abcdef - vpc_id: - description: The ID of the VPC the instance is in. - returned: always - type: str - sample: vpc-0011223344 - spot_price_limit: - description: - - The maximum hourly price for the preemptible instance. - returned: always - type: float - sample: 0.97 - spot_strategy: - description: - - The bidding mode of the pay-as-you-go instance. + description: List of ECS instances. + returned: always + type: complex + contains: + availability_zone: + description: The availability zone of the instance is in. + returned: always + type: str + sample: cn-beijing-a + block_device_mappings: + description: Any block device mapping entries for the instance. + returned: always + type: complex + contains: + device_name: + description: The device name exposed to the instance. returned: always type: str - sample: NoSpot + sample: /dev/xvda + attach_time: + description: The time stamp when the attachment initiated. + returned: always + type: str + sample: "2018-06-25T04:08:26Z" + delete_on_termination: + description: Indicates whether the volume is deleted on instance termination. + returned: always + type: bool + sample: true + status: + description: The attachment state. + returned: always + type: str + sample: in_use + volume_id: + description: The ID of the cloud disk. + returned: always + type: str + sample: d-2zei53pjsi117y6gf9t6 + cpu: + description: The CPU core count of the instance. + returned: always + type: int + sample: 4 + creation_time: + description: The time the instance was created. + returned: always + type: str + sample: "2018-06-25T04:08Z" + description: + description: The instance description. + returned: always + type: str + sample: "my ansible instance" + eip: + description: The attribution of EIP associated with the instance. + returned: always + type: complex + contains: + allocation_id: + description: The ID of the EIP. + returned: always + type: str + sample: eip-12345 + internet_charge_type: + description: The internet charge type of the EIP. + returned: always + type: str + sample: "paybybandwidth" + ip_address: + description: EIP address. + returned: always + type: str + sample: 42.10.2.2 + expired_time: + description: The time the instance will expire. + returned: always + type: str + sample: "2099-12-31T15:59Z" + gpu: + description: The attribution of instance GPU. + returned: always + type: complex + contains: + amount: + description: The count of the GPU. + returned: always + type: int + sample: 0 + spec: + description: The specification of the GPU. + returned: always + type: str + sample: "" + host_name: + description: The host name of the instance. + returned: always + type: str + sample: iZ2zewaoZ + id: + description: Alias of instance_id. + returned: always + type: str + sample: i-abc12345 + instance_id: + description: ECS instance resource ID. + returned: always + type: str + sample: i-abc12345 + image_id: + description: The ID of the image used to launch the instance. + returned: always + type: str + sample: m-0011223344 + inner_ip_address: + description: The inner IPv4 address of the classic instance. + returned: always + type: str + sample: 10.0.0.2 + instance_charge_type: + description: The instance charge type. + returned: always + type: str + sample: PostPaid + instance_name: + description: The name of the instance. + returned: always + type: str + sample: my-ecs + instance_type: + description: The instance type of the running instance. + returned: always + type: str + sample: ecs.sn1ne.xlarge + instance_type_family: + description: The instance type family of the instance belongs. + returned: always + type: str + sample: ecs.sn1ne + internet_charge_type: + description: The billing method of the network bandwidth. + returned: always + type: str + sample: PayByBandwidth + internet_max_bandwidth_in: + description: Maximum incoming bandwidth from the internet network. + returned: always + type: int + sample: 200 + internet_max_bandwidth_out: + description: Maximum incoming bandwidth from the internet network. + returned: always + type: int + sample: 20 + io_optimized: + description: Indicates whether the instance is optimized for EBS I/O. + returned: always + type: bool + sample: false + memory: + description: Memory size of the instance. + returned: always + type: int + sample: 8192 + network_interfaces: + description: One or more network interfaces for the instance. + returned: always + type: complex + contains: + mac_address: + description: The MAC address. + returned: always + type: str + sample: "00:11:22:33:44:55" + network_interface_id: + description: The ID of the network interface. + returned: always + type: str + sample: eni-01234567 + primary_ip_address: + description: The primary IPv4 address of the network interface within the vswitch. + returned: always + type: str + sample: 10.0.0.1 + osname: + description: The operation system name of the instance owned. + returned: always + type: str + sample: CentOS + ostype: + description: The operation system type of the instance owned. + returned: always + type: str + sample: linux + private_ip_address: + description: The IPv4 address of the network interface within the subnet. + returned: always + type: str + sample: 10.0.0.1 + public_ip_address: + description: The public IPv4 address assigned to the instance or eip address. + returned: always + type: str + sample: 43.0.0.1 + resource_group_id: + description: The id of the resource group to which the instance belongs. + returned: always + type: str + sample: my-ecs-group + security_groups: + description: One or more security groups for the instance. + returned: always + type: list + elements: dict + contains: + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-0123456 + group_name: + description: The name of the security group. + returned: always + type: str + sample: my-security-group + status: + description: The current status of the instance. + returned: always + type: str + sample: running + tags: + description: Any tags assigned to the instance. + returned: always + type: dict + sample: + user_data: + description: User-defined data. + returned: always + type: dict + sample: + vswitch_id: + description: The ID of the vswitch in which the instance is running. + returned: always + type: str + sample: vsw-dew00abcdef + vpc_id: + description: The ID of the VPC the instance is in. + returned: always + type: str + sample: vpc-0011223344 + spot_price_limit: + description: + - The maximum hourly price for the preemptible instance. + returned: always + type: float + sample: 0.97 + spot_strategy: + description: + - The bidding mode of the pay-as-you-go instance. + returned: always + type: str + sample: NoSpot ids: - description: List of ECS instance IDs - returned: always - type: list - sample: [i-12345er, i-3245fs] -''' + description: List of ECS instance IDs. + returned: always + type: list + sample: [i-12345er, i-3245fs] +""" import re import time diff --git a/plugins/modules/ali_instance_info.py b/plugins/modules/ali_instance_info.py index d6a7873742..b86ce2031d 100644 --- a/plugins/modules/ali_instance_info.py +++ b/plugins/modules/ali_instance_info.py @@ -24,51 +24,48 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ali_instance_info short_description: Gather information on instances of Alibaba Cloud ECS description: - - This module fetches data from the Open API in Alicloud. - The module must be called from within the ECS instance itself. - + - This module fetches data from the Open API in Alicloud. The module must be called from within the ECS instance itself. attributes: - check_mode: - version_added: 3.3.0 + check_mode: + version_added: 3.3.0 # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix options: - name_prefix: - description: - - Use a instance name prefix to filter ecs instances. - type: str - version_added: '0.2.0' - tags: - description: - - A hash/dictionaries of instance tags. C({"key":"value"}) - aliases: ["instance_tags"] - type: dict - filters: - description: - - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be - all of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details. - Filter keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to - connect different words in one parameter. C(InstanceIds) should be a list. - C(Tag.n.Key) and C(Tag.n.Value) should be a dict and using O(tags) instead. - type: dict - version_added: '0.2.0' + name_prefix: + description: + - Use a instance name prefix to filter ECS instances. + type: str + version_added: '0.2.0' + tags: + description: + - A hash/dictionaries of instance tags. C({"key":"value"}). + aliases: ["instance_tags"] + type: dict + filters: + description: + - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be all + of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details. Filter + keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to connect + different words in one parameter. C(InstanceIds) should be a list. C(Tag.n.Key) and C(Tag.n.Value) should be a dict + and using O(tags) instead. + type: dict + version_added: '0.2.0' author: - - "He Guimin (@xiaozhu36)" + - "He Guimin (@xiaozhu36)" requirements: - - "Python >= 3.6" - - "footmark >= 1.13.0" + - "Python >= 3.6" + - "footmark >= 1.13.0" extends_documentation_fragment: - - community.general.alicloud - - community.general.attributes - - community.general.attributes.info_module -''' + - community.general.alicloud + - community.general.attributes + - community.general.attributes.info_module +""" -EXAMPLES = ''' +EXAMPLES = r""" # Fetch instances details according to setting different filters - name: Find all instances in the specified region @@ -91,261 +88,261 @@ EXAMPLES = ''' community.general.ali_instance_info: tags: Test: "add" -''' +""" -RETURN = ''' +RETURN = r""" instances: - description: List of ECS instances - returned: always - type: complex - contains: - availability_zone: - description: The availability zone of the instance is in. - returned: always - type: str - sample: cn-beijing-a - block_device_mappings: - description: Any block device mapping entries for the instance. - returned: always - type: complex - contains: - device_name: - description: The device name exposed to the instance (for example, /dev/xvda). - returned: always - type: str - sample: /dev/xvda - attach_time: - description: The time stamp when the attachment initiated. - returned: always - type: str - sample: "2018-06-25T04:08:26Z" - delete_on_termination: - description: Indicates whether the volume is deleted on instance termination. - returned: always - type: bool - sample: true - status: - description: The attachment state. - returned: always - type: str - sample: in_use - volume_id: - description: The ID of the cloud disk. - returned: always - type: str - sample: d-2zei53pjsi117y6gf9t6 - cpu: - description: The CPU core count of the instance. - returned: always - type: int - sample: 4 - creation_time: - description: The time the instance was created. - returned: always - type: str - sample: "2018-06-25T04:08Z" - description: - description: The instance description. - returned: always - type: str - sample: "my ansible instance" - eip: - description: The attribution of EIP associated with the instance. - returned: always - type: complex - contains: - allocation_id: - description: The ID of the EIP. - returned: always - type: str - sample: eip-12345 - internet_charge_type: - description: The internet charge type of the EIP. - returned: always - type: str - sample: "paybybandwidth" - ip_address: - description: EIP address. - returned: always - type: str - sample: 42.10.2.2 - expired_time: - description: The time the instance will expire. - returned: always - type: str - sample: "2099-12-31T15:59Z" - gpu: - description: The attribution of instance GPU. - returned: always - type: complex - contains: - amount: - description: The count of the GPU. - returned: always - type: int - sample: 0 - spec: - description: The specification of the GPU. - returned: always - type: str - sample: "" - host_name: - description: The host name of the instance. - returned: always - type: str - sample: iZ2zewaoZ - id: - description: Alias of instance_id. - returned: always - type: str - sample: i-abc12345 - instance_id: - description: ECS instance resource ID. - returned: always - type: str - sample: i-abc12345 - image_id: - description: The ID of the image used to launch the instance. - returned: always - type: str - sample: m-0011223344 - inner_ip_address: - description: The inner IPv4 address of the classic instance. - returned: always - type: str - sample: 10.0.0.2 - instance_charge_type: - description: The instance charge type. - returned: always - type: str - sample: PostPaid - instance_name: - description: The name of the instance. - returned: always - type: str - sample: my-ecs - instance_type_family: - description: The instance type family of the instance belongs. - returned: always - type: str - sample: ecs.sn1ne - instance_type: - description: The instance type of the running instance. - returned: always - type: str - sample: ecs.sn1ne.xlarge - internet_charge_type: - description: The billing method of the network bandwidth. - returned: always - type: str - sample: PayByBandwidth - internet_max_bandwidth_in: - description: Maximum incoming bandwidth from the internet network. - returned: always - type: int - sample: 200 - internet_max_bandwidth_out: - description: Maximum incoming bandwidth from the internet network. - returned: always - type: int - sample: 20 - io_optimized: - description: Indicates whether the instance is optimized for EBS I/O. - returned: always - type: bool - sample: false - memory: - description: Memory size of the instance. - returned: always - type: int - sample: 8192 - network_interfaces: - description: One or more network interfaces for the instance. - returned: always - type: complex - contains: - mac_address: - description: The MAC address. - returned: always - type: str - sample: "00:11:22:33:44:55" - network_interface_id: - description: The ID of the network interface. - returned: always - type: str - sample: eni-01234567 - primary_ip_address: - description: The primary IPv4 address of the network interface within the vswitch. - returned: always - type: str - sample: 10.0.0.1 - osname: - description: The operation system name of the instance owned. - returned: always - type: str - sample: CentOS - ostype: - description: The operation system type of the instance owned. - returned: always - type: str - sample: linux - private_ip_address: - description: The IPv4 address of the network interface within the subnet. - returned: always - type: str - sample: 10.0.0.1 - public_ip_address: - description: The public IPv4 address assigned to the instance or eip address - returned: always - type: str - sample: 43.0.0.1 - resource_group_id: - description: The id of the resource group to which the instance belongs. - returned: always - type: str - sample: my-ecs-group - security_groups: - description: One or more security groups for the instance. - returned: always - type: list - elements: dict - contains: - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-0123456 - group_name: - description: The name of the security group. - returned: always - type: str - sample: my-security-group + description: List of ECS instances. + returned: always + type: complex + contains: + availability_zone: + description: The availability zone of the instance is in. + returned: always + type: str + sample: cn-beijing-a + block_device_mappings: + description: Any block device mapping entries for the instance. + returned: always + type: complex + contains: + device_name: + description: The device name exposed to the instance (for example, /dev/xvda). + returned: always + type: str + sample: /dev/xvda + attach_time: + description: The time stamp when the attachment initiated. + returned: always + type: str + sample: "2018-06-25T04:08:26Z" + delete_on_termination: + description: Indicates whether the volume is deleted on instance termination. + returned: always + type: bool + sample: true status: - description: The current status of the instance. - returned: always - type: str - sample: running - tags: - description: Any tags assigned to the instance. - returned: always - type: dict - sample: - vswitch_id: - description: The ID of the vswitch in which the instance is running. - returned: always - type: str - sample: vsw-dew00abcdef - vpc_id: - description: The ID of the VPC the instance is in. - returned: always - type: str - sample: vpc-0011223344 + description: The attachment state. + returned: always + type: str + sample: in_use + volume_id: + description: The ID of the cloud disk. + returned: always + type: str + sample: d-2zei53pjsi117y6gf9t6 + cpu: + description: The CPU core count of the instance. + returned: always + type: int + sample: 4 + creation_time: + description: The time the instance was created. + returned: always + type: str + sample: "2018-06-25T04:08Z" + description: + description: The instance description. + returned: always + type: str + sample: "my ansible instance" + eip: + description: The attribution of EIP associated with the instance. + returned: always + type: complex + contains: + allocation_id: + description: The ID of the EIP. + returned: always + type: str + sample: eip-12345 + internet_charge_type: + description: The internet charge type of the EIP. + returned: always + type: str + sample: "paybybandwidth" + ip_address: + description: EIP address. + returned: always + type: str + sample: 42.10.2.2 + expired_time: + description: The time the instance will expire. + returned: always + type: str + sample: "2099-12-31T15:59Z" + gpu: + description: The attribution of instance GPU. + returned: always + type: complex + contains: + amount: + description: The count of the GPU. + returned: always + type: int + sample: 0 + spec: + description: The specification of the GPU. + returned: always + type: str + sample: "" + host_name: + description: The host name of the instance. + returned: always + type: str + sample: iZ2zewaoZ + id: + description: Alias of instance_id. + returned: always + type: str + sample: i-abc12345 + instance_id: + description: ECS instance resource ID. + returned: always + type: str + sample: i-abc12345 + image_id: + description: The ID of the image used to launch the instance. + returned: always + type: str + sample: m-0011223344 + inner_ip_address: + description: The inner IPv4 address of the classic instance. + returned: always + type: str + sample: 10.0.0.2 + instance_charge_type: + description: The instance charge type. + returned: always + type: str + sample: PostPaid + instance_name: + description: The name of the instance. + returned: always + type: str + sample: my-ecs + instance_type_family: + description: The instance type family of the instance belongs. + returned: always + type: str + sample: ecs.sn1ne + instance_type: + description: The instance type of the running instance. + returned: always + type: str + sample: ecs.sn1ne.xlarge + internet_charge_type: + description: The billing method of the network bandwidth. + returned: always + type: str + sample: PayByBandwidth + internet_max_bandwidth_in: + description: Maximum incoming bandwidth from the internet network. + returned: always + type: int + sample: 200 + internet_max_bandwidth_out: + description: Maximum incoming bandwidth from the internet network. + returned: always + type: int + sample: 20 + io_optimized: + description: Indicates whether the instance is optimized for EBS I/O. + returned: always + type: bool + sample: false + memory: + description: Memory size of the instance. + returned: always + type: int + sample: 8192 + network_interfaces: + description: One or more network interfaces for the instance. + returned: always + type: complex + contains: + mac_address: + description: The MAC address. + returned: always + type: str + sample: "00:11:22:33:44:55" + network_interface_id: + description: The ID of the network interface. + returned: always + type: str + sample: eni-01234567 + primary_ip_address: + description: The primary IPv4 address of the network interface within the vswitch. + returned: always + type: str + sample: 10.0.0.1 + osname: + description: The operation system name of the instance owned. + returned: always + type: str + sample: CentOS + ostype: + description: The operation system type of the instance owned. + returned: always + type: str + sample: linux + private_ip_address: + description: The IPv4 address of the network interface within the subnet. + returned: always + type: str + sample: 10.0.0.1 + public_ip_address: + description: The public IPv4 address assigned to the instance or EIP address. + returned: always + type: str + sample: 43.0.0.1 + resource_group_id: + description: The id of the resource group to which the instance belongs. + returned: always + type: str + sample: my-ecs-group + security_groups: + description: One or more security groups for the instance. + returned: always + type: list + elements: dict + contains: + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-0123456 + group_name: + description: The name of the security group. + returned: always + type: str + sample: my-security-group + status: + description: The current status of the instance. + returned: always + type: str + sample: running + tags: + description: Any tags assigned to the instance. + returned: always + type: dict + sample: + vswitch_id: + description: The ID of the vswitch in which the instance is running. + returned: always + type: str + sample: vsw-dew00abcdef + vpc_id: + description: The ID of the VPC the instance is in. + returned: always + type: str + sample: vpc-0011223344 ids: - description: List of ECS instance IDs - returned: always - type: list - sample: [i-12345er, i-3245fs] -''' + description: List of ECS instance IDs. + returned: always + type: list + sample: [i-12345er, i-3245fs] +""" from ansible.module_utils.basic import AnsibleModule, missing_required_lib from ansible_collections.community.general.plugins.module_utils.alicloud_ecs import ( diff --git a/plugins/modules/alternatives.py b/plugins/modules/alternatives.py index d049c82b11..c96aede225 100644 --- a/plugins/modules/alternatives.py +++ b/plugins/modules/alternatives.py @@ -11,19 +11,18 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: alternatives short_description: Manages alternative programs for common commands description: - - Manages symbolic links using the 'update-alternatives' tool. - - Useful when multiple programs are installed but provide similar functionality (e.g. different editors). + - Manages symbolic links using the C(update-alternatives) tool. + - Useful when multiple programs are installed but provide similar functionality (for example, different editors). author: - - Marius Rieder (@jiuka) - - David Wittman (@DavidWittman) - - Gabe Mulley (@mulby) + - Marius Rieder (@jiuka) + - David Wittman (@DavidWittman) + - Gabe Mulley (@mulby) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -47,8 +46,8 @@ options: link: description: - The path to the symbolic link that should point to the real executable. - - This option is always required on RHEL-based distributions. On Debian-based distributions this option is - required when the alternative O(name) is unknown to the system. + - This option is always required on RHEL-based distributions. On Debian-based distributions this option is required + when the alternative O(name) is unknown to the system. type: path priority: description: @@ -56,14 +55,14 @@ options: type: int state: description: - - V(present) - install the alternative (if not already installed), but do - not set it as the currently selected alternative for the group. - - V(selected) - install the alternative (if not already installed), and - set it as the currently selected alternative for the group. - - V(auto) - install the alternative (if not already installed), and - set the group to auto mode. Added in community.general 5.1.0. + - V(present) - install the alternative (if not already installed), but do not set it as the currently selected alternative + for the group. + - V(selected) - install the alternative (if not already installed), and set it as the currently selected alternative + for the group. + - V(auto) - install the alternative (if not already installed), and set the group to auto mode. Added in community.general + 5.1.0. - V(absent) - removes the alternative. Added in community.general 5.1.0. - choices: [ present, selected, auto, absent ] + choices: [present, selected, auto, absent] default: selected type: str version_added: 4.8.0 @@ -71,8 +70,7 @@ options: description: - A list of subcommands. - Each subcommand needs a name, a link and a path parameter. - - Subcommands are also named 'slaves' or 'followers', depending on the version - of alternatives. + - Subcommands are also named C(slaves) or C(followers), depending on the version of C(alternatives). type: list elements: dict aliases: ['slaves'] @@ -93,10 +91,10 @@ options: type: path required: true version_added: 5.1.0 -requirements: [ update-alternatives ] -''' +requirements: [update-alternatives] +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Correct java version selected community.general.alternatives: name: java @@ -143,7 +141,7 @@ EXAMPLES = r''' - name: keytool link: /usr/bin/keytool path: /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/keytool -''' +""" import os import re diff --git a/plugins/modules/android_sdk.py b/plugins/modules/android_sdk.py index 9851a84fc2..c36c22eb0c 100644 --- a/plugins/modules/android_sdk.py +++ b/plugins/modules/android_sdk.py @@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: android_sdk short_description: Manages Android SDK packages description: - - Manages Android SDK packages. - - Allows installation from different channels (stable, beta, dev, canary). - - Allows installation of packages to a non-default SDK root directory. + - Manages Android SDK packages. + - Allows installation from different channels (stable, beta, dev, canary). + - Allows installation of packages to a non-default SDK root directory. author: Stanislav Shamilov (@shamilovstas) extends_documentation_fragment: - community.general.attributes @@ -29,8 +28,8 @@ version_added: 10.2.0 options: accept_licenses: description: - - If this is set to B(true), the module will try to accept license prompts generated by C(sdkmanager) during - package installation. Otherwise, every license prompt will be rejected. + - If this is set to V(true), the module will try to accept license prompts generated by C(sdkmanager) during package + installation. Otherwise, every license prompt will be rejected. type: bool default: false name: @@ -50,8 +49,8 @@ options: type: str sdk_root: description: - - Provides path for an alternative directory to install Android SDK packages to. By default, all packages - are installed to the directory where C(sdkmanager) is installed. + - Provides path for an alternative directory to install Android SDK packages to. By default, all packages are installed + to the directory where C(sdkmanager) is installed. type: path channel: description: @@ -63,27 +62,25 @@ requirements: - C(java) >= 17 - C(sdkmanager) Command line tool for installing Android SDK packages. notes: - - For some of the packages installed by C(sdkmanager) is it necessary to accept licenses. Usually it is done through - command line prompt in a form of a Y/N question when a licensed package is requested to be installed. If there are - several packages requested for installation and at least two of them belong to different licenses, the C(sdkmanager) - tool will prompt for these licenses in a loop. - In order to install packages, the module must be able to answer these license prompts. Currently, it is only - possible to answer one license prompt at a time, meaning that instead of installing multiple packages as a single - invocation of the C(sdkmanager --install) command, it will be done by executing the command independently for each - package. This makes sure that at most only one license prompt will need to be answered. - At the time of writing this module, a C(sdkmanager)'s package may belong to at most one license type that needs to - be accepted. However, if this is changes in the future, the module may hang as there might be more prompts generated - by the C(sdkmanager) tool which the module will not be able to answer. If this is the case, file an issue and in the - meantime, consider accepting all the licenses in advance, as it is described in the C(sdkmanager) - L(documentation,https://developer.android.com/tools/sdkmanager#accept-licenses), for instance, using the - M(ansible.builtin.command) module. + - For some of the packages installed by C(sdkmanager) is it necessary to accept licenses. Usually it is done through command + line prompt in a form of a Y/N question when a licensed package is requested to be installed. If there are several packages + requested for installation and at least two of them belong to different licenses, the C(sdkmanager) tool will prompt for + these licenses in a loop. In order to install packages, the module must be able to answer these license prompts. Currently, + it is only possible to answer one license prompt at a time, meaning that instead of installing multiple packages as a + single invocation of the C(sdkmanager --install) command, it will be done by executing the command independently for each + package. This makes sure that at most only one license prompt will need to be answered. At the time of writing this module, + a C(sdkmanager)'s package may belong to at most one license type that needs to be accepted. However, if this changes + in the future, the module may hang as there might be more prompts generated by the C(sdkmanager) tool which the module + will not be able to answer. If this becomes the case, file an issue and in the meantime, consider accepting all the licenses + in advance, as it is described in the C(sdkmanager) L(documentation,https://developer.android.com/tools/sdkmanager#accept-licenses), + for instance, using the M(ansible.builtin.command) module. seealso: - name: sdkmanager tool documentation description: Detailed information of how to install and use sdkmanager command line tool. link: https://developer.android.com/tools/sdkmanager -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Install build-tools;34.0.0 community.general.android_sdk: name: build-tools;34.0.0 @@ -122,21 +119,21 @@ EXAMPLES = r''' accept_licenses: true state: present channel: canary -''' +""" -RETURN = r''' +RETURN = r""" installed: - description: a list of packages that have been installed - returned: when packages have changed - type: list - sample: ['build-tools;34.0.0', 'platform-tools'] + description: A list of packages that have been installed. + returned: when packages have changed + type: list + sample: ['build-tools;34.0.0', 'platform-tools'] removed: - description: a list of packages that have been removed - returned: when packages have changed - type: list - sample: ['build-tools;34.0.0', 'platform-tools'] -''' + description: A list of packages that have been removed. + returned: when packages have changed + type: list + sample: ['build-tools;34.0.0', 'platform-tools'] +""" from ansible_collections.community.general.plugins.module_utils.mh.module_helper import StateModuleHelper from ansible_collections.community.general.plugins.module_utils.android_sdkmanager import Package, AndroidSdkManager diff --git a/plugins/modules/ansible_galaxy_install.py b/plugins/modules/ansible_galaxy_install.py index ea35b3afc0..ad055dfa14 100644 --- a/plugins/modules/ansible_galaxy_install.py +++ b/plugins/modules/ansible_galaxy_install.py @@ -8,30 +8,27 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: ansible_galaxy_install author: -- "Alexei Znamensky (@russoz)" + - "Alexei Znamensky (@russoz)" short_description: Install Ansible roles or collections using ansible-galaxy version_added: 3.5.0 description: -- This module allows the installation of Ansible collections or roles using C(ansible-galaxy). + - This module allows the installation of Ansible collections or roles using C(ansible-galaxy). notes: -- Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0. -- > - The module will try and run using the C(C.UTF-8) locale. - If that fails, it will try C(en_US.UTF-8). - If that one also fails, the module will fail. + - Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0. + - The module will try and run using the C(C.UTF-8) locale. If that fails, it will try C(en_US.UTF-8). If that one also fails, + the module will fail. seealso: -- name: C(ansible-galaxy) command manual page - description: Manual page for the command. - link: https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html + - name: C(ansible-galaxy) command manual page + description: Manual page for the command. + link: https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html requirements: -- ansible-core 2.11 or newer + - ansible-core 2.11 or newer extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -40,63 +37,59 @@ attributes: options: state: description: - - > - If O(state=present) then the collection or role will be installed. - Note that the collections and roles are not updated with this option. - - > - Currently the O(state=latest) is ignored unless O(type=collection), and it will - ensure the collection is installed and updated to the latest available version. - - Please note that O(force=true) can be used to perform upgrade regardless of O(type). + - If O(state=present) then the collection or role will be installed. Note that the collections and roles are not updated + with this option. + - Currently the O(state=latest) is ignored unless O(type=collection), and it will ensure the collection is installed + and updated to the latest available version. + - Please note that O(force=true) can be used to perform upgrade regardless of O(type). type: str choices: [present, latest] default: present version_added: 9.1.0 type: description: - - The type of installation performed by C(ansible-galaxy). - - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections. - - "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices." + - The type of installation performed by C(ansible-galaxy). + - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections. + - 'Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three + choices.' type: str choices: [collection, role, both] required: true name: description: - - Name of the collection or role being installed. - - > - Versions can be specified with C(ansible-galaxy) usual formats. - For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0). - - O(name) and O(requirements_file) are mutually exclusive. + - Name of the collection or role being installed. + - Versions can be specified with C(ansible-galaxy) usual formats. For example, the collection V(community.docker:1.6.1) + or the role V(ansistrano.deploy,3.8.0). + - O(name) and O(requirements_file) are mutually exclusive. type: str requirements_file: description: - - Path to a file containing a list of requirements to be installed. - - It works for O(type) equals to V(collection) and V(role). - - O(name) and O(requirements_file) are mutually exclusive. + - Path to a file containing a list of requirements to be installed. + - It works for O(type) equals to V(collection) and V(role). + - O(name) and O(requirements_file) are mutually exclusive. type: path dest: description: - - The path to the directory containing your collections or roles, according to the value of O(type). - - > - Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file) - contains both roles and collections and O(dest) is specified. + - The path to the directory containing your collections or roles, according to the value of O(type). + - Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file) contains + both roles and collections and O(dest) is specified. type: path no_deps: description: - - Refrain from installing dependencies. + - Refrain from installing dependencies. version_added: 4.5.0 type: bool default: false force: description: - - Force overwriting existing roles and/or collections. - - It can be used for upgrading, but the module output will always report C(changed=true). - - Using O(force=true) is mandatory when downgrading. + - Force overwriting existing roles and/or collections. + - It can be used for upgrading, but the module output will always report C(changed=true). + - Using O(force=true) is mandatory when downgrading. type: bool default: false """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Install collection community.network community.general.ansible_galaxy_install: type: collection @@ -120,8 +113,7 @@ EXAMPLES = """ force: true """ -RETURN = """ ---- +RETURN = r""" type: description: The value of the O(type) parameter. type: str @@ -144,8 +136,8 @@ force: returned: always installed_roles: description: - - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path. - - If O(name) is specified, returns that role name and the version installed per path. + - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path. + - If O(name) is specified, returns that role name and the version installed per path. type: dict returned: always when installing roles contains: @@ -160,13 +152,13 @@ installed_roles: ansistrano.deploy: 3.8.0 installed_collections: description: - - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path. - - If O(name) is specified, returns that collection name and the version installed per path. + - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path. + - If O(name) is specified, returns that collection name and the version installed per path. type: dict returned: always when installing collections contains: "": - description: Collections and versions for that path + description: Collections and versions for that path. type: dict sample: /home/az/.ansible/collections/ansible_collections: diff --git a/plugins/modules/apache2_mod_proxy.py b/plugins/modules/apache2_mod_proxy.py index 786089d13c..f70294bad1 100644 --- a/plugins/modules/apache2_mod_proxy.py +++ b/plugins/modules/apache2_mod_proxy.py @@ -9,19 +9,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: apache2_mod_proxy author: Olivier Boukili (@oboukili) short_description: Set and/or get members' attributes of an Apache httpd 2.4 mod_proxy balancer pool description: - - Set and/or get members' attributes of an Apache httpd 2.4 mod_proxy balancer - pool, using HTTP POST and GET requests. The httpd mod_proxy balancer-member - status page has to be enabled and accessible, as this module relies on parsing - this page. This module supports ansible check_mode, and requires BeautifulSoup - python module. + - Set and/or get members' attributes of an Apache httpd 2.4 mod_proxy balancer pool, using HTTP POST and GET requests. The + httpd mod_proxy balancer-member status page has to be enabled and accessible, as this module relies on parsing this page. extends_documentation_fragment: - community.general.attributes +requirements: + - Python package C(BeautifulSoup). attributes: check_mode: support: full @@ -31,28 +29,25 @@ options: balancer_url_suffix: type: str description: - - Suffix of the balancer pool url required to access the balancer pool - status page (e.g. balancer_vhost[:port]/balancer_url_suffix). + - Suffix of the balancer pool URL required to access the balancer pool status page (for example V(balancer_vhost[:port]/balancer_url_suffix)). default: /balancer-manager/ balancer_vhost: type: str description: - - (ipv4|ipv6|fqdn):port of the Apache httpd 2.4 mod_proxy balancer pool. + - (IPv4|IPv6|FQDN):port of the Apache httpd 2.4 mod_proxy balancer pool. required: true member_host: type: str description: - - (ipv4|ipv6|fqdn) of the balancer member to get or to set attributes to. - Port number is autodetected and should not be specified here. - If undefined, apache2_mod_proxy module will return a members list of - dictionaries of all the current balancer pool members' attributes. + - (IPv4|IPv6|FQDN) of the balancer member to get or to set attributes to. Port number is autodetected and should not + be specified here. If undefined, apache2_mod_proxy module will return a members list of dictionaries of all the current + balancer pool members' attributes. state: type: str description: - - Desired state of the member host. - (absent|disabled),drained,hot_standby,ignore_errors can be - simultaneously invoked by separating them with a comma (e.g. state=drained,ignore_errors). - - 'Accepted state values: ["present", "absent", "enabled", "disabled", "drained", "hot_standby", "ignore_errors"]' + - Desired state of the member host. (absent|disabled),drained,hot_standby,ignore_errors can be simultaneously invoked + by separating them with a comma (for example V(state=drained,ignore_errors)). + - 'Accepted state values: [V(present), V(absent), V(enabled), V(disabled), V(drained), V(hot_standby), V(ignore_errors)].' tls: description: - Use https to access balancer management page. @@ -63,9 +58,9 @@ options: - Validate ssl/tls certificates. type: bool default: true -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get all current balancer pool members attributes community.general.apache2_mod_proxy: balancer_vhost: 10.0.0.2 @@ -110,98 +105,98 @@ EXAMPLES = ''' member_host: '{{ member.host }}' state: absent delegate_to: myloadbalancernode -''' +""" -RETURN = ''' +RETURN = r""" member: - description: specific balancer member information dictionary, returned when apache2_mod_proxy module is invoked with member_host parameter. - type: dict - returned: success - sample: - {"attributes": - {"Busy": "0", - "Elected": "42", - "Factor": "1", - "From": "136K", - "Load": "0", - "Route": null, - "RouteRedir": null, - "Set": "0", - "Status": "Init Ok ", - "To": " 47K", - "Worker URL": null - }, - "balancer_url": "http://10.10.0.2/balancer-manager/", - "host": "10.10.0.20", - "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b", - "path": "/ws", - "port": 8080, - "protocol": "http", - "status": { - "disabled": false, - "drained": false, - "hot_standby": false, - "ignore_errors": false - } + description: specific balancer member information dictionary, returned when apache2_mod_proxy module is invoked with C(member_host) parameter. + type: dict + returned: success + sample: + {"attributes": + {"Busy": "0", + "Elected": "42", + "Factor": "1", + "From": "136K", + "Load": "0", + "Route": null, + "RouteRedir": null, + "Set": "0", + "Status": "Init Ok ", + "To": " 47K", + "Worker URL": null + }, + "balancer_url": "http://10.10.0.2/balancer-manager/", + "host": "10.10.0.20", + "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b", + "path": "/ws", + "port": 8080, + "protocol": "http", + "status": { + "disabled": false, + "drained": false, + "hot_standby": false, + "ignore_errors": false } + } members: - description: list of member (defined above) dictionaries, returned when apache2_mod_proxy is invoked with no member_host and state args. - returned: success - type: list - sample: - [{"attributes": { - "Busy": "0", - "Elected": "42", - "Factor": "1", - "From": "136K", - "Load": "0", - "Route": null, - "RouteRedir": null, - "Set": "0", - "Status": "Init Ok ", - "To": " 47K", - "Worker URL": null - }, - "balancer_url": "http://10.10.0.2/balancer-manager/", - "host": "10.10.0.20", - "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b", - "path": "/ws", - "port": 8080, - "protocol": "http", - "status": { - "disabled": false, - "drained": false, - "hot_standby": false, - "ignore_errors": false - } - }, - {"attributes": { - "Busy": "0", - "Elected": "42", - "Factor": "1", - "From": "136K", - "Load": "0", - "Route": null, - "RouteRedir": null, - "Set": "0", - "Status": "Init Ok ", - "To": " 47K", - "Worker URL": null - }, - "balancer_url": "http://10.10.0.2/balancer-manager/", - "host": "10.10.0.21", - "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.21:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b", - "path": "/ws", - "port": 8080, - "protocol": "http", - "status": { - "disabled": false, - "drained": false, - "hot_standby": false, - "ignore_errors": false} - } - ] -''' + description: list of member (defined above) dictionaries, returned when apache2_mod_proxy is invoked with no C(member_host) and state args. + returned: success + type: list + sample: + [{"attributes": { + "Busy": "0", + "Elected": "42", + "Factor": "1", + "From": "136K", + "Load": "0", + "Route": null, + "RouteRedir": null, + "Set": "0", + "Status": "Init Ok ", + "To": " 47K", + "Worker URL": null + }, + "balancer_url": "http://10.10.0.2/balancer-manager/", + "host": "10.10.0.20", + "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b", + "path": "/ws", + "port": 8080, + "protocol": "http", + "status": { + "disabled": false, + "drained": false, + "hot_standby": false, + "ignore_errors": false + } + }, + {"attributes": { + "Busy": "0", + "Elected": "42", + "Factor": "1", + "From": "136K", + "Load": "0", + "Route": null, + "RouteRedir": null, + "Set": "0", + "Status": "Init Ok ", + "To": " 47K", + "Worker URL": null + }, + "balancer_url": "http://10.10.0.2/balancer-manager/", + "host": "10.10.0.21", + "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.21:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b", + "path": "/ws", + "port": 8080, + "protocol": "http", + "status": { + "disabled": false, + "drained": false, + "hot_standby": false, + "ignore_errors": false} + } + ] +""" import re import traceback diff --git a/plugins/modules/apache2_module.py b/plugins/modules/apache2_module.py index a9fd72b24f..cacb870ee0 100644 --- a/plugins/modules/apache2_module.py +++ b/plugins/modules/apache2_module.py @@ -9,66 +9,64 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: apache2_module author: - - Christian Berendt (@berendt) - - Ralf Hertel (@n0trax) - - Robin Roth (@robinro) + - Christian Berendt (@berendt) + - Ralf Hertel (@n0trax) + - Robin Roth (@robinro) short_description: Enables/disables a module of the Apache2 webserver description: - - Enables or disables a specified module of the Apache2 webserver. + - Enables or disables a specified module of the Apache2 webserver. 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: - name: - type: str - description: - - Name of the module to enable/disable as given to C(a2enmod/a2dismod). - required: true - identifier: - type: str - description: - - Identifier of the module as listed by C(apache2ctl -M). - This is optional and usually determined automatically by the common convention of - appending V(_module) to O(name) as well as custom exception for popular modules. - required: false - force: - description: - - Force disabling of default modules and override Debian warnings. - required: false - type: bool - default: false - state: - type: str - description: - - Desired state of the module. - choices: ['present', 'absent'] - default: present - ignore_configcheck: - description: - - Ignore configuration checks about inconsistent module configuration. Especially for mpm_* modules. - type: bool - default: false - warn_mpm_absent: - description: - - Control the behavior of the warning process for MPM modules. - type: bool - default: true - version_added: 6.3.0 -requirements: ["a2enmod","a2dismod"] + name: + type: str + description: + - Name of the module to enable/disable as given to C(a2enmod)/C(a2dismod). + required: true + identifier: + type: str + description: + - Identifier of the module as listed by C(apache2ctl -M). This is optional and usually determined automatically by the + common convention of appending V(_module) to O(name) as well as custom exception for popular modules. + required: false + force: + description: + - Force disabling of default modules and override Debian warnings. + required: false + type: bool + default: false + state: + type: str + description: + - Desired state of the module. + choices: ['present', 'absent'] + default: present + ignore_configcheck: + description: + - Ignore configuration checks about inconsistent module configuration. Especially for mpm_* modules. + type: bool + default: false + warn_mpm_absent: + description: + - Control the behavior of the warning process for MPM modules. + type: bool + default: true + version_added: 6.3.0 +requirements: ["a2enmod", "a2dismod"] notes: - - This does not work on RedHat-based distributions. It does work on Debian- and SuSE-based distributions. - Whether it works on others depend on whether the C(a2enmod) and C(a2dismod) tools are available or not. -''' + - This does not work on RedHat-based distributions. It does work on Debian- and SuSE-based distributions. Whether it works + on others depend on whether the C(a2enmod) and C(a2dismod) tools are available or not. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Enable the Apache2 module wsgi community.general.apache2_module: state: present @@ -98,40 +96,40 @@ EXAMPLES = ''' warn_mpm_absent: false ignore_configcheck: true loop: - - module: mpm_event - state: absent - - module: mpm_prefork - state: present + - module: mpm_event + state: absent + - module: mpm_prefork + state: present - name: Enable dump_io module, which is identified as dumpio_module inside apache2 community.general.apache2_module: state: present name: dump_io identifier: dumpio_module -''' +""" -RETURN = ''' +RETURN = r""" result: - description: message about action taken - returned: always - type: str + description: Message about action taken. + returned: always + type: str warnings: - description: list of warning messages - returned: when needed - type: list + description: List of warning messages. + returned: when needed + type: list rc: - description: return code of underlying command - returned: failed - type: int + description: Return code of underlying command. + returned: failed + type: int stdout: - description: stdout of underlying command - returned: failed - type: str + description: The stdout of underlying command. + returned: failed + type: str stderr: - description: stderr of underlying command - returned: failed - type: str -''' + description: The stderr of underlying command. + returned: failed + type: str +""" import re diff --git a/plugins/modules/apk.py b/plugins/modules/apk.py index 7caefd1357..7f1f83ce56 100644 --- a/plugins/modules/apk.py +++ b/plugins/modules/apk.py @@ -12,8 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: apk short_description: Manages apk packages description: @@ -29,15 +28,15 @@ attributes: options: available: description: - - During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead of holding them) - if the currently installed package is no longer available from any repository. + - During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead + of holding them) if the currently installed package is no longer available from any repository. type: bool default: false name: description: - A package name, like V(foo), or multiple packages, like V(foo,bar). - - Do not include additional whitespace when specifying multiple packages as a string. - Prefer YAML lists over comma-separating multiple package names. + - Do not include additional whitespace when specifying multiple packages as a string. Prefer YAML lists over comma-separating + multiple package names. type: list elements: str no_cache: @@ -48,8 +47,8 @@ options: version_added: 1.0.0 repository: description: - - A package repository or multiple repositories. - Unlike with the underlying apk command, this list will override the system repositories rather than supplement them. + - A package repository or multiple repositories. Unlike with the underlying apk command, this list will override the + system repositories rather than supplement them. type: list elements: str state: @@ -59,7 +58,7 @@ options: - V(absent) ensures the package(s) is/are absent. V(removed) can be used as an alias. - V(latest) ensures the package(s) is/are present and the latest version(s). default: present - choices: [ "present", "absent", "latest", "installed", "removed" ] + choices: ["present", "absent", "latest", "installed", "removed"] type: str update_cache: description: @@ -73,17 +72,18 @@ options: default: false world: description: - - Use a custom world file when checking for explicitly installed packages. - The file is used only when a value is provided for O(name), and O(state) is set to V(present) or V(latest). + - Use a custom world file when checking for explicitly installed packages. The file is used only when a value is provided + for O(name), and O(state) is set to V(present) or V(latest). type: str default: /etc/apk/world version_added: 5.4.0 notes: - - 'O(name) and O(upgrade) are mutually exclusive.' - - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option. -''' + - O(name) and O(upgrade) are mutually exclusive. + - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly + to the O(name) option. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Update repositories and install foo package community.general.apk: name: foo @@ -157,15 +157,15 @@ EXAMPLES = ''' name: foo state: latest world: /etc/apk/world.custom -''' +""" -RETURN = ''' +RETURN = r""" packages: - description: a list of packages that have been changed - returned: when packages have changed - type: list - sample: ['package', 'other-package'] -''' + description: A list of packages that have been changed. + returned: when packages have changed + type: list + sample: ['package', 'other-package'] +""" import re # Import module snippets. diff --git a/plugins/modules/apt_repo.py b/plugins/modules/apt_repo.py index 4c82587d03..87df0064ca 100644 --- a/plugins/modules/apt_repo.py +++ b/plugins/modules/apt_repo.py @@ -9,16 +9,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: apt_repo -short_description: Manage APT repositories via apt-repo +short_description: Manage APT repositories using C(apt-repo) description: - - Manages APT repositories using apt-repo tool. - - See U(https://www.altlinux.org/Apt-repo) for details about apt-repo + - Manages APT repositories using C(apt-repo) tool. + - See U(https://www.altlinux.org/Apt-repo) for details about C(apt-repo). notes: - - This module works on ALT based distros. - - Does NOT support checkmode, due to a limitation in apt-repo tool. + - This module works on ALT based distros. + - Does NOT support checkmode, due to a limitation in C(apt-repo) tool. extends_documentation_fragment: - community.general.attributes attributes: @@ -35,13 +34,13 @@ options: state: description: - Indicates the desired repository state. - choices: [ absent, present ] + choices: [absent, present] default: present type: str remove_others: description: - - Remove other then added repositories - - Used if O(state=present) + - Remove other then added repositories. + - Used if O(state=present). type: bool default: false update: @@ -50,10 +49,10 @@ options: type: bool default: false author: -- Mikhail Gordeev (@obirvalger) -''' + - Mikhail Gordeev (@obirvalger) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Remove all repositories community.general.apt_repo: repo: all @@ -70,9 +69,9 @@ EXAMPLES = ''' repo: copy:///space/ALT/Sisyphus state: present update: true -''' +""" -RETURN = ''' # ''' +RETURN = """ # """ import os diff --git a/plugins/modules/apt_rpm.py b/plugins/modules/apt_rpm.py index 3a0b6d805f..5a5ba57faf 100644 --- a/plugins/modules/apt_rpm.py +++ b/plugins/modules/apt_rpm.py @@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: apt_rpm short_description: APT-RPM package manager description: @@ -28,18 +27,16 @@ options: package: description: - List of packages to install, upgrade, or remove. - - Since community.general 8.0.0, may include paths to local C(.rpm) files - if O(state=installed) or O(state=present), requires C(rpm) python - module. - aliases: [ name, pkg ] + - Since community.general 8.0.0, may include paths to local C(.rpm) files if O(state=installed) or O(state=present), + requires C(rpm) Python module. + aliases: [name, pkg] type: list elements: str state: description: - Indicates the desired package state. - - Please note that V(present) and V(installed) are equivalent to V(latest) right now. - This will change in the future. To simply ensure that a package is installed, without upgrading - it, use the V(present_not_latest) state. + - Please note that V(present) and V(installed) are equivalent to V(latest) right now. This will change in the future. + To simply ensure that a package is installed, without upgrading it, use the V(present_not_latest) state. - The states V(latest) and V(present_not_latest) have been added in community.general 8.6.0. choices: - absent @@ -52,14 +49,15 @@ options: type: str update_cache: description: - - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a separate step. + - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as + a separate step. - Default is not to update the cache. type: bool default: false clean: description: - - Run the equivalent of C(apt-get clean) to clear out the local repository of retrieved package files. It removes everything but - the lock file from C(/var/cache/apt/archives/) and C(/var/cache/apt/archives/partial/). + - Run the equivalent of C(apt-get clean) to clear out the local repository of retrieved package files. It removes everything + but the lock file from C(/var/cache/apt/archives/) and C(/var/cache/apt/archives/partial/). - Can be run as part of the package installation (clean runs before install) or as a separate step. type: bool default: false @@ -77,13 +75,12 @@ options: default: false version_added: 6.5.0 requirements: - - C(rpm) python package (rpm bindings), optional. Required if O(package) - option includes local files. + - C(rpm) Python package (rpm bindings), optional. Required if O(package) option includes local files. author: -- Evgenii Terechkov (@evgkrsk) -''' + - Evgenii Terechkov (@evgkrsk) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.apt_rpm: pkg: foo @@ -122,7 +119,7 @@ EXAMPLES = ''' update_cache: true dist_upgrade: true update_kernel: true -''' +""" import os import re diff --git a/plugins/modules/archive.py b/plugins/modules/archive.py index 6784aa1ac3..4e4b6368ce 100644 --- a/plugins/modules/archive.py +++ b/plugins/modules/archive.py @@ -10,17 +10,16 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: archive short_description: Creates a compressed archive of one or more files or trees extends_documentation_fragment: - - files - - community.general.attributes + - files + - community.general.attributes description: - - Creates or extends an archive. - - The source and archive are on the remote host, and the archive I(is not) copied to the local host. - - Source files can be deleted after archival by specifying O(remove=True). + - Creates or extends an archive. + - The source and archive are on the target host, and the archive I(is not) copied to the controller host. + - Source files can be deleted after archival by specifying O(remove=True). attributes: check_mode: support: full @@ -37,17 +36,19 @@ options: description: - The type of compression to use. type: str - choices: [ bz2, gz, tar, xz, zip ] + choices: [bz2, gz, tar, xz, zip] default: gz dest: description: - The file name of the destination archive. The parent directory must exists on the remote host. - - This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list. + - This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths + in a list. - If the destination archive already exists, it will be truncated and overwritten. type: path exclude_path: description: - - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob expansion. + - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob + expansion. - Use O(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the O(path) list. type: list elements: path @@ -72,18 +73,19 @@ options: type: bool default: false notes: - - Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives. - - This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives. - These are part of the Python standard library for Python 2 and 3. + - Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives. + - This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives. These are + part of the Python standard library for Python 2 and 3. requirements: - - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python 2) if using C(xz) format. + - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python + 2) if using C(xz) format. seealso: - - module: ansible.builtin.unarchive + - module: ansible.builtin.unarchive author: - - Ben Doherty (@bendoh) -''' + - Ben Doherty (@bendoh) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Compress directory /path/to/foo/ into /path/to/foo.tgz community.general.archive: path: /path/to/foo @@ -102,28 +104,28 @@ EXAMPLES = r''' - name: Create a bz2 archive of multiple files, rooted at /path community.general.archive: path: - - /path/to/foo - - /path/wong/foo + - /path/to/foo + - /path/wong/foo dest: /path/file.tar.bz2 format: bz2 - name: Create a bz2 archive of a globbed path, while excluding specific dirnames community.general.archive: path: - - /path/to/foo/* + - /path/to/foo/* dest: /path/file.tar.bz2 exclude_path: - - /path/to/foo/bar - - /path/to/foo/baz + - /path/to/foo/bar + - /path/to/foo/baz format: bz2 - name: Create a bz2 archive of a globbed path, while excluding a glob of dirnames community.general.archive: path: - - /path/to/foo/* + - /path/to/foo/* dest: /path/file.tar.bz2 exclude_path: - - /path/to/foo/ba* + - /path/to/foo/ba* format: bz2 - name: Use gzip to compress a single archive (i.e don't archive it first with tar) @@ -138,45 +140,44 @@ EXAMPLES = r''' dest: /path/file.tar.gz format: gz force_archive: true -''' +""" -RETURN = r''' +RETURN = r""" state: - description: - The state of the input O(path). - type: str - returned: always + description: The state of the input O(path). + type: str + returned: always dest_state: - description: - - The state of the O(dest) file. - - V(absent) when the file does not exist. - - V(archive) when the file is an archive. - - V(compress) when the file is compressed, but not an archive. - - V(incomplete) when the file is an archive, but some files under O(path) were not found. - type: str - returned: success - version_added: 3.4.0 + description: + - The state of the O(dest) file. + - V(absent) when the file does not exist. + - V(archive) when the file is an archive. + - V(compress) when the file is compressed, but not an archive. + - V(incomplete) when the file is an archive, but some files under O(path) were not found. + type: str + returned: success + version_added: 3.4.0 missing: - description: Any files that were missing from the source. - type: list - returned: success + description: Any files that were missing from the source. + type: list + returned: success archived: - description: Any files that were compressed or added to the archive. - type: list - returned: success + description: Any files that were compressed or added to the archive. + type: list + returned: success arcroot: - description: The archive root. - type: str - returned: always + description: The archive root. + type: str + returned: always expanded_paths: - description: The list of matching paths from paths argument. - type: list - returned: always + description: The list of matching paths from paths argument. + type: list + returned: always expanded_exclude_paths: - description: The list of matching exclude paths from the exclude_path argument. - type: list - returned: always -''' + description: The list of matching exclude paths from the exclude_path argument. + type: list + returned: always +""" import abc import bz2 diff --git a/plugins/modules/atomic_container.py b/plugins/modules/atomic_container.py index d1567c8923..dccebf83da 100644 --- a/plugins/modules/atomic_container.py +++ b/plugins/modules/atomic_container.py @@ -9,69 +9,67 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: atomic_container short_description: Manage the containers on the atomic host platform description: - - Manage the containers on the atomic host platform. - - Allows to manage the lifecycle of a container on the atomic host platform. + - Manage the containers on the atomic host platform. + - Allows to manage the lifecycle of a container on the atomic host platform. author: "Giuseppe Scrivano (@giuseppe)" -notes: - - Host should support C(atomic) command requirements: - - atomic + - atomic +notes: + - According to U(https://projectatomic.io/) the project has been sunset around 2019/2020, in favor of C(podman) and Fedora CoreOS. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none diff_mode: support: none options: - backend: - description: - - Define the backend to use for the container. - required: true - choices: ["docker", "ostree"] - type: str - name: - description: - - Name of the container. - required: true - type: str - image: - description: - - The image to use to install the container. - required: true - type: str - rootfs: - description: - - Define the rootfs of the image. - type: str - state: - description: - - State of the container. - choices: ["absent", "latest", "present", "rollback"] - default: "latest" - type: str - mode: - description: - - Define if it is an user or a system container. - choices: ["user", "system"] - type: str - values: - description: - - Values for the installation of the container. - - This option is permitted only with mode 'user' or 'system'. - - The values specified here will be used at installation time as --set arguments for atomic install. - type: list - elements: str - default: [] -''' - -EXAMPLES = r''' + backend: + description: + - Define the backend to use for the container. + required: true + choices: ["docker", "ostree"] + type: str + name: + description: + - Name of the container. + required: true + type: str + image: + description: + - The image to use to install the container. + required: true + type: str + rootfs: + description: + - Define the rootfs of the image. + type: str + state: + description: + - State of the container. + choices: ["absent", "latest", "present", "rollback"] + default: "latest" + type: str + mode: + description: + - Define if it is an user or a system container. + choices: ["user", "system"] + type: str + values: + description: + - Values for the installation of the container. + - This option is permitted only with mode 'user' or 'system'. + - The values specified here will be used at installation time as --set arguments for atomic install. + type: list + elements: str + default: [] +""" +EXAMPLES = r""" - name: Install the etcd system container community.general.atomic_container: name: etcd @@ -80,7 +78,7 @@ EXAMPLES = r''' state: latest mode: system values: - - ETCD_NAME=etcd.server + - ETCD_NAME=etcd.server - name: Uninstall the etcd system container community.general.atomic_container: @@ -89,15 +87,15 @@ EXAMPLES = r''' backend: ostree state: absent mode: system -''' +""" -RETURN = r''' +RETURN = r""" msg: - description: The command standard output - returned: always - type: str - sample: 'Using default tag: latest ...' -''' + description: The command standard output. + returned: always + type: str + sample: 'Using default tag: latest ...' +""" # import module snippets import traceback diff --git a/plugins/modules/atomic_host.py b/plugins/modules/atomic_host.py index ebb74caf16..0d43a4d467 100644 --- a/plugins/modules/atomic_host.py +++ b/plugins/modules/atomic_host.py @@ -8,37 +8,37 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: atomic_host short_description: Manage the atomic host platform description: - - Manage the atomic host platform. - - Rebooting of Atomic host platform should be done outside this module. + - Manage the atomic host platform. + - Rebooting of Atomic host platform should be done outside this module. author: -- Saravanan KR (@krsacme) + - Saravanan KR (@krsacme) notes: - - Host should be an atomic platform (verified by existence of '/run/ostree-booted' file). + - Host should be an atomic platform (verified by existence of '/run/ostree-booted' file). + - According to U(https://projectatomic.io/) the project has been sunset around 2019/2020, in favor of C(podman) and Fedora CoreOS. requirements: - atomic extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - revision: - description: - - The version number of the atomic host to be deployed. - - Providing V(latest) will upgrade to the latest available version. - default: 'latest' - aliases: [ version ] - type: str -''' + revision: + description: + - The version number of the atomic host to be deployed. + - Providing V(latest) will upgrade to the latest available version. + default: 'latest' + aliases: [version] + type: str +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Upgrade the atomic host platform to the latest version (atomic host upgrade) community.general.atomic_host: revision: latest @@ -46,15 +46,15 @@ EXAMPLES = r''' - name: Deploy a specific revision as the atomic host (atomic host deploy 23.130) community.general.atomic_host: revision: 23.130 -''' +""" -RETURN = r''' +RETURN = r""" msg: - description: The command standard output - returned: always - type: str - sample: 'Already on latest' -''' + description: The command standard output. + returned: always + type: str + sample: 'Already on latest' +""" import os import traceback diff --git a/plugins/modules/atomic_image.py b/plugins/modules/atomic_image.py index 4bd15e27ab..a251eba5a5 100644 --- a/plugins/modules/atomic_image.py +++ b/plugins/modules/atomic_image.py @@ -8,52 +8,52 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: atomic_image short_description: Manage the container images on the atomic host platform description: - - Manage the container images on the atomic host platform. - - Allows to execute the commands specified by the RUN label in the container image when present. + - Manage the container images on the atomic host platform. + - Allows to execute the commands specified by the RUN label in the container image when present. author: -- Saravanan KR (@krsacme) + - Saravanan KR (@krsacme) notes: - - Host should support C(atomic) command. + - According to U(https://projectatomic.io/) the project has been sunset around 2019/2020, in favor of C(podman) and Fedora CoreOS. requirements: - atomic extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - backend: - description: - - Define the backend where the image is pulled. - choices: [ 'docker', 'ostree' ] - type: str - name: - description: - - Name of the container image. - required: true - type: str - state: - description: - - The state of the container image. - - The state V(latest) will ensure container image is upgraded to the latest version and forcefully restart container, if running. - choices: [ 'absent', 'latest', 'present' ] - default: 'latest' - type: str - started: - description: - - Start or Stop the container. - type: bool - default: true -''' + backend: + description: + - Define the backend where the image is pulled. + choices: ['docker', 'ostree'] + type: str + name: + description: + - Name of the container image. + required: true + type: str + state: + description: + - The state of the container image. + - The state V(latest) will ensure container image is upgraded to the latest version and forcefully restart container, + if running. + choices: ['absent', 'latest', 'present'] + default: 'latest' + type: str + started: + description: + - Start or stop the container. + type: bool + default: true +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Execute the run command on rsyslog container image (atomic run rhel7/rsyslog) community.general.atomic_image: name: rhel7/rsyslog @@ -64,15 +64,15 @@ EXAMPLES = r''' name: busybox state: latest backend: ostree -''' +""" -RETURN = r''' +RETURN = r""" msg: - description: The command standard output - returned: always - type: str - sample: 'Using default tag: latest ...' -''' + description: The command standard output. + returned: always + type: str + sample: 'Using default tag: latest ...' +""" import traceback from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/awall.py b/plugins/modules/awall.py index f3c2384b5b..b95f36ea8d 100644 --- a/plugins/modules/awall.py +++ b/plugins/modules/awall.py @@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: awall short_description: Manage awall policies author: Ted Trask (@tdtrask) description: - This modules allows for enable/disable/activate of C(awall) policies. - - Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files - and activates the configuration on the system. + - Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files and activates the configuration + on the system. extends_documentation_fragment: - community.general.attributes attributes: @@ -35,7 +34,7 @@ options: description: - Whether the policies should be enabled or disabled. type: str - choices: [ disabled, enabled ] + choices: [disabled, enabled] default: enabled activate: description: @@ -45,29 +44,29 @@ options: type: bool default: false notes: - - At least one of O(name) and O(activate) is required. -''' + - At least one of O(name) and O(activate) is required. +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Enable "foo" and "bar" policy community.general.awall: - name: [ foo bar ] + name: [foo bar] state: enabled - name: Disable "foo" and "bar" policy and activate new rules community.general.awall: name: - - foo - - bar + - foo + - bar state: disabled activate: false - name: Activate currently enabled firewall rules community.general.awall: activate: true -''' +""" -RETURN = ''' # ''' +RETURN = """ # """ import re from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/beadm.py b/plugins/modules/beadm.py index 8857fd8464..3d9d8ca651 100644 --- a/plugins/modules/beadm.py +++ b/plugins/modules/beadm.py @@ -9,62 +9,59 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: beadm short_description: Manage ZFS boot environments on FreeBSD/Solaris/illumos systems description: - - Create, delete or activate ZFS boot environments. - - Mount and unmount ZFS boot environments. + - Create, delete or activate ZFS boot environments. + - Mount and unmount ZFS boot environments. author: Adam Števko (@xen0l) 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: - name: - description: - - ZFS boot environment name. - type: str - required: true - aliases: [ "be" ] - snapshot: - description: - - If specified, the new boot environment will be cloned from the given - snapshot or inactive boot environment. - type: str + name: description: - description: - - Associate a description with a new boot environment. This option is - available only on Solarish platforms. - type: str - options: - description: - - Create the datasets for new BE with specific ZFS properties. - - Multiple options can be specified. - - This option is available only on Solarish platforms. - type: str - mountpoint: - description: - - Path where to mount the ZFS boot environment. - type: path - state: - description: - - Create or delete ZFS boot environment. - type: str - choices: [ absent, activated, mounted, present, unmounted ] - default: present - force: - description: - - Specifies if the unmount should be forced. - type: bool - default: false -''' + - ZFS boot environment name. + type: str + required: true + aliases: ["be"] + snapshot: + description: + - If specified, the new boot environment will be cloned from the given snapshot or inactive boot environment. + type: str + description: + description: + - Associate a description with a new boot environment. This option is available only on Solarish platforms. + type: str + options: + description: + - Create the datasets for new BE with specific ZFS properties. + - Multiple options can be specified. + - This option is available only on Solarish platforms. + type: str + mountpoint: + description: + - Path where to mount the ZFS boot environment. + type: path + state: + description: + - Create or delete ZFS boot environment. + type: str + choices: [absent, activated, mounted, present, unmounted] + default: present + force: + description: + - Specifies if the unmount should be forced. + type: bool + default: false +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create ZFS boot environment community.general.beadm: name: upgrade-be @@ -103,45 +100,45 @@ EXAMPLES = r''' community.general.beadm: name: upgrade-be state: activated -''' +""" -RETURN = r''' +RETURN = r""" name: - description: BE name - returned: always - type: str - sample: pre-upgrade + description: BE name. + returned: always + type: str + sample: pre-upgrade snapshot: - description: ZFS snapshot to create BE from - returned: always - type: str - sample: rpool/ROOT/oi-hipster@fresh + description: ZFS snapshot to create BE from. + returned: always + type: str + sample: rpool/ROOT/oi-hipster@fresh description: - description: BE description - returned: always - type: str - sample: Upgrade from 9.0 to 10.0 + description: BE description. + returned: always + type: str + sample: Upgrade from 9.0 to 10.0 options: - description: BE additional options - returned: always - type: str - sample: compression=on + description: BE additional options. + returned: always + type: str + sample: compression=on mountpoint: - description: BE mountpoint - returned: always - type: str - sample: /mnt/be + description: BE mountpoint. + returned: always + type: str + sample: /mnt/be state: - description: state of the target - returned: always - type: str - sample: present + description: State of the target. + returned: always + type: str + sample: present force: - description: If forced action is wanted - returned: always - type: bool - sample: false -''' + description: If forced action is wanted. + returned: always + type: bool + sample: false +""" import os from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/bearychat.py b/plugins/modules/bearychat.py index f52737facd..1dec1bce68 100644 --- a/plugins/modules/bearychat.py +++ b/plugins/modules/bearychat.py @@ -7,12 +7,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: bearychat short_description: Send BearyChat notifications description: - - The M(community.general.bearychat) module sends notifications to U(https://bearychat.com) - via the Incoming Robot integration. + - The M(community.general.bearychat) module sends notifications to U(https://bearychat.com) using the Incoming Robot integration. author: "Jiangge Zhang (@tonyseek)" extends_documentation_fragment: - community.general.attributes @@ -25,8 +24,7 @@ options: url: type: str description: - - BearyChat WebHook URL. This authenticates you to the bearychat - service. It looks like + - BearyChat WebHook URL. This authenticates you to the bearychat service. It looks like V(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60). required: true text: @@ -41,17 +39,16 @@ options: channel: type: str description: - - Channel to send the message to. If absent, the message goes to the - default channel selected by the O(url). + - Channel to send the message to. If absent, the message goes to the default channel selected by the O(url). attachments: type: list elements: dict description: - Define a list of attachments. For more information, see - https://github.com/bearyinnovative/bearychat-tutorial/blob/master/robots/incoming.md#attachments -''' + U(https://github.com/bearyinnovative/bearychat-tutorial/blob/master/robots/incoming.md#attachments). +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Send notification message via BearyChat local_action: module: bearychat @@ -75,12 +72,12 @@ EXAMPLES = """ - http://example.com/index.png """ -RETURN = """ +RETURN = r""" msg: - description: execution result - returned: success - type: str - sample: "OK" + description: Execution result. + returned: success + type: str + sample: "OK" """ try: diff --git a/plugins/modules/bigpanda.py b/plugins/modules/bigpanda.py index 7bde5fc1d8..071440b839 100644 --- a/plugins/modules/bigpanda.py +++ b/plugins/modules/bigpanda.py @@ -8,13 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: bigpanda author: "Hagai Kariti (@hkariti)" short_description: Notify BigPanda about deployments description: - - Notify BigPanda when deployments start and end (successfully or not). Returns a deployment object containing all the parameters for future module calls. + - Notify BigPanda when deployments start and end (successfully or not). Returns a deployment object containing all the parameters + for future module calls. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,7 +26,7 @@ options: component: type: str description: - - "The name of the component being deployed. Ex: billing" + - 'The name of the component being deployed. Ex: V(billing).' required: true aliases: ['name'] version: @@ -55,7 +55,7 @@ options: env: type: str description: - - The environment name, typically 'production', 'staging', etc. + - The environment name, typically V(production), V(staging), and so on. required: false owner: type: str @@ -75,27 +75,27 @@ options: default: "https://api.bigpanda.io" validate_certs: description: - - If V(false), SSL certificates for the target url will not be validated. This should only be used - on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates for the target url will not be validated. This should only be used on personally controlled + sites using self-signed certificates. required: false default: true type: bool deployment_message: type: str description: - - Message about the deployment. + - Message about the deployment. version_added: '0.2.0' source_system: type: str description: - - Source system used in the requests to the API + - Source system used in the requests to the API. default: ansible # informational: requirements for nodes -requirements: [ ] -''' +requirements: [] +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Notify BigPanda about a deployment community.general.bigpanda: component: myapp @@ -128,7 +128,7 @@ EXAMPLES = ''' token: '{{ deployment.token }}' state: finished delegate_to: localhost -''' +""" # =========================================== # Module execution. diff --git a/plugins/modules/bitbucket_access_key.py b/plugins/modules/bitbucket_access_key.py index 29c19b8b3d..f78f55d3bb 100644 --- a/plugins/modules/bitbucket_access_key.py +++ b/plugins/modules/bitbucket_access_key.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: bitbucket_access_key short_description: Manages Bitbucket repository access keys description: @@ -33,7 +32,7 @@ options: workspace: description: - The repository owner. - - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." + - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user). type: str required: true key: @@ -50,13 +49,13 @@ options: - Indicates desired state of the access key. type: str required: true - choices: [ absent, present ] + choices: [absent, present] notes: - Bitbucket OAuth consumer or App password should have permissions to read and administrate account repositories. - Check mode is supported. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create access key community.general.bitbucket_access_key: repository: 'bitbucket-repo' @@ -71,9 +70,9 @@ EXAMPLES = r''' workspace: bitbucket_workspace label: Bitbucket state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.source_control.bitbucket import BitbucketHelper diff --git a/plugins/modules/bitbucket_pipeline_key_pair.py b/plugins/modules/bitbucket_pipeline_key_pair.py index 3bc41c2987..e16af96867 100644 --- a/plugins/modules/bitbucket_pipeline_key_pair.py +++ b/plugins/modules/bitbucket_pipeline_key_pair.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: bitbucket_pipeline_key_pair short_description: Manages Bitbucket pipeline SSH key pair description: @@ -33,7 +32,7 @@ options: workspace: description: - The repository owner. - - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." + - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user). type: str required: true public_key: @@ -49,12 +48,12 @@ options: - Indicates desired state of the key pair. type: str required: true - choices: [ absent, present ] + choices: [absent, present] notes: - Check mode is supported. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create or update SSH key pair community.general.bitbucket_pipeline_key_pair: repository: 'bitbucket-repo' @@ -68,9 +67,9 @@ EXAMPLES = r''' repository: bitbucket-repo workspace: bitbucket_workspace state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.source_control.bitbucket import BitbucketHelper diff --git a/plugins/modules/bitbucket_pipeline_known_host.py b/plugins/modules/bitbucket_pipeline_known_host.py index 3e6c4bfbf1..f5594dc8ac 100644 --- a/plugins/modules/bitbucket_pipeline_known_host.py +++ b/plugins/modules/bitbucket_pipeline_known_host.py @@ -8,13 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: bitbucket_pipeline_known_host short_description: Manages Bitbucket pipeline known hosts description: - Manages Bitbucket pipeline known hosts under the "SSH Keys" menu. - - The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it manually. + - The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it + manually. author: - Evgeniy Krysanov (@catcombo) extends_documentation_fragment: @@ -36,7 +36,7 @@ options: workspace: description: - The repository owner. - - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." + - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user). type: str required: true name: @@ -53,12 +53,12 @@ options: - Indicates desired state of the record. type: str required: true - choices: [ absent, present ] + choices: [absent, present] notes: - Check mode is supported. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create known hosts from the list community.general.bitbucket_pipeline_known_host: repository: 'bitbucket-repo' @@ -83,9 +83,9 @@ EXAMPLES = r''' name: bitbucket.org key: '{{lookup("file", "bitbucket.pub") }}' state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ import socket diff --git a/plugins/modules/bitbucket_pipeline_variable.py b/plugins/modules/bitbucket_pipeline_variable.py index 1ff8e43753..08a1d3f1e8 100644 --- a/plugins/modules/bitbucket_pipeline_variable.py +++ b/plugins/modules/bitbucket_pipeline_variable.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: bitbucket_pipeline_variable short_description: Manages Bitbucket pipeline variables description: @@ -33,7 +32,7 @@ options: workspace: description: - The repository owner. - - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." + - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user). type: str required: true name: @@ -55,13 +54,13 @@ options: - Indicates desired state of the variable. type: str required: true - choices: [ absent, present ] + choices: [absent, present] notes: - Check mode is supported. - For secured values return parameter C(changed) is always V(true). -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create or update pipeline variables from the list community.general.bitbucket_pipeline_variable: repository: 'bitbucket-repo' @@ -71,8 +70,8 @@ EXAMPLES = r''' secured: '{{ item.secured }}' state: present with_items: - - { name: AWS_ACCESS_KEY, value: ABCD1234, secured: false } - - { name: AWS_SECRET, value: qwe789poi123vbn0, secured: true } + - {name: AWS_ACCESS_KEY, value: ABCD1234, secured: false} + - {name: AWS_SECRET, value: qwe789poi123vbn0, secured: true} - name: Remove pipeline variable community.general.bitbucket_pipeline_variable: @@ -80,9 +79,9 @@ EXAMPLES = r''' workspace: bitbucket_workspace name: AWS_ACCESS_KEY state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule, _load_params from ansible_collections.community.general.plugins.module_utils.source_control.bitbucket import BitbucketHelper diff --git a/plugins/modules/bootc_manage.py b/plugins/modules/bootc_manage.py index 5628ffcca0..44444960df 100644 --- a/plugins/modules/bootc_manage.py +++ b/plugins/modules/bootc_manage.py @@ -8,34 +8,32 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: bootc_manage version_added: 9.3.0 author: -- Ryan Cook (@cooktheryan) + - Ryan Cook (@cooktheryan) short_description: Bootc Switch and Upgrade description: - - This module manages the switching and upgrading of C(bootc). + - This module manages the switching and upgrading of C(bootc). options: - state: - description: - - 'Control to apply the latest image or switch the image.' - - 'B(Note:) This will not reboot the system.' - - 'Please use M(ansible.builtin.reboot) to reboot the system.' - required: true - type: str - choices: ['switch', 'latest'] - image: - description: - - 'The image to switch to.' - - 'This is required when O(state=switch).' - required: false - type: str + state: + description: + - Control whether to apply the latest image or switch the image. + - B(Note:) This will not reboot the system. + - Please use M(ansible.builtin.reboot) to reboot the system. + required: true + type: str + choices: ['switch', 'latest'] + image: + description: + - The image to switch to. + - This is required when O(state=switch). + required: false + type: str +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # Switch to a different image - name: Provide image to switch to a different image and retain the current running image community.general.bootc_manage: @@ -46,10 +44,10 @@ EXAMPLES = ''' - name: Apply updates of the current running image community.general.bootc_manage: state: latest -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/bower.py b/plugins/modules/bower.py index 1824e68bb8..3e7ebdaecc 100644 --- a/plugins/modules/bower.py +++ b/plugins/modules/bower.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: bower -short_description: Manage bower packages with bower +short_description: Manage bower packages with C(bower) description: - - Manage bower packages with bower + - Manage bower packages with C(bower). author: "Michael Warkentin (@mwarkentin)" extends_documentation_fragment: - community.general.attributes @@ -27,39 +26,39 @@ options: name: type: str description: - - The name of a bower package to install + - The name of a bower package to install. offline: description: - - Install packages from local cache, if the packages were installed before + - Install packages from local cache, if the packages were installed before. type: bool default: false production: description: - - Install with --production flag + - Install with C(--production) flag. type: bool default: false path: type: path description: - - The base path where to install the bower packages + - The base path where to install the bower packages. required: true relative_execpath: type: path description: - - Relative path to bower executable from install path + - Relative path to bower executable from install path. state: type: str description: - - The state of the bower package + - The state of the bower package. default: present - choices: [ "present", "absent", "latest" ] + choices: ["present", "absent", "latest"] version: type: str description: - - The version to be installed -''' + - The version to be installed. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install "bootstrap" bower package. community.general.bower: name: bootstrap @@ -91,7 +90,8 @@ EXAMPLES = ''' - community.general.bower: path: /app/location relative_execpath: node_modules/.bin -''' +""" + import json import os diff --git a/plugins/modules/btrfs_info.py b/plugins/modules/btrfs_info.py index c367b9ed10..c3f4204684 100644 --- a/plugins/modules/btrfs_info.py +++ b/plugins/modules/btrfs_info.py @@ -7,78 +7,73 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: btrfs_info short_description: Query btrfs filesystem info version_added: "6.6.0" -description: Query status of available btrfs filesystems, including uuid, label, subvolumes and mountpoints. +description: Query status of available btrfs filesystems, including UUID, label, subvolumes and mountpoints. author: - - Gregory Furlong (@gnfzdz) + - Gregory Furlong (@gnfzdz) extends_documentation_fragment: - - community.general.attributes - - community.general.attributes.info_module -''' - -EXAMPLES = r''' + - community.general.attributes + - community.general.attributes.info_module +""" +EXAMPLES = r""" - name: Query information about mounted btrfs filesystems community.general.btrfs_info: register: my_btrfs_info +""" -''' - -RETURN = r''' - +RETURN = r""" filesystems: - description: Summaries of the current state for all btrfs filesystems found on the target host. - type: list - elements: dict - returned: success - contains: - uuid: - description: A unique identifier assigned to the filesystem. - type: str - sample: 96c9c605-1454-49b8-a63a-15e2584c208e - label: - description: An optional label assigned to the filesystem. - type: str - sample: Tank - devices: - description: A list of devices assigned to the filesystem. - type: list - sample: - - /dev/sda1 - - /dev/sdb1 - default_subvolume: - description: The id of the filesystem's default subvolume. - type: int - sample: 5 - subvolumes: - description: A list of dicts containing metadata for all of the filesystem's subvolumes. - type: list - elements: dict - contains: - id: - description: An identifier assigned to the subvolume, unique within the containing filesystem. - type: int - sample: 256 - mountpoints: - description: Paths where the subvolume is mounted on the targeted host. - type: list - sample: ['/home'] - parent: - description: The identifier of this subvolume's parent. - type: int - sample: 5 - path: - description: The full path of the subvolume relative to the btrfs fileystem's root. - type: str - sample: /@home - -''' + description: Summaries of the current state for all btrfs filesystems found on the target host. + type: list + elements: dict + returned: success + contains: + uuid: + description: A unique identifier assigned to the filesystem. + type: str + sample: 96c9c605-1454-49b8-a63a-15e2584c208e + label: + description: An optional label assigned to the filesystem. + type: str + sample: Tank + devices: + description: A list of devices assigned to the filesystem. + type: list + sample: + - /dev/sda1 + - /dev/sdb1 + default_subvolume: + description: The id of the filesystem's default subvolume. + type: int + sample: 5 + subvolumes: + description: A list of dicts containing metadata for all of the filesystem's subvolumes. + type: list + elements: dict + contains: + id: + description: An identifier assigned to the subvolume, unique within the containing filesystem. + type: int + sample: 256 + mountpoints: + description: Paths where the subvolume is mounted on the targeted host. + type: list + sample: ['/home'] + parent: + description: The identifier of this subvolume's parent. + type: int + sample: 5 + path: + description: The full path of the subvolume relative to the btrfs fileystem's root. + type: str + sample: /@home +""" from ansible_collections.community.general.plugins.module_utils.btrfs import BtrfsFilesystemsProvider diff --git a/plugins/modules/btrfs_subvolume.py b/plugins/modules/btrfs_subvolume.py index 0aa38bf0e4..b1593a8ecd 100644 --- a/plugins/modules/btrfs_subvolume.py +++ b/plugins/modules/btrfs_subvolume.py @@ -7,8 +7,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: btrfs_subvolume short_description: Manage btrfs subvolumes version_added: "6.6.0" @@ -16,71 +15,73 @@ version_added: "6.6.0" description: Creates, updates and deletes btrfs subvolumes and snapshots. options: - automount: - description: - - Allow the module to temporarily mount the targeted btrfs filesystem in order to validate the current state and make any required changes. - type: bool - default: false - default: - description: - - Make the subvolume specified by O(name) the filesystem's default subvolume. - type: bool - default: false - filesystem_device: - description: - - A block device contained within the btrfs filesystem to be targeted. - - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted. - type: path - filesystem_label: - description: - - A descriptive label assigned to the btrfs filesystem to be targeted. - - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted. - type: str - filesystem_uuid: - description: - - A unique identifier assigned to the btrfs filesystem to be targeted. - - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted. - type: str - name: - description: - - Name of the subvolume/snapshot to be targeted. - required: true - type: str - recursive: - description: - - When true, indicates that parent/child subvolumes should be created/removedas necessary - to complete the operation (for O(state=present) and O(state=absent) respectively). - type: bool - default: false - snapshot_source: - description: - - Identifies the source subvolume for the created snapshot. - - Infers that the created subvolume is a snapshot. - type: str - snapshot_conflict: - description: - - Policy defining behavior when a subvolume already exists at the path of the requested snapshot. - - V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required. - Warning, this option does not yet verify that the target subvolume was generated from a snapshot of the requested source. - - V(clobber) - If a subvolume already exists at the requested location, delete it first. - This option is not idempotent and will result in a new snapshot being generated on every execution. - - V(error) - If a subvolume already exists at the requested location, return an error. - This option is not idempotent and will result in an error on replay of the module. - type: str - choices: [ skip, clobber, error ] - default: skip - state: - description: - - Indicates the current state of the targeted subvolume. - type: str - choices: [ absent, present ] - default: present + automount: + description: + - Allow the module to temporarily mount the targeted btrfs filesystem in order to validate the current state and make + any required changes. + type: bool + default: false + default: + description: + - Make the subvolume specified by O(name) the filesystem's default subvolume. + type: bool + default: false + filesystem_device: + description: + - A block device contained within the btrfs filesystem to be targeted. + - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted. + type: path + filesystem_label: + description: + - A descriptive label assigned to the btrfs filesystem to be targeted. + - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted. + type: str + filesystem_uuid: + description: + - A unique identifier assigned to the btrfs filesystem to be targeted. + - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted. + type: str + name: + description: + - Name of the subvolume/snapshot to be targeted. + required: true + type: str + recursive: + description: + - When true, indicates that parent/child subvolumes should be created/removedas necessary to complete the operation + (for O(state=present) and O(state=absent) respectively). + type: bool + default: false + snapshot_source: + description: + - Identifies the source subvolume for the created snapshot. + - Infers that the created subvolume is a snapshot. + type: str + snapshot_conflict: + description: + - Policy defining behavior when a subvolume already exists at the path of the requested snapshot. + - V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that + no change is required. Warning, this option does not yet verify that the target subvolume was generated from a snapshot + of the requested source. + - V(clobber) - If a subvolume already exists at the requested location, delete it first. This option is not idempotent + and will result in a new snapshot being generated on every execution. + - V(error) - If a subvolume already exists at the requested location, return an error. This option is not idempotent + and will result in an error on replay of the module. + type: str + choices: [skip, clobber, error] + default: skip + state: + description: + - Indicates the current state of the targeted subvolume. + type: str + choices: [absent, present] + default: present notes: - - If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided, there is expected - to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or only a single - btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and return an error. - + - If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided, + there is expected to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or + only a single btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and + return an error. extends_documentation_fragment: - community.general.attributes @@ -88,17 +89,16 @@ attributes: check_mode: support: partial details: - - In some scenarios it may erroneously report intermediate subvolumes being created. - After mounting, if a directory like file is found where the subvolume would have been created, the operation is skipped. + - In some scenarios it may erroneously report intermediate subvolumes being created. After mounting, if a directory + like file is found where the subvolume would have been created, the operation is skipped. diff_mode: support: none author: - - Gregory Furlong (@gnfzdz) -''' - -EXAMPLES = r''' + - Gregory Furlong (@gnfzdz) +""" +EXAMPLES = r""" - name: Create a @home subvolume under the root subvolume community.general.btrfs_subvolume: name: /@home @@ -127,85 +127,83 @@ EXAMPLES = r''' community.general.btrfs_subvolume: name: /@snapshots/@2022_06_09 snapshot_source: /@ - recursive: True + recursive: true filesystem_device: /dev/vda2 - name: Remove the /@ subvolume and recursively delete child subvolumes as required community.general.btrfs_subvolume: name: /@snapshots/@2022_06_09 snapshot_source: /@ - recursive: True + recursive: true filesystem_device: /dev/vda2 +""" -''' - -RETURN = r''' - +RETURN = r""" filesystem: - description: + description: - A summary of the final state of the targeted btrfs filesystem. - type: dict - returned: success - contains: - uuid: - description: A unique identifier assigned to the filesystem. - returned: success - type: str - sample: 96c9c605-1454-49b8-a63a-15e2584c208e - label: - description: An optional label assigned to the filesystem. - returned: success - type: str - sample: Tank - devices: - description: A list of devices assigned to the filesystem. - returned: success - type: list - sample: - - /dev/sda1 - - /dev/sdb1 - default_subvolume: - description: The ID of the filesystem's default subvolume. - returned: success and if filesystem is mounted - type: int - sample: 5 - subvolumes: - description: A list of dicts containing metadata for all of the filesystem's subvolumes. - returned: success and if filesystem is mounted - type: list - elements: dict - contains: - id: - description: An identifier assigned to the subvolume, unique within the containing filesystem. - type: int - sample: 256 - mountpoints: - description: Paths where the subvolume is mounted on the targeted host. - type: list - sample: ['/home'] - parent: - description: The identifier of this subvolume's parent. - type: int - sample: 5 - path: - description: The full path of the subvolume relative to the btrfs fileystem's root. - type: str - sample: /@home + type: dict + returned: success + contains: + uuid: + description: A unique identifier assigned to the filesystem. + returned: success + type: str + sample: 96c9c605-1454-49b8-a63a-15e2584c208e + label: + description: An optional label assigned to the filesystem. + returned: success + type: str + sample: Tank + devices: + description: A list of devices assigned to the filesystem. + returned: success + type: list + sample: + - /dev/sda1 + - /dev/sdb1 + default_subvolume: + description: The ID of the filesystem's default subvolume. + returned: success and if filesystem is mounted + type: int + sample: 5 + subvolumes: + description: A list of dicts containing metadata for all of the filesystem's subvolumes. + returned: success and if filesystem is mounted + type: list + elements: dict + contains: + id: + description: An identifier assigned to the subvolume, unique within the containing filesystem. + type: int + sample: 256 + mountpoints: + description: Paths where the subvolume is mounted on the targeted host. + type: list + sample: ['/home'] + parent: + description: The identifier of this subvolume's parent. + type: int + sample: 5 + path: + description: The full path of the subvolume relative to the btrfs fileystem's root. + type: str + sample: /@home modifications: - description: + description: - A list where each element describes a change made to the target btrfs filesystem. - type: list - returned: Success - elements: str + type: list + returned: Success + elements: str target_subvolume_id: - description: + description: - The ID of the subvolume specified with the O(name) parameter, either pre-existing or created as part of module execution. - type: int - sample: 257 - returned: Success and subvolume exists after module execution -''' + type: int + sample: 257 + returned: Success and subvolume exists after module execution +""" from ansible_collections.community.general.plugins.module_utils.btrfs import BtrfsFilesystemsProvider, BtrfsCommands, BtrfsModuleException from ansible_collections.community.general.plugins.module_utils.btrfs import normalize_subvolume_path diff --git a/plugins/modules/bundler.py b/plugins/modules/bundler.py index 59f10800c1..bfd7fe7ec1 100644 --- a/plugins/modules/bundler.py +++ b/plugins/modules/bundler.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: bundler short_description: Manage Ruby Gem dependencies with Bundler description: - - Manage installation and Gem version dependencies for Ruby using the Bundler gem + - Manage installation and Gem version dependencies for Ruby using the Bundler gem. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,80 +25,72 @@ options: executable: type: str description: - - The path to the bundler executable + - The path to the bundler executable. state: type: str description: - - The desired state of the Gem bundle. V(latest) updates gems to the most recent, acceptable version + - The desired state of the Gem bundle. V(latest) updates gems to the most recent, acceptable version. choices: [present, latest] default: present chdir: type: path description: - - The directory to execute the bundler commands from. This directory - needs to contain a valid Gemfile or .bundle/ directory - - If not specified, it will default to the temporary working directory + - The directory to execute the bundler commands from. This directory needs to contain a valid Gemfile or .bundle/ directory. + - If not specified, it will default to the temporary working directory. exclude_groups: type: list elements: str description: - - A list of Gemfile groups to exclude during operations. This only - applies when O(state=present). Bundler considers this - a 'remembered' property for the Gemfile and will automatically exclude - groups in future operations even if O(exclude_groups) is not set + - A list of Gemfile groups to exclude during operations. This only applies when O(state=present). Bundler considers + this a 'remembered' property for the Gemfile and will automatically exclude groups in future operations even if O(exclude_groups) + is not set. clean: description: - - Only applies if O(state=present). If set removes any gems on the - target host that are not in the gemfile + - Only applies if O(state=present). If set removes any gems on the target host that are not in the gemfile. type: bool default: false gemfile: type: path description: - Only applies if O(state=present). The path to the gemfile to use to install gems. - - If not specified it will default to the Gemfile in current directory + - If not specified it will default to the Gemfile in current directory. local: description: - - If set only installs gems from the cache on the target host + - If set only installs gems from the cache on the target host. type: bool default: false deployment_mode: description: - - Only applies if O(state=present). If set it will install gems in - ./vendor/bundle instead of the default location. Requires a Gemfile.lock - file to have been created prior + - Only applies if O(state=present). If set it will install gems in C(./vendor/bundle) instead of the default location. + Requires a C(Gemfile.lock) file to have been created prior. type: bool default: false user_install: description: - - Only applies if O(state=present). Installs gems in the local user's cache or for all users + - Only applies if O(state=present). Installs gems in the local user's cache or for all users. type: bool default: true gem_path: type: path description: - - Only applies if O(state=present). Specifies the directory to - install the gems into. If O(chdir) is set then this path is relative to - O(chdir) + - Only applies if O(state=present). Specifies the directory to install the gems into. If O(chdir) is set then this path + is relative to O(chdir). - If not specified the default RubyGems gem paths will be used. binstub_directory: type: path description: - - Only applies if O(state=present). Specifies the directory to - install any gem bins files to. When executed the bin files will run - within the context of the Gemfile and fail if any required gem - dependencies are not installed. If O(chdir) is set then this path is - relative to O(chdir) + - Only applies if O(state=present). Specifies the directory to install any gem bins files to. When executed the bin + files will run within the context of the Gemfile and fail if any required gem dependencies are not installed. If O(chdir) + is set then this path is relative to O(chdir). extra_args: type: str description: - - A space separated string of additional commands that can be applied to - the Bundler command. Refer to the Bundler documentation for more - information + - A space separated string of additional commands that can be applied to the Bundler command. Refer to the Bundler documentation + for more information. author: "Tim Hoiberg (@thoiberg)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install gems from a Gemfile in the current directory community.general.bundler: state: present @@ -124,7 +115,7 @@ EXAMPLES = ''' community.general.bundler: state: latest chdir: ~/rails_project -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/bzr.py b/plugins/modules/bzr.py index 5a60d765c7..7a4512a5dd 100644 --- a/plugins/modules/bzr.py +++ b/plugins/modules/bzr.py @@ -9,59 +9,55 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: bzr author: -- André Paramés (@andreparames) + - André Paramés (@andreparames) short_description: Deploy software (or files) from bzr branches description: - - Manage C(bzr) branches to deploy files or software. + - Manage C(bzr) branches to deploy files or software. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none diff_mode: support: none options: - name: - description: - - SSH or HTTP protocol address of the parent branch. - aliases: [ parent ] - required: true - type: str - dest: - description: - - Absolute path of where the branch should be cloned to. - required: true - type: path - version: - description: - - What version of the branch to clone. This can be the - bzr revno or revid. - default: head - type: str - force: - description: - - If V(true), any modified files in the working - tree will be discarded. - type: bool - default: false - executable: - description: - - Path to bzr executable to use. If not supplied, - the normal mechanism for resolving binary paths will be used. - type: str -''' + name: + description: + - SSH or HTTP protocol address of the parent branch. + aliases: [parent] + required: true + type: str + dest: + description: + - Absolute path of where the branch should be cloned to. + required: true + type: path + version: + description: + - What version of the branch to clone. This can be the bzr revno or revid. + default: head + type: str + force: + description: + - If V(true), any modified files in the working tree will be discarded. + type: bool + default: false + executable: + description: + - Path to bzr executable to use. If not supplied, the normal mechanism for resolving binary paths will be used. + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Checkout community.general.bzr: name: bzr+ssh://foosball.example.org/path/to/branch dest: /srv/checkout version: 22 -''' +""" import os import re