ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-06-27 18:50:21 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Adjust YAML in plugin docs (#10234)

Browse source 
* Adjust YAML in plugin docs.

* Update ignore.txt.

* Forgot two indents.

* adjust connection plugins
adjust filter plugins
adjust inventory plugins
adjust lookup plugins

* Re-add YAML document start.

---------

Co-authored-by: Alexei Znamensky <russoz@gmail.com>
This commit is contained in:
Felix Fontein 2025-06-16 17:46:01 +02:00 • committed by GitHub
parent e8f965fbf8
commit d032de3b16
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 903 additions and 859 deletions
Download patch file Download diff file Expand all files Collapse all files

6
plugins/connection/wsl.py
View file

@ -99,7 +99,7 @@ options:
section: paramiko_connection section: paramiko_connection
type: boolean type: boolean
look_for_keys: look_for_keys:
default: True default: true
description: "Set to V(false) to disable searching for private key files in C(~/.ssh/)." description: "Set to V(false) to disable searching for private key files in C(~/.ssh/)."
env: env:
- name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS - name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS
@ -119,7 +119,7 @@ options:
vars: vars:
- name: ansible_paramiko_proxy_command - name: ansible_paramiko_proxy_command
record_host_keys: record_host_keys:
default: True default: true
description: "Save the host keys to a file." description: "Save the host keys to a file."
env: env:
- name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS - name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS
@ -147,7 +147,7 @@ options:
use_persistent_connections: use_persistent_connections:
description: "Toggles the use of persistence for connections." description: "Toggles the use of persistence for connections."
type: boolean type: boolean
default: False default: false
env: env:
- name: ANSIBLE_USE_PERSISTENT_CONNECTIONS - name: ANSIBLE_USE_PERSISTENT_CONNECTIONS
ini: ini:

36
plugins/doc_fragments/attributes.py
View file

@ -32,14 +32,14 @@ attributes:
INFO_MODULE = r''' INFO_MODULE = r'''
options: {} options: {}
attributes: attributes:
check_mode: check_mode:
support: full support: full
details: details:
- This action does not modify state. - This action does not modify state.
diff_mode: diff_mode:
support: N/A support: N/A
details: details:
- This action does not modify state. - This action does not modify state.
''' '''
CONN = r""" CONN = r"""
@ -64,16 +64,16 @@ attributes:
FACTS_MODULE = r''' FACTS_MODULE = r'''
options: {} options: {}
attributes: attributes:
check_mode: check_mode:
support: full support: full
details: details:
- This action does not modify state. - This action does not modify state.
diff_mode: diff_mode:
support: N/A support: N/A
details: details:
- This action does not modify state. - This action does not modify state.
facts: facts:
support: full support: full
''' '''
FILES = r""" FILES = r"""

30
plugins/doc_fragments/emc.py
View file

@ -13,21 +13,21 @@ class ModuleDocFragment(object):
# Documentation fragment for VNX (emc_vnx) # Documentation fragment for VNX (emc_vnx)
EMC_VNX = r''' EMC_VNX = r'''
options: options:
sp_address: sp_address:
description: description:
- Address of the SP of target/secondary storage. - Address of the SP of target/secondary storage.
type: str type: str
required: true required: true
sp_user: sp_user:
description: description:
- Username for accessing SP. - Username for accessing SP.
type: str type: str
default: sysadmin default: sysadmin
sp_password: sp_password:
description: description:
- password for accessing SP. - password for accessing SP.
type: str type: str
default: sysadmin default: sysadmin
requirements: requirements:
- An EMC VNX Storage device. - An EMC VNX Storage device.
- storops (0.5.10 or greater). Install using C(pip install storops). - storops (0.5.10 or greater). Install using C(pip install storops).

2
plugins/filter/json_patch.yml
View file

@ -64,7 +64,7 @@ EXAMPLES: |
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ input | community.general.json_patch('add', '/1', {'baz': 'qux'}) }}" msg: "{{ input | community.general.json_patch('add', '/1', {'baz': 'qux'}) }}"
vars: vars:
input: ["foo": { "one": 1 }, "bar": { "two": 2 }] input: ["foo": { "one": 1 }, "bar": { "two": 2 }]
# => [{"foo": {"one": 1}}, {"baz": "qux"}, {"bar": {"two": 2}}] # => [{"foo": {"one": 1}}, {"baz": "qux"}, {"bar": {"two": 2}}]
- name: Insert a new key into a dictionary - name: Insert a new key into a dictionary

12
plugins/filter/to_prettytable.py
View file

