ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-06-29 19:50:25 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

fixed hidden warnings from extra tests - batch 2 (#10027)
Some checks failed
EOL CI / EOL Sanity (Ⓐ2.15) (push) Has been cancelled
Details
EOL CI / EOL Units (Ⓐ2.15+py2.7) (push) Has been cancelled
Details
EOL CI / EOL Units (Ⓐ2.15+py3.10) (push) Has been cancelled
Details
EOL CI / EOL Units (Ⓐ2.15+py3.5) (push) Has been cancelled
Details
EOL CI / EOL I (Ⓐ2.15+alpine3+py:azp/posix/1/) (push) Has been cancelled
Details
EOL CI / EOL I (Ⓐ2.15+alpine3+py:azp/posix/2/) (push) Has been cancelled
Details
EOL CI / EOL I (Ⓐ2.15+alpine3+py:azp/posix/3/) (push) Has been cancelled
Details
EOL CI / EOL I (Ⓐ2.15+fedora37+py:azp/posix/1/) (push) Has been cancelled
Details
EOL CI / EOL I (Ⓐ2.15+fedora37+py:azp/posix/2/) (push) Has been cancelled
Details
EOL CI / EOL I (Ⓐ2.15+fedora37+py:azp/posix/3/) (push) Has been cancelled
Details
nox / Run extra sanity tests (push) Has been cancelled
Details

Browse source 
* fixed hidden warnings from extra tests - batch 2

* remove multiple yaml doc markers from EXAMPLE blocks

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* Apply suggestions from code review

* Apply suggestions from code review

* dig: adjust markup for return suboptions

* Update plugins/lookup/dig.py

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Alexei Znamensky 2025-05-05 00:05:32 +12:00 • committed by GitHub
parent a042721c82
commit 299172d27b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
36 changed files with 1930 additions and 1940 deletions
Download patch file Download diff file Expand all files Collapse all files

5
plugins/inventory/proxmox.py
View file

@ -155,7 +155,11 @@ 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.
plugin: community.general.proxmox
user: ci@pve
token_id: gitlab-1
token_secret: !vault |
$ANSIBLE_VAULT;1.1;AES256
62353634333163633336343265623632626339313032653563653165313262343931643431656138
@ -216,7 +220,6 @@ 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

42
plugins/inventory/xen_orchestra.py
View file

@ -5,38 +5,41 @@
from __future__ import annotations
DOCUMENTATION = '''
name: xen_orchestra
short_description: Xen Orchestra inventory source
version_added: 4.1.0
author:
DOCUMENTATION = r"""
name: xen_orchestra
short_description: Xen Orchestra inventory source
version_added: 4.1.0
author:
- Dom Del Nano (@ddelnano) <ddelnano@gmail.com>
- Samori Gorse (@shinuza) <samorigorse@gmail.com>
requirements:
requirements:
- websocket-client >= 1.0.0
description:
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:
- 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:
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.
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.
- 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.
- 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:
@ -44,7 +47,8 @@ DOCUMENTATION = '''
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.
- 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:
@ -54,7 +58,7 @@ DOCUMENTATION = '''
type: boolean
default: true
use_ssl:
description: Use wss when connecting to the Xen Orchestra API
description: Use wss when connecting to the Xen Orchestra API.
type: boolean
default: true
use_vm_uuid:
@ -71,10 +75,11 @@ DOCUMENTATION = '''
type: boolean
default: true
version_added: 10.4.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
---
# file must be named xen_orchestra.yaml or xen_orchestra.yml
plugin: community.general.xen_orchestra
api_host: 192.168.1.255
@ -88,8 +93,7 @@ compose:
ansible_port: 2222
use_vm_uuid: false
use_host_uuid: true
'''
"""
import json
import ssl

33
plugins/lookup/bitwarden.py
View file

@ -5,20 +5,20 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
name: bitwarden
author:
DOCUMENTATION = r"""
name: bitwarden
author:
- Jonathan Lung (@lungj) <lungj@heresjono.com>
requirements:
requirements:
- bw (command line utility)
- be logged into bitwarden
- bitwarden vault unlocked
- E(BW_SESSION) environment variable set
short_description: Retrieve secrets from Bitwarden
version_added: 5.4.0
description:
short_description: Retrieve secrets from Bitwarden
version_added: 5.4.0
description:
- Retrieve secrets from Bitwarden.
options:
options:
_terms:
description: Key(s) to fetch values for from login info.
required: true
@ -27,8 +27,7 @@ DOCUMENTATION = """
search:
description:
- Field to retrieve, for example V(name) or V(id).
- If set to V(id), only zero or one element can be returned.
Use the Jinja C(first) filter to get the only list element.
- If set to V(id), only zero or one element can be returned. Use the Jinja C(first) filter to get the only list element.
- If set to V(None) or V(''), or if O(_terms) is empty, records are not filtered by fields.
type: str
default: name
@ -58,13 +57,13 @@ DOCUMENTATION = """
version_added: 8.4.0
result_count:
description:
- Number of results expected for the lookup query. Task will fail if O(result_count)
is set but does not match the number of query results. Leave empty to skip this check.
- Number of results expected for the lookup query. Task will fail if O(result_count) is set but does not match the number
of query results. Leave empty to skip this check.
type: int
version_added: 10.4.0
"""
EXAMPLES = """
EXAMPLES = r"""
- name: "Get 'password' from all Bitwarden records named 'a_test'"
ansible.builtin.debug:
msg: >-
@ -111,12 +110,12 @@ EXAMPLES = """
{{ lookup('community.general.bitwarden', 'a_test', result_count=1) }}
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- A one-element list that contains a list of requested fields or JSON objects of matches.
- If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true),
this always gets reduced to a list of field values or JSON objects.
- If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true), this always gets reduced
to a list of field values or JSON objects.
type: list
elements: list
"""

22
plugins/lookup/bitwarden_secrets_manager.py
View file

@ -6,17 +6,17 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
name: bitwarden_secrets_manager
author:
DOCUMENTATION = r"""
name: bitwarden_secrets_manager
author:
- jantari (@jantari)
requirements:
requirements:
- bws (command line utility)
short_description: Retrieve secrets from Bitwarden Secrets Manager
version_added: 7.2.0
description:
short_description: Retrieve secrets from Bitwarden Secrets Manager
version_added: 7.2.0
description:
- Retrieve secrets from Bitwarden Secrets Manager.
options:
options:
_terms:
description: Secret ID(s) to fetch values for.
required: true
@ -30,7 +30,7 @@ DOCUMENTATION = """
type: str
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Get a secret relying on the BWS_ACCESS_TOKEN environment variable for authentication
ansible.builtin.debug:
msg: >-
@ -62,8 +62,8 @@ EXAMPLES = """
{{ lookup("community.general.bitwarden_secrets_manager", "2bc23e48-4932-40de-a047-5524b7ddc972").value }}
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description: List containing one or more secrets.
type: list
elements: dict

28
plugins/lookup/cartesian.py
View file

@ -6,24 +6,24 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: cartesian
short_description: returns the cartesian product of lists
description:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: cartesian
short_description: returns the cartesian product of lists
description:
- Takes the input lists and returns a list that represents the product of the input lists.
- It is clearer with an example, it turns [1, 2, 3], [a, b] into [1, a], [1, b], [2, a], [2, b], [3, a], [3, b].
You can see the exact syntax in the examples section.
options:
- You can see the exact syntax in the examples section.
options:
_terms:
description:
- a set of lists
- A set of lists.
type: list
elements: list
required: true
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Example of the change in the description
ansible.builtin.debug:
msg: "{{ lookup('community.general.cartesian', [1,2,3], [a, b])}}"
@ -34,13 +34,13 @@ EXAMPLES = """
with_community.general.cartesian:
- "{{list1}}"
- "{{list2}}"
- [1,2,3,4,5,6]
- [1, 2, 3, 4, 5, 6]
"""
RETURN = """
_list:
RETURN = r"""
_list:
description:
- list of lists composed of elements of the input lists
- List of lists composed of elements of the input lists.
type: list
elements: list
"""

37
plugins/lookup/chef_databag.py
View file

@ -6,38 +6,37 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: chef_databag
short_description: fetches data from a Chef Databag
description:
- "This is a lookup plugin to provide access to chef data bags using the pychef package.
It interfaces with the chef server api using the same methods to find a knife or chef-client config file to load parameters from,
starting from either the given base path or the current working directory.
The lookup order mirrors the one from Chef, all folders in the base path are walked back looking for the following configuration
file in order : .chef/knife.rb, ~/.chef/knife.rb, /etc/chef/client.rb"
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: chef_databag
short_description: fetches data from a Chef Databag
description:
- 'This is a lookup plugin to provide access to chef data bags using the pychef package. It interfaces with the chef server
API using the same methods to find a knife or chef-client config file to load parameters from, starting from either the
given base path or the current working directory. The lookup order mirrors the one from Chef, all folders in the base
path are walked back looking for the following configuration file in order: C(.chef/knife.rb), C(~/.chef/knife.rb), C(/etc/chef/client.rb).'
requirements:
- "pychef (L(Python library, https://pychef.readthedocs.io), C(pip install pychef))"
options:
options:
name:
description:
- Name of the databag
- Name of the databag.
type: string
required: true
item:
description:
- Item to fetch
- Item to fetch.
type: string
required: true
'''
"""
EXAMPLES = """
- ansible.builtin.debug:
EXAMPLES = r"""
- ansible.builtin.debug:
msg: "{{ lookup('community.general.chef_databag', 'name=data_bag_name item=data_bag_item') }}"
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- The value from the databag.
type: list

30
plugins/lookup/collection_version.py
View file

@ -5,18 +5,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
name: collection_version
author: Felix Fontein (@felixfontein)
version_added: "4.0.0"
short_description: Retrieves the version of an installed collection
description:
- This lookup allows to query the version of an installed collection, and to determine whether a
collection is installed at all.
- By default it returns V(none) for non-existing collections and V(*) for collections without a
version number. The latter should only happen in development environments, or when installing
a collection from git which has no version in its C(galaxy.yml). This behavior can be adjusted
by providing other values with O(result_not_found) and O(result_no_version).
- This lookup allows to query the version of an installed collection, and to determine whether a collection is installed
at all.
- By default it returns V(none) for non-existing collections and V(*) for collections without a version number. The latter
should only happen in development environments, or when installing a collection from git which has no version in its C(galaxy.yml).
This behavior can be adjusted by providing other values with O(result_not_found) and O(result_no_version).
options:
_terms:
description:
@ -34,28 +33,25 @@ options:
result_no_version:
description:
- The value to return when the collection has no version number.
- This can happen for collections installed from git which do not have a version number
in C(galaxy.yml).
- This can happen for collections installed from git which do not have a version number in C(galaxy.yml).
- By default, V(*) is returned.
type: string
default: '*'
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Check version of community.general
ansible.builtin.debug:
msg: "community.general version {{ lookup('community.general.collection_version', 'community.general') }}"
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- The version number of the collections listed as input.
- If a collection can not be found, it will return the value provided in O(result_not_found).
By default, this is V(none).
- If a collection can be found, but the version not identified, it will return the value provided in
O(result_no_version). By default, this is V(*). This can happen for collections installed
from git which do not have a version number in V(galaxy.yml).
- If a collection can not be found, it will return the value provided in O(result_not_found). By default, this is V(none).
- If a collection can be found, but the version not identified, it will return the value provided in O(result_no_version).
By default, this is V(*). This can happen for collections installed from git which do not have a version number in V(galaxy.yml).
type: list
elements: str
"""

36
plugins/lookup/consul_kv.py
View file

@ -7,17 +7,17 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: consul_kv
short_description: Fetch metadata from a Consul key value store.
description:
- Lookup metadata for a playbook from the key value store in a Consul cluster.
Values can be easily set in the kv store with simple rest commands
- C(curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata)
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: consul_kv
short_description: Fetch metadata from a Consul key value store
description:
- Lookup metadata for a playbook from the key value store in a Consul cluster. Values can be easily set in the kv store
with simple rest commands.
- C(curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata).
requirements:
- 'python-consul python library U(https://python-consul.readthedocs.io/en/latest/#installation)'
options:
options:
_raw:
description: List of key(s) to retrieve.
type: list
@ -78,7 +78,7 @@ DOCUMENTATION = '''
url:
description:
- The target to connect to.
- "Should look like this: V(https://my.consul.server:8500)."
- 'Should look like this: V(https://my.consul.server:8500).'
type: str
version_added: 1.0.0
env:
@ -86,27 +86,27 @@ DOCUMENTATION = '''
ini:
- section: lookup_consul
key: url
'''
"""
EXAMPLES = """
- ansible.builtin.debug:
EXAMPLES = r"""
- ansible.builtin.debug:
msg: 'key contains {{item}}'
with_community.general.consul_kv:
- 'key/to/retrieve'
- name: Parameters can be provided after the key be more specific about what to retrieve
- name: Parameters can be provided after the key be more specific about what to retrieve
ansible.builtin.debug:
msg: 'key contains {{item}}'
with_community.general.consul_kv:
- 'key/to recurse=true token=E6C060A9-26FB-407A-B83E-12DDAFCB4D98'
- name: retrieving a KV from a remote cluster on non default port
- name: retrieving a KV from a remote cluster on non default port
ansible.builtin.debug:
msg: "{{ lookup('community.general.consul_kv', 'my/key', host='10.10.10.10', port=2000) }}"
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- Value(s) stored in consul.
type: dict

40
plugins/lookup/credstash.py
View file

@ -6,54 +6,54 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: credstash
short_description: retrieve secrets from Credstash on AWS
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: credstash
short_description: retrieve secrets from Credstash on AWS
requirements:
- credstash (python library)
description:
- "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash"
options:
description:
- "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash."
options:
_terms:
description: term or list of terms to lookup in the credit store
description: Term or list of terms to lookup in the credit store.
type: list
elements: string
required: true
table:
description: name of the credstash table to query
description: Name of the credstash table to query.
type: str
default: 'credential-store'
version:
description: Credstash version
description: Credstash version.
type: str
default: ''
region:
description: AWS region
description: AWS region.
type: str
profile_name:
description: AWS profile to use for authentication
description: AWS profile to use for authentication.
type: str
env:
- name: AWS_PROFILE
aws_access_key_id:
description: AWS access key ID
description: AWS access key ID.
type: str
env:
- name: AWS_ACCESS_KEY_ID
aws_secret_access_key:
description: AWS access key
description: AWS access key.
type: str
env:
- name: AWS_SECRET_ACCESS_KEY
aws_session_token:
description: AWS session token
description: AWS session token.
type: str
env:
- name: AWS_SESSION_TOKEN
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: first use credstash to store your secrets
ansible.builtin.shell: credstash put my-github-password secure123
@ -86,8 +86,8 @@ EXAMPLES = """
msg: "{{ lookup('community.general.credstash', 'some-password', context=dict(app='my_app', environment='production')) }}"
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- Value(s) stored in Credstash.
type: str

40
plugins/lookup/cyberarkpassword.py
View file

@ -6,15 +6,15 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: cyberarkpassword
short_description: get secrets from CyberArk AIM
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: cyberarkpassword
short_description: get secrets from CyberArk AIM
requirements:
- CyberArk AIM tool installed
description:
description:
- Get secrets from CyberArk AIM.
options :
options:
_command:
description: Cyberark CLI utility.
type: string
@ -32,17 +32,19 @@ DOCUMENTATION = '''
output:
description:
- Specifies the desired output fields separated by commas.
- "They could be: Password, PassProps.<property>, PasswordChangeInProcess"
- 'They could be: Password, PassProps.<property>, PasswordChangeInProcess.'
type: string
default: 'password'
_extra:
description: for extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and ASCP Implementation Guide"
notes:
- For Ansible on Windows, please change the -parameters (-p, -d, and -o) to /parameters (/p, /d, and /o) and change the location of CLIPasswordSDK.exe.
'''
description: For extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and
ASCP Implementation Guide".
notes:
- For Ansible on Windows, please change the -parameters (C(-p), C(-d), and C(-o)) to /parameters (C(/p), C(/d), and C(/o)) and change the
location of C(CLIPasswordSDK.exe).
"""
EXAMPLES = """
- name: passing options to the lookup
EXAMPLES = r"""
- name: passing options to the lookup
ansible.builtin.debug:
msg: '{{ lookup("community.general.cyberarkpassword", cyquery) }}'
vars:
@ -52,7 +54,7 @@ EXAMPLES = """
output: "Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess"
- name: used in a loop
- name: used in a loop
ansible.builtin.debug:
msg: "{{item}}"
with_community.general.cyberarkpassword:
@ -61,7 +63,7 @@ EXAMPLES = """
output: 'Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess'
"""
RETURN = """
RETURN = r"""
_result:
description: A list containing one dictionary.
type: list
@ -69,12 +71,12 @@ _result:
contains:
password:
description:
- The actual value stored
- The actual value stored.
passprops:
description: properties assigned to the entry
description: Properties assigned to the entry.
type: dictionary
passwordchangeinprocess:
description: did the password change?
description: Did the password change?
"""
import os

25
plugins/lookup/dependent.py
View file

@ -6,31 +6,30 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
name: dependent
short_description: Composes a list with nested elements of other lists or dicts which can depend on previous loop variables
author: Felix Fontein (@felixfontein)
version_added: 3.1.0
description:
- "Takes the input lists and returns a list with elements that are lists, dictionaries,
or template expressions which evaluate to lists or dicts, composed of the elements of
the input evaluated lists and dictionaries."
- Takes the input lists and returns a list with elements that are lists, dictionaries, or template expressions which evaluate
to lists or dicts, composed of the elements of the input evaluated lists and dictionaries.
options:
_terms:
description:
- A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary.
The name is the index that is used in the result object. The value is iterated over as described below.
- A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary. The name
is the index that is used in the result object. The value is iterated over as described below.
- If the value is a list, it is simply iterated over.
- If the value is a dictionary, it is iterated over and returned as if they would be processed by the
P(ansible.builtin.dict2items#filter) filter.
- If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen
elements with C(item.<index_name>). The result must be a list or a dictionary.
- If the value is a dictionary, it is iterated over and returned as if they would be processed by the P(ansible.builtin.dict2items#filter)
filter.
- If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen elements with
C(item.<index_name>). The result must be a list or a dictionary.
type: list
elements: dict
required: true
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Install/remove public keys for active admin users
ansible.posix.authorized_key:
user: "{{ item.admin.key }}"
@ -106,8 +105,8 @@ EXAMPLES = """
- 5.6.7.8
"""
RETURN = """
_list:
RETURN = r"""
_list:
description:
- A list composed of dictionaries whose keys are the variable names from the input list.
type: list

117
plugins/lookup/dig.py
View file

@ -6,27 +6,28 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: dig
author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
short_description: query DNS using the dnspython library
requirements:
DOCUMENTATION = r"""
name: dig
author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
short_description: query DNS using the dnspython library
requirements:
- dnspython (python library, http://www.dnspython.org/)
description:
- The dig lookup runs queries against DNS servers to retrieve DNS records for a specific name (FQDN - fully qualified domain name).
It is possible to lookup any DNS record in this manner.
description:
- The dig lookup runs queries against DNS servers to retrieve DNS records for a specific name (FQDN - fully qualified domain
name). It is possible to lookup any DNS record in this manner.
- There is a couple of different syntaxes that can be used to specify what record should be retrieved, and for which name.
It is also possible to explicitly specify the DNS server(s) to use for lookups.
- In its simplest form, the dig lookup plugin can be used to retrieve an IPv4 address (DNS A record) associated with FQDN
- In addition to (default) A record, it is also possible to specify a different record type that should be queried.
This can be done by either passing-in additional parameter of format qtype=TYPE to the dig lookup, or by appending /TYPE to the FQDN being queried.
- If multiple values are associated with the requested record, the results will be returned as a comma-separated list.
In such cases you may want to pass option C(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup),
- In its simplest form, the dig lookup plugin can be used to retrieve an IPv4 address (DNS A record) associated with FQDN.
- In addition to (default) A record, it is also possible to specify a different record type that should be queried. This
can be done by either passing-in additional parameter of format qtype=TYPE to the dig lookup, or by appending /TYPE to
the FQDN being queried.
- If multiple values are associated with the requested record, the results will be returned as a comma-separated list. In
such cases you may want to pass option C(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup),
which will result in the record values being returned as a list over which you can iterate later on.
- By default, the lookup will rely on system-wide configured DNS servers for performing the query.
It is also possible to explicitly specify DNS servers to query using the @DNS_SERVER_1,DNS_SERVER_2,...,DNS_SERVER_N notation.
This needs to be passed-in as an additional parameter to the lookup
options:
- By default, the lookup will rely on system-wide configured DNS servers for performing the query. It is also possible to
explicitly specify DNS servers to query using the @DNS_SERVER_1,DNS_SERVER_2,...,DNS_SERVER_N notation. This needs to
be passed-in as an additional parameter to the lookup.
options:
_terms:
description: Domain(s) to query.
type: list
@ -38,7 +39,8 @@ DOCUMENTATION = '''
- V(CAA) has been added in community.general 6.3.0.
type: str
default: 'A'
choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, SRV, SSHFP, TLSA, TXT]
choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF,
SRV, SSHFP, TLSA, TXT]
flat:
description: If 0 each record is returned as a dictionary, otherwise a string.
type: int
@ -51,9 +53,8 @@ DOCUMENTATION = '''
fail_on_error:
description:
- Abort execution on lookup errors.
- The default for this option will likely change to V(true) in the future.
The current default, V(false), is used for backwards compatibility, and will result in empty strings
or the string V(NXDOMAIN) in the result in case of errors.
- The default for this option will likely change to V(true) in the future. The current default, V(false), is used for
backwards compatibility, and will result in empty strings or the string V(NXDOMAIN) in the result in case of errors.
default: false
type: bool
version_added: 5.4.0
@ -67,7 +68,7 @@ DOCUMENTATION = '''
version_added: 6.0.0
class:
description:
- "Class."
- Class.
type: str
default: 'IN'
tcp:
@ -80,15 +81,17 @@ DOCUMENTATION = '''
default: 53
type: int
version_added: 9.5.0
notes:
- ALL is not a record per-se, merely the listed fields are available for any record results you retrieve in the form of a dictionary.
- While the 'dig' lookup plugin supports anything which dnspython supports out of the box, only a subset can be converted into a dictionary.
- If you need to obtain the AAAA record (IPv6 address), you must specify the record type explicitly.
Syntax for specifying the record type is shown in the examples below.
notes:
- V(ALL) is not a record in itself, merely the listed fields are available for any record results you retrieve in the form of
a dictionary.
- While the plugin supports anything which C(dnspython) supports out of the box, only a subset can be converted
into a dictionary.
- If you need to obtain the AAAA record (IPv6 address), you must specify the record type explicitly. Syntax for specifying
the record type is shown in the examples below.
- The trailing dot in most of the examples listed is purely optional, but is specified for completeness/correctness sake.
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Simple A record (IPV4 address) lookup for example.com
ansible.builtin.debug:
msg: "{{ lookup('community.general.dig', 'example.com.')}}"
@ -139,83 +142,83 @@ EXAMPLES = """
msg: "{{ lookup('community.general.dig', 'example.org./A', retry_servfail=true) }}"
"""
RETURN = """
_list:
RETURN = r"""
_list:
description:
- List of composed strings or dictionaries with key and value
If a dictionary, fields shows the keys returned depending on query type
- List of composed strings or of dictionaries, with fields depending
on query type.
type: list
elements: raw
contains:
ALL:
description:
- owner, ttl, type
- C(owner), C(ttl), C(type).
A:
description:
- address
- C(address).
AAAA:
description:
- address
- C(address).
CAA:
description:
- flags
- tag
- value
- C(flags).
- C(tag).
- C(value).
version_added: 6.3.0
CNAME:
description:
- target
- C(target).
DNAME:
description:
- target
- C(target).
DNSKEY:
description:
- flags, algorithm, protocol, key
- C(flags), C(algorithm), C(protocol), C(key).
DS:
description:
- algorithm, digest_type, key_tag, digest
- C(algorithm), C(digest_type), C(key_tag), C(digest).
HINFO:
description:
- cpu, os
- C(cpu), C(os).
LOC:
description:
- latitude, longitude, altitude, size, horizontal_precision, vertical_precision
- C(latitude), C(longitude), C(altitude), C(size), C(horizontal_precision), C(vertical_precision).
MX:
description:
- preference, exchange
- C(preference), C(exchange).
NAPTR:
description:
- order, preference, flags, service, regexp, replacement
- C(order), C(preference), C(flags), C(service), C(regexp), C(replacement).
NS:
description:
- target
- C(target).
NSEC3PARAM:
description:
- algorithm, flags, iterations, salt
- C(algorithm), C(flags), C(iterations), C(salt).
PTR:
description:
- target
- C(target).
RP:
description:
- mbox, txt
- C(mbox), C(txt).
SOA:
description:
- mname, rname, serial, refresh, retry, expire, minimum
- C(mname), C(rname), C(serial), C(refresh), C(retry), C(expire), C(minimum).
SPF:
description:
- strings
- C(strings).
SRV:
description:
- priority, weight, port, target
- C(priority), C(weight), C(port), C(target).
SSHFP:
description:
- algorithm, fp_type, fingerprint
- C(algorithm), C(fp_type), C(fingerprint).
TLSA:
description:
- usage, selector, mtype, cert
- C(usage), C(selector), C(mtype), C(cert).
TXT:
description:
- strings
- C(strings).
"""
from ansible.errors import AnsibleError

26
plugins/lookup/dnstxt.py
View file

@ -6,17 +6,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: dnstxt
author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
short_description: query a domain(s)'s DNS txt fields
requirements:
DOCUMENTATION = r"""
name: dnstxt
author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
short_description: query a domain(s)'s DNS txt fields
requirements:
- dns/dns.resolver (python library)
description:
description:
- Uses a python library to return the DNS TXT record for a domain.
options:
options:
_terms:
description: domain or list of domains to query TXT records from
description: Domain or list of domains to query TXT records from.
required: true
type: list
elements: string
@ -27,9 +27,9 @@ DOCUMENTATION = '''
default: false
type: bool
version_added: 6.0.0
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: show txt entry
ansible.builtin.debug:
msg: "{{lookup('community.general.dnstxt', ['test.example.com'])}}"
@ -48,10 +48,10 @@ EXAMPLES = """
with_community.general.dnstxt: "{{lookup('community.general.dnstxt', ['test.example.com']).split(',')}}"
"""
RETURN = """
_list:
RETURN = r"""
_list:
description:
- values returned by the DNS TXT record.
- Values returned by the DNS TXT record.
type: list
"""

9
plugins/lookup/dsv.py
View file

@ -12,8 +12,7 @@ author: Adam Migus (@amigus) <adam@migus.org>
short_description: Get secrets from Thycotic DevOps Secrets Vault
version_added: 1.0.0
description:
- Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a
DSV O(tenant) using a O(client_id) and O(client_secret).
- Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a DSV O(tenant) using a O(client_id) and O(client_secret).
requirements:
- python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/
options:
@ -31,8 +30,7 @@ options:
required: true
tld:
default: com
description: The top-level domain of the tenant; the second format
parameter in the default O(url_template).
description: The top-level domain of the tenant; the second format parameter in the default O(url_template).
type: string
env:
- name: DSV_TLD
@ -60,8 +58,7 @@ options:
required: true
url_template:
default: https://{}.secretsvaultcloud.{}/v1
description: The path to prepend to the base URL to form a valid REST
API request.
description: The path to prepend to the base URL to form a valid REST API request.
type: string
env:
- name: DSV_URL_TEMPLATE

36
plugins/lookup/etcd.py
View file

@ -8,46 +8,46 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author:
DOCUMENTATION = r"""
author:
- Jan-Piet Mens (@jpmens)
name: etcd
short_description: get info from an etcd server
description:
- Retrieves data from an etcd server
options:
name: etcd
short_description: get info from an etcd server
description:
- Retrieves data from an etcd server.
options:
_terms:
description:
- the list of keys to lookup on the etcd server
- The list of keys to lookup on the etcd server.
type: list
elements: string
required: true
url:
description:
- Environment variable with the URL for the etcd server
- Environment variable with the URL for the etcd server.
type: string
default: 'http://127.0.0.1:4001'
env:
- name: ANSIBLE_ETCD_URL
version:
description:
- Environment variable with the etcd protocol version
- Environment variable with the etcd protocol version.
type: string
default: 'v1'
env:
- name: ANSIBLE_ETCD_VERSION
validate_certs:
description:
- toggle checking that the ssl certificates are valid, you normally only want to turn this off with self-signed certs.
- Toggle checking that the ssl certificates are valid, you normally only want to turn this off with self-signed certs.
default: true
type: boolean
seealso:
seealso:
- module: community.general.etcd3
- plugin: community.general.etcd3
plugin_type: lookup
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: "a value from a locally running etcd"
ansible.builtin.debug:
msg: "{{ lookup('community.general.etcd', 'foo/bar') }}"
@ -59,15 +59,15 @@ EXAMPLES = '''
- name: "you can set server options inline"
ansible.builtin.debug:
msg: "{{ lookup('community.general.etcd', 'foo', version='v2', url='http://192.168.0.27:4001') }}"
'''
"""
RETURN = '''
_raw:
RETURN = r"""
_raw:
description:
- List of values associated with input keys.
type: list
elements: string
'''
"""
import json

54
plugins/lookup/etcd3.py
View file

@ -7,18 +7,18 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
author:
DOCUMENTATION = r"""
author:
- Eric Belhomme (@eric-belhomme) <ebelhomme@fr.scc.com>
version_added: '0.2.0'
name: etcd3
short_description: Get key values from etcd3 server
description:
version_added: '0.2.0'
name: etcd3
short_description: Get key values from etcd3 server
description:
- Retrieves key values and/or key prefixes from etcd3 server using its native gRPC API.
- Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some C(ETCDCTL_*) environment variables.
- Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some E(ETCDCTL_*) environment
variables.
- See U(https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide) for etcd overview.
options:
options:
_terms:
description:
- The list of keys (or key prefixes) to look up on the etcd3 server.
@ -32,8 +32,8 @@ DOCUMENTATION = '''
default: false
endpoints:
description:
- Counterpart of E(ETCDCTL_ENDPOINTS) environment variable.
Specify the etcd3 connection with and URL form, for example V(https://hostname:2379), or V(<host>:<port>) form.
- Counterpart of E(ETCDCTL_ENDPOINTS) environment variable. Specify the etcd3 connection with an URL form, for example
V(https://hostname:2379), or V(<host>:<port>) form.
- The V(host) part is overwritten by O(host) option, if defined.
- The V(port) part is overwritten by O(port) option, if defined.
env:
@ -42,29 +42,29 @@ DOCUMENTATION = '''
type: str
host:
description:
- etcd3 listening client host.
- Etcd3 listening client host.
- Takes precedence over O(endpoints).
type: str
port:
description:
- etcd3 listening client port.
- Etcd3 listening client port.
- Takes precedence over O(endpoints).
type: int
ca_cert:
description:
- etcd3 CA authority.
- Etcd3 CA authority.
env:
- name: ETCDCTL_CACERT
type: str
cert_cert:
description:
- etcd3 client certificate.
- Etcd3 client certificate.
env:
- name: ETCDCTL_CERT
type: str
cert_key:
description:
- etcd3 client private key.
- Etcd3 client private key.
env:
- name: ETCDCTL_KEY
type: str
@ -88,20 +88,20 @@ DOCUMENTATION = '''
- name: ETCDCTL_PASSWORD
type: str
notes:
notes:
- O(host) and O(port) options take precedence over (endpoints) option.
- The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT)
environment variable and keep O(endpoints), O(host), and O(port) unused.
seealso:
- The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT) environment variable and keep O(endpoints),
O(host), and O(port) unused.
seealso:
- module: community.general.etcd3
- plugin: community.general.etcd
plugin_type: lookup
requirements:
requirements:
- "etcd3 >= 0.10"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: "a value from a locally running etcd"
ansible.builtin.debug:
msg: "{{ lookup('community.general.etcd3', 'foo/bar') }}"
@ -117,10 +117,10 @@ EXAMPLES = '''
- name: "connect to etcd3 with a client certificate"
ansible.builtin.debug:
msg: "{{ lookup('community.general.etcd3', 'foo/bar', cert_cert='/etc/ssl/etcd/client.pem', cert_key='/etc/ssl/etcd/client.key') }}"
'''
"""
RETURN = '''
_raw:
RETURN = r"""
_raw:
description:
- List of keys and associated values.
type: list
@ -132,7 +132,7 @@ RETURN = '''
value:
description: The element's value.
type: str
'''
"""
import re

17
plugins/lookup/filetree.py
View file

@ -6,22 +6,23 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
name: filetree
author: Dag Wieers (@dagwieers) <dag@wieers.com>
short_description: recursively match all files in a directory tree
description:
- This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership.
- Supports directories, files and symlinks, including SELinux and other file properties.
- If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed in previous paths.
This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role.
- This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership.
- Supports directories, files and symlinks, including SELinux and other file properties.
- If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed
in previous paths. This enables merging different trees in order of importance, or add role_vars to specific paths to
influence different instances of the same role.
options:
_terms:
description: Path(s) of files to read.
required: true
type: list
elements: string
'''
"""
EXAMPLES = r"""
- name: Create directories
@ -59,7 +60,7 @@ EXAMPLES = r"""
"""
RETURN = r"""
_raw:
_raw:
description: List of dictionaries with file information.
type: list
elements: dict
@ -79,7 +80,7 @@ RETURN = r"""
description: The permissions the resulting file or directory.
type: str
state:
description: TODO
description: TODO.
type: str
owner:
description: Name of the user that owns the file/directory.

30
plugins/lookup/flattened.py
View file

@ -6,34 +6,34 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: flattened
author: Serge van Ginderachter (!UNKNOWN) <serge@vanginderachter.be>
short_description: return single list completely flattened
description:
DOCUMENTATION = r"""
name: flattened
author: Serge van Ginderachter (!UNKNOWN) <serge@vanginderachter.be>
short_description: return single list completely flattened
description:
- Given one or more lists, this lookup will flatten any list elements found recursively until only 1 list is left.
options:
options:
_terms:
description: lists to flatten
description: Lists to flatten.
type: list
elements: raw
required: true
notes:
- Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level,
this plugin will continue to flatten until it cannot find lists anymore.
notes:
- Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level, this plugin will continue to flatten until
it cannot find lists anymore.
- Aka highlander plugin, there can only be one (list).
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: "'unnest' all elements into single list"
ansible.builtin.debug:
msg: "all in one list {{lookup('community.general.flattened', [1,2,3,[5,6]], ['a','b','c'], [[5,6,1,3], [34,'a','b','c']])}}"
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- flattened list
- Flattened list.
type: list
"""
from ansible.errors import AnsibleError

30
plugins/lookup/github_app_access_token.py
View file

@ -5,17 +5,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: github_app_access_token
author:
DOCUMENTATION = r"""
name: github_app_access_token
author:
- Poh Wei Sheng (@weisheng-p)
short_description: Obtain short-lived Github App Access tokens
version_added: '8.2.0'
requirements:
short_description: Obtain short-lived Github App Access tokens
version_added: '8.2.0'
requirements:
- jwt (https://github.com/GehirnInc/python-jwt)
description:
description:
- This generates a Github access token that can be used with a C(git) command, if you use a Github App.
options:
options:
key_path:
description:
- Path to your private key.
@ -29,7 +29,7 @@ DOCUMENTATION = '''
installation_id:
description:
- The installation ID that contains the git repository you would like access to.
- As of 2023-12-24, this can be found via Settings page > Integrations > Application. The last part of the URL in the
- As of 2023-12-24, this can be found at Settings page > Integrations > Application. The last part of the URL in the
configure button is the installation ID.
- Alternatively, you can use PyGithub (U(https://github.com/PyGithub/PyGithub)) to get your installation ID.
required: true
@ -45,9 +45,9 @@ DOCUMENTATION = '''
- How long the token should last for in seconds.
default: 600
type: int
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get access token to be used for git checkout with app_id=123456, installation_id=64209
ansible.builtin.git:
repo: >-
@ -57,14 +57,14 @@ EXAMPLES = '''
github_token: >-
{{ lookup('community.general.github_app_access_token', key_path='/home/to_your/key',
app_id='123456', installation_id='64209') }}
'''
"""
RETURN = '''
_raw:
RETURN = r"""
_raw:
description: A one-element list containing your GitHub access token.
type: list
elements: str
'''
"""
try:

24
plugins/lookup/hiera.py
View file

@ -6,16 +6,16 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author:
DOCUMENTATION = r"""
author:
- Juan Manuel Parrilla (@jparrill)
name: hiera
short_description: get info from hiera data
requirements:
name: hiera
short_description: get info from hiera data
requirements:
- hiera (command line utility)
description:
description:
- Retrieves data from an Puppetmaster node using Hiera as ENC.
options:
options:
_terms:
description:
- The list of keys to lookup on the Puppetmaster.
@ -37,9 +37,9 @@ DOCUMENTATION = '''
env:
- name: ANSIBLE_HIERA_CFG
# FIXME: incomplete options .. _terms? environment/fqdn?
'''
"""
EXAMPLES = """
EXAMPLES = r"""
# All this examples depends on hiera.yml that describes the hierarchy
- name: "a value from Hiera 'DB'"
@ -55,10 +55,10 @@ EXAMPLES = """
msg: "{{ lookup('community.general.hiera', 'foo fqdn=puppet01.localdomain') }}"
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description:
- a value associated with input key
- A value associated with input key.
type: list
elements: str
"""

20
plugins/lookup/keyring.py
View file

@ -7,18 +7,18 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: keyring
author:
DOCUMENTATION = r"""
name: keyring
author:
- Samuel Boucher (!UNKNOWN) <boucher.samuel.c@gmail.com>
requirements:
requirements:
- keyring (python library)
short_description: grab secrets from the OS keyring
description:
short_description: grab secrets from the OS keyring
description:
- Allows you to access data stored in the OS provided keyring/keychain.
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: output secrets to screen (BAD IDEA)
ansible.builtin.debug:
msg: "Password: {{item}}"
@ -31,8 +31,8 @@ EXAMPLES = """
login_user: joe
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description: Secrets stored.
type: list
elements: str

24
plugins/lookup/lastpass.py
View file

@ -6,17 +6,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: lastpass
author:
DOCUMENTATION = r"""
name: lastpass
author:
- Andrew Zenk (!UNKNOWN) <azenk@umn.edu>
requirements:
requirements:
- lpass (command line utility)
- must have already logged into LastPass
short_description: fetch data from LastPass
description:
short_description: fetch data from LastPass
description:
- Use the lpass command line utility to fetch specific fields from LastPass.
options:
options:
_terms:
description: Key from which you want to retrieve the field.
required: true
@ -26,17 +26,17 @@ DOCUMENTATION = '''
description: Field to return from LastPass.
default: 'password'
type: str
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: get 'custom_field' from LastPass entry 'entry-name'
ansible.builtin.debug:
msg: "{{ lookup('community.general.lastpass', 'entry-name', field='custom_field') }}"
"""
RETURN = """
_raw:
description: secrets stored
RETURN = r"""
_raw:
description: Secrets stored.
type: list
elements: str
"""

24
plugins/lookup/lmdb_kv.py
View file

@ -6,17 +6,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: lmdb_kv
author:
DOCUMENTATION = r"""
name: lmdb_kv
author:
- Jan-Piet Mens (@jpmens)
version_added: '0.2.0'
short_description: fetch data from LMDB
description:
version_added: '0.2.0'
short_description: fetch data from LMDB
description:
- This lookup returns a list of results from an LMDB DB corresponding to a list of items given to it.
requirements:
requirements:
- lmdb (Python library U(https://lmdb.readthedocs.io/en/release/))
options:
options:
_terms:
description: List of keys to query.
type: list
@ -27,9 +27,9 @@ DOCUMENTATION = '''
default: 'ansible.mdb'
vars:
- name: lmdb_kv_db
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: query LMDB for a list of country codes
ansible.builtin.debug:
msg: "{{ query('community.general.lmdb_kv', 'nl', 'be', 'lu', db='jp.mdb') }}"
@ -52,9 +52,9 @@ EXAMPLES = """
- be
"""
RETURN = """
RETURN = r"""
_raw:
description: value(s) stored in LMDB
description: Value(s) stored in LMDB.
type: list
elements: raw
"""

45
plugins/lookup/merge_variables.py
View file

@ -6,22 +6,22 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
author:
DOCUMENTATION = r"""
author:
- Roy Lenferink (@rlenferink)
- Mark Ettema (@m-a-r-k-e)
- Alexander Petrenz (@alpex8)
name: merge_variables
short_description: merge variables whose names match a given pattern
description:
- This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or
regular expressions, optionally.
version_added: 6.5.0
options:
name: merge_variables
short_description: merge variables whose names match a given pattern
description:
- This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or regular expressions,
optionally.
version_added: 6.5.0
options:
_terms:
description:
- Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions
that will be used to match all variables that should be merged.
- Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions that will
be used to match all variables that should be merged.
required: true
type: list
elements: str
@ -47,10 +47,9 @@ DOCUMENTATION = """
description:
- Return an error, print a warning or ignore it when a key will be overwritten.
- The default behavior V(error) makes the plugin fail when a key would be overwritten.
- When V(warn) and V(ignore) are used, note that it is important to know that the variables
are sorted by name before being merged. Keys for later variables in this order will overwrite
keys of the same name for variables earlier in this order. To avoid potential confusion,
better use O(override=error) whenever possible.
- When V(warn) and V(ignore) are used, note that it is important to know that the variables are sorted by name before
being merged. Keys for later variables in this order will overwrite keys of the same name for variables earlier in
this order. To avoid potential confusion, better use O(override=error) whenever possible.
type: str
default: 'error'
choices:
@ -64,14 +63,14 @@ DOCUMENTATION = """
key: override
groups:
description:
- Search for variables accross hosts that belong to the given groups. This allows to collect configuration pieces
accross different hosts (for example a service on a host with its database on another host).
- Search for variables across hosts that belong to the given groups. This allows to collect configuration pieces across
different hosts (for example a service on a host with its database on another host).
type: list
elements: str
version_added: 8.5.0
"""
EXAMPLES = """
EXAMPLES = r"""
# Some example variables, they can be defined anywhere as long as they are in scope
test_init_list:
- "list init item 1"
@ -91,7 +90,6 @@ testb__test_dict:
ports:
- 3
# Merge variables that end with '__test_dict' and store the result in a variable 'example_a'
example_a: "{{ lookup('community.general.merge_variables', '__test_dict', pattern_type='suffix') }}"
@ -100,7 +98,6 @@ example_a: "{{ lookup('community.general.merge_variables', '__test_dict', patter
# - 1
# - 3
# Merge variables that match the '^.+__test_list$' regular expression, starting with an initial value and store the
# result in a variable 'example_b'
example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', initial_value=test_init_list) }}"
@ -112,10 +109,10 @@ example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', in
# - "test b item 1"
"""
RETURN = """
_raw:
description: In case the search matches list items, a list will be returned. In case the search matches dicts, a
dict will be returned.
RETURN = r"""
_raw:
description: In case the search matches list items, a list will be returned. In case the search matches dicts, a dict will
be returned.
type: raw
elements: raw
"""

43
plugins/lookup/onepassword.py
View file

@ -8,18 +8,18 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: onepassword
author:
DOCUMENTATION = r"""
name: onepassword
author:
- Scott Buchanan (@scottsb)
- Andrew Zenk (@azenk)
- Sam Doran (@samdoran)
short_description: Fetch field values from 1Password
description:
short_description: Fetch field values from 1Password
description:
- P(community.general.onepassword#lookup) wraps the C(op) command line utility to fetch specific field values from 1Password.
requirements:
requirements:
- C(op) 1Password command line utility
options:
options:
_terms:
description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
required: true
@ -35,12 +35,13 @@ DOCUMENTATION = '''
type: str
service_account_token:
version_added: 7.1.0
extends_documentation_fragment:
extends_documentation_fragment:
- community.general.onepassword
- community.general.onepassword.lookup
'''
"""
EXAMPLES = """
EXAMPLES = r"""
---
# These examples only work when already signed in to 1Password
- name: Retrieve password for KITT when already signed in to 1Password
ansible.builtin.debug:
@ -56,29 +57,21 @@ EXAMPLES = """
- name: Retrieve password for HAL when not signed in to 1Password
ansible.builtin.debug:
var: lookup('community.general.onepassword',
'HAL 9000',
subdomain='Discovery',
master_password=vault_master_password)
var: lookup('community.general.onepassword', 'HAL 9000', subdomain='Discovery', master_password=vault_master_password)
- name: Retrieve password for HAL when never signed in to 1Password
ansible.builtin.debug:
var: lookup('community.general.onepassword',
'HAL 9000',
subdomain='Discovery',
master_password=vault_master_password,
username='tweety@acme.com',
secret_key=vault_secret_key)
var: >-
lookup('community.general.onepassword', 'HAL 9000', subdomain='Discovery', master_password=vault_master_password,
username='tweety@acme.com', secret_key=vault_secret_key)
- name: Retrieve password from specific account
ansible.builtin.debug:
var: lookup('community.general.onepassword',
'HAL 9000',
account_id='abc123')
var: lookup('community.general.onepassword', 'HAL 9000', account_id='abc123')
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description: Field data requested.
type: list
elements: str

32
plugins/lookup/onepassword_doc.py
View file

@ -6,41 +6,41 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: onepassword_doc
author:
DOCUMENTATION = r"""
name: onepassword_doc
author:
- Sam Doran (@samdoran)
requirements:
requirements:
- C(op) 1Password command line utility version 2 or later.
short_description: Fetch documents stored in 1Password
version_added: "8.1.0"
description:
short_description: Fetch documents stored in 1Password
version_added: "8.1.0"
description:
- P(community.general.onepassword_doc#lookup) wraps C(op) command line utility to fetch one or more documents from 1Password.
notes:
notes:
- The document contents are a string exactly as stored in 1Password.
- This plugin requires C(op) version 2 or later.
options:
options:
_terms:
description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
required: true
type: list
elements: string
extends_documentation_fragment:
extends_documentation_fragment:
- community.general.onepassword
- community.general.onepassword.lookup
'''
"""
EXAMPLES = """
EXAMPLES = r"""
---
- name: Retrieve a private key from 1Password
ansible.builtin.debug:
var: lookup('community.general.onepassword_doc', 'Private key')
"""
RETURN = """
_raw:
description: Requested document
RETURN = r"""
_raw:
description: Requested document.
type: list
elements: string
"""

25
plugins/lookup/onepassword_raw.py
View file

@ -8,18 +8,18 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: onepassword_raw
author:
DOCUMENTATION = r"""
name: onepassword_raw
author:
- Scott Buchanan (@scottsb)
- Andrew Zenk (@azenk)
- Sam Doran (@samdoran)
requirements:
requirements:
- C(op) 1Password command line utility
short_description: Fetch an entire item from 1Password
description:
short_description: Fetch an entire item from 1Password
description:
- P(community.general.onepassword_raw#lookup) wraps C(op) command line utility to fetch an entire item from 1Password.
options:
options:
_terms:
description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
required: true
@ -31,12 +31,13 @@ DOCUMENTATION = '''
version_added: 6.0.0
service_account_token:
version_added: 7.1.0
extends_documentation_fragment:
extends_documentation_fragment:
- community.general.onepassword
- community.general.onepassword.lookup
'''
"""
EXAMPLES = """
EXAMPLES = r"""
---
- name: Retrieve all data about Wintermute
ansible.builtin.debug:
var: lookup('community.general.onepassword_raw', 'Wintermute')
@ -46,8 +47,8 @@ EXAMPLES = """
var: lookup('community.general.onepassword_raw', 'Wintermute', subdomain='Turing', vault_password='DmbslfLvasjdl')
"""
RETURN = """
_raw:
RETURN = r"""
_raw:
description: Entire item requested.
type: list
elements: dict

8
plugins/lookup/onepassword_ssh_key.py
View file

@ -5,7 +5,7 @@
from __future__ import annotations
DOCUMENTATION = """
DOCUMENTATION = r"""
name: onepassword_ssh_key
author:
- Mohammed Babelly (@mohammedbabelly20)
@ -19,7 +19,6 @@ notes:
- By default, it returns the private key value in PKCS#8 format, unless O(ssh_format=true) is passed.
- The pluging works only for C(SSHKEY) type items.
- This plugin requires C(op) version 2 or later.
options:
_terms:
description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
@ -36,13 +35,14 @@ extends_documentation_fragment:
- community.general.onepassword.lookup
"""
EXAMPLES = """
EXAMPLES = r"""
---
- name: Retrieve the private SSH key from 1Password
ansible.builtin.debug:
msg: "{{ lookup('community.general.onepassword_ssh_key', 'SSH Key', ssh_format=true) }}"
"""
RETURN = """
RETURN = r"""
_raw:
description: Private key of SSH keypair.
type: list

45
plugins/lookup/passwordstore.py
View file

@ -7,26 +7,26 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: passwordstore
author:
DOCUMENTATION = r"""
name: passwordstore
author:
- Patrick Deelman (!UNKNOWN) <patrick@patrickdeelman.nl>
short_description: manage passwords with passwordstore.org's pass utility
description:
- Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility.
It can also retrieve, create or update YAML style keys stored as multilines in the passwordfile.
- To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to
C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using O(lock=readwrite) instead.
options:
short_description: manage passwords with passwordstore.org's pass utility
description:
- Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. It can also retrieve,
create or update YAML style keys stored as multilines in the passwordfile.
- To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to C(~/.gnupg/gpg-agent.conf). Where
this is not possible, consider using O(lock=readwrite) instead.
options:
_terms:
description: query key.
description: Query key.
required: true
directory:
description:
- The directory of the password store.
- If O(backend=pass), the default is V(~/.password-store) is used.
- If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml),
falling back to V(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config.
- If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), falling back to V(~/.local/share/gopass/stores/root)
if C(path) is not defined in the gopass config.
type: path
vars:
- name: passwordstore
@ -79,8 +79,8 @@ DOCUMENTATION = '''
- If O(create=true), the value for this option is ignored and assumed to be V(create).
- If set to V(error), the lookup will error out if the passname does not exist.
- If set to V(create), the passname will be created with the provided length O(length) if it does not exist.
- If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist.
When using C(lookup) and not C(query), this will be translated to an empty string.
- If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist. When using C(lookup) and
not C(query), this will be translated to an empty string.
version_added: 3.1.0
type: str
default: error
@ -108,7 +108,8 @@ DOCUMENTATION = '''
locktimeout:
description:
- Lock timeout applied when O(lock) is not V(none).
- Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals V(15m).
- Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals
V(15m).
- Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details.
ini:
- section: passwordstore_lookup
@ -157,17 +158,17 @@ DOCUMENTATION = '''
ini:
- section: passwordstore_lookup
key: missing_subkey
notes:
notes:
- The lookup supports passing all options as lookup parameters since community.general 6.0.0.
'''
EXAMPLES = """
"""
EXAMPLES = r"""
ansible.cfg: |
[passwordstore_lookup]
lock=readwrite
locktimeout=45s
missing_subkey=warn
tasks.yml: |
tasks.yml: |-
---
# Debug is used for examples, BAD IDEA to show passwords on screen
@ -233,10 +234,10 @@ tasks.yml: |
passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test', returnall=true)}}"
"""
RETURN = """
RETURN = r"""
_raw:
description:
- a password
- A password.
type: list
elements: str
"""

30
plugins/lookup/random_pet.py
View file

@ -8,17 +8,17 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
name: random_pet
author:
DOCUMENTATION = r"""
name: random_pet
author:
- Abhijeet Kasurde (@Akasurde)
short_description: Generates random pet names
version_added: '3.1.0'
requirements:
short_description: Generates random pet names
version_added: '3.1.0'
requirements:
- petname U(https://github.com/dustinkirkland/python-petname)
description:
description:
- Generates random pet names that can be used as unique identifiers for the resources.
options:
options:
words:
description:
- The number of words in the pet name.
@ -37,9 +37,9 @@ DOCUMENTATION = r'''
description: The character to separate words in the pet name.
default: "-"
type: str
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate pet name
ansible.builtin.debug:
var: lookup('community.general.random_pet')
@ -59,14 +59,14 @@ EXAMPLES = r'''
ansible.builtin.debug:
var: lookup('community.general.random_pet', length=7)
# Example result: 'natural-peacock'
'''
"""
RETURN = r'''
_raw:
description: A one-element list containing a random pet name
RETURN = r"""
_raw:
description: A one-element list containing a random pet name.
type: list
elements: str
'''
"""
try:
import petname

23
plugins/lookup/random_string.py
View file

@ -9,16 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
name: random_string
author:
name: random_string
author:
- Abhijeet Kasurde (@Akasurde)
short_description: Generates random string
version_added: '3.2.0'
description:
short_description: Generates random string
version_added: '3.2.0'
description:
- Generates random string based upon the given constraints.
- Uses L(random.SystemRandom,https://docs.python.org/3/library/random.html#random.SystemRandom),
so should be strong enough for cryptographic purposes.
options:
- Uses L(random.SystemRandom,https://docs.python.org/3/library/random.html#random.SystemRandom), so should be strong enough
for cryptographic purposes.
options:
length:
description: The length of the string.
default: 8
@ -77,8 +77,7 @@ DOCUMENTATION = r"""
type: str
override_all:
description:
- Override all values of O(numbers), O(upper), O(lower), and O(special) with
the given list of characters.
- Override all values of O(numbers), O(upper), O(lower), and O(special) with the given list of characters.
type: str
ignore_similar_chars:
description:
@ -142,8 +141,8 @@ EXAMPLES = r"""
"""
RETURN = r"""
_raw:
description: A one-element list containing a random string
_raw:
description: A one-element list containing a random string.
type: list
elements: str
"""

19
plugins/lookup/random_words.py
View file

@ -10,18 +10,17 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
name: random_words
author:
name: random_words
author:
- Thomas Sjögren (@konstruktoid)
short_description: Return a number of random words
version_added: "4.0.0"
requirements:
short_description: Return a number of random words
version_added: "4.0.0"
requirements:
- xkcdpass U(https://github.com/redacted/XKCD-password-generator)
description:
- Returns a number of random words. The output can for example be used for
passwords.
description:
- Returns a number of random words. The output can for example be used for passwords.
- See U(https://xkcd.com/936/) for background.
options:
options:
numwords:
description:
- The number of words.
@ -74,7 +73,7 @@ EXAMPLES = r"""
"""
RETURN = r"""
_raw:
_raw:
description: A single-element list containing random words.
type: list
elements: str

33
plugins/lookup/redis.py
View file

@ -6,23 +6,23 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: redis
author:
DOCUMENTATION = r"""
name: redis
author:
- Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
- Ansible Core Team
short_description: fetch data from Redis
description:
- This lookup returns a list of results from a Redis DB corresponding to a list of items given to it
requirements:
short_description: fetch data from Redis
description:
- This lookup returns a list of results from a Redis DB corresponding to a list of items given to it.
requirements:
- redis (python library https://github.com/andymccurdy/redis-py/)
options:
options:
_terms:
description: list of keys to query
description: List of keys to query.
type: list
elements: string
host:
description: location of Redis host
description: Location of Redis host.
type: string
default: '127.0.0.1'
env:
@ -31,7 +31,7 @@ DOCUMENTATION = '''
- section: lookup_redis
key: host
port:
description: port on which Redis is listening on
description: Port on which Redis is listening on.
default: 6379
type: int
env:
@ -40,16 +40,16 @@ DOCUMENTATION = '''
- section: lookup_redis
key: port
socket:
description: path to socket on which to query Redis, this option overrides host and port options when set.
description: Path to socket on which to query Redis, this option overrides host and port options when set.
type: path
env:
- name: ANSIBLE_REDIS_SOCKET
ini:
- section: lookup_redis
key: socket
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: query redis for somekey (default or configured settings used)
ansible.builtin.debug:
msg: "{{ lookup('community.general.redis', 'somekey') }}"
@ -66,12 +66,11 @@ EXAMPLES = """
- name: use list directly with a socket
ansible.builtin.debug:
msg: "{{ lookup('community.general.redis', 'key1', 'key2', socket='/var/tmp/redis.sock') }}"
"""
RETURN = """
RETURN = r"""
_raw:
description: value(s) stored in Redis
description: Value(s) stored in Redis.
type: list
elements: str
"""

7
plugins/lookup/revbitspss.py
View file

@ -12,8 +12,8 @@ author: RevBits (@RevBits) <info@revbits.com>
short_description: Get secrets from RevBits PAM server
version_added: 4.1.0
description:
- Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM
Server using API key authentication with the REST API.
- Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM Server using API key authentication with the REST
API.
requirements:
- revbits_ansible - U(https://pypi.org/project/revbits_ansible/)
options:
@ -45,6 +45,7 @@ _list:
"""
EXAMPLES = r"""
---
- hosts: localhost
vars:
secret: >-
@ -58,7 +59,7 @@ EXAMPLES = r"""
}}
tasks:
- ansible.builtin.debug:
msg: >
msg: >-
UUIDPAM is {{ (secret['UUIDPAM']) }} and DB_PASS is {{ (secret['DB_PASS']) }}
"""

19
plugins/lookup/shelvefile.py
View file

@ -6,13 +6,13 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: shelvefile
author: Alejandro Guirao (!UNKNOWN) <lekumberri@gmail.com>
short_description: read keys from Python shelve file
description:
DOCUMENTATION = r"""
name: shelvefile
author: Alejandro Guirao (!UNKNOWN) <lekumberri@gmail.com>
short_description: read keys from Python shelve file
description:
- Read keys from Python shelve file.
options:
options:
_terms:
description: Sets of key value pairs of parameters.
type: list
@ -25,15 +25,16 @@ DOCUMENTATION = '''
description: Path to shelve file.
type: path
required: true
'''
"""
EXAMPLES = """
EXAMPLES = r"""
---
- name: Retrieve a string value corresponding to a key inside a Python shelve file
ansible.builtin.debug:
msg: "{{ lookup('community.general.shelvefile', 'file=path_to_some_shelve_file.db key=key_to_retrieve') }}"
"""
RETURN = """
RETURN = r"""
_list:
description: Value(s) of key(s) in shelve file(s).
type: list

20
plugins/lookup/tss.py
View file

@ -12,12 +12,10 @@ author: Adam Migus (@amigus) <adam@migus.org>
short_description: Get secrets from Thycotic Secret Server
version_added: 1.0.0
description:
- Uses the Thycotic Secret Server Python SDK to get Secrets from Secret
Server using token authentication with O(username) and O(password) on
the REST API at O(base_url).
- When using self-signed certificates the environment variable
E(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates
(in C(.pem) format).
- Uses the Thycotic Secret Server Python SDK to get Secrets from Secret Server using token authentication with O(username)
and O(password) on the REST API at O(base_url).
- When using self-signed certificates the environment variable E(REQUESTS_CA_BUNDLE) can be set to a file containing the
trusted certificates (in C(.pem) format).
- For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt').
requirements:
- python-tss-sdk - https://pypi.org/project/python-tss-sdk/
@ -34,7 +32,7 @@ options:
version_added: 7.2.0
fetch_secret_ids_from_folder:
description:
- Boolean flag which indicates whether secret ids are in a folder is fetched by folder ID or not.
- Boolean flag which indicates whether secret IDs are in a folder is fetched by folder ID or not.
- V(true) then the terms will be considered as a folder IDs. Otherwise (default), they are considered as secret IDs.
required: false
type: bool
@ -106,16 +104,14 @@ options:
version_added: 3.7.0
api_path_uri:
default: /api/v1
description: The path to append to the base URL to form a valid REST
API request.
description: The path to append to the base URL to form a valid REST API request.
type: string
env:
- name: TSS_API_PATH_URI
required: false
token_path_uri:
default: /oauth2/token
description: The path to append to the base URL to form a valid OAuth2
Access Grant request.
description: The path to append to the base URL to form a valid OAuth2 Access Grant request.
type: string
env:
- name: TSS_TOKEN_PATH_URI
@ -251,7 +247,7 @@ EXAMPLES = r"""
}}
tasks:
- ansible.builtin.debug:
msg: >
msg: >-
the password is {{
(secret['items']
| items2dict(key_name='slug',