diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index 0f41cabe7d..b334b0f6ba 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -155,7 +155,11 @@ user: ci@pve token_id: gitlab-1 token_secret: fa256e9c-26ab-41ec-82da-707a2c079829 +--- # The secret can also be a vault string or passed via the environment variable TOKEN_SECRET. +plugin: community.general.proxmox +user: ci@pve +token_id: gitlab-1 token_secret: !vault | $ANSIBLE_VAULT;1.1;AES256 62353634333163633336343265623632626339313032653563653165313262343931643431656138 @@ -216,7 +220,6 @@ password: "{{ lookup('community.general.random_string', base64=True) }}" # Note that this can easily give you wrong values as ansible_host. See further up for # an example where this is set to `false` and where ansible_host is set with `compose`. want_proxmox_nodes_ansible_host: true - ''' import itertools diff --git a/plugins/inventory/xen_orchestra.py b/plugins/inventory/xen_orchestra.py index 4a6d431a7d..ce45b161c9 100644 --- a/plugins/inventory/xen_orchestra.py +++ b/plugins/inventory/xen_orchestra.py @@ -5,76 +5,81 @@ from __future__ import annotations -DOCUMENTATION = ''' - name: xen_orchestra - short_description: Xen Orchestra inventory source - version_added: 4.1.0 - author: - - Dom Del Nano (@ddelnano) - - Samori Gorse (@shinuza) - requirements: - - websocket-client >= 1.0.0 +DOCUMENTATION = r""" +name: xen_orchestra +short_description: Xen Orchestra inventory source +version_added: 4.1.0 +author: + - Dom Del Nano (@ddelnano) + - Samori Gorse (@shinuza) +requirements: + - websocket-client >= 1.0.0 +description: + - Get inventory hosts from a Xen Orchestra deployment. + - Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml). +extends_documentation_fragment: + - constructed + - inventory_cache +options: + plugin: + description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to + recognize it as its own. + required: true + choices: ['community.general.xen_orchestra'] + type: str + api_host: description: - - Get inventory hosts from a Xen Orchestra deployment. - - 'Uses a configuration file as an inventory source, it must end in C(.xen_orchestra.yml) or C(.xen_orchestra.yaml).' - extends_documentation_fragment: - - constructed - - inventory_cache - options: - plugin: - description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own. - required: true - choices: ['community.general.xen_orchestra'] - type: str - api_host: - description: - - API host to XOA API. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. - type: str - env: - - name: ANSIBLE_XO_HOST - user: - description: - - Xen Orchestra user. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_USER - password: - description: - - Xen Orchestra password. - - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. - required: true - type: str - env: - - name: ANSIBLE_XO_PASSWORD - validate_certs: - description: Verify TLS certificate if using HTTPS. - type: boolean - default: true - use_ssl: - description: Use wss when connecting to the Xen Orchestra API - type: boolean - default: true - use_vm_uuid: - description: - - Import Xen VMs to inventory using their UUID as the VM entry name. - - If set to V(false) use VM name labels instead of UUIDs. - 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 -''' + - API host to XOA API. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) + will be used instead. + type: str + env: + - name: ANSIBLE_XO_HOST + user: + description: + - Xen Orchestra user. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) + will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_USER + password: + description: + - Xen Orchestra password. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) + will be used instead. + required: true + type: str + env: + - name: ANSIBLE_XO_PASSWORD + validate_certs: + description: Verify TLS certificate if using HTTPS. + type: boolean + default: true + use_ssl: + description: Use wss when connecting to the Xen Orchestra API. + type: boolean + default: true + use_vm_uuid: + description: + - Import Xen VMs to inventory using their UUID as the VM entry name. + - If set to V(false) use VM name labels instead of UUIDs. + 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 plugin: community.general.xen_orchestra api_host: 192.168.1.255 @@ -83,13 +88,12 @@ password: xo_pwd validate_certs: true use_ssl: true groups: - kube_nodes: "'kube_node' in tags" + kube_nodes: "'kube_node' in tags" compose: - ansible_port: 2222 + ansible_port: 2222 use_vm_uuid: false use_host_uuid: true - -''' +""" import json import ssl diff --git a/plugins/lookup/bitwarden.py b/plugins/lookup/bitwarden.py index c41ab72ac3..13bf43b0d4 100644 --- a/plugins/lookup/bitwarden.py +++ b/plugins/lookup/bitwarden.py @@ -5,66 +5,65 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ - name: bitwarden - author: - - Jonathan Lung (@lungj) - requirements: - - bw (command line utility) - - be logged into bitwarden - - bitwarden vault unlocked - - E(BW_SESSION) environment variable set - short_description: Retrieve secrets from Bitwarden - version_added: 5.4.0 +DOCUMENTATION = r""" +name: bitwarden +author: + - Jonathan Lung (@lungj) +requirements: + - bw (command line utility) + - be logged into bitwarden + - bitwarden vault unlocked + - E(BW_SESSION) environment variable set +short_description: Retrieve secrets from Bitwarden +version_added: 5.4.0 +description: + - Retrieve secrets from Bitwarden. +options: + _terms: + description: Key(s) to fetch values for from login info. + required: true + type: list + elements: str + search: 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: - - Field to retrieve, for example V(name) or V(id). - - If set to V(id), only zero or one element can be returned. - Use the Jinja C(first) filter to get the only list element. - - If set to V(None) or V(''), or if O(_terms) is empty, records are not filtered by fields. - type: str - default: name - version_added: 5.7.0 - field: - description: Field to fetch. Leave unset to fetch whole response. - type: str - collection_id: - description: - - Collection ID to filter results by collection. Leave unset to skip filtering. - - O(collection_id) and O(collection_name) are mutually exclusive. - type: str - version_added: 6.3.0 - collection_name: - description: - - Collection name to filter results by collection. Leave unset to skip filtering. - - O(collection_id) and O(collection_name) are mutually exclusive. - type: str - version_added: 10.4.0 - organization_id: - description: Organization ID to filter results by organization. Leave unset to skip filtering. - type: str - version_added: 8.5.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 + - Field to retrieve, for example V(name) or V(id). + - If set to V(id), only zero or one element can be returned. Use the Jinja C(first) filter to get the only list element. + - If set to V(None) or V(''), or if O(_terms) is empty, records are not filtered by fields. + type: str + default: name + version_added: 5.7.0 + field: + description: Field to fetch. Leave unset to fetch whole response. + type: str + collection_id: + description: + - Collection ID to filter results by collection. Leave unset to skip filtering. + - O(collection_id) and O(collection_name) are mutually exclusive. + type: str + version_added: 6.3.0 + collection_name: + description: + - Collection name to filter results by collection. Leave unset to skip filtering. + - O(collection_id) and O(collection_name) are mutually exclusive. + type: str + version_added: 10.4.0 + organization_id: + description: Organization ID to filter results by organization. Leave unset to skip filtering. + type: str + version_added: 8.5.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'" ansible.builtin.debug: msg: >- @@ -111,14 +110,14 @@ EXAMPLES = """ {{ lookup('community.general.bitwarden', 'a_test', result_count=1) }} """ -RETURN = """ - _raw: - description: - - A one-element list that contains a list of requested fields or JSON objects of matches. - - If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true), - this always gets reduced to a list of field values or JSON objects. - type: list - elements: list +RETURN = r""" +_raw: + description: + - A one-element list that contains a list of requested fields or JSON objects of matches. + - If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true), this always gets reduced + to a list of field values or JSON objects. + type: list + elements: list """ from subprocess import Popen, PIPE diff --git a/plugins/lookup/bitwarden_secrets_manager.py b/plugins/lookup/bitwarden_secrets_manager.py index 3d08067105..431384c079 100644 --- a/plugins/lookup/bitwarden_secrets_manager.py +++ b/plugins/lookup/bitwarden_secrets_manager.py @@ -6,31 +6,31 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ - name: bitwarden_secrets_manager - author: - - jantari (@jantari) - requirements: - - bws (command line utility) - short_description: Retrieve secrets from Bitwarden Secrets Manager - version_added: 7.2.0 - description: - - Retrieve secrets from Bitwarden Secrets Manager. - options: - _terms: - description: Secret ID(s) to fetch values for. - required: true - type: list - elements: str - bws_access_token: - description: The BWS access token to use for this lookup. - env: - - name: BWS_ACCESS_TOKEN - required: true - type: str +DOCUMENTATION = r""" +name: bitwarden_secrets_manager +author: + - jantari (@jantari) +requirements: + - bws (command line utility) +short_description: Retrieve secrets from Bitwarden Secrets Manager +version_added: 7.2.0 +description: + - Retrieve secrets from Bitwarden Secrets Manager. +options: + _terms: + description: Secret ID(s) to fetch values for. + required: true + type: list + elements: str + bws_access_token: + description: The BWS access token to use for this lookup. + env: + - name: BWS_ACCESS_TOKEN + required: true + type: str """ -EXAMPLES = """ +EXAMPLES = r""" - name: Get a secret relying on the BWS_ACCESS_TOKEN environment variable for authentication ansible.builtin.debug: msg: >- @@ -62,11 +62,11 @@ EXAMPLES = """ {{ lookup("community.general.bitwarden_secrets_manager", "2bc23e48-4932-40de-a047-5524b7ddc972").value }} """ -RETURN = """ - _raw: - description: List containing one or more secrets. - type: list - elements: dict +RETURN = r""" +_raw: + description: List containing one or more secrets. + type: list + elements: dict """ from subprocess import Popen, PIPE diff --git a/plugins/lookup/cartesian.py b/plugins/lookup/cartesian.py index d63f3943b0..cdac3a2a29 100644 --- a/plugins/lookup/cartesian.py +++ b/plugins/lookup/cartesian.py @@ -6,24 +6,24 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: cartesian - short_description: returns the cartesian product of lists +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: cartesian +short_description: returns the cartesian product of lists +description: + - Takes the input lists and returns a list that represents the product of the input lists. + - It is clearer with an example, it turns [1, 2, 3], [a, b] into [1, a], [1, b], [2, a], [2, b], [3, a], [3, b]. + - You can see the exact syntax in the examples section. +options: + _terms: 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: - - a set of lists - type: list - elements: list - required: true -''' + - A set of lists. + type: list + elements: list + required: true +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Example of the change in the description ansible.builtin.debug: msg: "{{ lookup('community.general.cartesian', [1,2,3], [a, b])}}" @@ -34,15 +34,15 @@ EXAMPLES = """ with_community.general.cartesian: - "{{list1}}" - "{{list2}}" - - [1,2,3,4,5,6] + - [1, 2, 3, 4, 5, 6] """ -RETURN = """ - _list: - description: - - list of lists composed of elements of the input lists - type: list - elements: list +RETURN = r""" +_list: + description: + - List of lists composed of elements of the input lists. + type: list + elements: list """ from itertools import product diff --git a/plugins/lookup/chef_databag.py b/plugins/lookup/chef_databag.py index eaa6a1aefa..f3302c6e31 100644 --- a/plugins/lookup/chef_databag.py +++ b/plugins/lookup/chef_databag.py @@ -6,42 +6,41 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: chef_databag - short_description: fetches data from a Chef Databag +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: chef_databag +short_description: fetches data from a Chef Databag +description: + - 'This is a lookup plugin to provide access to chef data bags using the pychef package. It interfaces with the chef server + API using the same methods to find a knife or chef-client config file to load parameters from, starting from either the + given base path or the current working directory. The lookup order mirrors the one from Chef, all folders in the base + path are walked back looking for the following configuration file in order: C(.chef/knife.rb), C(~/.chef/knife.rb), C(/etc/chef/client.rb).' +requirements: + - "pychef (L(Python library, https://pychef.readthedocs.io), C(pip install pychef))" +options: + name: description: - - "This is a lookup plugin to provide access to chef data bags using the pychef package. - It interfaces with the chef server api using the same methods to find a knife or chef-client config file to load parameters from, - starting from either the given base path or the current working directory. - The lookup order mirrors the one from Chef, all folders in the base path are walked back looking for the following configuration - file in order : .chef/knife.rb, ~/.chef/knife.rb, /etc/chef/client.rb" - requirements: - - "pychef (L(Python library, https://pychef.readthedocs.io), C(pip install pychef))" - options: - 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') }}" + - Name of the databag. + type: string + required: true + item: + description: + - Item to fetch. + type: string + required: true """ -RETURN = """ - _raw: - description: - - The value from the databag. - type: list - elements: dict +EXAMPLES = r""" +- ansible.builtin.debug: + msg: "{{ lookup('community.general.chef_databag', 'name=data_bag_name item=data_bag_item') }}" +""" + +RETURN = r""" +_raw: + description: + - The value from the databag. + type: list + elements: dict """ from ansible.errors import AnsibleError diff --git a/plugins/lookup/collection_version.py b/plugins/lookup/collection_version.py index 28a9c34420..2ed8a0c466 100644 --- a/plugins/lookup/collection_version.py +++ b/plugins/lookup/collection_version.py @@ -5,18 +5,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" name: collection_version author: Felix Fontein (@felixfontein) version_added: "4.0.0" short_description: Retrieves the version of an installed collection description: - - This lookup allows to query the version of an installed collection, and to determine whether a - collection is installed at all. - - By default it returns V(none) for non-existing collections and V(*) for collections without a - version number. The latter should only happen in development environments, or when installing - a collection from git which has no version in its C(galaxy.yml). This behavior can be adjusted - by providing other values with O(result_not_found) and O(result_no_version). + - This lookup allows to query the version of an installed collection, and to determine whether a collection is installed + at all. + - By default it returns V(none) for non-existing collections and V(*) for collections without a version number. The latter + should only happen in development environments, or when installing a collection from git which has no version in its C(galaxy.yml). + This behavior can be adjusted by providing other values with O(result_not_found) and O(result_no_version). options: _terms: description: @@ -34,30 +33,27 @@ options: result_no_version: description: - The value to return when the collection has no version number. - - This can happen for collections installed from git which do not have a version number - in C(galaxy.yml). + - This can happen for collections installed from git which do not have a version number in C(galaxy.yml). - By default, V(*) is returned. type: string default: '*' """ -EXAMPLES = """ +EXAMPLES = r""" - name: Check version of community.general ansible.builtin.debug: msg: "community.general version {{ lookup('community.general.collection_version', 'community.general') }}" """ -RETURN = """ - _raw: - description: - - The version number of the collections listed as input. - - If a collection can not be found, it will return the value provided in O(result_not_found). - By default, this is V(none). - - If a collection can be found, but the version not identified, it will return the value provided in - O(result_no_version). By default, this is V(*). This can happen for collections installed - from git which do not have a version number in V(galaxy.yml). - type: list - elements: str +RETURN = r""" +_raw: + description: + - The version number of the collections listed as input. + - If a collection can not be found, it will return the value provided in O(result_not_found). By default, this is V(none). + - If a collection can be found, but the version not identified, it will return the value provided in O(result_no_version). + By default, this is V(*). This can happen for collections installed from git which do not have a version number in V(galaxy.yml). + type: list + elements: str """ import json diff --git a/plugins/lookup/consul_kv.py b/plugins/lookup/consul_kv.py index cf7226d579..349b7f3db2 100644 --- a/plugins/lookup/consul_kv.py +++ b/plugins/lookup/consul_kv.py @@ -7,109 +7,109 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: consul_kv - short_description: Fetch metadata from a Consul key value store. +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: consul_kv +short_description: Fetch metadata from a Consul key value store +description: + - Lookup metadata for a playbook from the key value store in a Consul cluster. Values can be easily set in the kv store + with simple rest commands. + - C(curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata). +requirements: + - 'python-consul python library U(https://python-consul.readthedocs.io/en/latest/#installation)' +options: + _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: - - 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: - - If the key has a value with the specified index then this is returned allowing access to historical values. - type: int - datacenter: - description: - - Retrieve the key from a consul datacenter other than the default for the consul host. - type: str - token: - description: The acl token to allow access to restricted values. - type: str - host: - default: localhost - type: str - description: - - The target to connect to, must be a resolvable address. - - Will be determined from E(ANSIBLE_CONSUL_URL) if that is set. - ini: - - section: lookup_consul - key: host - port: - description: - - The port of the target host to connect to. - - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. - type: int - default: 8500 - scheme: - default: http - type: str - description: - - Whether to use http or https. - - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. - validate_certs: - default: true - description: Whether to verify the TLS connection or not. - type: bool - env: - - name: ANSIBLE_CONSUL_VALIDATE_CERTS - ini: - - section: lookup_consul - key: validate_certs - client_cert: - description: The client cert to verify the TLS connection. - type: str - 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) }}" + - If the key has a value with the specified index then this is returned allowing access to historical values. + type: int + datacenter: + description: + - Retrieve the key from a consul datacenter other than the default for the consul host. + type: str + token: + description: The acl token to allow access to restricted values. + type: str + host: + default: localhost + type: str + description: + - The target to connect to, must be a resolvable address. + - Will be determined from E(ANSIBLE_CONSUL_URL) if that is set. + ini: + - section: lookup_consul + key: host + port: + description: + - The port of the target host to connect to. + - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. + type: int + default: 8500 + scheme: + default: http + type: str + description: + - Whether to use http or https. + - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. + validate_certs: + default: true + description: Whether to verify the TLS connection or not. + type: bool + env: + - name: ANSIBLE_CONSUL_VALIDATE_CERTS + ini: + - section: lookup_consul + key: validate_certs + client_cert: + description: The client cert to verify the TLS connection. + type: str + 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 """ -RETURN = """ - _raw: - description: - - Value(s) stored in consul. - type: dict +EXAMPLES = r""" +- ansible.builtin.debug: + msg: 'key contains {{item}}' + with_community.general.consul_kv: + - 'key/to/retrieve' + +- name: Parameters can be provided after the key be more specific about what to retrieve + 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 diff --git a/plugins/lookup/credstash.py b/plugins/lookup/credstash.py index 0700a5ddcb..4273aa184a 100644 --- a/plugins/lookup/credstash.py +++ b/plugins/lookup/credstash.py @@ -6,54 +6,54 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: credstash - short_description: retrieve secrets from Credstash on AWS - requirements: - - credstash (python library) - description: - - "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash" - options: - _terms: - description: term or list of terms to lookup in the credit store - type: list - elements: string - required: true - table: - description: name of the credstash table to query - type: str - default: 'credential-store' - version: - description: Credstash version - type: str - default: '' - region: - description: AWS region - type: str - profile_name: - description: AWS profile to use for authentication - type: str - env: - - name: AWS_PROFILE - aws_access_key_id: - description: AWS access key ID - type: str - env: - - name: AWS_ACCESS_KEY_ID - aws_secret_access_key: - description: AWS access key - type: str - env: - - name: AWS_SECRET_ACCESS_KEY - aws_session_token: - description: AWS session token - type: str - env: - - name: AWS_SESSION_TOKEN -''' +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: credstash +short_description: retrieve secrets from Credstash on AWS +requirements: + - credstash (python library) +description: + - "Credstash is a small utility for managing secrets using AWS's KMS and DynamoDB: https://github.com/fugue/credstash." +options: + _terms: + description: Term or list of terms to lookup in the credit store. + type: list + elements: string + required: true + table: + description: Name of the credstash table to query. + type: str + default: 'credential-store' + version: + description: Credstash version. + type: str + default: '' + region: + description: AWS region. + type: str + profile_name: + description: AWS profile to use for authentication. + type: str + env: + - name: AWS_PROFILE + aws_access_key_id: + description: AWS access key ID. + type: str + env: + - name: AWS_ACCESS_KEY_ID + aws_secret_access_key: + description: AWS access key. + type: str + env: + - name: AWS_SECRET_ACCESS_KEY + aws_session_token: + description: AWS session token. + type: str + env: + - name: AWS_SESSION_TOKEN +""" -EXAMPLES = """ +EXAMPLES = r""" - name: first use credstash to store your secrets ansible.builtin.shell: credstash put my-github-password secure123 @@ -77,20 +77,20 @@ EXAMPLES = """ environment: production tasks: - - name: "Test credstash lookup plugin -- get the password with a context passed as a variable" - ansible.builtin.debug: - msg: "{{ lookup('community.general.credstash', 'some-password', context=context) }}" + - name: "Test credstash lookup plugin -- get the password with a context passed as a variable" + ansible.builtin.debug: + msg: "{{ lookup('community.general.credstash', 'some-password', context=context) }}" - - name: "Test credstash lookup plugin -- get the password with a context defined here" - ansible.builtin.debug: - msg: "{{ lookup('community.general.credstash', 'some-password', context=dict(app='my_app', environment='production')) }}" + - name: "Test credstash lookup plugin -- get the password with a context defined here" + ansible.builtin.debug: + msg: "{{ lookup('community.general.credstash', 'some-password', context=dict(app='my_app', environment='production')) }}" """ -RETURN = """ - _raw: - description: - - Value(s) stored in Credstash. - type: str +RETURN = r""" +_raw: + description: + - Value(s) stored in Credstash. + type: str """ from ansible.errors import AnsibleError diff --git a/plugins/lookup/cyberarkpassword.py b/plugins/lookup/cyberarkpassword.py index 4ed040dc6d..a3a1468049 100644 --- a/plugins/lookup/cyberarkpassword.py +++ b/plugins/lookup/cyberarkpassword.py @@ -6,62 +6,64 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: Unknown (!UNKNOWN) - name: cyberarkpassword - short_description: get secrets from CyberArk AIM - requirements: - - CyberArk AIM tool installed +DOCUMENTATION = r""" +author: Unknown (!UNKNOWN) +name: cyberarkpassword +short_description: get secrets from CyberArk AIM +requirements: + - 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: - - 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: - - Specifies the desired output fields separated by commas. - - "They could be: Password, PassProps., 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' + - Specifies the desired output fields separated by commas. + - 'They could be: Password, PassProps., 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 (C(-p), C(-d), and C(-o)) to /parameters (C(/p), C(/d), and C(/o)) and change the + location of C(CLIPasswordSDK.exe). """ -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: description: A list containing one dictionary. type: list @@ -69,12 +71,12 @@ _result: contains: password: description: - - The actual value stored + - The actual value stored. passprops: - description: properties assigned to the entry + description: Properties assigned to the entry. type: dictionary passwordchangeinprocess: - description: did the password change? + description: Did the password change? """ import os diff --git a/plugins/lookup/dependent.py b/plugins/lookup/dependent.py index 2b7f293872..3e917df169 100644 --- a/plugins/lookup/dependent.py +++ b/plugins/lookup/dependent.py @@ -6,31 +6,30 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ +DOCUMENTATION = r""" name: dependent short_description: Composes a list with nested elements of other lists or dicts which can depend on previous loop variables author: Felix Fontein (@felixfontein) version_added: 3.1.0 description: - - "Takes the input lists and returns a list with elements that are lists, dictionaries, - or template expressions which evaluate to lists or dicts, composed of the elements of - the input evaluated lists and dictionaries." + - Takes the input lists and returns a list with elements that are lists, dictionaries, or template expressions which evaluate + to lists or dicts, composed of the elements of the input evaluated lists and dictionaries. options: _terms: description: - - A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary. - The name is the index that is used in the result object. The value is iterated over as described below. + - A list where the elements are one-element dictionaries, mapping a name to a string, list, or dictionary. The name + is the index that is used in the result object. The value is iterated over as described below. - If the value is a list, it is simply iterated over. - - If the value is a dictionary, it is iterated over and returned as if they would be processed by the - P(ansible.builtin.dict2items#filter) filter. - - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen - elements with C(item.). The result must be a list or a dictionary. + - If the value is a dictionary, it is iterated over and returned as if they would be processed by the P(ansible.builtin.dict2items#filter) + filter. + - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen elements with + C(item.). The result must be a list or a dictionary. type: list elements: dict required: true """ -EXAMPLES = """ +EXAMPLES = r""" - name: Install/remove public keys for active admin users ansible.posix.authorized_key: user: "{{ item.admin.key }}" @@ -76,9 +75,9 @@ EXAMPLES = """ loop_control: # Makes the output readable, so that it doesn't contain the whole subdictionaries and lists label: |- - {{ [item.zone.key, item.prefix.key, item.entry.key, - item.entry.value.ttl | default(3600), - item.entry.value.absent | default(False), item.entry.value.value] }} + {{ [item.zone.key, item.prefix.key, item.entry.key, + item.entry.value.ttl | default(3600), + item.entry.value.absent | default(False), item.entry.value.value] }} with_community.general.dependent: - zone: dns_setup - prefix: item.zone.value @@ -89,36 +88,36 @@ EXAMPLES = """ '': A: value: - - 1.2.3.4 + - 1.2.3.4 AAAA: value: - - "2a01:1:2:3::1" + - "2a01:1:2:3::1" 'test._domainkey': TXT: ttl: 300 value: - - '"k=rsa; t=s; p=MIGfMA..."' + - '"k=rsa; t=s; p=MIGfMA..."' example.org: 'www': A: value: - - 1.2.3.4 - - 5.6.7.8 + - 1.2.3.4 + - 5.6.7.8 """ -RETURN = """ - _list: - description: - - A list composed of dictionaries whose keys are the variable names from the input list. - type: list - elements: dict - sample: - - key1: a - key2: test - - key1: a - key2: foo - - key1: b - key2: bar +RETURN = r""" +_list: + description: + - A list composed of dictionaries whose keys are the variable names from the input list. + type: list + elements: dict + sample: + - key1: a + key2: test + - key1: a + key2: foo + - key1: b + key2: bar """ from ansible.errors import AnsibleLookupError diff --git a/plugins/lookup/dig.py b/plugins/lookup/dig.py index cbb597b7b5..bb5cfad73a 100644 --- a/plugins/lookup/dig.py +++ b/plugins/lookup/dig.py @@ -6,89 +6,92 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: dig - author: Jan-Piet Mens (@jpmens) - short_description: query DNS using the dnspython library - requirements: - - dnspython (python library, http://www.dnspython.org/) +DOCUMENTATION = r""" +name: dig +author: Jan-Piet Mens (@jpmens) +short_description: query DNS using the dnspython library +requirements: + - dnspython (python library, http://www.dnspython.org/) +description: + - The dig lookup runs queries against DNS servers to retrieve DNS records for a specific name (FQDN - fully qualified domain + name). It is possible to lookup any DNS record in this manner. + - 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: - - 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: - - Record type to query. - - V(DLV) has been removed in community.general 6.0.0. - - V(CAA) has been added in community.general 6.3.0. - type: str - default: 'A' - choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, SRV, SSHFP, TLSA, TXT] - flat: - description: If 0 each record is returned as a dictionary, otherwise a string. - type: int - default: 1 - retry_servfail: - description: Retry a nameserver if it returns SERVFAIL. - default: false - type: bool - version_added: 3.6.0 - fail_on_error: - description: - - Abort execution on lookup errors. - - The default for this option will likely change to V(true) in the future. - The current default, V(false), is used for backwards compatibility, and will result in empty strings - or the string V(NXDOMAIN) in the result in case of errors. - default: false - type: bool - version_added: 5.4.0 - 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. - - This option will be forced to V(true) if multiple domains to be queried are specified. - default: false - type: bool - version_added: 6.0.0 - class: - description: - - "Class." - 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. -''' + - Record type to query. + - V(DLV) has been removed in community.general 6.0.0. + - V(CAA) has been added in community.general 6.3.0. + type: str + default: 'A' + choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, + SRV, SSHFP, TLSA, TXT] + flat: + description: If 0 each record is returned as a dictionary, otherwise a string. + type: int + default: 1 + retry_servfail: + description: Retry a nameserver if it returns SERVFAIL. + default: false + type: bool + version_added: 3.6.0 + fail_on_error: + description: + - Abort execution on lookup errors. + - The default for this option will likely change to V(true) in the future. The current default, V(false), is used for + backwards compatibility, and will result in empty strings or the string V(NXDOMAIN) in the result in case of errors. + default: false + type: bool + version_added: 5.4.0 + 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. + - This option will be forced to V(true) if multiple domains to be queried are specified. + default: false + type: bool + version_added: 6.0.0 + class: + description: + - Class. + 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: + - V(ALL) is not a record in itself, merely the listed fields are available for any record results you retrieve in the form of + a dictionary. + - While the plugin supports anything which C(dnspython) supports out of the box, only a subset can be converted + into a dictionary. + - If you need to obtain the AAAA record (IPv6 address), you must specify the record type explicitly. Syntax for specifying + the record type is shown in the examples below. + - The trailing dot in most of the examples listed is purely optional, but is specified for completeness/correctness sake. +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Simple A record (IPV4 address) lookup for example.com ansible.builtin.debug: msg: "{{ lookup('community.general.dig', 'example.com.')}}" @@ -139,83 +142,83 @@ EXAMPLES = """ msg: "{{ lookup('community.general.dig', 'example.org./A', retry_servfail=true) }}" """ -RETURN = """ - _list: - description: - - List of composed strings or dictionaries with key and value - If a dictionary, fields shows the keys returned depending on query type - type: list - elements: raw - contains: - ALL: - description: - - owner, ttl, type - A: - description: - - address - AAAA: - description: - - address - CAA: - description: - - flags - - tag - - value - version_added: 6.3.0 - CNAME: - description: - - target - DNAME: - description: - - target - DNSKEY: - description: - - flags, algorithm, protocol, key - DS: - description: - - algorithm, digest_type, key_tag, digest - HINFO: - description: - - cpu, os - LOC: - description: - - latitude, longitude, altitude, size, horizontal_precision, vertical_precision - MX: - description: - - preference, exchange - NAPTR: - description: - - order, preference, flags, service, regexp, replacement - NS: - description: - - target - NSEC3PARAM: - description: - - algorithm, flags, iterations, salt - PTR: - description: - - target - RP: - description: - - mbox, txt - SOA: - description: - - mname, rname, serial, refresh, retry, expire, minimum - SPF: - description: - - strings - SRV: - description: - - priority, weight, port, target - SSHFP: - description: - - algorithm, fp_type, fingerprint - TLSA: - description: - - usage, selector, mtype, cert - TXT: - description: - - strings +RETURN = r""" +_list: + description: + - List of composed strings or of dictionaries, with fields depending + on query type. + type: list + elements: raw + contains: + ALL: + description: + - C(owner), C(ttl), C(type). + A: + description: + - C(address). + AAAA: + description: + - C(address). + CAA: + description: + - C(flags). + - C(tag). + - C(value). + version_added: 6.3.0 + CNAME: + description: + - C(target). + DNAME: + description: + - C(target). + DNSKEY: + description: + - C(flags), C(algorithm), C(protocol), C(key). + DS: + description: + - C(algorithm), C(digest_type), C(key_tag), C(digest). + HINFO: + description: + - C(cpu), C(os). + LOC: + description: + - C(latitude), C(longitude), C(altitude), C(size), C(horizontal_precision), C(vertical_precision). + MX: + description: + - C(preference), C(exchange). + NAPTR: + description: + - C(order), C(preference), C(flags), C(service), C(regexp), C(replacement). + NS: + description: + - C(target). + NSEC3PARAM: + description: + - C(algorithm), C(flags), C(iterations), C(salt). + PTR: + description: + - C(target). + RP: + description: + - C(mbox), C(txt). + SOA: + description: + - C(mname), C(rname), C(serial), C(refresh), C(retry), C(expire), C(minimum). + SPF: + description: + - C(strings). + SRV: + description: + - C(priority), C(weight), C(port), C(target). + SSHFP: + description: + - C(algorithm), C(fp_type), C(fingerprint). + TLSA: + description: + - C(usage), C(selector), C(mtype), C(cert). + TXT: + description: + - C(strings). """ from ansible.errors import AnsibleError diff --git a/plugins/lookup/dnstxt.py b/plugins/lookup/dnstxt.py index baaa63aa98..eb24a63e99 100644 --- a/plugins/lookup/dnstxt.py +++ b/plugins/lookup/dnstxt.py @@ -6,30 +6,30 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: dnstxt - author: Jan-Piet Mens (@jpmens) - short_description: query a domain(s)'s DNS txt fields - requirements: - - dns/dns.resolver (python library) +DOCUMENTATION = r""" +name: dnstxt +author: Jan-Piet Mens (@jpmens) +short_description: query a domain(s)'s DNS txt fields +requirements: + - 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: - - 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: - - 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 -''' + - 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 ansible.builtin.debug: 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(',')}}" """ -RETURN = """ - _list: - description: - - values returned by the DNS TXT record. - type: list +RETURN = r""" +_list: + description: + - Values returned by the DNS TXT record. + type: list """ HAVE_DNS = False diff --git a/plugins/lookup/dsv.py b/plugins/lookup/dsv.py index eba3e36368..0b34b3ce31 100644 --- a/plugins/lookup/dsv.py +++ b/plugins/lookup/dsv.py @@ -12,81 +12,78 @@ author: Adam Migus (@amigus) short_description: Get secrets from Thycotic DevOps Secrets Vault version_added: 1.0.0 description: - - Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a - DSV O(tenant) using a O(client_id) and O(client_secret). + - Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a DSV O(tenant) using a O(client_id) and O(client_secret). requirements: - - python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/ + - python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/ options: - _terms: - description: The path to the secret, for example V(/staging/servers/web1). - required: true - tenant: - description: The first format parameter in the default O(url_template). - type: string - env: - - name: DSV_TENANT - ini: - - section: dsv_lookup - key: tenant - required: true - tld: - default: com - description: The top-level domain of the tenant; the second format - parameter in the default O(url_template). - type: string - env: - - name: DSV_TLD - ini: - - section: dsv_lookup - key: tld - required: false - client_id: - description: The client_id with which to request the Access Grant. - type: string - env: - - name: DSV_CLIENT_ID - ini: - - section: dsv_lookup - key: client_id - required: true - client_secret: - description: The client secret associated with the specific O(client_id). - type: string - env: - - name: DSV_CLIENT_SECRET - ini: - - section: dsv_lookup - key: client_secret - required: true - url_template: - default: https://{}.secretsvaultcloud.{}/v1 - description: The path to prepend to the base URL to form a valid REST - API request. - type: string - env: - - name: DSV_URL_TEMPLATE - ini: - - section: dsv_lookup - key: url_template - required: false + _terms: + description: The path to the secret, for example V(/staging/servers/web1). + required: true + tenant: + description: The first format parameter in the default O(url_template). + type: string + env: + - name: DSV_TENANT + ini: + - section: dsv_lookup + key: tenant + required: true + tld: + default: com + description: The top-level domain of the tenant; the second format parameter in the default O(url_template). + type: string + env: + - name: DSV_TLD + ini: + - section: dsv_lookup + key: tld + required: false + client_id: + description: The client_id with which to request the Access Grant. + type: string + env: + - name: DSV_CLIENT_ID + ini: + - section: dsv_lookup + key: client_id + required: true + client_secret: + description: The client secret associated with the specific O(client_id). + type: string + env: + - name: DSV_CLIENT_SECRET + ini: + - section: dsv_lookup + key: client_secret + required: true + url_template: + default: https://{}.secretsvaultcloud.{}/v1 + description: The path to prepend to the base URL to form a valid REST API request. + type: string + env: + - name: DSV_URL_TEMPLATE + ini: + - section: dsv_lookup + key: url_template + required: false """ RETURN = r""" _list: - description: - - One or more JSON responses to C(GET /secrets/{path}). - - See U(https://dsv.thycotic.com/api/index.html#operation/getSecret). - type: list - elements: dict + description: + - One or more JSON responses to C(GET /secrets/{path}). + - See U(https://dsv.thycotic.com/api/index.html#operation/getSecret). + type: list + elements: dict """ EXAMPLES = r""" - hosts: localhost vars: - secret: "{{ lookup('community.general.dsv', '/test/secret') }}" + secret: "{{ lookup('community.general.dsv', '/test/secret') }}" tasks: - - ansible.builtin.debug: - msg: 'the password is {{ secret["data"]["password"] }}' + - ansible.builtin.debug: + msg: 'the password is {{ secret["data"]["password"] }}' """ from ansible.errors import AnsibleError, AnsibleOptionsError diff --git a/plugins/lookup/etcd.py b/plugins/lookup/etcd.py index 1e7dc3c960..d8c708bfc8 100644 --- a/plugins/lookup/etcd.py +++ b/plugins/lookup/etcd.py @@ -8,46 +8,46 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: - - Jan-Piet Mens (@jpmens) - name: etcd - short_description: get info from an etcd server +DOCUMENTATION = r""" +author: + - Jan-Piet Mens (@jpmens) +name: etcd +short_description: get info from an etcd server +description: + - Retrieves data from an etcd server. +options: + _terms: description: - - Retrieves data from an etcd server - options: - _terms: - description: - - the list of keys to lookup on the etcd server - type: list - elements: string - required: true - url: - description: - - Environment variable with the URL for the etcd server - type: string - default: 'http://127.0.0.1:4001' - env: - - name: ANSIBLE_ETCD_URL - version: - description: - - Environment variable with the etcd protocol version - type: string - default: 'v1' - env: - - name: ANSIBLE_ETCD_VERSION - validate_certs: - description: - - toggle checking that the ssl certificates are valid, you normally only want to turn this off with self-signed certs. - default: true - type: boolean - seealso: - - module: community.general.etcd3 - - plugin: community.general.etcd3 - plugin_type: lookup -''' + - The list of keys to lookup on the etcd server. + type: list + elements: string + required: true + url: + description: + - Environment variable with the URL for the etcd server. + type: string + default: 'http://127.0.0.1:4001' + env: + - name: ANSIBLE_ETCD_URL + version: + description: + - Environment variable with the etcd protocol version. + type: string + default: 'v1' + env: + - name: ANSIBLE_ETCD_VERSION + validate_certs: + description: + - Toggle checking that the ssl certificates are valid, you normally only want to turn this off with self-signed certs. + default: true + type: boolean +seealso: + - module: community.general.etcd3 + - plugin: community.general.etcd3 + plugin_type: lookup +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: "a value from a locally running etcd" ansible.builtin.debug: msg: "{{ lookup('community.general.etcd', 'foo/bar') }}" @@ -59,15 +59,15 @@ EXAMPLES = ''' - name: "you can set server options inline" ansible.builtin.debug: msg: "{{ lookup('community.general.etcd', 'foo', version='v2', url='http://192.168.0.27:4001') }}" -''' +""" -RETURN = ''' - _raw: - description: - - List of values associated with input keys. - type: list - elements: string -''' +RETURN = r""" +_raw: + description: + - List of values associated with input keys. + type: list + elements: string +""" import json diff --git a/plugins/lookup/etcd3.py b/plugins/lookup/etcd3.py index c67e975b97..2af1e9052b 100644 --- a/plugins/lookup/etcd3.py +++ b/plugins/lookup/etcd3.py @@ -7,101 +7,101 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - author: - - Eric Belhomme (@eric-belhomme) - version_added: '0.2.0' - name: etcd3 - short_description: Get key values from etcd3 server +DOCUMENTATION = r""" +author: + - Eric Belhomme (@eric-belhomme) +version_added: '0.2.0' +name: etcd3 +short_description: Get key values from etcd3 server +description: + - Retrieves key values and/or key prefixes from etcd3 server using its native gRPC API. + - Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some E(ETCDCTL_*) environment + variables. + - See U(https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide) for etcd overview. +options: + _terms: description: - - Retrieves key values and/or key prefixes from etcd3 server using its native gRPC API. - - Try to reuse M(community.general.etcd3) options for connection parameters, but add support for some C(ETCDCTL_*) environment variables. - - See U(https://github.com/etcd-io/etcd/tree/master/Documentation/op-guide) for etcd overview. + - The list of keys (or key prefixes) to look up on the etcd3 server. + type: list + 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(:) 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: - _terms: - description: - - The list of keys (or key prefixes) to look up on the etcd3 server. - type: list - 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 and URL form, for example V(https://hostname:2379), or V(:) 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: + - O(host) and O(port) options take precedence over (endpoints) option. + - The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT) environment variable and keep O(endpoints), + O(host), and O(port) unused. +seealso: + - module: community.general.etcd3 + - plugin: community.general.etcd + plugin_type: lookup - notes: - - O(host) and O(port) options take precedence over (endpoints) option. - - The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT) - environment variable and keep O(endpoints), O(host), and O(port) unused. - seealso: - - module: community.general.etcd3 - - plugin: community.general.etcd - plugin_type: lookup +requirements: + - "etcd3 >= 0.10" +""" - requirements: - - "etcd3 >= 0.10" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: "a value from a locally running etcd" ansible.builtin.debug: msg: "{{ lookup('community.general.etcd3', 'foo/bar') }}" @@ -117,22 +117,22 @@ EXAMPLES = ''' - name: "connect to etcd3 with a client certificate" ansible.builtin.debug: msg: "{{ lookup('community.general.etcd3', 'foo/bar', cert_cert='/etc/ssl/etcd/client.pem', cert_key='/etc/ssl/etcd/client.key') }}" -''' +""" -RETURN = ''' - _raw: - description: - - List of keys and associated values. - type: list - elements: dict - contains: - key: - description: The element's key. - type: str - value: - description: The element's value. - type: str -''' +RETURN = r""" +_raw: + description: + - List of keys and associated values. + type: list + elements: dict + contains: + key: + description: The element's key. + type: str + value: + description: The element's value. + type: str +""" import re diff --git a/plugins/lookup/filetree.py b/plugins/lookup/filetree.py index 3036e152c2..fd064cb4e6 100644 --- a/plugins/lookup/filetree.py +++ b/plugins/lookup/filetree.py @@ -6,22 +6,23 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" name: filetree author: Dag Wieers (@dagwieers) short_description: recursively match all files in a directory tree description: -- This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership. -- Supports directories, files and symlinks, including SELinux and other file properties. -- If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed in previous paths. - This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role. + - This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership. + - Supports directories, files and symlinks, including SELinux and other file properties. + - If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed + in previous paths. This enables merging different trees in order of importance, or add role_vars to specific paths to + influence different instances of the same role. options: _terms: description: Path(s) of files to read. required: true type: list elements: string -''' +""" EXAMPLES = r""" - name: Create directories @@ -59,61 +60,61 @@ EXAMPLES = r""" """ RETURN = r""" - _raw: - description: List of dictionaries with file information. - type: list - elements: dict - contains: - src: - description: - - Full path to file. - - Not returned when RV(_raw[].state) is set to V(directory). - type: path - root: - description: Allows filtering by original location. - type: path - path: - description: Contains the relative path to root. - type: path - mode: - description: The permissions the resulting file or directory. - type: str - state: - description: TODO - type: str - owner: - description: Name of the user that owns the file/directory. - type: raw - group: - description: Name of the group that owns the file/directory. - type: raw - seuser: - description: The user part of the SELinux file context. - type: raw - serole: - description: The role part of the SELinux file context. - type: raw - setype: - description: The type part of the SELinux file context. - type: raw - selevel: - description: The level part of the SELinux file context. - type: raw - uid: - description: Owner ID of the file/directory. - type: int - gid: - description: Group ID of the file/directory. - type: int - size: - description: Size of the target. - type: int - mtime: - description: Time of last modification. - type: float - ctime: - description: Time of last metadata update or creation (depends on OS). - type: float +_raw: + description: List of dictionaries with file information. + type: list + elements: dict + contains: + src: + description: + - Full path to file. + - Not returned when RV(_raw[].state) is set to V(directory). + type: path + root: + description: Allows filtering by original location. + type: path + path: + description: Contains the relative path to root. + type: path + mode: + description: The permissions the resulting file or directory. + type: str + state: + description: TODO. + type: str + owner: + description: Name of the user that owns the file/directory. + type: raw + group: + description: Name of the group that owns the file/directory. + type: raw + seuser: + description: The user part of the SELinux file context. + type: raw + serole: + description: The role part of the SELinux file context. + type: raw + setype: + description: The type part of the SELinux file context. + type: raw + selevel: + description: The level part of the SELinux file context. + type: raw + uid: + description: Owner ID of the file/directory. + type: int + gid: + description: Group ID of the file/directory. + type: int + size: + description: Size of the target. + type: int + mtime: + description: Time of last modification. + type: float + ctime: + description: Time of last metadata update or creation (depends on OS). + type: float """ import os import pwd diff --git a/plugins/lookup/flattened.py b/plugins/lookup/flattened.py index 5365f2ca99..c558df110f 100644 --- a/plugins/lookup/flattened.py +++ b/plugins/lookup/flattened.py @@ -6,35 +6,35 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: flattened - author: Serge van Ginderachter (!UNKNOWN) - short_description: return single list completely flattened - description: - - Given one or more lists, this lookup will flatten any list elements found recursively until only 1 list is left. - options: - _terms: - description: lists to flatten - type: list - elements: raw - required: true - notes: - - Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level, - this plugin will continue to flatten until it cannot find lists anymore. - - Aka highlander plugin, there can only be one (list). -''' +DOCUMENTATION = r""" +name: flattened +author: Serge van Ginderachter (!UNKNOWN) +short_description: return single list completely flattened +description: + - Given one or more lists, this lookup will flatten any list elements found recursively until only 1 list is left. +options: + _terms: + description: Lists to flatten. + type: list + elements: raw + required: true +notes: + - Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level, this plugin will continue to flatten until + it cannot find lists anymore. + - Aka highlander plugin, there can only be one (list). +""" -EXAMPLES = """ +EXAMPLES = r""" - name: "'unnest' all elements into single list" ansible.builtin.debug: msg: "all in one list {{lookup('community.general.flattened', [1,2,3,[5,6]], ['a','b','c'], [[5,6,1,3], [34,'a','b','c']])}}" """ -RETURN = """ - _raw: - description: - - flattened list - type: list +RETURN = r""" +_raw: + description: + - Flattened list. + type: list """ from ansible.errors import AnsibleError from ansible.module_utils.six import string_types diff --git a/plugins/lookup/github_app_access_token.py b/plugins/lookup/github_app_access_token.py index 73fd09a0a9..dbc8cde3b5 100644 --- a/plugins/lookup/github_app_access_token.py +++ b/plugins/lookup/github_app_access_token.py @@ -5,49 +5,49 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: github_app_access_token - author: - - Poh Wei Sheng (@weisheng-p) - short_description: Obtain short-lived Github App Access tokens - version_added: '8.2.0' - requirements: - - jwt (https://github.com/GehirnInc/python-jwt) +DOCUMENTATION = r""" +name: github_app_access_token +author: + - Poh Wei Sheng (@weisheng-p) +short_description: Obtain short-lived Github App Access tokens +version_added: '8.2.0' +requirements: + - 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: - - 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: - - Path to your private key. - - Either O(key_path) or O(private_key) must be specified. - type: path - app_id: - description: - - Your GitHub App ID, you can find this in the Settings page. - required: true - type: str - installation_id: - description: - - The installation ID that contains the git repository you would like access to. - - As of 2023-12-24, this can be found via Settings page > Integrations > Application. The last part of the URL in the - configure button is the installation ID. - - Alternatively, you can use PyGithub (U(https://github.com/PyGithub/PyGithub)) to get your installation ID. - required: true - type: str - private_key: - description: - - GitHub App private key in PEM file format as string. - - Either O(key_path) or O(private_key) must be specified. - type: str - version_added: 10.0.0 - token_expiry: - description: - - How long the token should last for in seconds. - default: 600 - type: int -''' + - Path to your private key. + - Either O(key_path) or O(private_key) must be specified. + type: path + app_id: + description: + - Your GitHub App ID, you can find this in the Settings page. + required: true + type: str + installation_id: + description: + - The installation ID that contains the git repository you would like access to. + - As of 2023-12-24, this can be found at Settings page > Integrations > Application. The last part of the URL in the + configure button is the installation ID. + - Alternatively, you can use PyGithub (U(https://github.com/PyGithub/PyGithub)) to get your installation ID. + required: true + type: str + private_key: + description: + - GitHub App private key in PEM file format as string. + - Either O(key_path) or O(private_key) must be specified. + type: str + version_added: 10.0.0 + token_expiry: + 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 ansible.builtin.git: repo: >- @@ -57,14 +57,14 @@ EXAMPLES = ''' github_token: >- {{ lookup('community.general.github_app_access_token', key_path='/home/to_your/key', app_id='123456', installation_id='64209') }} -''' +""" -RETURN = ''' - _raw: - description: A one-element list containing your GitHub access token. - type: list - elements: str -''' +RETURN = r""" +_raw: + description: A one-element list containing your GitHub access token. + type: list + elements: str +""" try: diff --git a/plugins/lookup/hiera.py b/plugins/lookup/hiera.py index 8463a8844e..7aacad4e26 100644 --- a/plugins/lookup/hiera.py +++ b/plugins/lookup/hiera.py @@ -6,40 +6,40 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - author: - - Juan Manuel Parrilla (@jparrill) - name: hiera - short_description: get info from hiera data - requirements: - - hiera (command line utility) +DOCUMENTATION = r""" +author: + - Juan Manuel Parrilla (@jparrill) +name: hiera +short_description: get info from hiera data +requirements: + - hiera (command line utility) +description: + - Retrieves data from an Puppetmaster node using Hiera as ENC. +options: + _terms: description: - - Retrieves data from an Puppetmaster node using Hiera as ENC. - options: - _terms: - description: - - The list of keys to lookup on the Puppetmaster. - type: list - elements: string - required: true - executable: - description: - - Binary file to execute Hiera. - type: string - default: '/usr/bin/hiera' - env: - - name: ANSIBLE_HIERA_BIN - config_file: - description: - - File that describes the hierarchy of Hiera. - type: string - default: '/etc/hiera.yaml' - env: - - name: ANSIBLE_HIERA_CFG + - The list of keys to lookup on the Puppetmaster. + type: list + elements: string + required: true + executable: + description: + - Binary file to execute Hiera. + type: string + default: '/usr/bin/hiera' + env: + - name: ANSIBLE_HIERA_BIN + config_file: + description: + - File that describes the hierarchy of Hiera. + type: string + default: '/etc/hiera.yaml' + env: + - name: ANSIBLE_HIERA_CFG # FIXME: incomplete options .. _terms? environment/fqdn? -''' +""" -EXAMPLES = """ +EXAMPLES = r""" # All this examples depends on hiera.yml that describes the hierarchy - name: "a value from Hiera 'DB'" @@ -55,12 +55,12 @@ EXAMPLES = """ msg: "{{ lookup('community.general.hiera', 'foo fqdn=puppet01.localdomain') }}" """ -RETURN = """ - _raw: - description: - - a value associated with input key - type: list - elements: str +RETURN = r""" +_raw: + description: + - A value associated with input key. + type: list + elements: str """ from ansible.plugins.lookup import LookupBase diff --git a/plugins/lookup/keyring.py b/plugins/lookup/keyring.py index ebc35a8ee1..2cbc2ea8c2 100644 --- a/plugins/lookup/keyring.py +++ b/plugins/lookup/keyring.py @@ -7,18 +7,18 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: keyring - author: - - Samuel Boucher (!UNKNOWN) - requirements: - - keyring (python library) - short_description: grab secrets from the OS keyring - description: - - Allows you to access data stored in the OS provided keyring/keychain. -''' +DOCUMENTATION = r""" +name: keyring +author: + - Samuel Boucher (!UNKNOWN) +requirements: + - keyring (python library) +short_description: grab secrets from the OS keyring +description: + - Allows you to access data stored in the OS provided keyring/keychain. +""" -EXAMPLES = """ +EXAMPLES = r""" - name: output secrets to screen (BAD IDEA) ansible.builtin.debug: msg: "Password: {{item}}" @@ -31,11 +31,11 @@ EXAMPLES = """ login_user: joe """ -RETURN = """ - _raw: - description: Secrets stored. - type: list - elements: str +RETURN = r""" +_raw: + description: Secrets stored. + type: list + elements: str """ HAS_KEYRING = True diff --git a/plugins/lookup/lastpass.py b/plugins/lookup/lastpass.py index 70ef8d1414..28b9af3466 100644 --- a/plugins/lookup/lastpass.py +++ b/plugins/lookup/lastpass.py @@ -6,39 +6,39 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: lastpass - author: - - Andrew Zenk (!UNKNOWN) - requirements: - - lpass (command line utility) - - must have already logged into LastPass - short_description: fetch data from LastPass - description: - - Use the lpass command line utility to fetch specific fields from LastPass. - options: - _terms: - description: Key from which you want to retrieve the field. - required: true - type: list - elements: str - field: - description: Field to return from LastPass. - default: 'password' - type: str -''' +DOCUMENTATION = r""" +name: lastpass +author: + - Andrew Zenk (!UNKNOWN) +requirements: + - lpass (command line utility) + - must have already logged into LastPass +short_description: fetch data from LastPass +description: + - Use the lpass command line utility to fetch specific fields from LastPass. +options: + _terms: + description: Key from which you want to retrieve the field. + required: true + type: list + elements: str + field: + description: Field to return from LastPass. + default: 'password' + type: str +""" -EXAMPLES = """ +EXAMPLES = r""" - name: get 'custom_field' from LastPass entry 'entry-name' ansible.builtin.debug: msg: "{{ lookup('community.general.lastpass', 'entry-name', field='custom_field') }}" """ -RETURN = """ - _raw: - description: secrets stored - type: list - elements: str +RETURN = r""" +_raw: + description: Secrets stored. + type: list + elements: str """ from subprocess import Popen, PIPE diff --git a/plugins/lookup/lmdb_kv.py b/plugins/lookup/lmdb_kv.py index c09321d081..d44aac55c3 100644 --- a/plugins/lookup/lmdb_kv.py +++ b/plugins/lookup/lmdb_kv.py @@ -6,30 +6,30 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: lmdb_kv - author: - - Jan-Piet Mens (@jpmens) - version_added: '0.2.0' - short_description: fetch data from LMDB - description: - - This lookup returns a list of results from an LMDB DB corresponding to a list of items given to it. - requirements: - - lmdb (Python library U(https://lmdb.readthedocs.io/en/release/)) - options: - _terms: - description: List of keys to query. - type: list - elements: str - db: - description: Path to LMDB database. - type: str - default: 'ansible.mdb' - vars: - - name: lmdb_kv_db -''' +DOCUMENTATION = r""" +name: lmdb_kv +author: + - Jan-Piet Mens (@jpmens) +version_added: '0.2.0' +short_description: fetch data from LMDB +description: + - This lookup returns a list of results from an LMDB DB corresponding to a list of items given to it. +requirements: + - lmdb (Python library U(https://lmdb.readthedocs.io/en/release/)) +options: + _terms: + description: List of keys to query. + type: list + elements: str + db: + description: Path to LMDB database. + type: str + default: 'ansible.mdb' + vars: + - name: lmdb_kv_db +""" -EXAMPLES = """ +EXAMPLES = r""" - name: query LMDB for a list of country codes ansible.builtin.debug: msg: "{{ query('community.general.lmdb_kv', 'nl', 'be', 'lu', db='jp.mdb') }}" @@ -40,7 +40,7 @@ EXAMPLES = """ vars: - lmdb_kv_db: jp.mdb with_community.general.lmdb_kv: - - "n*" + - "n*" - name: get an item by key ansible.builtin.assert: @@ -52,9 +52,9 @@ EXAMPLES = """ - be """ -RETURN = """ +RETURN = r""" _raw: - description: value(s) stored in LMDB + description: Value(s) stored in LMDB. type: list elements: raw """ diff --git a/plugins/lookup/merge_variables.py b/plugins/lookup/merge_variables.py index e352524292..f3f185a164 100644 --- a/plugins/lookup/merge_variables.py +++ b/plugins/lookup/merge_variables.py @@ -6,72 +6,71 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ - author: - - Roy Lenferink (@rlenferink) - - Mark Ettema (@m-a-r-k-e) - - Alexander Petrenz (@alpex8) - name: merge_variables - short_description: merge variables whose names match a given pattern +DOCUMENTATION = r""" +author: + - Roy Lenferink (@rlenferink) + - Mark Ettema (@m-a-r-k-e) + - Alexander Petrenz (@alpex8) +name: merge_variables +short_description: merge variables whose names match a given pattern +description: + - This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or regular expressions, + optionally. +version_added: 6.5.0 +options: + _terms: description: - - This lookup returns the merged result of all variables in scope that match the given prefixes, suffixes, or - regular expressions, optionally. - version_added: 6.5.0 - options: - _terms: - description: - - Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions - that will be used to match all variables that should be merged. - required: true - type: list - elements: str - pattern_type: - description: - - Change the way of searching for the specified pattern. - type: str - default: 'regex' - choices: - - prefix - - suffix - - regex - env: - - name: ANSIBLE_MERGE_VARIABLES_PATTERN_TYPE - ini: - - section: merge_variables_lookup - key: pattern_type - initial_value: - description: - - An initial value to start with. - type: raw - override: - description: - - Return an error, print a warning or ignore it when a key will be overwritten. - - The default behavior V(error) makes the plugin fail when a key would be overwritten. - - When V(warn) and V(ignore) are used, note that it is important to know that the variables - are sorted by name before being merged. Keys for later variables in this order will overwrite - keys of the same name for variables earlier in this order. To avoid potential confusion, - better use O(override=error) whenever possible. - type: str - default: 'error' - choices: - - error - - warn - - ignore - env: - - name: ANSIBLE_MERGE_VARIABLES_OVERRIDE - ini: - - section: merge_variables_lookup - key: override - groups: - description: - - Search for variables accross hosts that belong to the given groups. This allows to collect configuration pieces - accross different hosts (for example a service on a host with its database on another host). - type: list - elements: str - version_added: 8.5.0 + - Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions that will + be used to match all variables that should be merged. + required: true + type: list + elements: str + pattern_type: + description: + - Change the way of searching for the specified pattern. + type: str + default: 'regex' + choices: + - prefix + - suffix + - regex + env: + - name: ANSIBLE_MERGE_VARIABLES_PATTERN_TYPE + ini: + - section: merge_variables_lookup + key: pattern_type + initial_value: + description: + - An initial value to start with. + type: raw + override: + description: + - Return an error, print a warning or ignore it when a key will be overwritten. + - The default behavior V(error) makes the plugin fail when a key would be overwritten. + - When V(warn) and V(ignore) are used, note that it is important to know that the variables are sorted by name before + being merged. Keys for later variables in this order will overwrite keys of the same name for variables earlier in + this order. To avoid potential confusion, better use O(override=error) whenever possible. + type: str + default: 'error' + choices: + - error + - warn + - ignore + env: + - name: ANSIBLE_MERGE_VARIABLES_OVERRIDE + ini: + - section: merge_variables_lookup + key: override + groups: + description: + - Search for variables across hosts that belong to the given groups. This allows to collect configuration pieces across + different hosts (for example a service on a host with its database on another host). + type: list + elements: str + version_added: 8.5.0 """ -EXAMPLES = """ +EXAMPLES = r""" # Some example variables, they can be defined anywhere as long as they are in scope test_init_list: - "list init item 1" @@ -91,7 +90,6 @@ testb__test_dict: ports: - 3 - # Merge variables that end with '__test_dict' and store the result in a variable 'example_a' example_a: "{{ lookup('community.general.merge_variables', '__test_dict', pattern_type='suffix') }}" @@ -100,7 +98,6 @@ example_a: "{{ lookup('community.general.merge_variables', '__test_dict', patter # - 1 # - 3 - # Merge variables that match the '^.+__test_list$' regular expression, starting with an initial value and store the # result in a variable 'example_b' example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', initial_value=test_init_list) }}" @@ -112,12 +109,12 @@ example_b: "{{ lookup('community.general.merge_variables', '^.+__test_list$', in # - "test b item 1" """ -RETURN = """ - _raw: - description: In case the search matches list items, a list will be returned. In case the search matches dicts, a - dict will be returned. - type: raw - elements: raw +RETURN = r""" +_raw: + description: In case the search matches list items, a list will be returned. In case the search matches dicts, a dict will + be returned. + type: raw + elements: raw """ import re diff --git a/plugins/lookup/onepassword.py b/plugins/lookup/onepassword.py index ce0179a31e..d30234f14d 100644 --- a/plugins/lookup/onepassword.py +++ b/plugins/lookup/onepassword.py @@ -8,39 +8,40 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: onepassword - author: - - Scott Buchanan (@scottsb) - - Andrew Zenk (@azenk) - - Sam Doran (@samdoran) - short_description: Fetch field values from 1Password - description: - - P(community.general.onepassword#lookup) wraps the C(op) command line utility to fetch specific field values from 1Password. - requirements: - - C(op) 1Password command line utility - options: - _terms: - description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. - required: true - type: list - elements: string - account_id: - version_added: 7.5.0 - domain: - version_added: 3.2.0 - field: - description: Field to return from each matching item (case-insensitive). - default: 'password' - type: str - service_account_token: - version_added: 7.1.0 - extends_documentation_fragment: - - community.general.onepassword - - community.general.onepassword.lookup -''' +DOCUMENTATION = r""" +name: onepassword +author: + - Scott Buchanan (@scottsb) + - Andrew Zenk (@azenk) + - Sam Doran (@samdoran) +short_description: Fetch field values from 1Password +description: + - P(community.general.onepassword#lookup) wraps the C(op) command line utility to fetch specific field values from 1Password. +requirements: + - C(op) 1Password command line utility +options: + _terms: + description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. + required: true + type: list + elements: string + account_id: + version_added: 7.5.0 + domain: + version_added: 3.2.0 + field: + description: Field to return from each matching item (case-insensitive). + default: 'password' + type: str + service_account_token: + version_added: 7.1.0 +extends_documentation_fragment: + - community.general.onepassword + - community.general.onepassword.lookup +""" -EXAMPLES = """ +EXAMPLES = r""" +--- # These examples only work when already signed in to 1Password - name: Retrieve password for KITT when already signed in to 1Password ansible.builtin.debug: @@ -56,32 +57,24 @@ EXAMPLES = """ - name: Retrieve password for HAL when not signed in to 1Password ansible.builtin.debug: - var: lookup('community.general.onepassword', - 'HAL 9000', - subdomain='Discovery', - master_password=vault_master_password) + var: lookup('community.general.onepassword', 'HAL 9000', subdomain='Discovery', master_password=vault_master_password) - name: Retrieve password for HAL when never signed in to 1Password ansible.builtin.debug: - var: lookup('community.general.onepassword', - 'HAL 9000', - subdomain='Discovery', - master_password=vault_master_password, - username='tweety@acme.com', - secret_key=vault_secret_key) + var: >- + lookup('community.general.onepassword', 'HAL 9000', subdomain='Discovery', master_password=vault_master_password, + username='tweety@acme.com', secret_key=vault_secret_key) - name: Retrieve password from specific account ansible.builtin.debug: - var: lookup('community.general.onepassword', - 'HAL 9000', - account_id='abc123') + var: lookup('community.general.onepassword', 'HAL 9000', account_id='abc123') """ -RETURN = """ - _raw: - description: Field data requested. - type: list - elements: str +RETURN = r""" +_raw: + description: Field data requested. + type: list + elements: str """ import abc diff --git a/plugins/lookup/onepassword_doc.py b/plugins/lookup/onepassword_doc.py index 5ffcf02c69..82ca790a31 100644 --- a/plugins/lookup/onepassword_doc.py +++ b/plugins/lookup/onepassword_doc.py @@ -6,43 +6,43 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: onepassword_doc - author: - - Sam Doran (@samdoran) - requirements: - - C(op) 1Password command line utility version 2 or later. - short_description: Fetch documents stored in 1Password - version_added: "8.1.0" - description: - - P(community.general.onepassword_doc#lookup) wraps C(op) command line utility to fetch one or more documents from 1Password. - notes: - - The document contents are a string exactly as stored in 1Password. - - This plugin requires C(op) version 2 or later. +DOCUMENTATION = r""" +name: onepassword_doc +author: + - Sam Doran (@samdoran) +requirements: + - C(op) 1Password command line utility version 2 or later. +short_description: Fetch documents stored in 1Password +version_added: "8.1.0" +description: + - P(community.general.onepassword_doc#lookup) wraps C(op) command line utility to fetch one or more documents from 1Password. +notes: + - The document contents are a string exactly as stored in 1Password. + - 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: - _terms: - description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. - required: true - type: list - elements: string +extends_documentation_fragment: + - community.general.onepassword + - community.general.onepassword.lookup +""" - extends_documentation_fragment: - - community.general.onepassword - - community.general.onepassword.lookup -''' - -EXAMPLES = """ +EXAMPLES = r""" +--- - name: Retrieve a private key from 1Password ansible.builtin.debug: var: lookup('community.general.onepassword_doc', 'Private key') """ -RETURN = """ - _raw: - description: Requested document - type: list - elements: string +RETURN = r""" +_raw: + description: Requested document. + type: list + elements: string """ from ansible_collections.community.general.plugins.lookup.onepassword import OnePass, OnePassCLIv2 diff --git a/plugins/lookup/onepassword_raw.py b/plugins/lookup/onepassword_raw.py index dc3e590329..2d9829ec9d 100644 --- a/plugins/lookup/onepassword_raw.py +++ b/plugins/lookup/onepassword_raw.py @@ -8,35 +8,36 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: onepassword_raw - author: - - Scott Buchanan (@scottsb) - - Andrew Zenk (@azenk) - - Sam Doran (@samdoran) - requirements: - - C(op) 1Password command line utility - short_description: Fetch an entire item from 1Password - description: - - P(community.general.onepassword_raw#lookup) wraps C(op) command line utility to fetch an entire item from 1Password. - options: - _terms: - description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. - required: true - type: list - elements: string - account_id: - version_added: 7.5.0 - domain: - version_added: 6.0.0 - service_account_token: - version_added: 7.1.0 - extends_documentation_fragment: - - community.general.onepassword - - community.general.onepassword.lookup -''' +DOCUMENTATION = r""" +name: onepassword_raw +author: + - Scott Buchanan (@scottsb) + - Andrew Zenk (@azenk) + - Sam Doran (@samdoran) +requirements: + - C(op) 1Password command line utility +short_description: Fetch an entire item from 1Password +description: + - P(community.general.onepassword_raw#lookup) wraps C(op) command line utility to fetch an entire item from 1Password. +options: + _terms: + description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. + required: true + type: list + elements: string + account_id: + version_added: 7.5.0 + domain: + version_added: 6.0.0 + service_account_token: + version_added: 7.1.0 +extends_documentation_fragment: + - community.general.onepassword + - community.general.onepassword.lookup +""" -EXAMPLES = """ +EXAMPLES = r""" +--- - name: Retrieve all data about Wintermute ansible.builtin.debug: var: lookup('community.general.onepassword_raw', 'Wintermute') @@ -46,11 +47,11 @@ EXAMPLES = """ var: lookup('community.general.onepassword_raw', 'Wintermute', subdomain='Turing', vault_password='DmbslfLvasjdl') """ -RETURN = """ - _raw: - description: Entire item requested. - type: list - elements: dict +RETURN = r""" +_raw: + description: Entire item requested. + type: list + elements: dict """ import json diff --git a/plugins/lookup/onepassword_ssh_key.py b/plugins/lookup/onepassword_ssh_key.py index 253d8c68f4..395de59f23 100644 --- a/plugins/lookup/onepassword_ssh_key.py +++ b/plugins/lookup/onepassword_ssh_key.py @@ -5,7 +5,7 @@ from __future__ import annotations -DOCUMENTATION = """ +DOCUMENTATION = r""" name: onepassword_ssh_key author: - Mohammed Babelly (@mohammedbabelly20) @@ -19,7 +19,6 @@ notes: - By default, it returns the private key value in PKCS#8 format, unless O(ssh_format=true) is passed. - The pluging works only for C(SSHKEY) type items. - This plugin requires C(op) version 2 or later. - options: _terms: description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve. @@ -36,13 +35,14 @@ extends_documentation_fragment: - community.general.onepassword.lookup """ -EXAMPLES = """ +EXAMPLES = r""" +--- - name: Retrieve the private SSH key from 1Password ansible.builtin.debug: msg: "{{ lookup('community.general.onepassword_ssh_key', 'SSH Key', ssh_format=true) }}" """ -RETURN = """ +RETURN = r""" _raw: description: Private key of SSH keypair. type: list diff --git a/plugins/lookup/passwordstore.py b/plugins/lookup/passwordstore.py index 479f8d537a..54e89d6f8f 100644 --- a/plugins/lookup/passwordstore.py +++ b/plugins/lookup/passwordstore.py @@ -7,167 +7,168 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: passwordstore - author: - - Patrick Deelman (!UNKNOWN) - short_description: manage passwords with passwordstore.org's pass utility +DOCUMENTATION = r""" +name: passwordstore +author: + - Patrick Deelman (!UNKNOWN) +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: - - 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: - - The directory of the password store. - - If O(backend=pass), the default is V(~/.password-store) is used. - - If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), - falling back to V(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config. - type: path - vars: - - name: passwordstore - env: - - name: PASSWORD_STORE_DIR - create: - description: Create the password or the subkey if it does not already exist. Takes precedence over O(missing). - type: bool - default: false - overwrite: - description: Overwrite the password or the subkey if it does already exist. - type: bool - default: false - umask: - description: - - Sets the umask for the created V(.gpg) files. The first octed must be greater than 3 (user readable). - - Note pass' default value is V('077'). - type: string - env: - - name: PASSWORD_STORE_UMASK - version_added: 1.3.0 - returnall: - description: Return all the content of the password, not only the first line. - type: bool - default: false - subkey: - description: - - By default return a specific subkey of the password. When set to V(password), always returns the first line. - - With O(overwrite=true), it will create the subkey and return it. - type: str - default: password - userpass: - description: Specify a password to save, instead of a generated one. - type: str - length: - description: The length of the generated password. - type: integer - default: 16 - backup: - description: Used with O(overwrite=true). Backup the previous password or subkey in a subkey. - type: bool - default: false - nosymbols: - description: Use alphanumeric characters. - type: bool - default: false - missing: - description: - - List of preference about what to do if the password file is missing. - - If O(create=true), the value for this option is ignored and assumed to be V(create). - - If set to V(error), the lookup will error out if the passname does not exist. - - If set to V(create), the passname will be created with the provided length O(length) if it does not exist. - - If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist. - When using C(lookup) and not C(query), this will be translated to an empty string. - version_added: 3.1.0 - type: str - default: error - choices: - - error - - warn - - empty - - create - lock: - description: - - How to synchronize operations. - - The default of V(write) only synchronizes write operations. - - V(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel. - - V(none) does not do any synchronization. - ini: - - section: passwordstore_lookup - key: lock - type: str - default: write - choices: - - readwrite - - write - - none - version_added: 4.5.0 - locktimeout: - description: - - Lock timeout applied when O(lock) is not V(none). - - Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals V(15m). - - Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details. - ini: - - section: passwordstore_lookup - key: locktimeout - type: str - default: 15m - version_added: 4.5.0 - backend: - description: - - Specify which backend to use. - - Defaults to V(pass), passwordstore.org's original pass utility. - - V(gopass) support is incomplete. - ini: - - section: passwordstore_lookup - key: backend - vars: - - name: passwordstore_backend - type: str - default: pass - choices: - - pass - - gopass - version_added: 5.2.0 - timestamp: - description: Add the password generation information to the end of the file. - type: bool - default: true - version_added: 8.1.0 - preserve: - description: Include the old (edited) password inside the pass file. - type: bool - default: true - version_added: 8.1.0 - missing_subkey: - description: - - Preference about what to do if the password subkey is missing. - - If set to V(error), the lookup will error out if the subkey does not exist. - - If set to V(empty) or V(warn), will return a V(none) in case the subkey does not exist. - version_added: 8.6.0 - type: str - default: empty - choices: - - error - - 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 = """ + - The directory of the password store. + - If O(backend=pass), the default is V(~/.password-store) is used. + - If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), falling back to V(~/.local/share/gopass/stores/root) + if C(path) is not defined in the gopass config. + type: path + vars: + - name: passwordstore + env: + - name: PASSWORD_STORE_DIR + create: + description: Create the password or the subkey if it does not already exist. Takes precedence over O(missing). + type: bool + default: false + overwrite: + description: Overwrite the password or the subkey if it does already exist. + type: bool + default: false + umask: + description: + - Sets the umask for the created V(.gpg) files. The first octed must be greater than 3 (user readable). + - Note pass' default value is V('077'). + type: string + env: + - name: PASSWORD_STORE_UMASK + version_added: 1.3.0 + returnall: + description: Return all the content of the password, not only the first line. + type: bool + default: false + subkey: + description: + - By default return a specific subkey of the password. When set to V(password), always returns the first line. + - With O(overwrite=true), it will create the subkey and return it. + type: str + default: password + userpass: + description: Specify a password to save, instead of a generated one. + type: str + length: + description: The length of the generated password. + type: integer + default: 16 + backup: + description: Used with O(overwrite=true). Backup the previous password or subkey in a subkey. + type: bool + default: false + nosymbols: + description: Use alphanumeric characters. + type: bool + default: false + missing: + description: + - List of preference about what to do if the password file is missing. + - If O(create=true), the value for this option is ignored and assumed to be V(create). + - If set to V(error), the lookup will error out if the passname does not exist. + - If set to V(create), the passname will be created with the provided length O(length) if it does not exist. + - If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist. When using C(lookup) and + not C(query), this will be translated to an empty string. + version_added: 3.1.0 + type: str + default: error + choices: + - error + - warn + - empty + - create + lock: + description: + - How to synchronize operations. + - The default of V(write) only synchronizes write operations. + - V(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel. + - V(none) does not do any synchronization. + ini: + - section: passwordstore_lookup + key: lock + type: str + default: write + choices: + - readwrite + - write + - none + version_added: 4.5.0 + locktimeout: + description: + - Lock timeout applied when O(lock) is not V(none). + - Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals + V(15m). + - Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details. + ini: + - section: passwordstore_lookup + key: locktimeout + type: str + default: 15m + version_added: 4.5.0 + backend: + description: + - Specify which backend to use. + - Defaults to V(pass), passwordstore.org's original pass utility. + - V(gopass) support is incomplete. + ini: + - section: passwordstore_lookup + key: backend + vars: + - name: passwordstore_backend + type: str + default: pass + choices: + - pass + - gopass + version_added: 5.2.0 + timestamp: + description: Add the password generation information to the end of the file. + type: bool + default: true + version_added: 8.1.0 + preserve: + description: Include the old (edited) password inside the pass file. + type: bool + default: true + version_added: 8.1.0 + missing_subkey: + description: + - Preference about what to do if the password subkey is missing. + - If set to V(error), the lookup will error out if the subkey does not exist. + - If set to V(empty) or V(warn), will return a V(none) in case the subkey does not exist. + version_added: 8.6.0 + type: str + default: empty + choices: + - error + - 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 = r""" ansible.cfg: | [passwordstore_lookup] lock=readwrite locktimeout=45s missing_subkey=warn -tasks.yml: | +tasks.yml: |- --- # Debug is used for examples, BAD IDEA to show passwords on screen @@ -233,10 +234,10 @@ tasks.yml: | passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test', returnall=true)}}" """ -RETURN = """ +RETURN = r""" _raw: description: - - a password + - A password. type: list elements: str """ diff --git a/plugins/lookup/random_pet.py b/plugins/lookup/random_pet.py index 77f1c34a51..ff51fc8b31 100644 --- a/plugins/lookup/random_pet.py +++ b/plugins/lookup/random_pet.py @@ -8,38 +8,38 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' - name: random_pet - author: - - Abhijeet Kasurde (@Akasurde) - short_description: Generates random pet names - version_added: '3.1.0' - requirements: - - petname U(https://github.com/dustinkirkland/python-petname) +DOCUMENTATION = r""" +name: random_pet +author: + - Abhijeet Kasurde (@Akasurde) +short_description: Generates random pet names +version_added: '3.1.0' +requirements: + - 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: - - Generates random pet names that can be used as unique identifiers for the resources. - options: - words: - description: - - The number of words in the pet name. - default: 2 - type: int - length: - description: - - The maximal length of every component of the pet name. - - Values below 3 will be set to 3 by petname. - default: 6 - type: int - prefix: - description: A string to prefix with the name. - type: str - separator: - description: The character to separate words in the pet name. - default: "-" - type: str -''' + - The number of words in the pet name. + default: 2 + type: int + length: + description: + - The maximal length of every component of the pet name. + - Values below 3 will be set to 3 by petname. + default: 6 + type: int + prefix: + description: A string to prefix with the name. + type: str + separator: + description: The character to separate words in the pet name. + default: "-" + type: str +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Generate pet name ansible.builtin.debug: var: lookup('community.general.random_pet') @@ -59,14 +59,14 @@ EXAMPLES = r''' ansible.builtin.debug: var: lookup('community.general.random_pet', length=7) # Example result: 'natural-peacock' -''' +""" -RETURN = r''' - _raw: - description: A one-element list containing a random pet name - type: list - elements: str -''' +RETURN = r""" +_raw: + description: A one-element list containing a random pet name. + type: list + elements: str +""" try: import petname diff --git a/plugins/lookup/random_string.py b/plugins/lookup/random_string.py index 9b811dd8b3..bd72916d92 100644 --- a/plugins/lookup/random_string.py +++ b/plugins/lookup/random_string.py @@ -9,95 +9,94 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = r""" - name: random_string - author: - - Abhijeet Kasurde (@Akasurde) - short_description: Generates random string - version_added: '3.2.0' +name: random_string +author: + - Abhijeet Kasurde (@Akasurde) +short_description: Generates random string +version_added: '3.2.0' +description: + - Generates random string based upon the given constraints. + - Uses L(random.SystemRandom,https://docs.python.org/3/library/random.html#random.SystemRandom), so should be strong enough + for cryptographic purposes. +options: + length: + description: The length of the string. + default: 8 + type: int + upper: 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: - - Include uppercase letters in the string. - default: true - type: bool - lower: - description: - - Include lowercase letters in the string. - default: true - type: bool - numbers: - description: - - Include numbers in the string. - default: true - type: bool - special: - description: - - Include special characters in the string. - - Special characters are taken from Python standard library C(string). - See L(the documentation of string.punctuation,https://docs.python.org/3/library/string.html#string.punctuation) - for which characters will be used. - - The choice of special characters can be changed to setting O(override_special). - default: true - type: bool - min_numeric: - description: - - Minimum number of numeric characters in the string. - - If set, overrides O(numbers=false). - default: 0 - type: int - min_upper: - description: - - Minimum number of uppercase alphabets in the string. - - If set, overrides O(upper=false). - default: 0 - type: int - min_lower: - description: - - Minimum number of lowercase alphabets in the string. - - If set, overrides O(lower=false). - default: 0 - type: int - min_special: - description: - - Minimum number of special character in the string. - default: 0 - type: int - override_special: - description: - - Override a list of special characters to use in the string. - - If set O(min_special) should be set to a non-default value. - type: str - override_all: - description: - - Override all values of O(numbers), O(upper), O(lower), and O(special) with - the given list of characters. - type: str - ignore_similar_chars: - description: - - Ignore similar characters, such as V(l) and V(1), or V(O) and V(0). - - These characters can be configured in O(similar_chars). - default: false - type: bool - version_added: 7.5.0 - 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 + - Include uppercase letters in the string. + default: true + type: bool + lower: + description: + - Include lowercase letters in the string. + default: true + type: bool + numbers: + description: + - Include numbers in the string. + default: true + type: bool + special: + description: + - Include special characters in the string. + - Special characters are taken from Python standard library C(string). + See L(the documentation of string.punctuation,https://docs.python.org/3/library/string.html#string.punctuation) + for which characters will be used. + - The choice of special characters can be changed to setting O(override_special). + default: true + type: bool + min_numeric: + description: + - Minimum number of numeric characters in the string. + - If set, overrides O(numbers=false). + default: 0 + type: int + min_upper: + description: + - Minimum number of uppercase alphabets in the string. + - If set, overrides O(upper=false). + default: 0 + type: int + min_lower: + description: + - Minimum number of lowercase alphabets in the string. + - If set, overrides O(lower=false). + default: 0 + type: int + min_special: + description: + - Minimum number of special character in the string. + default: 0 + type: int + override_special: + description: + - Override a list of special characters to use in the string. + - If set O(min_special) should be set to a non-default value. + type: str + override_all: + description: + - Override all values of O(numbers), O(upper), O(lower), and O(special) with the given list of characters. + type: str + ignore_similar_chars: + description: + - Ignore similar characters, such as V(l) and V(1), or V(O) and V(0). + - These characters can be configured in O(similar_chars). + default: false + type: bool + version_added: 7.5.0 + 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""" @@ -142,10 +141,10 @@ EXAMPLES = r""" """ RETURN = r""" - _raw: - description: A one-element list containing a random string - type: list - elements: str +_raw: + description: A one-element list containing a random string. + type: list + elements: str """ import base64 diff --git a/plugins/lookup/random_words.py b/plugins/lookup/random_words.py index a4aa1b3178..247871dba0 100644 --- a/plugins/lookup/random_words.py +++ b/plugins/lookup/random_words.py @@ -10,44 +10,43 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = r""" - name: random_words - author: - - Thomas Sjögren (@konstruktoid) - short_description: Return a number of random words - version_added: "4.0.0" - requirements: - - xkcdpass U(https://github.com/redacted/XKCD-password-generator) +name: random_words +author: + - Thomas Sjögren (@konstruktoid) +short_description: Return a number of random words +version_added: "4.0.0" +requirements: + - xkcdpass U(https://github.com/redacted/XKCD-password-generator) +description: + - Returns a number of random words. The output can for example be used for passwords. + - See U(https://xkcd.com/936/) for background. +options: + numwords: 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: - - The number of words. - default: 6 - type: int - min_length: - description: - - Minimum length of words to make password. - default: 5 - type: int - max_length: - description: - - Maximum length of words to make password. - default: 9 - type: int - delimiter: - description: - - The delimiter character between words. - default: " " - 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 + - The number of words. + default: 6 + type: int + min_length: + description: + - Minimum length of words to make password. + default: 5 + type: int + max_length: + description: + - Maximum length of words to make password. + default: 9 + type: int + delimiter: + description: + - The delimiter character between words. + default: " " + 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""" @@ -74,10 +73,10 @@ EXAMPLES = r""" """ RETURN = r""" - _raw: - description: A single-element list containing random words. - type: list - elements: str +_raw: + description: A single-element list containing random words. + type: list + elements: str """ from ansible.errors import AnsibleLookupError diff --git a/plugins/lookup/redis.py b/plugins/lookup/redis.py index 5c669a7f23..3c8ff07a23 100644 --- a/plugins/lookup/redis.py +++ b/plugins/lookup/redis.py @@ -6,50 +6,50 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: redis - author: - - Jan-Piet Mens (@jpmens) - - Ansible Core Team - short_description: fetch data from Redis - description: - - This lookup returns a list of results from a Redis DB corresponding to a list of items given to it - requirements: - - redis (python library https://github.com/andymccurdy/redis-py/) - options: - _terms: - description: list of keys to query - type: list - elements: string - host: - description: location of Redis host - type: string - default: '127.0.0.1' - env: - - name: ANSIBLE_REDIS_HOST - ini: - - section: lookup_redis - key: host - port: - description: port on which Redis is listening on - default: 6379 - type: int - env: - - name: ANSIBLE_REDIS_PORT - ini: - - section: lookup_redis - key: port - socket: - description: path to socket on which to query Redis, this option overrides host and port options when set. - type: path - env: - - name: ANSIBLE_REDIS_SOCKET - ini: - - section: lookup_redis - key: socket -''' +DOCUMENTATION = r""" +name: redis +author: + - Jan-Piet Mens (@jpmens) + - Ansible Core Team +short_description: fetch data from Redis +description: + - This lookup returns a list of results from a Redis DB corresponding to a list of items given to it. +requirements: + - redis (python library https://github.com/andymccurdy/redis-py/) +options: + _terms: + description: List of keys to query. + type: list + elements: string + host: + description: Location of Redis host. + type: string + default: '127.0.0.1' + env: + - name: ANSIBLE_REDIS_HOST + ini: + - section: lookup_redis + key: host + port: + description: Port on which Redis is listening on. + default: 6379 + type: int + env: + - name: ANSIBLE_REDIS_PORT + ini: + - section: lookup_redis + key: port + socket: + description: Path to socket on which to query Redis, this option overrides host and port options when set. + type: path + env: + - name: ANSIBLE_REDIS_SOCKET + ini: + - section: lookup_redis + key: socket +""" -EXAMPLES = """ +EXAMPLES = r""" - name: query redis for somekey (default or configured settings used) ansible.builtin.debug: msg: "{{ lookup('community.general.redis', 'somekey') }}" @@ -66,12 +66,11 @@ EXAMPLES = """ - name: use list directly with a socket ansible.builtin.debug: msg: "{{ lookup('community.general.redis', 'key1', 'key2', socket='/var/tmp/redis.sock') }}" - """ -RETURN = """ +RETURN = r""" _raw: - description: value(s) stored in Redis + description: Value(s) stored in Redis. type: list elements: str """ diff --git a/plugins/lookup/revbitspss.py b/plugins/lookup/revbitspss.py index 89c19cf23c..c40140671d 100644 --- a/plugins/lookup/revbitspss.py +++ b/plugins/lookup/revbitspss.py @@ -12,54 +12,55 @@ author: RevBits (@RevBits) short_description: Get secrets from RevBits PAM server version_added: 4.1.0 description: - - Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM - Server using API key authentication with the REST API. + - Uses the revbits_ansible Python SDK to get Secrets from RevBits PAM Server using API key authentication with the REST + API. requirements: - - revbits_ansible - U(https://pypi.org/project/revbits_ansible/) + - revbits_ansible - U(https://pypi.org/project/revbits_ansible/) options: - _terms: - description: - - This will be an array of keys for secrets which you want to fetch from RevBits PAM. - required: true - type: list - elements: string - base_url: - description: - - This will be the base URL of the server, for example V(https://server-url-here). - required: true - type: string - api_key: - description: - - This will be the API key for authentication. You can get it from the RevBits PAM secret manager module. - required: true - type: string + _terms: + description: + - This will be an array of keys for secrets which you want to fetch from RevBits PAM. + required: true + type: list + elements: string + base_url: + description: + - This will be the base URL of the server, for example V(https://server-url-here). + required: true + type: string + api_key: + description: + - This will be the API key for authentication. You can get it from the RevBits PAM secret manager module. + required: true + type: string """ RETURN = r""" _list: - description: - - 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. - type: list - elements: dict + description: + - 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. + type: list + elements: dict """ EXAMPLES = r""" +--- - hosts: localhost vars: - secret: >- - {{ - lookup( - 'community.general.revbitspss', - 'UUIDPAM', 'DB_PASS', - base_url='https://server-url-here', - api_key='API_KEY_GOES_HERE' - ) - }} + secret: >- + {{ + lookup( + 'community.general.revbitspss', + 'UUIDPAM', 'DB_PASS', + base_url='https://server-url-here', + api_key='API_KEY_GOES_HERE' + ) + }} tasks: - - ansible.builtin.debug: - msg: > - UUIDPAM is {{ (secret['UUIDPAM']) }} and DB_PASS is {{ (secret['DB_PASS']) }} + - ansible.builtin.debug: + msg: >- + UUIDPAM is {{ (secret['UUIDPAM']) }} and DB_PASS is {{ (secret['DB_PASS']) }} """ from ansible.plugins.lookup import LookupBase diff --git a/plugins/lookup/shelvefile.py b/plugins/lookup/shelvefile.py index 4d965372fb..4921e050a0 100644 --- a/plugins/lookup/shelvefile.py +++ b/plugins/lookup/shelvefile.py @@ -6,34 +6,35 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: shelvefile - author: Alejandro Guirao (!UNKNOWN) - short_description: read keys from Python shelve file - description: - - Read keys from Python shelve file. - options: - _terms: - description: Sets of key value pairs of parameters. - type: list - elements: str - key: - description: Key to query. - type: str - required: true - file: - description: Path to shelve file. - type: path - required: true -''' +DOCUMENTATION = r""" +name: shelvefile +author: Alejandro Guirao (!UNKNOWN) +short_description: read keys from Python shelve file +description: + - Read keys from Python shelve file. +options: + _terms: + description: Sets of key value pairs of parameters. + type: list + elements: str + key: + description: Key to query. + type: str + required: true + file: + description: Path to shelve file. + type: path + required: true +""" -EXAMPLES = """ +EXAMPLES = r""" +--- - name: Retrieve a string value corresponding to a key inside a Python shelve file ansible.builtin.debug: msg: "{{ lookup('community.general.shelvefile', 'file=path_to_some_shelve_file.db key=key_to_retrieve') }}" """ -RETURN = """ +RETURN = r""" _list: description: Value(s) of key(s) in shelve file(s). type: list diff --git a/plugins/lookup/tss.py b/plugins/lookup/tss.py index ffae6bb824..6a97d4b29c 100644 --- a/plugins/lookup/tss.py +++ b/plugins/lookup/tss.py @@ -12,200 +12,196 @@ author: Adam Migus (@amigus) short_description: Get secrets from Thycotic Secret Server version_added: 1.0.0 description: - - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret - Server using token authentication with O(username) and O(password) on - the REST API at O(base_url). - - When using self-signed certificates the environment variable - E(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates - (in C(.pem) format). - - For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt'). + - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret Server using token authentication with O(username) + and O(password) on the REST API at O(base_url). + - When using self-signed certificates the environment variable E(REQUESTS_CA_BUNDLE) can be set to a file containing the + trusted certificates (in C(.pem) format). + - For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt'). requirements: - - python-tss-sdk - https://pypi.org/project/python-tss-sdk/ + - python-tss-sdk - https://pypi.org/project/python-tss-sdk/ options: - _terms: - description: The integer ID of the secret. - required: true - type: list - elements: int - secret_path: - description: Indicate a full path of secret including folder and secret name when the secret ID is set to 0. - required: false - type: str - version_added: 7.2.0 - fetch_secret_ids_from_folder: - description: - - Boolean flag which indicates whether secret ids are in a folder is fetched by folder ID or not. - - V(true) then the terms will be considered as a folder IDs. Otherwise (default), they are considered as secret IDs. - required: false - type: bool - version_added: 7.1.0 - fetch_attachments: - description: - - 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. - required: false - type: bool - version_added: 7.0.0 - file_download_path: - description: Indicate the file attachment download location. - required: false - type: path - version_added: 7.0.0 - base_url: - description: The base URL of the server, for example V(https://localhost/SecretServer). - type: string - env: - - name: TSS_BASE_URL - ini: - - section: tss_lookup - key: base_url - required: true - username: - description: The username with which to request the OAuth2 Access Grant. - type: string - env: - - name: TSS_USERNAME - ini: - - section: tss_lookup - key: username - password: - description: - - The password associated with the supplied username. - - Required when O(token) is not provided. - type: string - env: - - name: TSS_PASSWORD - ini: - - section: tss_lookup - key: password - domain: - default: "" - description: - - The domain with which to request the OAuth2 Access Grant. - - Optional when O(token) is not provided. - - Requires C(python-tss-sdk) version 1.0.0 or greater. - type: string - env: - - name: TSS_DOMAIN - ini: - - section: tss_lookup - key: domain - required: false - version_added: 3.6.0 - token: - description: - - Existing token for Thycotic authorizer. - - If provided, O(username) and O(password) are not needed. - - Requires C(python-tss-sdk) version 1.0.0 or greater. - type: string - env: - - name: TSS_TOKEN - ini: - - section: tss_lookup - key: token - version_added: 3.7.0 - api_path_uri: - default: /api/v1 - description: The path to append to the base URL to form a valid REST - API request. - type: string - env: - - name: TSS_API_PATH_URI - required: false - token_path_uri: - default: /oauth2/token - description: The path to append to the base URL to form a valid OAuth2 - Access Grant request. - type: string - env: - - name: TSS_TOKEN_PATH_URI - required: false + _terms: + description: The integer ID of the secret. + required: true + type: list + elements: int + secret_path: + description: Indicate a full path of secret including folder and secret name when the secret ID is set to 0. + required: false + type: str + version_added: 7.2.0 + fetch_secret_ids_from_folder: + description: + - Boolean flag which indicates whether secret IDs are in a folder is fetched by folder ID or not. + - V(true) then the terms will be considered as a folder IDs. Otherwise (default), they are considered as secret IDs. + required: false + type: bool + version_added: 7.1.0 + fetch_attachments: + description: + - 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. + required: false + type: bool + version_added: 7.0.0 + file_download_path: + description: Indicate the file attachment download location. + required: false + type: path + version_added: 7.0.0 + base_url: + description: The base URL of the server, for example V(https://localhost/SecretServer). + type: string + env: + - name: TSS_BASE_URL + ini: + - section: tss_lookup + key: base_url + required: true + username: + description: The username with which to request the OAuth2 Access Grant. + type: string + env: + - name: TSS_USERNAME + ini: + - section: tss_lookup + key: username + password: + description: + - The password associated with the supplied username. + - Required when O(token) is not provided. + type: string + env: + - name: TSS_PASSWORD + ini: + - section: tss_lookup + key: password + domain: + default: "" + description: + - The domain with which to request the OAuth2 Access Grant. + - Optional when O(token) is not provided. + - Requires C(python-tss-sdk) version 1.0.0 or greater. + type: string + env: + - name: TSS_DOMAIN + ini: + - section: tss_lookup + key: domain + required: false + version_added: 3.6.0 + token: + description: + - Existing token for Thycotic authorizer. + - If provided, O(username) and O(password) are not needed. + - Requires C(python-tss-sdk) version 1.0.0 or greater. + type: string + env: + - name: TSS_TOKEN + ini: + - section: tss_lookup + key: token + version_added: 3.7.0 + api_path_uri: + default: /api/v1 + description: The path to append to the base URL to form a valid REST API request. + type: string + env: + - name: TSS_API_PATH_URI + required: false + token_path_uri: + default: /oauth2/token + description: The path to append to the base URL to form a valid OAuth2 Access Grant request. + type: string + env: + - name: TSS_TOKEN_PATH_URI + required: false """ RETURN = r""" _list: - description: - - The JSON responses to C(GET /secrets/{id}). - - See U(https://updates.thycotic.net/secretserver/restapiguide/TokenAuth/#operation--secrets--id--get). - type: list - elements: dict + description: + - The JSON responses to C(GET /secrets/{id}). + - See U(https://updates.thycotic.net/secretserver/restapiguide/TokenAuth/#operation--secrets--id--get). + type: list + elements: dict """ EXAMPLES = r""" - hosts: localhost vars: - secret: >- - {{ - lookup( - 'community.general.tss', - 102, - base_url='https://secretserver.domain.com/SecretServer/', - username='user.name', - password='password' - ) - }} + secret: >- + {{ + lookup( + 'community.general.tss', + 102, + base_url='https://secretserver.domain.com/SecretServer/', + username='user.name', + password='password' + ) + }} tasks: - - ansible.builtin.debug: - msg: > - the password is {{ - (secret['items'] - | items2dict(key_name='slug', - value_name='itemValue'))['password'] - }} + - ansible.builtin.debug: + msg: > + the password is {{ + (secret['items'] + | items2dict(key_name='slug', + value_name='itemValue'))['password'] + }} - hosts: localhost vars: - secret: >- - {{ - lookup( - 'community.general.tss', - 102, - base_url='https://secretserver.domain.com/SecretServer/', - username='user.name', - password='password', - domain='domain' - ) - }} + secret: >- + {{ + lookup( + 'community.general.tss', + 102, + base_url='https://secretserver.domain.com/SecretServer/', + username='user.name', + password='password', + domain='domain' + ) + }} tasks: - - ansible.builtin.debug: - msg: > - the password is {{ - (secret['items'] - | items2dict(key_name='slug', - value_name='itemValue'))['password'] - }} + - ansible.builtin.debug: + msg: > + the password is {{ + (secret['items'] + | items2dict(key_name='slug', + value_name='itemValue'))['password'] + }} - hosts: localhost vars: - secret_password: >- - {{ - ((lookup( - 'community.general.tss', - 102, - base_url='https://secretserver.domain.com/SecretServer/', - token='thycotic_access_token', - ) | from_json).get('items') | items2dict(key_name='slug', value_name='itemValue'))['password'] - }} + secret_password: >- + {{ + ((lookup( + 'community.general.tss', + 102, + base_url='https://secretserver.domain.com/SecretServer/', + token='thycotic_access_token', + ) | from_json).get('items') | items2dict(key_name='slug', value_name='itemValue'))['password'] + }} tasks: - - ansible.builtin.debug: - msg: the password is {{ secret_password }} + - ansible.builtin.debug: + msg: the password is {{ secret_password }} # 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 # and file content will display in debug message. - hosts: localhost vars: - secret: >- - {{ - lookup( - 'community.general.tss', - 102, - fetch_attachments=True, - file_download_path='/home/certs', - base_url='https://secretserver.domain.com/SecretServer/', - token='thycotic_access_token' - ) - }} + secret: >- + {{ + lookup( + 'community.general.tss', + 102, + fetch_attachments=True, + file_download_path='/home/certs', + base_url='https://secretserver.domain.com/SecretServer/', + token='thycotic_access_token' + ) + }} tasks: - ansible.builtin.debug: 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 - hosts: localhost vars: - secret: >- - {{ - lookup( - 'community.general.tss', - 102, - fetch_secret_ids_from_folder=true, - base_url='https://secretserver.domain.com/SecretServer/', - token='thycotic_access_token' - ) - }} + secret: >- + {{ + lookup( + 'community.general.tss', + 102, + fetch_secret_ids_from_folder=true, + base_url='https://secretserver.domain.com/SecretServer/', + token='thycotic_access_token' + ) + }} tasks: - ansible.builtin.debug: msg: > @@ -238,25 +234,25 @@ EXAMPLES = r""" # If secret ID is 0 and secret_path has value then secret is fetched by secret path - hosts: localhost vars: - secret: >- - {{ - lookup( - 'community.general.tss', - 0, - secret_path='\folderName\secretName' - base_url='https://secretserver.domain.com/SecretServer/', - username='user.name', - password='password' - ) - }} + secret: >- + {{ + lookup( + 'community.general.tss', + 0, + secret_path='\folderName\secretName' + base_url='https://secretserver.domain.com/SecretServer/', + username='user.name', + password='password' + ) + }} tasks: - - ansible.builtin.debug: - msg: > - the password is {{ - (secret['items'] - | items2dict(key_name='slug', - value_name='itemValue'))['password'] - }} + - ansible.builtin.debug: + msg: >- + the password is {{ + (secret['items'] + | items2dict(key_name='slug', + value_name='itemValue'))['password'] + }} """ import abc