From 4a9ddde387ea3266c48c2263178860e07f5f1640 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Mon, 6 Jan 2025 21:34:49 +1300 Subject: [PATCH 1/4] plugins (become, callback, filter, inventory): style adjustments --- plugins/become/pfexec.py | 4 +- plugins/callback/default_without_diff.py | 2 +- plugins/callback/yaml.py | 3 +- plugins/filter/accumulate.py | 53 +-- plugins/filter/counter.py | 43 +-- plugins/filter/crc32.py | 50 +-- plugins/filter/dict.py | 42 +-- plugins/filter/dict_kv.py | 52 +-- plugins/filter/from_csv.py | 106 +++--- plugins/filter/from_ini.py | 74 ++-- plugins/filter/groupby_as_dict.py | 56 +-- plugins/filter/jc.py | 82 ++--- plugins/filter/json_query.py | 58 ++-- plugins/filter/keep_keys.py | 112 +++--- plugins/filter/lists_mergeby.py | 128 ++++--- plugins/filter/random_mac.py | 50 +-- plugins/filter/remove_keys.py | 130 +++---- plugins/filter/replace_keys.py | 142 ++++---- plugins/filter/reveal_ansible_type.py | 106 +++--- plugins/filter/to_ini.py | 68 ++-- plugins/filter/unicode_normalize.py | 66 ++-- plugins/filter/version_sort.py | 48 +-- plugins/inventory/cobbler.py | 208 +++++------ plugins/inventory/gitlab_runners.py | 139 ++++---- plugins/inventory/icinga2.py | 129 ++++--- plugins/inventory/iocage.py | 201 ++++++----- plugins/inventory/linode.py | 234 +++++++------ plugins/inventory/lxd.py | 318 ++++++++--------- plugins/inventory/nmap.py | 223 ++++++------ plugins/inventory/online.py | 86 ++--- plugins/inventory/opennebula.py | 140 ++++---- plugins/inventory/proxmox.py | 424 ++++++++++++----------- plugins/inventory/scaleway.py | 196 +++++------ plugins/inventory/stackpath_compute.py | 90 +++-- plugins/inventory/virtualbox.py | 113 +++--- plugins/inventory/xen_orchestra.py | 121 +++---- 36 files changed, 2059 insertions(+), 2038 deletions(-) diff --git a/plugins/become/pfexec.py b/plugins/become/pfexec.py index 62d22bdb61c..b23509281cc 100644 --- a/plugins/become/pfexec.py +++ b/plugins/become/pfexec.py @@ -15,8 +15,8 @@ become_user: description: - User you 'become' to execute the task. - - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here - for Ansible to make decisions needed for the task execution, like file permissions. + - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here for + Ansible to make decisions needed for the task execution, like file permissions. type: string default: root ini: diff --git a/plugins/callback/default_without_diff.py b/plugins/callback/default_without_diff.py index 8f300d8e4f2..b6ef75ce91d 100644 --- a/plugins/callback/default_without_diff.py +++ b/plugins/callback/default_without_diff.py @@ -29,7 +29,7 @@ stdout_callback = community.general.default_without_diff # Enable callback with environment variables: -environment_variable: | +environment_variable: |- ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff """ diff --git a/plugins/callback/yaml.py b/plugins/callback/yaml.py index 0484f80a34b..a68c590cf75 100644 --- a/plugins/callback/yaml.py +++ b/plugins/callback/yaml.py @@ -14,7 +14,8 @@ short_description: YAML-ized Ansible screen output deprecated: removed_in: 13.0.0 - why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in YAML format. + why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in + YAML format. alternative: Use O(ansible.builtin.default#callback:result_format=yaml). description: - Ansible output that can be quite a bit easier to read than the default JSON formatting. diff --git a/plugins/filter/accumulate.py b/plugins/filter/accumulate.py index 9400936e1d4..c48afa04672 100644 --- a/plugins/filter/accumulate.py +++ b/plugins/filter/accumulate.py @@ -2,43 +2,44 @@ # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) # SPDX-License-Identifier: GPL-3.0-or-later -DOCUMENTATION = ''' - name: accumulate - short_description: Produce a list of accumulated sums of the input list contents - version_added: 10.1.0 - author: Max Gautier (@VannTen) - description: - - Passthrough to the L(Python itertools.accumulate function,https://docs.python.org/3/library/itertools.html#itertools.accumulate). - - Transforms an input list into the cumulative list of results from applying addition to the elements of the input list. - - Addition means the default Python implementation of C(+) for input list elements type. - options: - _input: - description: A list. - type: list - elements: any - required: true -''' - -RETURN = ''' - _value: - description: A list of cumulated sums of the elements of the input list. +DOCUMENTATION = r""" +name: accumulate +short_description: Produce a list of accumulated sums of the input list contents +version_added: 10.1.0 +author: Max Gautier (@VannTen) +description: + - Passthrough to the L(Python itertools.accumulate function,https://docs.python.org/3/library/itertools.html#itertools.accumulate). + - Transforms an input list into the cumulative list of results from applying addition to the elements of the input list. + - Addition means the default Python implementation of C(+) for input list elements type. +options: + _input: + description: A list. type: list elements: any -''' + required: true +""" -EXAMPLES = ''' +RETURN = r""" +_value: + description: A list of cumulated sums of the elements of the input list. + type: list + elements: any +""" + +EXAMPLES = r""" - name: Enumerate parent directories of some path ansible.builtin.debug: var: > - "/some/path/to/my/file" - | split('/') | map('split', '/') - | community.general.accumulate | map('join', '/') + "/some/path/to/my/file" + | split('/') | map('split', '/') + | community.general.accumulate | map('join', '/') # Produces: ['', '/some', '/some/path', '/some/path/to', '/some/path/to/my', '/some/path/to/my/file'] + - name: Growing string ansible.builtin.debug: var: "'abc' | community.general.accumulate" # Produces ['a', 'ab', 'abc'] -''' +""" from itertools import accumulate from collections.abc import Sequence diff --git a/plugins/filter/counter.py b/plugins/filter/counter.py index 1b79294b59f..93ffa64d018 100644 --- a/plugins/filter/counter.py +++ b/plugins/filter/counter.py @@ -6,34 +6,35 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: counter - short_description: Counts hashable elements in a sequence - version_added: 4.3.0 - author: Rémy Keil (@keilr) - description: - - Counts hashable elements in a sequence. - options: - _input: - description: A sequence. - type: list - elements: any - required: true -''' +DOCUMENTATION = r""" +name: counter +short_description: Counts hashable elements in a sequence +version_added: 4.3.0 +author: Rémy Keil (@keilr) +description: + - Counts hashable elements in a sequence. +options: + _input: + description: A sequence. + type: list + elements: any + required: true +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Count occurrences ansible.builtin.debug: msg: >- {{ [1, 'a', 2, 2, 'a', 'b', 'a'] | community.general.counter }} # Produces: {1: 1, 'a': 3, 2: 2, 'b': 1} -''' +""" -RETURN = ''' - _value: - description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as values. - type: dictionary -''' +RETURN = r""" +_value: + description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as + values. + type: dictionary +""" from ansible.errors import AnsibleFilterError from ansible.module_utils.common._collections_compat import Sequence diff --git a/plugins/filter/crc32.py b/plugins/filter/crc32.py index 1f0aa2e9b03..bdf6d51614a 100644 --- a/plugins/filter/crc32.py +++ b/plugins/filter/crc32.py @@ -16,33 +16,33 @@ HAS_ZLIB = False -DOCUMENTATION = ''' - name: crc32 - short_description: Generate a CRC32 checksum - version_added: 5.4.0 - description: - - Checksum a string using CRC32 algorithm and return its hexadecimal representation. - options: - _input: - description: - - The string to checksum. - type: string - required: true - author: - - Julien Riou -''' +DOCUMENTATION = r""" +name: crc32 +short_description: Generate a CRC32 checksum +version_added: 5.4.0 +description: + - Checksum a string using CRC32 algorithm and return its hexadecimal representation. +options: + _input: + description: + - The string to checksum. + type: string + required: true +author: + - Julien Riou +""" -EXAMPLES = ''' - - name: Checksum a test string - ansible.builtin.debug: - msg: "{{ 'test' | community.general.crc32 }}" -''' +EXAMPLES = r""" +- name: Checksum a test string + ansible.builtin.debug: + msg: "{{ 'test' | community.general.crc32 }}" +""" -RETURN = ''' - _value: - description: CRC32 checksum. - type: string -''' +RETURN = r""" +_value: + description: CRC32 checksum. + type: string +""" def crc32s(value): diff --git a/plugins/filter/dict.py b/plugins/filter/dict.py index 3e0558bb616..b3e81bd4ab7 100644 --- a/plugins/filter/dict.py +++ b/plugins/filter/dict.py @@ -7,22 +7,22 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - name: dict - short_description: Convert a list of tuples into a dictionary - version_added: 3.0.0 - author: Felix Fontein (@felixfontein) - description: - - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function. - options: - _input: - description: A list of tuples (with exactly two elements). - type: list - elements: tuple - required: true -''' +DOCUMENTATION = r""" +name: dict +short_description: Convert a list of tuples into a dictionary +version_added: 3.0.0 +author: Felix Fontein (@felixfontein) +description: + - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function. +options: + _input: + description: A list of tuples (with exactly two elements). + type: list + elements: tuple + required: true +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Convert list of tuples into dictionary ansible.builtin.set_fact: dictionary: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}" @@ -53,13 +53,13 @@ # "k2": 42, # "k3": "b" # } -''' +""" -RETURN = ''' - _value: - description: A dictionary with the provided key-value pairs. - type: dictionary -''' +RETURN = r""" +_value: + description: A dictionary with the provided key-value pairs. + type: dictionary +""" def dict_filter(sequence): diff --git a/plugins/filter/dict_kv.py b/plugins/filter/dict_kv.py index 59595f95737..8c4fb017525 100644 --- a/plugins/filter/dict_kv.py +++ b/plugins/filter/dict_kv.py @@ -6,37 +6,37 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: dict_kv - short_description: Convert a value to a dictionary with a single key-value pair - version_added: 1.3.0 - author: Stanislav German-Evtushenko (@giner) - description: - - Convert a value to a dictionary with a single key-value pair. - positional: key - options: - _input: - description: The value for the single key-value pair. - type: any - required: true - key: - description: The key for the single key-value pair. - type: any - required: true -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: dict_kv +short_description: Convert a value to a dictionary with a single key-value pair +version_added: 1.3.0 +author: Stanislav German-Evtushenko (@giner) +description: + - Convert a value to a dictionary with a single key-value pair. +positional: key +options: + _input: + description: The value for the single key-value pair. + type: any + required: true + key: + description: The key for the single key-value pair. + type: any + required: true +""" + +EXAMPLES = r""" - name: Create a one-element dictionary from a value ansible.builtin.debug: msg: "{{ 'myvalue' | dict_kv('mykey') }}" # Produces the dictionary {'mykey': 'myvalue'} -''' +""" -RETURN = ''' - _value: - description: A dictionary with a single key-value pair. - type: dictionary -''' +RETURN = r""" +_value: + description: A dictionary with a single key-value pair. + type: dictionary +""" def dict_kv(value, key): diff --git a/plugins/filter/from_csv.py b/plugins/filter/from_csv.py index 617f3147945..3a05769365d 100644 --- a/plugins/filter/from_csv.py +++ b/plugins/filter/from_csv.py @@ -8,51 +8,51 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - name: from_csv - short_description: Converts CSV text input into list of dicts - version_added: 2.3.0 - author: Andrew Pantuso (@Ajpantuso) - description: - - Converts CSV text input into list of dictionaries. - options: - _input: - description: A string containing a CSV document. - type: string - required: true - dialect: - description: - - The CSV dialect to use when parsing the CSV file. - - Possible values include V(excel), V(excel-tab) or V(unix). - type: str - default: excel - fieldnames: - description: - - A list of field names for every column. - - This is needed if the CSV does not have a header. - type: list - elements: str - delimiter: - description: - - A one-character string used to separate fields. - - When using this parameter, you change the default value used by O(dialect). - - The default value depends on the dialect used. - type: str - skipinitialspace: - description: - - Whether to ignore any whitespaces immediately following the delimiter. - - When using this parameter, you change the default value used by O(dialect). - - The default value depends on the dialect used. - type: bool - strict: - description: - - Whether to raise an exception on bad CSV input. - - When using this parameter, you change the default value used by O(dialect). - - The default value depends on the dialect used. - type: bool -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: from_csv +short_description: Converts CSV text input into list of dicts +version_added: 2.3.0 +author: Andrew Pantuso (@Ajpantuso) +description: + - Converts CSV text input into list of dictionaries. +options: + _input: + description: A string containing a CSV document. + type: string + required: true + dialect: + description: + - The CSV dialect to use when parsing the CSV file. + - Possible values include V(excel), V(excel-tab) or V(unix). + type: str + default: excel + fieldnames: + description: + - A list of field names for every column. + - This is needed if the CSV does not have a header. + type: list + elements: str + delimiter: + description: + - A one-character string used to separate fields. + - When using this parameter, you change the default value used by O(dialect). + - The default value depends on the dialect used. + type: str + skipinitialspace: + description: + - Whether to ignore any whitespaces immediately following the delimiter. + - When using this parameter, you change the default value used by O(dialect). + - The default value depends on the dialect used. + type: bool + strict: + description: + - Whether to raise an exception on bad CSV input. + - When using this parameter, you change the default value used by O(dialect). + - The default value depends on the dialect used. + type: bool +""" + +EXAMPLES = r""" - name: Parse a CSV file's contents ansible.builtin.debug: msg: >- @@ -71,14 +71,14 @@ # "Column 1": "bar", # "Value": "42", # } -''' - -RETURN = ''' - _value: - description: A list with one dictionary per row. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: A list with one dictionary per row. + type: list + elements: dictionary +""" from ansible.errors import AnsibleFilterError diff --git a/plugins/filter/from_ini.py b/plugins/filter/from_ini.py index 5b4bd4a3af4..01ae150d087 100644 --- a/plugins/filter/from_ini.py +++ b/plugins/filter/from_ini.py @@ -6,43 +6,43 @@ from __future__ import absolute_import, division, print_function -DOCUMENTATION = r''' - name: from_ini - short_description: Converts INI text input into a dictionary - version_added: 8.2.0 - author: Steffen Scheib (@sscheib) - description: - - Converts INI text input into a dictionary. - options: - _input: - description: A string containing an INI document. - type: string - required: true -''' - -EXAMPLES = r''' - - name: Slurp an INI file - ansible.builtin.slurp: - src: /etc/rhsm/rhsm.conf - register: rhsm_conf - - - name: Display the INI file as dictionary - ansible.builtin.debug: - var: rhsm_conf.content | b64decode | community.general.from_ini - - - name: Set a new dictionary fact with the contents of the INI file - ansible.builtin.set_fact: - rhsm_dict: >- - {{ - rhsm_conf.content | b64decode | community.general.from_ini - }} -''' - -RETURN = ''' - _value: - description: A dictionary representing the INI file. - type: dictionary -''' +DOCUMENTATION = r""" +name: from_ini +short_description: Converts INI text input into a dictionary +version_added: 8.2.0 +author: Steffen Scheib (@sscheib) +description: + - Converts INI text input into a dictionary. +options: + _input: + description: A string containing an INI document. + type: string + required: true +""" + +EXAMPLES = r""" +- name: Slurp an INI file + ansible.builtin.slurp: + src: /etc/rhsm/rhsm.conf + register: rhsm_conf + +- name: Display the INI file as dictionary + ansible.builtin.debug: + var: rhsm_conf.content | b64decode | community.general.from_ini + +- name: Set a new dictionary fact with the contents of the INI file + ansible.builtin.set_fact: + rhsm_dict: >- + {{ + rhsm_conf.content | b64decode | community.general.from_ini + }} +""" + +RETURN = r""" +_value: + description: A dictionary representing the INI file. + type: dictionary +""" __metaclass__ = type diff --git a/plugins/filter/groupby_as_dict.py b/plugins/filter/groupby_as_dict.py index 8e29c5863c0..80c7ad7885d 100644 --- a/plugins/filter/groupby_as_dict.py +++ b/plugins/filter/groupby_as_dict.py @@ -6,29 +6,29 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: groupby_as_dict - short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute - version_added: 3.1.0 - author: Felix Fontein (@felixfontein) - description: - - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute. - - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries with the same value, - or when you need a dictionary with list values, or when you need to use deeply nested attributes. - positional: attribute - options: - _input: - description: A list of dictionaries - type: list - elements: dictionary - required: true - attribute: - description: The attribute to use as the key. - type: str - required: true -''' +DOCUMENTATION = r""" +name: groupby_as_dict +short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute +version_added: 3.1.0 +author: Felix Fontein (@felixfontein) +description: + - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute. + - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries + with the same value, or when you need a dictionary with list values, or when you need to use deeply nested attributes. +positional: attribute +options: + _input: + description: A list of dictionaries. + type: list + elements: dictionary + required: true + attribute: + description: The attribute to use as the key. + type: str + required: true +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Arrange a list of dictionaries as a dictionary of dictionaries ansible.builtin.debug: msg: "{{ sequence | community.general.groupby_as_dict('key') }}" @@ -46,13 +46,13 @@ # other_value: # key: other_value # baz: bar -''' +""" -RETURN = ''' - _value: - description: A dictionary containing the dictionaries from the list as values. - type: dictionary -''' +RETURN = r""" +_value: + description: A dictionary containing the dictionaries from the list as values. + type: dictionary +""" from ansible.errors import AnsibleFilterError from ansible.module_utils.common._collections_compat import Mapping, Sequence diff --git a/plugins/filter/jc.py b/plugins/filter/jc.py index 2fe3ef9d734..388fcf0d3fb 100644 --- a/plugins/filter/jc.py +++ b/plugins/filter/jc.py @@ -8,41 +8,41 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: jc - short_description: Convert output of many shell commands and file-types to JSON - version_added: 1.1.0 - author: Kelly Brazil (@kellyjonbrazil) - description: - - Convert output of many shell commands and file-types to JSON. - - Uses the L(jc library,https://github.com/kellyjonbrazil/jc). - positional: parser - options: - _input: - description: The data to convert. - type: string - required: true - parser: - description: - - The correct parser for the input data. - - For example V(ifconfig). - - "Note: use underscores instead of dashes (if any) in the parser module name." - - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers. - type: string - required: true - quiet: - description: Set to V(false) to not suppress warnings. - type: boolean - default: true - raw: - description: Set to V(true) to return pre-processed JSON. - type: boolean - default: false - requirements: - - jc installed as a Python library (U(https://pypi.org/project/jc/)) -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: jc +short_description: Convert output of many shell commands and file-types to JSON +version_added: 1.1.0 +author: Kelly Brazil (@kellyjonbrazil) +description: + - Convert output of many shell commands and file-types to JSON. + - Uses the L(jc library,https://github.com/kellyjonbrazil/jc). +positional: parser +options: + _input: + description: The data to convert. + type: string + required: true + parser: + description: + - The correct parser for the input data. + - For example V(ifconfig). + - 'Note: use underscores instead of dashes (if any) in the parser module name.' + - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers. + type: string + required: true + quiet: + description: Set to V(false) to not suppress warnings. + type: boolean + default: true + raw: + description: Set to V(true) to return pre-processed JSON. + type: boolean + default: false +requirements: + - jc installed as a Python library (U(https://pypi.org/project/jc/)) +""" + +EXAMPLES = r""" - name: Install the prereqs of the jc filter (jc Python package) on the Ansible controller delegate_to: localhost ansible.builtin.pip: @@ -68,13 +68,13 @@ # "operating_system": "GNU/Linux", # "processor": "x86_64" # } -''' +""" -RETURN = ''' - _value: - description: The processed output. - type: any -''' +RETURN = r""" +_value: + description: The processed output. + type: any +""" from ansible.errors import AnsibleError, AnsibleFilterError import importlib diff --git a/plugins/filter/json_query.py b/plugins/filter/json_query.py index 9e8fa4ef2e7..61223b07026 100644 --- a/plugins/filter/json_query.py +++ b/plugins/filter/json_query.py @@ -6,29 +6,29 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: json_query - short_description: Select a single element or a data subset from a complex data structure - description: - - This filter lets you query a complex JSON structure and iterate over it using a loop structure. - positional: expr - options: - _input: - description: - - The JSON data to query. - type: any - required: true - expr: - description: - - The query expression. - - See U(http://jmespath.org/examples.html) for examples. - type: string - required: true - requirements: - - jmespath -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: json_query +short_description: Select a single element or a data subset from a complex data structure +description: + - This filter lets you query a complex JSON structure and iterate over it using a loop structure. +positional: expr +options: + _input: + description: + - The JSON data to query. + type: any + required: true + expr: + description: + - The query expression. + - See U(http://jmespath.org/examples.html) for examples. + type: string + required: true +requirements: + - jmespath +""" + +EXAMPLES = r""" - name: Define data to work on in the examples below ansible.builtin.set_fact: domain_definition: @@ -99,13 +99,13 @@ msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}" vars: server_name_query: "domain.server[?contains(name,'server1')].port" -''' +""" -RETURN = ''' - _value: - description: The result of the query. - type: any -''' +RETURN = r""" +_value: + description: The result of the query. + type: any +""" from ansible.errors import AnsibleError, AnsibleFilterError diff --git a/plugins/filter/keep_keys.py b/plugins/filter/keep_keys.py index 97b706a9506..4cff4405fc0 100644 --- a/plugins/filter/keep_keys.py +++ b/plugins/filter/keep_keys.py @@ -7,99 +7,99 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: keep_keys - short_description: Keep specific keys from dictionaries in a list - version_added: "9.1.0" - author: - - Vladimir Botka (@vbotka) - - Felix Fontein (@felixfontein) - description: This filter keeps only specified keys from a provided list of dictionaries. - options: - _input: - description: - - A list of dictionaries. - - Top level keys must be strings. - type: list - elements: dictionary - required: true - target: - description: - - A single key or key pattern to keep, or a list of keys or keys patterns to keep. - - If O(matching_parameter=regex) there must be exactly one pattern provided. - type: raw - required: true - matching_parameter: - description: Specify the matching option of target keys. - type: str - default: equal - choices: - equal: Matches keys of exactly one of the O(target) items. - starts_with: Matches keys that start with one of the O(target) items. - ends_with: Matches keys that end with one of the O(target) items. - regex: - - Matches keys that match the regular expresion provided in O(target). - - In this case, O(target) must be a regex string or a list with single regex string. -''' - -EXAMPLES = ''' - l: +DOCUMENTATION = r""" +name: keep_keys +short_description: Keep specific keys from dictionaries in a list +version_added: "9.1.0" +author: + - Vladimir Botka (@vbotka) + - Felix Fontein (@felixfontein) +description: This filter keeps only specified keys from a provided list of dictionaries. +options: + _input: + description: + - A list of dictionaries. + - Top level keys must be strings. + type: list + elements: dictionary + required: true + target: + description: + - A single key or key pattern to keep, or a list of keys or keys patterns to keep. + - If O(matching_parameter=regex) there must be exactly one pattern provided. + type: raw + required: true + matching_parameter: + description: Specify the matching option of target keys. + type: str + default: equal + choices: + equal: Matches keys of exactly one of the O(target) items. + starts_with: Matches keys that start with one of the O(target) items. + ends_with: Matches keys that end with one of the O(target) items. + regex: + - Matches keys that match the regular expresion provided in O(target). + - In this case, O(target) must be a regex string or a list with single regex string. +""" + +EXAMPLES = r""" +- l: - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} # 1) By default match keys that equal any of the items in the target. - t: [k0_x0, k1_x1] +- t: [k0_x0, k1_x1] r: "{{ l | community.general.keep_keys(target=t) }}" # 2) Match keys that start with any of the items in the target. - t: [k0, k1] +- t: [k0, k1] r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}" # 3) Match keys that end with any of the items in target. - t: [x0, x1] +- t: [x0, x1] r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}" # 4) Match keys by the regex. - t: ['^.*[01]_x.*$'] +- t: ['^.*[01]_x.*$'] r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}" # 5) Match keys by the regex. - t: '^.*[01]_x.*$' +- t: '^.*[01]_x.*$' r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}" # The results of above examples 1-5 are all the same. - r: +- r: - {k0_x0: A0, k1_x1: B0} - {k0_x0: A1, k1_x1: B1} # 6) By default match keys that equal the target. - t: k0_x0 +- t: k0_x0 r: "{{ l | community.general.keep_keys(target=t) }}" # 7) Match keys that start with the target. - t: k0 +- t: k0 r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}" # 8) Match keys that end with the target. - t: x0 +- t: x0 r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}" # 9) Match keys by the regex. - t: '^.*0_x.*$' +- t: '^.*0_x.*$' r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}" # The results of above examples 6-9 are all the same. - r: +- r: - {k0_x0: A0} - {k0_x0: A1} -''' - -RETURN = ''' - _value: - description: The list of dictionaries with selected keys. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: The list of dictionaries with selected keys. + type: list + elements: dictionary +""" from ansible_collections.community.general.plugins.plugin_utils.keys_filter import ( _keys_filter_params, diff --git a/plugins/filter/lists_mergeby.py b/plugins/filter/lists_mergeby.py index 0e47d50172d..b34246993ca 100644 --- a/plugins/filter/lists_mergeby.py +++ b/plugins/filter/lists_mergeby.py @@ -6,65 +6,59 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: lists_mergeby - short_description: Merge two or more lists of dictionaries by a given attribute - version_added: 2.0.0 - author: Vladimir Botka (@vbotka) - description: - - Merge two or more lists by attribute O(index). Optional - parameters O(recursive) and O(list_merge) control the merging of - the nested dictionaries and lists. - - The function C(merge_hash) from C(ansible.utils.vars) is used. - - To learn details on how to use the parameters O(recursive) and - O(list_merge) see Ansible User's Guide chapter "Using filters to - manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the - filter P(ansible.builtin.combine#filter). - - positional: another_list, index - options: - _input: - description: - - A list of dictionaries, or a list of lists of dictionaries. - - The required type of the C(elements) is set to C(raw) - because all elements of O(_input) can be either dictionaries - or lists. - type: list - elements: raw - required: true - another_list: - description: - - Another list of dictionaries, or a list of lists of dictionaries. - - This parameter can be specified multiple times. - type: list - elements: raw - index: - description: - - The dictionary key that must be present in every dictionary in every list that is used to - merge the lists. - type: string - required: true - recursive: - description: - - Should the combine recursively merge nested dictionaries (hashes). - - "B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg)." - type: boolean - default: false - list_merge: - description: - - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists. - type: string - default: replace - choices: - - replace - - keep - - append - - prepend - - append_rp - - prepend_rp -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: lists_mergeby +short_description: Merge two or more lists of dictionaries by a given attribute +version_added: 2.0.0 +author: Vladimir Botka (@vbotka) +description: + - Merge two or more lists by attribute O(index). Optional parameters O(recursive) and O(list_merge) control the merging + of the nested dictionaries and lists. + - The function C(merge_hash) from C(ansible.utils.vars) is used. + - To learn details on how to use the parameters O(recursive) and O(list_merge) see Ansible User's Guide chapter "Using filters + to manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the filter P(ansible.builtin.combine#filter). +positional: another_list, index +options: + _input: + description: + - A list of dictionaries, or a list of lists of dictionaries. + - The required type of the C(elements) is set to C(raw) because all elements of O(_input) can be either dictionaries + or lists. + type: list + elements: raw + required: true + another_list: + description: + - Another list of dictionaries, or a list of lists of dictionaries. + - This parameter can be specified multiple times. + type: list + elements: raw + index: + description: + - The dictionary key that must be present in every dictionary in every list that is used to merge the lists. + type: string + required: true + recursive: + description: + - Should the combine recursively merge nested dictionaries (hashes). + - B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg). + type: boolean + default: false + list_merge: + description: + - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists. + type: string + default: replace + choices: + - replace + - keep + - append + - prepend + - append_rp + - prepend_rp +""" + +EXAMPLES = r""" # Some results below are manually formatted for better readability. The # dictionaries' keys will be sorted alphabetically in real output. @@ -193,14 +187,14 @@ # r: # - {index: a, foo: {x:1, y: 3, z: 4}} # - {index: b, foo: [Y1, Y2]} -''' - -RETURN = ''' - _value: - description: The merged list. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: The merged list. + type: list + elements: dictionary +""" from ansible.errors import AnsibleFilterError from ansible.module_utils.six import string_types diff --git a/plugins/filter/random_mac.py b/plugins/filter/random_mac.py index 662c62b07cd..49910bc6be1 100644 --- a/plugins/filter/random_mac.py +++ b/plugins/filter/random_mac.py @@ -7,25 +7,25 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: random_mac - short_description: Generate a random MAC address - description: - - Generates random networking interfaces MAC addresses for a given prefix. - options: - _input: - description: A string prefix to use as a basis for the random MAC generated. - type: string - required: true - seed: - description: - - A randomization seed to initialize the process, used to get repeatable results. - - If no seed is provided, a system random source such as C(/dev/urandom) is used. - required: false - type: string -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: random_mac +short_description: Generate a random MAC address +description: + - Generates random networking interfaces MAC addresses for a given prefix. +options: + _input: + description: A string prefix to use as a basis for the random MAC generated. + type: string + required: true + seed: + description: + - A randomization seed to initialize the process, used to get repeatable results. + - If no seed is provided, a system random source such as C(/dev/urandom) is used. + required: false + type: string +""" + +EXAMPLES = r""" - name: Random MAC given a prefix ansible.builtin.debug: msg: "{{ '52:54:00' | community.general.random_mac }}" @@ -34,13 +34,13 @@ - name: With a seed ansible.builtin.debug: msg: "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}" -''' +""" -RETURN = ''' - _value: - description: The generated MAC. - type: string -''' +RETURN = r""" +_value: + description: The generated MAC. + type: string +""" import re from random import Random, SystemRandom diff --git a/plugins/filter/remove_keys.py b/plugins/filter/remove_keys.py index 7a4d912d349..d2e6282ea9f 100644 --- a/plugins/filter/remove_keys.py +++ b/plugins/filter/remove_keys.py @@ -7,99 +7,99 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: remove_keys - short_description: Remove specific keys from dictionaries in a list - version_added: "9.1.0" - author: - - Vladimir Botka (@vbotka) - - Felix Fontein (@felixfontein) - description: This filter removes only specified keys from a provided list of dictionaries. - options: - _input: - description: - - A list of dictionaries. - - Top level keys must be strings. - type: list - elements: dictionary - required: true - target: - description: - - A single key or key pattern to remove, or a list of keys or keys patterns to remove. - - If O(matching_parameter=regex) there must be exactly one pattern provided. - type: raw - required: true - matching_parameter: - description: Specify the matching option of target keys. - type: str - default: equal - choices: - equal: Matches keys of exactly one of the O(target) items. - starts_with: Matches keys that start with one of the O(target) items. - ends_with: Matches keys that end with one of the O(target) items. - regex: - - Matches keys that match the regular expresion provided in O(target). - - In this case, O(target) must be a regex string or a list with single regex string. -''' - -EXAMPLES = ''' - l: +DOCUMENTATION = r""" +name: remove_keys +short_description: Remove specific keys from dictionaries in a list +version_added: "9.1.0" +author: + - Vladimir Botka (@vbotka) + - Felix Fontein (@felixfontein) +description: This filter removes only specified keys from a provided list of dictionaries. +options: + _input: + description: + - A list of dictionaries. + - Top level keys must be strings. + type: list + elements: dictionary + required: true + target: + description: + - A single key or key pattern to remove, or a list of keys or keys patterns to remove. + - If O(matching_parameter=regex) there must be exactly one pattern provided. + type: raw + required: true + matching_parameter: + description: Specify the matching option of target keys. + type: str + default: equal + choices: + equal: Matches keys of exactly one of the O(target) items. + starts_with: Matches keys that start with one of the O(target) items. + ends_with: Matches keys that end with one of the O(target) items. + regex: + - Matches keys that match the regular expresion provided in O(target). + - In this case, O(target) must be a regex string or a list with single regex string. +""" + +EXAMPLES = r""" +- l: - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} # 1) By default match keys that equal any of the items in the target. - t: [k0_x0, k1_x1] - r: "{{ l | community.general.remove_keys(target=t) }}" +- t: [k0_x0, k1_x1] +- r: "{{ l | community.general.remove_keys(target=t) }}" # 2) Match keys that start with any of the items in the target. - t: [k0, k1] - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" +- t: [k0, k1] +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" # 3) Match keys that end with any of the items in target. - t: [x0, x1] - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" +- t: [x0, x1] +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" # 4) Match keys by the regex. - t: ['^.*[01]_x.*$'] - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" +- t: ['^.*[01]_x.*$'] +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" # 5) Match keys by the regex. - t: '^.*[01]_x.*$' - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" +- t: '^.*[01]_x.*$' +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" # The results of above examples 1-5 are all the same. - r: +- r: - {k2_x2: [C0], k3_x3: foo} - {k2_x2: [C1], k3_x3: bar} # 6) By default match keys that equal the target. - t: k0_x0 - r: "{{ l | community.general.remove_keys(target=t) }}" +- t: k0_x0 +- r: "{{ l | community.general.remove_keys(target=t) }}" # 7) Match keys that start with the target. - t: k0 - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" +- t: k0 +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" # 8) Match keys that end with the target. - t: x0 - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" +- t: x0 +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" # 9) Match keys by the regex. - t: '^.*0_x.*$' - r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" +- t: '^.*0_x.*$' +- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" # The results of above examples 6-9 are all the same. - r: +- r: - {k1_x1: B0, k2_x2: [C0], k3_x3: foo} - {k1_x1: B1, k2_x2: [C1], k3_x3: bar} -''' - -RETURN = ''' - _value: - description: The list of dictionaries with selected keys removed. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: The list of dictionaries with selected keys removed. + type: list + elements: dictionary +""" from ansible_collections.community.general.plugins.plugin_utils.keys_filter import ( _keys_filter_params, diff --git a/plugins/filter/replace_keys.py b/plugins/filter/replace_keys.py index 70b264eba6a..d314c1fc234 100644 --- a/plugins/filter/replace_keys.py +++ b/plugins/filter/replace_keys.py @@ -7,129 +7,129 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: replace_keys - short_description: Replace specific keys in a list of dictionaries - version_added: "9.1.0" - author: - - Vladimir Botka (@vbotka) - - Felix Fontein (@felixfontein) - description: This filter replaces specified keys in a provided list of dictionaries. - options: - _input: - description: - - A list of dictionaries. - - Top level keys must be strings. - type: list - elements: dictionary - required: true - target: +DOCUMENTATION = r""" +name: replace_keys +short_description: Replace specific keys in a list of dictionaries +version_added: "9.1.0" +author: + - Vladimir Botka (@vbotka) + - Felix Fontein (@felixfontein) +description: This filter replaces specified keys in a provided list of dictionaries. +options: + _input: + description: + - A list of dictionaries. + - Top level keys must be strings. + type: list + elements: dictionary + required: true + target: + description: + - A list of dictionaries with attributes C(before) and C(after). + - The value of O(target[].after) replaces key matching O(target[].before). + type: list + elements: dictionary + required: true + suboptions: + before: description: - - A list of dictionaries with attributes C(before) and C(after). - - The value of O(target[].after) replaces key matching O(target[].before). - type: list - elements: dictionary - required: true - suboptions: - before: - description: - - A key or key pattern to change. - - The interpretation of O(target[].before) depends on O(matching_parameter). - - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used. - type: str - after: - description: A matching key change to. - type: str - matching_parameter: - description: Specify the matching option of target keys. + - A key or key pattern to change. + - The interpretation of O(target[].before) depends on O(matching_parameter). + - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used. type: str - default: equal - choices: - equal: Matches keys of exactly one of the O(target[].before) items. - starts_with: Matches keys that start with one of the O(target[].before) items. - ends_with: Matches keys that end with one of the O(target[].before) items. - regex: Matches keys that match one of the regular expressions provided in O(target[].before). -''' - -EXAMPLES = ''' - l: + after: + description: A matching key change to. + type: str + matching_parameter: + description: Specify the matching option of target keys. + type: str + default: equal + choices: + equal: Matches keys of exactly one of the O(target[].before) items. + starts_with: Matches keys that start with one of the O(target[].before) items. + ends_with: Matches keys that end with one of the O(target[].before) items. + regex: Matches keys that match one of the regular expressions provided in O(target[].before). +""" + +EXAMPLES = r""" +- l: - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} # 1) By default, replace keys that are equal any of the attributes before. - t: +- t: - {before: k0_x0, after: a0} - {before: k1_x1, after: a1} - r: "{{ l | community.general.replace_keys(target=t) }}" +- r: "{{ l | community.general.replace_keys(target=t) }}" # 2) Replace keys that starts with any of the attributes before. - t: +- t: - {before: k0, after: a0} - {before: k1, after: a1} - r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" +- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" # 3) Replace keys that ends with any of the attributes before. - t: +- t: - {before: x0, after: a0} - {before: x1, after: a1} - r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}" +- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}" # 4) Replace keys that match any regex of the attributes before. - t: +- t: - {before: "^.*0_x.*$", after: a0} - {before: "^.*1_x.*$", after: a1} - r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" +- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" # The results of above examples 1-4 are all the same. - r: +- r: - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo} - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar} # 5) If more keys match the same attribute before the last one will be used. - t: +- t: - {before: "^.*_x.*$", after: X} - r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" +- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" # gives - r: +- r: - X: foo - X: bar # 6) If there are items with equal attribute before the first one will be used. - t: +- t: - {before: "^.*_x.*$", after: X} - {before: "^.*_x.*$", after: Y} - r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" +- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" # gives - r: +- r: - X: foo - X: bar # 7) If there are more matches for a key the first one will be used. - l: +- l: - {aaa1: A, bbb1: B, ccc1: C} - {aaa2: D, bbb2: E, ccc2: F} - t: +- t: - {before: a, after: X} - {before: aa, after: Y} - r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" +- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" # gives - r: +- r: - {X: A, bbb1: B, ccc1: C} - {X: D, bbb2: E, ccc2: F} -''' - -RETURN = ''' - _value: - description: The list of dictionaries with replaced keys. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: The list of dictionaries with replaced keys. + type: list + elements: dictionary +""" from ansible_collections.community.general.plugins.plugin_utils.keys_filter import ( _keys_filter_params, diff --git a/plugins/filter/reveal_ansible_type.py b/plugins/filter/reveal_ansible_type.py index 916aaff9306..6da13d0e946 100644 --- a/plugins/filter/reveal_ansible_type.py +++ b/plugins/filter/reveal_ansible_type.py @@ -6,116 +6,116 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: reveal_ansible_type - short_description: Return input type - version_added: "9.2.0" - author: Vladimir Botka (@vbotka) - description: This filter returns input type. - options: - _input: - description: Input data. - type: raw - required: true - alias: - description: Data type aliases. - default: {} - type: dictionary -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: reveal_ansible_type +short_description: Return input type +version_added: "9.2.0" +author: Vladimir Botka (@vbotka) +description: This filter returns input type. +options: + _input: + description: Input data. + type: raw + required: true + alias: + description: Data type aliases. + default: {} + type: dictionary +""" + +EXAMPLES = r""" # Substitution converts str to AnsibleUnicode # ------------------------------------------- # String. AnsibleUnicode. -data: "abc" -result: '{{ data | community.general.reveal_ansible_type }}' +- data: "abc" +- result: '{{ data | community.general.reveal_ansible_type }}' # result => AnsibleUnicode # String. AnsibleUnicode alias str. -alias: {"AnsibleUnicode": "str"} -data: "abc" -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} +- data: "abc" +- result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => str # List. All items are AnsibleUnicode. -data: ["a", "b", "c"] -result: '{{ data | community.general.reveal_ansible_type }}' +- data: ["a", "b", "c"] +- result: '{{ data | community.general.reveal_ansible_type }}' # result => list[AnsibleUnicode] # Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode. -data: {"a": "foo", "b": "bar", "c": "baz"} -result: '{{ data | community.general.reveal_ansible_type }}' +- data: {"a": "foo", "b": "bar", "c": "baz"} +- result: '{{ data | community.general.reveal_ansible_type }}' # result => dict[AnsibleUnicode, AnsibleUnicode] # No substitution and no alias. Type of strings is str # ---------------------------------------------------- # String -result: '{{ "abc" | community.general.reveal_ansible_type }}' +- result: '{{ "abc" | community.general.reveal_ansible_type }}' # result => str # Integer -result: '{{ 123 | community.general.reveal_ansible_type }}' +- result: '{{ 123 | community.general.reveal_ansible_type }}' # result => int # Float -result: '{{ 123.45 | community.general.reveal_ansible_type }}' +- result: '{{ 123.45 | community.general.reveal_ansible_type }}' # result => float # Boolean -result: '{{ true | community.general.reveal_ansible_type }}' +- result: '{{ true | community.general.reveal_ansible_type }}' # result => bool # List. All items are strings. -result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}' +- result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}' # result => list[str] # List of dictionaries. -result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}' +- result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}' # result => list[dict] # Dictionary. All keys are strings. All values are integers. -result: '{{ {"a": 1} | community.general.reveal_ansible_type }}' +- result: '{{ {"a": 1} | community.general.reveal_ansible_type }}' # result => dict[str, int] # Dictionary. All keys are strings. All values are integers. -result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}' +- result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}' # result => dict[str, int] # Type of strings is AnsibleUnicode or str # ---------------------------------------- # Dictionary. The keys are integers or strings. All values are strings. -alias: {"AnsibleUnicode": "str"} -data: {1: 'a', 'b': 'b'} -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} +- data: {1: 'a', 'b': 'b'} +- result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[int|str, str] # Dictionary. All keys are integers. All values are keys. -alias: {"AnsibleUnicode": "str"} -data: {1: 'a', 2: 'b'} -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} +- data: {1: 'a', 2: 'b'} +- result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[int, str] # Dictionary. All keys are strings. Multiple types values. -alias: {"AnsibleUnicode": "str"} -data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}} -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} +- data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}} +- result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[str, bool|dict|float|int|list|str] # List. Multiple types items. -alias: {"AnsibleUnicode": "str"} -data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}] -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} +- data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}] +- result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => list[bool|dict|float|int|list|str] -''' +""" -RETURN = ''' - _value: - description: Type of the data. - type: str -''' +RETURN = r""" +_value: + description: Type of the data. + type: str +""" from ansible_collections.community.general.plugins.plugin_utils.ansible_type import _ansible_type diff --git a/plugins/filter/to_ini.py b/plugins/filter/to_ini.py index 2bc41f6962e..f06763ac66c 100644 --- a/plugins/filter/to_ini.py +++ b/plugins/filter/to_ini.py @@ -6,34 +6,34 @@ from __future__ import absolute_import, division, print_function -DOCUMENTATION = r''' - name: to_ini - short_description: Converts a dictionary to the INI file format - version_added: 8.2.0 - author: Steffen Scheib (@sscheib) - description: - - Converts a dictionary to the INI file format. - options: - _input: - description: The dictionary that should be converted to the INI format. - type: dictionary - required: true -''' - -EXAMPLES = r''' - - name: Define a dictionary - ansible.builtin.set_fact: - my_dict: - section_name: - key_name: 'key value' - - another_section: - connection: 'ssh' - - - name: Write dictionary to INI file - ansible.builtin.copy: - dest: /tmp/test.ini - content: '{{ my_dict | community.general.to_ini }}' +DOCUMENTATION = r""" +name: to_ini +short_description: Converts a dictionary to the INI file format +version_added: 8.2.0 +author: Steffen Scheib (@sscheib) +description: + - Converts a dictionary to the INI file format. +options: + _input: + description: The dictionary that should be converted to the INI format. + type: dictionary + required: true +""" + +EXAMPLES = r""" +- name: Define a dictionary + ansible.builtin.set_fact: + my_dict: + section_name: + key_name: 'key value' + + another_section: + connection: 'ssh' + +- name: Write dictionary to INI file + ansible.builtin.copy: + dest: /tmp/test.ini + content: '{{ my_dict | community.general.to_ini }}' # /tmp/test.ini will look like this: # [section_name] @@ -41,13 +41,13 @@ # # [another_section] # connection = ssh -''' +""" -RETURN = r''' - _value: - description: A string formatted as INI file. - type: string -''' +RETURN = r""" +_value: + description: A string formatted as INI file. + type: string +""" __metaclass__ = type diff --git a/plugins/filter/unicode_normalize.py b/plugins/filter/unicode_normalize.py index dfbf20c573a..9401197eba0 100644 --- a/plugins/filter/unicode_normalize.py +++ b/plugins/filter/unicode_normalize.py @@ -7,45 +7,45 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - name: unicode_normalize - short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms - version_added: 3.7.0 - author: Andrew Pantuso (@Ajpantuso) - description: - - Normalizes unicode strings to facilitate comparison of characters with normalized forms. - positional: form - options: - _input: - description: A unicode string. - type: string - required: true - form: - description: - - The normal form to use. - - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details. - type: string - default: NFC - choices: - - NFC - - NFD - - NFKC - - NFKD -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: unicode_normalize +short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms +version_added: 3.7.0 +author: Andrew Pantuso (@Ajpantuso) +description: + - Normalizes unicode strings to facilitate comparison of characters with normalized forms. +positional: form +options: + _input: + description: A unicode string. + type: string + required: true + form: + description: + - The normal form to use. + - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details. + type: string + default: NFC + choices: + - NFC + - NFD + - NFKC + - NFKD +""" + +EXAMPLES = r""" - name: Normalize unicode string ansible.builtin.set_fact: dictionary: "{{ 'ä' | community.general.unicode_normalize('NFKD') }}" # The resulting string has length 2: one letter is 'a', the other # the diacritic combiner. -''' +""" -RETURN = ''' - _value: - description: The normalized unicode string of the specified normal form. - type: string -''' +RETURN = r""" +_value: + description: The normalized unicode string of the specified normal form. + type: string +""" from unicodedata import normalize diff --git a/plugins/filter/version_sort.py b/plugins/filter/version_sort.py index 09eedbf5632..f5a844c542d 100644 --- a/plugins/filter/version_sort.py +++ b/plugins/filter/version_sort.py @@ -6,34 +6,34 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: version_sort - short_description: Sort a list according to version order instead of pure alphabetical one - version_added: 2.2.0 - author: Eric L. (@ericzolf) - description: - - Sort a list according to version order instead of pure alphabetical one. - options: - _input: - description: A list of strings to sort. - type: list - elements: string - required: true -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: version_sort +short_description: Sort a list according to version order instead of pure alphabetical one +version_added: 2.2.0 +author: Eric L. (@ericzolf) +description: + - Sort a list according to version order instead of pure alphabetical one. +options: + _input: + description: A list of strings to sort. + type: list + elements: string + required: true +""" + +EXAMPLES = r""" - name: Convert list of tuples into dictionary ansible.builtin.set_fact: dictionary: "{{ ['2.1', '2.10', '2.9'] | community.general.version_sort }}" # Result is ['2.1', '2.9', '2.10'] -''' - -RETURN = ''' - _value: - description: The list of strings sorted by version. - type: list - elements: string -''' +""" + +RETURN = r""" +_value: + description: The list of strings sorted by version. + type: list + elements: string +""" from ansible_collections.community.general.plugins.module_utils.version import LooseVersion diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index 7d65f583d65..3b0b7b56a01 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -6,114 +6,118 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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 + 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 - 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 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(cobbleer_ipv6_addresses) dictionary to the defined O(group) mapping - interface DNS names to IP addresses. - type: boolean - default: true - version_added: 7.1.0 -''' - -EXAMPLES = ''' + - 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 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(cobbleer_ipv6_addresses) dictionary to the + defined O(group) mapping interface DNS names to IP addresses. + type: boolean + default: true + version_added: 7.1.0 +""" + +EXAMPLES = r""" # my.cobbler.yml plugin: community.general.cobbler url: http://cobbler/cobbler_api user: ansible-tester password: secure -''' +""" import socket diff --git a/plugins/inventory/gitlab_runners.py b/plugins/inventory/gitlab_runners.py index 9a467905dd2..a5d6125ed12 100644 --- a/plugins/inventory/gitlab_runners.py +++ b/plugins/inventory/gitlab_runners.py @@ -8,77 +8,80 @@ __metaclass__ = type -DOCUMENTATION = ''' - name: gitlab_runners - author: - - Stefan Heitmüller (@morph027) - short_description: Ansible dynamic inventory plugin for GitLab runners. - requirements: - - python-gitlab > 1.8.0 - extends_documentation_fragment: - - constructed - description: - - Reads inventories from the GitLab API. - - Uses a YAML configuration file gitlab_runners.[yml|yaml]. - options: - plugin: - description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own. - type: str - required: true - choices: - - gitlab_runners - - community.general.gitlab_runners - server_url: - description: The URL of the GitLab server, with protocol (i.e. http or https). - env: - - name: GITLAB_SERVER_URL - version_added: 1.0.0 - type: str - required: true - api_token: - description: GitLab token for logging in. - env: - - name: GITLAB_API_TOKEN - version_added: 1.0.0 - type: str - aliases: - - private_token - - access_token - filter: - description: filter runners from GitLab API - env: - - name: GITLAB_FILTER - version_added: 1.0.0 - type: str - choices: ['active', 'paused', 'online', 'specific', 'shared'] - verbose_output: - description: Toggle to (not) include all available nodes metadata - type: bool - default: true -''' +DOCUMENTATION = r""" +name: gitlab_runners +author: + - Stefan Heitmüller (@morph027) +short_description: Ansible dynamic inventory plugin for GitLab runners +requirements: + - python-gitlab > 1.8.0 +extends_documentation_fragment: + - constructed +description: + - Reads inventories from the GitLab API. + - Uses a YAML configuration file gitlab_runners.[yml|yaml]. +options: + plugin: + description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its + own. + type: str + required: true + choices: + - gitlab_runners + - community.general.gitlab_runners + server_url: + description: The URL of the GitLab server, with protocol (i.e. http or https). + env: + - name: GITLAB_SERVER_URL + version_added: 1.0.0 + type: str + required: true + api_token: + description: GitLab token for logging in. + env: + - name: GITLAB_API_TOKEN + version_added: 1.0.0 + type: str + aliases: + - private_token + - access_token + filter: + description: Filter runners from GitLab API. + env: + - name: GITLAB_FILTER + version_added: 1.0.0 + type: str + choices: ['active', 'paused', 'online', 'specific', 'shared'] + verbose_output: + description: Toggle to (not) include all available nodes metadata. + type: bool + default: true +""" -EXAMPLES = ''' +EXAMPLES = r""" # gitlab_runners.yml -plugin: community.general.gitlab_runners -host: https://gitlab.com +- example 1: | + plugin: community.general.gitlab_runners + host: https://gitlab.com -# Example using constructed features to create groups and set ansible_host -plugin: community.general.gitlab_runners -host: https://gitlab.com -strict: false -keyed_groups: - # add e.g. amd64 hosts to an arch_amd64 group - - prefix: arch - key: 'architecture' - # add e.g. linux hosts to an os_linux group - - prefix: os - key: 'platform' - # create a group per runner tag - # e.g. a runner tagged w/ "production" ends up in group "label_production" - # hint: labels containing special characters will be converted to safe names - - key: 'tag_list' - prefix: tag -''' +- example 2: |- + # Example using constructed features to create groups and set ansible_host + plugin: community.general.gitlab_runners + host: https://gitlab.com + strict: false + keyed_groups: + # add e.g. amd64 hosts to an arch_amd64 group + - prefix: arch + key: 'architecture' + # add e.g. linux hosts to an os_linux group + - prefix: os + key: 'platform' + # create a group per runner tag + # e.g. a runner tagged w/ "production" ends up in group "label_production" + # hint: labels containing special characters will be converted to safe names + - key: 'tag_list' + prefix: tag +""" from ansible.errors import AnsibleError, AnsibleParserError from ansible.plugins.inventory import BaseInventoryPlugin, Constructable diff --git a/plugins/inventory/icinga2.py b/plugins/inventory/icinga2.py index 527a3291732..a383510dd73 100644 --- a/plugins/inventory/icinga2.py +++ b/plugins/inventory/icinga2.py @@ -7,71 +7,70 @@ __metaclass__ = type -DOCUMENTATION = ''' - name: icinga2 - short_description: Icinga2 inventory source - version_added: 3.7.0 - author: - - Cliff Hults (@BongoEADGC6) +DOCUMENTATION = r""" +name: icinga2 +short_description: Icinga2 inventory source +version_added: 3.7.0 +author: + - Cliff Hults (@BongoEADGC6) +description: + - Get inventory hosts from the Icinga2 API. + - Uses a configuration file as an inventory source, it must end in C(.icinga2.yml) or C(.icinga2.yaml). +extends_documentation_fragment: + - constructed +options: + strict: + version_added: 4.4.0 + compose: + version_added: 4.4.0 + groups: + version_added: 4.4.0 + keyed_groups: + version_added: 4.4.0 + plugin: + description: Name of the plugin. + required: true + type: string + choices: ['community.general.icinga2'] + url: + description: Root URL of Icinga2 API. + type: string + required: true + user: + description: Username to query the API. + type: string + required: true + password: + description: Password to query the API. + type: string + required: true + host_filter: description: - - Get inventory hosts from the Icinga2 API. - - "Uses a configuration file as an inventory source, it must end in - C(.icinga2.yml) or C(.icinga2.yaml)." - extends_documentation_fragment: - - constructed - options: - strict: - version_added: 4.4.0 - compose: - version_added: 4.4.0 - groups: - version_added: 4.4.0 - keyed_groups: - version_added: 4.4.0 - plugin: - description: Name of the plugin. - required: true - type: string - choices: ['community.general.icinga2'] - url: - description: Root URL of Icinga2 API. - type: string - required: true - user: - description: Username to query the API. - type: string - required: true - password: - description: Password to query the API. - type: string - required: true - host_filter: - description: - - An Icinga2 API valid host filter. Leave blank for no filtering - type: string - required: false - validate_certs: - description: Enables or disables SSL certificate verification. - type: boolean - default: true - inventory_attr: - description: - - Allows the override of the inventory name based on different attributes. - - This allows for changing the way limits are used. - - The current default, V(address), is sometimes not unique or present. We recommend to use V(name) instead. - type: string - default: address - choices: ['name', 'display_name', 'address'] - version_added: 4.2.0 - group_by_hostgroups: - description: - - Uses Icinga2 hostgroups as groups. - type: boolean - default: true - version_added: 8.4.0 -''' - -EXAMPLES = r''' + - 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""" # my.icinga2.yml plugin: community.general.icinga2 url: http://localhost:5665 @@ -94,7 +93,7 @@ # set 'ansible_user' and 'ansible_port' from icinga2 host vars ansible_user: icinga2_attributes.vars.ansible_user ansible_port: icinga2_attributes.vars.ansible_port | default(22) -''' +""" import json diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py index 5dc18b47100..e230ac8b415 100644 --- a/plugins/inventory/iocage.py +++ b/plugins/inventory/iocage.py @@ -7,111 +7,106 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: iocage - short_description: iocage inventory source - version_added: 10.2.0 - author: - - Vladimir Botka (@vbotka) - requirements: - - iocage >= 1.8 +DOCUMENTATION = r""" +name: iocage +short_description: iocage inventory source +version_added: 10.2.0 +author: + - Vladimir Botka (@vbotka) +requirements: + - iocage >= 1.8 +description: + - Get inventory hosts from the iocage jail manager running on O(host). + - By default, O(host) is V(localhost). If O(host) is not V(localhost) it is expected that the user running Ansible on the + controller can connect to the O(host) account O(user) with SSH non-interactively and execute the command C(iocage list). + - Uses a configuration file as an inventory source, it must end in C(.iocage.yml) or C(.iocage.yaml). +extends_documentation_fragment: + - ansible.builtin.constructed + - ansible.builtin.inventory_cache +options: + plugin: description: - - Get inventory hosts from the iocage jail manager running on O(host). - - By default, O(host) is V(localhost). If O(host) is not V(localhost) it - is expected that the user running Ansible on the controller can - connect to the O(host) account O(user) with SSH non-interactively and - execute the command C(iocage list). - - Uses a configuration file as an inventory source, it must end - in C(.iocage.yml) or C(.iocage.yaml). - extends_documentation_fragment: - - ansible.builtin.constructed - - ansible.builtin.inventory_cache - options: - plugin: - description: - - The name of this plugin, it should always be set to - V(community.general.iocage) for this plugin to recognize - it as its own. - required: true - choices: ['community.general.iocage'] - type: str - host: - description: The IP/hostname of the C(iocage) host. - type: str - default: localhost - user: - description: - - C(iocage) user. - It is expected that the O(user) is able to connect to the - O(host) with SSH and execute the command C(iocage list). - This option is not required if O(host) is V(localhost). - type: str - get_properties: - description: - - Get jails' properties. - Creates dictionary C(iocage_properties) for each added host. - type: boolean - default: false - env: - description: O(user)'s environment on O(host). - type: dict - default: {} - notes: - - You might want to test the command C(ssh user@host iocage list -l) on - the controller before using this inventory plugin with O(user) specified - and with O(host) other than V(localhost). - - If you run this inventory plugin on V(localhost) C(ssh) is not used. - In this case, test the command C(iocage list -l). - - This inventory plugin creates variables C(iocage_*) for each added host. - - The values of these variables are collected from the output of the - command C(iocage list -l). - - The names of these variables correspond to the output columns. - - The column C(NAME) is used to name the added host. -''' - -EXAMPLES = ''' + - The name of this plugin, it should always be set to V(community.general.iocage) for this plugin to recognize it as + its own. + required: true + choices: ['community.general.iocage'] + type: str + host: + description: The IP/hostname of the C(iocage) host. + type: str + default: localhost + user: + description: + - C(iocage) user. It is expected that the O(user) is able to connect to the O(host) with SSH and execute the command + C(iocage list). This option is not required if O(host) is V(localhost). + type: str + get_properties: + description: + - Get jails' properties. Creates dictionary C(iocage_properties) for each added host. + type: boolean + default: false + env: + description: O(user)'s environment on O(host). + type: dict + default: {} +notes: + - You might want to test the command C(ssh user@host iocage list -l) on the controller before using this inventory plugin + with O(user) specified and with O(host) other than V(localhost). + - If you run this inventory plugin on V(localhost) C(ssh) is not used. In this case, test the command C(iocage list -l). + - This inventory plugin creates variables C(iocage_*) for each added host. + - The values of these variables are collected from the output of the command C(iocage list -l). + - The names of these variables correspond to the output columns. + - The column C(NAME) is used to name the added host. +""" + +EXAMPLES = r""" # file name must end with iocage.yaml or iocage.yml -plugin: community.general.iocage -host: 10.1.0.73 -user: admin - -# user is not required if iocage is running on localhost (default) -plugin: community.general.iocage - -# run cryptography without legacy algorithms -plugin: community.general.iocage -host: 10.1.0.73 -user: admin -env: - CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 - -# enable cache -plugin: community.general.iocage -host: 10.1.0.73 -user: admin -env: - CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 -cache: true - -# see inventory plugin ansible.builtin.constructed -plugin: community.general.iocage -host: 10.1.0.73 -user: admin -env: - CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 -cache: true -strict: false -compose: - ansible_host: iocage_ip4 - release: iocage_release | split('-') | first -groups: - test: inventory_hostname.startswith('test') -keyed_groups: - - prefix: distro - key: iocage_release - - prefix: state - key: iocage_state -''' +- | + plugin: community.general.iocage + host: 10.1.0.73 + user: admin + +- | + # user is not required if iocage is running on localhost (default) + plugin: community.general.iocage + +- | + # run cryptography without legacy algorithms + plugin: community.general.iocage + host: 10.1.0.73 + user: admin + env: + CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 + +- | + # enable cache + plugin: community.general.iocage + host: 10.1.0.73 + user: admin + env: + CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 + cache: true + +- |- + # see inventory plugin ansible.builtin.constructed + plugin: community.general.iocage + host: 10.1.0.73 + user: admin + env: + CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 + cache: true + strict: false + compose: + ansible_host: iocage_ip4 + release: iocage_release | split('-') | first + groups: + test: inventory_hostname.startswith('test') + keyed_groups: + - prefix: distro + key: iocage_release + - prefix: state + key: iocage_state +""" import re import os diff --git a/plugins/inventory/linode.py b/plugins/inventory/linode.py index 46f2faeacea..7ed3db3b359 100644 --- a/plugins/inventory/linode.py +++ b/plugins/inventory/linode.py @@ -6,121 +6,125 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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''' -# Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. -plugin: community.general.linode - -# You can use Jinja to template the access token. -plugin: community.general.linode -access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}" -# For older Ansible versions, you need to write this as: -# access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}" - -# Example with regions, types, groups and access token -plugin: community.general.linode -access_token: foobar -regions: - - eu-west -types: - - g5-standard-2 - -# Example with keyed_groups, groups, and compose -plugin: community.general.linode -access_token: foobar -keyed_groups: - - key: tags - separator: '' - - key: region - prefix: region -groups: - webservers: "'web' in (tags|list)" - mailservers: "'mail' in (tags|list)" -compose: - # By default, Ansible tries to connect to the label of the instance. - # Since that might not be a valid name to connect to, you can - # replace it with the first IPv4 address of the linode as follows: - ansible_ssh_host: ipv4[0] - ansible_port: 2222 - -# Example where control traffic limited to internal network -plugin: community.general.linode -access_token: foobar -ip_style: api -compose: - ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first" -''' +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""" +- | + # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. + plugin: community.general.linode + +- | + # You can use Jinja to template the access token. + plugin: community.general.linode + access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}" + # For older Ansible versions, you need to write this as: + # access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}" + +- | + # Example with regions, types, groups and access token + plugin: community.general.linode + access_token: foobar + regions: + - eu-west + types: + - g5-standard-2 + +- | + # Example with keyed_groups, groups, and compose + plugin: community.general.linode + access_token: foobar + keyed_groups: + - key: tags + separator: '' + - key: region + prefix: region + groups: + webservers: "'web' in (tags|list)" + mailservers: "'mail' in (tags|list)" + compose: + # By default, Ansible tries to connect to the label of the instance. + # Since that might not be a valid name to connect to, you can + # replace it with the first IPv4 address of the linode as follows: + ansible_ssh_host: ipv4[0] + ansible_port: 2222 + +- |- + # Example where control traffic limited to internal network + plugin: community.general.linode + access_token: foobar + ip_style: api + compose: + ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first" +""" from ansible.errors import AnsibleError from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py index d7b942c1f78..d996cc5b27f 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -6,164 +6,168 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' - name: lxd - short_description: Returns Ansible inventory from lxd host +DOCUMENTATION = r""" +name: lxd +short_description: Returns Ansible inventory from lxd host +description: + - Get inventory from the lxd. + - Uses a YAML configuration file that ends with 'lxd.(yml|yaml)'. +version_added: "3.0.0" +author: "Frank Dornheim (@conloos)" +requirements: + - ipaddress + - lxd >= 4.0 +options: + plugin: + description: Token that ensures this is a source file for the 'lxd' plugin. + type: string + required: true + choices: ['community.general.lxd'] + url: description: - - Get inventory from the lxd. - - Uses a YAML configuration file that ends with 'lxd.(yml|yaml)'. - version_added: "3.0.0" - author: "Frank Dornheim (@conloos)" - requirements: - - ipaddress - - lxd >= 4.0 - options: - plugin: - description: Token that ensures this is a source file for the 'lxd' plugin. - type: string - required: true - choices: [ 'community.general.lxd' ] - url: - description: - - The unix domain socket path or the https URL for the lxd server. - - Sockets in filesystem have to start with C(unix:). - - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). - type: string - default: unix:/var/snap/lxd/common/lxd/unix.socket - client_key: - description: - - The client certificate key file path. - aliases: [ key_file ] - default: $HOME/.config/lxc/client.key - type: path - client_cert: - description: - - The client certificate file path. - aliases: [ cert_file ] - default: $HOME/.config/lxc/client.crt - type: path - server_cert: - description: - - The server certificate file path. - type: path - version_added: 8.0.0 - server_check_hostname: - description: - - This option controls if the server's hostname is checked as part of the HTTPS connection verification. - This can be useful to disable, if for example, the server certificate provided (see O(server_cert) option) - does not cover a name matching the one used to communicate with the server. Such mismatch is common as LXD - generates self-signed server certificates by default. - type: bool - default: true - version_added: 8.0.0 - trust_password: - description: - - The client trusted password. - - You need to set this password on the lxd server before - running this module using the following command - C(lxc config set core.trust_password ) - See U(https://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). - - If O(trust_password) is set, this module send a request for authentication before sending any requests. - type: str - state: - description: Filter the instance according to the current status. - type: str - default: none - choices: [ 'STOPPED', 'STARTING', 'RUNNING', 'none' ] - project: - description: Filter the instance according to the given project. - type: str - default: default - version_added: 6.2.0 - type_filter: - description: - - Filter the instances by type V(virtual-machine), V(container) or V(both). - - The first version of the inventory only supported containers. - type: str - default: container - choices: [ 'virtual-machine', 'container', 'both' ] - version_added: 4.2.0 - prefered_instance_network_interface: - description: - - If an instance has multiple network interfaces, select which one is the preferred as pattern. - - Combined with the first number that can be found e.g. 'eth' + 0. - - The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface) - in community.general 3.8.0. The old name still works as an alias. - type: str - default: eth - aliases: - - prefered_container_network_interface - prefered_instance_network_family: - description: - - If an instance has multiple network interfaces, which one is the preferred by family. - - Specify V(inet) for IPv4 and V(inet6) for IPv6. - type: str - default: inet - choices: [ 'inet', 'inet6' ] - groupby: - description: - - Create groups by the following keywords C(location), C(network_range), C(os), C(pattern), C(profile), C(release), C(type), C(vlanid). - - See example for syntax. - type: dict -''' - -EXAMPLES = ''' -# simple lxd.yml -plugin: community.general.lxd -url: unix:/var/snap/lxd/common/lxd/unix.socket - -# simple lxd.yml including filter -plugin: community.general.lxd -url: unix:/var/snap/lxd/common/lxd/unix.socket -state: RUNNING - -# simple lxd.yml including virtual machines and containers -plugin: community.general.lxd -url: unix:/var/snap/lxd/common/lxd/unix.socket -type_filter: both - -# grouping lxd.yml -groupby: - locationBerlin: - type: location - attribute: Berlin - netRangeIPv4: - type: network_range - attribute: 10.98.143.0/24 - netRangeIPv6: - type: network_range - attribute: fd42:bd00:7b11:2167:216:3eff::/24 - osUbuntu: - type: os - attribute: ubuntu - testpattern: - type: pattern - attribute: test - profileDefault: - type: profile - attribute: default - profileX11: - type: profile - attribute: x11 - releaseFocal: - type: release - attribute: focal - releaseBionic: - type: release - attribute: bionic - typeVM: - type: type - attribute: virtual-machine - typeContainer: - type: type - attribute: container - vlan666: - type: vlanid - attribute: 666 - projectInternals: - type: project - attribute: internals -''' + - The unix domain socket path or the https URL for the lxd server. + - Sockets in filesystem have to start with C(unix:). + - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). + type: string + default: unix:/var/snap/lxd/common/lxd/unix.socket + client_key: + description: + - The client certificate key file path. + aliases: [key_file] + default: $HOME/.config/lxc/client.key + type: path + client_cert: + description: + - The client certificate file path. + aliases: [cert_file] + default: $HOME/.config/lxc/client.crt + type: path + server_cert: + description: + - The server certificate file path. + type: path + version_added: 8.0.0 + server_check_hostname: + description: + - This option controls if the server's hostname is checked as part of the HTTPS connection verification. This can be + useful to disable, if for example, the server certificate provided (see O(server_cert) option) does not cover a name + matching the one used to communicate with the server. Such mismatch is common as LXD generates self-signed server + certificates by default. + type: bool + default: true + version_added: 8.0.0 + trust_password: + description: + - The client trusted password. + - You need to set this password on the lxd server before running this module using the following command C(lxc config + set core.trust_password ) See + U(https://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). + - If O(trust_password) is set, this module send a request for authentication before sending any requests. + type: str + state: + description: Filter the instance according to the current status. + type: str + default: none + choices: ['STOPPED', 'STARTING', 'RUNNING', 'none'] + project: + description: Filter the instance according to the given project. + type: str + default: default + version_added: 6.2.0 + type_filter: + description: + - Filter the instances by type V(virtual-machine), V(container) or V(both). + - The first version of the inventory only supported containers. + type: str + default: container + choices: ['virtual-machine', 'container', 'both'] + version_added: 4.2.0 + prefered_instance_network_interface: + description: + - If an instance has multiple network interfaces, select which one is the preferred as pattern. + - Combined with the first number that can be found, for example V(eth0). + - 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 = r""" +- | + # simple lxd.yml + plugin: community.general.lxd + url: unix:/var/snap/lxd/common/lxd/unix.socket + +- | + # simple lxd.yml including filter + plugin: community.general.lxd + url: unix:/var/snap/lxd/common/lxd/unix.socket + state: RUNNING + +- | + # simple lxd.yml including virtual machines and containers + plugin: community.general.lxd + url: unix:/var/snap/lxd/common/lxd/unix.socket + type_filter: both + +- |- + # grouping lxd.yml + groupby: + locationBerlin: + type: location + attribute: Berlin + netRangeIPv4: + type: network_range + attribute: 10.98.143.0/24 + netRangeIPv6: + type: network_range + attribute: fd42:bd00:7b11:2167:216:3eff::/24 + osUbuntu: + type: os + attribute: ubuntu + testpattern: + type: pattern + attribute: test + profileDefault: + type: profile + attribute: default + profileX11: + type: profile + attribute: x11 + releaseFocal: + type: release + attribute: focal + releaseBionic: + type: release + attribute: bionic + typeVM: + type: type + attribute: virtual-machine + typeContainer: + type: type + attribute: container + vlan666: + type: vlanid + attribute: 666 + projectInternals: + type: project + attribute: internals +""" import json import re diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py index f40f33b972e..b3822dedf0d 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -6,117 +6,120 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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 - 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 -plugin: community.general.nmap -strict: false -address: 192.168.0.0/24 - - -# a sudo nmap scan to fully use nmap scan power. -plugin: community.general.nmap -sudo: true -strict: false -address: 192.168.0.0/24 - -# an nmap scan specifying ports and classifying results to an inventory group -plugin: community.general.nmap -address: 192.168.0.0/24 -exclude: 192.168.0.1, web.example.com -port: 22, 443 -groups: - web_servers: "ports | selectattr('port', 'equalto', '443')" -''' + - 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 using 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 using 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 + 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 + strict: false + address: 192.168.0.0/24 + + +- | + # a sudo nmap scan to fully use nmap scan power. + plugin: community.general.nmap + sudo: true + strict: false + address: 192.168.0.0/24 + +- |- + # an nmap scan specifying ports and classifying results to an inventory group + plugin: community.general.nmap + address: 192.168.0.0/24 + exclude: 192.168.0.1, web.example.com + port: 22, 443 + groups: + web_servers: "ports | selectattr('port', 'equalto', '443')" +""" import os import re diff --git a/plugins/inventory/online.py b/plugins/inventory/online.py index 9475049c089..b320d308956 100644 --- a/plugins/inventory/online.py +++ b/plugins/inventory/online.py @@ -6,49 +6,49 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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: +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''' + - 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""" # online_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i online_inventory.yml @@ -59,7 +59,7 @@ - location - offer - rpn -''' +""" import json from sys import version as python_version diff --git a/plugins/inventory/opennebula.py b/plugins/inventory/opennebula.py index 7fc320f3268..84915752801 100644 --- a/plugins/inventory/opennebula.py +++ b/plugins/inventory/opennebula.py @@ -7,77 +7,75 @@ __metaclass__ = type -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 -''' - -EXAMPLES = r''' + - 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""" # inventory_opennebula.yml file in YAML format # Example command line: ansible-inventory --list -i inventory_opennebula.yml @@ -85,7 +83,7 @@ plugin: community.general.opennebula api_url: https://opennebula:2633/RPC2 filter_by_label: Cache -''' +""" try: import pyone diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index cf25efc58c8..952cdc6df22 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -7,213 +7,225 @@ __metaclass__ = type -DOCUMENTATION = ''' - name: proxmox - short_description: Proxmox inventory source - version_added: "1.2.0" - author: - - Jeffrey van Pelt (@Thulium-Drake) - requirements: - - requests >= 1.1 +DOCUMENTATION = r""" +name: proxmox +short_description: Proxmox inventory source +version_added: "1.2.0" +author: + - Jeffrey van Pelt (@Thulium-Drake) +requirements: + - requests >= 1.1 +description: + - Get inventory hosts from a Proxmox PVE cluster. + - Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml). + - Will retrieve the first network interface with an IP for Proxmox nodes. + - Can retrieve LXC/QEMU configuration as facts. +extends_documentation_fragment: + - constructed + - inventory_cache +options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize + it as its own. + required: true + choices: ['community.general.proxmox'] + type: str + url: description: - - Get inventory hosts from a Proxmox PVE cluster. - - "Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml)" - - Will retrieve the first network interface with an IP for Proxmox nodes. - - Can retrieve LXC/QEMU configuration as facts. - extends_documentation_fragment: - - constructed - - inventory_cache - options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as its own. - required: true - choices: ['community.general.proxmox'] - type: str - url: - description: - - URL to Proxmox cluster. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_URL) will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the O(url). - default: 'http://localhost:8006' - type: str - env: - - name: PROXMOX_URL - version_added: 2.0.0 - user: - description: - - Proxmox authentication user. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_USER) will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the O(user). - required: true - type: str - env: - - name: PROXMOX_USER - version_added: 2.0.0 - password: - description: - - Proxmox authentication password. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_PASSWORD) will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the O(password). - - If you do not specify a password, you must set O(token_id) and O(token_secret) instead. - type: str - env: - - name: PROXMOX_PASSWORD - version_added: 2.0.0 - token_id: - description: - - Proxmox authentication token ID. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_ID) will be used instead. - - To use token authentication, you must also specify O(token_secret). If you do not specify O(token_id) and O(token_secret), - you must set a password instead. - - Make sure to grant explicit pve permissions to the token or disable 'privilege separation' to use the users' privileges instead. - version_added: 4.8.0 - type: str - env: - - name: PROXMOX_TOKEN_ID - token_secret: - description: - - Proxmox authentication token secret. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_SECRET) will be used instead. - - To use token authentication, you must also specify O(token_id). If you do not specify O(token_id) and O(token_secret), - you must set a password instead. - version_added: 4.8.0 - type: str - env: - - name: PROXMOX_TOKEN_SECRET - validate_certs: - description: Verify SSL certificate if using HTTPS. - type: boolean - default: true - group_prefix: - description: Prefix to apply to Proxmox groups. - default: proxmox_ - type: str - facts_prefix: - description: Prefix to apply to LXC/QEMU config facts. - default: proxmox_ - type: str - want_facts: - description: - - Gather LXC/QEMU configuration facts. - - When O(want_facts) is set to V(true) more details about QEMU VM status are possible, besides the running and stopped states. - Currently if the VM is running and it is suspended, the status will be running and the machine will be in C(running) group, - but its actual state will be paused. See O(qemu_extended_statuses) for how to retrieve the real status. - default: false - type: bool - qemu_extended_statuses: - description: - - Requires O(want_facts) to be set to V(true) to function. This will allow you to differentiate between C(paused) and C(prelaunch) - statuses of the QEMU VMs. - - This introduces multiple groups [prefixed with O(group_prefix)] C(prelaunch) and C(paused). - default: false - type: bool - version_added: 5.1.0 - want_proxmox_nodes_ansible_host: - version_added: 3.0.0 - description: - - Whether to set C(ansible_host) for proxmox nodes. - - When set to V(true) (default), will use the first available interface. This can be different from what you expect. - - The default of this option changed from V(true) to V(false) in community.general 6.0.0. - type: bool - default: false - exclude_nodes: - description: Exclude proxmox nodes and the nodes-group from the inventory output. - type: bool - default: false - version_added: 8.1.0 - filters: - version_added: 4.6.0 - description: A list of Jinja templates that allow filtering hosts. - type: list - elements: str - default: [] - strict: - version_added: 2.5.0 - compose: - version_added: 2.5.0 - groups: - version_added: 2.5.0 - keyed_groups: - version_added: 2.5.0 -''' - -EXAMPLES = ''' -# Minimal example which will not gather additional facts for QEMU/LXC guests -# By not specifying a URL the plugin will attempt to connect to the controller host on port 8006 -# my.proxmox.yml -plugin: community.general.proxmox -user: ansible@pve -password: secure -# Note that this can easily give you wrong values as ansible_host. See further below for -# an example where this is set to `false` and where ansible_host is set with `compose`. -want_proxmox_nodes_ansible_host: true - -# Instead of login with password, proxmox supports api token authentication since release 6.2. -plugin: community.general.proxmox -user: ci@pve -token_id: gitlab-1 -token_secret: fa256e9c-26ab-41ec-82da-707a2c079829 - -# The secret can also be a vault string or passed via the environment variable TOKEN_SECRET. -token_secret: !vault | - $ANSIBLE_VAULT;1.1;AES256 - 62353634333163633336343265623632626339313032653563653165313262343931643431656138 - 6134333736323265656466646539663134306166666237630a653363623262636663333762316136 - 34616361326263383766366663393837626437316462313332663736623066656237386531663731 - 3037646432383064630a663165303564623338666131353366373630656661333437393937343331 - 32643131386134396336623736393634373936356332623632306561356361323737313663633633 - 6231313333666361656537343562333337323030623732323833 - -# More complete example demonstrating the use of 'want_facts' and the constructed options -# Note that using facts returned by 'want_facts' in constructed options requires 'want_facts=true' -# my.proxmox.yml -plugin: community.general.proxmox -url: http://pve.domain.com:8006 -user: ansible@pve -password: secure -want_facts: true -keyed_groups: - # proxmox_tags_parsed is an example of a fact only returned when 'want_facts=true' - - key: proxmox_tags_parsed - separator: "" - prefix: group -groups: - webservers: "'web' in (proxmox_tags_parsed|list)" - mailservers: "'mail' in (proxmox_tags_parsed|list)" -compose: - ansible_port: 2222 -# Note that this can easily give you wrong values as ansible_host. See further below for -# an example where this is set to `false` and where ansible_host is set with `compose`. -want_proxmox_nodes_ansible_host: true - -# Using the inventory to allow ansible to connect via the first IP address of the VM / Container -# (Default is connection by name of QEMU/LXC guests) -# Note: my_inv_var demonstrates how to add a string variable to every host used by the inventory. -# my.proxmox.yml -plugin: community.general.proxmox -url: http://192.168.1.2:8006 -user: ansible@pve -password: secure -validate_certs: false # only do this when you trust the network! -want_facts: true -want_proxmox_nodes_ansible_host: false -compose: - ansible_host: proxmox_ipconfig0.ip | default(proxmox_net0.ip) | ipaddr('address') - my_inv_var_1: "'my_var1_value'" - my_inv_var_2: > - "my_var_2_value" - -# Specify the url, user and password using templating -# my.proxmox.yml -plugin: community.general.proxmox -url: "{{ lookup('ansible.builtin.ini', 'url', section='proxmox', file='file.ini') }}" -user: "{{ lookup('ansible.builtin.env','PM_USER') | default('ansible@pve') }}" -password: "{{ lookup('community.general.random_string', base64=True) }}" -# Note that this can easily give you wrong values as ansible_host. See further up for -# an example where this is set to `false` and where ansible_host is set with `compose`. -want_proxmox_nodes_ansible_host: true - -''' + - URL to Proxmox cluster. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_URL) will + be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(url). + default: 'http://localhost:8006' + type: str + env: + - name: PROXMOX_URL + version_added: 2.0.0 + user: + description: + - Proxmox authentication user. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_USER) will + be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(user). + required: true + type: str + env: + - name: PROXMOX_USER + version_added: 2.0.0 + password: + description: + - Proxmox authentication password. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_PASSWORD) + will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(password). + - If you do not specify a password, you must set O(token_id) and O(token_secret) instead. + type: str + env: + - name: PROXMOX_PASSWORD + version_added: 2.0.0 + token_id: + description: + - Proxmox authentication token ID. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_ID) + will be used instead. + - To use token authentication, you must also specify O(token_secret). If you do not specify O(token_id) and O(token_secret), + you must set a password instead. + - Make sure to grant explicit pve permissions to the token or disable 'privilege separation' to use the users' privileges + instead. + version_added: 4.8.0 + type: str + env: + - name: PROXMOX_TOKEN_ID + token_secret: + description: + - Proxmox authentication token secret. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_SECRET) + will be used instead. + - To use token authentication, you must also specify O(token_id). If you do not specify O(token_id) and O(token_secret), + you must set a password instead. + version_added: 4.8.0 + type: str + env: + - name: PROXMOX_TOKEN_SECRET + validate_certs: + description: Verify SSL certificate if using HTTPS. + type: boolean + default: true + group_prefix: + description: Prefix to apply to Proxmox groups. + default: proxmox_ + type: str + facts_prefix: + description: Prefix to apply to LXC/QEMU config facts. + default: proxmox_ + type: str + want_facts: + description: + - Gather LXC/QEMU configuration facts. + - When O(want_facts) is set to V(true) more details about QEMU VM status are possible, besides the running and stopped + states. Currently if the VM is running and it is suspended, the status will be running and the machine will be in + C(running) group, but its actual state will be paused. See O(qemu_extended_statuses) for how to retrieve the real + status. + default: false + type: bool + qemu_extended_statuses: + description: + - Requires O(want_facts) to be set to V(true) to function. This will allow you to differentiate between C(paused) and + C(prelaunch) statuses of the QEMU VMs. + - This introduces multiple groups [prefixed with O(group_prefix)] C(prelaunch) and C(paused). + default: false + type: bool + version_added: 5.1.0 + want_proxmox_nodes_ansible_host: + version_added: 3.0.0 + description: + - Whether to set C(ansible_host) for proxmox nodes. + - When set to V(true) (default), will use the first available interface. This can be different from what you expect. + - The default of this option changed from V(true) to V(false) in community.general 6.0.0. + type: bool + default: false + exclude_nodes: + description: Exclude proxmox nodes and the nodes-group from the inventory output. + type: bool + default: false + version_added: 8.1.0 + filters: + version_added: 4.6.0 + description: A list of Jinja templates that allow filtering hosts. + type: list + elements: str + default: [] + strict: + version_added: 2.5.0 + compose: + version_added: 2.5.0 + groups: + version_added: 2.5.0 + keyed_groups: + version_added: 2.5.0 +""" + +EXAMPLES = r""" +- | + # Minimal example which will not gather additional facts for QEMU/LXC guests + # By not specifying a URL the plugin will attempt to connect to the controller host on port 8006 + # my.proxmox.yml + plugin: community.general.proxmox + user: ansible@pve + password: secure + # Note that this can easily give you wrong values as ansible_host. See further below for + # an example where this is set to `false` and where ansible_host is set with `compose`. + want_proxmox_nodes_ansible_host: true + +- | + # Instead of login with password, proxmox supports api token authentication since release 6.2. + plugin: community.general.proxmox + user: ci@pve + token_id: gitlab-1 + token_secret: fa256e9c-26ab-41ec-82da-707a2c079829 + + # The secret can also be a vault string or passed via the environment variable TOKEN_SECRET. + token_secret: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 62353634333163633336343265623632626339313032653563653165313262343931643431656138 + 6134333736323265656466646539663134306166666237630a653363623262636663333762316136 + 34616361326263383766366663393837626437316462313332663736623066656237386531663731 + 3037646432383064630a663165303564623338666131353366373630656661333437393937343331 + 32643131386134396336623736393634373936356332623632306561356361323737313663633633 + 6231313333666361656537343562333337323030623732323833 + +- | + # More complete example demonstrating the use of 'want_facts' and the constructed options + # Note that using facts returned by 'want_facts' in constructed options requires 'want_facts=true' + # my.proxmox.yml + plugin: community.general.proxmox + url: http://pve.domain.com:8006 + user: ansible@pve + password: secure + want_facts: true + keyed_groups: + # proxmox_tags_parsed is an example of a fact only returned when 'want_facts=true' + - key: proxmox_tags_parsed + separator: "" + prefix: group + groups: + webservers: "'web' in (proxmox_tags_parsed|list)" + mailservers: "'mail' in (proxmox_tags_parsed|list)" + compose: + ansible_port: 2222 + # Note that this can easily give you wrong values as ansible_host. See further below for + # an example where this is set to `false` and where ansible_host is set with `compose`. + want_proxmox_nodes_ansible_host: true + +- | + # Using the inventory to allow ansible to connect via the first IP address of the VM / Container + # (Default is connection by name of QEMU/LXC guests) + # Note: my_inv_var demonstrates how to add a string variable to every host used by the inventory. + # my.proxmox.yml + plugin: community.general.proxmox + url: http://192.168.1.2:8006 + user: ansible@pve + password: secure + validate_certs: false # only do this when you trust the network! + want_facts: true + want_proxmox_nodes_ansible_host: false + compose: + ansible_host: proxmox_ipconfig0.ip | default(proxmox_net0.ip) | ipaddr('address') + my_inv_var_1: "'my_var1_value'" + my_inv_var_2: > + "my_var_2_value" + +- |- + # Specify the url, user and password using templating + # my.proxmox.yml + plugin: community.general.proxmox + url: "{{ lookup('ansible.builtin.ini', 'url', section='proxmox', file='file.ini') }}" + user: "{{ lookup('ansible.builtin.env','PM_USER') | default('ansible@pve') }}" + password: "{{ lookup('community.general.random_string', base64=True) }}" + # Note that this can easily give you wrong values as ansible_host. See further up for + # an example where this is set to `false` and where ansible_host is set with `compose`. + want_proxmox_nodes_ansible_host: true +""" import itertools import re diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index 9a40243ee77..990504fe8c1 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -7,108 +7,110 @@ __metaclass__ = type -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: + - 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''' + - 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""" # scaleway_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i scaleway_inventory.yml -# use hostname as inventory_hostname -# use the private IP address to connect to the host -plugin: community.general.scaleway -regions: - - ams1 - - par1 -tags: - - foobar -hostnames: - - hostname -variables: - ansible_host: private_ip - state: state - -# use hostname as inventory_hostname and public IP address to connect to the host -plugin: community.general.scaleway -hostnames: - - hostname -regions: - - par1 -variables: - ansible_host: public_ip.address - -# Using static strings as variables -plugin: community.general.scaleway -hostnames: - - hostname -variables: - ansible_host: public_ip.address - ansible_connection: "'ssh'" - ansible_user: "'admin'" -''' +- | + # use hostname as inventory_hostname + # use the private IP address to connect to the host + plugin: community.general.scaleway + regions: + - ams1 + - par1 + tags: + - foobar + hostnames: + - hostname + variables: + ansible_host: private_ip + state: state + +- | + # use hostname as inventory_hostname and public IP address to connect to the host + plugin: community.general.scaleway + hostnames: + - hostname + regions: + - par1 + variables: + ansible_host: public_ip.address + +- | + # Using static strings as variables + plugin: community.general.scaleway + hostnames: + - hostname + variables: + ansible_host: public_ip.address + ansible_connection: "'ssh'" + ansible_user: "'admin'" +""" import os import json diff --git a/plugins/inventory/stackpath_compute.py b/plugins/inventory/stackpath_compute.py index c87d0e52776..34b9391800a 100644 --- a/plugins/inventory/stackpath_compute.py +++ b/plugins/inventory/stackpath_compute.py @@ -7,60 +7,56 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: stackpath_compute - short_description: StackPath Edge Computing inventory source - version_added: 1.2.0 - author: - - UNKNOWN (@shayrybak) - extends_documentation_fragment: - - inventory_cache - - constructed +DOCUMENTATION = r""" +name: stackpath_compute +short_description: StackPath Edge Computing inventory source +version_added: 1.2.0 +author: + - UNKNOWN (@shayrybak) +extends_documentation_fragment: + - inventory_cache + - constructed +description: + - Get inventory hosts from StackPath Edge Computing. + - Uses a YAML configuration file that ends with stackpath_compute.(yml|yaml). +options: + plugin: description: - - Get inventory hosts from StackPath Edge Computing. - - Uses a YAML configuration file that ends with stackpath_compute.(yml|yaml). - options: - plugin: - description: - - A token that ensures this is a source file for the plugin. - required: true - type: string - choices: ['community.general.stackpath_compute'] - client_id: - description: - - An OAuth client ID generated from the API Management section of the StackPath customer portal - U(https://control.stackpath.net/api-management). - required: true - type: str - client_secret: - description: - - An OAuth client secret generated from the API Management section of the StackPath customer portal - U(https://control.stackpath.net/api-management). - required: true - type: str - stack_slugs: - description: - - A list of Stack slugs to query instances in. If no entry then get instances in all stacks on the account. - type: list - elements: str - use_internal_ip: - description: - - Whether or not to use internal IP addresses, If false, uses external IP addresses, internal otherwise. - - If an instance doesn't have an external IP it will not be returned when this option is set to false. - type: bool -''' + - A token that ensures this is a source file for the plugin. + required: true + type: string + choices: ['community.general.stackpath_compute'] + client_id: + description: + - An OAuth client ID generated from the API Management section of the StackPath customer portal U(https://control.stackpath.net/api-management). + required: true + type: str + client_secret: + description: + - An OAuth client secret generated from the API Management section of the StackPath customer portal U(https://control.stackpath.net/api-management). + required: true + type: str + stack_slugs: + description: + - A list of Stack slugs to query instances in. If no entry then get instances in all stacks on the account. + type: list + elements: str + use_internal_ip: + description: + - Whether or not to use internal IP addresses, If false, uses external IP addresses, internal otherwise. + - If an instance does not have an external IP it will not be returned when this option is set to false. + type: bool +""" -EXAMPLES = ''' -# Example using credentials to fetch all workload instances in a stack. ---- +EXAMPLES = r""" plugin: community.general.stackpath_compute client_id: my_client_id client_secret: my_client_secret stack_slugs: -- my_first_stack_slug -- my_other_stack_slug + - my_first_stack_slug + - my_other_stack_slug use_internal_ip: false -''' +""" import traceback import json diff --git a/plugins/inventory/virtualbox.py b/plugins/inventory/virtualbox.py index b0545319a1c..11187beae7f 100644 --- a/plugins/inventory/virtualbox.py +++ b/plugins/inventory/virtualbox.py @@ -6,70 +6,71 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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 between showing all VMs or 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 -''' - -EXAMPLES = ''' + - 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 = r""" # file must be named vbox.yaml or vbox.yml simple_config_file: - plugin: community.general.virtualbox - settings_password_file: /etc/virtulbox/secrets - query: - logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList - compose: - ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh') + plugin: community.general.virtualbox + settings_password_file: /etc/virtulbox/secrets + query: + logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList + compose: + ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh') # add hosts (all match with minishift vm) to the group container if any of the vms are in ansible_inventory' plugin: community.general.virtualbox groups: container: "'minis' in (inventory_hostname)" -''' +""" import os diff --git a/plugins/inventory/xen_orchestra.py b/plugins/inventory/xen_orchestra.py index 0a050d0bf9b..bf7b4b1cb5c 100644 --- a/plugins/inventory/xen_orchestra.py +++ b/plugins/inventory/xen_orchestra.py @@ -6,62 +6,66 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: xen_orchestra - short_description: Xen Orchestra inventory source - version_added: 4.1.0 - author: - - Dom Del Nano (@ddelnano) - - Samori Gorse (@shinuza) - requirements: - - websocket-client >= 1.0.0 +DOCUMENTATION = r""" +name: xen_orchestra +short_description: Xen Orchestra inventory source +version_added: 4.1.0 +author: + - Dom Del Nano (@ddelnano) + - Samori Gorse (@shinuza) +requirements: + - websocket-client >= 1.0.0 +description: + - Get inventory hosts from a Xen Orchestra deployment. + - Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml). +extends_documentation_fragment: + - constructed + - inventory_cache +options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to + recognize it as its own. + required: true + choices: ['community.general.xen_orchestra'] + type: str + api_host: description: - - Get inventory hosts from a Xen Orchestra deployment. - - 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).' - extends_documentation_fragment: - - constructed - - inventory_cache - options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own. - required: true - choices: ['community.general.xen_orchestra'] - type: str - api_host: - description: - - API host to XOA API. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. - type: str - env: - - name: ANSIBLE_XO_HOST - user: - description: - - Xen Orchestra user. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_USER - password: - description: - - Xen Orchestra password. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_PASSWORD - validate_certs: - description: Verify TLS certificate if using HTTPS. - type: boolean - default: true - use_ssl: - description: Use wss when connecting to the Xen Orchestra API - type: boolean - default: true -''' - - -EXAMPLES = ''' + - API host to XOA API. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) + will be used instead. + type: str + env: + - name: ANSIBLE_XO_HOST + user: + description: + - Xen Orchestra user. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) + will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_USER + password: + description: + - Xen Orchestra password. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) + will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_PASSWORD + validate_certs: + description: Verify TLS certificate if using HTTPS. + type: boolean + default: true + use_ssl: + description: Use wss when connecting to the Xen Orchestra API. + type: boolean + default: true +""" + + +EXAMPLES = r""" # file must be named xen_orchestra.yaml or xen_orchestra.yml plugin: community.general.xen_orchestra api_host: 192.168.1.255 @@ -70,11 +74,10 @@ validate_certs: true use_ssl: true groups: - kube_nodes: "'kube_node' in tags" + kube_nodes: "'kube_node' in tags" compose: - ansible_port: 2222 - -''' + ansible_port: 2222 +""" import json import ssl From 16bd1e9dbb4f3429b546f38f76004cea4fad6c5a Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Tue, 7 Jan 2025 16:24:17 +1300 Subject: [PATCH 2/4] remove inventory plugins from PR --- plugins/inventory/cobbler.py | 208 ++++++------ plugins/inventory/gitlab_runners.py | 139 ++++---- plugins/inventory/icinga2.py | 129 ++++---- plugins/inventory/iocage.py | 201 ++++++------ plugins/inventory/linode.py | 234 +++++++------- plugins/inventory/lxd.py | 318 +++++++++---------- plugins/inventory/nmap.py | 223 +++++++------ plugins/inventory/online.py | 86 ++--- plugins/inventory/opennebula.py | 140 ++++---- plugins/inventory/proxmox.py | 424 ++++++++++++------------- plugins/inventory/scaleway.py | 196 ++++++------ plugins/inventory/stackpath_compute.py | 90 +++--- plugins/inventory/virtualbox.py | 113 ++++--- plugins/inventory/xen_orchestra.py | 121 ++++--- 14 files changed, 1299 insertions(+), 1323 deletions(-) diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index 3b0b7b56a01..7d65f583d65 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -6,118 +6,114 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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 - exclude_mgmt_classes: - description: Management classes to exclude from inventory. - type: list - default: [] - elements: str - version_added: 7.4.0 - exclude_profiles: +DOCUMENTATION = ''' + author: Orion Poplawski (@opoplawski) + name: cobbler + short_description: Cobbler inventory source + version_added: 1.0.0 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 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(cobbleer_ipv6_addresses) dictionary to the - defined O(group) mapping interface DNS names to IP addresses. - type: boolean - default: true - version_added: 7.1.0 -""" - -EXAMPLES = r""" + - 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 + 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 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(cobbleer_ipv6_addresses) dictionary to the defined O(group) mapping + interface DNS names to IP addresses. + type: boolean + default: true + version_added: 7.1.0 +''' + +EXAMPLES = ''' # my.cobbler.yml plugin: community.general.cobbler url: http://cobbler/cobbler_api user: ansible-tester password: secure -""" +''' import socket diff --git a/plugins/inventory/gitlab_runners.py b/plugins/inventory/gitlab_runners.py index a5d6125ed12..9a467905dd2 100644 --- a/plugins/inventory/gitlab_runners.py +++ b/plugins/inventory/gitlab_runners.py @@ -8,80 +8,77 @@ __metaclass__ = type -DOCUMENTATION = r""" -name: gitlab_runners -author: - - Stefan Heitmüller (@morph027) -short_description: Ansible dynamic inventory plugin for GitLab runners -requirements: - - python-gitlab > 1.8.0 -extends_documentation_fragment: - - constructed -description: - - Reads inventories from the GitLab API. - - Uses a YAML configuration file gitlab_runners.[yml|yaml]. -options: - plugin: - description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its - own. - type: str - required: true - choices: - - gitlab_runners - - community.general.gitlab_runners - server_url: - description: The URL of the GitLab server, with protocol (i.e. http or https). - env: - - name: GITLAB_SERVER_URL - version_added: 1.0.0 - type: str - required: true - api_token: - description: GitLab token for logging in. - env: - - name: GITLAB_API_TOKEN - version_added: 1.0.0 - type: str - aliases: - - private_token - - access_token - filter: - description: Filter runners from GitLab API. - env: - - name: GITLAB_FILTER - version_added: 1.0.0 - type: str - choices: ['active', 'paused', 'online', 'specific', 'shared'] - verbose_output: - description: Toggle to (not) include all available nodes metadata. - type: bool - default: true -""" +DOCUMENTATION = ''' + name: gitlab_runners + author: + - Stefan Heitmüller (@morph027) + short_description: Ansible dynamic inventory plugin for GitLab runners. + requirements: + - python-gitlab > 1.8.0 + extends_documentation_fragment: + - constructed + description: + - Reads inventories from the GitLab API. + - Uses a YAML configuration file gitlab_runners.[yml|yaml]. + options: + plugin: + description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own. + type: str + required: true + choices: + - gitlab_runners + - community.general.gitlab_runners + server_url: + description: The URL of the GitLab server, with protocol (i.e. http or https). + env: + - name: GITLAB_SERVER_URL + version_added: 1.0.0 + type: str + required: true + api_token: + description: GitLab token for logging in. + env: + - name: GITLAB_API_TOKEN + version_added: 1.0.0 + type: str + aliases: + - private_token + - access_token + filter: + description: filter runners from GitLab API + env: + - name: GITLAB_FILTER + version_added: 1.0.0 + type: str + choices: ['active', 'paused', 'online', 'specific', 'shared'] + verbose_output: + description: Toggle to (not) include all available nodes metadata + type: bool + default: true +''' -EXAMPLES = r""" +EXAMPLES = ''' # gitlab_runners.yml -- example 1: | - plugin: community.general.gitlab_runners - host: https://gitlab.com +plugin: community.general.gitlab_runners +host: https://gitlab.com -- example 2: |- - # Example using constructed features to create groups and set ansible_host - plugin: community.general.gitlab_runners - host: https://gitlab.com - strict: false - keyed_groups: - # add e.g. amd64 hosts to an arch_amd64 group - - prefix: arch - key: 'architecture' - # add e.g. linux hosts to an os_linux group - - prefix: os - key: 'platform' - # create a group per runner tag - # e.g. a runner tagged w/ "production" ends up in group "label_production" - # hint: labels containing special characters will be converted to safe names - - key: 'tag_list' - prefix: tag -""" +# Example using constructed features to create groups and set ansible_host +plugin: community.general.gitlab_runners +host: https://gitlab.com +strict: false +keyed_groups: + # add e.g. amd64 hosts to an arch_amd64 group + - prefix: arch + key: 'architecture' + # add e.g. linux hosts to an os_linux group + - prefix: os + key: 'platform' + # create a group per runner tag + # e.g. a runner tagged w/ "production" ends up in group "label_production" + # hint: labels containing special characters will be converted to safe names + - key: 'tag_list' + prefix: tag +''' from ansible.errors import AnsibleError, AnsibleParserError from ansible.plugins.inventory import BaseInventoryPlugin, Constructable diff --git a/plugins/inventory/icinga2.py b/plugins/inventory/icinga2.py index a383510dd73..527a3291732 100644 --- a/plugins/inventory/icinga2.py +++ b/plugins/inventory/icinga2.py @@ -7,70 +7,71 @@ __metaclass__ = type -DOCUMENTATION = r""" -name: icinga2 -short_description: Icinga2 inventory source -version_added: 3.7.0 -author: - - Cliff Hults (@BongoEADGC6) -description: - - Get inventory hosts from the Icinga2 API. - - Uses a configuration file as an inventory source, it must end in C(.icinga2.yml) or C(.icinga2.yaml). -extends_documentation_fragment: - - constructed -options: - strict: - version_added: 4.4.0 - compose: - version_added: 4.4.0 - groups: - version_added: 4.4.0 - keyed_groups: - version_added: 4.4.0 - plugin: - description: Name of the plugin. - required: true - type: string - choices: ['community.general.icinga2'] - url: - description: Root URL of Icinga2 API. - type: string - required: true - user: - description: Username to query the API. - type: string - required: true - password: - description: Password to query the API. - type: string - required: true - host_filter: +DOCUMENTATION = ''' + name: icinga2 + short_description: Icinga2 inventory source + version_added: 3.7.0 + author: + - Cliff Hults (@BongoEADGC6) 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""" + - 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 +''' + +EXAMPLES = r''' # my.icinga2.yml plugin: community.general.icinga2 url: http://localhost:5665 @@ -93,7 +94,7 @@ # set 'ansible_user' and 'ansible_port' from icinga2 host vars ansible_user: icinga2_attributes.vars.ansible_user ansible_port: icinga2_attributes.vars.ansible_port | default(22) -""" +''' import json diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py index e230ac8b415..5dc18b47100 100644 --- a/plugins/inventory/iocage.py +++ b/plugins/inventory/iocage.py @@ -7,106 +7,111 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r""" -name: iocage -short_description: iocage inventory source -version_added: 10.2.0 -author: - - Vladimir Botka (@vbotka) -requirements: - - iocage >= 1.8 -description: - - Get inventory hosts from the iocage jail manager running on O(host). - - By default, O(host) is V(localhost). If O(host) is not V(localhost) it is expected that the user running Ansible on the - controller can connect to the O(host) account O(user) with SSH non-interactively and execute the command C(iocage list). - - Uses a configuration file as an inventory source, it must end in C(.iocage.yml) or C(.iocage.yaml). -extends_documentation_fragment: - - ansible.builtin.constructed - - ansible.builtin.inventory_cache -options: - plugin: +DOCUMENTATION = ''' + name: iocage + short_description: iocage inventory source + version_added: 10.2.0 + author: + - Vladimir Botka (@vbotka) + requirements: + - iocage >= 1.8 description: - - The name of this plugin, it should always be set to V(community.general.iocage) for this plugin to recognize it as - its own. - required: true - choices: ['community.general.iocage'] - type: str - host: - description: The IP/hostname of the C(iocage) host. - type: str - default: localhost - user: - description: - - C(iocage) user. It is expected that the O(user) is able to connect to the O(host) with SSH and execute the command - C(iocage list). This option is not required if O(host) is V(localhost). - type: str - get_properties: - description: - - Get jails' properties. Creates dictionary C(iocage_properties) for each added host. - type: boolean - default: false - env: - description: O(user)'s environment on O(host). - type: dict - default: {} -notes: - - You might want to test the command C(ssh user@host iocage list -l) on the controller before using this inventory plugin - with O(user) specified and with O(host) other than V(localhost). - - If you run this inventory plugin on V(localhost) C(ssh) is not used. In this case, test the command C(iocage list -l). - - This inventory plugin creates variables C(iocage_*) for each added host. - - The values of these variables are collected from the output of the command C(iocage list -l). - - The names of these variables correspond to the output columns. - - The column C(NAME) is used to name the added host. -""" - -EXAMPLES = r""" + - Get inventory hosts from the iocage jail manager running on O(host). + - By default, O(host) is V(localhost). If O(host) is not V(localhost) it + is expected that the user running Ansible on the controller can + connect to the O(host) account O(user) with SSH non-interactively and + execute the command C(iocage list). + - Uses a configuration file as an inventory source, it must end + in C(.iocage.yml) or C(.iocage.yaml). + extends_documentation_fragment: + - ansible.builtin.constructed + - ansible.builtin.inventory_cache + options: + plugin: + description: + - The name of this plugin, it should always be set to + V(community.general.iocage) for this plugin to recognize + it as its own. + required: true + choices: ['community.general.iocage'] + type: str + host: + description: The IP/hostname of the C(iocage) host. + type: str + default: localhost + user: + description: + - C(iocage) user. + It is expected that the O(user) is able to connect to the + O(host) with SSH and execute the command C(iocage list). + This option is not required if O(host) is V(localhost). + type: str + get_properties: + description: + - Get jails' properties. + Creates dictionary C(iocage_properties) for each added host. + type: boolean + default: false + env: + description: O(user)'s environment on O(host). + type: dict + default: {} + notes: + - You might want to test the command C(ssh user@host iocage list -l) on + the controller before using this inventory plugin with O(user) specified + and with O(host) other than V(localhost). + - If you run this inventory plugin on V(localhost) C(ssh) is not used. + In this case, test the command C(iocage list -l). + - This inventory plugin creates variables C(iocage_*) for each added host. + - The values of these variables are collected from the output of the + command C(iocage list -l). + - The names of these variables correspond to the output columns. + - The column C(NAME) is used to name the added host. +''' + +EXAMPLES = ''' # file name must end with iocage.yaml or iocage.yml -- | - plugin: community.general.iocage - host: 10.1.0.73 - user: admin - -- | - # user is not required if iocage is running on localhost (default) - plugin: community.general.iocage - -- | - # run cryptography without legacy algorithms - plugin: community.general.iocage - host: 10.1.0.73 - user: admin - env: - CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 - -- | - # enable cache - plugin: community.general.iocage - host: 10.1.0.73 - user: admin - env: - CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 - cache: true - -- |- - # see inventory plugin ansible.builtin.constructed - plugin: community.general.iocage - host: 10.1.0.73 - user: admin - env: - CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 - cache: true - strict: false - compose: - ansible_host: iocage_ip4 - release: iocage_release | split('-') | first - groups: - test: inventory_hostname.startswith('test') - keyed_groups: - - prefix: distro - key: iocage_release - - prefix: state - key: iocage_state -""" +plugin: community.general.iocage +host: 10.1.0.73 +user: admin + +# user is not required if iocage is running on localhost (default) +plugin: community.general.iocage + +# run cryptography without legacy algorithms +plugin: community.general.iocage +host: 10.1.0.73 +user: admin +env: + CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 + +# enable cache +plugin: community.general.iocage +host: 10.1.0.73 +user: admin +env: + CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 +cache: true + +# see inventory plugin ansible.builtin.constructed +plugin: community.general.iocage +host: 10.1.0.73 +user: admin +env: + CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1 +cache: true +strict: false +compose: + ansible_host: iocage_ip4 + release: iocage_release | split('-') | first +groups: + test: inventory_hostname.startswith('test') +keyed_groups: + - prefix: distro + key: iocage_release + - prefix: state + key: iocage_state +''' import re import os diff --git a/plugins/inventory/linode.py b/plugins/inventory/linode.py index 7ed3db3b359..46f2faeacea 100644 --- a/plugins/inventory/linode.py +++ b/plugins/inventory/linode.py @@ -6,125 +6,121 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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""" -- | - # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. - plugin: community.general.linode - -- | - # You can use Jinja to template the access token. - plugin: community.general.linode - access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}" - # For older Ansible versions, you need to write this as: - # access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}" - -- | - # Example with regions, types, groups and access token - plugin: community.general.linode - access_token: foobar - regions: - - eu-west - types: - - g5-standard-2 - -- | - # Example with keyed_groups, groups, and compose - plugin: community.general.linode - access_token: foobar - keyed_groups: - - key: tags - separator: '' - - key: region - prefix: region - groups: - webservers: "'web' in (tags|list)" - mailservers: "'mail' in (tags|list)" - compose: - # By default, Ansible tries to connect to the label of the instance. - # Since that might not be a valid name to connect to, you can - # replace it with the first IPv4 address of the linode as follows: - ansible_ssh_host: ipv4[0] - ansible_port: 2222 - -- |- - # Example where control traffic limited to internal network - plugin: community.general.linode - access_token: foobar - ip_style: api - compose: - ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first" -""" +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''' +# Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment. +plugin: community.general.linode + +# You can use Jinja to template the access token. +plugin: community.general.linode +access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}" +# For older Ansible versions, you need to write this as: +# access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}" + +# Example with regions, types, groups and access token +plugin: community.general.linode +access_token: foobar +regions: + - eu-west +types: + - g5-standard-2 + +# Example with keyed_groups, groups, and compose +plugin: community.general.linode +access_token: foobar +keyed_groups: + - key: tags + separator: '' + - key: region + prefix: region +groups: + webservers: "'web' in (tags|list)" + mailservers: "'mail' in (tags|list)" +compose: + # By default, Ansible tries to connect to the label of the instance. + # Since that might not be a valid name to connect to, you can + # replace it with the first IPv4 address of the linode as follows: + ansible_ssh_host: ipv4[0] + ansible_port: 2222 + +# Example where control traffic limited to internal network +plugin: community.general.linode +access_token: foobar +ip_style: api +compose: + ansible_host: "ipv4 | community.general.json_query('[?public==`false`].address') | first" +''' from ansible.errors import AnsibleError from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py index d996cc5b27f..d7b942c1f78 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -6,168 +6,164 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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: +DOCUMENTATION = r''' + name: lxd + short_description: Returns Ansible inventory from lxd host description: - - The unix domain socket path or the https URL for the lxd server. - - Sockets in filesystem have to start with C(unix:). - - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). - type: string - default: unix:/var/snap/lxd/common/lxd/unix.socket - client_key: - description: - - The client certificate key file path. - aliases: [key_file] - default: $HOME/.config/lxc/client.key - type: path - client_cert: - description: - - The client certificate file path. - aliases: [cert_file] - default: $HOME/.config/lxc/client.crt - type: path - server_cert: - description: - - The server certificate file path. - type: path - version_added: 8.0.0 - server_check_hostname: - description: - - This option controls if the server's hostname is checked as part of the HTTPS connection verification. This can be - useful to disable, if for example, the server certificate provided (see O(server_cert) option) does not cover a name - matching the one used to communicate with the server. Such mismatch is common as LXD generates self-signed server - certificates by default. - type: bool - default: true - version_added: 8.0.0 - trust_password: - description: - - The client trusted password. - - You need to set this password on the lxd server before running this module using the following command C(lxc config - set core.trust_password ) See - U(https://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). - - If O(trust_password) is set, this module send a request for authentication before sending any requests. - type: str - state: - description: Filter the instance according to the current status. - type: str - default: none - choices: ['STOPPED', 'STARTING', 'RUNNING', 'none'] - project: - description: Filter the instance according to the given project. - type: str - default: default - version_added: 6.2.0 - type_filter: - description: - - Filter the instances by type V(virtual-machine), V(container) or V(both). - - The first version of the inventory only supported containers. - type: str - default: container - choices: ['virtual-machine', 'container', 'both'] - version_added: 4.2.0 - prefered_instance_network_interface: - description: - - If an instance has multiple network interfaces, select which one is the preferred as pattern. - - Combined with the first number that can be found, for example V(eth0). - - 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 = r""" -- | - # simple lxd.yml - plugin: community.general.lxd - url: unix:/var/snap/lxd/common/lxd/unix.socket - -- | - # simple lxd.yml including filter - plugin: community.general.lxd - url: unix:/var/snap/lxd/common/lxd/unix.socket - state: RUNNING - -- | - # simple lxd.yml including virtual machines and containers - plugin: community.general.lxd - url: unix:/var/snap/lxd/common/lxd/unix.socket - type_filter: both - -- |- - # grouping lxd.yml - groupby: - locationBerlin: - type: location - attribute: Berlin - netRangeIPv4: - type: network_range - attribute: 10.98.143.0/24 - netRangeIPv6: - type: network_range - attribute: fd42:bd00:7b11:2167:216:3eff::/24 - osUbuntu: - type: os - attribute: ubuntu - testpattern: - type: pattern - attribute: test - profileDefault: - type: profile - attribute: default - profileX11: - type: profile - attribute: x11 - releaseFocal: - type: release - attribute: focal - releaseBionic: - type: release - attribute: bionic - typeVM: - type: type - attribute: virtual-machine - typeContainer: - type: type - attribute: container - vlan666: - type: vlanid - attribute: 666 - projectInternals: - type: project - attribute: internals -""" + - Get inventory from the lxd. + - Uses a YAML configuration file that ends with 'lxd.(yml|yaml)'. + version_added: "3.0.0" + author: "Frank Dornheim (@conloos)" + requirements: + - ipaddress + - lxd >= 4.0 + options: + plugin: + description: Token that ensures this is a source file for the 'lxd' plugin. + type: string + required: true + choices: [ 'community.general.lxd' ] + url: + description: + - The unix domain socket path or the https URL for the lxd server. + - Sockets in filesystem have to start with C(unix:). + - Mostly C(unix:/var/lib/lxd/unix.socket) or C(unix:/var/snap/lxd/common/lxd/unix.socket). + type: string + default: unix:/var/snap/lxd/common/lxd/unix.socket + client_key: + description: + - The client certificate key file path. + aliases: [ key_file ] + default: $HOME/.config/lxc/client.key + type: path + client_cert: + description: + - The client certificate file path. + aliases: [ cert_file ] + default: $HOME/.config/lxc/client.crt + type: path + server_cert: + description: + - The server certificate file path. + type: path + version_added: 8.0.0 + server_check_hostname: + description: + - This option controls if the server's hostname is checked as part of the HTTPS connection verification. + This can be useful to disable, if for example, the server certificate provided (see O(server_cert) option) + does not cover a name matching the one used to communicate with the server. Such mismatch is common as LXD + generates self-signed server certificates by default. + type: bool + default: true + version_added: 8.0.0 + trust_password: + description: + - The client trusted password. + - You need to set this password on the lxd server before + running this module using the following command + C(lxc config set core.trust_password ) + See U(https://documentation.ubuntu.com/lxd/en/latest/authentication/#adding-client-certificates-using-a-trust-password). + - If O(trust_password) is set, this module send a request for authentication before sending any requests. + type: str + state: + description: Filter the instance according to the current status. + type: str + default: none + choices: [ 'STOPPED', 'STARTING', 'RUNNING', 'none' ] + project: + description: Filter the instance according to the given project. + type: str + default: default + version_added: 6.2.0 + type_filter: + description: + - Filter the instances by type V(virtual-machine), V(container) or V(both). + - The first version of the inventory only supported containers. + type: str + default: container + choices: [ 'virtual-machine', 'container', 'both' ] + version_added: 4.2.0 + prefered_instance_network_interface: + description: + - If an instance has multiple network interfaces, select which one is the preferred as pattern. + - Combined with the first number that can be found e.g. 'eth' + 0. + - The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface) + in community.general 3.8.0. The old name still works as an alias. + type: str + default: eth + aliases: + - prefered_container_network_interface + prefered_instance_network_family: + description: + - If an instance has multiple network interfaces, which one is the preferred by family. + - Specify V(inet) for IPv4 and V(inet6) for IPv6. + type: str + default: inet + choices: [ 'inet', 'inet6' ] + groupby: + description: + - Create groups by the following keywords C(location), C(network_range), C(os), C(pattern), C(profile), C(release), C(type), C(vlanid). + - See example for syntax. + type: dict +''' + +EXAMPLES = ''' +# simple lxd.yml +plugin: community.general.lxd +url: unix:/var/snap/lxd/common/lxd/unix.socket + +# simple lxd.yml including filter +plugin: community.general.lxd +url: unix:/var/snap/lxd/common/lxd/unix.socket +state: RUNNING + +# simple lxd.yml including virtual machines and containers +plugin: community.general.lxd +url: unix:/var/snap/lxd/common/lxd/unix.socket +type_filter: both + +# grouping lxd.yml +groupby: + locationBerlin: + type: location + attribute: Berlin + netRangeIPv4: + type: network_range + attribute: 10.98.143.0/24 + netRangeIPv6: + type: network_range + attribute: fd42:bd00:7b11:2167:216:3eff::/24 + osUbuntu: + type: os + attribute: ubuntu + testpattern: + type: pattern + attribute: test + profileDefault: + type: profile + attribute: default + profileX11: + type: profile + attribute: x11 + releaseFocal: + type: release + attribute: focal + releaseBionic: + type: release + attribute: bionic + typeVM: + type: type + attribute: virtual-machine + typeContainer: + type: type + attribute: container + vlan666: + type: vlanid + attribute: 666 + projectInternals: + type: project + attribute: internals +''' import json import re diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py index b3822dedf0d..f40f33b972e 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -6,120 +6,117 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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: +DOCUMENTATION = ''' + author: Unknown (!UNKNOWN) + name: nmap + short_description: Uses nmap to find hosts to target 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 using 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 using 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 - 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 - strict: false - address: 192.168.0.0/24 - - -- | - # a sudo nmap scan to fully use nmap scan power. - plugin: community.general.nmap - sudo: true - strict: false - address: 192.168.0.0/24 - -- |- - # an nmap scan specifying ports and classifying results to an inventory group - plugin: community.general.nmap - address: 192.168.0.0/24 - exclude: 192.168.0.1, web.example.com - port: 22, 443 - groups: - web_servers: "ports | selectattr('port', 'equalto', '443')" -""" + - 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 + 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 +plugin: community.general.nmap +strict: false +address: 192.168.0.0/24 + + +# a sudo nmap scan to fully use nmap scan power. +plugin: community.general.nmap +sudo: true +strict: false +address: 192.168.0.0/24 + +# an nmap scan specifying ports and classifying results to an inventory group +plugin: community.general.nmap +address: 192.168.0.0/24 +exclude: 192.168.0.1, web.example.com +port: 22, 443 +groups: + web_servers: "ports | selectattr('port', 'equalto', '443')" +''' import os import re diff --git a/plugins/inventory/online.py b/plugins/inventory/online.py index b320d308956..9475049c089 100644 --- a/plugins/inventory/online.py +++ b/plugins/inventory/online.py @@ -6,49 +6,49 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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: +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""" + - 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''' # online_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i online_inventory.yml @@ -59,7 +59,7 @@ - location - offer - rpn -""" +''' import json from sys import version as python_version diff --git a/plugins/inventory/opennebula.py b/plugins/inventory/opennebula.py index 84915752801..7fc320f3268 100644 --- a/plugins/inventory/opennebula.py +++ b/plugins/inventory/opennebula.py @@ -7,75 +7,77 @@ __metaclass__ = type -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: +DOCUMENTATION = r''' + name: opennebula + author: + - Kristian Feldsam (@feldsam) + short_description: OpenNebula inventory source + version_added: "3.8.0" + extends_documentation_fragment: + - constructed 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 -""" - -EXAMPLES = r""" + - 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 +''' + +EXAMPLES = r''' # inventory_opennebula.yml file in YAML format # Example command line: ansible-inventory --list -i inventory_opennebula.yml @@ -83,7 +85,7 @@ plugin: community.general.opennebula api_url: https://opennebula:2633/RPC2 filter_by_label: Cache -""" +''' try: import pyone diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index 952cdc6df22..cf25efc58c8 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -7,225 +7,213 @@ __metaclass__ = type -DOCUMENTATION = r""" -name: proxmox -short_description: Proxmox inventory source -version_added: "1.2.0" -author: - - Jeffrey van Pelt (@Thulium-Drake) -requirements: - - requests >= 1.1 -description: - - Get inventory hosts from a Proxmox PVE cluster. - - Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml). - - Will retrieve the first network interface with an IP for Proxmox nodes. - - Can retrieve LXC/QEMU configuration as facts. -extends_documentation_fragment: - - constructed - - inventory_cache -options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize - it as its own. - required: true - choices: ['community.general.proxmox'] - type: str - url: +DOCUMENTATION = ''' + name: proxmox + short_description: Proxmox inventory source + version_added: "1.2.0" + author: + - Jeffrey van Pelt (@Thulium-Drake) + requirements: + - requests >= 1.1 description: - - URL to Proxmox cluster. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_URL) will - be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the O(url). - default: 'http://localhost:8006' - type: str - env: - - name: PROXMOX_URL - version_added: 2.0.0 - user: - description: - - Proxmox authentication user. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_USER) will - be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the O(user). - required: true - type: str - env: - - name: PROXMOX_USER - version_added: 2.0.0 - password: - description: - - Proxmox authentication password. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_PASSWORD) - will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the O(password). - - If you do not specify a password, you must set O(token_id) and O(token_secret) instead. - type: str - env: - - name: PROXMOX_PASSWORD - version_added: 2.0.0 - token_id: - description: - - Proxmox authentication token ID. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_ID) - will be used instead. - - To use token authentication, you must also specify O(token_secret). If you do not specify O(token_id) and O(token_secret), - you must set a password instead. - - Make sure to grant explicit pve permissions to the token or disable 'privilege separation' to use the users' privileges - instead. - version_added: 4.8.0 - type: str - env: - - name: PROXMOX_TOKEN_ID - token_secret: - description: - - Proxmox authentication token secret. - - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_SECRET) - will be used instead. - - To use token authentication, you must also specify O(token_id). If you do not specify O(token_id) and O(token_secret), - you must set a password instead. - version_added: 4.8.0 - type: str - env: - - name: PROXMOX_TOKEN_SECRET - validate_certs: - description: Verify SSL certificate if using HTTPS. - type: boolean - default: true - group_prefix: - description: Prefix to apply to Proxmox groups. - default: proxmox_ - type: str - facts_prefix: - description: Prefix to apply to LXC/QEMU config facts. - default: proxmox_ - type: str - want_facts: - description: - - Gather LXC/QEMU configuration facts. - - When O(want_facts) is set to V(true) more details about QEMU VM status are possible, besides the running and stopped - states. Currently if the VM is running and it is suspended, the status will be running and the machine will be in - C(running) group, but its actual state will be paused. See O(qemu_extended_statuses) for how to retrieve the real - status. - default: false - type: bool - qemu_extended_statuses: - description: - - Requires O(want_facts) to be set to V(true) to function. This will allow you to differentiate between C(paused) and - C(prelaunch) statuses of the QEMU VMs. - - This introduces multiple groups [prefixed with O(group_prefix)] C(prelaunch) and C(paused). - default: false - type: bool - version_added: 5.1.0 - want_proxmox_nodes_ansible_host: - version_added: 3.0.0 - description: - - Whether to set C(ansible_host) for proxmox nodes. - - When set to V(true) (default), will use the first available interface. This can be different from what you expect. - - The default of this option changed from V(true) to V(false) in community.general 6.0.0. - type: bool - default: false - exclude_nodes: - description: Exclude proxmox nodes and the nodes-group from the inventory output. - type: bool - default: false - version_added: 8.1.0 - filters: - version_added: 4.6.0 - description: A list of Jinja templates that allow filtering hosts. - type: list - elements: str - default: [] - strict: - version_added: 2.5.0 - compose: - version_added: 2.5.0 - groups: - version_added: 2.5.0 - keyed_groups: - version_added: 2.5.0 -""" - -EXAMPLES = r""" -- | - # Minimal example which will not gather additional facts for QEMU/LXC guests - # By not specifying a URL the plugin will attempt to connect to the controller host on port 8006 - # my.proxmox.yml - plugin: community.general.proxmox - user: ansible@pve - password: secure - # Note that this can easily give you wrong values as ansible_host. See further below for - # an example where this is set to `false` and where ansible_host is set with `compose`. - want_proxmox_nodes_ansible_host: true - -- | - # Instead of login with password, proxmox supports api token authentication since release 6.2. - plugin: community.general.proxmox - user: ci@pve - token_id: gitlab-1 - token_secret: fa256e9c-26ab-41ec-82da-707a2c079829 - - # The secret can also be a vault string or passed via the environment variable TOKEN_SECRET. - token_secret: !vault | - $ANSIBLE_VAULT;1.1;AES256 - 62353634333163633336343265623632626339313032653563653165313262343931643431656138 - 6134333736323265656466646539663134306166666237630a653363623262636663333762316136 - 34616361326263383766366663393837626437316462313332663736623066656237386531663731 - 3037646432383064630a663165303564623338666131353366373630656661333437393937343331 - 32643131386134396336623736393634373936356332623632306561356361323737313663633633 - 6231313333666361656537343562333337323030623732323833 - -- | - # More complete example demonstrating the use of 'want_facts' and the constructed options - # Note that using facts returned by 'want_facts' in constructed options requires 'want_facts=true' - # my.proxmox.yml - plugin: community.general.proxmox - url: http://pve.domain.com:8006 - user: ansible@pve - password: secure - want_facts: true - keyed_groups: - # proxmox_tags_parsed is an example of a fact only returned when 'want_facts=true' - - key: proxmox_tags_parsed - separator: "" - prefix: group - groups: - webservers: "'web' in (proxmox_tags_parsed|list)" - mailservers: "'mail' in (proxmox_tags_parsed|list)" - compose: - ansible_port: 2222 - # Note that this can easily give you wrong values as ansible_host. See further below for - # an example where this is set to `false` and where ansible_host is set with `compose`. - want_proxmox_nodes_ansible_host: true - -- | - # Using the inventory to allow ansible to connect via the first IP address of the VM / Container - # (Default is connection by name of QEMU/LXC guests) - # Note: my_inv_var demonstrates how to add a string variable to every host used by the inventory. - # my.proxmox.yml - plugin: community.general.proxmox - url: http://192.168.1.2:8006 - user: ansible@pve - password: secure - validate_certs: false # only do this when you trust the network! - want_facts: true - want_proxmox_nodes_ansible_host: false - compose: - ansible_host: proxmox_ipconfig0.ip | default(proxmox_net0.ip) | ipaddr('address') - my_inv_var_1: "'my_var1_value'" - my_inv_var_2: > - "my_var_2_value" - -- |- - # Specify the url, user and password using templating - # my.proxmox.yml - plugin: community.general.proxmox - url: "{{ lookup('ansible.builtin.ini', 'url', section='proxmox', file='file.ini') }}" - user: "{{ lookup('ansible.builtin.env','PM_USER') | default('ansible@pve') }}" - password: "{{ lookup('community.general.random_string', base64=True) }}" - # Note that this can easily give you wrong values as ansible_host. See further up for - # an example where this is set to `false` and where ansible_host is set with `compose`. - want_proxmox_nodes_ansible_host: true -""" + - Get inventory hosts from a Proxmox PVE cluster. + - "Uses a configuration file as an inventory source, it must end in C(.proxmox.yml) or C(.proxmox.yaml)" + - Will retrieve the first network interface with an IP for Proxmox nodes. + - Can retrieve LXC/QEMU configuration as facts. + extends_documentation_fragment: + - constructed + - inventory_cache + options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as its own. + required: true + choices: ['community.general.proxmox'] + type: str + url: + description: + - URL to Proxmox cluster. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_URL) will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(url). + default: 'http://localhost:8006' + type: str + env: + - name: PROXMOX_URL + version_added: 2.0.0 + user: + description: + - Proxmox authentication user. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_USER) will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(user). + required: true + type: str + env: + - name: PROXMOX_USER + version_added: 2.0.0 + password: + description: + - Proxmox authentication password. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_PASSWORD) will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(password). + - If you do not specify a password, you must set O(token_id) and O(token_secret) instead. + type: str + env: + - name: PROXMOX_PASSWORD + version_added: 2.0.0 + token_id: + description: + - Proxmox authentication token ID. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_ID) will be used instead. + - To use token authentication, you must also specify O(token_secret). If you do not specify O(token_id) and O(token_secret), + you must set a password instead. + - Make sure to grant explicit pve permissions to the token or disable 'privilege separation' to use the users' privileges instead. + version_added: 4.8.0 + type: str + env: + - name: PROXMOX_TOKEN_ID + token_secret: + description: + - Proxmox authentication token secret. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_SECRET) will be used instead. + - To use token authentication, you must also specify O(token_id). If you do not specify O(token_id) and O(token_secret), + you must set a password instead. + version_added: 4.8.0 + type: str + env: + - name: PROXMOX_TOKEN_SECRET + validate_certs: + description: Verify SSL certificate if using HTTPS. + type: boolean + default: true + group_prefix: + description: Prefix to apply to Proxmox groups. + default: proxmox_ + type: str + facts_prefix: + description: Prefix to apply to LXC/QEMU config facts. + default: proxmox_ + type: str + want_facts: + description: + - Gather LXC/QEMU configuration facts. + - When O(want_facts) is set to V(true) more details about QEMU VM status are possible, besides the running and stopped states. + Currently if the VM is running and it is suspended, the status will be running and the machine will be in C(running) group, + but its actual state will be paused. See O(qemu_extended_statuses) for how to retrieve the real status. + default: false + type: bool + qemu_extended_statuses: + description: + - Requires O(want_facts) to be set to V(true) to function. This will allow you to differentiate between C(paused) and C(prelaunch) + statuses of the QEMU VMs. + - This introduces multiple groups [prefixed with O(group_prefix)] C(prelaunch) and C(paused). + default: false + type: bool + version_added: 5.1.0 + want_proxmox_nodes_ansible_host: + version_added: 3.0.0 + description: + - Whether to set C(ansible_host) for proxmox nodes. + - When set to V(true) (default), will use the first available interface. This can be different from what you expect. + - The default of this option changed from V(true) to V(false) in community.general 6.0.0. + type: bool + default: false + exclude_nodes: + description: Exclude proxmox nodes and the nodes-group from the inventory output. + type: bool + default: false + version_added: 8.1.0 + filters: + version_added: 4.6.0 + description: A list of Jinja templates that allow filtering hosts. + type: list + elements: str + default: [] + strict: + version_added: 2.5.0 + compose: + version_added: 2.5.0 + groups: + version_added: 2.5.0 + keyed_groups: + version_added: 2.5.0 +''' + +EXAMPLES = ''' +# Minimal example which will not gather additional facts for QEMU/LXC guests +# By not specifying a URL the plugin will attempt to connect to the controller host on port 8006 +# my.proxmox.yml +plugin: community.general.proxmox +user: ansible@pve +password: secure +# Note that this can easily give you wrong values as ansible_host. See further below for +# an example where this is set to `false` and where ansible_host is set with `compose`. +want_proxmox_nodes_ansible_host: true + +# Instead of login with password, proxmox supports api token authentication since release 6.2. +plugin: community.general.proxmox +user: ci@pve +token_id: gitlab-1 +token_secret: fa256e9c-26ab-41ec-82da-707a2c079829 + +# The secret can also be a vault string or passed via the environment variable TOKEN_SECRET. +token_secret: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 62353634333163633336343265623632626339313032653563653165313262343931643431656138 + 6134333736323265656466646539663134306166666237630a653363623262636663333762316136 + 34616361326263383766366663393837626437316462313332663736623066656237386531663731 + 3037646432383064630a663165303564623338666131353366373630656661333437393937343331 + 32643131386134396336623736393634373936356332623632306561356361323737313663633633 + 6231313333666361656537343562333337323030623732323833 + +# More complete example demonstrating the use of 'want_facts' and the constructed options +# Note that using facts returned by 'want_facts' in constructed options requires 'want_facts=true' +# my.proxmox.yml +plugin: community.general.proxmox +url: http://pve.domain.com:8006 +user: ansible@pve +password: secure +want_facts: true +keyed_groups: + # proxmox_tags_parsed is an example of a fact only returned when 'want_facts=true' + - key: proxmox_tags_parsed + separator: "" + prefix: group +groups: + webservers: "'web' in (proxmox_tags_parsed|list)" + mailservers: "'mail' in (proxmox_tags_parsed|list)" +compose: + ansible_port: 2222 +# Note that this can easily give you wrong values as ansible_host. See further below for +# an example where this is set to `false` and where ansible_host is set with `compose`. +want_proxmox_nodes_ansible_host: true + +# Using the inventory to allow ansible to connect via the first IP address of the VM / Container +# (Default is connection by name of QEMU/LXC guests) +# Note: my_inv_var demonstrates how to add a string variable to every host used by the inventory. +# my.proxmox.yml +plugin: community.general.proxmox +url: http://192.168.1.2:8006 +user: ansible@pve +password: secure +validate_certs: false # only do this when you trust the network! +want_facts: true +want_proxmox_nodes_ansible_host: false +compose: + ansible_host: proxmox_ipconfig0.ip | default(proxmox_net0.ip) | ipaddr('address') + my_inv_var_1: "'my_var1_value'" + my_inv_var_2: > + "my_var_2_value" + +# Specify the url, user and password using templating +# my.proxmox.yml +plugin: community.general.proxmox +url: "{{ lookup('ansible.builtin.ini', 'url', section='proxmox', file='file.ini') }}" +user: "{{ lookup('ansible.builtin.env','PM_USER') | default('ansible@pve') }}" +password: "{{ lookup('community.general.random_string', base64=True) }}" +# Note that this can easily give you wrong values as ansible_host. See further up for +# an example where this is set to `false` and where ansible_host is set with `compose`. +want_proxmox_nodes_ansible_host: true + +''' import itertools import re diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index 990504fe8c1..9a40243ee77 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -7,110 +7,108 @@ __metaclass__ = type -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: +DOCUMENTATION = r''' + name: scaleway + author: + - Remy Leone (@remyleone) + short_description: Scaleway inventory source 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: + - 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 -""" - -EXAMPLES = r""" + - 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''' # scaleway_inventory.yml file in YAML format # Example command line: ansible-inventory --list -i scaleway_inventory.yml -- | - # use hostname as inventory_hostname - # use the private IP address to connect to the host - plugin: community.general.scaleway - regions: - - ams1 - - par1 - tags: - - foobar - hostnames: - - hostname - variables: - ansible_host: private_ip - state: state - -- | - # use hostname as inventory_hostname and public IP address to connect to the host - plugin: community.general.scaleway - hostnames: - - hostname - regions: - - par1 - variables: - ansible_host: public_ip.address - -- | - # Using static strings as variables - plugin: community.general.scaleway - hostnames: - - hostname - variables: - ansible_host: public_ip.address - ansible_connection: "'ssh'" - ansible_user: "'admin'" -""" +# use hostname as inventory_hostname +# use the private IP address to connect to the host +plugin: community.general.scaleway +regions: + - ams1 + - par1 +tags: + - foobar +hostnames: + - hostname +variables: + ansible_host: private_ip + state: state + +# use hostname as inventory_hostname and public IP address to connect to the host +plugin: community.general.scaleway +hostnames: + - hostname +regions: + - par1 +variables: + ansible_host: public_ip.address + +# Using static strings as variables +plugin: community.general.scaleway +hostnames: + - hostname +variables: + ansible_host: public_ip.address + ansible_connection: "'ssh'" + ansible_user: "'admin'" +''' import os import json diff --git a/plugins/inventory/stackpath_compute.py b/plugins/inventory/stackpath_compute.py index 34b9391800a..c87d0e52776 100644 --- a/plugins/inventory/stackpath_compute.py +++ b/plugins/inventory/stackpath_compute.py @@ -7,56 +7,60 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r""" -name: stackpath_compute -short_description: StackPath Edge Computing inventory source -version_added: 1.2.0 -author: - - UNKNOWN (@shayrybak) -extends_documentation_fragment: - - inventory_cache - - constructed -description: - - Get inventory hosts from StackPath Edge Computing. - - Uses a YAML configuration file that ends with stackpath_compute.(yml|yaml). -options: - plugin: +DOCUMENTATION = ''' + name: stackpath_compute + short_description: StackPath Edge Computing inventory source + version_added: 1.2.0 + author: + - UNKNOWN (@shayrybak) + extends_documentation_fragment: + - inventory_cache + - constructed description: - - A token that ensures this is a source file for the plugin. - required: true - type: string - choices: ['community.general.stackpath_compute'] - client_id: - description: - - An OAuth client ID generated from the API Management section of the StackPath customer portal U(https://control.stackpath.net/api-management). - required: true - type: str - client_secret: - description: - - An OAuth client secret generated from the API Management section of the StackPath customer portal U(https://control.stackpath.net/api-management). - required: true - type: str - stack_slugs: - description: - - A list of Stack slugs to query instances in. If no entry then get instances in all stacks on the account. - type: list - elements: str - use_internal_ip: - description: - - Whether or not to use internal IP addresses, If false, uses external IP addresses, internal otherwise. - - If an instance does not have an external IP it will not be returned when this option is set to false. - type: bool -""" + - Get inventory hosts from StackPath Edge Computing. + - Uses a YAML configuration file that ends with stackpath_compute.(yml|yaml). + options: + plugin: + description: + - A token that ensures this is a source file for the plugin. + required: true + type: string + choices: ['community.general.stackpath_compute'] + client_id: + description: + - An OAuth client ID generated from the API Management section of the StackPath customer portal + U(https://control.stackpath.net/api-management). + required: true + type: str + client_secret: + description: + - An OAuth client secret generated from the API Management section of the StackPath customer portal + U(https://control.stackpath.net/api-management). + required: true + type: str + stack_slugs: + description: + - A list of Stack slugs to query instances in. If no entry then get instances in all stacks on the account. + type: list + elements: str + use_internal_ip: + description: + - Whether or not to use internal IP addresses, If false, uses external IP addresses, internal otherwise. + - If an instance doesn't have an external IP it will not be returned when this option is set to false. + type: bool +''' -EXAMPLES = r""" +EXAMPLES = ''' +# Example using credentials to fetch all workload instances in a stack. +--- plugin: community.general.stackpath_compute client_id: my_client_id client_secret: my_client_secret stack_slugs: - - my_first_stack_slug - - my_other_stack_slug +- my_first_stack_slug +- my_other_stack_slug use_internal_ip: false -""" +''' import traceback import json diff --git a/plugins/inventory/virtualbox.py b/plugins/inventory/virtualbox.py index 11187beae7f..b0545319a1c 100644 --- a/plugins/inventory/virtualbox.py +++ b/plugins/inventory/virtualbox.py @@ -6,71 +6,70 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -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 between showing all VMs or 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: +DOCUMENTATION = ''' + author: Unknown (!UNKNOWN) + name: virtualbox + short_description: virtualbox inventory source 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 = r""" + - 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 +''' + +EXAMPLES = ''' # file must be named vbox.yaml or vbox.yml simple_config_file: - plugin: community.general.virtualbox - settings_password_file: /etc/virtulbox/secrets - query: - logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList - compose: - ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh') + plugin: community.general.virtualbox + settings_password_file: /etc/virtulbox/secrets + query: + logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList + compose: + ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh') # add hosts (all match with minishift vm) to the group container if any of the vms are in ansible_inventory' plugin: community.general.virtualbox groups: container: "'minis' in (inventory_hostname)" -""" +''' import os diff --git a/plugins/inventory/xen_orchestra.py b/plugins/inventory/xen_orchestra.py index bf7b4b1cb5c..0a050d0bf9b 100644 --- a/plugins/inventory/xen_orchestra.py +++ b/plugins/inventory/xen_orchestra.py @@ -6,66 +6,62 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r""" -name: xen_orchestra -short_description: Xen Orchestra inventory source -version_added: 4.1.0 -author: - - Dom Del Nano (@ddelnano) - - Samori Gorse (@shinuza) -requirements: - - websocket-client >= 1.0.0 -description: - - Get inventory hosts from a Xen Orchestra deployment. - - Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml). -extends_documentation_fragment: - - constructed - - inventory_cache -options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to - recognize it as its own. - required: true - choices: ['community.general.xen_orchestra'] - type: str - api_host: +DOCUMENTATION = ''' + name: xen_orchestra + short_description: Xen Orchestra inventory source + version_added: 4.1.0 + author: + - Dom Del Nano (@ddelnano) + - Samori Gorse (@shinuza) + requirements: + - websocket-client >= 1.0.0 description: - - API host to XOA API. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) - will be used instead. - type: str - env: - - name: ANSIBLE_XO_HOST - user: - description: - - Xen Orchestra user. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) - will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_USER - password: - description: - - Xen Orchestra password. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) - will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_PASSWORD - validate_certs: - description: Verify TLS certificate if using HTTPS. - type: boolean - default: true - use_ssl: - description: Use wss when connecting to the Xen Orchestra API. - type: boolean - default: true -""" - - -EXAMPLES = r""" + - Get inventory hosts from a Xen Orchestra deployment. + - 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).' + extends_documentation_fragment: + - constructed + - inventory_cache + options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own. + required: true + choices: ['community.general.xen_orchestra'] + type: str + api_host: + description: + - API host to XOA API. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. + type: str + env: + - name: ANSIBLE_XO_HOST + user: + description: + - Xen Orchestra user. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_USER + password: + description: + - Xen Orchestra password. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_PASSWORD + validate_certs: + description: Verify TLS certificate if using HTTPS. + type: boolean + default: true + use_ssl: + description: Use wss when connecting to the Xen Orchestra API + type: boolean + default: true +''' + + +EXAMPLES = ''' # file must be named xen_orchestra.yaml or xen_orchestra.yml plugin: community.general.xen_orchestra api_host: 192.168.1.255 @@ -74,10 +70,11 @@ validate_certs: true use_ssl: true groups: - kube_nodes: "'kube_node' in tags" + kube_nodes: "'kube_node' in tags" compose: - ansible_port: 2222 -""" + ansible_port: 2222 + +''' import json import ssl From a4c74675ea9db8c848cbd7b18362c9e0a25a3dac Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Tue, 7 Jan 2025 16:34:39 +1300 Subject: [PATCH 3/4] adjustments from review --- plugins/filter/remove_keys.py | 18 +++++++++--------- plugins/filter/replace_keys.py | 14 +++++++------- plugins/filter/reveal_ansible_type.py | 26 +++++++++++++------------- 3 files changed, 29 insertions(+), 29 deletions(-) diff --git a/plugins/filter/remove_keys.py b/plugins/filter/remove_keys.py index d2e6282ea9f..b7d05cc8040 100644 --- a/plugins/filter/remove_keys.py +++ b/plugins/filter/remove_keys.py @@ -49,23 +49,23 @@ # 1) By default match keys that equal any of the items in the target. - t: [k0_x0, k1_x1] -- r: "{{ l | community.general.remove_keys(target=t) }}" + r: "{{ l | community.general.remove_keys(target=t) }}" # 2) Match keys that start with any of the items in the target. - t: [k0, k1] -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" + : "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" # 3) Match keys that end with any of the items in target. - t: [x0, x1] -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" # 4) Match keys by the regex. - t: ['^.*[01]_x.*$'] -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" # 5) Match keys by the regex. - t: '^.*[01]_x.*$' -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" # The results of above examples 1-5 are all the same. - r: @@ -74,19 +74,19 @@ # 6) By default match keys that equal the target. - t: k0_x0 -- r: "{{ l | community.general.remove_keys(target=t) }}" + r: "{{ l | community.general.remove_keys(target=t) }}" # 7) Match keys that start with the target. - t: k0 -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" # 8) Match keys that end with the target. - t: x0 -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}" # 9) Match keys by the regex. - t: '^.*0_x.*$' -- r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}" # The results of above examples 6-9 are all the same. - r: diff --git a/plugins/filter/replace_keys.py b/plugins/filter/replace_keys.py index d314c1fc234..f317144be4e 100644 --- a/plugins/filter/replace_keys.py +++ b/plugins/filter/replace_keys.py @@ -60,25 +60,25 @@ - t: - {before: k0_x0, after: a0} - {before: k1_x1, after: a1} -- r: "{{ l | community.general.replace_keys(target=t) }}" + r: "{{ l | community.general.replace_keys(target=t) }}" # 2) Replace keys that starts with any of the attributes before. - t: - {before: k0, after: a0} - {before: k1, after: a1} -- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" + r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" # 3) Replace keys that ends with any of the attributes before. - t: - {before: x0, after: a0} - {before: x1, after: a1} -- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}" + r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}" # 4) Replace keys that match any regex of the attributes before. - t: - {before: "^.*0_x.*$", after: a0} - {before: "^.*1_x.*$", after: a1} -- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" + r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" # The results of above examples 1-4 are all the same. - r: @@ -88,7 +88,7 @@ # 5) If more keys match the same attribute before the last one will be used. - t: - {before: "^.*_x.*$", after: X} -- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" + r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" # gives @@ -100,7 +100,7 @@ - t: - {before: "^.*_x.*$", after: X} - {before: "^.*_x.*$", after: Y} -- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" + r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}" # gives @@ -115,7 +115,7 @@ - t: - {before: a, after: X} - {before: aa, after: Y} -- r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" + r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}" # gives diff --git a/plugins/filter/reveal_ansible_type.py b/plugins/filter/reveal_ansible_type.py index 6da13d0e946..3d7e40111c7 100644 --- a/plugins/filter/reveal_ansible_type.py +++ b/plugins/filter/reveal_ansible_type.py @@ -29,23 +29,23 @@ # String. AnsibleUnicode. - data: "abc" -- result: '{{ data | community.general.reveal_ansible_type }}' + result: '{{ data | community.general.reveal_ansible_type }}' # result => AnsibleUnicode # String. AnsibleUnicode alias str. - alias: {"AnsibleUnicode": "str"} -- data: "abc" -- result: '{{ data | community.general.reveal_ansible_type(alias) }}' + data: "abc" + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => str # List. All items are AnsibleUnicode. - data: ["a", "b", "c"] -- result: '{{ data | community.general.reveal_ansible_type }}' + result: '{{ data | community.general.reveal_ansible_type }}' # result => list[AnsibleUnicode] # Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode. - data: {"a": "foo", "b": "bar", "c": "baz"} -- result: '{{ data | community.general.reveal_ansible_type }}' + result: '{{ data | community.general.reveal_ansible_type }}' # result => dict[AnsibleUnicode, AnsibleUnicode] # No substitution and no alias. Type of strings is str @@ -88,26 +88,26 @@ # Dictionary. The keys are integers or strings. All values are strings. - alias: {"AnsibleUnicode": "str"} -- data: {1: 'a', 'b': 'b'} -- result: '{{ data | community.general.reveal_ansible_type(alias) }}' + data: {1: 'a', 'b': 'b'} + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[int|str, str] # Dictionary. All keys are integers. All values are keys. - alias: {"AnsibleUnicode": "str"} -- data: {1: 'a', 2: 'b'} -- result: '{{ data | community.general.reveal_ansible_type(alias) }}' + data: {1: 'a', 2: 'b'} + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[int, str] # Dictionary. All keys are strings. Multiple types values. - alias: {"AnsibleUnicode": "str"} -- data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}} -- result: '{{ data | community.general.reveal_ansible_type(alias) }}' + data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}} + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[str, bool|dict|float|int|list|str] # List. Multiple types items. - alias: {"AnsibleUnicode": "str"} -- data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}] -- result: '{{ data | community.general.reveal_ansible_type(alias) }}' + data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}] + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => list[bool|dict|float|int|list|str] """ From a14c6bc3d72950f7a03658d09c71b1affede8694 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Tue, 7 Jan 2025 16:51:22 +1300 Subject: [PATCH 4/4] typo --- plugins/filter/remove_keys.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/filter/remove_keys.py b/plugins/filter/remove_keys.py index b7d05cc8040..7baee12695f 100644 --- a/plugins/filter/remove_keys.py +++ b/plugins/filter/remove_keys.py @@ -53,7 +53,7 @@ # 2) Match keys that start with any of the items in the target. - t: [k0, k1] - : "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" + r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}" # 3) Match keys that end with any of the items in target. - t: [x0, x1]