ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-09-30 21:43:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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
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

228
plugins/inventory/cobbler.py
View file

@ -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

100
plugins/inventory/gitlab_runners.py
View file

@ -7,56 +7,56 @@
from __future__ import annotations
DOCUMENTATION = '''
name: gitlab_runners
author:
- Stefan Heitmüller (@morph027) <stefan.heitmueller@gmx.com>
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) <stefan.heitmueller@gmx.com>
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

128
plugins/inventory/icinga2.py
View file

@ -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) <cliff.hults@gmail.com>
DOCUMENTATION = r"""
name: icinga2
short_description: Icinga2 inventory source
version_added: 3.7.0
author:
- 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:
- 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

8
plugins/inventory/iocage.py
View file

@ -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/<name>/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

146
plugins/inventory/linode.py
View file

@ -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

202
plugins/inventory/lxd.py
View file

@ -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 <some random 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 <some random 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

192
plugins/inventory/nmap.py
View file

@ -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

86
plugins/inventory/online.py
View file

@ -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

140
plugins/inventory/opennebula.py
View file

@ -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

132
plugins/inventory/scaleway.py
View file

@ -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

98
plugins/inventory/virtualbox.py
View file

@ -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