@ -5,7 +5,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
DOCUMENTATION = ''' DOCUMENTATION = r"""
name: to_prettytable name: to_prettytable
short_description: Format a list of dictionaries as an ASCII table short_description: Format a list of dictionaries as an ASCII table
version_added: "10.7.0" 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 For example, V({'name': 'left', 'id': 'right'}) will align the C(name) column to the left
and the C(id) column to the right. and the C(id) column to the right.
type: dictionary type: dictionary
''' """
EXAMPLES = ''' EXAMPLES = r"""
--- ---
- name: Set a list of users - name: Set a list of users
ansible.builtin.set_fact: ansible.builtin.set_fact:
@ -104,13 +104,13 @@ EXAMPLES = '''
column_alignments={'name': 'center', 'age': 'right', 'role': 'left'} column_alignments={'name': 'center', 'age': 'right', 'role': 'left'}
) )
}} }}
''' """
RETURN = ''' RETURN = r"""
_value: _value:
description: The formatted ASCII table. description: The formatted ASCII table.
type: string type: string
''' """
try: try:
import prettytable import prettytable

228
plugins/inventory/cobbler.py
View file

@ -5,127 +5,127 @@
# SPDX-License-Identifier: GPL-3.0-or-later # SPDX-License-Identifier: GPL-3.0-or-later
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: Orion Poplawski (@opoplawski) author: Orion Poplawski (@opoplawski)
name: cobbler name: cobbler
short_description: Cobbler inventory source short_description: Cobbler inventory source
version_added: 1.0.0 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: description:
- Get inventory hosts from the cobbler service. - Profiles to exclude from inventory.
- "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." - Ignored if O(include_profiles) is specified.
- 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 type: list
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. default: []
extends_documentation_fragment: elements: str
- inventory_cache include_mgmt_classes:
options: description: Management classes to include from inventory.
plugin: type: list
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. default: []
type: string elements: str
required: true version_added: 7.4.0
choices: [ 'cobbler', 'community.general.cobbler' ] include_profiles:
url: description:
description: URL to cobbler. - Profiles to include from inventory.
type: string - If specified, all other profiles will be excluded.
default: 'http://cobbler/cobbler_api' - O(exclude_profiles) is ignored if O(include_profiles) is specified.
env: type: list
- name: COBBLER_SERVER default: []
user: elements: str
description: Cobbler authentication user. version_added: 4.4.0
type: string inventory_hostname:
required: false description:
env: - What to use for the ansible inventory hostname.
- name: COBBLER_USER - By default the networking hostname is used if defined, otherwise the DNS name of the management or first non-static interface.
password: - If set to V(system), the cobbler system name is used.
description: Cobbler authentication password. type: str
type: string choices: ['hostname', 'system']
required: false default: hostname
env: version_added: 7.1.0
- name: COBBLER_PASSWORD group_by:
cache_fallback: description: Keys to group hosts by.
description: Fallback to cached results if connection to cobbler fails. type: list
type: boolean elements: string
default: false default: ['mgmt_classes', 'owners', 'status']
connection_timeout: group:
description: Timeout to connect to cobbler server. description: Group to place all hosts into.
type: int default: cobbler
required: false group_prefix:
version_added: 10.7.0 description: Prefix to apply to cobbler groups.
exclude_mgmt_classes: default: cobbler_
description: Management classes to exclude from inventory. want_facts:
type: list description: Toggle, if V(true) the plugin will retrieve all host facts from the server.
default: [] type: boolean
elements: str default: true
version_added: 7.4.0 want_ip_addresses:
exclude_profiles: description:
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
- Profiles to exclude from inventory. interface DNS names to IP addresses.
- Ignored if O(include_profiles) is specified. type: boolean
type: list default: true
default: [] version_added: 7.1.0
elements: str facts_level:
include_mgmt_classes: description:
description: Management classes to include from inventory. - "Set to V(normal) to gather only system-level variables."
type: list - "Set to V(as_rendered) to gather all variables as rolled up by Cobbler."
default: [] type: string
elements: str choices: ['normal', 'as_rendered']
version_added: 7.4.0 default: normal
include_profiles: version_added: 10.7.0
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 # my.cobbler.yml
plugin: community.general.cobbler plugin: community.general.cobbler
url: http://cobbler/cobbler_api url: http://cobbler/cobbler_api
user: ansible-tester user: ansible-tester
password: secure password: secure
''' """
import socket import socket

100
plugins/inventory/gitlab_runners.py
View file

@ -7,56 +7,56 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = ''' DOCUMENTATION = r"""
name: gitlab_runners name: gitlab_runners
author: author:
- Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com> - Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
short_description: Ansible dynamic inventory plugin for GitLab runners. short_description: Ansible dynamic inventory plugin for GitLab runners.
requirements: requirements:
- python-gitlab > 1.8.0 - python-gitlab > 1.8.0
extends_documentation_fragment: extends_documentation_fragment:
- constructed - constructed
description: description:
- Reads inventories from the GitLab API. - Reads inventories from the GitLab API.
- Uses a YAML configuration file gitlab_runners.[yml|yaml]. - Uses a YAML configuration file gitlab_runners.[yml|yaml].
options: options:
plugin: plugin:
description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own. 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 type: str
required: true required: true
choices: choices:
- gitlab_runners - gitlab_runners
- community.general.gitlab_runners - community.general.gitlab_runners
server_url: server_url:
description: The URL of the GitLab server, with protocol (i.e. http or https). description: The URL of the GitLab server, with protocol (i.e. http or https).
env: env:
- name: GITLAB_SERVER_URL - name: GITLAB_SERVER_URL
version_added: 1.0.0 version_added: 1.0.0
type: str type: str
required: true required: true
api_token: api_token:
description: GitLab token for logging in. description: GitLab token for logging in.
env: env:
- name: GITLAB_API_TOKEN - name: GITLAB_API_TOKEN
version_added: 1.0.0 version_added: 1.0.0
type: str type: str
aliases: aliases:
- private_token - private_token
- access_token - access_token
filter: filter:
description: filter runners from GitLab API description: filter runners from GitLab API
env: env:
- name: GITLAB_FILTER - name: GITLAB_FILTER
version_added: 1.0.0 version_added: 1.0.0
type: str type: str
choices: ['active', 'paused', 'online', 'specific', 'shared'] choices: ['active', 'paused', 'online', 'specific', 'shared']
verbose_output: verbose_output:
description: Toggle to (not) include all available nodes metadata description: Toggle to (not) include all available nodes metadata
type: bool type: bool
default: true default: true
''' """
EXAMPLES = ''' EXAMPLES = r"""
--- ---
# gitlab_runners.yml # gitlab_runners.yml
plugin: community.general.gitlab_runners plugin: community.general.gitlab_runners
@ -79,7 +79,7 @@ keyed_groups:
# hint: labels containing special characters will be converted to safe names # hint: labels containing special characters will be converted to safe names
- key: 'tag_list' - key: 'tag_list'
prefix: tag prefix: tag
''' """
from ansible.errors import AnsibleError, AnsibleParserError from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.inventory import BaseInventoryPlugin, Constructable from ansible.plugins.inventory import BaseInventoryPlugin, Constructable

128
plugins/inventory/icinga2.py
View file

