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_id: gitlab-1
token_secret: fa256e9c-26ab-41ec-82da-707a2c079829 token_secret: fa256e9c-26ab-41ec-82da-707a2c079829
---
# The secret can also be a vault string or passed via the environment variable TOKEN_SECRET. # 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 | token_secret: !vault |
$ANSIBLE_VAULT;1.1;AES256 $ANSIBLE_VAULT;1.1;AES256
62353634333163633336343265623632626339313032653563653165313262343931643431656138 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 # 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`. # an example where this is set to `false` and where ansible_host is set with `compose`.
want_proxmox_nodes_ansible_host: true want_proxmox_nodes_ansible_host: true
''' '''
import itertools import itertools

146
plugins/inventory/xen_orchestra.py
View file

@ -5,76 +5,81 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = ''' DOCUMENTATION = r"""
name: xen_orchestra name: xen_orchestra
short_description: Xen Orchestra inventory source short_description: Xen Orchestra inventory source
version_added: 4.1.0 version_added: 4.1.0
author: author:
- Dom Del Nano (@ddelnano) <ddelnano@gmail.com> - Dom Del Nano (@ddelnano) <ddelnano@gmail.com>
- Samori Gorse (@shinuza) <samorigorse@gmail.com> - Samori Gorse (@shinuza) <samorigorse@gmail.com>
requirements: requirements:
- websocket-client >= 1.0.0 - 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: description:
- Get inventory hosts from a Xen Orchestra deployment. - API host to XOA API.
- 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).' - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST)
extends_documentation_fragment: will be used instead.
- constructed type: str
- inventory_cache env:
options: - name: ANSIBLE_XO_HOST
plugin: user:
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:
required: true - Xen Orchestra user.
choices: ['community.general.xen_orchestra'] - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER)
type: str will be used instead.
api_host: required: true
description: type: str
- API host to XOA API. env:
- If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. - name: ANSIBLE_XO_USER
type: str password:
env: description:
- name: ANSIBLE_XO_HOST - Xen Orchestra password.
user: - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD)
description: will be used instead.
- Xen Orchestra user. required: true
- If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. type: str
required: true env:
type: str - name: ANSIBLE_XO_PASSWORD
env: validate_certs:
- name: ANSIBLE_XO_USER description: Verify TLS certificate if using HTTPS.
password: type: boolean
description: default: true
- Xen Orchestra password. use_ssl:
- If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. description: Use wss when connecting to the Xen Orchestra API.
required: true type: boolean
type: str default: true
env: use_vm_uuid:
- name: ANSIBLE_XO_PASSWORD description:
validate_certs: - Import Xen VMs to inventory using their UUID as the VM entry name.
description: Verify TLS certificate if using HTTPS. - If set to V(false) use VM name labels instead of UUIDs.
type: boolean type: boolean
default: true default: true
use_ssl: version_added: 10.4.0
description: Use wss when connecting to the Xen Orchestra API use_host_uuid:
type: boolean description:
default: true - Import Xen Hosts to inventory using their UUID as the Host entry name.
use_vm_uuid: - If set to V(false) use Host name labels instead of UUIDs.
description: type: boolean
- Import Xen VMs to inventory using their UUID as the VM entry name. default: true
- If set to V(false) use VM name labels instead of UUIDs. version_added: 10.4.0
type: boolean """
default: true
version_added: 10.4.0
use_host_uuid:
description:
- Import Xen Hosts to inventory using their UUID as the Host entry name.
- If set to V(false) use Host name labels instead of UUIDs.
type: boolean
default: true
version_added: 10.4.0
'''
EXAMPLES = ''' EXAMPLES = r"""
---
# file must be named xen_orchestra.yaml or xen_orchestra.yml # file must be named xen_orchestra.yaml or xen_orchestra.yml
plugin: community.general.xen_orchestra plugin: community.general.xen_orchestra
api_host: 192.168.1.255 api_host: 192.168.1.255
@ -83,13 +88,12 @@ password: xo_pwd
validate_certs: true validate_certs: true
use_ssl: true use_ssl: true
groups: groups:
kube_nodes: "'kube_node' in tags" kube_nodes: "'kube_node' in tags"
compose: compose:
ansible_port: 2222 ansible_port: 2222
use_vm_uuid: false use_vm_uuid: false
use_host_uuid: true use_host_uuid: true
"""
'''
import json import json
import ssl import ssl

129
plugins/lookup/bitwarden.py
View file

