From cea6eeef371d6751220679459ed9ee77c157ffa3 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 26 Dec 2024 21:12:05 +1300 Subject: [PATCH] l*.py: normalize docs (#9390) --- plugins/modules/launchd.py | 90 +++--- plugins/modules/layman.py | 26 +- plugins/modules/lbu.py | 30 +- plugins/modules/ldap_attrs.py | 122 ++++---- plugins/modules/ldap_entry.py | 73 ++--- plugins/modules/ldap_passwd.py | 28 +- plugins/modules/ldap_search.py | 30 +- plugins/modules/librato_annotation.py | 117 ++++---- plugins/modules/linode.py | 216 +++++++------- plugins/modules/linode_v4.py | 66 ++--- plugins/modules/listen_ports_facts.py | 34 +-- plugins/modules/lldp.py | 28 +- plugins/modules/locale_gen.py | 51 ++-- plugins/modules/logentries.py | 72 ++--- plugins/modules/logentries_msg.py | 21 +- plugins/modules/logstash_plugin.py | 80 +++-- plugins/modules/lvg.py | 59 ++-- plugins/modules/lvg_rename.py | 19 +- plugins/modules/lvol.py | 61 ++-- plugins/modules/lxc_container.py | 411 +++++++++++++------------- plugins/modules/lxca_cmms.py | 59 ++-- plugins/modules/lxca_nodes.py | 63 ++-- plugins/modules/lxd_container.py | 370 +++++++++++------------ plugins/modules/lxd_profile.py | 244 ++++++++------- plugins/modules/lxd_project.py | 176 ++++++----- 25 files changed, 1195 insertions(+), 1351 deletions(-) diff --git a/plugins/modules/launchd.py b/plugins/modules/launchd.py index 9717825c718..ea2163964bd 100644 --- a/plugins/modules/launchd.py +++ b/plugins/modules/launchd.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: launchd author: - Martin Migasiewicz (@martinm82) @@ -20,57 +19,52 @@ extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - description: + name: + description: - Name of the service. - type: str - required: true - plist: - description: + type: str + required: true + plist: + description: - Name of the V(.plist) file for the service. - Defaults to V({name}.plist). - type: str - version_added: 10.1.0 - state: - description: - - V(started)/V(stopped) are idempotent actions that will not run - commands unless necessary. - - Launchd does not support V(restarted) nor V(reloaded) natively. - These will trigger a stop/start (restarted) or an unload/load - (reloaded). - - V(restarted) unloads and loads the service before start to ensure - that the latest job definition (plist) is used. - - V(reloaded) unloads and loads the service to ensure that the latest - job definition (plist) is used. Whether a service is started or - stopped depends on the content of the definition file. - type: str - choices: [ reloaded, restarted, started, stopped, unloaded ] - enabled: - description: + type: str + version_added: 10.1.0 + state: + description: + - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. + - Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an unload/load (reloaded). + - V(restarted) unloads and loads the service before start to ensure that the latest job definition (plist) is used. + - V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service is started or stopped + depends on the content of the definition file. + type: str + choices: [reloaded, restarted, started, stopped, unloaded] + enabled: + description: - Whether the service should start on boot. - - B(At least one of state and enabled are required.) - type: bool - force_stop: - description: + - B(At least one of state and enabled are required). + type: bool + force_stop: + description: - Whether the service should not be restarted automatically by launchd. - - Services might have the 'KeepAlive' attribute set to true in a launchd configuration. - In case this is set to true, stopping a service will cause that launchd starts the service again. - - Set this option to V(true) to let this module change the 'KeepAlive' attribute to V(false). - type: bool - default: false + - Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true, stopping a service + will cause that launchd starts the service again. + - Set this option to V(true) to let this module change the C(KeepAlive) attribute to V(false). + type: bool + default: false notes: -- A user must privileged to manage services using this module. + - A user must privileged to manage services using this module. requirements: -- A system managed by launchd -- The plistlib python library -''' + - A system managed by launchd + - The plistlib Python library +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Make sure spotify webhelper is started community.general.launchd: name: com.spotify.webhelper @@ -112,11 +106,11 @@ name: com.openssh.sshd plist: ssh.plist state: restarted -''' +""" -RETURN = r''' +RETURN = r""" status: - description: Metadata about service status + description: Metadata about service status. returned: always type: dict sample: @@ -126,7 +120,7 @@ "previous_pid": "82636", "previous_state": "running" } -''' +""" import os import plistlib diff --git a/plugins/modules/layman.py b/plugins/modules/layman.py index 13d514274bc..21b4eba9a4c 100644 --- a/plugins/modules/layman.py +++ b/plugins/modules/layman.py @@ -10,14 +10,13 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: layman author: "Jakub Jirutka (@jirutka)" short_description: Manage Gentoo overlays description: - - Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux. - Please note that Layman must be installed on a managed node prior using this module. + - Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux. Please note that Layman must be installed + on a managed node prior using this module. requirements: - layman python module extends_documentation_fragment: @@ -30,15 +29,13 @@ options: name: description: - - The overlay id to install, synchronize, or uninstall. - Use 'ALL' to sync all of the installed overlays (can be used only when O(state=updated)). + - The overlay id to install, synchronize, or uninstall. Use V(ALL) to sync all of the installed overlays (can be used only when O(state=updated)). required: true type: str list_url: description: - - An URL of the alternative overlays list that defines the overlay to install. - This list will be fetched and saved under C(${overlay_defs}/${name}.xml), where - C(overlay_defs) is read from the Layman's configuration. + - An URL of the alternative overlays list that defines the overlay to install. This list will be fetched and saved under C(${overlay_defs}/${name}.xml), + where C(overlay_defs) is read from the Layman's configuration. aliases: [url] type: str state: @@ -49,14 +46,13 @@ type: str validate_certs: description: - - If V(false), SSL certificates will not be validated. This should only be - set to V(false) when no other option exists. Prior to 1.9.3 the code - defaulted to V(false). + - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists. Prior to 1.9.3 the + code defaulted to V(false). type: bool default: true -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install the overlay mozilla which is on the central overlays list community.general.layman: name: mozilla @@ -81,7 +77,7 @@ community.general.layman: name: cvut state: absent -''' +""" import shutil import traceback diff --git a/plugins/modules/lbu.py b/plugins/modules/lbu.py index c961b6060d8..e91fd5e01ab 100644 --- a/plugins/modules/lbu.py +++ b/plugins/modules/lbu.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: lbu short_description: Local Backup Utility for Alpine Linux @@ -17,8 +16,7 @@ version_added: '0.2.0' description: - - Manage Local Backup Utility of Alpine Linux in run-from-RAM mode - + - Manage Local Backup Utility of Alpine Linux in run-from-RAM mode. extends_documentation_fragment: - community.general.attributes @@ -31,24 +29,24 @@ options: commit: description: - - Control whether to commit changed files. + - Control whether to commit changed files. type: bool exclude: description: - - List of paths to exclude. + - List of paths to exclude. type: list elements: str include: description: - - List of paths to include. + - List of paths to include. type: list elements: str author: - Kaarle Ritvanen (@kunkku) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Commit changed files (if any) - name: Commit community.general.lbu: @@ -59,22 +57,22 @@ community.general.lbu: commit: true exclude: - - /etc/opt + - /etc/opt # Include paths without committing - name: Include file and directory community.general.lbu: include: - - /root/.ssh/authorized_keys - - /var/lib/misc -''' + - /root/.ssh/authorized_keys + - /var/lib/misc +""" -RETURN = ''' +RETURN = r""" msg: - description: Error message + description: Error message. type: str returned: on failure -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/ldap_attrs.py b/plugins/modules/ldap_attrs.py index 7986833a6e6..8f1e0a0ea93 100644 --- a/plugins/modules/ldap_attrs.py +++ b/plugins/modules/ldap_attrs.py @@ -12,27 +12,19 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ldap_attrs short_description: Add or remove multiple LDAP attribute values description: - Add or remove multiple LDAP attribute values. notes: - - This only deals with attributes on existing entries. To add or remove - whole entries, see M(community.general.ldap_entry). - - The default authentication settings will attempt to use a SASL EXTERNAL - bind over a UNIX domain socket. This works well with the default Ubuntu - install for example, which includes a cn=peercred,cn=external,cn=auth ACL - rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in O(bind_dn) - and O(bind_pw). - - For O(state=present) and O(state=absent), all value comparisons are - performed on the server for maximum accuracy. For O(state=exact), values - have to be compared in Python, which obviously ignores LDAP matching - rules. This should work out in most cases, but it is theoretically - possible to see spurious changes when target and actual values are - semantically identical but lexically distinct. + - This only deals with attributes on existing entries. To add or remove whole entries, see M(community.general.ldap_entry). + - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu + install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need + to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw). + - For O(state=present) and O(state=absent), all value comparisons are performed on the server for maximum accuracy. For O(state=exact), values + have to be compared in Python, which obviously ignores LDAP matching rules. This should work out in most cases, but it is theoretically possible + to see spurious changes when target and actual values are semantically identical but lexically distinct. version_added: '0.2.0' author: - Jiri Tyr (@jtyr) @@ -53,46 +45,38 @@ choices: [present, absent, exact] default: present description: - - The state of the attribute values. If V(present), all given attribute - values will be added if they're missing. If V(absent), all given - attribute values will be removed if present. If V(exact), the set of - attribute values will be forced to exactly those provided and no others. - If O(state=exact) and the attribute value is empty, all values for - this attribute will be removed. + - The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If V(absent), all given + attribute values will be removed if present. If V(exact), the set of attribute values will be forced to exactly those provided and no + others. If O(state=exact) and the attribute value is empty, all values for this attribute will be removed. attributes: required: true type: dict description: - The attribute(s) and value(s) to add or remove. - - Each attribute value can be a string for single-valued attributes or - a list of strings for multi-valued attributes. - - If you specify values for this option in YAML, please note that you can improve - readability for long string values by using YAML block modifiers as seen in the - examples for this module. - - Note that when using values that YAML/ansible-core interprets as other types, - like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if - these are meant to be strings. Otherwise the wrong values may be sent to LDAP. + - Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes. + - If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block + modifiers as seen in the examples for this module. + - Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make + sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP. ordered: required: false type: bool default: false description: - - If V(true), prepend list values with X-ORDERED index numbers in all - attributes specified in the current task. This is useful mostly with + - If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This is useful mostly with C(olcAccess) attribute to easily manage LDAP Access Control Lists. extends_documentation_fragment: - community.general.ldap.documentation - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Configure directory number 1 for example.com community.general.ldap_attrs: dn: olcDatabase={1}hdb,cn=config attributes: - olcSuffix: dc=example,dc=com + olcSuffix: dc=example,dc=com state: exact # The complex argument format is required here to pass a list of ACL strings. @@ -100,17 +84,17 @@ community.general.ldap_attrs: dn: olcDatabase={1}hdb,cn=config attributes: - olcAccess: - - >- - {0}to attrs=userPassword,shadowLastChange - by self write - by anonymous auth - by dn="cn=admin,dc=example,dc=com" write - by * none' - - >- - {1}to dn.base="dc=example,dc=com" - by dn="cn=admin,dc=example,dc=com" write - by * read + olcAccess: + - >- + {0}to attrs=userPassword,shadowLastChange + by self write + by anonymous auth + by dn="cn=admin,dc=example,dc=com" write + by * none' + - >- + {1}to dn.base="dc=example,dc=com" + by dn="cn=admin,dc=example,dc=com" write + by * read state: exact # An alternative approach with automatic X-ORDERED numbering @@ -118,17 +102,17 @@ community.general.ldap_attrs: dn: olcDatabase={1}hdb,cn=config attributes: - olcAccess: - - >- - to attrs=userPassword,shadowLastChange - by self write - by anonymous auth - by dn="cn=admin,dc=example,dc=com" write - by * none' - - >- - to dn.base="dc=example,dc=com" - by dn="cn=admin,dc=example,dc=com" write - by * read + olcAccess: + - >- + to attrs=userPassword,shadowLastChange + by self write + by anonymous auth + by dn="cn=admin,dc=example,dc=com" write + by * none' + - >- + to dn.base="dc=example,dc=com" + by dn="cn=admin,dc=example,dc=com" write + by * read ordered: true state: exact @@ -136,23 +120,23 @@ community.general.ldap_attrs: dn: olcDatabase={1}hdb,cn=config attributes: - olcDbIndex: - - objectClass eq - - uid eq + olcDbIndex: + - objectClass eq + - uid eq - name: Set up a root user, which we can use later to bootstrap the directory community.general.ldap_attrs: dn: olcDatabase={1}hdb,cn=config attributes: - olcRootDN: cn=root,dc=example,dc=com - olcRootPW: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND" + olcRootDN: cn=root,dc=example,dc=com + olcRootPW: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND" state: exact - name: Remove an attribute with a specific value community.general.ldap_attrs: dn: uid=jdoe,ou=people,dc=example,dc=com attributes: - description: "An example user account" + description: "An example user account" state: absent server_uri: ldap://localhost/ bind_dn: cn=admin,dc=example,dc=com @@ -162,22 +146,22 @@ community.general.ldap_attrs: dn: uid=jdoe,ou=people,dc=example,dc=com attributes: - description: [] + description: [] state: exact server_uri: ldap://localhost/ bind_dn: cn=admin,dc=example,dc=com bind_pw: password -''' +""" -RETURN = r''' +RETURN = r""" modlist: - description: list of modified parameters + description: List of modified parameters. returned: success type: list sample: - [2, "olcRootDN", ["cn=root,dc=example,dc=com"]] -''' +""" import traceback diff --git a/plugins/modules/ldap_entry.py b/plugins/modules/ldap_entry.py index 5deaf7c4c4b..d3ce90433ac 100644 --- a/plugins/modules/ldap_entry.py +++ b/plugins/modules/ldap_entry.py @@ -11,21 +11,16 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ldap_entry short_description: Add or remove LDAP entries description: - - Add or remove LDAP entries. This module only asserts the existence or - non-existence of an LDAP entry, not its attributes. To assert the - attribute values of an entry, see M(community.general.ldap_attrs). + - Add or remove LDAP entries. This module only asserts the existence or non-existence of an LDAP entry, not its attributes. To assert the attribute + values of an entry, see M(community.general.ldap_attrs). notes: - - The default authentication settings will attempt to use a SASL EXTERNAL - bind over a UNIX domain socket. This works well with the default Ubuntu - install for example, which includes a cn=peercred,cn=external,cn=auth ACL - rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in O(bind_dn) - and O(bind_pw). + - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu + install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need + to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw). author: - Jiri Tyr (@jtyr) requirements: @@ -38,24 +33,18 @@ options: attributes: description: - - If O(state=present), attributes necessary to create an entry. Existing - entries are never modified. To assert specific attribute values on an - existing entry, use M(community.general.ldap_attrs) module instead. - - Each attribute value can be a string for single-valued attributes or - a list of strings for multi-valued attributes. - - If you specify values for this option in YAML, please note that you can improve - readability for long string values by using YAML block modifiers as seen in the - examples for this module. - - Note that when using values that YAML/ansible-core interprets as other types, - like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if - these are meant to be strings. Otherwise the wrong values may be sent to LDAP. + - If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific attribute values + on an existing entry, use M(community.general.ldap_attrs) module instead. + - Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes. + - If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block + modifiers as seen in the examples for this module. + - Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make + sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP. type: dict default: {} objectClass: description: - - If O(state=present), value or list of values to use when creating - the entry. It can either be a string or an actual list of - strings. + - If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual list of strings. type: list elements: str state: @@ -66,19 +55,17 @@ type: str recursive: description: - - If O(state=delete), a flag indicating whether a single entry or the - whole branch must be deleted. + - If O(state=delete), a flag indicating whether a single entry or the whole branch must be deleted. type: bool default: false version_added: 4.6.0 extends_documentation_fragment: - community.general.ldap.documentation - community.general.attributes - -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Make sure we have a parent entry for users community.general.ldap_entry: dn: ou=users,dc=example,dc=com @@ -103,19 +90,19 @@ attributes: description: An LDAP Administrator roleOccupant: - - cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com - - cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com + - cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com + - cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com olcAccess: - - >- - {0}to attrs=userPassword,shadowLastChange - by self write - by anonymous auth - by dn="cn=admin,dc=example,dc=com" write - by * none' - - >- - {1}to dn.base="dc=example,dc=com" - by dn="cn=admin,dc=example,dc=com" write - by * read + - >- + {0}to attrs=userPassword,shadowLastChange + by self write + by anonymous auth + by dn="cn=admin,dc=example,dc=com" write + by * none' + - >- + {1}to dn.base="dc=example,dc=com" + by dn="cn=admin,dc=example,dc=com" write + by * read - name: Get rid of an old entry community.general.ldap_entry: @@ -143,7 +130,7 @@ """ -RETURN = """ +RETURN = r""" # Default return values """ diff --git a/plugins/modules/ldap_passwd.py b/plugins/modules/ldap_passwd.py index 5044586b0fd..ab2c9a890b7 100644 --- a/plugins/modules/ldap_passwd.py +++ b/plugins/modules/ldap_passwd.py @@ -9,21 +9,16 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: ldap_passwd short_description: Set passwords in LDAP description: - - Set a password for an LDAP entry. This module only asserts that - a given password is valid for a given entry. To assert the - existence of an entry, see M(community.general.ldap_entry). + - Set a password for an LDAP entry. This module only asserts that a given password is valid for a given entry. To assert the existence of an + entry, see M(community.general.ldap_entry). notes: - - The default authentication settings will attempt to use a SASL EXTERNAL - bind over a UNIX domain socket. This works well with the default Ubuntu - install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL - rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in O(bind_dn) - and O(bind_pw). + - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu + install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you + need to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw). author: - Keller Fuchs (@KellerFuchs) requirements: @@ -41,10 +36,9 @@ extends_documentation_fragment: - community.general.ldap.documentation - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Set a password for the admin user community.general.ldap_passwd: dn: cn=admin,dc=example,dc=com @@ -56,13 +50,13 @@ passwd: "{{ item.value }}" with_dict: alice: alice123123 - bob: "|30b!" + bob: "|30b!" admin: "{{ vault_secret }}" """ -RETURN = """ +RETURN = r""" modlist: - description: list of modified parameters + description: List of modified parameters. returned: success type: list sample: diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py index 7958f86e0b7..6c47c2f7e0e 100644 --- a/plugins/modules/ldap_search.py +++ b/plugins/modules/ldap_search.py @@ -10,19 +10,15 @@ __metaclass__ = type DOCUMENTATION = r""" ---- module: ldap_search version_added: '0.2.0' short_description: Search for entries in a LDAP server description: - Return the results of an LDAP search. notes: - - The default authentication settings will attempt to use a SASL EXTERNAL - bind over a UNIX domain socket. This works well with the default Ubuntu - install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL - rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in O(bind_dn) - and O(bind_pw). + - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu + install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you + need to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw). author: - Sebastian Pfahl (@eryx12o45) requirements: @@ -55,30 +51,26 @@ type: list elements: str description: - - A list of attributes for limiting the result. Use an - actual list or a comma-separated string. + - A list of attributes for limiting the result. Use an actual list or a comma-separated string. schema: default: false type: bool description: - - Set to V(true) to return the full attribute schema of entries, not - their attribute values. Overrides O(attrs) when provided. + - Set to V(true) to return the full attribute schema of entries, not their attribute values. Overrides O(attrs) when provided. page_size: default: 0 type: int description: - - The page size when performing a simple paged result search (RFC 2696). - This setting can be tuned to reduce issues with timeouts and server limits. + - The page size when performing a simple paged result search (RFC 2696). This setting can be tuned to reduce issues with timeouts and server + limits. - Setting the page size to V(0) (default) disables paged searching. version_added: 7.1.0 base64_attributes: description: - - If provided, all attribute values returned that are listed in this option - will be Base64 encoded. - - If the special value V(*) appears in this list, all attributes will be - Base64 encoded. - - All other attribute values will be converted to UTF-8 strings. If they - contain binary data, please note that invalid UTF-8 bytes will be omitted. + - If provided, all attribute values returned that are listed in this option will be Base64 encoded. + - If the special value V(*) appears in this list, all attributes will be Base64 encoded. + - All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8 bytes will + be omitted. type: list elements: str version_added: 7.0.0 diff --git a/plugins/modules/librato_annotation.py b/plugins/modules/librato_annotation.py index ebfb751546a..b4f7dd54ccb 100644 --- a/plugins/modules/librato_annotation.py +++ b/plugins/modules/librato_annotation.py @@ -9,74 +9,73 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: librato_annotation short_description: Create an annotation in librato description: - - Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically + - Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically. author: "Seth Edwards (@Sedward)" requirements: [] 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: - user: - type: str - description: - - Librato account username - required: true - api_key: - type: str - description: - - Librato account api key - required: true - name: - type: str - description: - - The annotation stream name - - If the annotation stream does not exist, it will be created automatically - required: false - title: - type: str - description: - - The title of an annotation is a string and may contain spaces - - The title should be a short, high-level summary of the annotation e.g. v45 Deployment - required: true - source: - type: str - description: - - A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population - required: false + user: + type: str description: - type: str - description: - - The description contains extra metadata about a particular annotation - - The description should contain specifics on the individual annotation e.g. Deployed 9b562b2 shipped new feature foo! - required: false - start_time: - type: int - description: - - The unix timestamp indicating the time at which the event referenced by this annotation started - required: false - end_time: - type: int - description: - - The unix timestamp indicating the time at which the event referenced by this annotation ended - - For events that have a duration, this is a useful way to annotate the duration of the event - required: false - links: - type: list - elements: dict - description: - - See examples -''' + - Librato account username. + required: true + api_key: + type: str + description: + - Librato account api key. + required: true + name: + type: str + description: + - The annotation stream name. + - If the annotation stream does not exist, it will be created automatically. + required: false + title: + type: str + description: + - The title of an annotation is a string and may contain spaces. + - The title should be a short, high-level summary of the annotation for example V(v45 Deployment). + required: true + source: + type: str + description: + - A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population. + required: false + description: + type: str + description: + - The description contains extra metadata about a particular annotation. + - The description should contain specifics on the individual annotation for example V(Deployed 9b562b2 shipped new feature foo!). + required: false + start_time: + type: int + description: + - The unix timestamp indicating the time at which the event referenced by this annotation started. + required: false + end_time: + type: int + description: + - The unix timestamp indicating the time at which the event referenced by this annotation ended. + - For events that have a duration, this is a useful way to annotate the duration of the event. + required: false + links: + type: list + elements: dict + description: + - See examples. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a simple annotation event with a source community.general.librato_annotation: user: user@example.com @@ -105,7 +104,7 @@ description: This is a detailed description of maintenance start_time: 1395940006 end_time: 1395954406 -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url diff --git a/plugins/modules/linode.py b/plugins/modules/linode.py index 9b0dabdff28..9d907c898bb 100644 --- a/plugins/modules/linode.py +++ b/plugins/modules/linode.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: linode short_description: Manage instances on the Linode Public Cloud description: @@ -24,34 +23,32 @@ options: state: description: - - Indicate desired state of the resource - choices: [ absent, active, deleted, present, restarted, started, stopped ] + - Indicate desired state of the resource. + choices: [absent, active, deleted, present, restarted, started, stopped] default: present type: str api_key: description: - - Linode API key. - - E(LINODE_API_KEY) environment variable can be used instead. + - Linode API key. + - E(LINODE_API_KEY) environment variable can be used instead. type: str required: true name: description: - - Name to give the instance (alphanumeric, dashes, underscore). - - To keep sanity on the Linode Web Console, name is prepended with C(LinodeID-). + - Name to give the instance (alphanumeric, dashes, underscore). + - To keep sanity on the Linode Web Console, name is prepended with C(LinodeID-). required: true type: str displaygroup: description: - - Add the instance to a Display Group in Linode Manager. + - Add the instance to a Display Group in Linode Manager. type: str default: '' linode_id: description: - - Unique ID of a linode server. This value is read-only in the sense that - if you specify it on creation of a Linode it will not be used. The - Linode API generates these IDs and we can those generated value here to - reference a Linode more specifically. This is useful for idempotence. - aliases: [ lid ] + - Unique ID of a linode server. This value is read-only in the sense that if you specify it on creation of a Linode it will not be used. + The Linode API generates these IDs and we can those generated value here to reference a Linode more specifically. This is useful for idempotence. + aliases: [lid] type: int additional_disks: description: @@ -61,119 +58,118 @@ elements: dict alert_bwin_enabled: description: - - Set status of bandwidth in alerts. + - Set status of bandwidth in alerts. type: bool alert_bwin_threshold: description: - - Set threshold in MB of bandwidth in alerts. + - Set threshold in MB of bandwidth in alerts. type: int alert_bwout_enabled: description: - - Set status of bandwidth out alerts. + - Set status of bandwidth out alerts. type: bool alert_bwout_threshold: description: - - Set threshold in MB of bandwidth out alerts. + - Set threshold in MB of bandwidth out alerts. type: int alert_bwquota_enabled: description: - - Set status of bandwidth quota alerts as percentage of network transfer quota. + - Set status of bandwidth quota alerts as percentage of network transfer quota. type: bool alert_bwquota_threshold: description: - - Set threshold in MB of bandwidth quota alerts. + - Set threshold in MB of bandwidth quota alerts. type: int alert_cpu_enabled: description: - - Set status of receiving CPU usage alerts. + - Set status of receiving CPU usage alerts. type: bool alert_cpu_threshold: description: - - Set percentage threshold for receiving CPU usage alerts. Each CPU core adds 100% to total. + - Set percentage threshold for receiving CPU usage alerts. Each CPU core adds 100% to total. type: int alert_diskio_enabled: description: - - Set status of receiving disk IO alerts. + - Set status of receiving disk IO alerts. type: bool alert_diskio_threshold: description: - - Set threshold for average IO ops/sec over 2 hour period. + - Set threshold for average IO ops/sec over 2 hour period. type: int backupweeklyday: description: - - Day of the week to take backups. + - Day of the week to take backups. type: int backupwindow: description: - - The time window in which backups will be taken. + - The time window in which backups will be taken. type: int plan: description: - - plan to use for the instance (Linode plan) + - Plan to use for the instance (Linode plan). type: int payment_term: description: - - payment term to use for the instance (payment term in months) + - Payment term to use for the instance (payment term in months). default: 1 - choices: [ 1, 12, 24 ] + choices: [1, 12, 24] type: int password: description: - - root password to apply to a new server (auto generated if missing) + - Root password to apply to a new server (auto generated if missing). type: str private_ip: description: - - Add private IPv4 address when Linode is created. - - Default is V(false). + - Add private IPv4 address when Linode is created. + - Default is V(false). type: bool ssh_pub_key: description: - - SSH public key applied to root user + - SSH public key applied to root user. type: str swap: description: - - swap size in MB + - Swap size in MB. default: 512 type: int distribution: description: - - distribution to use for the instance (Linode Distribution) + - Distribution to use for the instance (Linode Distribution). type: int datacenter: description: - - datacenter to create an instance in (Linode Datacenter) + - Datacenter to create an instance in (Linode Datacenter). type: int kernel_id: description: - - kernel to use for the instance (Linode Kernel) + - Kernel to use for the instance (Linode Kernel). type: int wait: description: - - wait for the instance to be in state V(running) before returning + - Wait for the instance to be in state V(running) before returning. type: bool default: true wait_timeout: description: - - how long before wait gives up, in seconds + - How long before wait gives up, in seconds. default: 300 type: int watchdog: description: - - Set status of Lassie watchdog. + - Set status of Lassie watchdog. type: bool default: true requirements: - - linode-python + - linode-python author: -- Vincent Viallet (@zbal) + - Vincent Viallet (@zbal) notes: - Please note, linode-python does not have python 3 support. - This module uses the now deprecated v3 of the Linode API. - Please review U(https://www.linode.com/api/linode) for determining the required parameters. -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Create a new Linode community.general.linode: name: linode-test1 @@ -185,97 +181,97 @@ - name: Create a server with a private IP Address community.general.linode: - module: linode - api_key: 'longStringFromLinodeApi' - name: linode-test1 - plan: 1 - datacenter: 2 - distribution: 99 - password: 'superSecureRootPassword' - private_ip: true - ssh_pub_key: 'ssh-rsa qwerty' - swap: 768 - wait: true - wait_timeout: 600 - state: present + module: linode + api_key: 'longStringFromLinodeApi' + name: linode-test1 + plan: 1 + datacenter: 2 + distribution: 99 + password: 'superSecureRootPassword' + private_ip: true + ssh_pub_key: 'ssh-rsa qwerty' + swap: 768 + wait: true + wait_timeout: 600 + state: present delegate_to: localhost register: linode_creation - name: Fully configure new server community.general.linode: - api_key: 'longStringFromLinodeApi' - name: linode-test1 - plan: 4 - datacenter: 2 - distribution: 99 - kernel_id: 138 - password: 'superSecureRootPassword' - private_ip: true - ssh_pub_key: 'ssh-rsa qwerty' - swap: 768 - wait: true - wait_timeout: 600 - state: present - alert_bwquota_enabled: true - alert_bwquota_threshold: 80 - alert_bwin_enabled: true - alert_bwin_threshold: 10 - alert_cpu_enabled: true - alert_cpu_threshold: 210 - alert_bwout_enabled: true - alert_bwout_threshold: 10 - alert_diskio_enabled: true - alert_diskio_threshold: 10000 - backupweeklyday: 1 - backupwindow: 2 - displaygroup: 'test' - additional_disks: + api_key: 'longStringFromLinodeApi' + name: linode-test1 + plan: 4 + datacenter: 2 + distribution: 99 + kernel_id: 138 + password: 'superSecureRootPassword' + private_ip: true + ssh_pub_key: 'ssh-rsa qwerty' + swap: 768 + wait: true + wait_timeout: 600 + state: present + alert_bwquota_enabled: true + alert_bwquota_threshold: 80 + alert_bwin_enabled: true + alert_bwin_threshold: 10 + alert_cpu_enabled: true + alert_cpu_threshold: 210 + alert_bwout_enabled: true + alert_bwout_threshold: 10 + alert_diskio_enabled: true + alert_diskio_threshold: 10000 + backupweeklyday: 1 + backupwindow: 2 + displaygroup: 'test' + additional_disks: - {Label: 'disk1', Size: 2500, Type: 'raw'} - {Label: 'newdisk', Size: 2000} - watchdog: true + watchdog: true delegate_to: localhost register: linode_creation - name: Ensure a running server (create if missing) community.general.linode: - api_key: 'longStringFromLinodeApi' - name: linode-test1 - plan: 1 - datacenter: 2 - distribution: 99 - password: 'superSecureRootPassword' - ssh_pub_key: 'ssh-rsa qwerty' - swap: 768 - wait: true - wait_timeout: 600 - state: present + api_key: 'longStringFromLinodeApi' + name: linode-test1 + plan: 1 + datacenter: 2 + distribution: 99 + password: 'superSecureRootPassword' + ssh_pub_key: 'ssh-rsa qwerty' + swap: 768 + wait: true + wait_timeout: 600 + state: present delegate_to: localhost register: linode_creation - name: Delete a server community.general.linode: - api_key: 'longStringFromLinodeApi' - name: linode-test1 - linode_id: "{{ linode_creation.instance.id }}" - state: absent + api_key: 'longStringFromLinodeApi' + name: linode-test1 + linode_id: "{{ linode_creation.instance.id }}" + state: absent delegate_to: localhost - name: Stop a server community.general.linode: - api_key: 'longStringFromLinodeApi' - name: linode-test1 - linode_id: "{{ linode_creation.instance.id }}" - state: stopped + api_key: 'longStringFromLinodeApi' + name: linode-test1 + linode_id: "{{ linode_creation.instance.id }}" + state: stopped delegate_to: localhost - name: Reboot a server community.general.linode: - api_key: 'longStringFromLinodeApi' - name: linode-test1 - linode_id: "{{ linode_creation.instance.id }}" - state: restarted + api_key: 'longStringFromLinodeApi' + name: linode-test1 + linode_id: "{{ linode_creation.instance.id }}" + state: restarted delegate_to: localhost -''' +""" import time import traceback diff --git a/plugins/modules/linode_v4.py b/plugins/modules/linode_v4.py index da885f3a5f7..cac890f79b6 100644 --- a/plugins/modules/linode_v4.py +++ b/plugins/modules/linode_v4.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: linode_v4 short_description: Manage instances on the Linode cloud description: Manage instances on the Linode cloud. @@ -18,9 +17,8 @@ author: - Luke Murphy (@decentral1se) notes: - - No Linode resizing is currently implemented. This module will, in time, - replace the current Linode module which uses deprecated API bindings on the - Linode side. + - No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated API bindings + on the Linode side. extends_documentation_fragment: - community.general.attributes attributes: @@ -31,52 +29,44 @@ options: region: description: - - The region of the instance. This is a required parameter only when - creating Linode instances. See - U(https://www.linode.com/docs/api/regions/). + - The region of the instance. This is a required parameter only when creating Linode instances. See U(https://www.linode.com/docs/api/regions/). type: str image: description: - - The image of the instance. This is a required parameter only when - creating Linode instances. See - U(https://www.linode.com/docs/api/images/). + - The image of the instance. This is a required parameter only when creating Linode instances. + - See U(https://www.linode.com/docs/api/images/). type: str type: description: - - The type of the instance. This is a required parameter only when - creating Linode instances. See - U(https://www.linode.com/docs/api/linode-types/). + - The type of the instance. This is a required parameter only when creating Linode instances. + - See U(https://www.linode.com/docs/api/linode-types/). type: str label: description: - - The instance label. This label is used as the main determiner for - idempotence for the module and is therefore mandatory. + - The instance label. This label is used as the main determiner for idempotence for the module and is therefore mandatory. type: str required: true group: description: - - The group that the instance should be marked under. Please note, that - group labelling is deprecated but still supported. The encouraged - method for marking instances is to use tags. + - The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported. The encouraged + method for marking instances is to use tags. type: str private_ip: description: - - If V(true), the created Linode will have private networking enabled and - assigned a private IPv4 address. + - If V(true), the created Linode will have private networking enabled and assigned a private IPv4 address. type: bool default: false version_added: 3.0.0 tags: description: - - The tags that the instance should be marked under. See - U(https://www.linode.com/docs/api/tags/). + - The tags that the instance should be marked under. + - See U(https://www.linode.com/docs/api/tags/). type: list elements: str root_pass: description: - - The password for the root user. If not specified, one will be - generated. This generated password will be available in the task - success JSON. + - The password for the root user. If not specified, one will be generated. This generated password will be available in the task success + JSON. type: str authorized_keys: description: @@ -88,33 +78,31 @@ - The desired instance state. type: str choices: - - present - - absent + - present + - absent required: true access_token: description: - - The Linode API v4 access token. It may also be specified by exposing - the E(LINODE_ACCESS_TOKEN) environment variable. See - U(https://www.linode.com/docs/api#access-and-authentication). + - The Linode API v4 access token. It may also be specified by exposing the E(LINODE_ACCESS_TOKEN) environment variable. + - See U(https://www.linode.com/docs/api#access-and-authentication). required: true type: str stackscript_id: description: - The numeric ID of the StackScript to use when creating the instance. - See U(https://www.linode.com/docs/api/stackscripts/). + - See U(https://www.linode.com/docs/api/stackscripts/). type: int version_added: 1.3.0 stackscript_data: description: - - An object containing arguments to any User Defined Fields present in - the StackScript used when creating the instance. - Only valid when a stackscript_id is provided. - See U(https://www.linode.com/docs/api/stackscripts/). + - An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance. Only valid when + a O(stackscript_id) is provided. + - See U(https://www.linode.com/docs/api/stackscripts/). type: dict version_added: 1.3.0 -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Create a new Linode. community.general.linode_v4: label: new-linode @@ -135,7 +123,7 @@ state: absent """ -RETURN = """ +RETURN = r""" instance: description: The instance description in JSON serialized form. returned: Always. diff --git a/plugins/modules/listen_ports_facts.py b/plugins/modules/listen_ports_facts.py index 08030a8b371..9f9eb664811 100644 --- a/plugins/modules/listen_ports_facts.py +++ b/plugins/modules/listen_ports_facts.py @@ -8,21 +8,19 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: listen_ports_facts author: - - Nathan Davison (@ndavison) + - Nathan Davison (@ndavison) description: - - Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands. - - This module currently supports Linux only. + - Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands. + - This module currently supports Linux only. requirements: - netstat or ss short_description: Gather facts on processes listening on TCP and UDP ports notes: - - | - C(ss) returns all processes for each listen address and port. - This plugin will return each of them, so multiple entries for the same listen address and port are likely in results. + - C(ss) returns all processes for each listen address and port. + - This plugin will return each of them, so multiple entries for the same listen address and port are likely in results. extends_documentation_fragment: - community.general.attributes - community.general.attributes.facts @@ -31,7 +29,7 @@ command: description: - Override which command to use for fetching listen ports. - - 'By default module will use first found supported command on the system (in alphanumerical order).' + - By default module will use first found supported command on the system (in alphanumerical order). type: str choices: - netstat @@ -39,15 +37,15 @@ version_added: 4.1.0 include_non_listening: description: - - Show both listening and non-listening sockets (for TCP this means established connections). - - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), - RV(ansible_facts.tcp_listen[].foreign_address), and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts. + - Show both listening and non-listening sockets (for TCP this means established connections). + - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), RV(ansible_facts.tcp_listen[].foreign_address), + and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts. type: bool default: false version_added: 5.4.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Gather facts on listening ports community.general.listen_ports_facts: @@ -77,11 +75,11 @@ community.general.listen_ports_facts: command: 'netstat' include_non_listening: true -''' +""" -RETURN = r''' +RETURN = r""" ansible_facts: - description: Dictionary containing details of TCP and UDP ports with listening servers + description: Dictionary containing details of TCP and UDP ports with listening servers. returned: always type: complex contains: @@ -189,7 +187,7 @@ returned: always type: str sample: "root" -''' +""" import re import platform diff --git a/plugins/modules/lldp.py b/plugins/modules/lldp.py index fb608ff138d..baefb09d912 100644 --- a/plugins/modules/lldp.py +++ b/plugins/modules/lldp.py @@ -9,13 +9,12 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: lldp -requirements: [ lldpctl ] -short_description: Get details reported by lldp +requirements: [lldpctl] +short_description: Get details reported by LLDP description: - - Reads data out of lldpctl + - Reads data out of C(lldpctl). extends_documentation_fragment: - community.general.attributes attributes: @@ -26,25 +25,24 @@ options: {} author: "Andy Hill (@andyhky)" notes: - - Requires lldpd running and lldp enabled on switches -''' + - Requires C(lldpd) running and LLDP enabled on switches. +""" -EXAMPLES = ''' +EXAMPLES = r""" # Retrieve switch/port information - - name: Gather information from lldp - community.general.lldp: +- name: Gather information from LLDP + community.general.lldp: - - name: Print each switch/port - ansible.builtin.debug: +- name: Print each switch/port + ansible.builtin.debug: msg: "{{ lldp[item]['chassis']['name'] }} / {{ lldp[item]['port']['ifname'] }}" - with_items: "{{ lldp.keys() }}" + with_items: "{{ lldp.keys() }}" # TASK: [Print each switch/port] *********************************************************** # ok: [10.13.0.22] => (item=eth2) => {"item": "eth2", "msg": "switch1.example.com / Gi0/24"} # ok: [10.13.0.22] => (item=eth1) => {"item": "eth1", "msg": "switch2.example.com / Gi0/3"} # ok: [10.13.0.22] => (item=eth0) => {"item": "eth0", "msg": "switch3.example.com / Gi0/3"} - -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/locale_gen.py b/plugins/modules/locale_gen.py index 8886cdc9cdc..6c0412f4648 100644 --- a/plugins/modules/locale_gen.py +++ b/plugins/modules/locale_gen.py @@ -8,40 +8,39 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: locale_gen short_description: Creates or removes locales description: - - Manages locales by editing /etc/locale.gen and invoking locale-gen. + - Manages locales by editing /etc/locale.gen and invoking C(locale-gen). author: - - Augustus Kling (@AugustusKling) + - Augustus Kling (@AugustusKling) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - type: list - elements: str - description: - - Name and encoding of the locales, such as V(en_GB.UTF-8). - - Before community.general 9.3.0, this was a string. Using a string still works. - required: true - state: - type: str - description: - - Whether the locale shall be present. - choices: [ absent, present ] - default: present + name: + type: list + elements: str + description: + - Name and encoding of the locales, such as V(en_GB.UTF-8). + - Before community.general 9.3.0, this was a string. Using a string still works. + required: true + state: + type: str + description: + - Whether the locale shall be present. + choices: [absent, present] + default: present notes: - - This module does not support RHEL-based systems. -''' + - This module does not support RHEL-based systems. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Ensure a locale exists community.general.locale_gen: name: de_CH.UTF-8 @@ -53,7 +52,7 @@ - en_GB.UTF-8 - nl_NL.UTF-8 state: present -''' +""" import os import re diff --git a/plugins/modules/logentries.py b/plugins/modules/logentries.py index f177cf45469..420f054fac9 100644 --- a/plugins/modules/logentries.py +++ b/plugins/modules/logentries.py @@ -9,49 +9,49 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: logentries author: "Ivan Vanderbyl (@ivanvanderbyl)" -short_description: Module for tracking logs via logentries.com +short_description: Module for tracking logs using U(logentries.com) description: - - Sends logs to LogEntries in realtime + - Sends logs to LogEntries in realtime. 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: - type: str - description: - - path to a log file - required: true - state: - type: str - description: - - following state of the log - choices: [ 'present', 'absent', 'followed', 'unfollowed' ] - required: false - default: present - name: - type: str - description: - - name of the log - required: false - logtype: - type: str - description: - - type of the log - required: false - aliases: [type] + path: + type: str + description: + - Path to a log file. + required: true + state: + type: str + description: + - Following state of the log. + choices: ['present', 'absent', 'followed', 'unfollowed'] + required: false + default: present + name: + type: str + description: + - Name of the log. + required: false + logtype: + type: str + description: + - Type of the log. + required: false + aliases: [type] notes: - - Requires the LogEntries agent which can be installed following the instructions at logentries.com -''' -EXAMPLES = ''' + - Requires the LogEntries agent which can be installed following the instructions at U(logentries.com). +""" + +EXAMPLES = r""" - name: Track nginx logs community.general.logentries: path: /var/log/nginx/access.log @@ -62,7 +62,7 @@ community.general.logentries: path: /var/log/nginx/error.log state: absent -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/logentries_msg.py b/plugins/modules/logentries_msg.py index 03851ad1f4f..dd3b88d6248 100644 --- a/plugins/modules/logentries_msg.py +++ b/plugins/modules/logentries_msg.py @@ -9,12 +9,11 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: logentries_msg short_description: Send a message to logentries description: - - Send a message to logentries + - Send a message to logentries. extends_documentation_fragment: - community.general.attributes attributes: @@ -36,24 +35,24 @@ api: type: str description: - - API endpoint + - API endpoint. default: data.logentries.com port: type: int description: - - API endpoint port + - API endpoint port. default: 80 author: "Jimmy Tang (@jcftang) " -''' +""" -RETURN = '''# ''' +RETURN = """# """ -EXAMPLES = ''' +EXAMPLES = r""" - name: Send a message to logentries community.general.logentries_msg: - token=00000000-0000-0000-0000-000000000000 - msg="{{ ansible_hostname }}" -''' + token: 00000000-0000-0000-0000-000000000000 + msg: "{{ ansible_hostname }}" +""" import socket diff --git a/plugins/modules/logstash_plugin.py b/plugins/modules/logstash_plugin.py index 7ee118ff287..ba7bdc2cc58 100644 --- a/plugins/modules/logstash_plugin.py +++ b/plugins/modules/logstash_plugin.py @@ -8,53 +8,51 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: logstash_plugin short_description: Manage Logstash plugins description: - - Manages Logstash plugins. + - Manages Logstash plugins. author: Loic Blot (@nerzhul) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - name: - type: str - description: - - Install plugin with that name. - required: true - state: - type: str - description: - - Apply plugin state. - choices: ["present", "absent"] - default: present - plugin_bin: - type: path - description: - - Specify logstash-plugin to use for plugin management. - default: /usr/share/logstash/bin/logstash-plugin - proxy_host: - type: str - description: - - Proxy host to use during plugin installation. - proxy_port: - type: str - description: - - Proxy port to use during plugin installation. - version: - type: str - description: - - Specify plugin Version of the plugin to install. - If plugin exists with previous version, it will NOT be updated. -''' - -EXAMPLES = ''' + name: + type: str + description: + - Install plugin with that name. + required: true + state: + type: str + description: + - Apply plugin state. + choices: ["present", "absent"] + default: present + plugin_bin: + type: path + description: + - Specify logstash-plugin to use for plugin management. + default: /usr/share/logstash/bin/logstash-plugin + proxy_host: + type: str + description: + - Proxy host to use during plugin installation. + proxy_port: + type: str + description: + - Proxy port to use during plugin installation. + version: + type: str + description: + - Specify plugin Version of the plugin to install. If plugin exists with previous version, it will NOT be updated. +""" + +EXAMPLES = r""" - name: Install Logstash beats input plugin community.general.logstash_plugin: state: present @@ -77,7 +75,7 @@ name: logstash-input-beats environment: LS_JAVA_OPTS: "-Xms256m -Xmx256m" -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/lvg.py b/plugins/modules/lvg.py index 7ff7e3a2e75..f6f8abc0209 100644 --- a/plugins/modules/lvg.py +++ b/plugins/modules/lvg.py @@ -9,10 +9,9 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: -- Alexander Bulimov (@abulimov) + - Alexander Bulimov (@abulimov) module: lvg short_description: Configure LVM volume groups description: @@ -27,78 +26,76 @@ options: vg: description: - - The name of the volume group. + - The name of the volume group. type: str required: true pvs: description: - - List of comma-separated devices to use as physical devices in this volume group. - - Required when creating or resizing volume group. - - The module will take care of running pvcreate if needed. + - List of comma-separated devices to use as physical devices in this volume group. + - Required when creating or resizing volume group. + - The module will take care of running pvcreate if needed. type: list elements: str pesize: description: - - "The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector - (where the sector size is the largest sector size of the PVs currently used in the VG), - or at least 128KiB." - - O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte. + - The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the largest sector size + of the PVs currently used in the VG), or at least 128KiB. + - O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte. type: str default: "4" pv_options: description: - - Additional options to pass to C(pvcreate) when creating the volume group. + - Additional options to pass to C(pvcreate) when creating the volume group. type: str default: '' pvresize: description: - - If V(true), resize the physical volume to the maximum available size. + - If V(true), resize the physical volume to the maximum available size. type: bool default: false version_added: '0.2.0' vg_options: description: - - Additional options to pass to C(vgcreate) when creating the volume group. + - Additional options to pass to C(vgcreate) when creating the volume group. type: str default: '' state: description: - - Control if the volume group exists and it's state. - - The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0 - - "If V(active) or V(inactive), the module manages the VG's logical volumes current state. - The module also handles the VG's autoactivation state if supported - unless when creating a volume group and the autoactivation option specified in O(vg_options)." + - Control if the volume group exists and it's state. + - The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0. + - If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the VG's autoactivation + state if supported unless when creating a volume group and the autoactivation option specified in O(vg_options). type: str - choices: [ absent, present, active, inactive ] + choices: [absent, present, active, inactive] default: present force: description: - - If V(true), allows to remove volume group with logical volumes. + - If V(true), allows to remove volume group with logical volumes. type: bool default: false reset_vg_uuid: description: - - Whether the volume group's UUID is regenerated. - - This is B(not idempotent). Specifying this parameter always results in a change. + - Whether the volume group's UUID is regenerated. + - This is B(not idempotent). Specifying this parameter always results in a change. type: bool default: false version_added: 7.1.0 reset_pv_uuid: description: - - Whether the volume group's physical volumes' UUIDs are regenerated. - - This is B(not idempotent). Specifying this parameter always results in a change. + - Whether the volume group's physical volumes' UUIDs are regenerated. + - This is B(not idempotent). Specifying this parameter always results in a change. type: bool default: false version_added: 7.1.0 seealso: -- module: community.general.filesystem -- module: community.general.lvol -- module: community.general.parted + - module: community.general.filesystem + - module: community.general.lvol + - module: community.general.parted notes: - This module does not modify PE size for already present volume group. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB community.general.lvg: vg: vg.services @@ -154,7 +151,7 @@ pvs: /dev/sdb1,/dev/sdc5 reset_vg_uuid: true reset_pv_uuid: true -''' +""" import itertools import os diff --git a/plugins/modules/lvg_rename.py b/plugins/modules/lvg_rename.py index bd48ffa62f1..37f513697e9 100644 --- a/plugins/modules/lvg_rename.py +++ b/plugins/modules/lvg_rename.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - Laszlo Szomor (@lszomor) module: lvg_rename @@ -27,23 +26,23 @@ options: vg: description: - - The name or UUID of the source VG. - - See V(vgrename(8\)) for valid values. + - The name or UUID of the source VG. + - See V(vgrename(8\)) for valid values. type: str required: true vg_new: description: - - The new name of the VG. - - See V(lvm(8\)) for valid names. + - The new name of the VG. + - See V(lvm(8\)) for valid names. type: str required: true seealso: -- module: community.general.lvg + - module: community.general.lvg notes: - This module does not modify VG renaming-related configurations like C(fstab) entries or boot parameters. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Rename a VG by name community.general.lvg_rename: vg: vg_orig_name @@ -53,7 +52,7 @@ community.general.lvg_rename: vg_uuid: SNgd0Q-rPYa-dPB8-U1g6-4WZI-qHID-N7y9Vj vg_new: vg_new_name -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/lvol.py b/plugins/modules/lvol.py index 3a2f5c7cddb..34b24f7570c 100644 --- a/plugins/modules/lvol.py +++ b/plugins/modules/lvol.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: - - Jeroen Hoekx (@jhoekx) - - Alexander Bulimov (@abulimov) - - Raoul Baudach (@unkaputtbar112) - - Ziga Kern (@zigaSRC) + - Jeroen Hoekx (@jhoekx) + - Alexander Bulimov (@abulimov) + - Raoul Baudach (@unkaputtbar112) + - Ziga Kern (@zigaSRC) module: lvol short_description: Configure LVM logical volumes description: @@ -31,75 +30,69 @@ type: str required: true description: - - The volume group this logical volume is part of. + - The volume group this logical volume is part of. lv: type: str description: - - The name of the logical volume. + - The name of the logical volume. size: type: str description: - - The size of the logical volume, according to lvcreate(8) --size, by - default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE] units; or - according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN]; - Float values must begin with a digit. - - When resizing, apart from specifying an absolute size you may, according to - lvextend(8)|lvreduce(8) C(--size), specify the amount to extend the logical volume with - the prefix V(+) or the amount to reduce the logical volume by with prefix V(-). - - Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0. - - Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent). + - The size of the logical volume, according to lvcreate(8) C(--size), by default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE] + units; or according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN]; Float values must begin with a digit. + - When resizing, apart from specifying an absolute size you may, according to lvextend(8)|lvreduce(8) C(--size), specify the amount to extend + the logical volume with the prefix V(+) or the amount to reduce the logical volume by with prefix V(-). + - Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0. + - Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent). state: type: str description: - - Control if the logical volume exists. If V(present) and the - volume does not already exist then the O(size) option is required. - choices: [ absent, present ] + - Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option is required. + choices: [absent, present] default: present active: description: - - Whether the volume is active and visible to the host. + - Whether the volume is active and visible to the host. type: bool default: true force: description: - - Shrink or remove operations of volumes requires this switch. Ensures that - that filesystems get never corrupted/destroyed by mistake. + - Shrink or remove operations of volumes requires this switch. Ensures that that filesystems get never corrupted/destroyed by mistake. type: bool default: false opts: type: str description: - - Free-form options to be passed to the lvcreate command. + - Free-form options to be passed to the lvcreate command. snapshot: type: str description: - - The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the origin volume. + - The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the origin volume. pvs: type: list elements: str description: - - List of physical volumes (for example V(/dev/sda, /dev/sdb)). + - List of physical volumes (for example V(/dev/sda, /dev/sdb)). thinpool: type: str description: - - The thin pool volume name. When you want to create a thin provisioned volume, specify a thin pool volume name. + - The thin pool volume name. When you want to create a thin provisioned volume, specify a thin pool volume name. shrink: description: - - Shrink if current size is higher than size requested. + - Shrink if current size is higher than size requested. type: bool default: true resizefs: description: - - Resize the underlying filesystem together with the logical volume. - - Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. - Attempts to resize other filesystem types will fail. + - Resize the underlying filesystem together with the logical volume. + - Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. Attempts to resize other filesystem types will fail. type: bool default: false notes: - You must specify lv (when managing the state of logical volumes) or thinpool (when managing a thin provisioned volume). -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a logical volume of 512m community.general.lvol: vg: firefly @@ -233,7 +226,7 @@ lv: test thinpool: testpool size: 128g -''' +""" import re import shlex diff --git a/plugins/modules/lxc_container.py b/plugins/modules/lxc_container.py index 2d768eaafd5..9b44c4fc899 100644 --- a/plugins/modules/lxc_container.py +++ b/plugins/modules/lxc_container.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: lxc_container short_description: Manage LXC Containers description: @@ -19,183 +18,171 @@ extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - Name of a container. - type: str - required: true - backing_store: - choices: - - dir - - lvm - - loop - - btrfs - - overlayfs - - zfs - description: - - Backend storage type for the container. - type: str - default: dir - template: - description: - - Name of the template to use within an LXC create. - type: str - default: ubuntu - template_options: - description: - - Template options when building the container. - type: str - config: - description: - - Path to the LXC configuration file. - type: path - lv_name: - description: - - Name of the logical volume, defaults to the container name. - - If not specified, it defaults to C($CONTAINER_NAME). - type: str - vg_name: - description: - - If backend store is lvm, specify the name of the volume group. - type: str - default: lxc - thinpool: - description: - - Use LVM thin pool called TP. - type: str - fs_type: - description: - - Create fstype TYPE. - type: str - default: ext4 - fs_size: - description: - - File system Size. - type: str - default: 5G - directory: - description: - - Place rootfs directory under DIR. - type: path - zfs_root: - description: - - Create zfs under given zfsroot. - type: str - container_command: - description: - - Run a command within a container. - type: str - lxc_path: - description: - - Place container under E(PATH). - type: path - container_log: - description: - - Enable a container log for host actions to the container. - type: bool - default: false - container_log_level: - choices: - - Info - - info - - INFO - - Error - - error - - ERROR - - Debug - - debug - - DEBUG - description: - - Set the log level for a container where O(container_log) was set. - type: str - required: false - default: INFO - clone_name: - description: - - Name of the new cloned server. - - This is only used when state is clone. - type: str - clone_snapshot: - description: - - Create a snapshot a container when cloning. - - This is not supported by all container storage backends. - - Enabling this may fail if the backing store does not support snapshots. - type: bool - default: false - archive: - description: - - Create an archive of a container. - - This will create a tarball of the running container. - type: bool - default: false - archive_path: - description: - - Path the save the archived container. - - If the path does not exist the archive method will attempt to create it. - type: path - archive_compression: - choices: - - gzip - - bzip2 - - none - description: - - Type of compression to use when creating an archive of a running - container. - type: str - default: gzip - state: - choices: - - started - - stopped - - restarted - - absent - - frozen - - clone - description: - - Define the state of a container. - - If you clone a container using O(clone_name) the newly cloned - container created in a stopped state. - - The running container will be stopped while the clone operation is - happening and upon completion of the clone the original container - state will be restored. - type: str - default: started - container_config: - description: - - A list of C(key=value) options to use when configuring a container. - type: list - elements: str + name: + description: + - Name of a container. + type: str + required: true + backing_store: + choices: + - dir + - lvm + - loop + - btrfs + - overlayfs + - zfs + description: + - Backend storage type for the container. + type: str + default: dir + template: + description: + - Name of the template to use within an LXC create. + type: str + default: ubuntu + template_options: + description: + - Template options when building the container. + type: str + config: + description: + - Path to the LXC configuration file. + type: path + lv_name: + description: + - Name of the logical volume, defaults to the container name. + - If not specified, it defaults to E(CONTAINER_NAME). + type: str + vg_name: + description: + - If backend store is lvm, specify the name of the volume group. + type: str + default: lxc + thinpool: + description: + - Use LVM thin pool called TP. + type: str + fs_type: + description: + - Create fstype TYPE. + type: str + default: ext4 + fs_size: + description: + - File system Size. + type: str + default: 5G + directory: + description: + - Place rootfs directory under DIR. + type: path + zfs_root: + description: + - Create zfs under given zfsroot. + type: str + container_command: + description: + - Run a command within a container. + type: str + lxc_path: + description: + - Place container under E(PATH). + type: path + container_log: + description: + - Enable a container log for host actions to the container. + type: bool + default: false + container_log_level: + choices: + - Info + - info + - INFO + - Error + - error + - ERROR + - Debug + - debug + - DEBUG + description: + - Set the log level for a container where O(container_log) was set. + type: str + required: false + default: INFO + clone_name: + description: + - Name of the new cloned server. + - This is only used when state is clone. + type: str + clone_snapshot: + description: + - Create a snapshot a container when cloning. + - This is not supported by all container storage backends. + - Enabling this may fail if the backing store does not support snapshots. + type: bool + default: false + archive: + description: + - Create an archive of a container. + - This will create a tarball of the running container. + type: bool + default: false + archive_path: + description: + - Path the save the archived container. + - If the path does not exist the archive method will attempt to create it. + type: path + archive_compression: + choices: + - gzip + - bzip2 + - none + description: + - Type of compression to use when creating an archive of a running container. + type: str + default: gzip + state: + choices: + - started + - stopped + - restarted + - absent + - frozen + - clone + description: + - Define the state of a container. + - If you clone a container using O(clone_name) the newly cloned container created in a stopped state. + - The running container will be stopped while the clone operation is happening and upon completion of the clone the original container state + will be restored. + type: str + default: started + container_config: + description: + - A list of C(key=value) options to use when configuring a container. + type: list + elements: str requirements: - 'lxc >= 2.0 # OS package' - 'python3 >= 3.5 # OS Package' - 'python3-lxc # OS Package' notes: - - Containers must have a unique name. If you attempt to create a container - with a name that already exists in the users namespace the module will - simply return as "unchanged". - - The O(container_command) can be used with any state except V(absent). If - used with state V(stopped) the container will be V(started), the command - executed, and then the container V(stopped) again. Likewise if O(state=stopped) - and the container does not exist it will be first created, - V(started), the command executed, and then V(stopped). If you use a "|" - in the variable you can use common script formatting within the variable - itself. The O(container_command) option will always execute as BASH. - When using O(container_command), a log file is created in the C(/tmp/) directory - which contains both C(stdout) and C(stderr) of any command executed. - - If O(archive=true) the system will attempt to create a compressed - tarball of the running container. The O(archive) option supports LVM backed - containers and will create a snapshot of the running container when - creating the archive. - - If your distro does not have a package for C(python3-lxc), which is a - requirement for this module, it can be installed from source at - U(https://github.com/lxc/python3-lxc) or installed via pip using the - package name C(lxc). -''' + - Containers must have a unique name. If you attempt to create a container with a name that already exists in the users namespace the module + will simply return as "unchanged". + - The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will be V(started), the + command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container does not exist it will be first + created, V(started), the command executed, and then V(stopped). If you use a C(|) in the variable you can use common script formatting within + the variable itself. The O(container_command) option will always execute as C(bash). When using O(container_command), a log file is created in + the C(/tmp/) directory which contains both C(stdout) and C(stderr) of any command executed. + - If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option supports LVM backed + containers and will create a snapshot of the running container when creating the archive. + - If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed from source at + U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc). +""" EXAMPLES = r""" - name: Create a started container @@ -382,45 +369,45 @@ RETURN = r""" lxc_container: - description: container information - returned: success - type: complex - contains: - name: - description: name of the lxc container - returned: success - type: str - sample: test_host - init_pid: - description: pid of the lxc init process - returned: success - type: int - sample: 19786 - interfaces: - description: list of the container's network interfaces - returned: success - type: list - sample: [ "eth0", "lo" ] - ips: - description: list of ips - returned: success - type: list - sample: [ "10.0.3.3" ] - state: - description: resulting state of the container - returned: success - type: str - sample: "running" - archive: - description: resulting state of the container - returned: success, when archive is true - type: str - sample: "/tmp/test-container-config.tar" - clone: - description: if the container was cloned - returned: success, when clone_name is specified - type: bool - sample: true + description: Container information. + returned: success + type: complex + contains: + name: + description: Name of the lxc container. + returned: success + type: str + sample: test_host + init_pid: + description: Pid of the lxc init process. + returned: success + type: int + sample: 19786 + interfaces: + description: List of the container's network interfaces. + returned: success + type: list + sample: ["eth0", "lo"] + ips: + description: List of ips. + returned: success + type: list + sample: ["10.0.3.3"] + state: + description: Resulting state of the container. + returned: success + type: str + sample: "running" + archive: + description: Resulting state of the container. + returned: success, when archive is true + type: str + sample: "/tmp/test-container-config.tar" + clone: + description: If the container was cloned. + returned: success, when clone_name is specified + type: bool + sample: true """ import os diff --git a/plugins/modules/lxca_cmms.py b/plugins/modules/lxca_cmms.py index 1f811a7efa3..8ece67470be 100644 --- a/plugins/modules/lxca_cmms.py +++ b/plugins/modules/lxca_cmms.py @@ -8,16 +8,14 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: - Naval Patel (@navalkp) - Prashant Bhosale (@prabhosa) module: lxca_cmms short_description: Custom module for lxca cmms inventory utility description: - - This module returns/displays a inventory details of cmms - + - This module returns/displays a inventory details of cmms. attributes: check_mode: support: none @@ -26,32 +24,28 @@ options: uuid: - description: - uuid of device, this is string with length greater than 16. + description: UUID of device, this is string with length greater than 16. type: str command_options: - description: - options to filter nodes information + description: Options to filter nodes information. default: cmms choices: - - cmms - - cmms_by_uuid - - cmms_by_chassis_uuid + - cmms + - cmms_by_uuid + - cmms_by_chassis_uuid type: str chassis: - description: - uuid of chassis, this is string with length greater than 16. + description: UUID of chassis, this is string with length greater than 16. type: str extends_documentation_fragment: - community.general.lxca_common - community.general.attributes +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # get all cmms info - name: Get nodes data from LXCA community.general.lxca_cmms: @@ -76,28 +70,27 @@ auth_url: "https://10.243.15.168" chassis: "3C737AA5E31640CE949B10C129A8B01F" command_options: cmms_by_chassis_uuid +""" -''' - -RETURN = r''' +RETURN = r""" result: - description: cmms detail from lxca - returned: success - type: dict - sample: - cmmList: - - machineType: '' - model: '' - type: 'CMM' - uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF' + description: Cmms detail from lxca. + returned: success + type: dict + sample: + cmmList: + - machineType: '' + model: '' + type: 'CMM' + uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF' # bunch of properties - - machineType: '' - model: '' - type: 'CMM' - uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF' + - machineType: '' + model: '' + type: 'CMM' + uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF' # bunch of properties # Multiple cmms details -''' +""" import traceback from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/lxca_nodes.py b/plugins/modules/lxca_nodes.py index 3b37322edb8..f1336711148 100644 --- a/plugins/modules/lxca_nodes.py +++ b/plugins/modules/lxca_nodes.py @@ -8,16 +8,14 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: - Naval Patel (@navalkp) - Prashant Bhosale (@prabhosa) module: lxca_nodes short_description: Custom module for lxca nodes inventory utility description: - - This module returns/displays a inventory details of nodes - + - This module returns/displays a inventory details of nodes. attributes: check_mode: support: none @@ -26,34 +24,30 @@ options: uuid: - description: - uuid of device, this is string with length greater than 16. + description: UUID of device, this is string with length greater than 16. type: str command_options: - description: - options to filter nodes information + description: Options to filter nodes information. default: nodes choices: - - nodes - - nodes_by_uuid - - nodes_by_chassis_uuid - - nodes_status_managed - - nodes_status_unmanaged + - nodes + - nodes_by_uuid + - nodes_by_chassis_uuid + - nodes_status_managed + - nodes_status_unmanaged type: str chassis: - description: - uuid of chassis, this is string with length greater than 16. + description: UUID of chassis, this is string with length greater than 16. type: str extends_documentation_fragment: - community.general.lxca_common - community.general.attributes +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" # get all nodes info - name: Get nodes data from LXCA community.general.lxca_nodes: @@ -95,28 +89,27 @@ login_password: Password auth_url: "https://10.243.15.168" command_options: nodes_status_unmanaged +""" -''' - -RETURN = r''' +RETURN = r""" result: - description: nodes detail from lxca - returned: always - type: dict - sample: - nodeList: - - machineType: '6241' - model: 'AC1' - type: 'Rack-TowerServer' - uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF' + description: Nodes detail from lxca. + returned: always + type: dict + sample: + nodeList: + - machineType: '6241' + model: 'AC1' + type: 'Rack-TowerServer' + uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF' # bunch of properties - - machineType: '8871' - model: 'AC1' - type: 'Rack-TowerServer' - uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF' + - machineType: '8871' + model: 'AC1' + type: 'Rack-TowerServer' + uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF' # bunch of properties # Multiple nodes details -''' +""" import traceback from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/lxd_container.py b/plugins/modules/lxd_container.py index 5c5d8a4d8d2..3f0ab2607e3 100644 --- a/plugins/modules/lxd_container.py +++ b/plugins/modules/lxd_container.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: lxd_container short_description: Manage LXD instances description: @@ -19,198 +18,180 @@ extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: full - version_added: 6.4.0 - diff_mode: - support: full - version_added: 6.4.0 + check_mode: + support: full + version_added: 6.4.0 + diff_mode: + support: full + version_added: 6.4.0 options: - name: - description: - - Name of an instance. - type: str - required: true - project: - description: - - 'Project of an instance. - See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).' - required: false - type: str - version_added: 4.8.0 - architecture: - description: - - 'The architecture for the instance (for example V(x86_64) or V(i686)). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' - type: str - required: false - config: - description: - - 'The config for the instance (for example V({"limits.cpu": "2"})). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' - - If the instance already exists and its "config" values in metadata - obtained from the LXD API U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get) - are different, then this module tries to apply the configurations - U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put). - - The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true). - type: dict - required: false - ignore_volatile_options: - description: - - If set to V(true), options starting with C(volatile.) are ignored. As a result, - they are reapplied for each execution. - - This default behavior can be changed by setting this option to V(false). - - The default value changed from V(true) to V(false) in community.general 6.0.0. - type: bool - required: false - default: false - version_added: 3.7.0 - profiles: - description: - - Profile to be used by the instance. - type: list - elements: str - devices: - description: - - 'The devices for the instance - (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' - type: dict - required: false - ephemeral: - description: - - Whether or not the instance is ephemeral (for example V(true) or V(false)). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get). - required: false - type: bool - source: - description: - - 'The source for the instance - (for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/", - "protocol": "simplestreams", "alias": "22.04" })).' - - 'See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.' - - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).' - required: false - type: dict - state: - choices: - - started - - stopped - - restarted - - absent - - frozen - description: - - Define the state of an instance. - required: false - default: started - type: str - target: - description: - - For cluster deployments. Will attempt to create an instance on a target node. - If the instance exists elsewhere in a cluster, then it will not be replaced or moved. - The name should respond to same name of the node you see in C(lxc cluster list). - type: str - required: false - version_added: 1.0.0 - timeout: - description: - - A timeout for changing the state of the instance. - - This is also used as a timeout for waiting until IPv4 addresses - are set to the all network interfaces in the instance after - starting or restarting. - required: false - default: 30 - type: int - type: - description: - - Instance type can be either V(virtual-machine) or V(container). - required: false - default: container - choices: - - container - - virtual-machine - type: str - version_added: 4.1.0 - wait_for_ipv4_addresses: - description: - - If this is V(true), the C(lxd_container) waits until IPv4 addresses - are set to the all network interfaces in the instance after - starting or restarting. - required: false - default: false - type: bool - wait_for_container: - description: - - If set to V(true), the tasks will wait till the task reports a - success status when performing container operations. - default: false - type: bool - version_added: 4.4.0 - force_stop: - description: - - If this is V(true), the C(lxd_container) forces to stop the instance - when it stops or restarts the instance. - required: false - default: false - type: bool - url: - description: - - The unix domain socket path or the https URL for the LXD server. - required: false - default: unix:/var/lib/lxd/unix.socket - type: str - snap_url: - description: - - The unix domain socket path when LXD is installed by snap package manager. - required: false - default: unix:/var/snap/lxd/common/lxd/unix.socket - type: str - client_key: - description: - - The client certificate key file path. - - If not specified, it defaults to C(${HOME}/.config/lxc/client.key). - required: false - aliases: [ key_file ] - type: path - client_cert: - description: - - The client certificate file path. - - If not specified, it defaults to C(${HOME}/.config/lxc/client.crt). - required: false - aliases: [ cert_file ] - type: path - trust_password: - description: - - The client trusted password. - - 'You need to set this password on the LXD server before - running this module using the following command: - C(lxc config set core.trust_password ). - See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).' - - If trust_password is set, this module send a request for - authentication before sending any requests. - required: false - type: str + name: + description: + - Name of an instance. + type: str + required: true + project: + description: + - Project of an instance. + - See U(https://documentation.ubuntu.com/lxd/en/latest/projects/). + required: false + type: str + version_added: 4.8.0 + architecture: + description: + - The architecture for the instance (for example V(x86_64) or V(i686)). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get). + type: str + required: false + config: + description: + - 'The config for the instance (for example V({"limits.cpu": "2"})). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' + - If the instance already exists and its "config" values in metadata obtained from the LXD API + U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get) + are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put). + - The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true). + type: dict + required: false + ignore_volatile_options: + description: + - If set to V(true), options starting with C(volatile.) are ignored. As a result, they are reapplied for each execution. + - This default behavior can be changed by setting this option to V(false). + - The default value changed from V(true) to V(false) in community.general 6.0.0. + type: bool + required: false + default: false + version_added: 3.7.0 + profiles: + description: + - Profile to be used by the instance. + type: list + elements: str + devices: + description: + - 'The devices for the instance (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' + type: dict + required: false + ephemeral: + description: + - Whether or not the instance is ephemeral (for example V(true) or V(false)). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get). + required: false + type: bool + source: + description: + - 'The source for the instance (for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/", + "protocol": "simplestreams", "alias": "22.04" })).' + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation. + - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).' + required: false + type: dict + state: + choices: + - started + - stopped + - restarted + - absent + - frozen + description: + - Define the state of an instance. + required: false + default: started + type: str + target: + description: + - For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in a cluster, then it will + not be replaced or moved. The name should respond to same name of the node you see in C(lxc cluster list). + type: str + required: false + version_added: 1.0.0 + timeout: + description: + - A timeout for changing the state of the instance. + - This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance after starting or + restarting. + required: false + default: 30 + type: int + type: + description: + - Instance type can be either V(virtual-machine) or V(container). + required: false + default: container + choices: + - container + - virtual-machine + type: str + version_added: 4.1.0 + wait_for_ipv4_addresses: + description: + - If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance after starting + or restarting. + required: false + default: false + type: bool + wait_for_container: + description: + - If set to V(true), the tasks will wait till the task reports a success status when performing container operations. + default: false + type: bool + version_added: 4.4.0 + force_stop: + description: + - If this is V(true), the C(lxd_container) forces to stop the instance when it stops or restarts the instance. + required: false + default: false + type: bool + url: + description: + - The unix domain socket path or the https URL for the LXD server. + required: false + default: unix:/var/lib/lxd/unix.socket + type: str + snap_url: + description: + - The unix domain socket path when LXD is installed by snap package manager. + required: false + default: unix:/var/snap/lxd/common/lxd/unix.socket + type: str + client_key: + description: + - The client certificate key file path. + - If not specified, it defaults to C(${HOME}/.config/lxc/client.key). + required: false + aliases: [key_file] + type: path + client_cert: + description: + - The client certificate file path. + - If not specified, it defaults to C(${HOME}/.config/lxc/client.crt). + required: false + aliases: [cert_file] + type: path + trust_password: + description: + - The client trusted password. + - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password + ). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).' + - If trust_password is set, this module send a request for authentication before sending any requests. + required: false + type: str notes: - - Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance - with a name that already existed in the users namespace the module will - simply return as "unchanged". - - There are two ways to run commands inside a container or virtual machine, using the command - module or using the ansible lxd connection plugin bundled in Ansible >= - 2.1, the later requires python to be installed in the instance which can - be done with the command module. - - You can copy a file from the host to the instance - with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module - and the P(community.general.lxd#connection) connection plugin. - See the example below. - - You can copy a file in the created instance to the localhost - with C(command=lxc file pull instance_name/dir/filename filename). - See the first example below. - - linuxcontainers.org has phased out LXC/LXD support with March 2024 + - Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance with a name that + already existed in the users namespace the module will simply return as "unchanged". + - There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible lxd connection plugin + bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be done with the command module. + - You can copy a file from the host to the instance with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the + P(community.general.lxd#connection) connection plugin. See the example below. + - You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename). See the first + example below. + - Linuxcontainers.org has phased out LXC/LXD support with March 2024 (U(https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)). Currently only Ubuntu is still providing images. -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # An example for creating a Ubuntu container and install python - hosts: localhost connection: local @@ -279,7 +260,7 @@ source: type: image mode: pull - # Provides Ubuntu minimal images + # Provides Ubuntu minimal images server: https://cloud-images.ubuntu.com/minimal/releases/ protocol: simplestreams alias: "22.04" @@ -400,12 +381,12 @@ protocol: simplestreams type: image mode: pull - server: [...] # URL to the image server + server: ['...'] # URL to the image server alias: debian/11 timeout: 600 -''' +""" -RETURN = ''' +RETURN = r""" addresses: description: Mapping from the network device name to a list of IPv4 addresses in the instance. returned: when state is started or restarted @@ -426,7 +407,8 @@ returned: success type: list sample: ["create", "start"] -''' +""" + import copy import datetime import os diff --git a/plugins/modules/lxd_profile.py b/plugins/modules/lxd_profile.py index 13660fd91da..c46559298bf 100644 --- a/plugins/modules/lxd_profile.py +++ b/plugins/modules/lxd_profile.py @@ -9,126 +9,114 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: lxd_profile short_description: Manage LXD profiles description: - - Management of LXD profiles + - Management of LXD profiles. author: "Hiroaki Nakamura (@hnakamur)" extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - Name of a profile. - required: true - type: str - project: - description: - - 'Project of a profile. - See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).' - type: str - required: false - version_added: 4.8.0 + name: description: - description: - - Description of the profile. - type: str - config: - description: - - 'The config for the instance (e.g. {"limits.memory": "4GB"}). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).' - - If the profile already exists and its "config" value in metadata - obtained from - GET /1.0/profiles/ - U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get) - are different, then this module tries to apply the configurations - U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put). - - Not all config values are supported to apply the existing profile. - Maybe you need to delete and recreate a profile. - required: false - type: dict - devices: - description: - - 'The devices for the profile - (e.g. {"rootfs": {"path": "/dev/kvm", "type": "unix-char"}). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).' - required: false - type: dict - new_name: - description: - - A new name of a profile. - - If this parameter is specified a profile will be renamed to this name. - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post). - required: false - type: str - merge_profile: - description: - - Merge the configuration of the present profile with the new desired configuration, - instead of replacing it. - required: false - default: false - type: bool - version_added: 2.1.0 - state: - choices: - - present - - absent - description: - - Define the state of a profile. - required: false - default: present - type: str - url: - description: - - The unix domain socket path or the https URL for the LXD server. - required: false - default: unix:/var/lib/lxd/unix.socket - type: str - snap_url: - description: - - The unix domain socket path when LXD is installed by snap package manager. - required: false - default: unix:/var/snap/lxd/common/lxd/unix.socket - type: str - client_key: - description: - - The client certificate key file path. - - If not specified, it defaults to C($HOME/.config/lxc/client.key). - required: false - aliases: [ key_file ] - type: path - client_cert: - description: - - The client certificate file path. - - If not specified, it defaults to C($HOME/.config/lxc/client.crt). - required: false - aliases: [ cert_file ] - type: path - trust_password: - description: - - The client trusted password. - - You need to set this password on the LXD server before - running this module using the following command. - lxc config set core.trust_password - See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/) - - If trust_password is set, this module send a request for - authentication before sending any requests. - required: false - type: str + - Name of a profile. + required: true + type: str + project: + description: + - Project of a profile. See U(https://documentation.ubuntu.com/lxd/en/latest/projects/). + type: str + required: false + version_added: 4.8.0 + description: + description: + - Description of the profile. + type: str + config: + description: + - 'The config for the instance (for example V({"limits.memory": "4GB"})). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).' + - If the profile already exists and its C(config) value in metadata obtained from GET /1.0/profiles/ + U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get) + are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put). + - Not all config values are supported to apply the existing profile. Maybe you need to delete and recreate a profile. + required: false + type: dict + devices: + description: + - 'The devices for the profile (for example V({"rootfs": {"path": "/dev/kvm", "type": "unix-char"})). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).' + required: false + type: dict + new_name: + description: + - A new name of a profile. + - If this parameter is specified a profile will be renamed to this name. + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post). + required: false + type: str + merge_profile: + description: + - Merge the configuration of the present profile with the new desired configuration, instead of replacing it. + required: false + default: false + type: bool + version_added: 2.1.0 + state: + choices: + - present + - absent + description: + - Define the state of a profile. + required: false + default: present + type: str + url: + description: + - The unix domain socket path or the https URL for the LXD server. + required: false + default: unix:/var/lib/lxd/unix.socket + type: str + snap_url: + description: + - The unix domain socket path when LXD is installed by snap package manager. + required: false + default: unix:/var/snap/lxd/common/lxd/unix.socket + type: str + client_key: + description: + - The client certificate key file path. + - If not specified, it defaults to C($HOME/.config/lxc/client.key). + required: false + aliases: [key_file] + type: path + client_cert: + description: + - The client certificate file path. + - If not specified, it defaults to C($HOME/.config/lxc/client.crt). + required: false + aliases: [cert_file] + type: path + trust_password: + description: + - The client trusted password. + - You need to set this password on the LXD server before running this module using the following command. lxc config set core.trust_password + See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/). + - If trust_password is set, this module send a request for authentication before sending any requests. + required: false + type: str notes: - - Profiles must have a unique name. If you attempt to create a profile - with a name that already existed in the users namespace the module will + - Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace the module will simply return as "unchanged". -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # An example for creating a profile - hosts: localhost connection: local @@ -162,22 +150,22 @@ - hosts: localhost connection: local tasks: - - name: Create macvlan profile - community.general.lxd_profile: - url: https://127.0.0.1:8443 - # These client_cert and client_key values are equal to the default values. - #client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt" - #client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key" - trust_password: mypassword - name: macvlan - state: present - config: {} - description: my macvlan profile - devices: - eth0: - nictype: macvlan - parent: br0 - type: nic + - name: Create macvlan profile + community.general.lxd_profile: + url: https://127.0.0.1:8443 + # These client_cert and client_key values are equal to the default values. + #client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt" + #client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key" + trust_password: mypassword + name: macvlan + state: present + config: {} + description: my macvlan profile + devices: + eth0: + nictype: macvlan + parent: br0 + type: nic # An example for modify/merge a profile - hosts: localhost @@ -214,11 +202,11 @@ name: macvlan new_name: macvlan2 state: present -''' +""" -RETURN = ''' +RETURN = r""" old_state: - description: The old state of the profile + description: The old state of the profile. returned: success type: str sample: "absent" @@ -232,7 +220,7 @@ returned: success type: list sample: ["create"] -''' +""" import os from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/lxd_project.py b/plugins/modules/lxd_project.py index 0d321808a25..ee90b881681 100644 --- a/plugins/modules/lxd_project.py +++ b/plugins/modules/lxd_project.py @@ -7,8 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: lxd_project short_description: Manage LXD projects version_added: 4.8.0 @@ -18,98 +17,91 @@ extends_documentation_fragment: - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - Name of the project. - required: true - type: str + name: description: - description: - - Description of the project. - type: str - config: - description: - - 'The config for the project (for example V({"features.profiles": "true"})). - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).' - - If the project already exists and its "config" value in metadata - obtained from - C(GET /1.0/projects/) - U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get) - are different, then this module tries to apply the configurations - U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put). - type: dict - new_name: - description: - - A new name of a project. - - If this parameter is specified a project will be renamed to this name. - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post). - required: false - type: str - merge_project: - description: - - Merge the configuration of the present project with the new desired configuration, - instead of replacing it. If configuration is the same after merged, no change will be made. - required: false - default: false - type: bool - state: - choices: - - present - - absent - description: - - Define the state of a project. - required: false - default: present - type: str - url: - description: - - The Unix domain socket path or the https URL for the LXD server. - required: false - default: unix:/var/lib/lxd/unix.socket - type: str - snap_url: - description: - - The Unix domain socket path when LXD is installed by snap package manager. - required: false - default: unix:/var/snap/lxd/common/lxd/unix.socket - type: str - client_key: - description: - - The client certificate key file path. - - If not specified, it defaults to C($HOME/.config/lxc/client.key). - required: false - aliases: [ key_file ] - type: path - client_cert: - description: - - The client certificate file path. - - If not specified, it defaults to C($HOME/.config/lxc/client.crt). - required: false - aliases: [ cert_file ] - type: path - trust_password: - description: - - The client trusted password. - - 'You need to set this password on the LXD server before - running this module using the following command: - C(lxc config set core.trust_password ) - See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).' - - If O(trust_password) is set, this module send a request for - authentication before sending any requests. - required: false - type: str + - Name of the project. + required: true + type: str + description: + description: + - Description of the project. + type: str + config: + description: + - 'The config for the project (for example V({"features.profiles": "true"})). + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).' + - If the project already exists and its "config" value in metadata obtained from C(GET /1.0/projects/) + U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get) + are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put). + type: dict + new_name: + description: + - A new name of a project. + - If this parameter is specified a project will be renamed to this name. + - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post). + required: false + type: str + merge_project: + description: + - Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration is the same + after merged, no change will be made. + required: false + default: false + type: bool + state: + choices: + - present + - absent + description: + - Define the state of a project. + required: false + default: present + type: str + url: + description: + - The Unix domain socket path or the https URL for the LXD server. + required: false + default: unix:/var/lib/lxd/unix.socket + type: str + snap_url: + description: + - The Unix domain socket path when LXD is installed by snap package manager. + required: false + default: unix:/var/snap/lxd/common/lxd/unix.socket + type: str + client_key: + description: + - The client certificate key file path. + - If not specified, it defaults to C($HOME/.config/lxc/client.key). + required: false + aliases: [key_file] + type: path + client_cert: + description: + - The client certificate file path. + - If not specified, it defaults to C($HOME/.config/lxc/client.crt). + required: false + aliases: [cert_file] + type: path + trust_password: + description: + - The client trusted password. + - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password + ) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).' + - If O(trust_password) is set, this module send a request for authentication before sending any requests. + required: false + type: str notes: - - Projects must have a unique name. If you attempt to create a project - with a name that already existed in the users namespace the module will + - Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace the module will simply return as "unchanged". -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # An example for creating a project - hosts: localhost connection: local @@ -132,9 +124,9 @@ state: present config: {} description: my new project -''' +""" -RETURN = ''' +RETURN = r""" old_state: description: The old state of the project. returned: success @@ -184,7 +176,7 @@ type: list elements: str sample: ["create"] -''' +""" from ansible_collections.community.general.plugins.module_utils.lxd import ( LXDClient, LXDClientException, default_key_file, default_cert_file