@ -6,71 +6,71 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = ''' DOCUMENTATION = r"""
name: icinga2 name: icinga2
short_description: Icinga2 inventory source short_description: Icinga2 inventory source
version_added: 3.7.0 version_added: 3.7.0
author: author:
- Cliff Hults (@BongoEADGC6) <cliff.hults@gmail.com> - Cliff Hults (@BongoEADGC6) <cliff.hults@gmail.com>
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: description:
- Get inventory hosts from the Icinga2 API. - An Icinga2 API valid host filter. Leave blank for no filtering
- "Uses a configuration file as an inventory source, it must end in type: string
C(.icinga2.yml) or C(.icinga2.yaml)." required: false
extends_documentation_fragment: validate_certs:
- constructed description: Enables or disables SSL certificate verification.
options: type: boolean
strict: default: true
version_added: 4.4.0 inventory_attr:
compose: description:
version_added: 4.4.0 - Allows the override of the inventory name based on different attributes.
groups: - This allows for changing the way limits are used.
version_added: 4.4.0 - The current default, V(address), is sometimes not unique or present. We recommend to use V(name) instead.
keyed_groups: type: string
version_added: 4.4.0 default: address
plugin: choices: ['name', 'display_name', 'address']
description: Name of the plugin. version_added: 4.2.0
required: true group_by_hostgroups:
type: string description:
choices: ['community.general.icinga2'] - Uses Icinga2 hostgroups as groups.
url: type: boolean
description: Root URL of Icinga2 API. default: true
type: string version_added: 8.4.0
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
'''
EXAMPLES = r''' EXAMPLES = r"""
# my.icinga2.yml # my.icinga2.yml
plugin: community.general.icinga2 plugin: community.general.icinga2
url: http://localhost:5665 url: http://localhost:5665
@ -93,7 +93,7 @@ compose:
# set 'ansible_user' and 'ansible_port' from icinga2 host vars # set 'ansible_user' and 'ansible_port' from icinga2 host vars
ansible_user: icinga2_attributes.vars.ansible_user ansible_user: icinga2_attributes.vars.ansible_user
ansible_port: icinga2_attributes.vars.ansible_port | default(22) ansible_port: icinga2_attributes.vars.ansible_port | default(22)
''' """
import json import json

8
plugins/inventory/iocage.py
View file

@ -6,7 +6,7 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: iocage name: iocage
short_description: iocage inventory source short_description: iocage inventory source
version_added: 10.2.0 version_added: 10.2.0
@ -110,9 +110,9 @@ notes:
expects to find the O(hooks_results) items in the path expects to find the O(hooks_results) items in the path
C(/iocage/iocage/jails/<name>/root). If you mount the C(poolname) to a C(/iocage/iocage/jails/<name>/root). If you mount the C(poolname) to a
different path the easiest remedy is to create a symlink. different path the easiest remedy is to create a symlink.
''' """
EXAMPLES = r''' EXAMPLES = r"""
--- ---
# file name must end with iocage.yaml or iocage.yml # file name must end with iocage.yaml or iocage.yml
plugin: community.general.iocage plugin: community.general.iocage
@ -182,7 +182,7 @@ compose:
ansible_host: iocage_hooks.0 ansible_host: iocage_hooks.0
groups: groups:
test: inventory_hostname.startswith('test') test: inventory_hostname.startswith('test')
''' """
import re import re
import os import os

146
plugins/inventory/linode.py
View file

@ -5,79 +5,79 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: linode name: linode
author: author:
- Luke Murphy (@decentral1se) - Luke Murphy (@decentral1se)
short_description: Ansible dynamic inventory plugin for Linode. short_description: Ansible dynamic inventory plugin for Linode.
requirements: requirements:
- linode_api4 >= 2.0.0 - linode_api4 >= 2.0.0
description: description:
- Reads inventories from the Linode API v4. - Reads inventories from the Linode API v4.
- Uses a YAML configuration file that ends with linode.(yml|yaml). - Uses a YAML configuration file that ends with linode.(yml|yaml).
- Linode labels are used by default as the hostnames. - Linode labels are used by default as the hostnames.
- The default inventory groups are built from groups (deprecated by - The default inventory groups are built from groups (deprecated by
Linode) and not tags. Linode) and not tags.
extends_documentation_fragment: extends_documentation_fragment:
- constructed - constructed
- inventory_cache - inventory_cache
options: options:
cache: cache:
version_added: 4.5.0 version_added: 4.5.0
cache_plugin: cache_plugin:
version_added: 4.5.0 version_added: 4.5.0
cache_timeout: cache_timeout:
version_added: 4.5.0 version_added: 4.5.0
cache_connection: cache_connection:
version_added: 4.5.0 version_added: 4.5.0
cache_prefix: cache_prefix:
version_added: 4.5.0 version_added: 4.5.0
plugin: plugin:
description: Marks this as an instance of the 'linode' plugin. description: Marks this as an instance of the 'linode' plugin.
type: string type: string
required: true required: true
choices: ['linode', 'community.general.linode'] choices: ['linode', 'community.general.linode']
ip_style: ip_style:
description: Populate hostvars with all information available from the Linode APIv4. description: Populate hostvars with all information available from the Linode APIv4.
type: string type: string
default: plain default: plain
choices: choices:
- plain - plain
- api - api
version_added: 3.6.0 version_added: 3.6.0
access_token: access_token:
description: The Linode account personal access token. description: The Linode account personal access token.
type: string type: string
required: true required: true
env: env:
- name: LINODE_ACCESS_TOKEN - name: LINODE_ACCESS_TOKEN
regions: regions:
description: Populate inventory with instances in this region. description: Populate inventory with instances in this region.
default: [] default: []
type: list type: list
elements: string elements: string
tags: tags:
description: Populate inventory only with instances which have at least one of the tags listed here. description: Populate inventory only with instances which have at least one of the tags listed here.
default: [] default: []
type: list type: list
elements: string elements: string
version_added: 2.0.0 version_added: 2.0.0
types: types:
description: Populate inventory with instances with this type. description: Populate inventory with instances with this type.
default: [] default: []
type: list type: list
elements: string elements: string
strict: strict:
version_added: 2.0.0 version_added: 2.0.0
compose: compose:
version_added: 2.0.0 version_added: 2.0.0
groups: groups:
version_added: 2.0.0 version_added: 2.0.0
keyed_groups: keyed_groups:
version_added: 2.0.0 version_added: 2.0.0
''' """
EXAMPLES = r''' EXAMPLES = r"""
--- ---
# Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment.
plugin: community.general.linode plugin: community.general.linode
@ -124,7 +124,7 @@ access_token: foobar
ip_style: api ip_style: api
compose: compose:
ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first" ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first"
''' """
from ansible.errors import AnsibleError from ansible.errors import AnsibleError
from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable

202
plugins/inventory/lxd.py
View file

@ -5,108 +5,108 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: lxd name: lxd
short_description: Returns Ansible inventory from lxd host 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: description:
- Get inventory from the lxd. - The unix domain socket path or the https URL for the lxd server.
- Uses a YAML configuration file that ends with 'lxd.(yml|yaml)'. - Sockets in filesystem have to start with C(unix:).
version_added: "3.0.0" - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket).
author: "Frank Dornheim (@conloos)" type: string
requirements: default: unix:/var/snap/lxd/common/lxd/unix.socket
- ipaddress client_key:
- lxd >= 4.0 description:
options: - The client certificate key file path.
plugin: aliases: [key_file]
description: Token that ensures this is a source file for the 'lxd' plugin. default: $HOME/.config/lxc/client.key
type: string type: path
required: true client_cert:
choices: [ 'community.general.lxd' ] description:
url: - The client certificate file path.
description: aliases: [cert_file]
- The unix domain socket path or the https URL for the lxd server. default: $HOME/.config/lxc/client.crt
- Sockets in filesystem have to start with C(unix:). type: path
- Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). server_cert:
type: string description:
default: unix:/var/snap/lxd/common/lxd/unix.socket - The server certificate file path.
client_key: type: path
description: version_added: 8.0.0
- The client certificate key file path. server_check_hostname:
aliases: [ key_file ] description:
default: $HOME/.config/lxc/client.key - This option controls if the server's hostname is checked as part of the HTTPS connection verification.
type: path This can be useful to disable, if for example, the server certificate provided (see O(server_cert) option)
client_cert: does not cover a name matching the one used to communicate with the server. Such mismatch is common as LXD
description: generates self-signed server certificates by default.
- The client certificate file path. type: bool
aliases: [ cert_file ] default: true
default: $HOME/.config/lxc/client.crt version_added: 8.0.0
type: path trust_password:
server_cert: description:
description: - The client trusted password.
- The server certificate file path. - You need to set this password on the lxd server before
type: path running this module using the following command
version_added: 8.0.0 C(lxc config set core.trust_password <some random password>)
server_check_hostname: See U(https://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password).
description: - If O(trust_password) is set, this module send a request for authentication before sending any requests.
- This option controls if the server's hostname is checked as part of the HTTPS connection verification. type: str
This can be useful to disable, if for example, the server certificate provided (see O(server_cert) option) state:
does not cover a name matching the one used to communicate with the server. Such mismatch is common as LXD description: Filter the instance according to the current status.
generates self-signed server certificates by default. type: str
type: bool default: none
default: true choices: ['STOPPED', 'STARTING', 'RUNNING', 'none']
version_added: 8.0.0 project:
trust_password: description: Filter the instance according to the given project.
description: type: str
- The client trusted password. default: default
- You need to set this password on the lxd server before version_added: 6.2.0
running this module using the following command type_filter:
C(lxc config set core.trust_password <some random password>) description:
See U(https://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). - Filter the instances by type V(virtual-machine), V(container) or V(both).
- If O(trust_password) is set, this module send a request for authentication before sending any requests. - The first version of the inventory only supported containers.
type: str type: str
state: default: container
description: Filter the instance according to the current status. choices: ['virtual-machine', 'container', 'both']
type: str version_added: 4.2.0
default: none prefered_instance_network_interface:
choices: [ 'STOPPED', 'STARTING', 'RUNNING', 'none' ] description:
project: - If an instance has multiple network interfaces, select which one is the preferred as pattern.
description: Filter the instance according to the given project. - Combined with the first number that can be found e.g. 'eth' + 0.
type: str - The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface)
default: default in community.general 3.8.0. The old name still works as an alias.
version_added: 6.2.0 type: str
type_filter: default: eth
description: aliases:
- Filter the instances by type V(virtual-machine), V(container) or V(both). - prefered_container_network_interface
- The first version of the inventory only supported containers. prefered_instance_network_family:
type: str description:
default: container - If an instance has multiple network interfaces, which one is the preferred by family.
choices: [ 'virtual-machine', 'container', 'both' ] - Specify V(inet) for IPv4 and V(inet6) for IPv6.
version_added: 4.2.0 type: str
prefered_instance_network_interface: default: inet
description: choices: ['inet', 'inet6']
- If an instance has multiple network interfaces, select which one is the preferred as pattern. groupby:
- Combined with the first number that can be found e.g. 'eth' + 0. description:
- The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface) - Create groups by the following keywords C(location), C(network_range), C(os), C(pattern), C(profile), C(release), C(type), C(vlanid).
in community.general 3.8.0. The old name still works as an alias. - See example for syntax.
type: str type: dict
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 # simple lxd.yml
plugin: community.general.lxd plugin: community.general.lxd
@ -165,7 +165,7 @@ groupby:
projectInternals: projectInternals:
type: project type: project
attribute: internals attribute: internals
''' """
import json import json
import re import re