@ -5,66 +5,65 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
name: bitwarden name: bitwarden
author: author:
- Jonathan Lung (@lungj) <lungj@heresjono.com> - Jonathan Lung (@lungj) <lungj@heresjono.com>
requirements: requirements:
- bw (command line utility) - bw (command line utility)
- be logged into bitwarden - be logged into bitwarden
- bitwarden vault unlocked - bitwarden vault unlocked
- E(BW_SESSION) environment variable set - E(BW_SESSION) environment variable set
short_description: Retrieve secrets from Bitwarden short_description: Retrieve secrets from Bitwarden
version_added: 5.4.0 version_added: 5.4.0
description:
- Retrieve secrets from Bitwarden.
options:
_terms:
description: Key(s) to fetch values for from login info.
required: true
type: list
elements: str
search:
description: description:
- Retrieve secrets from Bitwarden. - Field to retrieve, for example V(name) or V(id).
options: - 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.
_terms: - If set to V(None) or V(''), or if O(_terms) is empty, records are not filtered by fields.
description: Key(s) to fetch values for from login info. type: str
required: true default: name
type: list version_added: 5.7.0
elements: str field:
search: description: Field to fetch. Leave unset to fetch whole response.
description: type: str
- Field to retrieve, for example V(name) or V(id). collection_id:
- If set to V(id), only zero or one element can be returned. description:
Use the Jinja C(first) filter to get the only list element. - Collection ID to filter results by collection. Leave unset to skip filtering.
- If set to V(None) or V(''), or if O(_terms) is empty, records are not filtered by fields. - O(collection_id) and O(collection_name) are mutually exclusive.
type: str type: str
default: name version_added: 6.3.0
version_added: 5.7.0 collection_name:
field: description:
description: Field to fetch. Leave unset to fetch whole response. - Collection name to filter results by collection. Leave unset to skip filtering.
type: str - O(collection_id) and O(collection_name) are mutually exclusive.
collection_id: type: str
description: version_added: 10.4.0
- Collection ID to filter results by collection. Leave unset to skip filtering. organization_id:
- O(collection_id) and O(collection_name) are mutually exclusive. description: Organization ID to filter results by organization. Leave unset to skip filtering.
type: str type: str
version_added: 6.3.0 version_added: 8.5.0
collection_name: bw_session:
description: description: Pass session key instead of reading from env.
- Collection name to filter results by collection. Leave unset to skip filtering. type: str
- O(collection_id) and O(collection_name) are mutually exclusive. version_added: 8.4.0
type: str result_count:
version_added: 10.4.0 description:
organization_id: - Number of results expected for the lookup query. Task will fail if O(result_count) is set but does not match the number
description: Organization ID to filter results by organization. Leave unset to skip filtering. of query results. Leave empty to skip this check.
type: str type: int
version_added: 8.5.0 version_added: 10.4.0
bw_session:
description: Pass session key instead of reading from env.
type: str
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.
type: int
version_added: 10.4.0
""" """
EXAMPLES = """ EXAMPLES = r"""
- name: "Get 'password' from all Bitwarden records named 'a_test'" - name: "Get 'password' from all Bitwarden records named 'a_test'"
ansible.builtin.debug: ansible.builtin.debug:
msg: >- msg: >-
@ -111,14 +110,14 @@ EXAMPLES = """
{{ lookup('community.general.bitwarden', 'a_test', result_count=1) }} {{ lookup('community.general.bitwarden', 'a_test', result_count=1) }}
""" """
RETURN = """ RETURN = r"""
_raw: _raw:
description: description:
- A one-element list that contains a list of requested fields or JSON objects of matches. - 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), - If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true), this always gets reduced
this always gets reduced to a list of field values or JSON objects. to a list of field values or JSON objects.
type: list type: list
elements: list elements: list
""" """
from subprocess import Popen, PIPE from subprocess import Popen, PIPE

56
plugins/lookup/bitwarden_secrets_manager.py
View file

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

46
plugins/lookup/cartesian.py
View file

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

65
plugins/lookup/chef_databag.py
View file

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

38
plugins/lookup/collection_version.py
View file

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

200
plugins/lookup/consul_kv.py
View file

@ -7,109 +7,109 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: Unknown (!UNKNOWN) author: Unknown (!UNKNOWN)
name: consul_kv name: consul_kv
short_description: Fetch metadata from a Consul key value store. 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:
_raw:
description: List of key(s) to retrieve.
type: list
elements: string
recurse:
type: boolean
description: If true, will retrieve all the values that have the given key as prefix.
default: false
index:
description: description:
- Lookup metadata for a playbook from the key value store in a Consul cluster. - If the key has a value with the specified index then this is returned allowing access to historical values.
Values can be easily set in the kv store with simple rest commands type: int
- C(curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata) datacenter:
requirements: description:
- 'python-consul python library U(https://python-consul.readthedocs.io/en/latest/#installation)' - Retrieve the key from a consul datacenter other than the default for the consul host.
options: type: str
_raw: token:
description: List of key(s) to retrieve. description: The acl token to allow access to restricted values.
type: list type: str
elements: string host:
recurse: default: localhost
type: boolean type: str
description: If true, will retrieve all the values that have the given key as prefix. description:
default: false - The target to connect to, must be a resolvable address.
index: - Will be determined from E(ANSIBLE_CONSUL_URL) if that is set.
description: ini:
- If the key has a value with the specified index then this is returned allowing access to historical values. - section: lookup_consul
type: int key: host
datacenter: port:
description: description:
- Retrieve the key from a consul datacenter other than the default for the consul host. - The port of the target host to connect to.
type: str - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there.
token: type: int
description: The acl token to allow access to restricted values. default: 8500
type: str scheme:
host: default: http
default: localhost type: str
type: str description:
description: - Whether to use http or https.
- The target to connect to, must be a resolvable address. - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there.
- Will be determined from E(ANSIBLE_CONSUL_URL) if that is set. validate_certs:
ini: default: true
- section: lookup_consul description: Whether to verify the TLS connection or not.
key: host type: bool
port: env:
description: - name: ANSIBLE_CONSUL_VALIDATE_CERTS
- The port of the target host to connect to. ini:
- If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. - section: lookup_consul
type: int key: validate_certs
default: 8500 client_cert:
scheme: description: The client cert to verify the TLS connection.
default: http type: str
type: str env:
description: - name: ANSIBLE_CONSUL_CLIENT_CERT
- Whether to use http or https. ini:
- If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. - section: lookup_consul
validate_certs: key: client_cert
default: true url:
description: Whether to verify the TLS connection or not. description:
type: bool - The target to connect to.
env: - 'Should look like this: V(https://my.consul.server:8500).'
- name: ANSIBLE_CONSUL_VALIDATE_CERTS type: str
ini: version_added: 1.0.0
- section: lookup_consul env:
key: validate_certs - name: ANSIBLE_CONSUL_URL
client_cert: ini:
description: The client cert to verify the TLS connection. - section: lookup_consul
type: str key: url
env:
- name: ANSIBLE_CONSUL_CLIENT_CERT
ini:
- section: lookup_consul
key: client_cert
url:
description:
- The target to connect to.
- "Should look like this: V(https://my.consul.server:8500)."
type: str
version_added: 1.0.0
env:
- name: ANSIBLE_CONSUL_URL
ini:
- section: lookup_consul
key: url
'''
EXAMPLES = """
- 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
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
ansible.builtin.debug:
msg: "{{ lookup('community.general.consul_kv', 'my/key', host='10.10.10.10', port=2000) }}"
""" """
RETURN = """ EXAMPLES = r"""
_raw: - ansible.builtin.debug:
description: msg: 'key contains {{item}}'
- Value(s) stored in consul. with_community.general.consul_kv:
type: dict - 'key/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
ansible.builtin.debug:
msg: "{{ lookup('community.general.consul_kv', 'my/key', host='10.10.10.10', port=2000) }}"
"""
RETURN = r"""
_raw:
description:
- Value(s) stored in consul.
type: dict
""" """
from ansible.module_utils.six.moves.urllib.parse import urlparse from ansible.module_utils.six.moves.urllib.parse import urlparse

116
plugins/lookup/credstash.py
View file

@ -6,54 +6,54 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: Unknown (!UNKNOWN) author: Unknown (!UNKNOWN)
name: credstash name: credstash
short_description: retrieve secrets from Credstash on AWS short_description: retrieve secrets from Credstash on AWS
requirements: requirements:
- credstash (python library) - credstash (python library)
description: description:
- "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash" - "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash."
options: options:
_terms: _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 type: list
elements: string elements: string
required: true required: true
table: table:
description: name of the credstash table to query description: Name of the credstash table to query.
type: str type: str
default: 'credential-store' default: 'credential-store'
version: version:
description: Credstash version description: Credstash version.
type: str type: str
default: '' default: ''
region: region:
description: AWS region description: AWS region.
type: str type: str
profile_name: profile_name:
description: AWS profile to use for authentication description: AWS profile to use for authentication.
type: str type: str
env: env:
- name: AWS_PROFILE - name: AWS_PROFILE
aws_access_key_id: aws_access_key_id:
description: AWS access key ID description: AWS access key ID.
type: str type: str
env: env:
- name: AWS_ACCESS_KEY_ID - name: AWS_ACCESS_KEY_ID
aws_secret_access_key: aws_secret_access_key:
description: AWS access key description: AWS access key.
type: str type: str
env: env:
- name: AWS_SECRET_ACCESS_KEY - name: AWS_SECRET_ACCESS_KEY
aws_session_token: aws_session_token:
description: AWS session token description: AWS session token.
type: str type: str
env: env:
- name: AWS_SESSION_TOKEN - name: AWS_SESSION_TOKEN
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: first use credstash to store your secrets - name: first use credstash to store your secrets
ansible.builtin.shell: credstash put my-github-password secure123 ansible.builtin.shell: credstash put my-github-password secure123
@ -77,20 +77,20 @@ EXAMPLES = """
environment: production environment: production
tasks: tasks:
- name: "Test credstash lookup plugin -- get the password with a context passed as a variable" - name: "Test credstash lookup plugin -- get the password with a context passed as a variable"
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ lookup('community.general.credstash', 'some-password', context=context) }}" msg: "{{ lookup('community.general.credstash', 'some-password', context=context) }}"
- name: "Test credstash lookup plugin -- get the password with a context defined here" - name: "Test credstash lookup plugin -- get the password with a context defined here"
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ lookup('community.general.credstash', 'some-password', context=dict(app='my_app', environment='production')) }}" msg: "{{ lookup('community.general.credstash', 'some-password', context=dict(app='my_app', environment='production')) }}"
""" """
RETURN = """ RETURN = r"""
_raw: _raw:
description: description:
- Value(s) stored in Credstash. - Value(s) stored in Credstash.
type: str type: str
""" """
from ansible.errors import AnsibleError from ansible.errors import AnsibleError

114
plugins/lookup/cyberarkpassword.py
View file

@ -6,62 +6,64 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: Unknown (!UNKNOWN) author: Unknown (!UNKNOWN)
name: cyberarkpassword name: cyberarkpassword
short_description: get secrets from CyberArk AIM short_description: get secrets from CyberArk AIM
requirements: requirements:
- CyberArk AIM tool installed - CyberArk AIM tool installed
description:
- Get secrets from CyberArk AIM.
options:
_command:
description: Cyberark CLI utility.
type: string
env:
- name: AIM_CLIPASSWORDSDK_CMD
default: '/opt/CARKaim/sdk/clipasswordsdk'
appid:
description: Defines the unique ID of the application that is issuing the password request.
type: string
required: true
query:
description: Describes the filter criteria for the password retrieval.
type: string
required: true
output:
description: description:
- Get secrets from CyberArk AIM. - Specifies the desired output fields separated by commas.
options : - 'They could be: Password, PassProps.<property>, PasswordChangeInProcess.'
_command: type: string
description: Cyberark CLI utility. default: 'password'
type: string _extra:
env: description: For extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and
- name: AIM_CLIPASSWORDSDK_CMD ASCP Implementation Guide".
default: '/opt/CARKaim/sdk/clipasswordsdk' notes:
appid: - 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
description: Defines the unique ID of the application that is issuing the password request. location of C(CLIPasswordSDK.exe).
type: string
required: true
query:
description: Describes the filter criteria for the password retrieval.
type: string
required: true
output:
description:
- Specifies the desired output fields separated by commas.
- "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.
'''
EXAMPLES = """
- name: passing options to the lookup
ansible.builtin.debug:
msg: '{{ lookup("community.general.cyberarkpassword", cyquery) }}'
vars:
cyquery:
appid: "app_ansible"
query: "safe=CyberArk_Passwords;folder=root;object=AdminPass"
output: "Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess"
- name: used in a loop
ansible.builtin.debug:
msg: "{{item}}"
with_community.general.cyberarkpassword:
appid: 'app_ansible'
query: 'safe=CyberArk_Passwords;folder=root;object=AdminPass'
output: 'Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess'
""" """
RETURN = """ EXAMPLES = r"""
- name: passing options to the lookup
ansible.builtin.debug:
msg: '{{ lookup("community.general.cyberarkpassword", cyquery) }}'
vars:
cyquery:
appid: "app_ansible"
query: "safe=CyberArk_Passwords;folder=root;object=AdminPass"
output: "Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess"
- name: used in a loop
ansible.builtin.debug:
msg: "{{item}}"
with_community.general.cyberarkpassword:
appid: 'app_ansible'
query: 'safe=CyberArk_Passwords;folder=root;object=AdminPass'
output: 'Password,PassProps.UserName,PassProps.Address,PasswordChangeInProcess'
"""
RETURN = r"""
_result: _result:
description: A list containing one dictionary. description: A list containing one dictionary.
type: list type: list
@ -69,12 +71,12 @@ _result:
contains: contains:
password: password:
description: description:
- The actual value stored - The actual value stored.
passprops: passprops:
description: properties assigned to the entry description: Properties assigned to the entry.
type: dictionary type: dictionary
passwordchangeinprocess: passwordchangeinprocess:
description: did the password change? description: Did the password change?
""" """
import os import os

