diff --git a/plugins/connection/wsl.py b/plugins/connection/wsl.py index 886ac5c60f..06c0652312 100644 --- a/plugins/connection/wsl.py +++ b/plugins/connection/wsl.py @@ -99,7 +99,7 @@ options: section: paramiko_connection type: boolean look_for_keys: - default: True + default: true description: "Set to V(false) to disable searching for private key files in C(~/.ssh/)." env: - name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS @@ -119,7 +119,7 @@ options: vars: - name: ansible_paramiko_proxy_command record_host_keys: - default: True + default: true description: "Save the host keys to a file." env: - name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS @@ -147,7 +147,7 @@ options: use_persistent_connections: description: "Toggles the use of persistence for connections." type: boolean - default: False + default: false env: - name: ANSIBLE_USE_PERSISTENT_CONNECTIONS ini: diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py index 2ab083eab2..d6cc2b8c25 100644 --- a/plugins/doc_fragments/attributes.py +++ b/plugins/doc_fragments/attributes.py @@ -32,14 +32,14 @@ attributes: INFO_MODULE = r''' options: {} attributes: - check_mode: - support: full - details: - - This action does not modify state. - diff_mode: - support: N/A - details: - - This action does not modify state. + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. ''' CONN = r""" @@ -64,16 +64,16 @@ attributes: FACTS_MODULE = r''' options: {} attributes: - check_mode: - support: full - details: - - This action does not modify state. - diff_mode: - support: N/A - details: - - This action does not modify state. - facts: - support: full + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. + facts: + support: full ''' FILES = r""" diff --git a/plugins/doc_fragments/emc.py b/plugins/doc_fragments/emc.py index 7c62285a72..14dc7bc129 100644 --- a/plugins/doc_fragments/emc.py +++ b/plugins/doc_fragments/emc.py @@ -13,21 +13,21 @@ class ModuleDocFragment(object): # Documentation fragment for VNX (emc_vnx) EMC_VNX = r''' options: - sp_address: - description: - - Address of the SP of target/secondary storage. - type: str - required: true - sp_user: - description: - - Username for accessing SP. - type: str - default: sysadmin - sp_password: - description: - - password for accessing SP. - type: str - default: sysadmin + sp_address: + description: + - Address of the SP of target/secondary storage. + type: str + required: true + sp_user: + description: + - Username for accessing SP. + type: str + default: sysadmin + sp_password: + description: + - password for accessing SP. + type: str + default: sysadmin requirements: - An EMC VNX Storage device. - storops (0.5.10 or greater). Install using C(pip install storops). diff --git a/plugins/filter/json_patch.yml b/plugins/filter/json_patch.yml index 6b95ae4dfa..42a0309202 100644 --- a/plugins/filter/json_patch.yml +++ b/plugins/filter/json_patch.yml @@ -64,7 +64,7 @@ EXAMPLES: | ansible.builtin.debug: msg: "{{ input | community.general.json_patch('add', '/1', {'baz': 'qux'}) }}" vars: - input: ["foo": { "one": 1 }, "bar": { "two": 2 }] + input: ["foo": { "one": 1 }, "bar": { "two": 2 }] # => [{"foo": {"one": 1}}, {"baz": "qux"}, {"bar": {"two": 2}}] - name: Insert a new key into a dictionary diff --git a/plugins/filter/to_prettytable.py b/plugins/filter/to_prettytable.py index ed03ef7517..249c830230 100644 --- a/plugins/filter/to_prettytable.py +++ b/plugins/filter/to_prettytable.py @@ -5,7 +5,7 @@ from __future__ import (absolute_import, division, print_function) -DOCUMENTATION = ''' +DOCUMENTATION = r""" name: to_prettytable short_description: Format a list of dictionaries as an ASCII table version_added: "10.7.0" @@ -37,9 +37,9 @@ options: For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left and the C(id) column to the right. type: dictionary -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" --- - name: Set a list of users ansible.builtin.set_fact: @@ -104,13 +104,13 @@ EXAMPLES = ''' column_alignments={'name': 'center', 'age': 'right', 'role': 'left'} ) }} -''' +""" -RETURN = ''' +RETURN = r""" _value: description: The formatted ASCII table. type: string -''' +""" try: import prettytable diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index e622a4d34d..3526093b8c 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -5,127 +5,127 @@ # SPDX-License-Identifier: GPL-3.0-or-later from __future__ import annotations -DOCUMENTATION = ''' - author: Orion Poplawski (@opoplawski) - name: cobbler - short_description: Cobbler inventory source - version_added: 1.0.0 +DOCUMENTATION = r""" +author: Orion Poplawski (@opoplawski) +name: cobbler +short_description: Cobbler inventory source +version_added: 1.0.0 +description: + - Get inventory hosts from the cobbler service. + - "Uses a configuration file as an inventory source, it must end in C(.cobbler.yml) or C(.cobbler.yaml) and have a C(plugin: cobbler) entry." + - Adds the primary IP addresses to C(cobbler_ipv4_address) and C(cobbler_ipv6_address) host variables if defined in Cobbler. The primary IP address is + defined as the management interface if defined, or the interface who's DNS name matches the hostname of the system, or else the first interface found. +extends_documentation_fragment: + - inventory_cache +options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as its own. + type: string + required: true + choices: ['cobbler', 'community.general.cobbler'] + url: + description: URL to cobbler. + type: string + default: 'http://cobbler/cobbler_api' + env: + - name: COBBLER_SERVER + user: + description: Cobbler authentication user. + type: string + required: false + env: + - name: COBBLER_USER + password: + description: Cobbler authentication password. + type: string + required: false + env: + - name: COBBLER_PASSWORD + cache_fallback: + description: Fallback to cached results if connection to cobbler fails. + type: boolean + default: false + connection_timeout: + description: Timeout to connect to cobbler server. + type: int + required: false + version_added: 10.7.0 + exclude_mgmt_classes: + description: Management classes to exclude from inventory. + type: list + default: [] + elements: str + version_added: 7.4.0 + exclude_profiles: description: - - Get inventory hosts from the cobbler service. - - "Uses a configuration file as an inventory source, it must end in C(.cobbler.yml) or C(.cobbler.yaml) and have a C(plugin: cobbler) entry." - - Adds the primary IP addresses to C(cobbler_ipv4_address) and C(cobbler_ipv6_address) host variables if defined in Cobbler. The primary IP address is - defined as the management interface if defined, or the interface who's DNS name matches the hostname of the system, or else the first interface found. - extends_documentation_fragment: - - inventory_cache - options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as its own. - type: string - required: true - choices: [ 'cobbler', 'community.general.cobbler' ] - url: - description: URL to cobbler. - type: string - default: 'http://cobbler/cobbler_api' - env: - - name: COBBLER_SERVER - user: - description: Cobbler authentication user. - type: string - required: false - env: - - name: COBBLER_USER - password: - description: Cobbler authentication password. - type: string - required: false - env: - - name: COBBLER_PASSWORD - cache_fallback: - description: Fallback to cached results if connection to cobbler fails. - type: boolean - default: false - connection_timeout: - description: Timeout to connect to cobbler server. - type: int - required: false - version_added: 10.7.0 - exclude_mgmt_classes: - description: Management classes to exclude from inventory. - type: list - default: [] - elements: str - version_added: 7.4.0 - exclude_profiles: - description: - - Profiles to exclude from inventory. - - Ignored if O(include_profiles) is specified. - type: list - default: [] - elements: str - include_mgmt_classes: - description: Management classes to include from inventory. - type: list - default: [] - elements: str - version_added: 7.4.0 - include_profiles: - description: - - Profiles to include from inventory. - - If specified, all other profiles will be excluded. - - O(exclude_profiles) is ignored if O(include_profiles) is specified. - type: list - default: [] - elements: str - version_added: 4.4.0 - inventory_hostname: - description: - - What to use for the ansible inventory hostname. - - By default the networking hostname is used if defined, otherwise the DNS name of the management or first non-static interface. - - If set to V(system), the cobbler system name is used. - type: str - choices: [ 'hostname', 'system' ] - default: hostname - version_added: 7.1.0 - group_by: - description: Keys to group hosts by. - type: list - elements: string - default: [ 'mgmt_classes', 'owners', 'status' ] - group: - description: Group to place all hosts into. - default: cobbler - group_prefix: - description: Prefix to apply to cobbler groups. - default: cobbler_ - want_facts: - description: Toggle, if V(true) the plugin will retrieve all host facts from the server. - type: boolean - default: true - want_ip_addresses: - description: - - Toggle, if V(true) the plugin will add a C(cobbler_ipv4_addresses) and C(cobbler_ipv6_addresses) dictionary to the defined O(group) mapping - interface DNS names to IP addresses. - type: boolean - default: true - version_added: 7.1.0 - facts_level: - description: - - "Set to V(normal) to gather only system-level variables." - - "Set to V(as_rendered) to gather all variables as rolled up by Cobbler." - type: string - choices: [ 'normal', 'as_rendered' ] - default: normal - version_added: 10.7.0 -''' + - Profiles to exclude from inventory. + - Ignored if O(include_profiles) is specified. + type: list + default: [] + elements: str + include_mgmt_classes: + description: Management classes to include from inventory. + type: list + default: [] + elements: str + version_added: 7.4.0 + include_profiles: + description: + - Profiles to include from inventory. + - If specified, all other profiles will be excluded. + - O(exclude_profiles) is ignored if O(include_profiles) is specified. + type: list + default: [] + elements: str + version_added: 4.4.0 + inventory_hostname: + description: + - What to use for the ansible inventory hostname. + - By default the networking hostname is used if defined, otherwise the DNS name of the management or first non-static interface. + - If set to V(system), the cobbler system name is used. + type: str + choices: ['hostname', 'system'] + default: hostname + version_added: 7.1.0 + group_by: + description: Keys to group hosts by. + type: list + elements: string + default: ['mgmt_classes', 'owners', 'status'] + group: + description: Group to place all hosts into. + default: cobbler + group_prefix: + description: Prefix to apply to cobbler groups. + default: cobbler_ + want_facts: + description: Toggle, if V(true) the plugin will retrieve all host facts from the server. + type: boolean + default: true + want_ip_addresses: + description: + - Toggle, if V(true) the plugin will add a C(cobbler_ipv4_addresses) and C(cobbler_ipv6_addresses) dictionary to the defined O(group) mapping + interface DNS names to IP addresses. + type: boolean + default: true + version_added: 7.1.0 + facts_level: + description: + - "Set to V(normal) to gather only system-level variables." + - "Set to V(as_rendered) to gather all variables as rolled up by Cobbler." + type: string + choices: ['normal', 'as_rendered'] + default: normal + version_added: 10.7.0 +""" -EXAMPLES = ''' +EXAMPLES = r""" # my.cobbler.yml plugin: community.general.cobbler url: http://cobbler/cobbler_api user: ansible-tester password: secure -''' +""" import socket diff --git a/plugins/inventory/gitlab_runners.py b/plugins/inventory/gitlab_runners.py index 961f20444b..192be319a7 100644 --- a/plugins/inventory/gitlab_runners.py +++ b/plugins/inventory/gitlab_runners.py @@ -7,56 +7,56 @@ from __future__ import annotations -DOCUMENTATION = ''' - name: gitlab_runners - author: - - Stefan Heitmüller (@morph027) - short_description: Ansible dynamic inventory plugin for GitLab runners. - requirements: - - python-gitlab > 1.8.0 - extends_documentation_fragment: - - constructed - description: - - Reads inventories from the GitLab API. - - Uses a YAML configuration file gitlab_runners.[yml|yaml]. - options: - plugin: - description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own. - type: str - required: true - choices: - - gitlab_runners - - community.general.gitlab_runners - server_url: - description: The URL of the GitLab server, with protocol (i.e. http or https). - env: - - name: GITLAB_SERVER_URL - version_added: 1.0.0 - type: str - required: true - api_token: - description: GitLab token for logging in. - env: - - name: GITLAB_API_TOKEN - version_added: 1.0.0 - type: str - aliases: - - private_token - - access_token - filter: - description: filter runners from GitLab API - env: - - name: GITLAB_FILTER - version_added: 1.0.0 - type: str - choices: ['active', 'paused', 'online', 'specific', 'shared'] - verbose_output: - description: Toggle to (not) include all available nodes metadata - type: bool - default: true -''' +DOCUMENTATION = r""" +name: gitlab_runners +author: + - Stefan Heitmüller (@morph027) +short_description: Ansible dynamic inventory plugin for GitLab runners. +requirements: + - python-gitlab > 1.8.0 +extends_documentation_fragment: + - constructed +description: + - Reads inventories from the GitLab API. + - Uses a YAML configuration file gitlab_runners.[yml|yaml]. +options: + plugin: + description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own. + type: str + required: true + choices: + - gitlab_runners + - community.general.gitlab_runners + server_url: + description: The URL of the GitLab server, with protocol (i.e. http or https). + env: + - name: GITLAB_SERVER_URL + version_added: 1.0.0 + type: str + required: true + api_token: + description: GitLab token for logging in. + env: + - name: GITLAB_API_TOKEN + version_added: 1.0.0 + type: str + aliases: + - private_token + - access_token + filter: + description: filter runners from GitLab API + env: + - name: GITLAB_FILTER + version_added: 1.0.0 + type: str + choices: ['active', 'paused', 'online', 'specific', 'shared'] + verbose_output: + description: Toggle to (not) include all available nodes metadata + type: bool + default: true +""" -EXAMPLES = ''' +EXAMPLES = r""" --- # gitlab_runners.yml plugin: community.general.gitlab_runners @@ -79,7 +79,7 @@ keyed_groups: # hint: labels containing special characters will be converted to safe names - key: 'tag_list' prefix: tag -''' +""" from ansible.errors import AnsibleError, AnsibleParserError from ansible.plugins.inventory import BaseInventoryPlugin, Constructable diff --git a/plugins/inventory/icinga2.py b/plugins/inventory/icinga2.py index 7ee87df065..feb2d10d8a 100644 --- a/plugins/inventory/icinga2.py +++ b/plugins/inventory/icinga2.py @@ -6,71 +6,71 @@ from __future__ import annotations -DOCUMENTATION = ''' - name: icinga2 - short_description: Icinga2 inventory source - version_added: 3.7.0 - author: - - Cliff Hults (@BongoEADGC6) +DOCUMENTATION = r""" +name: icinga2 +short_description: Icinga2 inventory source +version_added: 3.7.0 +author: + - Cliff Hults (@BongoEADGC6) +description: + - Get inventory hosts from the Icinga2 API. + - "Uses a configuration file as an inventory source, it must end in + C(.icinga2.yml) or C(.icinga2.yaml)." +extends_documentation_fragment: + - constructed +options: + strict: + version_added: 4.4.0 + compose: + version_added: 4.4.0 + groups: + version_added: 4.4.0 + keyed_groups: + version_added: 4.4.0 + plugin: + description: Name of the plugin. + required: true + type: string + choices: ['community.general.icinga2'] + url: + description: Root URL of Icinga2 API. + type: string + required: true + user: + description: Username to query the API. + type: string + required: true + password: + description: Password to query the API. + type: string + required: true + host_filter: description: - - Get inventory hosts from the Icinga2 API. - - "Uses a configuration file as an inventory source, it must end in - C(.icinga2.yml) or C(.icinga2.yaml)." - extends_documentation_fragment: - - constructed - options: - strict: - version_added: 4.4.0 - compose: - version_added: 4.4.0 - groups: - version_added: 4.4.0 - keyed_groups: - version_added: 4.4.0 - plugin: - description: Name of the plugin. - required: true - type: string - choices: ['community.general.icinga2'] - url: - description: Root URL of Icinga2 API. - type: string - required: true - user: - description: Username to query the API. - type: string - required: true - password: - description: Password to query the API. - type: string - required: true - host_filter: - description: - - An Icinga2 API valid host filter. Leave blank for no filtering - type: string - required: false - validate_certs: - description: Enables or disables SSL certificate verification. - type: boolean - default: true - inventory_attr: - description: - - Allows the override of the inventory name based on different attributes. - - This allows for changing the way limits are used. - - The current default, V(address), is sometimes not unique or present. We recommend to use V(name) instead. - type: string - default: address - choices: ['name', 'display_name', 'address'] - version_added: 4.2.0 - group_by_hostgroups: - description: - - Uses Icinga2 hostgroups as groups. - type: boolean - default: true - version_added: 8.4.0 -''' + - An Icinga2 API valid host filter. Leave blank for no filtering + type: string + required: false + validate_certs: + description: Enables or disables SSL certificate verification. + type: boolean + default: true + inventory_attr: + description: + - Allows the override of the inventory name based on different attributes. + - This allows for changing the way limits are used. + - The current default, V(address), is sometimes not unique or present. We recommend to use V(name) instead. + type: string + default: address + choices: ['name', 'display_name', 'address'] + version_added: 4.2.0 + group_by_hostgroups: + description: + - Uses Icinga2 hostgroups as groups. + type: boolean + default: true + version_added: 8.4.0 +""" -EXAMPLES = r''' +EXAMPLES = r""" # my.icinga2.yml plugin: community.general.icinga2 url: http://localhost:5665 @@ -93,7 +93,7 @@ compose: # set 'ansible_user' and 'ansible_port' from icinga2 host vars ansible_user: icinga2_attributes.vars.ansible_user ansible_port: icinga2_attributes.vars.ansible_port | default(22) -''' +""" import json diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py index 1303cdcff9..8e296b571a 100644 --- a/plugins/inventory/iocage.py +++ b/plugins/inventory/iocage.py @@ -6,7 +6,7 @@ from __future__ import annotations -DOCUMENTATION = r''' +DOCUMENTATION = r""" name: iocage short_description: iocage inventory source version_added: 10.2.0 @@ -110,9 +110,9 @@ notes: expects to find the O(hooks_results) items in the path C(/iocage/iocage/jails//root). If you mount the C(poolname) to a different path the easiest remedy is to create a symlink. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" --- # file name must end with iocage.yaml or iocage.yml plugin: community.general.iocage @@ -182,7 +182,7 @@ compose: ansible_host: iocage_hooks.0 groups: test: inventory_hostname.startswith('test') -''' +""" import re import os diff --git a/plugins/inventory/linode.py b/plugins/inventory/linode.py index 594cf30eba..3e7ddc5a82 100644 --- a/plugins/inventory/linode.py +++ b/plugins/inventory/linode.py @@ -5,79 +5,79 @@ from __future__ import annotations -DOCUMENTATION = r''' - name: linode - author: - - Luke Murphy (@decentral1se) - short_description: Ansible dynamic inventory plugin for Linode. - requirements: - - linode_api4 >= 2.0.0 - description: - - Reads inventories from the Linode API v4. - - Uses a YAML configuration file that ends with linode.(yml|yaml). - - Linode labels are used by default as the hostnames. - - The default inventory groups are built from groups (deprecated by - Linode) and not tags. - extends_documentation_fragment: - - constructed - - inventory_cache - options: - cache: - version_added: 4.5.0 - cache_plugin: - version_added: 4.5.0 - cache_timeout: - version_added: 4.5.0 - cache_connection: - version_added: 4.5.0 - cache_prefix: - version_added: 4.5.0 - plugin: - description: Marks this as an instance of the 'linode' plugin. - type: string - required: true - choices: ['linode', 'community.general.linode'] - ip_style: - description: Populate hostvars with all information available from the Linode APIv4. - type: string - default: plain - choices: - - plain - - api - version_added: 3.6.0 - access_token: - description: The Linode account personal access token. - type: string - required: true - env: - - name: LINODE_ACCESS_TOKEN - regions: - description: Populate inventory with instances in this region. - default: [] - type: list - elements: string - tags: - description: Populate inventory only with instances which have at least one of the tags listed here. - default: [] - type: list - elements: string - version_added: 2.0.0 - types: - description: Populate inventory with instances with this type. - default: [] - type: list - elements: string - strict: - version_added: 2.0.0 - compose: - version_added: 2.0.0 - groups: - version_added: 2.0.0 - keyed_groups: - version_added: 2.0.0 -''' +DOCUMENTATION = r""" +name: linode +author: + - Luke Murphy (@decentral1se) +short_description: Ansible dynamic inventory plugin for Linode. +requirements: + - linode_api4 >= 2.0.0 +description: + - Reads inventories from the Linode API v4. + - Uses a YAML configuration file that ends with linode.(yml|yaml). + - Linode labels are used by default as the hostnames. + - The default inventory groups are built from groups (deprecated by + Linode) and not tags. +extends_documentation_fragment: + - constructed + - inventory_cache +options: + cache: + version_added: 4.5.0 + cache_plugin: + version_added: 4.5.0 + cache_timeout: + version_added: 4.5.0 + cache_connection: + version_added: 4.5.0 + cache_prefix: + version_added: 4.5.0 + plugin: + description: Marks this as an instance of the 'linode' plugin. + type: string + required: true + choices: ['linode', 'community.general.linode'] + ip_style: + description: Populate hostvars with all information available from the Linode APIv4. + type: string + default: plain + choices: + - plain + - api + version_added: 3.6.0 + access_token: + description: The Linode account personal access token. + type: string + required: true + env: + - name: LINODE_ACCESS_TOKEN + regions: + description: Populate inventory with instances in this region. + default: [] + type: list + elements: string + tags: + description: Populate inventory only with instances which have at least one of the tags listed here. + default: [] + type: list + elements: string + version_added: 2.0.0 + types: + description: Populate inventory with instances with this type. + default: [] + type: list + elements: string + strict: + version_added: 2.0.0 + compose: + version_added: 2.0.0 + groups: + version_added: 2.0.0 + keyed_groups: + version_added: 2.0.0 +""" -EXAMPLES = r''' +EXAMPLES = r""" --- # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. plugin: community.general.linode @@ -124,7 +124,7 @@ access_token: foobar ip_style: api compose: ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first" -''' +""" from ansible.errors import AnsibleError from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py index 480af8388c..b1492d663c 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -5,108 +5,108 @@ from __future__ import annotations -DOCUMENTATION = r''' - name: lxd - short_description: Returns Ansible inventory from lxd host +DOCUMENTATION = r""" +name: lxd +short_description: Returns Ansible inventory from lxd host +description: + - Get inventory from the lxd. + - Uses a YAML configuration file that ends with 'lxd.(yml|yaml)'. +version_added: "3.0.0" +author: "Frank Dornheim (@conloos)" +requirements: + - ipaddress + - lxd >= 4.0 +options: + plugin: + description: Token that ensures this is a source file for the 'lxd' plugin. + type: string + required: true + choices: ['community.general.lxd'] + url: description: - - Get inventory from the lxd. - - Uses a YAML configuration file that ends with 'lxd.(yml|yaml)'. - version_added: "3.0.0" - author: "Frank Dornheim (@conloos)" - requirements: - - ipaddress - - lxd >= 4.0 - options: - plugin: - description: Token that ensures this is a source file for the 'lxd' plugin. - type: string - required: true - choices: [ 'community.general.lxd' ] - url: - description: - - The unix domain socket path or the https URL for the lxd server. - - Sockets in filesystem have to start with C(unix:). - - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). - type: string - default: unix:/var/snap/lxd/common/lxd/unix.socket - client_key: - description: - - The client certificate key file path. - aliases: [ key_file ] - default: $HOME/.config/lxc/client.key - type: path - client_cert: - description: - - The client certificate file path. - aliases: [ cert_file ] - default: $HOME/.config/lxc/client.crt - type: path - server_cert: - description: - - The server certificate file path. - type: path - version_added: 8.0.0 - server_check_hostname: - description: - - This option controls if the server's hostname is checked as part of the HTTPS connection verification. - This can be useful to disable, if for example, the server certificate provided (see O(server_cert) option) - does not cover a name matching the one used to communicate with the server. Such mismatch is common as LXD - generates self-signed server certificates by default. - type: bool - default: true - version_added: 8.0.0 - 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://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). - - If O(trust_password) is set, this module send a request for authentication before sending any requests. - type: str - state: - description: Filter the instance according to the current status. - type: str - default: none - choices: [ 'STOPPED', 'STARTING', 'RUNNING', 'none' ] - project: - description: Filter the instance according to the given project. - type: str - default: default - version_added: 6.2.0 - type_filter: - description: - - Filter the instances by type V(virtual-machine), V(container) or V(both). - - The first version of the inventory only supported containers. - type: str - default: container - choices: [ 'virtual-machine', 'container', 'both' ] - version_added: 4.2.0 - prefered_instance_network_interface: - description: - - If an instance has multiple network interfaces, select which one is the preferred as pattern. - - Combined with the first number that can be found e.g. 'eth' + 0. - - The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface) - in community.general 3.8.0. The old name still works as an alias. - type: str - default: eth - aliases: - - prefered_container_network_interface - prefered_instance_network_family: - description: - - If an instance has multiple network interfaces, which one is the preferred by family. - - Specify V(inet) for IPv4 and V(inet6) for IPv6. - type: str - default: inet - choices: [ 'inet', 'inet6' ] - groupby: - description: - - Create groups by the following keywords C(location), C(network_range), C(os), C(pattern), C(profile), C(release), C(type), C(vlanid). - - See example for syntax. - type: dict -''' + - The unix domain socket path or the https URL for the lxd server. + - Sockets in filesystem have to start with C(unix:). + - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). + type: string + default: unix:/var/snap/lxd/common/lxd/unix.socket + client_key: + description: + - The client certificate key file path. + aliases: [key_file] + default: $HOME/.config/lxc/client.key + type: path + client_cert: + description: + - The client certificate file path. + aliases: [cert_file] + default: $HOME/.config/lxc/client.crt + type: path + server_cert: + description: + - The server certificate file path. + type: path + version_added: 8.0.0 + server_check_hostname: + description: + - This option controls if the server's hostname is checked as part of the HTTPS connection verification. + This can be useful to disable, if for example, the server certificate provided (see O(server_cert) option) + does not cover a name matching the one used to communicate with the server. Such mismatch is common as LXD + generates self-signed server certificates by default. + type: bool + default: true + version_added: 8.0.0 + 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://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). + - If O(trust_password) is set, this module send a request for authentication before sending any requests. + type: str + state: + description: Filter the instance according to the current status. + type: str + default: none + choices: ['STOPPED', 'STARTING', 'RUNNING', 'none'] + project: + description: Filter the instance according to the given project. + type: str + default: default + version_added: 6.2.0 + type_filter: + description: + - Filter the instances by type V(virtual-machine), V(container) or V(both). + - The first version of the inventory only supported containers. + type: str + default: container + choices: ['virtual-machine', 'container', 'both'] + version_added: 4.2.0 + prefered_instance_network_interface: + description: + - If an instance has multiple network interfaces, select which one is the preferred as pattern. + - Combined with the first number that can be found e.g. 'eth' + 0. + - The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface) + in community.general 3.8.0. The old name still works as an alias. + type: str + default: eth + aliases: + - prefered_container_network_interface + prefered_instance_network_family: + description: + - If an instance has multiple network interfaces, which one is the preferred by family. + - Specify V(inet) for IPv4 and V(inet6) for IPv6. + type: str + default: inet + choices: ['inet', 'inet6'] + groupby: + description: + - Create groups by the following keywords C(location), C(network_range), C(os), C(pattern), C(profile), C(release), C(type), C(vlanid). + - See example for syntax. + type: dict +""" -EXAMPLES = ''' +EXAMPLES = r""" --- # simple lxd.yml plugin: community.general.lxd @@ -165,7 +165,7 @@ groupby: projectInternals: type: project attribute: internals -''' +""" import json import re diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py index 3bd6e9fda3..f8a792964c 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -5,102 +5,102 @@ from __future__ import annotations -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: nmap - short_description: Uses nmap to find hosts to target +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: nmap +short_description: Uses nmap to find hosts to target +description: + - Uses a YAML configuration file with a valid YAML extension. +extends_documentation_fragment: + - constructed + - inventory_cache +requirements: + - nmap CLI installed +options: + plugin: + description: token that ensures this is a source file for the 'nmap' plugin. + type: string + required: true + choices: ['nmap', 'community.general.nmap'] + sudo: + description: Set to V(true) to execute a C(sudo nmap) plugin scan. + version_added: 4.8.0 + default: false + type: boolean + address: + description: Network IP or range of IPs to scan, you can use a simple range (10.2.2.15-25) or CIDR notation. + type: string + required: true + env: + - name: ANSIBLE_NMAP_ADDRESS + version_added: 6.6.0 + exclude: description: - - Uses a YAML configuration file with a valid YAML extension. - extends_documentation_fragment: - - constructed - - inventory_cache - requirements: - - nmap CLI installed - options: - plugin: - description: token that ensures this is a source file for the 'nmap' plugin. - type: string - required: true - choices: ['nmap', 'community.general.nmap'] - sudo: - description: Set to V(true) to execute a C(sudo nmap) plugin scan. - version_added: 4.8.0 - default: false - type: boolean - address: - description: Network IP or range of IPs to scan, you can use a simple range (10.2.2.15-25) or CIDR notation. - type: string - required: true - env: - - name: ANSIBLE_NMAP_ADDRESS - version_added: 6.6.0 - exclude: - description: - - List of addresses to exclude. - - For example V(10.2.2.15-25) or V(10.2.2.15,10.2.2.16). - type: list - elements: string - env: - - name: ANSIBLE_NMAP_EXCLUDE - version_added: 6.6.0 - port: - description: - - Only scan specific port or port range (C(-p)). - - For example, you could pass V(22) for a single port, V(1-65535) for a range of ports, - or V(U:53,137,T:21-25,139,8080,S:9) to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all. - type: string - version_added: 6.5.0 - ports: - description: Enable/disable scanning ports. - type: boolean - default: true - ipv4: - description: use IPv4 type addresses - type: boolean - default: true - ipv6: - description: use IPv6 type addresses - type: boolean - default: true - udp_scan: - description: - - Scan via UDP. - - Depending on your system you might need O(sudo=true) for this to work. - type: boolean - default: false - version_added: 6.1.0 - icmp_timestamp: - description: - - Scan via ICMP Timestamp (C(-PP)). - - Depending on your system you might need O(sudo=true) for this to work. - type: boolean - default: false - version_added: 6.1.0 - open: - description: Only scan for open (or possibly open) ports. - type: boolean - default: false - version_added: 6.5.0 - dns_resolve: - description: Whether to always (V(true)) or never (V(false)) do DNS resolution. - type: boolean - default: false - version_added: 6.1.0 - dns_servers: - description: Specify which DNS servers to use for name resolution. - type: list - elements: string - version_added: 10.5.0 - use_arp_ping: - description: Whether to always (V(true)) use the quick ARP ping or (V(false)) a slower but more reliable method. - type: boolean - default: true - version_added: 7.4.0 - notes: - - At least one of O(ipv4) or O(ipv6) is required to be V(true); both can be V(true), but they cannot both be V(false). - - 'TODO: add OS fingerprinting' -''' -EXAMPLES = ''' + - List of addresses to exclude. + - For example V(10.2.2.15-25) or V(10.2.2.15,10.2.2.16). + type: list + elements: string + env: + - name: ANSIBLE_NMAP_EXCLUDE + version_added: 6.6.0 + port: + description: + - Only scan specific port or port range (C(-p)). + - For example, you could pass V(22) for a single port, V(1-65535) for a range of ports, + or V(U:53,137,T:21-25,139,8080,S:9) to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all. + type: string + version_added: 6.5.0 + ports: + description: Enable/disable scanning ports. + type: boolean + default: true + ipv4: + description: use IPv4 type addresses + type: boolean + default: true + ipv6: + description: use IPv6 type addresses + type: boolean + default: true + udp_scan: + description: + - Scan via UDP. + - Depending on your system you might need O(sudo=true) for this to work. + type: boolean + default: false + version_added: 6.1.0 + icmp_timestamp: + description: + - Scan via ICMP Timestamp (C(-PP)). + - Depending on your system you might need O(sudo=true) for this to work. + type: boolean + default: false + version_added: 6.1.0 + open: + description: Only scan for open (or possibly open) ports. + type: boolean + default: false + version_added: 6.5.0 + dns_resolve: + description: Whether to always (V(true)) or never (V(false)) do DNS resolution. + type: boolean + default: false + version_added: 6.1.0 + dns_servers: + description: Specify which DNS servers to use for name resolution. + type: list + elements: string + version_added: 10.5.0 + use_arp_ping: + description: Whether to always (V(true)) use the quick ARP ping or (V(false)) a slower but more reliable method. + type: boolean + default: true + version_added: 7.4.0 +notes: + - At least one of O(ipv4) or O(ipv6) is required to be V(true); both can be V(true), but they cannot both be V(false). + - 'TODO: add OS fingerprinting' +""" +EXAMPLES = r""" --- # inventory.config file in YAML format plugin: community.general.nmap @@ -122,7 +122,7 @@ exclude: 192.168.0.1, web.example.com port: 22, 443 groups: web_servers: "ports | selectattr('port', 'equalto', '443')" -''' +""" import os import re diff --git a/plugins/inventory/online.py b/plugins/inventory/online.py index 9e29c91e54..e88deb4012 100644 --- a/plugins/inventory/online.py +++ b/plugins/inventory/online.py @@ -5,49 +5,49 @@ from __future__ import annotations -DOCUMENTATION = r''' - name: online - author: - - Remy Leone (@remyleone) - short_description: Scaleway (previously Online SAS or Online.net) inventory source - description: - - Get inventory hosts from Scaleway (previously Online SAS or Online.net). - options: - plugin: - description: token that ensures this is a source file for the 'online' plugin. - type: string - required: true - choices: ['online', 'community.general.online'] - oauth_token: - required: true - description: Online OAuth token. - type: string - env: - # in order of precedence - - name: ONLINE_TOKEN - - name: ONLINE_API_KEY - - name: ONLINE_OAUTH_TOKEN - hostnames: - description: List of preference about what to use as an hostname. - type: list - elements: string - default: - - public_ipv4 - choices: - - public_ipv4 - - private_ipv4 - - hostname - groups: - description: List of groups. - type: list - elements: string - choices: - - location - - offer - - rpn -''' +DOCUMENTATION = r""" +name: online +author: + - Remy Leone (@remyleone) +short_description: Scaleway (previously Online SAS or Online.net) inventory source +description: + - Get inventory hosts from Scaleway (previously Online SAS or Online.net). +options: + plugin: + description: token that ensures this is a source file for the 'online' plugin. + type: string + required: true + choices: ['online', 'community.general.online'] + oauth_token: + required: true + description: Online OAuth token. + type: string + env: + # in order of precedence + - name: ONLINE_TOKEN + - name: ONLINE_API_KEY + - name: ONLINE_OAUTH_TOKEN + hostnames: + description: List of preference about what to use as an hostname. + type: list + elements: string + default: + - public_ipv4 + choices: + - public_ipv4 + - private_ipv4 + - hostname + groups: + description: List of groups. + type: list + elements: string + choices: + - location + - offer + - rpn +""" -EXAMPLES = r''' +EXAMPLES = r""" # online_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i online_inventory.yml @@ -58,7 +58,7 @@ groups: - location - offer - rpn -''' +""" import json from sys import version as python_version diff --git a/plugins/inventory/opennebula.py b/plugins/inventory/opennebula.py index ed26880d07..7bf6ccf224 100644 --- a/plugins/inventory/opennebula.py +++ b/plugins/inventory/opennebula.py @@ -6,77 +6,77 @@ from __future__ import annotations -DOCUMENTATION = r''' - name: opennebula - author: - - Kristian Feldsam (@feldsam) - short_description: OpenNebula inventory source - version_added: "3.8.0" - extends_documentation_fragment: - - constructed +DOCUMENTATION = r""" +name: opennebula +author: + - Kristian Feldsam (@feldsam) +short_description: OpenNebula inventory source +version_added: "3.8.0" +extends_documentation_fragment: + - constructed +description: + - Get inventory hosts from OpenNebula cloud. + - Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml) + to set parameter values. + - Uses O(api_authfile), C(~/.one/one_auth), or E(ONE_AUTH) pointing to a OpenNebula credentials file. +options: + plugin: + description: Token that ensures this is a source file for the 'opennebula' plugin. + type: string + required: true + choices: [community.general.opennebula] + api_url: description: - - Get inventory hosts from OpenNebula cloud. - - Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml) - to set parameter values. - - Uses O(api_authfile), C(~/.one/one_auth), or E(ONE_AUTH) pointing to a OpenNebula credentials file. - options: - plugin: - description: Token that ensures this is a source file for the 'opennebula' plugin. - type: string - required: true - choices: [ community.general.opennebula ] - api_url: - description: - - URL of the OpenNebula RPC server. - - It is recommended to use HTTPS so that the username/password are not - transferred over the network unencrypted. - - If not set then the value of the E(ONE_URL) environment variable is used. - env: - - name: ONE_URL - required: true - type: string - api_username: - description: - - Name of the user to login into the OpenNebula RPC server. If not set - then the value of the E(ONE_USERNAME) environment variable is used. - env: - - name: ONE_USERNAME - type: string - api_password: - description: - - Password or a token of the user to login into OpenNebula RPC server. - - If not set, the value of the E(ONE_PASSWORD) environment variable is used. - env: - - name: ONE_PASSWORD - required: false - type: string - api_authfile: - description: - - If both O(api_username) or O(api_password) are not set, then it will try - authenticate with ONE auth file. Default path is C(~/.one/one_auth). - - Set environment variable E(ONE_AUTH) to override this path. - env: - - name: ONE_AUTH - required: false - type: string - hostname: - description: Field to match the hostname. Note V(v4_first_ip) corresponds to the first IPv4 found on VM. - type: string - default: v4_first_ip - choices: - - v4_first_ip - - v6_first_ip - - name - filter_by_label: - description: Only return servers filtered by this label. - type: string - group_by_labels: - description: Create host groups by vm labels - type: bool - default: true -''' + - URL of the OpenNebula RPC server. + - It is recommended to use HTTPS so that the username/password are not + transferred over the network unencrypted. + - If not set then the value of the E(ONE_URL) environment variable is used. + env: + - name: ONE_URL + required: true + type: string + api_username: + description: + - Name of the user to login into the OpenNebula RPC server. If not set + then the value of the E(ONE_USERNAME) environment variable is used. + env: + - name: ONE_USERNAME + type: string + api_password: + description: + - Password or a token of the user to login into OpenNebula RPC server. + - If not set, the value of the E(ONE_PASSWORD) environment variable is used. + env: + - name: ONE_PASSWORD + required: false + type: string + api_authfile: + description: + - If both O(api_username) or O(api_password) are not set, then it will try + authenticate with ONE auth file. Default path is C(~/.one/one_auth). + - Set environment variable E(ONE_AUTH) to override this path. + env: + - name: ONE_AUTH + required: false + type: string + hostname: + description: Field to match the hostname. Note V(v4_first_ip) corresponds to the first IPv4 found on VM. + type: string + default: v4_first_ip + choices: + - v4_first_ip + - v6_first_ip + - name + filter_by_label: + description: Only return servers filtered by this label. + type: string + group_by_labels: + description: Create host groups by vm labels + type: bool + default: true +""" -EXAMPLES = r''' +EXAMPLES = r""" # inventory_opennebula.yml file in YAML format # Example command line: ansible-inventory --list -i inventory_opennebula.yml @@ -84,7 +84,7 @@ EXAMPLES = r''' plugin: community.general.opennebula api_url: https://opennebula:2633/RPC2 filter_by_label: Cache -''' +""" try: import pyone diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index d815890df4..488bbbe084 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -6,73 +6,73 @@ from __future__ import annotations -DOCUMENTATION = r''' - name: scaleway - author: - - Remy Leone (@remyleone) - short_description: Scaleway inventory source +DOCUMENTATION = r""" +name: scaleway +author: + - Remy Leone (@remyleone) +short_description: Scaleway inventory source +description: + - Get inventory hosts from Scaleway. +requirements: + - PyYAML +options: + plugin: + description: Token that ensures this is a source file for the 'scaleway' plugin. + required: true + type: string + choices: ['scaleway', 'community.general.scaleway'] + regions: + description: Filter results on a specific Scaleway region. + type: list + elements: string + default: + - ams1 + - par1 + - par2 + - waw1 + tags: + description: Filter results on a specific tag. + type: list + elements: string + scw_profile: description: - - Get inventory hosts from Scaleway. - requirements: - - PyYAML - options: - plugin: - description: Token that ensures this is a source file for the 'scaleway' plugin. - required: true - type: string - choices: ['scaleway', 'community.general.scaleway'] - regions: - description: Filter results on a specific Scaleway region. - type: list - elements: string - default: - - ams1 - - par1 - - par2 - - waw1 - tags: - description: Filter results on a specific tag. - type: list - elements: string - scw_profile: - description: - - The config profile to use in config file. - - By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is not defined. - type: string - version_added: 4.4.0 - oauth_token: - description: - - Scaleway OAuth token. - - If not explicitly defined or in environment variables, it will try to lookup in the scaleway-cli configuration file - (C($SCW_CONFIG_PATH), C($XDG_CONFIG_HOME/scw/config.yaml), or C(~/.config/scw/config.yaml)). - - More details on L(how to generate token, https://www.scaleway.com/en/docs/generate-api-keys/). - type: string - env: - # in order of precedence - - name: SCW_TOKEN - - name: SCW_API_KEY - - name: SCW_OAUTH_TOKEN - hostnames: - description: List of preference about what to use as an hostname. - type: list - elements: string - default: - - public_ipv4 - choices: - - public_ipv4 - - private_ipv4 - - public_ipv6 - - hostname - - id - variables: - description: 'Set individual variables: keys are variable names and - values are templates. Any value returned by the - L(Scaleway API, https://developer.scaleway.com/#servers-server-get) - can be used.' - type: dict -''' + - The config profile to use in config file. + - By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is not defined. + type: string + version_added: 4.4.0 + oauth_token: + description: + - Scaleway OAuth token. + - If not explicitly defined or in environment variables, it will try to lookup in the scaleway-cli configuration file + (C($SCW_CONFIG_PATH), C($XDG_CONFIG_HOME/scw/config.yaml), or C(~/.config/scw/config.yaml)). + - More details on L(how to generate token, https://www.scaleway.com/en/docs/generate-api-keys/). + type: string + env: + # in order of precedence + - name: SCW_TOKEN + - name: SCW_API_KEY + - name: SCW_OAUTH_TOKEN + hostnames: + description: List of preference about what to use as an hostname. + type: list + elements: string + default: + - public_ipv4 + choices: + - public_ipv4 + - private_ipv4 + - public_ipv6 + - hostname + - id + variables: + description: 'Set individual variables: keys are variable names and + values are templates. Any value returned by the + L(Scaleway API, https://developer.scaleway.com/#servers-server-get) + can be used.' + type: dict +""" -EXAMPLES = r''' +EXAMPLES = r""" # scaleway_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i scaleway_inventory.yml @@ -110,7 +110,7 @@ variables: ansible_host: public_ip.address ansible_connection: "'ssh'" ansible_user: "'admin'" -''' +""" import os import json diff --git a/plugins/inventory/virtualbox.py b/plugins/inventory/virtualbox.py index db2750f636..d94cd64110 100644 --- a/plugins/inventory/virtualbox.py +++ b/plugins/inventory/virtualbox.py @@ -5,56 +5,56 @@ from __future__ import annotations -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: virtualbox - short_description: virtualbox inventory source +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: virtualbox +short_description: virtualbox inventory source +description: + - Get inventory hosts from the local virtualbox installation. + - Uses a YAML configuration file that ends with virtualbox.(yml|yaml) or vbox.(yml|yaml). + - The inventory_hostname is always the 'Name' of the virtualbox instance. + - Groups can be assigned to the VMs using C(VBoxManage). Multiple groups can be assigned by using V(/) as a delimeter. + - A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation for details. +extends_documentation_fragment: + - constructed + - inventory_cache +options: + plugin: + description: token that ensures this is a source file for the 'virtualbox' plugin + type: string + required: true + choices: ['virtualbox', 'community.general.virtualbox'] + running_only: + description: toggles showing all vms vs only those currently running + type: boolean + default: false + settings_password_file: + description: provide a file containing the settings password (equivalent to --settingspwfile) + type: string + network_info_path: + description: property path to query for network information (ansible_host) + type: string + default: "/VirtualBox/GuestInfo/Net/0/V4/IP" + query: + description: create vars from virtualbox properties + type: dictionary + default: {} + enable_advanced_group_parsing: description: - - Get inventory hosts from the local virtualbox installation. - - Uses a YAML configuration file that ends with virtualbox.(yml|yaml) or vbox.(yml|yaml). - - The inventory_hostname is always the 'Name' of the virtualbox instance. - - Groups can be assigned to the VMs using C(VBoxManage). Multiple groups can be assigned by using V(/) as a delimeter. - - A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation for details. - extends_documentation_fragment: - - constructed - - inventory_cache - options: - plugin: - description: token that ensures this is a source file for the 'virtualbox' plugin - type: string - required: true - choices: ['virtualbox', 'community.general.virtualbox'] - running_only: - description: toggles showing all vms vs only those currently running - type: boolean - default: false - settings_password_file: - description: provide a file containing the settings password (equivalent to --settingspwfile) - type: string - network_info_path: - description: property path to query for network information (ansible_host) - type: string - default: "/VirtualBox/GuestInfo/Net/0/V4/IP" - query: - description: create vars from virtualbox properties - type: dictionary - default: {} - enable_advanced_group_parsing: - description: - - The default group parsing rule (when this setting is set to V(false)) is to split the VirtualBox VM's group based on the V(/) character and - assign the resulting list elements as an Ansible Group. - - Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups according to - U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups). - Groups are now split using the V(,) character, and the V(/) character indicates nested groups. - - When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3") will result in - the group C(TestGroup2) being a child group of C(TestGroup); and - the VM being a part of C(TestGroup2) and C(TestGroup3). - default: false - type: bool - version_added: 9.2.0 -''' + - The default group parsing rule (when this setting is set to V(false)) is to split the VirtualBox VM's group based on the V(/) character and + assign the resulting list elements as an Ansible Group. + - Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups according to + U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups). + Groups are now split using the V(,) character, and the V(/) character indicates nested groups. + - When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3") will result in + the group C(TestGroup2) being a child group of C(TestGroup); and + the VM being a part of C(TestGroup2) and C(TestGroup3). + default: false + type: bool + version_added: 9.2.0 +""" -EXAMPLES = ''' +EXAMPLES = r""" --- # file must be named vbox.yaml or vbox.yml plugin: community.general.virtualbox @@ -69,7 +69,7 @@ compose: plugin: community.general.virtualbox groups: container: "'minis' in (inventory_hostname)" -''' +""" import os diff --git a/plugins/lookup/dig.py b/plugins/lookup/dig.py index bb5cfad73a..d958cf186f 100644 --- a/plugins/lookup/dig.py +++ b/plugins/lookup/dig.py @@ -39,8 +39,30 @@ options: - V(CAA) has been added in community.general 6.3.0. type: str default: 'A' - choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, - SRV, SSHFP, TLSA, TXT] + choices: + - A + - ALL + - AAAA + - CAA + - CNAME + - DNAME + - DNSKEY + - DS + - HINFO + - LOC + - MX + - NAPTR + - NS + - NSEC3PARAM + - PTR + - RP + - RRSIG + - SOA + - SPF + - SRV + - SSHFP + - TLSA + - TXT flat: description: If 0 each record is returned as a dictionary, otherwise a string. type: int diff --git a/plugins/test/a_module.py b/plugins/test/a_module.py index 0d6cecac6a..14f7ae27f2 100644 --- a/plugins/test/a_module.py +++ b/plugins/test/a_module.py @@ -6,18 +6,18 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type DOCUMENTATION = ''' - name: a_module - short_description: Test whether a given string refers to an existing module or action plugin - version_added: 4.0.0 - author: Felix Fontein (@felixfontein) - description: - - Test whether a given string refers to an existing module or action plugin. - - This can be useful in roles, which can use this to ensure that required modules are present ahead of time. - options: - _input: - description: A string denoting a fully qualified collection name (FQCN) of a module or action plugin. - type: string - required: true +name: a_module +short_description: Test whether a given string refers to an existing module or action plugin +version_added: 4.0.0 +author: Felix Fontein (@felixfontein) +description: + - Test whether a given string refers to an existing module or action plugin. + - This can be useful in roles, which can use this to ensure that required modules are present ahead of time. +options: + _input: + description: A string denoting a fully qualified collection name (FQCN) of a module or action plugin. + type: string + required: true ''' EXAMPLES = ''' @@ -34,9 +34,9 @@ EXAMPLES = ''' ''' RETURN = ''' - _value: - description: Whether the module or action plugin denoted by the input exists. - type: boolean +_value: + description: Whether the module or action plugin denoted by the input exists. + type: boolean ''' from ansible.plugins.loader import action_loader, module_loader diff --git a/plugins/test/ansible_type.py b/plugins/test/ansible_type.py index f7c004f33f..45bf1b42e5 100644 --- a/plugins/test/ansible_type.py +++ b/plugins/test/ansible_type.py @@ -6,31 +6,31 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type DOCUMENTATION = ''' - name: ansible_type - short_description: Validate input type - version_added: "9.2.0" - author: Vladimir Botka (@vbotka) - description: This test validates input type. - options: - _input: - description: Input data. - type: raw - required: true - dtype: - description: A single data type, or a data types list to be validated. - type: raw - required: true - alias: - description: Data type aliases. - default: {} - type: dictionary +name: ansible_type +short_description: Validate input type +version_added: "9.2.0" +author: Vladimir Botka (@vbotka) +description: This test validates input type. +options: + _input: + description: Input data. + type: raw + required: true + dtype: + description: A single data type, or a data types list to be validated. + type: raw + required: true + alias: + description: Data type aliases. + default: {} + type: dictionary ''' EXAMPLES = ''' - # Substitution converts str to AnsibleUnicode or _AnsibleTaggedStr # ---------------------------------------------------------------- +--- # String. AnsibleUnicode or _AnsibleTaggedStr. dtype: - AnsibleUnicode @@ -39,6 +39,7 @@ data: "abc" result: '{{ data is community.general.ansible_type(dtype) }}' # result => true +--- # String. AnsibleUnicode/_AnsibleTaggedStr alias str. alias: {"AnsibleUnicode": "str", "_AnsibleTaggedStr": "str"} dtype: str @@ -46,6 +47,7 @@ data: "abc" result: '{{ data is community.general.ansible_type(dtype, alias) }}' # result => true +--- # List. All items are AnsibleUnicode/_AnsibleTaggedStr. dtype: - list[AnsibleUnicode] @@ -54,6 +56,7 @@ data: ["a", "b", "c"] result: '{{ data is community.general.ansible_type(dtype) }}' # result => true +--- # Dictionary. All keys and values are AnsibleUnicode/_AnsibleTaggedStr. dtype: - dict[AnsibleUnicode, AnsibleUnicode] @@ -65,41 +68,49 @@ result: '{{ data is community.general.ansible_type(dtype) }}' # No substitution and no alias. Type of strings is str # ---------------------------------------------------- +--- # String dtype: str result: '{{ "abc" is community.general.ansible_type(dtype) }}' # result => true +--- # Integer dtype: int result: '{{ 123 is community.general.ansible_type(dtype) }}' # result => true +--- # Float dtype: float result: '{{ 123.45 is community.general.ansible_type(dtype) }}' # result => true +--- # Boolean dtype: bool result: '{{ true is community.general.ansible_type(dtype) }}' # result => true +--- # List. All items are strings. dtype: list[str] result: '{{ ["a", "b", "c"] is community.general.ansible_type(dtype) }}' # result => true +--- # List of dictionaries. dtype: list[dict] result: '{{ [{"a": 1}, {"b": 2}] is community.general.ansible_type(dtype) }}' # result => true +--- # Dictionary. All keys are strings. All values are integers. dtype: dict[str, int] result: '{{ {"a": 1} is community.general.ansible_type(dtype) }}' # result => true +--- # Dictionary. All keys are strings. All values are integers. dtype: dict[str, int] result: '{{ {"a": 1, "b": 2} is community.general.ansible_type(dtype) }}' @@ -108,6 +119,7 @@ result: '{{ {"a": 1, "b": 2} is community.general.ansible_type(dtype) }}' # Type of strings is AnsibleUnicode, _AnsibleTaggedStr, or str # ------------------------------------------------------------ +--- # Dictionary. The keys are integers or strings. All values are strings. alias: AnsibleUnicode: str @@ -118,6 +130,7 @@ data: {1: 'a', 'b': 'b'} result: '{{ data is community.general.ansible_type(dtype, alias) }}' # result => true +--- # Dictionary. All keys are integers. All values are keys. alias: AnsibleUnicode: str @@ -128,6 +141,7 @@ data: {1: 'a', 2: 'b'} result: '{{ data is community.general.ansible_type(dtype, alias) }}' # result => true +--- # Dictionary. All keys are strings. Multiple types values. alias: AnsibleUnicode: str @@ -135,10 +149,11 @@ alias: _AnsibleTaggedInt: int _AnsibleTaggedFloat: float dtype: dict[str, bool|dict|float|int|list|str] -data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}} +data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}} result: '{{ data is community.general.ansible_type(dtype, alias) }}' # result => true +--- # List. Multiple types items. alias: AnsibleUnicode: str @@ -146,25 +161,28 @@ alias: _AnsibleTaggedInt: int _AnsibleTaggedFloat: float dtype: list[bool|dict|float|int|list|str] -data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}] +data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}] result: '{{ data is community.general.ansible_type(dtype, alias) }}' # result => true # Option dtype is list # -------------------- +--- # AnsibleUnicode, _AnsibleTaggedStr, or str dtype: ['AnsibleUnicode', '_AnsibleTaggedStr', 'str'] data: abc result: '{{ data is community.general.ansible_type(dtype) }}' # result => true +--- # float or int dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"] data: 123 result: '{{ data is community.general.ansible_type(dtype) }}' # result => true +--- # float or int dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"] data: 123.45 @@ -174,23 +192,25 @@ result: '{{ data is community.general.ansible_type(dtype) }}' # Multiple alias # -------------- +--- # int alias number alias: - int: number - float: number - _AnsibleTaggedInt: number - _AnsibleTaggedFloat: float + int: number + float: number + _AnsibleTaggedInt: number + _AnsibleTaggedFloat: float dtype: number data: 123 result: '{{ data is community.general.ansible_type(dtype, alias) }}' # result => true +--- # float alias number alias: - int: number - float: number - _AnsibleTaggedInt: number - _AnsibleTaggedFloat: float + int: number + float: number + _AnsibleTaggedInt: number + _AnsibleTaggedFloat: float dtype: number data: 123.45 result: '{{ data is community.general.ansible_type(dtype, alias) }}' @@ -198,9 +218,9 @@ result: '{{ data is community.general.ansible_type(dtype, alias) }}' ''' RETURN = ''' - _value: - description: Whether the data type is valid. - type: bool +_value: + description: Whether the data type is valid. + type: bool ''' from ansible.errors import AnsibleFilterError diff --git a/plugins/test/fqdn_valid.py b/plugins/test/fqdn_valid.py index 1ec7742077..c8a143687a 100644 --- a/plugins/test/fqdn_valid.py +++ b/plugins/test/fqdn_valid.py @@ -17,41 +17,41 @@ else: DOCUMENTATION = ''' - name: fqdn_valid - short_description: Validates fully-qualified domain names against RFC 1123 - version_added: 8.1.0 - author: Vladimir Botka (@vbotka) - requirements: +name: fqdn_valid +short_description: Validates fully-qualified domain names against RFC 1123 +version_added: 8.1.0 +author: Vladimir Botka (@vbotka) +requirements: - fqdn>=1.5.1 (PyPI) - description: - - This test validates Fully Qualified Domain Names (FQDNs) - conforming to the Internet Engineering Task Force specification - RFC 1123 and RFC 952. - - The design intent is to validate that a string would be - traditionally acceptable as a public Internet hostname to - RFC-conforming software, which is a strict subset of the logic - in modern web browsers like Mozilla Firefox and Chromium that - determines whether make a DNS lookup. - - Certificate Authorities like Let's Encrypt run a narrower set of - string validation logic to determine validity for issuance. This - test is not intended to achieve functional parity with CA - issuance. - - Single label names are allowed by default (O(min_labels=1)). - options: - _input: - description: Name of the host. - type: str - required: true - min_labels: - description: Required minimum of labels, separated by period. - default: 1 - type: int - required: false - allow_underscores: - description: Allow underscore characters. - default: false - type: bool - required: false +description: + - This test validates Fully Qualified Domain Names (FQDNs) + conforming to the Internet Engineering Task Force specification + RFC 1123 and RFC 952. + - The design intent is to validate that a string would be + traditionally acceptable as a public Internet hostname to + RFC-conforming software, which is a strict subset of the logic + in modern web browsers like Mozilla Firefox and Chromium that + determines whether make a DNS lookup. + - Certificate Authorities like Let's Encrypt run a narrower set of + string validation logic to determine validity for issuance. This + test is not intended to achieve functional parity with CA + issuance. + - Single label names are allowed by default (O(min_labels=1)). +options: + _input: + description: Name of the host. + type: str + required: true + min_labels: + description: Required minimum of labels, separated by period. + default: 1 + type: int + required: false + allow_underscores: + description: Allow underscore characters. + default: false + type: bool + required: false ''' EXAMPLES = ''' @@ -69,9 +69,9 @@ EXAMPLES = ''' ''' RETURN = ''' - _value: - description: Whether the name is valid. - type: bool +_value: + description: Whether the name is valid. + type: bool ''' diff --git a/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt index 841806971d..63b01e5cd6 100644 --- a/tests/sanity/ignore-2.15.txt +++ b/tests/sanity/ignore-2.15.txt @@ -17,4 +17,5 @@ plugins/modules/parted.py validate-modules:parameter-state-invalid-choice plugins/modules/rhevm.py validate-modules:parameter-state-invalid-choice plugins/modules/udm_user.py import-3.11 # Uses deprecated stdlib library 'crypt' plugins/modules/xfconf.py validate-modules:return-syntax-error +plugins/test/ansible_type.py yamllint:unparsable-with-libyaml tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt index 7e8a51074d..1642c0d275 100644 --- a/tests/sanity/ignore-2.16.txt +++ b/tests/sanity/ignore-2.16.txt @@ -18,4 +18,5 @@ plugins/modules/rhevm.py validate-modules:parameter-state-invalid-choice plugins/modules/udm_user.py import-3.11 # Uses deprecated stdlib library 'crypt' plugins/modules/udm_user.py import-3.12 # Uses deprecated stdlib library 'crypt' plugins/modules/xfconf.py validate-modules:return-syntax-error +plugins/test/ansible_type.py yamllint:unparsable-with-libyaml tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes