ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-23 05:10:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Start using semantic markup (#6627)

Browse source 
* Start using semantic markup.

* Forgot some places.

* Fix typo.

* Use 'ignore:' prefix until https://github.com/ansible-community/antsibull-docs/pull/155 is out.

* Break too long line.
This commit is contained in:
Felix Fontein 2023-06-10 09:28:40 +02:00 • committed by GitHub
commit 011b2f8bdc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
71 changed files with 342 additions and 345 deletions
Download patch file Download diff file Expand all files Collapse all files

2
plugins/lookup/bitwarden.py
View file

@ -25,7 +25,7 @@ DOCUMENTATION = """
type: list
elements: str
search:
description: Field to retrieve, for example C(name) or C(id).
description: Field to retrieve, for example V(name) or V(id).
type: str
default: name
version_added: 5.7.0

18
plugins/lookup/collection_version.py
View file

@ -13,22 +13,22 @@ 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 C(none) for non-existing collections and C(*) for collections without a
- 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 I(result_not_found) and I(result_no_version).
by providing other values with O(result_not_found) and O(result_no_version).
options:
_terms:
description:
- The collections to look for.
- For example C(community.general).
- For example V(community.general).
type: list
elements: str
required: true
result_not_found:
description:
- The value to return when the collection could not be found.
- By default, C(none) is returned.
- By default, V(none) is returned.
type: string
default: ~
result_no_version:
@ -36,7 +36,7 @@ options:
- 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).
- By default, C(*) is returned.
- By default, V(*) is returned.
type: string
default: '*'
"""
@ -51,11 +51,11 @@ 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 I(result_not_found).
By default, this is C(none).
- 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
I(result_no_version). By default, this is C(*). This can happen for collections installed
from git which do not have a version number in C(galaxy.yml).
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
"""

13
plugins/lookup/consul_kv.py
View file

@ -38,23 +38,20 @@ DOCUMENTATION = '''
default: localhost
description:
- The target to connect to, must be a resolvable address.
Will be determined from C(ANSIBLE_CONSUL_URL) if that is set.
- "C(ANSIBLE_CONSUL_URL) should look like this: C(https://my.consul.server:8500)"
env:
- name: ANSIBLE_CONSUL_URL
- 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 C(ANSIBLE_CONSUL_URL) this value will be used from there.
- If you use E(ANSIBLE_CONSUL_URL) this value will be used from there.
default: 8500
scheme:
default: http
description:
- Whether to use http or https.
- If you use C(ANSIBLE_CONSUL_URL) this value will be used from there.
- If you use E(ANSIBLE_CONSUL_URL) this value will be used from there.
validate_certs:
default: true
description: Whether to verify the ssl connection or not.
@ -71,7 +68,9 @@ DOCUMENTATION = '''
- section: lookup_consul
key: client_cert
url:
description: "The target to connect to, should look like this: C(https://my.consul.server:8500)."
description:
- The target to connect to.
- "Should look like this: V(https://my.consul.server:8500)."
type: str
version_added: 1.0.0
env:

18
plugins/lookup/dig.py
View file

@ -21,7 +21,7 @@ DOCUMENTATION = '''
- 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 I(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup),
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.
@ -34,8 +34,8 @@ DOCUMENTATION = '''
qtype:
description:
- Record type to query.
- C(DLV) has been removed in community.general 6.0.0.
- C(CAA) has been added in community.general 6.3.0.
- 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]
@ -51,17 +51,17 @@ DOCUMENTATION = '''
fail_on_error:
description:
- Abort execution on lookup errors.
- The default for this option will likely change to C(true) in the future.
The current default, C(false), is used for backwards compatibility, and will result in empty strings
or the string C(NXDOMAIN) in the result in case of errors.
- The default for this option will likely change to V(true) in the future.
The current default, V(false), is used for backwards compatibility, and will result in empty strings
or the string V(NXDOMAIN) in the result in case of errors.
default: false
type: bool
version_added: 5.4.0
real_empty:
description:
- Return empty result without empty strings, and return empty list instead of C(NXDOMAIN).
- The default for this option will likely change to C(true) in the future.
- This option will be forced to C(true) if multiple domains to be queried are specified.
- 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

4
plugins/lookup/dnstxt.py
View file

@ -22,8 +22,8 @@ DOCUMENTATION = '''
elements: string
real_empty:
description:
- Return empty result without empty strings, and return empty list instead of C(NXDOMAIN).
- The default for this option will likely change to C(true) in the future.
- 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

10
plugins/lookup/dsv.py
View file

@ -13,15 +13,15 @@ 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 I(tenant) using a I(client_id) and I(client_secret).
DSV O(tenant) using a O(client_id) and O(client_secret).
requirements:
- python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/
options:
_terms:
description: The path to the secret, e.g. C(/staging/servers/web1).
description: The path to the secret, for example V(/staging/servers/web1).
required: true
tenant:
description: The first format parameter in the default I(url_template).
description: The first format parameter in the default O(url_template).
env:
- name: DSV_TENANT
ini:
@ -31,7 +31,7 @@ options:
tld:
default: com
description: The top-level domain of the tenant; the second format
parameter in the default I(url_template).
parameter in the default O(url_template).
env:
- name: DSV_TLD
ini:
@ -47,7 +47,7 @@ options:
key: client_id
required: true
client_secret:
description: The client secret associated with the specific I(client_id).
description: The client secret associated with the specific O(client_id).
env:
- name: DSV_CLIENT_SECRET
ini:

18
plugins/lookup/etcd3.py
View file

@ -32,10 +32,10 @@ DOCUMENTATION = '''
default: false
endpoints:
description:
- Counterpart of C(ETCDCTL_ENDPOINTS) environment variable.
Specify the etcd3 connection with and URL form eg. C(https://hostname:2379) or C(<host>:<port>) form.
- The C(host) part is overwritten by I(host) option, if defined.
- The C(port) part is overwritten by I(port) option, if defined.
- Counterpart of E(ETCDCTL_ENDPOINTS) environment variable.
Specify the etcd3 connection with and URL form, for example V(https://hostname:2379), or V(<host>:<port>) form.
- The V(host) part is overwritten by O(host) option, if defined.
- The V(port) part is overwritten by O(port) option, if defined.
env:
- name: ETCDCTL_ENDPOINTS
default: '127.0.0.1:2379'
@ -43,12 +43,12 @@ DOCUMENTATION = '''
host:
description:
- etcd3 listening client host.
- Takes precedence over I(endpoints).
- Takes precedence over O(endpoints).
type: str
port:
description:
- etcd3 listening client port.
- Takes precedence over I(endpoints).
- Takes precedence over O(endpoints).
type: int
ca_cert:
description:
@ -89,9 +89,9 @@ DOCUMENTATION = '''
type: str
notes:
- I(host) and I(port) options take precedence over (endpoints) option.
- The recommended way to connect to etcd3 server is using C(ETCDCTL_ENDPOINT)
environment variable and keep I(endpoints), I(host), and I(port) unused.
- 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
- ref: ansible_collections.community.general.etcd_lookup

2
plugins/lookup/filetree.py
View file

@ -65,7 +65,7 @@ RETURN = r"""
src:
description:
- Full path to file.
- Not returned when I(item.state) is set to C(directory).
- Not returned when RV(_raw[].state) is set to V(directory).
type: path
root:
description: Allows filtering by original location.

2
plugins/lookup/lmdb_kv.py
View file

@ -15,7 +15,7 @@ DOCUMENTATION = '''
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 https://lmdb.readthedocs.io/en/release/)
- lmdb (Python library U(https://lmdb.readthedocs.io/en/release/))
options:
_terms:
description: List of keys to query.

8
plugins/lookup/merge_variables.py
View file

@ -19,7 +19,7 @@ DOCUMENTATION = """
options:
_terms:
description:
- Depending on the value of I(pattern_type), this is a list of prefixes, suffixes, or regular expressions
- 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
@ -45,11 +45,11 @@ DOCUMENTATION = """
override:
description:
- Return an error, print a warning or ignore it when a key will be overwritten.
- The default behavior C(error) makes the plugin fail when a key would be overwritten.
- When C(warn) and C(ignore) are used, note that it is important to know that the variables
- 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 I(override=error) whenever possible.
better use O(override=error) whenever possible.
type: str
default: 'error'
choices:

6
plugins/lookup/onepassword.py
View file

@ -18,7 +18,7 @@ DOCUMENTATION = '''
- C(op) 1Password command line utility. See U(https://support.1password.com/command-line/)
short_description: fetch field values from 1Password
description:
- C(onepassword) wraps the C(op) command line utility to fetch specific field values from 1Password.
- P(community.general.onepassword#lookup) wraps the C(op) command line utility to fetch specific field values from 1Password.
options:
_terms:
description: identifier(s) (UUID, name, or subdomain; case-insensitive) of item(s) to retrieve.
@ -47,8 +47,8 @@ DOCUMENTATION = '''
notes:
- This lookup will use an existing 1Password session if one exists. If not, and you have already
performed an initial sign in (meaning C(~/.op/config), C(~/.config/op/config) or C(~/.config/.op/config) exists), then only the
C(master_password) is required. You may optionally specify C(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op).
- This lookup can perform an initial login by providing C(subdomain), C(username), C(secret_key), and C(master_password).
C(master_password) is required. You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op).
- This lookup can perform an initial login by providing O(subdomain), O(username), O(secret_key), and O(master_password).
- Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal credentials
needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or greater in strength
to the 1Password master password.

8
plugins/lookup/onepassword_raw.py
View file

@ -18,7 +18,7 @@ DOCUMENTATION = '''
- C(op) 1Password command line utility. See U(https://support.1password.com/command-line/)
short_description: fetch an entire item from 1Password
description:
- C(onepassword_raw) wraps C(op) command line utility to fetch an entire item from 1Password
- P(community.general.onepassword_raw#lookup) wraps C(op) command line utility to fetch an entire item from 1Password.
options:
_terms:
description: identifier(s) (UUID, name, or domain; case-insensitive) of item(s) to retrieve.
@ -43,9 +43,9 @@ DOCUMENTATION = '''
description: Vault containing the item to retrieve (case-insensitive). If absent will search all vaults.
notes:
- This lookup will use an existing 1Password session if one exists. If not, and you have already
performed an initial sign in (meaning C(~/.op/config exists)), then only the C(master_password) is required.
You may optionally specify C(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op).
- This lookup can perform an initial login by providing C(subdomain), C(username), C(secret_key), and C(master_password).
performed an initial sign in (meaning C(~/.op/config exists)), then only the O(master_password) is required.
You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op).
- This lookup can perform an initial login by providing O(subdomain), O(username), O(secret_key), and O(master_password).
- Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal credentials
needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or greater in strength
to the 1Password master password.

38
plugins/lookup/passwordstore.py
View file

@ -16,7 +16,7 @@ DOCUMENTATION = '''
- Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility.
It also retrieves 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 I(lock=readwrite) instead.
C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using O(lock=readwrite) instead.
options:
_terms:
description: query key.
@ -24,16 +24,16 @@ DOCUMENTATION = '''
directory:
description:
- The directory of the password store.
- If I(backend=pass), the default is C(~/.password-store) is used.
- If I(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml),
falling back to C(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config.
- 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 if it does not already exist. Takes precedence over C(missing).
description: Create the password if it does not already exist. Takes precedence over O(missing).
type: bool
default: false
overwrite:
@ -43,7 +43,7 @@ DOCUMENTATION = '''
umask:
description:
- Sets the umask for the created .gpg files. The first octed must be greater than 3 (user readable).
- Note pass' default value is C('077').
- Note pass' default value is V('077').
env:
- name: PASSWORD_STORE_UMASK
version_added: 1.3.0
@ -52,7 +52,7 @@ DOCUMENTATION = '''
type: bool
default: false
subkey:
description: Return a specific subkey of the password. When set to C(password), always returns the first line.
description: Return a specific subkey of the password. When set to V(password), always returns the first line.
type: str
default: password
userpass:
@ -63,7 +63,7 @@ DOCUMENTATION = '''
type: integer
default: 16
backup:
description: Used with C(overwrite=true). Backup the previous password in a subkey.
description: Used with O(overwrite=true). Backup the previous password in a subkey.
type: bool
default: false
nosymbols:
@ -73,10 +73,10 @@ DOCUMENTATION = '''
missing:
description:
- List of preference about what to do if the password file is missing.
- If I(create=true), the value for this option is ignored and assumed to be C(create).
- If set to C(error), the lookup will error out if the passname does not exist.
- If set to C(create), the passname will be created with the provided length I(length) if it does not exist.
- If set to C(empty) or C(warn), will return a C(none) in case the passname does not exist.
- 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
@ -89,9 +89,9 @@ DOCUMENTATION = '''
lock:
description:
- How to synchronize operations.
- The default of C(write) only synchronizes write operations.
- C(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel.
- C(none) does not do any synchronization.
- 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
@ -104,8 +104,8 @@ DOCUMENTATION = '''
version_added: 4.5.0
locktimeout:
description:
- Lock timeout applied when I(lock) is not C(none).
- Time with a unit suffix, C(s), C(m), C(h) for seconds, minutes, and hours, respectively. For example, C(900s) equals C(15m).
- 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
@ -116,8 +116,8 @@ DOCUMENTATION = '''
backend:
description:
- Specify which backend to use.
- Defaults to C(pass), passwordstore.org's original pass utility.
- C(gopass) support is incomplete.
- Defaults to V(pass), passwordstore.org's original pass utility.
- V(gopass) support is incomplete.
ini:
- section: passwordstore_lookup
key: backend

12
plugins/lookup/random_string.py
View file

@ -42,25 +42,25 @@ DOCUMENTATION = r"""
- 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 I(override_special).
- 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 I(numbers=false).
- If set, overrides O(numbers=false).
default: 0
type: int
min_upper:
description:
- Minimum number of uppercase alphabets in the string.
- If set, overrides I(upper=false).
- If set, overrides O(upper=false).
default: 0
type: int
min_lower:
description:
- Minimum number of lowercase alphabets in the string.
- If set, overrides I(lower=false).
- If set, overrides O(lower=false).
default: 0
type: int
min_special:
@ -71,11 +71,11 @@ DOCUMENTATION = r"""
override_special:
description:
- Overide a list of special characters to use in the string.
- If set I(min_special) should be set to a non-default value.
- If set O(min_special) should be set to a non-default value.
type: str
override_all:
description:
- Override all values of I(numbers), I(upper), I(lower), and I(special) with
- Override all values of O(numbers), O(upper), O(lower), and O(special) with
the given list of characters.
type: str
base64:

2
plugins/lookup/revbitspss.py
View file

@ -25,7 +25,7 @@ options:
elements: string
base_url:
description:
- This will be the base URL of the server, for example C(https://server-url-here).
- This will be the base URL of the server, for example V(https://server-url-here).
required: true
type: string
api_key:

14
plugins/lookup/tss.py
View file

@ -13,8 +13,8 @@ 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 I(username) and I(password) on
the REST API at I(base_url).
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
C(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates
(in C(.pem) format).
@ -36,7 +36,7 @@ options:
fetch_attachments:
description:
- Boolean flag which indicates whether attached files will get downloaded or not.
- The download will only happen if I(file_download_path) has been provided.
- The download will only happen if O(file_download_path) has been provided.
required: false
type: bool
version_added: 7.0.0
@ -46,7 +46,7 @@ options:
type: path
version_added: 7.0.0
base_url:
description: The base URL of the server, e.g. C(https://localhost/SecretServer).
description: The base URL of the server, for example V(https://localhost/SecretServer).
env:
- name: TSS_BASE_URL
ini:
@ -63,7 +63,7 @@ options:
password:
description:
- The password associated with the supplied username.
- Required when I(token) is not provided.
- Required when O(token) is not provided.
env:
- name: TSS_PASSWORD
ini:
@ -73,7 +73,7 @@ options:
default: ""
description:
- The domain with which to request the OAuth2 Access Grant.
- Optional when I(token) is not provided.
- Optional when O(token) is not provided.
- Requires C(python-tss-sdk) version 1.0.0 or greater.
env:
- name: TSS_DOMAIN
@ -85,7 +85,7 @@ options:
token:
description:
- Existing token for Thycotic authorizer.
- If provided, I(username) and I(password) are not needed.
- If provided, O(username) and O(password) are not needed.
- Requires C(python-tss-sdk) version 1.0.0 or greater.
env:
- name: TSS_TOKEN