63
plugins/lookup/dependent.py
View file

@ -6,31 +6,30 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
name: dependent name: dependent
short_description: Composes a list with nested elements of other lists or dicts which can depend on previous loop variables short_description: Composes a list with nested elements of other lists or dicts which can depend on previous loop variables
author: Felix Fontein (@felixfontein) author: Felix Fontein (@felixfontein)
version_added: 3.1.0 version_added: 3.1.0
description: description:
- "Takes the input lists and returns a list with elements that are lists, dictionaries, - Takes the input lists and returns a list with elements that are lists, dictionaries, or template expressions which evaluate
or template expressions which evaluate to lists or dicts, composed of the elements of to lists or dicts, composed of the elements of the input evaluated lists and dictionaries.
the input evaluated lists and dictionaries."
options: options:
_terms: _terms:
description: description:
- A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary. - A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary. The name
The name is the index that is used in the result object. The value is iterated over as described below. 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 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 - 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)
P(ansible.builtin.dict2items#filter) filter. filter.
- If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen elements with
elements with C(item.<index_name>). The result must be a list or a dictionary. C(item.<index_name>). The result must be a list or a dictionary.
type: list type: list
elements: dict elements: dict
required: true required: true
""" """
EXAMPLES = """ EXAMPLES = r"""
- name: Install/remove public keys for active admin users - name: Install/remove public keys for active admin users
ansible.posix.authorized_key: ansible.posix.authorized_key:
user: "{{ item.admin.key }}" user: "{{ item.admin.key }}"
@ -76,9 +75,9 @@ EXAMPLES = """
loop_control: loop_control:
# Makes the output readable, so that it doesn't contain the whole subdictionaries and lists # Makes the output readable, so that it doesn't contain the whole subdictionaries and lists
label: |- label: |-
{{ [item.zone.key, item.prefix.key, item.entry.key, {{ [item.zone.key, item.prefix.key, item.entry.key,
item.entry.value.ttl | default(3600), item.entry.value.ttl | default(3600),
item.entry.value.absent | default(False), item.entry.value.value] }} item.entry.value.absent | default(False), item.entry.value.value] }}
with_community.general.dependent: with_community.general.dependent:
- zone: dns_setup - zone: dns_setup
- prefix: item.zone.value - prefix: item.zone.value
@ -89,36 +88,36 @@ EXAMPLES = """
'': '':
A: A:
value: value:
- 1.2.3.4 - 1.2.3.4
AAAA: AAAA:
value: value:
- "2a01:1:2:3::1" - "2a01:1:2:3::1"
'test._domainkey': 'test._domainkey':
TXT: TXT:
ttl: 300 ttl: 300
value: value:
- '"k=rsa; t=s; p=MIGfMA..."' - '"k=rsa; t=s; p=MIGfMA..."'
example.org: example.org:
'www': 'www':
A: A:
value: value:
- 1.2.3.4 - 1.2.3.4
- 5.6.7.8 - 5.6.7.8
""" """
RETURN = """ RETURN = r"""
_list: _list:
description: description:
- A list composed of dictionaries whose keys are the variable names from the input list. - A list composed of dictionaries whose keys are the variable names from the input list.
type: list type: list
elements: dict elements: dict
sample: sample:
- key1: a - key1: a
key2: test key2: test
- key1: a - key1: a
key2: foo key2: foo
- key1: b - key1: b
key2: bar key2: bar
""" """
from ansible.errors import AnsibleLookupError from ansible.errors import AnsibleLookupError

319
plugins/lookup/dig.py
View file

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

54
plugins/lookup/dnstxt.py
View file

@ -6,30 +6,30 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
name: dnstxt name: dnstxt
author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com> author: Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
short_description: query a domain(s)'s DNS txt fields short_description: query a domain(s)'s DNS txt fields
requirements: requirements:
- dns/dns.resolver (python library) - dns/dns.resolver (python library)
description:
- Uses a python library to return the DNS TXT record for a domain.
options:
_terms:
description: Domain or list of domains to query TXT records from.
required: true
type: list
elements: string
real_empty:
description: description:
- Uses a python library to return the DNS TXT record for a domain. - Return empty result without empty strings, and return empty list instead of V(NXDOMAIN).
options: - The default for this option will likely change to V(true) in the future.
_terms: default: false
description: domain or list of domains to query TXT records from type: bool
required: true version_added: 6.0.0
type: list """
elements: string
real_empty:
description:
- Return empty result without empty strings, and return empty list instead of V(NXDOMAIN).
- The default for this option will likely change to V(true) in the future.
default: false
type: bool
version_added: 6.0.0
'''
EXAMPLES = """ EXAMPLES = r"""
- name: show txt entry - name: show txt entry
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{lookup('community.general.dnstxt', ['test.example.com'])}}" msg: "{{lookup('community.general.dnstxt', ['test.example.com'])}}"
@ -48,11 +48,11 @@ EXAMPLES = """
with_community.general.dnstxt: "{{lookup('community.general.dnstxt', ['test.example.com']).split(',')}}" with_community.general.dnstxt: "{{lookup('community.general.dnstxt', ['test.example.com']).split(',')}}"
""" """
RETURN = """ RETURN = r"""
_list: _list:
description: description:
- values returned by the DNS TXT record. - Values returned by the DNS TXT record.
type: list type: list
""" """
HAVE_DNS = False HAVE_DNS = False

123
plugins/lookup/dsv.py
View file

@ -12,81 +12,78 @@ author: Adam Migus (@amigus) <adam@migus.org>
short_description: Get secrets from Thycotic DevOps Secrets Vault short_description: Get secrets from Thycotic DevOps Secrets Vault
version_added: 1.0.0 version_added: 1.0.0
description: description:
- Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a - 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).
DSV O(tenant) using a O(client_id) and O(client_secret).
requirements: requirements:
- python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/ - python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/
options: options:
_terms: _terms:
description: The path to the secret, for example V(/staging/servers/web1). description: The path to the secret, for example V(/staging/servers/web1).
required: true required: true
tenant: tenant:
description: The first format parameter in the default O(url_template). description: The first format parameter in the default O(url_template).
type: string type: string
env: env:
- name: DSV_TENANT - name: DSV_TENANT
ini: ini:
- section: dsv_lookup - section: dsv_lookup
key: tenant key: tenant
required: true required: true
tld: tld:
default: com default: com
description: The top-level domain of the tenant; the second format description: The top-level domain of the tenant; the second format parameter in the default O(url_template).
parameter in the default O(url_template). type: string
type: string env:
env: - name: DSV_TLD
- name: DSV_TLD ini:
ini: - section: dsv_lookup
- section: dsv_lookup key: tld
key: tld required: false
required: false client_id:
client_id: description: The client_id with which to request the Access Grant.
description: The client_id with which to request the Access Grant. type: string
type: string env:
env: - name: DSV_CLIENT_ID
- name: DSV_CLIENT_ID ini:
ini: - section: dsv_lookup
- section: dsv_lookup key: client_id
key: client_id required: true
required: true client_secret:
client_secret: description: The client secret associated with the specific O(client_id).
description: The client secret associated with the specific O(client_id). type: string
type: string env:
env: - name: DSV_CLIENT_SECRET
- name: DSV_CLIENT_SECRET ini:
ini: - section: dsv_lookup
- section: dsv_lookup key: client_secret
key: client_secret required: true
required: true url_template:
url_template: default: https://{}.secretsvaultcloud.{}/v1
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 type: string
API request. env:
type: string - name: DSV_URL_TEMPLATE
env: ini:
- name: DSV_URL_TEMPLATE - section: dsv_lookup
ini: key: url_template
- section: dsv_lookup required: false
key: url_template
required: false
""" """
RETURN = r""" RETURN = r"""
_list: _list:
description: description:
- One or more JSON responses to C(GET /secrets/{path}). - One or more JSON responses to C(GET /secrets/{path}).
- See U(https://dsv.thycotic.com/api/index.html#operation/getSecret). - See U(https://dsv.thycotic.com/api/index.html#operation/getSecret).
type: list type: list
elements: dict elements: dict
""" """
EXAMPLES = r""" EXAMPLES = r"""
- hosts: localhost - hosts: localhost
vars: vars:
secret: "{{ lookup('community.general.dsv', '/test/secret') }}" secret: "{{ lookup('community.general.dsv', '/test/secret') }}"
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: 'the password is {{ secret["data"]["password"] }}' msg: 'the password is {{ secret["data"]["password"] }}'
""" """
from ansible.errors import AnsibleError, AnsibleOptionsError from ansible.errors import AnsibleError, AnsibleOptionsError

92
plugins/lookup/etcd.py
View file

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

212
plugins/lookup/etcd3.py
View file

@ -7,101 +7,101 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: author:
- Eric Belhomme (@eric-belhomme) <ebelhomme@fr.scc.com> - Eric Belhomme (@eric-belhomme) <ebelhomme@fr.scc.com>
version_added: '0.2.0' version_added: '0.2.0'
name: etcd3 name: etcd3
short_description: Get key values from etcd3 server 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 E(ETCDCTL_*) environment
variables.
- See U(https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide) for etcd overview.
options:
_terms:
description: description:
- Retrieves key values and/or key prefixes from etcd3 server using its native gRPC API. - The list of keys (or key prefixes) to look up on the etcd3 server.
- Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some C(ETCDCTL_*) environment variables. type: list
- See U(https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide) for etcd overview. elements: str
required: true
prefix:
description:
- Look for key or prefix key.
type: bool
default: false
endpoints:
description:
- 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:
- name: ETCDCTL_ENDPOINTS
default: '127.0.0.1:2379'
type: str
host:
description:
- Etcd3 listening client host.
- Takes precedence over O(endpoints).
type: str
port:
description:
- Etcd3 listening client port.
- Takes precedence over O(endpoints).
type: int
ca_cert:
description:
- Etcd3 CA authority.
env:
- name: ETCDCTL_CACERT
type: str
cert_cert:
description:
- Etcd3 client certificate.
env:
- name: ETCDCTL_CERT
type: str
cert_key:
description:
- Etcd3 client private key.
env:
- name: ETCDCTL_KEY
type: str
timeout:
description:
- Client timeout.
default: 60
env:
- name: ETCDCTL_DIAL_TIMEOUT
type: int
user:
description:
- Authenticated user name.
env:
- name: ETCDCTL_USER
type: str
password:
description:
- Authenticated user password.
env:
- name: ETCDCTL_PASSWORD
type: str
options: notes:
_terms: - O(host) and O(port) options take precedence over (endpoints) option.
description: - The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT) environment variable and keep O(endpoints),
- The list of keys (or key prefixes) to look up on the etcd3 server. O(host), and O(port) unused.
type: list seealso:
elements: str - module: community.general.etcd3
required: true - plugin: community.general.etcd
prefix: plugin_type: lookup
description:
- Look for key or prefix key.
type: bool
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.
- 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:
- name: ETCDCTL_ENDPOINTS
default: '127.0.0.1:2379'
type: str
host:
description:
- etcd3 listening client host.
- Takes precedence over O(endpoints).
type: str
port:
description:
- etcd3 listening client port.
- Takes precedence over O(endpoints).
type: int
ca_cert:
description:
- etcd3 CA authority.
env:
- name: ETCDCTL_CACERT
type: str
cert_cert:
description:
- etcd3 client certificate.
env:
- name: ETCDCTL_CERT
type: str
cert_key:
description:
- etcd3 client private key.
env:
- name: ETCDCTL_KEY
type: str
timeout:
description:
- Client timeout.
default: 60
env:
- name: ETCDCTL_DIAL_TIMEOUT
type: int
user:
description:
- Authenticated user name.
env:
- name: ETCDCTL_USER
type: str
password:
description:
- Authenticated user password.
env:
- name: ETCDCTL_PASSWORD
type: str
notes: requirements:
- O(host) and O(port) options take precedence over (endpoints) option. - "etcd3 >= 0.10"
- 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: EXAMPLES = r"""
- "etcd3 >= 0.10"
'''
EXAMPLES = '''
- name: "a value from a locally running etcd" - name: "a value from a locally running etcd"
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ lookup('community.general.etcd3', 'foo/bar') }}" msg: "{{ lookup('community.general.etcd3', 'foo/bar') }}"
@ -117,22 +117,22 @@ EXAMPLES = '''
- name: "connect to etcd3 with a client certificate" - name: "connect to etcd3 with a client certificate"
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ lookup('community.general.etcd3', 'foo/bar', cert_cert='/etc/ssl/etcd/client.pem', cert_key='/etc/ssl/etcd/client.key') }}" msg: "{{ lookup('community.general.etcd3', 'foo/bar', cert_cert='/etc/ssl/etcd/client.pem', cert_key='/etc/ssl/etcd/client.key') }}"
''' """
RETURN = ''' RETURN = r"""
_raw: _raw:
description: description:
- List of keys and associated values. - List of keys and associated values.
type: list type: list
elements: dict elements: dict
contains: contains:
key: key:
description: The element's key. description: The element's key.
type: str type: str
value: value:
description: The element's value. description: The element's value.
type: str type: str
''' """
import re import re

123
plugins/lookup/filetree.py
View file

@ -6,22 +6,23 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
name: filetree name: filetree
author: Dag Wieers (@dagwieers) <dag@wieers.com> author: Dag Wieers (@dagwieers) <dag@wieers.com>
short_description: recursively match all files in a directory tree short_description: recursively match all files in a directory tree
description: description:
- This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership. - 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. - 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. - If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed
This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role. 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: options:
_terms: _terms:
description: Path(s) of files to read. description: Path(s) of files to read.
required: true required: true
type: list type: list
elements: string elements: string
''' """
EXAMPLES = r""" EXAMPLES = r"""
- name: Create directories - name: Create directories
@ -59,61 +60,61 @@ EXAMPLES = r"""
""" """
RETURN = r""" RETURN = r"""
_raw: _raw:
description: List of dictionaries with file information. description: List of dictionaries with file information.
type: list type: list
elements: dict elements: dict
contains: contains:
src: src:
description: description:
- Full path to file. - Full path to file.
- Not returned when RV(_raw[].state) is set to V(directory). - Not returned when RV(_raw[].state) is set to V(directory).
type: path type: path
root: root:
description: Allows filtering by original location. description: Allows filtering by original location.
type: path type: path
path: path:
description: Contains the relative path to root. description: Contains the relative path to root.
type: path type: path
mode: mode:
description: The permissions the resulting file or directory. description: The permissions the resulting file or directory.
type: str type: str
state: state:
description: TODO description: TODO.
type: str type: str
owner: owner:
description: Name of the user that owns the file/directory. description: Name of the user that owns the file/directory.
type: raw type: raw
group: group:
description: Name of the group that owns the file/directory. description: Name of the group that owns the file/directory.
type: raw type: raw
seuser: seuser:
description: The user part of the SELinux file context. description: The user part of the SELinux file context.
type: raw type: raw
serole: serole:
description: The role part of the SELinux file context. description: The role part of the SELinux file context.
type: raw type: raw
setype: setype:
description: The type part of the SELinux file context. description: The type part of the SELinux file context.
type: raw type: raw
selevel: selevel:
description: The level part of the SELinux file context. description: The level part of the SELinux file context.
type: raw type: raw
uid: uid:
description: Owner ID of the file/directory. description: Owner ID of the file/directory.
type: int type: int
gid: gid:
description: Group ID of the file/directory. description: Group ID of the file/directory.
type: int type: int
size: size:
description: Size of the target. description: Size of the target.
type: int type: int
mtime: mtime:
description: Time of last modification. description: Time of last modification.
type: float type: float
ctime: ctime:
description: Time of last metadata update or creation (depends on OS). description: Time of last metadata update or creation (depends on OS).
type: float type: float
""" """
import os import os
import pwd import pwd

46
plugins/lookup/flattened.py
View file

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

96
plugins/lookup/github_app_access_token.py
View file

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

74
plugins/lookup/hiera.py
View file

@ -6,40 +6,40 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
author: author:
- Juan Manuel Parrilla (@jparrill) - Juan Manuel Parrilla (@jparrill)
name: hiera name: hiera
short_description: get info from hiera data short_description: get info from hiera data
requirements: requirements:
- hiera (command line utility) - hiera (command line utility)
description:
- Retrieves data from an Puppetmaster node using Hiera as ENC.
options:
_terms:
description: description:
- Retrieves data from an Puppetmaster node using Hiera as ENC. - The list of keys to lookup on the Puppetmaster.
options: type: list
_terms: elements: string
description: required: true
- The list of keys to lookup on the Puppetmaster. executable:
type: list description:
elements: string - Binary file to execute Hiera.
required: true type: string
executable: default: '/usr/bin/hiera'
description: env:
- Binary file to execute Hiera. - name: ANSIBLE_HIERA_BIN
type: string config_file:
default: '/usr/bin/hiera' description:
env: - File that describes the hierarchy of Hiera.
- name: ANSIBLE_HIERA_BIN type: string
config_file: default: '/etc/hiera.yaml'
description: env:
- File that describes the hierarchy of Hiera. - name: ANSIBLE_HIERA_CFG
type: string
default: '/etc/hiera.yaml'
env:
- name: ANSIBLE_HIERA_CFG
# FIXME: incomplete options .. _terms? environment/fqdn? # FIXME: incomplete options .. _terms? environment/fqdn?
''' """
EXAMPLES = """ EXAMPLES = r"""
# All this examples depends on hiera.yml that describes the hierarchy # All this examples depends on hiera.yml that describes the hierarchy
- name: "a value from Hiera 'DB'" - name: "a value from Hiera 'DB'"
@ -55,12 +55,12 @@ EXAMPLES = """
msg: "{{ lookup('community.general.hiera', 'foo fqdn=puppet01.localdomain') }}" msg: "{{ lookup('community.general.hiera', 'foo fqdn=puppet01.localdomain') }}"
""" """
RETURN = """ RETURN = r"""
_raw: _raw:
description: description:
- a value associated with input key - A value associated with input key.
type: list type: list
elements: str elements: str
""" """
from ansible.plugins.lookup import LookupBase from ansible.plugins.lookup import LookupBase

32
plugins/lookup/keyring.py
View file

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

54
plugins/lookup/lastpass.py
View file

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

52
plugins/lookup/lmdb_kv.py
View file

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

139
plugins/lookup/merge_variables.py
View file

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

93
plugins/lookup/onepassword.py
View file

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

60
plugins/lookup/onepassword_doc.py
View file

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

67
plugins/lookup/onepassword_raw.py
View file

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

8
plugins/lookup/onepassword_ssh_key.py
View file

@ -5,7 +5,7 @@
from __future__ import annotations from __future__ import annotations
DOCUMENTATION = """ DOCUMENTATION = r"""
name: onepassword_ssh_key name: onepassword_ssh_key
author: author:
- Mohammed Babelly (@mohammedbabelly20) - 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. - 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. - The pluging works only for C(SSHKEY) type items.
- This plugin requires C(op) version 2 or later. - This plugin requires C(op) version 2 or later.
options: options:
_terms: _terms:
description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
@ -36,13 +35,14 @@ extends_documentation_fragment:
- community.general.onepassword.lookup - community.general.onepassword.lookup
""" """
EXAMPLES = """ EXAMPLES = r"""
---
- name: Retrieve the private SSH key from 1Password - name: Retrieve the private SSH key from 1Password
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ lookup('community.general.onepassword_ssh_key', 'SSH Key', ssh_format=true) }}" msg: "{{ lookup('community.general.onepassword_ssh_key', 'SSH Key', ssh_format=true) }}"
""" """
RETURN = """ RETURN = r"""
_raw: _raw:
description: Private key of SSH keypair. description: Private key of SSH keypair.
type: list type: list

313
plugins/lookup/passwordstore.py
View file

@ -7,167 +7,168 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
name: passwordstore name: passwordstore
author: author:
- Patrick Deelman (!UNKNOWN) <patrick@patrickdeelman.nl> - Patrick Deelman (!UNKNOWN) <patrick@patrickdeelman.nl>
short_description: manage passwords with passwordstore.org's pass utility 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.
required: true
directory:
description: description:
- Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. - The directory of the password store.
It can also retrieve, create or update YAML style keys stored as multilines in the passwordfile. - If O(backend=pass), the default is V(~/.password-store) is used.
- To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to - 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)
C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using O(lock=readwrite) instead. if C(path) is not defined in the gopass config.
options: type: path
_terms: vars:
description: query key. - name: passwordstore
required: true env:
directory: - name: PASSWORD_STORE_DIR
description: create:
- The directory of the password store. description: Create the password or the subkey if it does not already exist. Takes precedence over O(missing).
- If O(backend=pass), the default is V(~/.password-store) is used. type: bool
- If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), default: false
falling back to V(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config. overwrite:
type: path description: Overwrite the password or the subkey if it does already exist.
vars: type: bool
- name: passwordstore default: false
env: umask:
- name: PASSWORD_STORE_DIR description:
create: - Sets the umask for the created V(.gpg) files. The first octed must be greater than 3 (user readable).
description: Create the password or the subkey if it does not already exist. Takes precedence over O(missing). - Note pass' default value is V('077').
type: bool type: string
default: false env:
overwrite: - name: PASSWORD_STORE_UMASK
description: Overwrite the password or the subkey if it does already exist. version_added: 1.3.0
type: bool returnall:
default: false description: Return all the content of the password, not only the first line.
umask: type: bool
description: default: false
- Sets the umask for the created V(.gpg) files. The first octed must be greater than 3 (user readable). subkey:
- Note pass' default value is V('077'). description:
type: string - By default return a specific subkey of the password. When set to V(password), always returns the first line.
env: - With O(overwrite=true), it will create the subkey and return it.
- name: PASSWORD_STORE_UMASK type: str
version_added: 1.3.0 default: password
returnall: userpass:
description: Return all the content of the password, not only the first line. description: Specify a password to save, instead of a generated one.
type: bool type: str
default: false length:
subkey: description: The length of the generated password.
description: type: integer
- By default return a specific subkey of the password. When set to V(password), always returns the first line. default: 16
- With O(overwrite=true), it will create the subkey and return it. backup:
type: str description: Used with O(overwrite=true). Backup the previous password or subkey in a subkey.
default: password type: bool
userpass: default: false
description: Specify a password to save, instead of a generated one. nosymbols:
type: str description: Use alphanumeric characters.
length: type: bool
description: The length of the generated password. default: false
type: integer missing:
default: 16 description:
backup: - List of preference about what to do if the password file is missing.
description: Used with O(overwrite=true). Backup the previous password or subkey in a subkey. - If O(create=true), the value for this option is ignored and assumed to be V(create).
type: bool - If set to V(error), the lookup will error out if the passname does not exist.
default: false - If set to V(create), the passname will be created with the provided length O(length) if it does not exist.
nosymbols: - 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
description: Use alphanumeric characters. not C(query), this will be translated to an empty string.
type: bool version_added: 3.1.0
default: false type: str
missing: default: error
description: choices:
- List of preference about what to do if the password file is missing. - error
- If O(create=true), the value for this option is ignored and assumed to be V(create). - warn
- If set to V(error), the lookup will error out if the passname does not exist. - empty
- If set to V(create), the passname will be created with the provided length O(length) if it does not exist. - create
- If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist. lock:
When using C(lookup) and not C(query), this will be translated to an empty string. description:
version_added: 3.1.0 - How to synchronize operations.
type: str - The default of V(write) only synchronizes write operations.
default: error - V(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel.
choices: - V(none) does not do any synchronization.
- error ini:
- warn - section: passwordstore_lookup
- empty key: lock
- create type: str
lock: default: write
description: choices:
- How to synchronize operations. - readwrite
- The default of V(write) only synchronizes write operations. - write
- V(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel. - none
- V(none) does not do any synchronization. version_added: 4.5.0
ini: locktimeout:
- section: passwordstore_lookup description:
key: lock - Lock timeout applied when O(lock) is not V(none).
type: str - Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals
default: write V(15m).
choices: - Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details.
- readwrite ini:
- write - section: passwordstore_lookup
- none key: locktimeout
version_added: 4.5.0 type: str
locktimeout: default: 15m
description: version_added: 4.5.0
- Lock timeout applied when O(lock) is not V(none). backend:
- Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals V(15m). description:
- Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details. - Specify which backend to use.
ini: - Defaults to V(pass), passwordstore.org's original pass utility.
- section: passwordstore_lookup - V(gopass) support is incomplete.
key: locktimeout ini:
type: str - section: passwordstore_lookup
default: 15m key: backend
version_added: 4.5.0 vars:
backend: - name: passwordstore_backend
description: type: str
- Specify which backend to use. default: pass
- Defaults to V(pass), passwordstore.org's original pass utility. choices:
- V(gopass) support is incomplete. - pass
ini: - gopass
- section: passwordstore_lookup version_added: 5.2.0
key: backend timestamp:
vars: description: Add the password generation information to the end of the file.
- name: passwordstore_backend type: bool
type: str default: true
default: pass version_added: 8.1.0
choices: preserve:
- pass description: Include the old (edited) password inside the pass file.
- gopass type: bool
version_added: 5.2.0 default: true
timestamp: version_added: 8.1.0
description: Add the password generation information to the end of the file. missing_subkey:
type: bool description:
default: true - Preference about what to do if the password subkey is missing.
version_added: 8.1.0 - If set to V(error), the lookup will error out if the subkey does not exist.
preserve: - If set to V(empty) or V(warn), will return a V(none) in case the subkey does not exist.
description: Include the old (edited) password inside the pass file. version_added: 8.6.0
type: bool type: str
default: true default: empty
version_added: 8.1.0 choices:
missing_subkey: - error
description: - warn
- Preference about what to do if the password subkey is missing. - empty
- If set to V(error), the lookup will error out if the subkey does not exist. ini:
- If set to V(empty) or V(warn), will return a V(none) in case the subkey does not exist. - section: passwordstore_lookup
version_added: 8.6.0 key: missing_subkey
type: str notes:
default: empty - The lookup supports passing all options as lookup parameters since community.general 6.0.0.
choices: """
- error EXAMPLES = r"""
- warn
- empty
ini:
- section: passwordstore_lookup
key: missing_subkey
notes:
- The lookup supports passing all options as lookup parameters since community.general 6.0.0.
'''
EXAMPLES = """
ansible.cfg: | ansible.cfg: |
[passwordstore_lookup] [passwordstore_lookup]
lock=readwrite lock=readwrite
locktimeout=45s locktimeout=45s
missing_subkey=warn missing_subkey=warn
tasks.yml: | tasks.yml: |-
--- ---
# Debug is used for examples, BAD IDEA to show passwords on screen # 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)}}" passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test', returnall=true)}}"
""" """
RETURN = """ RETURN = r"""
_raw: _raw:
description: description:
- a password - A password.
type: list type: list
elements: str elements: str
""" """