192
plugins/inventory/nmap.py
View file

@ -5,102 +5,102 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: Unknown (!UNKNOWN) author: Unknown (!UNKNOWN)
name: nmap name: nmap
short_description: Uses nmap to find hosts to target 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: description:
- Uses a YAML configuration file with a valid YAML extension. - List of addresses to exclude.
extends_documentation_fragment: - For example V(10.2.2.15-25) or V(10.2.2.15,10.2.2.16).
- constructed type: list
- inventory_cache elements: string
requirements: env:
- nmap CLI installed - name: ANSIBLE_NMAP_EXCLUDE
options: version_added: 6.6.0
plugin: port:
description: token that ensures this is a source file for the 'nmap' plugin. description:
type: string - Only scan specific port or port range (C(-p)).
required: true - For example, you could pass V(22) for a single port, V(1-65535) for a range of ports,
choices: ['nmap', 'community.general.nmap'] 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.
sudo: type: string
description: Set to V(true) to execute a C(sudo nmap) plugin scan. version_added: 6.5.0
version_added: 4.8.0 ports:
default: false description: Enable/disable scanning ports.
type: boolean type: boolean
address: default: true
description: Network IP or range of IPs to scan, you can use a simple range (10.2.2.15-25) or CIDR notation. ipv4:
type: string description: use IPv4 type addresses
required: true type: boolean
env: default: true
- name: ANSIBLE_NMAP_ADDRESS ipv6:
version_added: 6.6.0 description: use IPv6 type addresses
exclude: type: boolean
description: default: true
- List of addresses to exclude. udp_scan:
- For example V(10.2.2.15-25) or V(10.2.2.15,10.2.2.16). description:
type: list - Scan via UDP.
elements: string - Depending on your system you might need O(sudo=true) for this to work.
env: type: boolean
- name: ANSIBLE_NMAP_EXCLUDE default: false
version_added: 6.6.0 version_added: 6.1.0
port: icmp_timestamp:
description: description:
- Only scan specific port or port range (C(-p)). - Scan via ICMP Timestamp (C(-PP)).
- For example, you could pass V(22) for a single port, V(1-65535) for a range of ports, - Depending on your system you might need O(sudo=true) for this to work.
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: boolean
type: string default: false
version_added: 6.5.0 version_added: 6.1.0
ports: open:
description: Enable/disable scanning ports. description: Only scan for open (or possibly open) ports.
type: boolean type: boolean
default: true default: false
ipv4: version_added: 6.5.0
description: use IPv4 type addresses dns_resolve:
type: boolean description: Whether to always (V(true)) or never (V(false)) do DNS resolution.
default: true type: boolean
ipv6: default: false
description: use IPv6 type addresses version_added: 6.1.0
type: boolean dns_servers:
default: true description: Specify which DNS servers to use for name resolution.
udp_scan: type: list
description: elements: string
- Scan via UDP. version_added: 10.5.0
- Depending on your system you might need O(sudo=true) for this to work. use_arp_ping:
type: boolean description: Whether to always (V(true)) use the quick ARP ping or (V(false)) a slower but more reliable method.
default: false type: boolean
version_added: 6.1.0 default: true
icmp_timestamp: version_added: 7.4.0
description: notes:
- Scan via ICMP Timestamp (C(-PP)). - 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).
- Depending on your system you might need O(sudo=true) for this to work. - 'TODO: add OS fingerprinting'
type: boolean """
default: false EXAMPLES = r"""
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 = '''
--- ---
# inventory.config file in YAML format # inventory.config file in YAML format
plugin: community.general.nmap plugin: community.general.nmap
@ -122,7 +122,7 @@ exclude: 192.168.0.1, web.example.com
port: 22, 443 port: 22, 443
groups: groups:
web_servers: "ports | selectattr('port', 'equalto', '443')" web_servers: "ports | selectattr('port', 'equalto', '443')"
''' """
import os import os
import re import re

86
plugins/inventory/online.py
View file

@ -5,49 +5,49 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: online name: online
author: author:
- Remy Leone (@remyleone) - Remy Leone (@remyleone)
short_description: Scaleway (previously Online SAS or Online.net) inventory source short_description: Scaleway (previously Online SAS or Online.net) inventory source
description: description:
- Get inventory hosts from Scaleway (previously Online SAS or Online.net). - Get inventory hosts from Scaleway (previously Online SAS or Online.net).
options: options:
plugin: plugin:
description: token that ensures this is a source file for the 'online' plugin. description: token that ensures this is a source file for the 'online' plugin.
type: string type: string
required: true required: true
choices: ['online', 'community.general.online'] choices: ['online', 'community.general.online']
oauth_token: oauth_token:
required: true required: true
description: Online OAuth token. description: Online OAuth token.
type: string type: string
env: env:
# in order of precedence # in order of precedence
- name: ONLINE_TOKEN - name: ONLINE_TOKEN
- name: ONLINE_API_KEY - name: ONLINE_API_KEY
- name: ONLINE_OAUTH_TOKEN - name: ONLINE_OAUTH_TOKEN
hostnames: hostnames:
description: List of preference about what to use as an hostname. description: List of preference about what to use as an hostname.
type: list type: list
elements: string elements: string
default: default:
- public_ipv4 - public_ipv4
choices: choices:
- public_ipv4 - public_ipv4
- private_ipv4 - private_ipv4
- hostname - hostname
groups: groups:
description: List of groups. description: List of groups.
type: list type: list
elements: string elements: string
choices: choices:
- location - location
- offer - offer
- rpn - rpn
''' """
EXAMPLES = r''' EXAMPLES = r"""
# online_inventory.yml file in YAML format # online_inventory.yml file in YAML format
# Example command line: ansible-inventory --list -i online_inventory.yml # Example command line: ansible-inventory --list -i online_inventory.yml
@ -58,7 +58,7 @@ groups:
- location - location
- offer - offer
- rpn - rpn
''' """
import json import json
from sys import version as python_version from sys import version as python_version

140
plugins/inventory/opennebula.py
View file

@ -6,77 +6,77 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: opennebula name: opennebula
author: author:
- Kristian Feldsam (@feldsam) - Kristian Feldsam (@feldsam)
short_description: OpenNebula inventory source short_description: OpenNebula inventory source
version_added: "3.8.0" version_added: "3.8.0"
extends_documentation_fragment: extends_documentation_fragment:
- constructed - 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: description:
- Get inventory hosts from OpenNebula cloud. - URL of the OpenNebula RPC server.
- Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml) - It is recommended to use HTTPS so that the username/password are not
to set parameter values. transferred over the network unencrypted.
- Uses O(api_authfile), C(~/.one/one_auth), or E(ONE_AUTH) pointing to a OpenNebula credentials file. - If not set then the value of the E(ONE_URL) environment variable is used.
options: env:
plugin: - name: ONE_URL
description: Token that ensures this is a source file for the 'opennebula' plugin. required: true
type: string type: string
required: true api_username:
choices: [ community.general.opennebula ] description:
api_url: - Name of the user to login into the OpenNebula RPC server. If not set
description: then the value of the E(ONE_USERNAME) environment variable is used.
- URL of the OpenNebula RPC server. env:
- It is recommended to use HTTPS so that the username/password are not - name: ONE_USERNAME
transferred over the network unencrypted. type: string
- If not set then the value of the E(ONE_URL) environment variable is used. api_password:
env: description:
- name: ONE_URL - Password or a token of the user to login into OpenNebula RPC server.
required: true - If not set, the value of the E(ONE_PASSWORD) environment variable is used.
type: string env:
api_username: - name: ONE_PASSWORD
description: required: false
- Name of the user to login into the OpenNebula RPC server. If not set type: string
then the value of the E(ONE_USERNAME) environment variable is used. api_authfile:
env: description:
- name: ONE_USERNAME - If both O(api_username) or O(api_password) are not set, then it will try
type: string authenticate with ONE auth file. Default path is C(~/.one/one_auth).
api_password: - Set environment variable E(ONE_AUTH) to override this path.
description: env:
- Password or a token of the user to login into OpenNebula RPC server. - name: ONE_AUTH
- If not set, the value of the E(ONE_PASSWORD) environment variable is used. required: false
env: type: string
- name: ONE_PASSWORD hostname:
required: false description: Field to match the hostname. Note V(v4_first_ip) corresponds to the first IPv4 found on VM.
type: string type: string
api_authfile: default: v4_first_ip
description: choices:
- If both O(api_username) or O(api_password) are not set, then it will try - v4_first_ip
authenticate with ONE auth file. Default path is C(~/.one/one_auth). - v6_first_ip
- Set environment variable E(ONE_AUTH) to override this path. - name
env: filter_by_label:
- name: ONE_AUTH description: Only return servers filtered by this label.
required: false type: string
type: string group_by_labels:
hostname: description: Create host groups by vm labels
description: Field to match the hostname. Note V(v4_first_ip) corresponds to the first IPv4 found on VM. type: bool
type: string default: true
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 # inventory_opennebula.yml file in YAML format
# Example command line: ansible-inventory --list -i inventory_opennebula.yml # Example command line: ansible-inventory --list -i inventory_opennebula.yml
@ -84,7 +84,7 @@ EXAMPLES = r'''
plugin: community.general.opennebula plugin: community.general.opennebula
api_url: https://opennebula:2633/RPC2 api_url: https://opennebula:2633/RPC2
filter_by_label: Cache filter_by_label: Cache
''' """
try: try:
import pyone import pyone

