From 3db0a111480107af4692342746f392815d1e0cd9 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 27 Dec 2024 14:44:36 +0100 Subject: [PATCH] [PR #9418/43599c68 backport][stable-10] c*.py: normalize docs (#9426) c*.py: normalize docs (#9418) * c*.py: normalize docs * fix copy/paste mistake * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 43599c6850cd55b04d8e1a787d5c4a87e524d1be) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/campfire.py | 30 +- plugins/modules/capabilities.py | 67 +++-- plugins/modules/cargo.py | 17 +- plugins/modules/catapult.py | 41 ++- plugins/modules/circonus_annotation.py | 210 +++++++------ plugins/modules/cisco_webex.py | 31 +- plugins/modules/clc_aa_policy.py | 49 ++- plugins/modules/clc_alert_policy.py | 69 ++--- plugins/modules/clc_blueprint_package.py | 58 ++-- plugins/modules/clc_firewall_policy.py | 70 ++--- plugins/modules/clc_group.py | 53 ++-- plugins/modules/clc_loadbalancer.py | 58 ++-- plugins/modules/clc_modify_server.py | 92 +++--- plugins/modules/clc_publicip.py | 58 ++-- plugins/modules/clc_server.py | 104 +++---- plugins/modules/clc_server_snapshot.py | 60 ++-- plugins/modules/cloud_init_data_facts.py | 20 +- plugins/modules/cloudflare_dns.py | 363 +++++++++++------------ plugins/modules/cobbler_sync.py | 37 ++- plugins/modules/cobbler_system.py | 59 ++-- plugins/modules/composer.py | 198 ++++++------- plugins/modules/consul.py | 287 +++++++++--------- plugins/modules/consul_acl_bootstrap.py | 46 ++- plugins/modules/consul_agent_check.py | 104 +++---- plugins/modules/consul_agent_service.py | 100 +++---- plugins/modules/consul_auth_method.py | 21 +- plugins/modules/consul_binding_rule.py | 16 +- plugins/modules/consul_kv.py | 190 ++++++------ plugins/modules/consul_policy.py | 82 +++-- plugins/modules/consul_role.py | 65 ++-- plugins/modules/consul_session.py | 147 +++++---- plugins/modules/consul_token.py | 61 ++-- plugins/modules/copr.py | 89 +++--- plugins/modules/cpanm.py | 73 +++-- plugins/modules/cronvar.py | 21 +- plugins/modules/crypttab.py | 31 +- 36 files changed, 1450 insertions(+), 1627 deletions(-) diff --git a/plugins/modules/campfire.py b/plugins/modules/campfire.py index 1e0f1ecea4c..91e83fc7d18 100644 --- a/plugins/modules/campfire.py +++ b/plugins/modules/campfire.py @@ -9,15 +9,14 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: campfire short_description: Send a message to Campfire description: - - Send a message to Campfire. - - Messages with newlines will result in a "Paste" message being sent. + - Send a message to Campfire. + - Messages with newlines will result in a "Paste" message being sent. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -49,22 +48,17 @@ description: - Send a notification sound before the message. required: false - choices: ["56k", "bell", "bezos", "bueller", "clowntown", - "cottoneyejoe", "crickets", "dadgummit", "dangerzone", - "danielsan", "deeper", "drama", "greatjob", "greyjoy", - "guarantee", "heygirl", "horn", "horror", - "inconceivable", "live", "loggins", "makeitso", "noooo", - "nyan", "ohmy", "ohyeah", "pushit", "rimshot", - "rollout", "rumble", "sax", "secret", "sexyback", - "story", "tada", "tmyk", "trololo", "trombone", "unix", - "vuvuzela", "what", "whoomp", "yeah", "yodel"] + choices: ["56k", "bell", "bezos", "bueller", "clowntown", "cottoneyejoe", "crickets", "dadgummit", "dangerzone", "danielsan", + "deeper", "drama", "greatjob", "greyjoy", "guarantee", "heygirl", "horn", "horror", "inconceivable", "live", "loggins", + "makeitso", "noooo", "nyan", "ohmy", "ohyeah", "pushit", "rimshot", "rollout", "rumble", "sax", "secret", "sexyback", + "story", "tada", "tmyk", "trololo", "trombone", "unix", "vuvuzela", "what", "whoomp", "yeah", "yodel"] # informational: requirements for nodes -requirements: [ ] +requirements: [] author: "Adam Garside (@fabulops)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Send a message to Campfire community.general.campfire: subscription: foo @@ -79,7 +73,7 @@ room: 123 notify: loggins msg: Task completed ... with feeling. -''' +""" try: from html import escape as html_escape diff --git a/plugins/modules/capabilities.py b/plugins/modules/capabilities.py index a0b6d522235..18c56605b92 100644 --- a/plugins/modules/capabilities.py +++ b/plugins/modules/capabilities.py @@ -8,48 +8,47 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: capabilities short_description: Manage Linux capabilities description: - - This module manipulates files privileges using the Linux capabilities(7) system. + - This module manipulates files privileges using the Linux capabilities(7) system. 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: - path: - description: - - Specifies the path to the file to be managed. - type: str - required: true - aliases: [ key ] - capability: - description: - - Desired capability to set (with operator and flags, if O(state=present)) or remove (if O(state=absent)) - type: str - required: true - aliases: [ cap ] - state: - description: - - Whether the entry should be present or absent in the file's capabilities. - type: str - choices: [ absent, present ] - default: present + path: + description: + - Specifies the path to the file to be managed. + type: str + required: true + aliases: [key] + capability: + description: + - Desired capability to set (with operator and flags, if O(state=present)) or remove (if O(state=absent)). + type: str + required: true + aliases: [cap] + state: + description: + - Whether the entry should be present or absent in the file's capabilities. + type: str + choices: [absent, present] + default: present notes: - - The capabilities system will automatically transform operators and flags into the effective set, - so for example, C(cap_foo=ep) will probably become C(cap_foo+ep). - - This module does not attempt to determine the final operator and flags to compare, - so you will want to ensure that your capabilities argument matches the final capabilities. + - The capabilities system will automatically transform operators and flags into the effective set, so for example, C(cap_foo=ep) + will probably become C(cap_foo+ep). + - This module does not attempt to determine the final operator and flags to compare, so you will want to ensure that your + capabilities argument matches the final capabilities. author: -- Nate Coraor (@natefoo) -''' + - Nate Coraor (@natefoo) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Set cap_sys_chroot+ep on /foo community.general.capabilities: path: /foo @@ -61,7 +60,7 @@ path: /bar capability: cap_net_bind_service state: absent -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/cargo.py b/plugins/modules/cargo.py index 2fc729da206..ea2976036c9 100644 --- a/plugins/modules/cargo.py +++ b/plugins/modules/cargo.py @@ -11,7 +11,6 @@ DOCUMENTATION = r""" ---- module: cargo short_description: Manage Rust packages with cargo version_added: 4.3.0 @@ -39,16 +38,12 @@ elements: str required: true path: - description: - -> - The base path where to install the Rust packages. Cargo automatically appends - V(/bin). In other words, V(/usr/local) will become V(/usr/local/bin). + description: The base path where to install the Rust packages. Cargo automatically appends V(/bin). In other words, + V(/usr/local) will become V(/usr/local/bin). type: path version: - description: - -> - The version to install. If O(name) contains multiple values, the module will - try to install all of them in this version. + description: The version to install. If O(name) contains multiple values, the module will try to install all of them + in this version. type: str required: false locked: @@ -65,7 +60,7 @@ required: false type: str default: present - choices: [ "present", "absent", "latest" ] + choices: ["present", "absent", "latest"] directory: description: - Path to the source directory to install the Rust package from. @@ -74,7 +69,7 @@ required: false version_added: 9.1.0 requirements: - - cargo installed + - cargo installed """ EXAMPLES = r""" diff --git a/plugins/modules/catapult.py b/plugins/modules/catapult.py index acd83985125..e9c661e99b5 100644 --- a/plugins/modules/catapult.py +++ b/plugins/modules/catapult.py @@ -11,14 +11,13 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: catapult -short_description: Send a sms / mms using the catapult bandwidth api +short_description: Send a sms / mms using the catapult bandwidth API description: - - Allows notifications to be sent using sms / mms via the catapult bandwidth api. + - Allows notifications to be sent using SMS / MMS using the catapult bandwidth API. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -44,31 +43,30 @@ media: type: str description: - - For MMS messages, a media url to the location of the media to be sent with the message. + - For MMS messages, a media URL to the location of the media to be sent with the message. user_id: type: str description: - - User Id from Api account page. + - User Id from API account page. required: true api_token: type: str description: - - Api Token from Api account page. + - API Token from API account page. required: true api_secret: type: str description: - - Api Secret from Api account page. + - API Secret from API account page. required: true author: "Jonathan Mainguy (@Jmainguy)" notes: - - Will return changed even if the media url is wrong. - - Will return changed if the destination number is invalid. + - Will return changed even if the media url is wrong. + - Will return changed if the destination number is invalid. +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Send a mms to multiple users community.general.catapult: src: "+15035555555" @@ -89,16 +87,15 @@ user_id: "{{ user_id }}" api_token: "{{ api_token }}" api_secret: "{{ api_secret }}" +""" -''' - -RETURN = ''' +RETURN = r""" changed: - description: Whether the api accepted the message. - returned: always - type: bool - sample: true -''' + description: Whether the API accepted the message. + returned: always + type: bool + sample: true +""" import json diff --git a/plugins/modules/circonus_annotation.py b/plugins/modules/circonus_annotation.py index f3b94a05242..9e563171cd9 100644 --- a/plugins/modules/circonus_annotation.py +++ b/plugins/modules/circonus_annotation.py @@ -9,62 +9,59 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: circonus_annotation -short_description: Create an annotation in circonus +short_description: Create an annotation in Circonus description: - - Create an annotation event with a given category, title and description. Optionally start, end or durations can be provided + - Create an annotation event with a given category, title and description. Optionally start, end or durations can be provided. author: "Nick Harring (@NickatEpic)" requirements: - - requests (either >= 2.0.0 for Python 3, or >= 1.0.0 for Python 2) -notes: - - Check mode isn't supported. + - requests (either >= 2.0.0 for Python 3, or >= 1.0.0 for Python 2) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - api_key: - type: str - description: - - Circonus API key - required: true - category: - type: str - description: - - Annotation Category - required: true + api_key: + type: str description: - type: str - description: - - Description of annotation - required: true - title: - type: str - description: - - Title of annotation - required: true - start: - type: int - description: - - Unix timestamp of event start - - If not specified, it defaults to "now". - stop: - type: int - description: - - Unix timestamp of event end - - If not specified, it defaults to "now" + O(duration). - duration: - type: int - description: - - Duration in seconds of annotation - default: 0 -''' -EXAMPLES = ''' + - Circonus API key. + required: true + category: + type: str + description: + - Annotation Category. + required: true + description: + type: str + description: + - Description of annotation. + required: true + title: + type: str + description: + - Title of annotation. + required: true + start: + type: int + description: + - Unix timestamp of event start. + - If not specified, it defaults to "now". + stop: + type: int + description: + - Unix timestamp of event end. + - If not specified, it defaults to "now" + O(duration). + duration: + type: int + description: + - Duration in seconds of annotation. + default: 0 +""" +EXAMPLES = r""" - name: Create a simple annotation event with a source, defaults to start and end time of now community.general.circonus_annotation: api_key: XXXXXXXXXXXXXXXXX @@ -88,66 +85,67 @@ category: This category groups like annotations start_time: 1395940006 end_time: 1395954407 -''' +""" -RETURN = ''' +RETURN = r""" annotation: - description: details about the created annotation - returned: success - type: complex - contains: - _cid: - description: annotation identifier - returned: success - type: str - sample: /annotation/100000 - _created: - description: creation timestamp - returned: success - type: int - sample: 1502236928 - _last_modified: - description: last modification timestamp - returned: success - type: int - sample: 1502236928 - _last_modified_by: - description: last modified by - returned: success - type: str - sample: /user/1000 - category: - description: category of the created annotation - returned: success - type: str - sample: alerts - title: - description: title of the created annotation - returned: success - type: str - sample: WARNING - description: - description: description of the created annotation - returned: success - type: str - sample: Host is down. - start: - description: timestamp, since annotation applies - returned: success - type: int - sample: Host is down. - stop: - description: timestamp, since annotation ends - returned: success - type: str - sample: Host is down. - rel_metrics: - description: Array of metrics related to this annotation, each metrics is a string. - returned: success - type: list - sample: - - 54321_kbps -''' + description: Details about the created annotation. + returned: success + type: complex + contains: + _cid: + description: Annotation identifier. + returned: success + type: str + sample: /annotation/100000 + _created: + description: Creation timestamp. + returned: success + type: int + sample: 1502236928 + _last_modified: + description: Last modification timestamp. + returned: success + type: int + sample: 1502236928 + _last_modified_by: + description: Last modified by. + returned: success + type: str + sample: /user/1000 + category: + description: Category of the created annotation. + returned: success + type: str + sample: alerts + title: + description: Title of the created annotation. + returned: success + type: str + sample: WARNING + description: + description: Description of the created annotation. + returned: success + type: str + sample: Host is down. + start: + description: Timestamp, since annotation applies. + returned: success + type: int + sample: Host is down. + stop: + description: Timestamp, since annotation ends. + returned: success + type: str + sample: Host is down. + rel_metrics: + description: Array of metrics related to this annotation, each metrics is a string. + returned: success + type: list + sample: + - 54321_kbps +""" + import json import time import traceback diff --git a/plugins/modules/cisco_webex.py b/plugins/modules/cisco_webex.py index caa77f576d0..14b87168462 100644 --- a/plugins/modules/cisco_webex.py +++ b/plugins/modules/cisco_webex.py @@ -9,17 +9,15 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: cisco_webex short_description: Send a message to a Cisco Webex Teams Room or Individual description: - - Send a message to a Cisco Webex Teams Room or Individual with options to control the formatting. + - Send a message to a Cisco Webex Teams Room or Individual with options to control the formatting. author: Drew Rusell (@drew-russell) notes: - The O(recipient_type) must be valid for the supplied O(recipient_id). - Full API documentation can be found at U(https://developer.webex.com/docs/api/basics). - extends_documentation_fragment: - community.general.attributes attributes: @@ -32,8 +30,8 @@ recipient_type: description: - - The request parameter you would like to send the message to. - - Messages can be sent to either a room or individual (by ID or E-Mail). + - The request parameter you would like to send the message to. + - Messages can be sent to either a room or individual (by ID or E-Mail). required: true choices: ['roomId', 'toPersonEmail', 'toPersonId'] type: str @@ -46,7 +44,7 @@ msg_type: description: - - Specifies how you would like the message formatted. + - Specifies how you would like the message formatted. default: text choices: ['text', 'markdown'] type: str @@ -64,9 +62,9 @@ - The message you would like to send. required: true type: str -''' +""" -EXAMPLES = """ +EXAMPLES = r""" # Note: The following examples assume a variable file has been imported # that contains the appropriate information. @@ -101,10 +99,9 @@ msg_type: text personal_token: "{{ token }}" msg: "Cisco Webex Teams Ansible Module - Text Message to Individual by E-Mail" - """ -RETURN = """ +RETURN = r""" status_code: description: - The Response Code returned by the Webex Teams API. @@ -114,12 +111,12 @@ sample: 200 message: - description: - - The Response Message returned by the Webex Teams API. - - Full Response Code explanations can be found at U(https://developer.webex.com/docs/api/basics). - returned: always - type: str - sample: OK (585 bytes) + description: + - The Response Message returned by the Webex Teams API. + - Full Response Code explanations can be found at U(https://developer.webex.com/docs/api/basics). + returned: always + type: str + sample: OK (585 bytes) """ from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url diff --git a/plugins/modules/clc_aa_policy.py b/plugins/modules/clc_aa_policy.py index 05135bd9576..d172c263432 100644 --- a/plugins/modules/clc_aa_policy.py +++ b/plugins/modules/clc_aa_policy.py @@ -9,11 +9,11 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_aa_policy -short_description: Create or Delete Anti Affinity Policies at CenturyLink Cloud +short_description: Create or Delete Anti-Affinity Policies at CenturyLink Cloud description: - - An Ansible module to Create or Delete Anti Affinity Policies at CenturyLink Cloud. + - An Ansible module to Create or Delete Anti-Affinity Policies at CenturyLink Cloud. extends_documentation_fragment: - community.general.attributes attributes: @@ -24,7 +24,7 @@ options: name: description: - - The name of the Anti Affinity Policy. + - The name of the Anti-Affinity Policy. type: str required: true location: @@ -38,28 +38,23 @@ type: str required: false default: present - choices: ['present','absent'] + choices: ['present', 'absent'] requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' -# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - ---- + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" - name: Create AA Policy hosts: localhost gather_facts: false @@ -91,11 +86,11 @@ - name: Debug ansible.builtin.debug: var: policy -''' +""" -RETURN = ''' +RETURN = r""" policy: - description: The anti affinity policy information + description: The anti-affinity policy information. returned: success type: dict sample: @@ -121,7 +116,7 @@ } ] } -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_alert_policy.py b/plugins/modules/clc_alert_policy.py index b77c83e3b73..999d1f743fe 100644 --- a/plugins/modules/clc_alert_policy.py +++ b/plugins/modules/clc_alert_policy.py @@ -10,7 +10,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_alert_policy short_description: Create or Delete Alert Policies at CenturyLink Cloud description: @@ -25,67 +25,58 @@ options: alias: description: - - The alias of your CLC Account + - The alias of your CLC Account. type: str required: true name: description: - - The name of the alert policy. This is mutually exclusive with id + - The name of the alert policy. This is mutually exclusive with O(id). type: str id: description: - - The alert policy id. This is mutually exclusive with name + - The alert policy id. This is mutually exclusive with O(name). type: str alert_recipients: description: - - A list of recipient email ids to notify the alert. - This is required for state 'present' + - A list of recipient email ids to notify the alert. This is required for O(state=present). type: list elements: str metric: description: - - The metric on which to measure the condition that will trigger the alert. - This is required for state 'present' + - The metric on which to measure the condition that will trigger the alert. This is required for O(state=present). type: str - choices: ['cpu','memory','disk'] + choices: ['cpu', 'memory', 'disk'] duration: description: - - The length of time in minutes that the condition must exceed the threshold. - This is required for state 'present' + - The length of time in minutes that the condition must exceed the threshold. This is required for O(state=present). type: str threshold: description: - - The threshold that will trigger the alert when the metric equals or exceeds it. - This is required for state 'present' - This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0 + - The threshold that will trigger the alert when the metric equals or exceeds it. This is required for O(state=present). + This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0. type: int state: description: - Whether to create or delete the policy. type: str default: present - choices: ['present','absent'] + choices: ['present', 'absent'] requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' -# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - ---- + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" - name: Create Alert Policy Example hosts: localhost gather_facts: false @@ -96,8 +87,8 @@ alias: wfad name: 'alert for disk > 80%' alert_recipients: - - test1@centurylink.com - - test2@centurylink.com + - test1@centurylink.com + - test2@centurylink.com metric: 'disk' duration: '00:05:00' threshold: 80 @@ -121,11 +112,11 @@ - name: Debug ansible.builtin.debug: var=policy -''' +""" -RETURN = ''' +RETURN = r""" policy: - description: The alert policy information + description: The alert policy information. returned: success type: dict sample: @@ -162,7 +153,7 @@ } ] } -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_blueprint_package.py b/plugins/modules/clc_blueprint_package.py index 672e06780f0..be44b585301 100644 --- a/plugins/modules/clc_blueprint_package.py +++ b/plugins/modules/clc_blueprint_package.py @@ -9,7 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_blueprint_package short_description: Deploys a blue print package on a set of servers in CenturyLink Cloud description: @@ -41,7 +41,7 @@ required: false state: description: - - Whether to install or uninstall the package. Currently it supports only "present" for install action. + - Whether to install or uninstall the package. Currently it supports only V(present) for install action. type: str required: false default: present @@ -53,45 +53,39 @@ default: 'True' required: false requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" -EXAMPLES = ''' +EXAMPLES = r""" # Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - name: Deploy package community.general.clc_blueprint_package: - server_ids: - - UC1TEST-SERVER1 - - UC1TEST-SERVER2 - package_id: 77abb844-579d-478d-3955-c69ab4a7ba1a - package_params: {} -''' + server_ids: + - UC1TEST-SERVER1 + - UC1TEST-SERVER2 + package_id: 77abb844-579d-478d-3955-c69ab4a7ba1a + package_params: {} +""" -RETURN = ''' +RETURN = r""" server_ids: - description: The list of server ids that are changed - returned: success - type: list - sample: - [ - "UC1TEST-SERVER1", - "UC1TEST-SERVER2" - ] -''' + description: The list of server ids that are changed. + returned: success + type: list + sample: ["UC1TEST-SERVER1", "UC1TEST-SERVER2"] +""" __version__ = '${version}' diff --git a/plugins/modules/clc_firewall_policy.py b/plugins/modules/clc_firewall_policy.py index b30037c6feb..7c34b7c744e 100644 --- a/plugins/modules/clc_firewall_policy.py +++ b/plugins/modules/clc_firewall_policy.py @@ -9,11 +9,11 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_firewall_policy short_description: Create/delete/update firewall policies description: - - Create or delete or update firewall policies on Centurylink Cloud + - Create or delete or update firewall policies on Centurylink Cloud. extends_documentation_fragment: - community.general.attributes attributes: @@ -24,46 +24,43 @@ options: location: description: - - Target datacenter for the firewall policy + - Target datacenter for the firewall policy. type: str required: true state: description: - - Whether to create or delete the firewall policy + - Whether to create or delete the firewall policy. type: str default: present choices: ['present', 'absent'] source: description: - - The list of source addresses for traffic on the originating firewall. - This is required when state is 'present' + - The list of source addresses for traffic on the originating firewall. This is required when O(state=present). type: list elements: str destination: description: - - The list of destination addresses for traffic on the terminating firewall. - This is required when state is 'present' + - The list of destination addresses for traffic on the terminating firewall. This is required when O(state=present). type: list elements: str ports: description: - - The list of ports associated with the policy. - TCP and UDP can take in single ports or port ranges. + - The list of ports associated with the policy. TCP and UDP can take in single ports or port ranges. - "Example: V(['any', 'icmp', 'TCP/123', 'UDP/123', 'TCP/123-456', 'UDP/123-456'])." type: list elements: str firewall_policy_id: description: - - Id of the firewall policy. This is required to update or delete an existing firewall policy + - Id of the firewall policy. This is required to update or delete an existing firewall policy. type: str source_account_alias: description: - - CLC alias for the source account + - CLC alias for the source account. type: str required: true destination_account_alias: description: - - CLC alias for the destination account + - CLC alias for the destination account. type: str wait: description: @@ -72,29 +69,26 @@ default: 'True' enabled: description: - - Whether the firewall policy is enabled or disabled + - Whether the firewall policy is enabled or disabled. type: str choices: ['True', 'False'] default: 'True' requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' ---- + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" - name: Create Firewall Policy hosts: localhost gather_facts: false @@ -121,16 +115,16 @@ location: VA1 state: absent firewall_policy_id: c62105233d7a4231bd2e91b9c791e43e1 -''' +""" -RETURN = ''' +RETURN = r""" firewall_policy_id: - description: The fire wall policy id - returned: success - type: str - sample: fc36f1bfd47242e488a9c44346438c05 + description: The firewall policy id. + returned: success + type: str + sample: fc36f1bfd47242e488a9c44346438c05 firewall_policy: - description: The fire wall policy information + description: The firewall policy information. returned: success type: dict sample: @@ -162,7 +156,7 @@ ], "status":"active" } -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_group.py b/plugins/modules/clc_group.py index 88aef2d63d6..ceb5513c607 100644 --- a/plugins/modules/clc_group.py +++ b/plugins/modules/clc_group.py @@ -10,11 +10,11 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_group short_description: Create/delete Server Groups at Centurylink Cloud description: - - Create or delete Server Groups at Centurylink Centurylink Cloud + - Create or delete Server Groups at Centurylink Centurylink Cloud. extends_documentation_fragment: - community.general.attributes attributes: @@ -25,12 +25,12 @@ options: name: description: - - The name of the Server Group + - The name of the Server Group. type: str required: true description: description: - - A description of the Server Group + - A description of the Server Group. type: str required: false parent: @@ -40,13 +40,13 @@ required: false location: description: - - Datacenter to create the group in. If location is not provided, the group gets created in the default datacenter - associated with the account + - Datacenter to create the group in. If location is not provided, the group gets created in the default datacenter associated + with the account. type: str required: false state: description: - - Whether to create or delete the group + - Whether to create or delete the group. type: str default: present choices: ['present', 'absent'] @@ -57,27 +57,22 @@ default: true required: false requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' - + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" # Create a Server Group - ---- - name: Create Server Group hosts: localhost gather_facts: false @@ -110,11 +105,11 @@ - name: Debug ansible.builtin.debug: var: clc -''' +""" -RETURN = ''' +RETURN = r""" group: - description: The group information + description: The group information. returned: success type: dict sample: @@ -209,7 +204,7 @@ "status":"active", "type":"default" } -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_loadbalancer.py b/plugins/modules/clc_loadbalancer.py index 675cc1100e0..4690bd65063 100644 --- a/plugins/modules/clc_loadbalancer.py +++ b/plugins/modules/clc_loadbalancer.py @@ -10,7 +10,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_loadbalancer short_description: Create, Delete shared loadbalancers in CenturyLink Cloud description: @@ -25,74 +25,72 @@ options: name: description: - - The name of the loadbalancer + - The name of the loadbalancer. type: str required: true description: description: - - A description for the loadbalancer + - A description for the loadbalancer. type: str alias: description: - - The alias of your CLC Account + - The alias of your CLC Account. type: str required: true location: description: - - The location of the datacenter where the load balancer resides in + - The location of the datacenter where the load balancer resides in. type: str required: true method: description: - -The balancing method for the load balancer pool + - The balancing method for the load balancer pool. type: str choices: ['leastConnection', 'roundRobin'] persistence: description: - - The persistence method for the load balancer + - The persistence method for the load balancer. type: str choices: ['standard', 'sticky'] port: description: - - Port to configure on the public-facing side of the load balancer pool + - Port to configure on the public-facing side of the load balancer pool. type: str choices: ['80', '443'] nodes: description: - - A list of nodes that needs to be added to the load balancer pool + - A list of nodes that needs to be added to the load balancer pool. type: list default: [] elements: dict status: description: - - The status of the loadbalancer + - The status of the loadbalancer. type: str default: enabled choices: ['enabled', 'disabled'] state: description: - - Whether to create or delete the load balancer pool + - Whether to create or delete the load balancer pool. type: str default: present choices: ['present', 'absent', 'port_absent', 'nodes_present', 'nodes_absent'] requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" # Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - name: Create Loadbalancer hosts: localhost @@ -173,11 +171,11 @@ - ipAddress: 10.11.22.123 privatePort: 80 state: absent -''' +""" -RETURN = ''' +RETURN = r""" loadbalancer: - description: The load balancer result object from CLC + description: The load balancer result object from CLC. returned: success type: dict sample: @@ -210,7 +208,7 @@ ], "status":"enabled" } -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_modify_server.py b/plugins/modules/clc_modify_server.py index b375d9d47af..ed01e36763c 100644 --- a/plugins/modules/clc_modify_server.py +++ b/plugins/modules/clc_modify_server.py @@ -9,7 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_modify_server short_description: Modify servers in CenturyLink Cloud description: @@ -30,7 +30,7 @@ elements: str cpu: description: - - How many CPUs to update on the server + - How many CPUs to update on the server. type: str memory: description: @@ -38,23 +38,19 @@ type: str anti_affinity_policy_id: description: - - The anti affinity policy id to be set for a hyper scale server. - This is mutually exclusive with 'anti_affinity_policy_name' + - The anti affinity policy id to be set for a hyper scale server. This is mutually exclusive with O(anti_affinity_policy_name). type: str anti_affinity_policy_name: description: - - The anti affinity policy name to be set for a hyper scale server. - This is mutually exclusive with 'anti_affinity_policy_id' + - The anti affinity policy name to be set for a hyper scale server. This is mutually exclusive with O(anti_affinity_policy_id). type: str alert_policy_id: description: - - The alert policy id to be associated to the server. - This is mutually exclusive with 'alert_policy_name' + - The alert policy id to be associated to the server. This is mutually exclusive with O(alert_policy_name). type: str alert_policy_name: description: - - The alert policy name to be associated to the server. - This is mutually exclusive with 'alert_policy_id' + - The alert policy name to be associated to the server. This is mutually exclusive with O(alert_policy_id). type: str state: description: @@ -68,95 +64,89 @@ type: bool default: true requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" # Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - name: Set the cpu count to 4 on a server community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 cpu: 4 state: present - name: Set the memory to 8GB on a server community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 memory: 8 state: present - name: Set the anti affinity policy on a server community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 anti_affinity_policy_name: 'aa_policy' state: present - name: Remove the anti affinity policy on a server community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 anti_affinity_policy_name: 'aa_policy' state: absent - name: Add the alert policy on a server community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 alert_policy_name: 'alert_policy' state: present - name: Remove the alert policy on a server community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 alert_policy_name: 'alert_policy' state: absent - name: Ret the memory to 16GB and cpu to 8 core on a lust if servers community.general.clc_modify_server: server_ids: - - UC1TESTSVR01 - - UC1TESTSVR02 + - UC1TESTSVR01 + - UC1TESTSVR02 cpu: 8 memory: 16 state: present -''' +""" -RETURN = ''' +RETURN = r""" server_ids: - description: The list of server ids that are changed - returned: success - type: list - sample: - [ - "UC1TEST-SVR01", - "UC1TEST-SVR02" - ] + description: The list of server ids that are changed. + returned: success + type: list + sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"] servers: - description: The list of server objects that are changed + description: The list of server objects that are changed. returned: success type: list sample: @@ -312,7 +302,7 @@ "type":"standard" } ] -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_publicip.py b/plugins/modules/clc_publicip.py index c1bffcea04c..086eaf64e40 100644 --- a/plugins/modules/clc_publicip.py +++ b/plugins/modules/clc_publicip.py @@ -9,11 +9,11 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_publicip -short_description: Add and Delete public ips on servers in CenturyLink Cloud +short_description: Add and Delete public IPs on servers in CenturyLink Cloud description: - - An Ansible module to add or delete public ip addresses on an existing server or servers in CenturyLink Cloud. + - An Ansible module to add or delete public IP addresses on an existing server or servers in CenturyLink Cloud. extends_documentation_fragment: - community.general.attributes attributes: @@ -30,7 +30,7 @@ choices: ['TCP', 'UDP', 'ICMP'] ports: description: - - A list of ports to expose. This is required when state is 'present' + - A list of ports to expose. This is required when O(state=present). type: list elements: int server_ids: @@ -41,8 +41,8 @@ elements: str state: description: - - Determine whether to create or delete public IPs. If present module will not create a second public ip if one - already exists. + - Determine whether to create or delete public IPs. If V(present) module will not create a second public ip if one already + exists. type: str default: present choices: ['present', 'absent'] @@ -52,23 +52,21 @@ type: bool default: true requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" # Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - name: Add Public IP to Server @@ -107,19 +105,15 @@ - name: Debug ansible.builtin.debug: var: clc -''' +""" -RETURN = ''' +RETURN = r""" server_ids: - description: The list of server ids that are changed - returned: success - type: list - sample: - [ - "UC1TEST-SVR01", - "UC1TEST-SVR02" - ] -''' + description: The list of server ids that are changed. + returned: success + type: list + sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"] +""" __version__ = '${version}' diff --git a/plugins/modules/clc_server.py b/plugins/modules/clc_server.py index 6bfe5a9b9e1..156fc6dee6c 100644 --- a/plugins/modules/clc_server.py +++ b/plugins/modules/clc_server.py @@ -9,7 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_server short_description: Create, Delete, Start and Stop servers in CenturyLink Cloud description: @@ -24,13 +24,13 @@ options: additional_disks: description: - - The list of additional disks for the server + - The list of additional disks for the server. type: list elements: dict default: [] add_public_ip: description: - - Whether to add a public ip to the server + - Whether to add a public ip to the server. type: bool default: false alias: @@ -39,32 +39,32 @@ type: str anti_affinity_policy_id: description: - - The anti-affinity policy to assign to the server. This is mutually exclusive with 'anti_affinity_policy_name'. + - The anti-affinity policy to assign to the server. This is mutually exclusive with O(anti_affinity_policy_name). type: str anti_affinity_policy_name: description: - - The anti-affinity policy to assign to the server. This is mutually exclusive with 'anti_affinity_policy_id'. + - The anti-affinity policy to assign to the server. This is mutually exclusive with O(anti_affinity_policy_id). type: str alert_policy_id: description: - - The alert policy to assign to the server. This is mutually exclusive with 'alert_policy_name'. + - The alert policy to assign to the server. This is mutually exclusive with O(alert_policy_name). type: str alert_policy_name: description: - - The alert policy to assign to the server. This is mutually exclusive with 'alert_policy_id'. + - The alert policy to assign to the server. This is mutually exclusive with O(alert_policy_id). type: str count: description: - - The number of servers to build (mutually exclusive with exact_count) + - The number of servers to build (mutually exclusive with O(exact_count)). default: 1 type: int count_group: description: - - Required when exact_count is specified. The Server Group use to determine how many servers to deploy. + - Required when exact_count is specified. The Server Group use to determine how many servers to deploy. type: str cpu: description: - - How many CPUs to provision on the server + - How many CPUs to provision on the server. default: 1 type: int cpu_autoscale_policy_id: @@ -83,8 +83,8 @@ type: str exact_count: description: - - Run in idempotent mode. Will insure that this exact number of servers are running in the provided group, - creating and deleting them to reach that count. Requires count_group to be set. + - Run in idempotent mode. Will insure that this exact number of servers are running in the provided group, creating + and deleting them to reach that count. Requires O(count_group) to be set. type: int group: description: @@ -112,7 +112,7 @@ default: 1 name: description: - - A 1 to 6 character identifier to use for the server. This is required when state is 'present' + - A 1 to 6 character identifier to use for the server. This is required when O(state=present). type: str network_id: description: @@ -126,7 +126,7 @@ default: [] password: description: - - Password for the administrator / root user + - Password for the administrator / root user. type: str primary_dns: description: @@ -150,8 +150,7 @@ type: str server_ids: description: - - Required for started, stopped, and absent states. - A list of server Ids to insure are started, stopped, or absent. + - Required for started, stopped, and absent states. A list of server Ids to insure are started, stopped, or absent. type: list default: [] elements: str @@ -173,12 +172,12 @@ choices: ['standard', 'hyperscale'] template: description: - - The template to use for server creation. Will search for a template if a partial string is provided. - This is required when state is 'present' + - The template to use for server creation. Will search for a template if a partial string is provided. This is required + when O(state=present). type: str ttl: description: - - The time to live for the server in seconds. The server will be deleted when this time expires. + - The time to live for the server in seconds. The server will be deleted when this time expires. type: str type: description: @@ -188,13 +187,12 @@ choices: ['standard', 'hyperscale', 'bareMetal'] configuration_id: description: - - Only required for bare metal servers. - Specifies the identifier for the specific configuration type of bare metal server to deploy. + - Only required for bare metal servers. Specifies the identifier for the specific configuration type of bare metal server + to deploy. type: str os_type: description: - - Only required for bare metal servers. - Specifies the OS to provision with the bare metal server. + - Only required for bare metal servers. Specifies the OS to provision with the bare metal server. type: str choices: ['redHat6_64Bit', 'centOS6_64Bit', 'windows2012R2Standard_64Bit', 'ubuntu14_64Bit'] wait: @@ -203,23 +201,21 @@ type: bool default: true requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" # Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - name: Provision a single Ubuntu Server @@ -255,29 +251,21 @@ server_ids: - UC1ACCT-TEST01 state: absent -''' +""" -RETURN = ''' +RETURN = r""" server_ids: - description: The list of server ids that are created - returned: success - type: list - sample: - [ - "UC1TEST-SVR01", - "UC1TEST-SVR02" - ] + description: The list of server ids that are created. + returned: success + type: list + sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"] partially_created_server_ids: - description: The list of server ids that are partially created - returned: success - type: list - sample: - [ - "UC1TEST-SVR01", - "UC1TEST-SVR02" - ] + description: The list of server ids that are partially created. + returned: success + type: list + sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"] servers: - description: The list of server objects returned from CLC + description: The list of server objects returned from CLC. returned: success type: list sample: @@ -433,7 +421,7 @@ "type":"standard" } ] -''' +""" __version__ = '${version}' diff --git a/plugins/modules/clc_server_snapshot.py b/plugins/modules/clc_server_snapshot.py index 82b2a995680..d9eaf9abe14 100644 --- a/plugins/modules/clc_server_snapshot.py +++ b/plugins/modules/clc_server_snapshot.py @@ -9,7 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: clc_server_snapshot short_description: Create, Delete and Restore server snapshots in CenturyLink Cloud description: @@ -48,30 +48,28 @@ required: false type: str requirements: - - python = 2.7 - - requests >= 2.5.0 - - clc-sdk + - requests >= 2.5.0 + - clc-sdk author: "CLC Runner (@clc-runner)" notes: - - To use this module, it is required to set the below environment variables which enables access to the - Centurylink Cloud - - CLC_V2_API_USERNAME, the account login id for the centurylink cloud - - CLC_V2_API_PASSWORD, the account password for the centurylink cloud - - Alternatively, the module accepts the API token and account alias. The API token can be generated using the - CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login - - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login - - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud - - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment. -''' - -EXAMPLES = ''' + - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud. + - E(CLC_V2_API_USERNAME), the account login id for the Centurylink Cloud. + - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud. + - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account + login and password using the HTTP API call @ https://api.ctl.io/v2/authentication/login + - E(CLC_V2_API_TOKEN), the API token generated from https://api.ctl.io/v2/authentication/login + - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud. + - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment. +""" + +EXAMPLES = r""" # Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples - name: Create server snapshot community.general.clc_server_snapshot: server_ids: - - UC1TEST-SVR01 - - UC1TEST-SVR02 + - UC1TEST-SVR01 + - UC1TEST-SVR02 expiration_days: 10 wait: true state: present @@ -79,31 +77,27 @@ - name: Restore server snapshot community.general.clc_server_snapshot: server_ids: - - UC1TEST-SVR01 - - UC1TEST-SVR02 + - UC1TEST-SVR01 + - UC1TEST-SVR02 wait: true state: restore - name: Delete server snapshot community.general.clc_server_snapshot: server_ids: - - UC1TEST-SVR01 - - UC1TEST-SVR02 + - UC1TEST-SVR01 + - UC1TEST-SVR02 wait: true state: absent -''' +""" -RETURN = ''' +RETURN = r""" server_ids: - description: The list of server ids that are changed - returned: success - type: list - sample: - [ - "UC1TEST-SVR01", - "UC1TEST-SVR02" - ] -''' + description: The list of server ids that are changed. + returned: success + type: list + sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"] +""" __version__ = '${version}' diff --git a/plugins/modules/cloud_init_data_facts.py b/plugins/modules/cloud_init_data_facts.py index d8209cc61ae..360b4119ef7 100644 --- a/plugins/modules/cloud_init_data_facts.py +++ b/plugins/modules/cloud_init_data_facts.py @@ -8,12 +8,11 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: cloud_init_data_facts short_description: Retrieve facts of cloud-init description: - - Gathers facts by reading the status.json and result.json of cloud-init. + - Gathers facts by reading the C(status.json) and C(result.json) of cloud-init. author: René Moser (@resmo) extends_documentation_fragment: - community.general.attributes @@ -22,14 +21,14 @@ options: filter: description: - - Filter facts + - Filter facts. type: str - choices: [ status, result ] + choices: [status, result] notes: - See http://cloudinit.readthedocs.io/ for more information about cloud-init. -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Gather all facts of cloud init community.general.cloud_init_data_facts: register: result @@ -44,10 +43,9 @@ until: "res.cloud_init_data_facts.status.v1.stage is defined and not res.cloud_init_data_facts.status.v1.stage" retries: 50 delay: 5 -''' +""" -RETURN = ''' ---- +RETURN = r""" cloud_init_data_facts: description: Facts of result and status. returned: success @@ -84,7 +82,7 @@ "stage": null } }' -''' +""" import os diff --git a/plugins/modules/cloudflare_dns.py b/plugins/modules/cloudflare_dns.py index a2bcc79f8e9..4ffbe109d5e 100644 --- a/plugins/modules/cloudflare_dns.py +++ b/plugins/modules/cloudflare_dns.py @@ -8,16 +8,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: cloudflare_dns author: -- Michael Gruener (@mgruener) + - Michael Gruener (@mgruener) short_description: Manage Cloudflare DNS records description: - - "Manages dns records via the Cloudflare API, see the docs: U(https://api.cloudflare.com/)." + - 'Manages dns records using the Cloudflare API, see the docs: U(https://api.cloudflare.com/).' extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -26,161 +25,162 @@ options: api_token: description: - - API token. - - Required for api token authentication. - - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)." - - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0. + - API token. + - Required for api token authentication. + - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)." + - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0. type: str version_added: '0.2.0' account_api_key: description: - - Account API key. - - Required for api keys authentication. - - "You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)." + - Account API key. + - Required for api keys authentication. + - "You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)." type: str - aliases: [ account_api_token ] + aliases: [account_api_token] account_email: description: - - Account email. Required for API keys authentication. + - Account email. Required for API keys authentication. type: str algorithm: description: - - Algorithm number. - - Required for O(type=DS) and O(type=SSHFP) when O(state=present). + - Algorithm number. + - Required for O(type=DS) and O(type=SSHFP) when O(state=present). type: int cert_usage: description: - - Certificate usage number. - - Required for O(type=TLSA) when O(state=present). + - Certificate usage number. + - Required for O(type=TLSA) when O(state=present). type: int - choices: [ 0, 1, 2, 3 ] + choices: [0, 1, 2, 3] comment: description: - - Comments or notes about the DNS record. + - Comments or notes about the DNS record. type: str version_added: 10.1.0 flag: description: - - Issuer Critical Flag. - - Required for O(type=CAA) when O(state=present). + - Issuer Critical Flag. + - Required for O(type=CAA) when O(state=present). type: int - choices: [ 0, 1 ] + choices: [0, 1] version_added: 8.0.0 tag: description: - - CAA issue restriction. - - Required for O(type=CAA) when O(state=present). + - CAA issue restriction. + - Required for O(type=CAA) when O(state=present). type: str - choices: [ issue, issuewild, iodef ] + choices: [issue, issuewild, iodef] version_added: 8.0.0 hash_type: description: - - Hash type number. - - Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present). + - Hash type number. + - Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present). type: int - choices: [ 1, 2 ] + choices: [1, 2] key_tag: description: - - DNSSEC key tag. - - Needed for O(type=DS) when O(state=present). + - DNSSEC key tag. + - Needed for O(type=DS) when O(state=present). type: int port: description: - - Service port. - - Required for O(type=SRV) and O(type=TLSA). + - Service port. + - Required for O(type=SRV) and O(type=TLSA). type: int priority: description: - - Record priority. - - Required for O(type=MX) and O(type=SRV) + - Record priority. + - Required for O(type=MX) and O(type=SRV). default: 1 type: int proto: description: - - Service protocol. Required for O(type=SRV) and O(type=TLSA). - - Common values are TCP and UDP. + - Service protocol. Required for O(type=SRV) and O(type=TLSA). + - Common values are TCP and UDP. type: str proxied: description: - - Proxy through Cloudflare network or just use DNS. + - Proxy through Cloudflare network or just use DNS. type: bool default: false record: description: - - Record to add. - - Required if O(state=present). - - Default is V(@) (that is, the zone name). + - Record to add. + - Required if O(state=present). + - Default is V(@) (that is, the zone name). type: str default: '@' - aliases: [ name ] + aliases: [name] selector: description: - - Selector number. - - Required for O(type=TLSA) when O(state=present). - choices: [ 0, 1 ] + - Selector number. + - Required for O(type=TLSA) when O(state=present). + choices: [0, 1] type: int service: description: - - Record service. - - Required for O(type=SRV). + - Record service. + - Required for O(type=SRV). type: str solo: description: - - Whether the record should be the only one for that record type and record name. - - Only use with O(state=present). - - This will delete all other records with the same record name and type. + - Whether the record should be the only one for that record type and record name. + - Only use with O(state=present). + - This will delete all other records with the same record name and type. type: bool state: description: - - Whether the record(s) should exist or not. + - Whether the record(s) should exist or not. type: str - choices: [ absent, present ] + choices: [absent, present] default: present tags: description: - - Custom tags for the DNS record. + - Custom tags for the DNS record. type: list elements: str version_added: 10.1.0 timeout: description: - - Timeout for Cloudflare API calls. + - Timeout for Cloudflare API calls. type: int default: 30 ttl: description: - - The TTL to give the new record. - - Must be between 120 and 2,147,483,647 seconds, or 1 for automatic. + - The TTL to give the new record. + - Must be between V(120) and V(2,147,483,647) seconds, or V(1) for automatic. type: int default: 1 type: description: - The type of DNS record to create. Required if O(state=present). - - Support for V(SPF) has been removed from community.general 9.0.0 since that record type is no longer supported by CloudFlare. + - Support for V(SPF) has been removed from community.general 9.0.0 since that record type is no longer supported by + CloudFlare. type: str - choices: [ A, AAAA, CNAME, DS, MX, NS, SRV, SSHFP, TLSA, CAA, TXT ] + choices: [A, AAAA, CNAME, DS, MX, NS, SRV, SSHFP, TLSA, CAA, TXT] value: description: - - The record value. - - Required for O(state=present). + - The record value. + - Required for O(state=present). type: str - aliases: [ content ] + aliases: [content] weight: description: - - Service weight. - - Required for O(type=SRV). + - Service weight. + - Required for O(type=SRV). type: int default: 1 zone: description: - - The name of the Zone to work with (e.g. "example.com"). - - The Zone must already exist. + - The name of the Zone to work with (for example V(example.com)). + - The Zone must already exist. type: str required: true - aliases: [ domain ] -''' + aliases: [domain] +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a test.example.net A record to point to 127.0.0.1 community.general.cloudflare_dns: zone: example.net @@ -207,8 +207,8 @@ value: 127.0.0.1 comment: Local test website tags: - - test - - local + - test + - local api_token: dummyapitoken - name: Create a example.net CNAME record to example.com @@ -311,123 +311,116 @@ algorithm: 8 hash_type: 2 value: B4EB5AC4467D2DFB3BAF9FB9961DC1B6FED54A58CDFAA3E465081EC86F89BFAB -''' +""" -RETURN = r''' +RETURN = r""" record: - description: A dictionary containing the record data. - returned: success, except on record deletion - type: complex - contains: - comment: - description: Comments or notes about the DNS record. - returned: success - type: str - sample: Domain verification record - version_added: 10.1.0 - comment_modified_on: - description: When the record comment was last modified. Omitted if there is no comment. - returned: success - type: str - sample: "2024-01-01T05:20:00.12345Z" - version_added: 10.1.0 - content: - description: The record content (details depend on record type). - returned: success - type: str - sample: 192.0.2.91 - created_on: - description: The record creation date. - returned: success - type: str - sample: "2016-03-25T19:09:42.516553Z" - data: - description: Additional record data. - returned: success, if type is SRV, DS, SSHFP TLSA or CAA - type: dict - sample: { - name: "jabber", - port: 8080, - priority: 10, - proto: "_tcp", - service: "_xmpp", - target: "jabberhost.sample.com", - weight: 5, - } - id: - description: The record ID. - returned: success - type: str - sample: f9efb0549e96abcb750de63b38c9576e - locked: - description: No documentation available. - returned: success - type: bool - sample: false - meta: - description: Extra Cloudflare-specific information about the record. - returned: success - type: dict - sample: { auto_added: false } - modified_on: - description: Record modification date. - returned: success - type: str - sample: "2016-03-25T19:09:42.516553Z" - name: - description: The record name as FQDN (including _service and _proto for SRV). - returned: success - type: str - sample: www.sample.com - priority: - description: Priority of the MX record. - returned: success, if type is MX - type: int - sample: 10 - proxiable: - description: Whether this record can be proxied through Cloudflare. - returned: success - type: bool - sample: false - proxied: - description: Whether the record is proxied through Cloudflare. - returned: success - type: bool - sample: false - tags: - description: Custom tags for the DNS record. - returned: success - type: list - elements: str - sample: ['production', 'app'] - version_added: 10.1.0 - tags_modified_on: - description: When the record tags were last modified. Omitted if there are no tags. - returned: success - type: str - sample: "2025-01-01T05:20:00.12345Z" - version_added: 10.1.0 - ttl: - description: The time-to-live for the record. - returned: success - type: int - sample: 300 - type: - description: The record type. - returned: success - type: str - sample: A - zone_id: - description: The ID of the zone containing the record. - returned: success - type: str - sample: abcede0bf9f0066f94029d2e6b73856a - zone_name: - description: The name of the zone containing the record. - returned: success - type: str - sample: sample.com -''' + description: A dictionary containing the record data. + returned: success, except on record deletion + type: complex + contains: + comment: + description: Comments or notes about the DNS record. + returned: success + type: str + sample: Domain verification record + version_added: 10.1.0 + comment_modified_on: + description: When the record comment was last modified. Omitted if there is no comment. + returned: success + type: str + sample: "2024-01-01T05:20:00.12345Z" + version_added: 10.1.0 + content: + description: The record content (details depend on record type). + returned: success + type: str + sample: 192.0.2.91 + created_on: + description: The record creation date. + returned: success + type: str + sample: "2016-03-25T19:09:42.516553Z" + data: + description: Additional record data. + returned: success, if type is SRV, DS, SSHFP TLSA or CAA + type: dict + sample: {name: "jabber", port: 8080, priority: 10, proto: "_tcp", service: "_xmpp", target: "jabberhost.sample.com", + weight: 5} + id: + description: The record ID. + returned: success + type: str + sample: f9efb0549e96abcb750de63b38c9576e + locked: + description: No documentation available. + returned: success + type: bool + sample: false + meta: + description: Extra Cloudflare-specific information about the record. + returned: success + type: dict + sample: {auto_added: false} + modified_on: + description: Record modification date. + returned: success + type: str + sample: "2016-03-25T19:09:42.516553Z" + name: + description: The record name as FQDN (including _service and _proto for SRV). + returned: success + type: str + sample: www.sample.com + priority: + description: Priority of the MX record. + returned: success, if type is MX + type: int + sample: 10 + proxiable: + description: Whether this record can be proxied through Cloudflare. + returned: success + type: bool + sample: false + proxied: + description: Whether the record is proxied through Cloudflare. + returned: success + type: bool + sample: false + tags: + description: Custom tags for the DNS record. + returned: success + type: list + elements: str + sample: ['production', 'app'] + version_added: 10.1.0 + tags_modified_on: + description: When the record tags were last modified. Omitted if there are no tags. + returned: success + type: str + sample: "2025-01-01T05:20:00.12345Z" + version_added: 10.1.0 + ttl: + description: The time-to-live for the record. + returned: success + type: int + sample: 300 + type: + description: The record type. + returned: success + type: str + sample: A + zone_id: + description: The ID of the zone containing the record. + returned: success + type: str + sample: abcede0bf9f0066f94029d2e6b73856a + zone_name: + description: The name of the zone containing the record. + returned: success + type: str + sample: sample.com +""" import json diff --git a/plugins/modules/cobbler_sync.py b/plugins/modules/cobbler_sync.py index 27f57028beb..95a3241b98d 100644 --- a/plugins/modules/cobbler_sync.py +++ b/plugins/modules/cobbler_sync.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: cobbler_sync short_description: Sync Cobbler description: @@ -24,44 +23,44 @@ options: host: description: - - The name or IP address of the Cobbler system. + - The name or IP address of the Cobbler system. default: 127.0.0.1 type: str port: description: - - Port number to be used for REST connection. - - The default value depends on parameter O(use_ssl). + - Port number to be used for REST connection. + - The default value depends on parameter O(use_ssl). type: int username: description: - - The username to log in to Cobbler. + - The username to log in to Cobbler. default: cobbler type: str password: description: - - The password to log in to Cobbler. + - The password to log in to Cobbler. type: str use_ssl: description: - - If V(false), an HTTP connection will be used instead of the default HTTPS connection. + - If V(false), an HTTP connection will be used instead of the default HTTPS connection. type: bool default: true validate_certs: description: - - If V(false), SSL certificates will not be validated. - - This should only set to V(false) when used on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. + - This should only set to V(false) when used on personally controlled sites using self-signed certificates. type: bool default: true author: -- Dag Wieers (@dagwieers) + - Dag Wieers (@dagwieers) todo: notes: -- Concurrently syncing Cobbler is bound to fail with weird errors. -- On python 2.7.8 and older (i.e. on RHEL7) you may need to tweak the python behaviour to disable certificate validation. - More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753). -''' + - Concurrently syncing Cobbler is bound to fail with weird errors. + - On Python 2.7.8 and older (such as RHEL7) you may need to tweak the Python behaviour to disable certificate validation. + More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753). +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Commit Cobbler changes community.general.cobbler_sync: host: cobbler01 @@ -69,11 +68,11 @@ password: MySuperSecureP4sswOrd run_once: true delegate_to: localhost -''' +""" -RETURN = r''' +RETURN = r""" # Default return values -''' +""" import ssl diff --git a/plugins/modules/cobbler_system.py b/plugins/modules/cobbler_system.py index a327ede84be..fd1db6bf3e7 100644 --- a/plugins/modules/cobbler_system.py +++ b/plugins/modules/cobbler_system.py @@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: cobbler_system short_description: Manage system objects in Cobbler description: - - Add, modify or remove systems in Cobbler + - Add, modify or remove systems in Cobbler. extends_documentation_fragment: - community.general.attributes attributes: @@ -24,67 +23,67 @@ options: host: description: - - The name or IP address of the Cobbler system. + - The name or IP address of the Cobbler system. default: 127.0.0.1 type: str port: description: - - Port number to be used for REST connection. - - The default value depends on parameter O(use_ssl). + - Port number to be used for REST connection. + - The default value depends on parameter O(use_ssl). type: int username: description: - - The username to log in to Cobbler. + - The username to log in to Cobbler. default: cobbler type: str password: description: - - The password to log in to Cobbler. + - The password to log in to Cobbler. type: str use_ssl: description: - - If V(false), an HTTP connection will be used instead of the default HTTPS connection. + - If V(false), an HTTP connection will be used instead of the default HTTPS connection. type: bool default: true validate_certs: description: - - If V(false), SSL certificates will not be validated. - - This should only set to V(false) when used on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. + - This should only set to V(false) when used on personally controlled sites using self-signed certificates. type: bool default: true name: description: - - The system name to manage. + - The system name to manage. type: str properties: description: - - A dictionary with system properties. + - A dictionary with system properties. type: dict interfaces: description: - - A list of dictionaries containing interface options. + - A list of dictionaries containing interface options. type: dict sync: description: - - Sync on changes. - - Concurrently syncing Cobbler is bound to fail. + - Sync on changes. + - Concurrently syncing Cobbler is bound to fail. type: bool default: false state: description: - - Whether the system should be present, absent or a query is made. - choices: [ absent, present, query ] + - Whether the system should be present, absent or a query is made. + choices: [absent, present, query] default: present type: str author: -- Dag Wieers (@dagwieers) + - Dag Wieers (@dagwieers) notes: -- Concurrently syncing Cobbler is bound to fail with weird errors. -- On python 2.7.8 and older (i.e. on RHEL7) you may need to tweak the python behaviour to disable certificate validation. - More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753). -''' + - Concurrently syncing Cobbler is bound to fail with weird errors. + - On Python 2.7.8 and older (such as RHEL7) you may need to tweak the Python behaviour to disable certificate validation. + More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753). +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure the system exists in Cobbler community.general.cobbler_system: host: cobbler01 @@ -93,7 +92,7 @@ name: myhost properties: profile: CentOS6-x86_64 - name_servers: [ 2.3.4.5, 3.4.5.6 ] + name_servers: [2.3.4.5, 3.4.5.6] name_servers_search: foo.com, bar.com interfaces: eth0: @@ -139,18 +138,18 @@ name: myhost state: absent delegate_to: localhost -''' +""" -RETURN = r''' +RETURN = r""" systems: - description: List of systems + description: List of systems. returned: O(state=query) and O(name) is not provided type: list system: - description: (Resulting) information about the system we are working with + description: (Resulting) information about the system we are working with. returned: when O(name) is provided type: dict -''' +""" import ssl diff --git a/plugins/modules/composer.py b/plugins/modules/composer.py index 3d1c4a3465a..59f3a151688 100644 --- a/plugins/modules/composer.py +++ b/plugins/modules/composer.py @@ -9,115 +9,113 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: composer author: - - "Dimitrios Tydeas Mengidis (@dmtrs)" - - "René Moser (@resmo)" + - "Dimitrios Tydeas Mengidis (@dmtrs)" + - "René Moser (@resmo)" short_description: Dependency Manager for PHP description: - - > - Composer is a tool for dependency management in PHP. It allows you to - declare the dependent libraries your project needs and it will install - them in your project for you. + - Composer is a tool for dependency management in PHP. It allows you to declare the dependent libraries your project needs + and it will install them in your project for you. 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: - command: - type: str - description: - - Composer command like "install", "update" and so on. - default: install - arguments: - type: str - description: - - Composer arguments like required package, version and so on. - default: '' - executable: - type: path - description: - - Path to PHP Executable on the remote host, if PHP is not in PATH. - aliases: [ php_path ] - working_dir: - type: path - description: - - Directory of your project (see --working-dir). This is required when - the command is not run globally. - - Will be ignored if O(global_command=true). - global_command: - description: - - Runs the specified command globally. - type: bool - default: false - prefer_source: - description: - - Forces installation from package sources when possible (see --prefer-source). - default: false - type: bool - prefer_dist: - description: - - Forces installation from package dist even for dev versions (see --prefer-dist). - default: false - type: bool - no_dev: - description: - - Disables installation of require-dev packages (see --no-dev). - default: true - type: bool - no_scripts: - description: - - Skips the execution of all scripts defined in composer.json (see --no-scripts). - default: false - type: bool - no_plugins: - description: - - Disables all plugins (see --no-plugins). - default: false - type: bool - optimize_autoloader: - description: - - Optimize autoloader during autoloader dump (see --optimize-autoloader). - - Convert PSR-0/4 autoloading to classmap to get a faster autoloader. - - Recommended especially for production, but can take a bit of time to run. - default: true - type: bool - classmap_authoritative: - description: - - Autoload classes from classmap only. - - Implicitly enable optimize_autoloader. - - Recommended especially for production, but can take a bit of time to run. - default: false - type: bool - apcu_autoloader: - description: - - Uses APCu to cache found/not-found classes - default: false - type: bool - ignore_platform_reqs: - description: - - Ignore php, hhvm, lib-* and ext-* requirements and force the installation even if the local machine does not fulfill these. - default: false - type: bool - composer_executable: - type: path - description: - - Path to composer executable on the remote host, if composer is not in E(PATH) or a custom composer is needed. - version_added: 3.2.0 + command: + type: str + description: + - Composer command like V(install), V(update) and so on. + default: install + arguments: + type: str + description: + - Composer arguments like required package, version and so on. + default: '' + executable: + type: path + description: + - Path to PHP executable on the remote host, if PHP is not in E(PATH). + aliases: [php_path] + working_dir: + type: path + description: + - Directory of your project (see C(--working-dir)). This is required when the command is not run globally. + - Will be ignored if O(global_command=true). + global_command: + description: + - Runs the specified command globally. + type: bool + default: false + prefer_source: + description: + - Forces installation from package sources when possible (see C(--prefer-source)). + default: false + type: bool + prefer_dist: + description: + - Forces installation from package dist even for dev versions (see C(--prefer-dist)). + default: false + type: bool + no_dev: + description: + - Disables installation of require-dev packages (see C(--no-dev)). + default: true + type: bool + no_scripts: + description: + - Skips the execution of all scripts defined in composer.json (see C(--no-scripts)). + default: false + type: bool + no_plugins: + description: + - Disables all plugins (see C(--no-plugins)). + default: false + type: bool + optimize_autoloader: + description: + - Optimize autoloader during autoloader dump (see C(--optimize-autoloader)). + - Convert PSR-0/4 autoloading to classmap to get a faster autoloader. + - Recommended especially for production, but can take a bit of time to run. + default: true + type: bool + classmap_authoritative: + description: + - Autoload classes from classmap only. + - Implicitly enable optimize_autoloader. + - Recommended especially for production, but can take a bit of time to run. + default: false + type: bool + apcu_autoloader: + description: + - Uses APCu to cache found/not-found classes. + default: false + type: bool + ignore_platform_reqs: + description: + - Ignore php, hhvm, lib-* and ext-* requirements and force the installation even if the local machine does not fulfill + these. + default: false + type: bool + composer_executable: + type: path + description: + - Path to composer executable on the remote host, if composer is not in E(PATH) or a custom composer is needed. + version_added: 3.2.0 requirements: - - php - - composer installed in bin path (recommended /usr/local/bin) or specified in O(composer_executable) + - php + - composer installed in bin path (recommended C(/usr/local/bin)) or specified in O(composer_executable) notes: - - Default options that are always appended in each execution are --no-ansi, --no-interaction and --no-progress if available. - - We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method to avoid issues. -''' + - Default options that are always appended in each execution are C(--no-ansi), C(--no-interaction) and C(--no-progress) if available. + - We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method + to avoid issues. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Download and installs all libs and dependencies outlined in the /path/to/project/composer.lock community.general.composer: command: install @@ -141,7 +139,7 @@ command: require global_command: true arguments: my/package -''' +""" import re from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/consul.py b/plugins/modules/consul.py index 28beeec52db..84624e3489f 100644 --- a/plugins/modules/consul.py +++ b/plugins/modules/consul.py @@ -9,26 +9,21 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: consul -short_description: Add, modify & delete services within a consul cluster +short_description: Add, modify & delete services within a Consul cluster description: - - Registers services and checks for an agent with a consul cluster. - A service is some process running on the agent node that should be advertised by - consul's discovery mechanism. It may optionally supply a check definition, - a periodic service test to notify the consul cluster of service's health. - - "Checks may also be registered per node e.g. disk usage, or cpu usage and - notify the health of the entire node to the cluster. - Service level checks do not require a check name or id as these are derived - by Consul from the Service name and id respectively by appending 'service:' - Node level checks require a O(check_name) and optionally a O(check_id)." - - Currently, there is no complete way to retrieve the script, interval or TTL - metadata for a registered check. Without this metadata it is not possible to - tell if the data supplied with ansible represents a change to a check. As a - result this does not attempt to determine changes and will always report a - changed occurred. An API method is planned to supply this metadata so at that - stage change management will be added. - - "See U(http://consul.io) for more details." + - Registers services and checks for an agent with a Consul cluster. A service is some process running on the agent node + that should be advertised by Consul's discovery mechanism. It may optionally supply a check definition, a periodic service + test to notify the Consul cluster of service's health. + - Checks may also be registered per node, for example disk usage, or cpu usage and notify the health of the entire node to the cluster. + Service level checks do not require a check name or id as these are derived by Consul from the Service name and id respectively + by appending V(service:) Node level checks require a O(check_name) and optionally a O(check_id). + - Currently, there is no complete way to retrieve the script, interval or TTL metadata for a registered check. Without this + metadata it is not possible to tell if the data supplied with ansible represents a change to a check. As a result this + does not attempt to determine changes and will always report a changed occurred. An API method is planned to supply this + metadata so at that stage change management will be added. + - See U(http://consul.io) for more details. requirements: - python-consul - requests @@ -41,139 +36,127 @@ diff_mode: support: none options: - state: - type: str - description: - - Register or deregister the consul service, defaults to present. - default: present - choices: ['present', 'absent'] - service_name: - type: str - description: - - Unique name for the service on a node, must be unique per node, - required if registering a service. May be omitted if registering - a node level check. - service_id: - type: str - description: - - The ID for the service, must be unique per node. If O(state=absent), - defaults to the service name if supplied. - host: - type: str - description: - - Host of the consul agent defaults to localhost. - default: localhost - port: - type: int - description: - - The port on which the consul agent is running. - default: 8500 - scheme: - type: str - description: - - The protocol scheme on which the consul agent is running. - default: http - validate_certs: - description: - - Whether to verify the TLS certificate of the consul agent. - type: bool - default: true - notes: - type: str - description: - - Notes to attach to check when registering it. - service_port: - type: int - description: - - The port on which the service is listening. Can optionally be supplied for - registration of a service, that is if O(service_name) or O(service_id) is set. - service_address: - type: str - description: - - The address to advertise that the service will be listening on. - This value will be passed as the C(address) parameter to Consul's - C(/v1/agent/service/register) API method, so refer to the Consul API - documentation for further details. - tags: - type: list - elements: str - description: - - Tags that will be attached to the service registration. - script: - type: str - description: - - The script/command that will be run periodically to check the health of the service. - - Requires O(interval) to be provided. - - Mutually exclusive with O(ttl), O(tcp) and O(http). - interval: - type: str - description: - - The interval at which the service check will be run. - This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). - If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). - - Required if one of the parameters O(script), O(http), or O(tcp) is specified. - check_id: - type: str - description: - - An ID for the service check. If O(state=absent), defaults to - O(check_name). Ignored if part of a service definition. - check_name: - type: str - description: - - Name for the service check. Required if standalone, ignored if - part of service definition. - check_node: - description: - - Node name. - # TODO: properly document! - type: str - check_host: - description: - - Host name. - # TODO: properly document! - type: str - ttl: - type: str - description: - - Checks can be registered with a TTL instead of a O(script) and O(interval) - this means that the service will check in with the agent before the - TTL expires. If it doesn't the check will be considered failed. - Required if registering a check and the script an interval are missing - Similar to the interval this is a number with a V(s) or V(m) suffix to - signify the units of seconds or minutes, for example V(15s) or V(1m). - If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). - - Mutually exclusive with O(script), O(tcp) and O(http). - tcp: - type: str - description: - - Checks can be registered with a TCP port. This means that consul - will check if the connection attempt to that port is successful (that is, the port is currently accepting connections). - The format is V(host:port), for example V(localhost:80). - - Requires O(interval) to be provided. - - Mutually exclusive with O(script), O(ttl) and O(http). - version_added: '1.3.0' - http: - type: str - description: - - Checks can be registered with an HTTP endpoint. This means that consul - will check that the http endpoint returns a successful HTTP status. - - Requires O(interval) to be provided. - - Mutually exclusive with O(script), O(ttl) and O(tcp). - timeout: - type: str - description: - - A custom HTTP check timeout. The consul default is 10 seconds. - Similar to the interval this is a number with a V(s) or V(m) suffix to - signify the units of seconds or minutes, for example V(15s) or V(1m). - If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). - token: - type: str - description: - - The token key identifying an ACL rule set. May be required to register services. -''' - -EXAMPLES = ''' -- name: Register nginx service with the local consul agent + state: + type: str + description: + - Register or deregister the Consul service, defaults to present. + default: present + choices: ['present', 'absent'] + service_name: + type: str + description: + - Unique name for the service on a node, must be unique per node, required if registering a service. May be omitted + if registering a node level check. + service_id: + type: str + description: + - The ID for the service, must be unique per node. If O(state=absent), defaults to the service name if supplied. + host: + type: str + description: + - Host of the Consul agent defaults to localhost. + default: localhost + port: + type: int + description: + - The port on which the Consul agent is running. + default: 8500 + scheme: + type: str + description: + - The protocol scheme on which the Consul agent is running. + default: http + validate_certs: + description: + - Whether to verify the TLS certificate of the Consul agent. + type: bool + default: true + notes: + type: str + description: + - Notes to attach to check when registering it. + service_port: + type: int + description: + - The port on which the service is listening. Can optionally be supplied for registration of a service, that is if O(service_name) + or O(service_id) is set. + service_address: + type: str + description: + - The address to advertise that the service will be listening on. This value will be passed as the C(address) parameter + to Consul's C(/v1/agent/service/register) API method, so refer to the Consul API documentation for further details. + tags: + type: list + elements: str + description: + - Tags that will be attached to the service registration. + script: + type: str + description: + - The script/command that will be run periodically to check the health of the service. + - Requires O(interval) to be provided. + - Mutually exclusive with O(ttl), O(tcp) and O(http). + interval: + type: str + description: + - The interval at which the service check will be run. This is a number with a V(s) or V(m) suffix to signify the units + of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used by default, for example + V(10) will be V(10s). + - Required if one of the parameters O(script), O(http), or O(tcp) is specified. + check_id: + type: str + description: + - An ID for the service check. If O(state=absent), defaults to O(check_name). Ignored if part of a service definition. + check_name: + type: str + description: + - Name for the service check. Required if standalone, ignored if part of service definition. + check_node: + description: + - Node name. + type: str + check_host: + description: + - Host name. + type: str + ttl: + type: str + description: + - Checks can be registered with a TTL instead of a O(script) and O(interval) this means that the service will check + in with the agent before the TTL expires. If it does not the check will be considered failed. Required if registering + a check and the script an interval are missing Similar to the interval this is a number with a V(s) or V(m) suffix + to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used + by default, for example V(10) will be V(10s). + - Mutually exclusive with O(script), O(tcp) and O(http). + tcp: + type: str + description: + - Checks can be registered with a TCP port. This means that Consul will check if the connection attempt to that port + is successful (that is, the port is currently accepting connections). The format is V(host:port), for example V(localhost:80). + - Requires O(interval) to be provided. + - Mutually exclusive with O(script), O(ttl) and O(http). + version_added: '1.3.0' + http: + type: str + description: + - Checks can be registered with an HTTP endpoint. This means that Consul will check that the http endpoint returns a + successful HTTP status. + - Requires O(interval) to be provided. + - Mutually exclusive with O(script), O(ttl) and O(tcp). + timeout: + type: str + description: + - A custom HTTP check timeout. The Consul default is 10 seconds. Similar to the interval this is a number with a V(s) + or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) + will be used by default, for example V(10) will be V(10s). + token: + type: str + description: + - The token key identifying an ACL rule set. May be required to register services. +""" + +EXAMPLES = r""" +- name: Register nginx service with the local Consul agent community.general.consul: service_name: nginx service_port: 80 @@ -239,7 +222,7 @@ service_id: nginx interval: 60s http: http://localhost:80/morestatus -''' +""" try: import consul diff --git a/plugins/modules/consul_acl_bootstrap.py b/plugins/modules/consul_acl_bootstrap.py index bf1da110bf3..7002c3d549d 100644 --- a/plugins/modules/consul_acl_bootstrap.py +++ b/plugins/modules/consul_acl_bootstrap.py @@ -9,13 +9,13 @@ __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: consul_acl_bootstrap short_description: Bootstrap ACLs in Consul version_added: 8.3.0 description: - - Allows bootstrapping of ACLs in a Consul cluster, see - U(https://developer.hashicorp.com/consul/api-docs/acl#bootstrap-acls) for details. + - Allows bootstrapping of ACLs in a Consul cluster, see U(https://developer.hashicorp.com/consul/api-docs/acl#bootstrap-acls) + for details. author: - Florian Apolloner (@apollo13) extends_documentation_fragment: @@ -40,35 +40,33 @@ type: str """ -EXAMPLES = """ +EXAMPLES = r""" - name: Bootstrap the ACL system community.general.consul_acl_bootstrap: bootstrap_secret: 22eaeed1-bdbd-4651-724e-42ae6c43e387 """ -RETURN = """ +RETURN = r""" result: - description: - - The bootstrap result as returned by the consul HTTP API. - - "B(Note:) If O(bootstrap_secret) has been specified the C(SecretID) and - C(ID) will not contain the secret but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). - If you pass O(bootstrap_secret), make sure your playbook/role does not depend - on this return value!" - returned: changed - type: dict - sample: - AccessorID: 834a5881-10a9-a45b-f63c-490e28743557 - CreateIndex: 25 - CreateTime: '2024-01-21T20:26:27.114612038+01:00' - Description: Bootstrap Token (Global Management) - Hash: X2AgaFhnQGRhSSF/h0m6qpX1wj/HJWbyXcxkEM/5GrY= - ID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER - Local: false - ModifyIndex: 25 - Policies: + description: + - The bootstrap result as returned by the Consul HTTP API. + - B(Note:) If O(bootstrap_secret) has been specified the C(SecretID) and C(ID) will not contain the secret but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). + If you pass O(bootstrap_secret), make sure your playbook/role does not depend on this return value! + returned: changed + type: dict + sample: + AccessorID: 834a5881-10a9-a45b-f63c-490e28743557 + CreateIndex: 25 + CreateTime: '2024-01-21T20:26:27.114612038+01:00' + Description: Bootstrap Token (Global Management) + Hash: X2AgaFhnQGRhSSF/h0m6qpX1wj/HJWbyXcxkEM/5GrY= + ID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER + Local: false + ModifyIndex: 25 + Policies: - ID: 00000000-0000-0000-0000-000000000001 Name: global-management - SecretID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER + SecretID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/consul_agent_check.py b/plugins/modules/consul_agent_check.py index 37392600497..ca1639063cd 100644 --- a/plugins/modules/consul_agent_check.py +++ b/plugins/modules/consul_agent_check.py @@ -9,20 +9,17 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: consul_agent_check -short_description: Add, modify, and delete checks within a consul cluster +short_description: Add, modify, and delete checks within a Consul cluster version_added: 9.1.0 description: - - Allows the addition, modification and deletion of checks in a consul - cluster via the agent. For more details on using and configuring Checks, - see U(https://developer.hashicorp.com/consul/api-docs/agent/check). - - Currently, there is no complete way to retrieve the script, interval or TTL - metadata for a registered check. Without this metadata it is not possible to - tell if the data supplied with ansible represents a change to a check. As a - result this does not attempt to determine changes and will always report a - changed occurred. An API method is planned to supply this metadata so at that - stage change management will be added. + - Allows the addition, modification and deletion of checks in a Consul cluster using the agent. For more details on using + and configuring Checks, see U(https://developer.hashicorp.com/consul/api-docs/agent/check). + - Currently, there is no complete way to retrieve the script, interval or TTL metadata for a registered check. Without this + metadata it is not possible to tell if the data supplied with ansible represents a change to a check. As a result this + does not attempt to determine changes and will always report a changed occurred. An API method is planned to supply this + metadata so at that stage change management will be added. author: - Michael Ilg (@Ilgmi) extends_documentation_fragment: @@ -34,13 +31,13 @@ check_mode: support: full details: - - The result is the object as it is defined in the module options and not the object structure of the consul API. - For a better overview of what the object structure looks like, - take a look at U(https://developer.hashicorp.com/consul/api-docs/agent/check#list-checks). + - The result is the object as it is defined in the module options and not the object structure of the Consul API. For + a better overview of what the object structure looks like, take a look at U(https://developer.hashicorp.com/consul/api-docs/agent/check#list-checks). diff_mode: support: partial details: - - In check mode the diff will show the object as it is defined in the module options and not the object structure of the consul API. + - In check mode the diff will show the object as it is defined in the module options and not the object structure of + the Consul API. options: state: description: @@ -50,18 +47,18 @@ type: str name: description: - - Required name for the service check. + - Required name for the service check. type: str id: description: - - Specifies a unique ID for this check on the node. This defaults to the O(name) parameter, but it may be necessary to provide - an ID for uniqueness. This value will return in the response as "CheckId". + - Specifies a unique ID for this check on the node. This defaults to the O(name) parameter, but it may be necessary + to provide an ID for uniqueness. This value will return in the response as "CheckId". type: str interval: description: - - The interval at which the service check will be run. - This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). - If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). + - The interval at which the service check will be run. This is a number with a V(s) or V(m) suffix to signify the units + of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used by default, for example + V(10) will be V(10s). - Required if one of the parameters O(args), O(http), or O(tcp) is specified. type: str notes: @@ -77,46 +74,41 @@ elements: str ttl: description: - - Checks can be registered with a TTL instead of a O(args) and O(interval) - this means that the service will check in with the agent before the - TTL expires. If it doesn't the check will be considered failed. - Required if registering a check and the script an interval are missing - Similar to the interval this is a number with a V(s) or V(m) suffix to - signify the units of seconds or minutes, for example V(15s) or V(1m). - If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). + - Checks can be registered with a TTL instead of a O(args) and O(interval) this means that the service will check in + with the agent before the TTL expires. If it does not the check will be considered failed. Required if registering + a check and the script an interval are missing Similar to the interval this is a number with a V(s) or V(m) suffix + to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used + by default, for example V(10) will be V(10s). - Mutually exclusive with O(args), O(tcp) and O(http). type: str tcp: description: - - Checks can be registered with a TCP port. This means that consul - will check if the connection attempt to that port is successful (that is, the port is currently accepting connections). - The format is V(host:port), for example V(localhost:80). + - Checks can be registered with a TCP port. This means that Consul will check if the connection attempt to that port + is successful (that is, the port is currently accepting connections). The format is V(host:port), for example V(localhost:80). - Requires O(interval) to be provided. - Mutually exclusive with O(args), O(ttl) and O(http). type: str version_added: '1.3.0' http: description: - - Checks can be registered with an HTTP endpoint. This means that consul - will check that the http endpoint returns a successful HTTP status. + - Checks can be registered with an HTTP endpoint. This means that Consul will check that the http endpoint returns a + successful HTTP status. - Requires O(interval) to be provided. - Mutually exclusive with O(args), O(ttl) and O(tcp). type: str timeout: description: - - A custom HTTP check timeout. The consul default is 10 seconds. - Similar to the interval this is a number with a V(s) or V(m) suffix to - signify the units of seconds or minutes, for example V(15s) or V(1m). - If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). + - A custom HTTP check timeout. The Consul default is 10 seconds. Similar to the interval this is a number with a V(s) + or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) + will be used by default, for example V(10) will be V(10s). type: str service_id: description: - - The ID for the service, must be unique per node. If O(state=absent), - defaults to the service name if supplied. + - The ID for the service, must be unique per node. If O(state=absent), defaults to the service name if supplied. type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Register tcp check for service 'nginx' community.general.consul_agent_check: name: nginx_tcp_check @@ -138,24 +130,24 @@ state: absent id: nginx_http_check service_id: "{{ nginx_service.ID }}" -''' +""" -RETURN = """ +RETURN = r""" check: - description: The check as returned by the consul HTTP API. - returned: always - type: dict - sample: - CheckID: nginx_check - ServiceID: nginx - Interval: 30s - Type: http - Notes: Nginx Check + description: The check as returned by the Consul HTTP API. + returned: always + type: dict + sample: + CheckID: nginx_check + ServiceID: nginx + Interval: 30s + Type: http + Notes: Nginx Check operation: - description: The operation performed. - returned: changed - type: str - sample: update + description: The operation performed. + returned: changed + type: str + sample: update """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/consul_agent_service.py b/plugins/modules/consul_agent_service.py index a8ef0989702..36be3f0d8f1 100644 --- a/plugins/modules/consul_agent_service.py +++ b/plugins/modules/consul_agent_service.py @@ -9,17 +9,15 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: consul_agent_service -short_description: Add, modify and delete services within a consul cluster +short_description: Add, modify and delete services within a Consul cluster version_added: 9.1.0 description: - - Allows the addition, modification and deletion of services in a consul - cluster via the agent. - - There are currently no plans to create services and checks in one. - This is because the Consul API does not provide checks for a service and - the checks themselves do not match the module parameters. - Therefore, only a service without checks can be created in this module. + - Allows the addition, modification and deletion of services in a Consul cluster using the agent. + - There are currently no plans to create services and checks in one. This is because the Consul API does not provide checks + for a service and the checks themselves do not match the module parameters. Therefore, only a service without checks can + be created in this module. author: - Michael Ilg (@Ilgmi) extends_documentation_fragment: @@ -43,13 +41,12 @@ type: str name: description: - - Unique name for the service on a node, must be unique per node, - required if registering a service. + - Unique name for the service on a node, must be unique per node, required if registering a service. type: str id: description: - - Specifies a unique ID for this service. This must be unique per agent. This defaults to the O(name) parameter if not provided. - If O(state=absent), defaults to the service name if supplied. + - Specifies a unique ID for this service. This must be unique per agent. This defaults to the O(name) parameter if not + provided. If O(state=absent), defaults to the service name if supplied. type: str tags: description: @@ -58,36 +55,33 @@ elements: str address: description: - - The address to advertise that the service will be listening on. - This value will be passed as the C(address) parameter to Consul's - C(/v1/agent/service/register) API method, so refer to the Consul API - documentation for further details. + - The address to advertise that the service will be listening on. This value will be passed as the C(address) parameter + to Consul's C(/v1/agent/service/register) API method, so refer to the Consul API documentation for further details. type: str meta: description: - - Optional meta data used for filtering. - For keys, the characters C(A-Z), C(a-z), C(0-9), C(_), C(-) are allowed. - Not allowed characters are replaced with underscores. + - Optional meta data used for filtering. For keys, the characters C(A-Z), C(a-z), C(0-9), C(_), C(-) are allowed. Not + allowed characters are replaced with underscores. type: dict service_port: description: - - The port on which the service is listening. Can optionally be supplied for - registration of a service, that is if O(name) or O(id) is set. + - The port on which the service is listening. Can optionally be supplied for registration of a service, that is if O(name) + or O(id) is set. type: int enable_tag_override: description: - - Specifies to disable the anti-entropy feature for this service's tags. - If EnableTagOverride is set to true then external agents can update this service in the catalog and modify the tags. + - Specifies to disable the anti-entropy feature for this service's tags. If C(EnableTagOverride) is set to true then external + agents can update this service in the catalog and modify the tags. type: bool - default: False + default: false weights: description: - - Specifies weights for the service + - Specifies weights for the service. type: dict suboptions: passing: description: - - Weights for passing. + - Weights for passing. type: int default: 1 warning: @@ -96,10 +90,10 @@ type: int default: 1 default: {"passing": 1, "warning": 1} -''' +""" -EXAMPLES = ''' -- name: Register nginx service with the local consul agent +EXAMPLES = r""" +- name: Register nginx service with the local Consul agent community.general.consul_agent_service: host: consul1.example.com token: some_management_acl @@ -162,33 +156,33 @@ tags: - prod - worker -''' +""" -RETURN = """ +RETURN = r""" service: - description: The service as returned by the consul HTTP API. - returned: always - type: dict - sample: - ID: nginx - Service: nginx - Address: localhost - Port: 80 - Tags: - - http - Meta: - - nginx_version: 1.23.3 - Datacenter: dc1 - Weights: - Passing: 1 - Warning: 1 - ContentHash: 61a245cd985261ac - EnableTagOverride: false + description: The service as returned by the Consul HTTP API. + returned: always + type: dict + sample: + ID: nginx + Service: nginx + Address: localhost + Port: 80 + Tags: + - http + Meta: + - nginx_version: 1.23.3 + Datacenter: dc1 + Weights: + Passing: 1 + Warning: 1 + ContentHash: 61a245cd985261ac + EnableTagOverride: false operation: - description: The operation performed. - returned: changed - type: str - sample: update + description: The operation performed. + returned: changed + type: str + sample: update """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/consul_auth_method.py b/plugins/modules/consul_auth_method.py index e28474c313d..a5cfd3b305f 100644 --- a/plugins/modules/consul_auth_method.py +++ b/plugins/modules/consul_auth_method.py @@ -9,14 +9,13 @@ __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: consul_auth_method short_description: Manipulate Consul auth methods version_added: 8.3.0 description: - - Allows the addition, modification and deletion of auth methods in a consul - cluster via the agent. For more details on using and configuring ACLs, - see U(https://www.consul.io/docs/guides/acl.html). + - Allows the addition, modification and deletion of auth methods in a Consul cluster using the agent. For more details on + using and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html). author: - Florian Apolloner (@apollo13) extends_documentation_fragment: @@ -77,7 +76,7 @@ type: dict """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create an auth method community.general.consul_auth_method: name: test @@ -103,9 +102,9 @@ token: "{{ consul_management_token }}" """ -RETURN = """ +RETURN = r""" auth_method: - description: The auth method as returned by the consul HTTP API. + description: The auth method as returned by the Consul HTTP API. returned: always type: dict sample: @@ -126,10 +125,10 @@ Name: test Type: jwt operation: - description: The operation performed. - returned: changed - type: str - sample: update + description: The operation performed. + returned: changed + type: str + sample: update """ import re diff --git a/plugins/modules/consul_binding_rule.py b/plugins/modules/consul_binding_rule.py index 6a2882cee29..bce48323c77 100644 --- a/plugins/modules/consul_binding_rule.py +++ b/plugins/modules/consul_binding_rule.py @@ -9,14 +9,13 @@ __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: consul_binding_rule short_description: Manipulate Consul binding rules version_added: 8.3.0 description: - - Allows the addition, modification and deletion of binding rules in a consul - cluster via the agent. For more details on using and configuring binding rules, - see U(https://developer.hashicorp.com/consul/api-docs/acl/binding-rules). + - Allows the addition, modification and deletion of binding rules in a Consul cluster using the agent. For more details on + using and configuring binding rules, see U(https://developer.hashicorp.com/consul/api-docs/acl/binding-rules). author: - Florian Apolloner (@apollo13) extends_documentation_fragment: @@ -41,7 +40,8 @@ name: description: - Specifies a name for the binding rule. - - 'Note: This is used to identify the binding rule. But since the API does not support a name, it is prefixed to the description.' + - 'Note: This is used to identify the binding rule. But since the API does not support a name, it is prefixed to the + description.' type: str required: true description: @@ -74,7 +74,7 @@ type: dict """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create a binding rule community.general.consul_binding_rule: name: my_name @@ -91,9 +91,9 @@ state: absent """ -RETURN = """ +RETURN = r""" binding_rule: - description: The binding rule as returned by the consul HTTP API. + description: The binding rule as returned by the Consul HTTP API. returned: always type: dict sample: diff --git a/plugins/modules/consul_kv.py b/plugins/modules/consul_kv.py index fd3a1fce06f..61831c47fe9 100644 --- a/plugins/modules/consul_kv.py +++ b/plugins/modules/consul_kv.py @@ -10,15 +10,14 @@ __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: consul_kv -short_description: Manipulate entries in the key/value store of a consul cluster +short_description: Manipulate entries in the key/value store of a Consul cluster description: - - Allows the retrieval, addition, modification and deletion of key/value entries in a - consul cluster via the agent. The entire contents of the record, including - the indices, flags and session are returned as C(value). - - If the O(key) represents a prefix then note that when a value is removed, the existing - value if any is returned as part of the results. + - Allows the retrieval, addition, modification and deletion of key/value entries in a Consul cluster using the agent. The + entire contents of the record, including the indices, flags and session are returned as C(value). + - If the O(key) represents a prefix then note that when a value is removed, the existing value if any is returned as part + of the results. - See http://www.consul.io/docs/agent/http.html#kv for more details. requirements: - python-consul @@ -29,98 +28,89 @@ extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - state: - description: - - The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key - contents will be set to the value supplied and C(changed) will be set to V(true) only if the value was - different to the current contents. If the state is V(present) and O(value) is not set, the existing value - associated to the key will be returned. The state V(absent) will remove the key/value pair, - again C(changed) will be set to V(true) only if the key actually existed - prior to the removal. An attempt can be made to obtain or free the - lock associated with a key/value pair with the states V(acquire) or - V(release) respectively. a valid session must be supplied to make the - attempt changed will be true if the attempt is successful, false - otherwise. - type: str - choices: [ absent, acquire, present, release ] - default: present - key: - description: - - The key at which the value should be stored. - type: str - required: true - value: - description: - - The value should be associated with the given key, required if O(state) - is V(present). - type: str - recurse: - description: - - If the key represents a prefix, each entry with the prefix can be - retrieved by setting this to V(true). - type: bool - retrieve: - description: - - If the O(state) is V(present) and O(value) is set, perform a - read after setting the value and return this value. - default: true - type: bool - session: - description: - - The session that should be used to acquire or release a lock - associated with a key/value pair. - type: str - token: - description: - - The token key identifying an ACL rule set that controls access to - the key value pair - type: str - cas: - description: - - Used when acquiring a lock with a session. If the O(cas) is V(0), then - Consul will only put the key if it does not already exist. If the - O(cas) value is non-zero, then the key is only set if the index matches - the ModifyIndex of that key. - type: str - flags: - description: - - Opaque positive integer value that can be passed when setting a value. - type: str - host: - description: - - Host of the consul agent. - type: str - default: localhost - port: - description: - - The port on which the consul agent is running. - type: int - default: 8500 - scheme: - description: - - The protocol scheme on which the consul agent is running. - type: str - default: http - validate_certs: - description: - - Whether to verify the tls certificate of the consul agent. - type: bool - default: true - datacenter: - description: - - The name of the datacenter to query. If unspecified, the query will default - to the datacenter of the Consul agent on O(host). - type: str - version_added: 10.0.0 -''' - - -EXAMPLES = ''' + state: + description: + - The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key contents + will be set to the value supplied and C(changed) will be set to V(true) only if the value was different to the current + contents. If the state is V(present) and O(value) is not set, the existing value associated to the key will be returned. + The state V(absent) will remove the key/value pair, again C(changed) will be set to V(true) only if the key actually + existed prior to the removal. An attempt can be made to obtain or free the lock associated with a key/value pair with + the states V(acquire) or V(release) respectively. A valid session must be supplied to make the attempt C(changed) will + be V(true) if the attempt is successful, V(false) otherwise. + type: str + choices: [absent, acquire, present, release] + default: present + key: + description: + - The key at which the value should be stored. + type: str + required: true + value: + description: + - The value should be associated with the given key, required if O(state) is V(present). + type: str + recurse: + description: + - If the key represents a prefix, each entry with the prefix can be retrieved by setting this to V(true). + type: bool + retrieve: + description: + - If the O(state) is V(present) and O(value) is set, perform a read after setting the value and return this value. + default: true + type: bool + session: + description: + - The session that should be used to acquire or release a lock associated with a key/value pair. + type: str + token: + description: + - The token key identifying an ACL rule set that controls access to the key value pair. + type: str + cas: + description: + - Used when acquiring a lock with a session. If the O(cas) is V(0), then Consul will only put the key if it does not + already exist. If the O(cas) value is non-zero, then the key is only set if the index matches the ModifyIndex of that + key. + type: str + flags: + description: + - Opaque positive integer value that can be passed when setting a value. + type: str + host: + description: + - Host of the Consul agent. + type: str + default: localhost + port: + description: + - The port on which the Consul agent is running. + type: int + default: 8500 + scheme: + description: + - The protocol scheme on which the Consul agent is running. + type: str + default: http + validate_certs: + description: + - Whether to verify the tls certificate of the Consul agent. + type: bool + default: true + datacenter: + description: + - The name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent + on O(host). + type: str + version_added: 10.0.0 +""" + + +EXAMPLES = r""" # If the key does not exist, the value associated to the "data" property in `retrieved_key` will be `None` # If the key value is empty string, `retrieved_key["data"]["Value"]` will be `None` - name: Retrieve a value from the key/value store @@ -138,7 +128,7 @@ key: somekey state: absent -- name: Add a node to an arbitrary group via consul inventory (see consul.ini) +- name: Add a node to an arbitrary group using Consul inventory (see consul.ini) community.general.consul_kv: key: ansible/groups/dc1/somenode value: top_secret @@ -149,7 +139,7 @@ value: 20160509 session: "{{ sessionid }}" state: acquire -''' +""" from ansible.module_utils.common.text.converters import to_text diff --git a/plugins/modules/consul_policy.py b/plugins/modules/consul_policy.py index 36139ac0974..c9758780b2e 100644 --- a/plugins/modules/consul_policy.py +++ b/plugins/modules/consul_policy.py @@ -9,14 +9,13 @@ __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: consul_policy short_description: Manipulate Consul policies version_added: 7.2.0 description: - - Allows the addition, modification and deletion of policies in a consul - cluster via the agent. For more details on using and configuring ACLs, - see U(https://www.consul.io/docs/guides/acl.html). + - Allows the addition, modification and deletion of policies in a Consul cluster using the agent. For more details on using + and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html). author: - Håkon Lerring (@Hakon) extends_documentation_fragment: @@ -49,8 +48,7 @@ elements: str name: description: - - The name that should be associated with the policy, this is opaque - to Consul. + - The name that should be associated with the policy, this is opaque to Consul. required: true type: str description: @@ -63,19 +61,19 @@ - Rule document that should be associated with the current policy. """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create a policy with rules community.general.consul_policy: host: consul1.example.com token: some_management_acl name: foo-access rules: | - key "foo" { - policy = "read" - } - key "private/foo" { - policy = "deny" - } + key "foo" { + policy = "read" + } + key "private/foo" { + policy = "deny" + } - name: Update the rules associated to a policy community.general.consul_policy: @@ -83,15 +81,15 @@ token: some_management_acl name: foo-access rules: | - key "foo" { - policy = "read" - } - key "private/foo" { - policy = "deny" - } - event "bbq" { - policy = "write" - } + key "foo" { + policy = "read" + } + key "private/foo" { + policy = "deny" + } + event "bbq" { + policy = "write" + } - name: Remove a policy community.general.consul_policy: @@ -101,28 +99,28 @@ state: absent """ -RETURN = """ +RETURN = r""" policy: - description: The policy as returned by the consul HTTP API. - returned: always - type: dict - sample: - CreateIndex: 632 - Description: Testing - Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A= - Name: foo-access - Rules: |- - key "foo" { - policy = "read" - } - key "private/foo" { - policy = "deny" - } + description: The policy as returned by the Consul HTTP API. + returned: always + type: dict + sample: + CreateIndex: 632 + Description: Testing + Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A= + Name: foo-access + Rules: |- + key "foo" { + policy = "read" + } + key "private/foo" { + policy = "deny" + } operation: - description: The operation performed. - returned: changed - type: str - sample: update + description: The operation performed. + returned: changed + type: str + sample: update """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/consul_role.py b/plugins/modules/consul_role.py index d6c4e4dd92a..f8b8d604adc 100644 --- a/plugins/modules/consul_role.py +++ b/plugins/modules/consul_role.py @@ -9,14 +9,13 @@ __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: consul_role short_description: Manipulate Consul roles version_added: 7.5.0 description: - - Allows the addition, modification and deletion of roles in a consul - cluster via the agent. For more details on using and configuring ACLs, - see U(https://www.consul.io/docs/guides/acl.html). + - Allows the addition, modification and deletion of roles in a Consul cluster using the agent. For more details on using and + configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html). author: - Håkon Lerring (@Hakon) extends_documentation_fragment: @@ -42,7 +41,7 @@ type: str state: description: - - whether the role should be present or absent. + - Whether the role should be present or absent. choices: ['present', 'absent'] default: present type: str @@ -98,9 +97,9 @@ description: - The name of the node. - Must not be longer than 256 characters, must start and end with a lowercase alphanumeric character. - - May only contain lowercase alphanumeric characters as well as - and _. - - This suboption has been renamed from O(service_identities[].name) to O(service_identities[].service_name) - in community.general 8.3.0. The old name can still be used. + - May only contain lowercase alphanumeric characters as well as V(-) and V(_). + - This suboption has been renamed from O(service_identities[].name) to O(service_identities[].service_name) in community.general + 8.3.0. The old name can still be used. type: str required: true aliases: @@ -110,7 +109,7 @@ - The datacenters the policies will be effective. - This will result in effective policy only being valid in this datacenter. - If an empty array (V([])) is specified, the policies will valid in all datacenters. - - including those which do not yet exist but may in the future. + - Including those which do not yet exist but may in the future. type: list elements: str node_identities: @@ -125,9 +124,9 @@ description: - The name of the node. - Must not be longer than 256 characters, must start and end with a lowercase alphanumeric character. - - May only contain lowercase alphanumeric characters as well as - and _. - - This suboption has been renamed from O(node_identities[].name) to O(node_identities[].node_name) - in community.general 8.3.0. The old name can still be used. + - May only contain lowercase alphanumeric characters as well as V(-) and V(_). + - This suboption has been renamed from O(node_identities[].name) to O(node_identities[].node_name) in community.general + 8.3.0. The old name can still be used. type: str required: true aliases: @@ -140,7 +139,7 @@ required: true """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create a role with 2 policies community.general.consul_role: host: consul1.example.com @@ -177,28 +176,28 @@ state: absent """ -RETURN = """ +RETURN = r""" role: - description: The role object. - returned: success - type: dict - sample: - { - "CreateIndex": 39, - "Description": "", - "Hash": "Trt0QJtxVEfvTTIcdTUbIJRr6Dsi6E4EcwSFxx9tCYM=", - "ID": "9a300b8d-48db-b720-8544-a37c0f5dafb5", - "ModifyIndex": 39, - "Name": "foo-role", - "Policies": [ - {"ID": "b1a00172-d7a1-0e66-a12e-7a4045c4b774", "Name": "foo-access"} - ] - } + description: The role object. + returned: success + type: dict + sample: + { + "CreateIndex": 39, + "Description": "", + "Hash": "Trt0QJtxVEfvTTIcdTUbIJRr6Dsi6E4EcwSFxx9tCYM=", + "ID": "9a300b8d-48db-b720-8544-a37c0f5dafb5", + "ModifyIndex": 39, + "Name": "foo-role", + "Policies": [ + {"ID": "b1a00172-d7a1-0e66-a12e-7a4045c4b774", "Name": "foo-access"} + ] + } operation: - description: The operation performed on the role. - returned: changed - type: str - sample: update + description: The operation performed on the role. + returned: changed + type: str + sample: update """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/consul_session.py b/plugins/modules/consul_session.py index 87a5f191431..ac9b126eeb8 100644 --- a/plugins/modules/consul_session.py +++ b/plugins/modules/consul_session.py @@ -8,14 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: consul_session -short_description: Manipulate consul sessions +short_description: Manipulate Consul sessions description: - - Allows the addition, modification and deletion of sessions in a consul - cluster. These sessions can then be used in conjunction with key value pairs - to implement distributed locks. In depth documentation for working with - sessions can be found at http://www.consul.io/docs/internals/sessions.html + - Allows the addition, modification and deletion of sessions in a Consul cluster. These sessions can then be used in conjunction + with key value pairs to implement distributed locks. In depth documentation for working with sessions can be found at + U(http://www.consul.io/docs/internals/sessions.html). author: - Steve Gargan (@sgargan) - Håkon Lerring (@Hakon) @@ -25,78 +24,68 @@ - community.general.consul.token - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none - action_group: - version_added: 8.3.0 + check_mode: + support: none + diff_mode: + support: none + action_group: + version_added: 8.3.0 options: - id: - description: - - ID of the session, required when O(state) is either V(info) or - V(remove). - type: str - state: - description: - - Whether the session should be present i.e. created if it doesn't - exist, or absent, removed if present. If created, the O(id) for the - session is returned in the output. If V(absent), O(id) is - required to remove the session. Info for a single session, all the - sessions for a node or all available sessions can be retrieved by - specifying V(info), V(node) or V(list) for the O(state); for V(node) - or V(info), the node O(name) or session O(id) is required as parameter. - choices: [ absent, info, list, node, present ] - type: str - default: present - name: - description: - - The name that should be associated with the session. Required when - O(state=node) is used. - type: str - delay: - description: - - The optional lock delay that can be attached to the session when it - is created. Locks for invalidated sessions ar blocked from being - acquired until this delay has expired. Durations are in seconds. - type: int - default: 15 - node: - description: - - The name of the node that with which the session will be associated. - by default this is the name of the agent. - type: str - datacenter: - description: - - The name of the datacenter in which the session exists or should be - created. - type: str - checks: - description: - - Checks that will be used to verify the session health. If - all the checks fail, the session will be invalidated and any locks - associated with the session will be release and can be acquired once - the associated lock delay has expired. - type: list - elements: str - behavior: - description: - - The optional behavior that can be attached to the session when it - is created. This controls the behavior when a session is invalidated. - choices: [ delete, release ] - type: str - default: release - ttl: - description: - - Specifies the duration of a session in seconds (between 10 and 86400). - type: int - version_added: 5.4.0 - token: - version_added: 5.6.0 -''' - -EXAMPLES = ''' -- name: Register basic session with consul + id: + description: + - ID of the session, required when O(state) is either V(info) or V(remove). + type: str + state: + description: + - Whether the session should be present, in other words it should be created if it does not exist, or absent, removed if present. If created, + the O(id) for the session is returned in the output. If V(absent), O(id) is required to remove the session. Info for + a single session, all the sessions for a node or all available sessions can be retrieved by specifying V(info), V(node) + or V(list) for the O(state); for V(node) or V(info), the node O(name) or session O(id) is required as parameter. + choices: [absent, info, list, node, present] + type: str + default: present + name: + description: + - The name that should be associated with the session. Required when O(state=node) is used. + type: str + delay: + description: + - The optional lock delay that can be attached to the session when it is created. Locks for invalidated sessions ar + blocked from being acquired until this delay has expired. Durations are in seconds. + type: int + default: 15 + node: + description: + - The name of the node that with which the session will be associated. By default this is the name of the agent. + type: str + datacenter: + description: + - The name of the datacenter in which the session exists or should be created. + type: str + checks: + description: + - Checks that will be used to verify the session health. If all the checks fail, the session will be invalidated and + any locks associated with the session will be release and can be acquired once the associated lock delay has expired. + type: list + elements: str + behavior: + description: + - The optional behavior that can be attached to the session when it is created. This controls the behavior when a session + is invalidated. + choices: [delete, release] + type: str + default: release + ttl: + description: + - Specifies the duration of a session in seconds (between 10 and 86400). + type: int + version_added: 5.4.0 + token: + version_added: 5.6.0 +""" + +EXAMPLES = r""" +- name: Register basic session with Consul community.general.consul_session: name: session1 @@ -123,8 +112,8 @@ - name: Register session with a ttl community.general.consul_session: name: session-with-ttl - ttl: 600 # sec -''' + ttl: 600 # sec +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.consul import ( diff --git a/plugins/modules/consul_token.py b/plugins/modules/consul_token.py index c8bc8bc2798..dccfa2f7a3c 100644 --- a/plugins/modules/consul_token.py +++ b/plugins/modules/consul_token.py @@ -9,14 +9,13 @@ __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" module: consul_token short_description: Manipulate Consul tokens version_added: 8.3.0 description: - - Allows the addition, modification and deletion of tokens in a consul - cluster via the agent. For more details on using and configuring ACLs, - see U(https://www.consul.io/docs/guides/acl.html). + - Allows the addition, modification and deletion of tokens in a Consul cluster using the agent. For more details on using + and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html). author: - Florian Apolloner (@apollo13) extends_documentation_fragment: @@ -42,13 +41,11 @@ type: str accessor_id: description: - - Specifies a UUID to use as the token's Accessor ID. - If not specified a UUID will be generated for this field. + - Specifies a UUID to use as the token's Accessor ID. If not specified a UUID will be generated for this field. type: str secret_id: description: - - Specifies a UUID to use as the token's Secret ID. - If not specified a UUID will be generated for this field. + - Specifies a UUID to use as the token's Secret ID. If not specified a UUID will be generated for this field. type: str description: description: @@ -125,7 +122,7 @@ description: - The datacenters the token will be effective. - If an empty array (V([])) is specified, the token will valid in all datacenters. - - including those which do not yet exist but may in the future. + - Including those which do not yet exist but may in the future. type: list elements: str node_identities: @@ -151,18 +148,16 @@ required: true local: description: - - If true, indicates that the token should not be replicated globally - and instead be local to the current datacenter. + - If true, indicates that the token should not be replicated globally and instead be local to the current datacenter. type: bool expiration_ttl: description: - - This is a convenience field and if set will initialize the C(expiration_time). - Can be specified in the form of V(60s) or V(5m) (that is, 60 seconds or 5 minutes, - respectively). Ingored when the token is updated! + - This is a convenience field and if set will initialize the C(expiration_time). Can be specified in the form of V(60s) + or V(5m) (that is, 60 seconds or 5 minutes, respectively). Ingored when the token is updated! type: str """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create / Update a token by accessor_id community.general.consul_token: state: present @@ -186,26 +181,26 @@ token: 8adddd91-0bd6-d41d-ae1a-3b49cfa9a0e8 """ -RETURN = """ +RETURN = r""" token: - description: The token as returned by the consul HTTP API. - returned: always - type: dict - sample: - AccessorID: 07a7de84-c9c7-448a-99cc-beaf682efd21 - CreateIndex: 632 - CreateTime: "2024-01-14T21:53:01.402749174+01:00" - Description: Testing - Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A= - Local: false - ModifyIndex: 633 - SecretID: bd380fba-da17-7cee-8576-8d6427c6c930 - ServiceIdentities: [{"ServiceName": "test"}] + description: The token as returned by the Consul HTTP API. + returned: always + type: dict + sample: + AccessorID: 07a7de84-c9c7-448a-99cc-beaf682efd21 + CreateIndex: 632 + CreateTime: "2024-01-14T21:53:01.402749174+01:00" + Description: Testing + Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A= + Local: false + ModifyIndex: 633 + SecretID: bd380fba-da17-7cee-8576-8d6427c6c930 + ServiceIdentities: ["ServiceName": "test"] operation: - description: The operation performed. - returned: changed - type: str - sample: update + description: The operation performed. + returned: changed + type: str + sample: update """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/copr.py b/plugins/modules/copr.py index 809064114af..90cb931210d 100644 --- a/plugins/modules/copr.py +++ b/plugins/modules/copr.py @@ -9,61 +9,60 @@ __metaclass__ = type DOCUMENTATION = r""" ---- module: copr short_description: Manage one of the Copr repositories version_added: 2.0.0 description: This module can enable, disable or remove the specified repository. author: Silvie Chlupova (@schlupov) requirements: - - dnf - - dnf-plugins-core + - dnf + - dnf-plugins-core notes: - - Supports C(check_mode). + - Supports C(check_mode). 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: - host: - description: The Copr host to work with. - default: copr.fedorainfracloud.org - type: str - protocol: - description: This indicate which protocol to use with the host. - default: https - type: str - name: - description: Copr directory name, for example C(@copr/copr-dev). - required: true - type: str - state: - description: - - Whether to set this project as V(enabled), V(disabled), or V(absent). - default: enabled - type: str - choices: [absent, enabled, disabled] - chroot: - description: - - The name of the chroot that you want to enable/disable/remove in the project, - for example V(epel-7-x86_64). Default chroot is determined by the operating system, - version of the operating system, and architecture on which the module is run. - type: str - includepkgs: - description: List of packages to include. - required: false - type: list - elements: str - version_added: 9.4.0 - excludepkgs: - description: List of packages to exclude. - required: false - type: list - elements: str - version_added: 9.4.0 + host: + description: The Copr host to work with. + default: copr.fedorainfracloud.org + type: str + protocol: + description: This indicate which protocol to use with the host. + default: https + type: str + name: + description: Copr directory name, for example C(@copr/copr-dev). + required: true + type: str + state: + description: + - Whether to set this project as V(enabled), V(disabled), or V(absent). + default: enabled + type: str + choices: [absent, enabled, disabled] + chroot: + description: + - The name of the chroot that you want to enable/disable/remove in the project, for example V(epel-7-x86_64). Default + chroot is determined by the operating system, version of the operating system, and architecture on which the module + is run. + type: str + includepkgs: + description: List of packages to include. + required: false + type: list + elements: str + version_added: 9.4.0 + excludepkgs: + description: List of packages to exclude. + required: false + type: list + elements: str + version_added: 9.4.0 """ EXAMPLES = r""" diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py index 04b3b06b7fa..3f708581acd 100644 --- a/plugins/modules/cpanm.py +++ b/plugins/modules/cpanm.py @@ -10,14 +10,13 @@ __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: cpanm short_description: Manages Perl library dependencies description: -- Manage Perl library dependencies using cpanminus. + - Manage Perl library dependencies using cpanminus. extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -27,82 +26,79 @@ name: type: str description: - - The Perl library to install. Valid values change according to the O(mode), see notes for more details. - - Note that for installing from a local path the parameter O(from_path) should be used. + - The Perl library to install. Valid values change according to the O(mode), see notes for more details. + - Note that for installing from a local path the parameter O(from_path) should be used. aliases: [pkg] from_path: type: path description: - - The local directory or C(tar.gz) file to install from. + - The local directory or C(tar.gz) file to install from. notest: description: - - Do not run unit tests. + - Do not run unit tests. type: bool default: false locallib: description: - - Specify the install base to install modules. + - Specify the install base to install modules. type: path mirror: description: - - Specifies the base URL for the CPAN mirror to use. + - Specifies the base URL for the CPAN mirror to use. type: str mirror_only: description: - - Use the mirror's index file instead of the CPAN Meta DB. + - Use the mirror's index file instead of the CPAN Meta DB. type: bool default: false installdeps: description: - - Only install dependencies. + - Only install dependencies. type: bool default: false version: description: - - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted. + - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted. type: str executable: description: - - Override the path to the cpanm executable. + - Override the path to the cpanm executable. type: path mode: description: - - Controls the module behavior. See notes below for more details. - - The default changed from V(compatibility) to V(new) in community.general 9.0.0. + - Controls the module behavior. See notes below for more details. + - The default changed from V(compatibility) to V(new) in community.general 9.0.0. type: str choices: [compatibility, new] default: new version_added: 3.0.0 name_check: description: - - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified). + - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when + specified). type: str version_added: 3.0.0 notes: -- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host. -- "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)." -- > - O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. - This was the default mode before community.general 9.0.0. - O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version) - when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL. - C(cpanm) version specifiers do not work in this mode. -- > - O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file, - a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized. - This is the default mode from community.general 9.0.0 onwards. - + - Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host. + - 'This module now comes with a choice of execution O(mode): V(compatibility) or V(new).' + - 'O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. This was the default + mode before community.general 9.0.0. O(name) must be either a module name or a distribution file. If the perl module given + by O(name) is installed (at the exact O(version) when specified), then nothing happens. Otherwise, it will be installed + using the C(cpanm) executable. O(name) cannot be an URL, or a git URL. C(cpanm) version specifiers do not work in this + mode.' + - 'O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module + name, a distribution file, a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version + specifiers are recognized. This is the default mode from community.general 9.0.0 onwards.' seealso: -- name: C(cpanm) command manual page - description: Manual page for the command. - link: https://metacpan.org/dist/App-cpanminus/view/bin/cpanm + - name: C(cpanm) command manual page + description: Manual page for the command. + link: https://metacpan.org/dist/App-cpanminus/view/bin/cpanm author: -- "Franck Cuny (@fcuny)" -- "Alexei Znamensky (@russoz)" + - "Franck Cuny (@fcuny)" + - "Alexei Znamensky (@russoz)" """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Install Dancer perl package community.general.cpanm: name: Dancer @@ -142,8 +138,7 @@ version: '1.0' """ -RETURN = """ ---- +RETURN = r""" cpanm_version: description: Version of CPANMinus. type: str diff --git a/plugins/modules/cronvar.py b/plugins/modules/cronvar.py index 66fa175498c..488e7397047 100644 --- a/plugins/modules/cronvar.py +++ b/plugins/modules/cronvar.py @@ -17,8 +17,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: cronvar short_description: Manage variables in crontabs description: @@ -49,14 +48,13 @@ type: str insertbefore: description: - - Used with O(state=present). If specified, the variable will be inserted - just before the variable specified. + - Used with O(state=present). If specified, the variable will be inserted just before the variable specified. type: str state: description: - Whether to ensure that the variable is present or absent. type: str - choices: [ absent, present ] + choices: [absent, present] default: present user: description: @@ -71,18 +69,17 @@ type: str backup: description: - - If set, create a backup of the crontab before it is modified. - The location of the backup is returned in the C(backup) variable by this module. - # TODO: C() above should be RV(), but return values have not been documented! + - If set, create a backup of the crontab before it is modified. The location of the backup is returned in the C(backup) + variable by this module. type: bool default: false requirements: - cron author: -- Doug Luce (@dougluce) -''' + - Doug Luce (@dougluce) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Ensure entry like "EMAIL=doug@ansibmod.con.com" exists community.general.cronvar: name: EMAIL @@ -99,7 +96,7 @@ value: /var/log/yum-autoupdate.log user: root cron_file: ansible_yum-autoupdate -''' +""" import os import platform diff --git a/plugins/modules/crypttab.py b/plugins/modules/crypttab.py index 931a0c930b4..b6a0e52cc3b 100644 --- a/plugins/modules/crypttab.py +++ b/plugins/modules/crypttab.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: crypttab short_description: Encrypted Linux block devices description: @@ -24,31 +23,27 @@ options: name: description: - - Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or - optionally prefixed with V(/dev/mapper/), as it appears in the filesystem. V(/dev/mapper/) - will be stripped from O(name). + - Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or optionally prefixed with V(/dev/mapper/), + as it appears in the filesystem. V(/dev/mapper/) will be stripped from O(name). type: str required: true state: description: - - Use V(present) to add a line to C(/etc/crypttab) or update its definition - if already present. + - Use V(present) to add a line to C(/etc/crypttab) or update its definition if already present. - Use V(absent) to remove a line with matching O(name). - - Use V(opts_present) to add options to those already present; options with - different values will be updated. + - Use V(opts_present) to add options to those already present; options with different values will be updated. - Use V(opts_absent) to remove options from the existing set. type: str required: true - choices: [ absent, opts_absent, opts_present, present ] + choices: [absent, opts_absent, opts_present, present] backing_device: description: - - Path to the underlying block device or file, or the UUID of a block-device - prefixed with V(UUID=). + - Path to the underlying block device or file, or the UUID of a block-device prefixed with V(UUID=). type: str password: description: - - Encryption password, the path to a file containing the password, or - V(-) or unset if the password should be entered at boot. + - Encryption password, the path to a file containing the password, or V(-) or unset if the password should be entered + at boot. type: path opts: description: @@ -61,10 +56,10 @@ type: path default: /etc/crypttab author: -- Steve (@groks) -''' + - Steve (@groks) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Set the options explicitly a device which must already exist community.general.crypttab: name: luks-home @@ -78,7 +73,7 @@ opts: discard loop: '{{ ansible_mounts }}' when: "'/dev/mapper/luks-' in {{ item.device }}" -''' +""" import os import traceback