74
plugins/lookup/random_pet.py
View file

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

183
plugins/lookup/random_string.py
View file

@ -9,95 +9,94 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r""" DOCUMENTATION = r"""
name: random_string name: random_string
author: author:
- Abhijeet Kasurde (@Akasurde) - Abhijeet Kasurde (@Akasurde)
short_description: Generates random string short_description: Generates random string
version_added: '3.2.0' 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:
length:
description: The length of the string.
default: 8
type: int
upper:
description: description:
- Generates random string based upon the given constraints. - Include uppercase letters in the string.
- Uses L(random.SystemRandom,https://docs.python.org/3/library/random.html#random.SystemRandom), default: true
so should be strong enough for cryptographic purposes. type: bool
options: lower:
length: description:
description: The length of the string. - Include lowercase letters in the string.
default: 8 default: true
type: int type: bool
upper: numbers:
description: description:
- Include uppercase letters in the string. - Include numbers in the string.
default: true default: true
type: bool type: bool
lower: special:
description: description:
- Include lowercase letters in the string. - Include special characters in the string.
default: true - Special characters are taken from Python standard library C(string).
type: bool See L(the documentation of string.punctuation,https://docs.python.org/3/library/string.html#string.punctuation)
numbers: for which characters will be used.
description: - The choice of special characters can be changed to setting O(override_special).
- Include numbers in the string. default: true
default: true type: bool
type: bool min_numeric:
special: description:
description: - Minimum number of numeric characters in the string.
- Include special characters in the string. - If set, overrides O(numbers=false).
- Special characters are taken from Python standard library C(string). default: 0
See L(the documentation of string.punctuation,https://docs.python.org/3/library/string.html#string.punctuation) type: int
for which characters will be used. min_upper:
- The choice of special characters can be changed to setting O(override_special). description:
default: true - Minimum number of uppercase alphabets in the string.
type: bool - If set, overrides O(upper=false).
min_numeric: default: 0
description: type: int
- Minimum number of numeric characters in the string. min_lower:
- If set, overrides O(numbers=false). description:
default: 0 - Minimum number of lowercase alphabets in the string.
type: int - If set, overrides O(lower=false).
min_upper: default: 0
description: type: int
- Minimum number of uppercase alphabets in the string. min_special:
- If set, overrides O(upper=false). description:
default: 0 - Minimum number of special character in the string.
type: int default: 0
min_lower: type: int
description: override_special:
- Minimum number of lowercase alphabets in the string. description:
- If set, overrides O(lower=false). - Override a list of special characters to use in the string.
default: 0 - If set O(min_special) should be set to a non-default value.
type: int type: str
min_special: override_all:
description: description:
- Minimum number of special character in the string. - Override all values of O(numbers), O(upper), O(lower), and O(special) with the given list of characters.
default: 0 type: str
type: int ignore_similar_chars:
override_special: description:
description: - Ignore similar characters, such as V(l) and V(1), or V(O) and V(0).
- Override a list of special characters to use in the string. - These characters can be configured in O(similar_chars).
- If set O(min_special) should be set to a non-default value. default: false
type: str type: bool
override_all: version_added: 7.5.0
description: similar_chars:
- Override all values of O(numbers), O(upper), O(lower), and O(special) with description:
the given list of characters. - Override a list of characters not to be use in the string.
type: str default: "il1LoO0"
ignore_similar_chars: type: str
description: version_added: 7.5.0
- Ignore similar characters, such as V(l) and V(1), or V(O) and V(0). base64:
- These characters can be configured in O(similar_chars). description:
default: false - Returns base64 encoded string.
type: bool type: bool
version_added: 7.5.0 default: false
similar_chars:
description:
- Override a list of characters not to be use in the string.
default: "il1LoO0"
type: str
version_added: 7.5.0
base64:
description:
- Returns base64 encoded string.
type: bool
default: false
""" """
EXAMPLES = r""" EXAMPLES = r"""
@ -142,10 +141,10 @@ EXAMPLES = r"""
""" """
RETURN = r""" RETURN = r"""
_raw: _raw:
description: A one-element list containing a random string description: A one-element list containing a random string.
type: list type: list
elements: str elements: str
""" """
import base64 import base64

81
plugins/lookup/random_words.py
View file

@ -10,44 +10,43 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r""" DOCUMENTATION = r"""
name: random_words name: random_words
author: author:
- Thomas Sjögren (@konstruktoid) - Thomas Sjögren (@konstruktoid)
short_description: Return a number of random words short_description: Return a number of random words
version_added: "4.0.0" version_added: "4.0.0"
requirements: requirements:
- xkcdpass U(https://github.com/redacted/XKCD-password-generator) - 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.
- See U(https://xkcd.com/936/) for background.
options:
numwords:
description: description:
- Returns a number of random words. The output can for example be used for - The number of words.
passwords. default: 6
- See U(https://xkcd.com/936/) for background. type: int
options: min_length:
numwords: description:
description: - Minimum length of words to make password.
- The number of words. default: 5
default: 6 type: int
type: int max_length:
min_length: description:
description: - Maximum length of words to make password.
- Minimum length of words to make password. default: 9
default: 5 type: int
type: int delimiter:
max_length: description:
description: - The delimiter character between words.
- Maximum length of words to make password. default: " "
default: 9 type: str
type: int case:
delimiter: description:
description: - The method for setting the case of each word in the passphrase.
- The delimiter character between words. choices: ["alternating", "upper", "lower", "random", "capitalize"]
default: " " default: "lower"
type: str type: str
case:
description:
- The method for setting the case of each word in the passphrase.
choices: ["alternating", "upper", "lower", "random", "capitalize"]
default: "lower"
type: str
""" """
EXAMPLES = r""" EXAMPLES = r"""
@ -74,10 +73,10 @@ EXAMPLES = r"""
""" """
RETURN = r""" RETURN = r"""
_raw: _raw:
description: A single-element list containing random words. description: A single-element list containing random words.
type: list type: list
elements: str elements: str
""" """
from ansible.errors import AnsibleLookupError from ansible.errors import AnsibleLookupError

91
plugins/lookup/redis.py
View file

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

73
plugins/lookup/revbitspss.py
View file

@ -12,54 +12,55 @@ author: RevBits (@RevBits) <info@revbits.com>
short_description: Get secrets from RevBits PAM server short_description: Get secrets from RevBits PAM server
version_added: 4.1.0 version_added: 4.1.0
description: description:
- Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM - Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM Server using API key authentication with the REST
Server using API key authentication with the REST API. API.
requirements: requirements:
- revbits_ansible - U(https://pypi.org/project/revbits_ansible/) - revbits_ansible - U(https://pypi.org/project/revbits_ansible/)
options: options:
_terms: _terms:
description: description:
- This will be an array of keys for secrets which you want to fetch from RevBits PAM. - This will be an array of keys for secrets which you want to fetch from RevBits PAM.
required: true required: true
type: list type: list
elements: string elements: string
base_url: base_url:
description: description:
- This will be the base URL of the server, for example V(https://server-url-here). - This will be the base URL of the server, for example V(https://server-url-here).
required: true required: true
type: string type: string
api_key: api_key:
description: description:
- This will be the API key for authentication. You can get it from the RevBits PAM secret manager module. - This will be the API key for authentication. You can get it from the RevBits PAM secret manager module.
required: true required: true
type: string type: string
""" """
RETURN = r""" RETURN = r"""
_list: _list:
description: description:
- The JSON responses which you can access with defined keys. - The JSON responses which you can access with defined keys.
- If you are fetching secrets named as UUID, PASSWORD it will gives you the dict of all secrets. - If you are fetching secrets named as UUID, PASSWORD it will gives you the dict of all secrets.
type: list type: list
elements: dict elements: dict
""" """
EXAMPLES = r""" EXAMPLES = r"""
---
- hosts: localhost - hosts: localhost
vars: vars:
secret: >- secret: >-
{{ {{
lookup( lookup(
'community.general.revbitspss', 'community.general.revbitspss',
'UUIDPAM', 'DB_PASS', 'UUIDPAM', 'DB_PASS',
base_url='https://server-url-here', base_url='https://server-url-here',
api_key='API_KEY_GOES_HERE' api_key='API_KEY_GOES_HERE'
) )
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: > msg: >-
UUIDPAM is {{ (secret['UUIDPAM']) }} and DB_PASS is {{ (secret['DB_PASS']) }} UUIDPAM is {{ (secret['UUIDPAM']) }} and DB_PASS is {{ (secret['DB_PASS']) }}
""" """
from ansible.plugins.lookup import LookupBase from ansible.plugins.lookup import LookupBase

45
plugins/lookup/shelvefile.py
View file

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

388
plugins/lookup/tss.py
View file

@ -12,200 +12,196 @@ author: Adam Migus (@amigus) <adam@migus.org>
short_description: Get secrets from Thycotic Secret Server short_description: Get secrets from Thycotic Secret Server
version_added: 1.0.0 version_added: 1.0.0
description: description:
- Uses the Thycotic Secret Server Python SDK to get Secrets from Secret - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret Server using token authentication with O(username)
Server using token authentication with O(username) and O(password) on and O(password) on the REST API at O(base_url).
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
- When using self-signed certificates the environment variable trusted certificates (in C(.pem) format).
E(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates - For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt').
(in C(.pem) format).
- For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt').
requirements: requirements:
- python-tss-sdk - https://pypi.org/project/python-tss-sdk/ - python-tss-sdk - https://pypi.org/project/python-tss-sdk/
options: options:
_terms: _terms:
description: The integer ID of the secret. description: The integer ID of the secret.
required: true required: true
type: list type: list
elements: int elements: int
secret_path: secret_path:
description: Indicate a full path of secret including folder and secret name when the secret ID is set to 0. description: Indicate a full path of secret including folder and secret name when the secret ID is set to 0.
required: false required: false
type: str type: str
version_added: 7.2.0 version_added: 7.2.0
fetch_secret_ids_from_folder: fetch_secret_ids_from_folder:
description: 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. - V(true) then the terms will be considered as a folder IDs. Otherwise (default), they are considered as secret IDs.
required: false required: false
type: bool type: bool
version_added: 7.1.0 version_added: 7.1.0
fetch_attachments: fetch_attachments:
description: description:
- Boolean flag which indicates whether attached files will get downloaded or not. - Boolean flag which indicates whether attached files will get downloaded or not.
- The download will only happen if O(file_download_path) has been provided. - The download will only happen if O(file_download_path) has been provided.
required: false required: false
type: bool type: bool
version_added: 7.0.0 version_added: 7.0.0
file_download_path: file_download_path:
description: Indicate the file attachment download location. description: Indicate the file attachment download location.
required: false required: false
type: path type: path
version_added: 7.0.0 version_added: 7.0.0
base_url: base_url:
description: The base URL of the server, for example V(https://localhost/SecretServer). description: The base URL of the server, for example V(https://localhost/SecretServer).
type: string type: string
env: env:
- name: TSS_BASE_URL - name: TSS_BASE_URL
ini: ini:
- section: tss_lookup - section: tss_lookup
key: base_url key: base_url
required: true required: true
username: username:
description: The username with which to request the OAuth2 Access Grant. description: The username with which to request the OAuth2 Access Grant.
type: string type: string
env: env:
- name: TSS_USERNAME - name: TSS_USERNAME
ini: ini:
- section: tss_lookup - section: tss_lookup
key: username key: username
password: password:
description: description:
- The password associated with the supplied username. - The password associated with the supplied username.
- Required when O(token) is not provided. - Required when O(token) is not provided.
type: string type: string
env: env:
- name: TSS_PASSWORD - name: TSS_PASSWORD
ini: ini:
- section: tss_lookup - section: tss_lookup
key: password key: password
domain: domain:
default: "" default: ""
description: description:
- The domain with which to request the OAuth2 Access Grant. - The domain with which to request the OAuth2 Access Grant.
- Optional when O(token) is not provided. - Optional when O(token) is not provided.
- Requires C(python-tss-sdk) version 1.0.0 or greater. - Requires C(python-tss-sdk) version 1.0.0 or greater.
type: string type: string
env: env:
- name: TSS_DOMAIN - name: TSS_DOMAIN
ini: ini:
- section: tss_lookup - section: tss_lookup
key: domain key: domain
required: false required: false
version_added: 3.6.0 version_added: 3.6.0
token: token:
description: description:
- Existing token for Thycotic authorizer. - Existing token for Thycotic authorizer.
- If provided, O(username) and O(password) are not needed. - If provided, O(username) and O(password) are not needed.
- Requires C(python-tss-sdk) version 1.0.0 or greater. - Requires C(python-tss-sdk) version 1.0.0 or greater.
type: string type: string
env: env:
- name: TSS_TOKEN - name: TSS_TOKEN
ini: ini:
- section: tss_lookup - section: tss_lookup
key: token key: token
version_added: 3.7.0 version_added: 3.7.0
api_path_uri: api_path_uri:
default: /api/v1 default: /api/v1
description: The path to append to the base URL to form a valid REST description: The path to append to the base URL to form a valid REST API request.
API request. type: string
type: string env:
env: - name: TSS_API_PATH_URI
- name: TSS_API_PATH_URI required: false
required: false token_path_uri:
token_path_uri: default: /oauth2/token
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 type: string
Access Grant request. env:
type: string - name: TSS_TOKEN_PATH_URI
env: required: false
- name: TSS_TOKEN_PATH_URI
required: false
""" """
RETURN = r""" RETURN = r"""
_list: _list:
description: description:
- The JSON responses to C(GET /secrets/{id}). - The JSON responses to C(GET /secrets/{id}).
- See U(https://updates.thycotic.net/secretserver/restapiguide/TokenAuth/#operation--secrets--id--get). - See U(https://updates.thycotic.net/secretserver/restapiguide/TokenAuth/#operation--secrets--id--get).
type: list type: list
elements: dict elements: dict
""" """
EXAMPLES = r""" EXAMPLES = r"""
- hosts: localhost - hosts: localhost
vars: vars:
secret: >- secret: >-
{{ {{
lookup( lookup(
'community.general.tss', 'community.general.tss',
102, 102,
base_url='https://secretserver.domain.com/SecretServer/', base_url='https://secretserver.domain.com/SecretServer/',
username='user.name', username='user.name',
password='password' password='password'
) )
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: > msg: >
the password is {{ the password is {{
(secret['items'] (secret['items']
| items2dict(key_name='slug', | items2dict(key_name='slug',
value_name='itemValue'))['password'] value_name='itemValue'))['password']
}} }}
- hosts: localhost - hosts: localhost
vars: vars:
secret: >- secret: >-
{{ {{
lookup( lookup(
'community.general.tss', 'community.general.tss',
102, 102,
base_url='https://secretserver.domain.com/SecretServer/', base_url='https://secretserver.domain.com/SecretServer/',
username='user.name', username='user.name',
password='password', password='password',
domain='domain' domain='domain'
) )
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: > msg: >
the password is {{ the password is {{
(secret['items'] (secret['items']
| items2dict(key_name='slug', | items2dict(key_name='slug',
value_name='itemValue'))['password'] value_name='itemValue'))['password']
}} }}
- hosts: localhost - hosts: localhost
vars: vars:
secret_password: >- secret_password: >-
{{ {{
((lookup( ((lookup(
'community.general.tss', 'community.general.tss',
102, 102,
base_url='https://secretserver.domain.com/SecretServer/', base_url='https://secretserver.domain.com/SecretServer/',
token='thycotic_access_token', token='thycotic_access_token',
) | from_json).get('items') | items2dict(key_name='slug', value_name='itemValue'))['password'] ) | from_json).get('items') | items2dict(key_name='slug', value_name='itemValue'))['password']
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: the password is {{ secret_password }} msg: the password is {{ secret_password }}
# Private key stores into certificate file which is attached with secret. # Private key stores into certificate file which is attached with secret.
# If fetch_attachments=True then private key file will be download on specified path # If fetch_attachments=True then private key file will be download on specified path
# and file content will display in debug message. # and file content will display in debug message.
- hosts: localhost - hosts: localhost
vars: vars:
secret: >- secret: >-
{{ {{
lookup( lookup(
'community.general.tss', 'community.general.tss',
102, 102,
fetch_attachments=True, fetch_attachments=True,
file_download_path='/home/certs', file_download_path='/home/certs',
base_url='https://secretserver.domain.com/SecretServer/', base_url='https://secretserver.domain.com/SecretServer/',
token='thycotic_access_token' token='thycotic_access_token'
) )
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: > msg: >
@ -218,16 +214,16 @@ EXAMPLES = r"""
# If fetch_secret_ids_from_folder=true then secret IDs are in a folder is fetched based on folder ID # If fetch_secret_ids_from_folder=true then secret IDs are in a folder is fetched based on folder ID
- hosts: localhost - hosts: localhost
vars: vars:
secret: >- secret: >-
{{ {{
lookup( lookup(
'community.general.tss', 'community.general.tss',
102, 102,
fetch_secret_ids_from_folder=true, fetch_secret_ids_from_folder=true,
base_url='https://secretserver.domain.com/SecretServer/', base_url='https://secretserver.domain.com/SecretServer/',
token='thycotic_access_token' token='thycotic_access_token'
) )
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: > msg: >
@ -238,25 +234,25 @@ EXAMPLES = r"""
# If secret ID is 0 and secret_path has value then secret is fetched by secret path # If secret ID is 0 and secret_path has value then secret is fetched by secret path
- hosts: localhost - hosts: localhost
vars: vars:
secret: >- secret: >-
{{ {{
lookup( lookup(
'community.general.tss', 'community.general.tss',
0, 0,
secret_path='\folderName\secretName' secret_path='\folderName\secretName'
base_url='https://secretserver.domain.com/SecretServer/', base_url='https://secretserver.domain.com/SecretServer/',
username='user.name', username='user.name',
password='password' password='password'
) )
}} }}
tasks: tasks:
- ansible.builtin.debug: - ansible.builtin.debug:
msg: > msg: >-
the password is {{ the password is {{
(secret['items'] (secret['items']
| items2dict(key_name='slug', | items2dict(key_name='slug',
value_name='itemValue'))['password'] value_name='itemValue'))['password']
}} }}
""" """
import abc import abc