132
plugins/inventory/scaleway.py
View file

@ -6,73 +6,73 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: scaleway name: scaleway
author: author:
- Remy Leone (@remyleone) - Remy Leone (@remyleone)
short_description: Scaleway inventory source 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: description:
- Get inventory hosts from Scaleway. - The config profile to use in config file.
requirements: - 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.
- PyYAML type: string
options: version_added: 4.4.0
plugin: oauth_token:
description: Token that ensures this is a source file for the 'scaleway' plugin. description:
required: true - Scaleway OAuth token.
type: string - If not explicitly defined or in environment variables, it will try to lookup in the scaleway-cli configuration file
choices: ['scaleway', 'community.general.scaleway'] (C($SCW_CONFIG_PATH), C($XDG_CONFIG_HOME/scw/config.yaml), or C(~/.config/scw/config.yaml)).
regions: - More details on L(how to generate token, https://www.scaleway.com/en/docs/generate-api-keys/).
description: Filter results on a specific Scaleway region. type: string
type: list env:
elements: string # in order of precedence
default: - name: SCW_TOKEN
- ams1 - name: SCW_API_KEY
- par1 - name: SCW_OAUTH_TOKEN
- par2 hostnames:
- waw1 description: List of preference about what to use as an hostname.
tags: type: list
description: Filter results on a specific tag. elements: string
type: list default:
elements: string - public_ipv4
scw_profile: choices:
description: - public_ipv4
- The config profile to use in config file. - private_ipv4
- 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. - public_ipv6
type: string - hostname
version_added: 4.4.0 - id
oauth_token: variables:
description: description: 'Set individual variables: keys are variable names and
- Scaleway OAuth token. values are templates. Any value returned by the
- If not explicitly defined or in environment variables, it will try to lookup in the scaleway-cli configuration file L(Scaleway API, https://developer.scaleway.com/#servers-server-get)
(C($SCW_CONFIG_PATH), C($XDG_CONFIG_HOME/scw/config.yaml), or C(~/.config/scw/config.yaml)). can be used.'
- More details on L(how to generate token, https://www.scaleway.com/en/docs/generate-api-keys/). type: dict
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 # scaleway_inventory.yml file in YAML format
# Example command line: ansible-inventory --list -i scaleway_inventory.yml # Example command line: ansible-inventory --list -i scaleway_inventory.yml
@ -110,7 +110,7 @@ variables:
ansible_host: public_ip.address ansible_host: public_ip.address
ansible_connection: "'ssh'" ansible_connection: "'ssh'"
ansible_user: "'admin'" ansible_user: "'admin'"
''' """
import os import os
import json import json

98
plugins/inventory/virtualbox.py
View file

@ -5,56 +5,56 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: Unknown (!UNKNOWN) author: Unknown (!UNKNOWN)
name: virtualbox name: virtualbox
short_description: virtualbox inventory source 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: description:
- Get inventory hosts from the local virtualbox installation. - 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
- Uses a YAML configuration file that ends with virtualbox.(yml|yaml) or vbox.(yml|yaml). assign the resulting list elements as an Ansible Group.
- The inventory_hostname is always the 'Name' of the virtualbox instance. - Setting O(enable_advanced_group_parsing=true) changes this behaviour to match VirtualBox's interpretation of groups according to
- Groups can be assigned to the VMs using C(VBoxManage). Multiple groups can be assigned by using V(/) as a delimeter. U(https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups).
- A separate parameter, O(enable_advanced_group_parsing) is exposed to change grouping behaviour. See the parameter documentation for details. Groups are now split using the V(,) character, and the V(/) character indicates nested groups.
extends_documentation_fragment: - When enabled, a VM that's been configured using V(VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2,/TestGroup3") will result in
- constructed the group C(TestGroup2) being a child group of C(TestGroup); and
- inventory_cache the VM being a part of C(TestGroup2) and C(TestGroup3).
options: default: false
plugin: type: bool
description: token that ensures this is a source file for the 'virtualbox' plugin version_added: 9.2.0
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
'''
EXAMPLES = ''' EXAMPLES = r"""
--- ---
# file must be named vbox.yaml or vbox.yml # file must be named vbox.yaml or vbox.yml
plugin: community.general.virtualbox plugin: community.general.virtualbox
@ -69,7 +69,7 @@ compose:
plugin: community.general.virtualbox plugin: community.general.virtualbox
groups: groups:
container: "'minis' in (inventory_hostname)" container: "'minis' in (inventory_hostname)"
''' """
import os import os

26
plugins/lookup/dig.py
View file

@ -39,8 +39,30 @@ options:
- V(CAA) has been added in community.general 6.3.0. - V(CAA) has been added in community.general 6.3.0.
type: str type: str
default: 'A' default: 'A'
choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, choices:
SRV, SSHFP, TLSA, TXT] - A
- ALL
- AAAA
- CAA
- CNAME
- DNAME
- DNSKEY
- DS
- HINFO
- LOC
- MX
- NAPTR
- NS
- NSEC3PARAM
- PTR
- RP
- RRSIG
- SOA
- SPF
- SRV
- SSHFP
- TLSA
- TXT
flat: flat:
description: If 0 each record is returned as a dictionary, otherwise a string. description: If 0 each record is returned as a dictionary, otherwise a string.
type: int type: int

30
plugins/test/a_module.py
View file

@ -6,18 +6,18 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = '''
name: a_module name: a_module
short_description: Test whether a given string refers to an existing module or action plugin short_description: Test whether a given string refers to an existing module or action plugin
version_added: 4.0.0 version_added: 4.0.0
author: Felix Fontein (@felixfontein) author: Felix Fontein (@felixfontein)
description: description:
- Test whether a given string refers to an existing module or action plugin. - 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. - This can be useful in roles, which can use this to ensure that required modules are present ahead of time.
options: options:
_input: _input:
description: A string denoting a fully qualified collection name (FQCN) of a module or action plugin. description: A string denoting a fully qualified collection name (FQCN) of a module or action plugin.
type: string type: string
required: true required: true
''' '''
EXAMPLES = ''' EXAMPLES = '''
@ -34,9 +34,9 @@ EXAMPLES = '''
''' '''
RETURN = ''' RETURN = '''
_value: _value:
description: Whether the module or action plugin denoted by the input exists. description: Whether the module or action plugin denoted by the input exists.
type: boolean type: boolean
''' '''
from ansible.plugins.loader import action_loader, module_loader from ansible.plugins.loader import action_loader, module_loader

84
plugins/test/ansible_type.py
View file

@ -6,31 +6,31 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = '''
name: ansible_type name: ansible_type
short_description: Validate input type short_description: Validate input type
version_added: "9.2.0" version_added: "9.2.0"
author: Vladimir Botka (@vbotka) author: Vladimir Botka (@vbotka)
description: This test validates input type. description: This test validates input type.
options: options:
_input: _input:
description: Input data. description: Input data.
type: raw type: raw
required: true required: true
dtype: dtype:
description: A single data type, or a data types list to be validated. description: A single data type, or a data types list to be validated.
type: raw type: raw
required: true required: true
alias: alias:
description: Data type aliases. description: Data type aliases.
default: {} default: {}
type: dictionary type: dictionary
''' '''
EXAMPLES = ''' EXAMPLES = '''
# Substitution converts str to AnsibleUnicode or _AnsibleTaggedStr # Substitution converts str to AnsibleUnicode or _AnsibleTaggedStr
# ---------------------------------------------------------------- # ----------------------------------------------------------------
---
# String. AnsibleUnicode or _AnsibleTaggedStr. # String. AnsibleUnicode or _AnsibleTaggedStr.
dtype: dtype:
- AnsibleUnicode - AnsibleUnicode
@ -39,6 +39,7 @@ data: "abc"
result: '{{ data is community.general.ansible_type(dtype) }}' result: '{{ data is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# String. AnsibleUnicode/_AnsibleTaggedStr alias str. # String. AnsibleUnicode/_AnsibleTaggedStr alias str.
alias: {"AnsibleUnicode": "str", "_AnsibleTaggedStr": "str"} alias: {"AnsibleUnicode": "str", "_AnsibleTaggedStr": "str"}
dtype: str dtype: str
@ -46,6 +47,7 @@ data: "abc"
result: '{{ data is community.general.ansible_type(dtype, alias) }}' result: '{{ data is community.general.ansible_type(dtype, alias) }}'
# result => true # result => true
---
# List. All items are AnsibleUnicode/_AnsibleTaggedStr. # List. All items are AnsibleUnicode/_AnsibleTaggedStr.
dtype: dtype:
- list[AnsibleUnicode] - list[AnsibleUnicode]
@ -54,6 +56,7 @@ data: ["a", "b", "c"]
result: '{{ data is community.general.ansible_type(dtype) }}' result: '{{ data is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# Dictionary. All keys and values are AnsibleUnicode/_AnsibleTaggedStr. # Dictionary. All keys and values are AnsibleUnicode/_AnsibleTaggedStr.
dtype: dtype:
- dict[AnsibleUnicode, AnsibleUnicode] - 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 # No substitution and no alias. Type of strings is str
# ---------------------------------------------------- # ----------------------------------------------------
---
# String # String
dtype: str dtype: str
result: '{{ "abc" is community.general.ansible_type(dtype) }}' result: '{{ "abc" is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# Integer # Integer
dtype: int dtype: int
result: '{{ 123 is community.general.ansible_type(dtype) }}' result: '{{ 123 is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# Float # Float
dtype: float dtype: float
result: '{{ 123.45 is community.general.ansible_type(dtype) }}' result: '{{ 123.45 is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# Boolean # Boolean
dtype: bool dtype: bool
result: '{{ true is community.general.ansible_type(dtype) }}' result: '{{ true is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# List. All items are strings. # List. All items are strings.
dtype: list[str] dtype: list[str]
result: '{{ ["a", "b", "c"] is community.general.ansible_type(dtype) }}' result: '{{ ["a", "b", "c"] is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# List of dictionaries. # List of dictionaries.
dtype: list[dict] dtype: list[dict]
result: '{{ [{"a": 1}, {"b": 2}] is community.general.ansible_type(dtype) }}' result: '{{ [{"a": 1}, {"b": 2}] is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# Dictionary. All keys are strings. All values are integers. # Dictionary. All keys are strings. All values are integers.
dtype: dict[str, int] dtype: dict[str, int]
result: '{{ {"a": 1} is community.general.ansible_type(dtype) }}' result: '{{ {"a": 1} is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# Dictionary. All keys are strings. All values are integers. # Dictionary. All keys are strings. All values are integers.
dtype: dict[str, int] dtype: dict[str, int]
result: '{{ {"a": 1, "b": 2} is community.general.ansible_type(dtype) }}' 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 # Type of strings is AnsibleUnicode, _AnsibleTaggedStr, or str
# ------------------------------------------------------------ # ------------------------------------------------------------
---
# Dictionary. The keys are integers or strings. All values are strings. # Dictionary. The keys are integers or strings. All values are strings.
alias: alias:
AnsibleUnicode: str AnsibleUnicode: str
@ -118,6 +130,7 @@ data: {1: 'a', 'b': 'b'}
result: '{{ data is community.general.ansible_type(dtype, alias) }}' result: '{{ data is community.general.ansible_type(dtype, alias) }}'
# result => true # result => true
---
# Dictionary. All keys are integers. All values are keys. # Dictionary. All keys are integers. All values are keys.
alias: alias:
AnsibleUnicode: str AnsibleUnicode: str
@ -128,6 +141,7 @@ data: {1: 'a', 2: 'b'}
result: '{{ data is community.general.ansible_type(dtype, alias) }}' result: '{{ data is community.general.ansible_type(dtype, alias) }}'
# result => true # result => true
---
# Dictionary. All keys are strings. Multiple types values. # Dictionary. All keys are strings. Multiple types values.
alias: alias:
AnsibleUnicode: str AnsibleUnicode: str
@ -135,10 +149,11 @@ alias:
_AnsibleTaggedInt: int _AnsibleTaggedInt: int
_AnsibleTaggedFloat: float _AnsibleTaggedFloat: float
dtype: dict[str, bool|dict|float|int|list|str] 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: '{{ data is community.general.ansible_type(dtype, alias) }}'
# result => true # result => true
---
# List. Multiple types items. # List. Multiple types items.
alias: alias:
AnsibleUnicode: str AnsibleUnicode: str
@ -146,25 +161,28 @@ alias:
_AnsibleTaggedInt: int _AnsibleTaggedInt: int
_AnsibleTaggedFloat: float _AnsibleTaggedFloat: float
dtype: list[bool|dict|float|int|list|str] 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: '{{ data is community.general.ansible_type(dtype, alias) }}'
# result => true # result => true
# Option dtype is list # Option dtype is list
# -------------------- # --------------------
---
# AnsibleUnicode, _AnsibleTaggedStr, or str # AnsibleUnicode, _AnsibleTaggedStr, or str
dtype: ['AnsibleUnicode', '_AnsibleTaggedStr', 'str'] dtype: ['AnsibleUnicode', '_AnsibleTaggedStr', 'str']
data: abc data: abc
result: '{{ data is community.general.ansible_type(dtype) }}' result: '{{ data is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# float or int # float or int
dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"] dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"]
data: 123 data: 123
result: '{{ data is community.general.ansible_type(dtype) }}' result: '{{ data is community.general.ansible_type(dtype) }}'
# result => true # result => true
---
# float or int # float or int
dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"] dtype: ['float', 'int', "_AnsibleTaggedInt", "_AnsibleTaggedFloat"]
data: 123.45 data: 123.45
@ -174,23 +192,25 @@ result: '{{ data is community.general.ansible_type(dtype) }}'
# Multiple alias # Multiple alias
# -------------- # --------------
---
# int alias number # int alias number
alias: alias:
int: number int: number
float: number float: number
_AnsibleTaggedInt: number _AnsibleTaggedInt: number
_AnsibleTaggedFloat: float _AnsibleTaggedFloat: float
dtype: number dtype: number
data: 123 data: 123
result: '{{ data is community.general.ansible_type(dtype, alias) }}' result: '{{ data is community.general.ansible_type(dtype, alias) }}'
# result => true # result => true
---
# float alias number # float alias number
alias: alias:
int: number int: number
float: number float: number
_AnsibleTaggedInt: number _AnsibleTaggedInt: number
_AnsibleTaggedFloat: float _AnsibleTaggedFloat: float
dtype: number dtype: number
data: 123.45 data: 123.45
result: '{{ data is community.general.ansible_type(dtype, alias) }}' result: '{{ data is community.general.ansible_type(dtype, alias) }}'
@ -198,9 +218,9 @@ result: '{{ data is community.general.ansible_type(dtype, alias) }}'
''' '''
RETURN = ''' RETURN = '''
_value: _value:
description: Whether the data type is valid. description: Whether the data type is valid.
type: bool type: bool
''' '''
from ansible.errors import AnsibleFilterError from ansible.errors import AnsibleFilterError

74
plugins/test/fqdn_valid.py
View file

@ -17,41 +17,41 @@ else:
DOCUMENTATION = ''' DOCUMENTATION = '''
name: fqdn_valid name: fqdn_valid
short_description: Validates fully-qualified domain names against RFC 1123 short_description: Validates fully-qualified domain names against RFC 1123
version_added: 8.1.0 version_added: 8.1.0
author: Vladimir Botka (@vbotka) author: Vladimir Botka (@vbotka)
requirements: requirements:
- fqdn>=1.5.1 (PyPI) - fqdn>=1.5.1 (PyPI)
description: description:
- This test validates Fully Qualified Domain Names (FQDNs) - This test validates Fully Qualified Domain Names (FQDNs)
conforming to the Internet Engineering Task Force specification conforming to the Internet Engineering Task Force specification
RFC 1123 and RFC 952. RFC 1123 and RFC 952.
- The design intent is to validate that a string would be - The design intent is to validate that a string would be
traditionally acceptable as a public Internet hostname to traditionally acceptable as a public Internet hostname to
RFC-conforming software, which is a strict subset of the logic RFC-conforming software, which is a strict subset of the logic
in modern web browsers like Mozilla Firefox and Chromium that in modern web browsers like Mozilla Firefox and Chromium that
determines whether make a DNS lookup. determines whether make a DNS lookup.
- Certificate Authorities like Let's Encrypt run a narrower set of - Certificate Authorities like Let's Encrypt run a narrower set of
string validation logic to determine validity for issuance. This string validation logic to determine validity for issuance. This
test is not intended to achieve functional parity with CA test is not intended to achieve functional parity with CA
issuance. issuance.
- Single label names are allowed by default (O(min_labels=1)). - Single label names are allowed by default (O(min_labels=1)).
options: options:
_input: _input:
description: Name of the host. description: Name of the host.
type: str type: str
required: true required: true
min_labels: min_labels:
description: Required minimum of labels, separated by period. description: Required minimum of labels, separated by period.
default: 1 default: 1
type: int type: int
required: false required: false
allow_underscores: allow_underscores:
description: Allow underscore characters. description: Allow underscore characters.
default: false default: false
type: bool type: bool
required: false required: false
''' '''
EXAMPLES = ''' EXAMPLES = '''
@ -69,9 +69,9 @@ EXAMPLES = '''
''' '''
RETURN = ''' RETURN = '''
_value: _value:
description: Whether the name is valid. description: Whether the name is valid.
type: bool type: bool
''' '''

1
tests/sanity/ignore-2.15.txt
View file

@ -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/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.11 # Uses deprecated stdlib library 'crypt'
plugins/modules/xfconf.py validate-modules:return-syntax-error 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 tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes

1
tests/sanity/ignore-2.16.txt
View file

@ -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.11 # Uses deprecated stdlib library 'crypt'
plugins/modules/udm_user.py import-3.12 # 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/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 tests/unit/plugins/modules/test_gio_mime.yaml no-smart-quotes