From daed4dcc94ad729571d77c1ff4984b3fe1c35096 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 21 Jul 2024 21:03:41 +0200 Subject: [PATCH] Type options of lookup plugins (#8626) Type options of lookup plugins. --- changelogs/fragments/8626-lookup-types.yml | 2 ++ plugins/lookup/chef_databag.py | 2 ++ plugins/lookup/consul_kv.py | 14 +++++++++++--- plugins/lookup/cyberarkpassword.py | 4 ++++ plugins/lookup/dsv.py | 5 +++++ plugins/lookup/etcd.py | 2 ++ plugins/lookup/filetree.py | 4 +++- plugins/lookup/hiera.py | 2 ++ plugins/lookup/onepassword.py | 2 ++ plugins/lookup/onepassword_doc.py | 2 ++ plugins/lookup/onepassword_raw.py | 2 ++ plugins/lookup/passwordstore.py | 3 ++- plugins/lookup/redis.py | 3 +++ plugins/lookup/shelvefile.py | 4 ++++ plugins/lookup/tss.py | 10 +++++++++- 15 files changed, 55 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/8626-lookup-types.yml diff --git a/changelogs/fragments/8626-lookup-types.yml b/changelogs/fragments/8626-lookup-types.yml new file mode 100644 index 0000000000..b6ebf35748 --- /dev/null +++ b/changelogs/fragments/8626-lookup-types.yml @@ -0,0 +1,2 @@ +minor_changes: + - "chef_databag, consul_kv, cyberarkpassword, dsv, etcd, filetree, hiera, onepassword, onepassword_doc, onepassword_raw, passwordstore, redis, shelvefile, tss lookup plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8626)." diff --git a/plugins/lookup/chef_databag.py b/plugins/lookup/chef_databag.py index b14d924ae8..a116b21e5f 100644 --- a/plugins/lookup/chef_databag.py +++ b/plugins/lookup/chef_databag.py @@ -22,10 +22,12 @@ DOCUMENTATION = ''' name: description: - Name of the databag + type: string required: true item: description: - Item to fetch + type: string required: true ''' diff --git a/plugins/lookup/consul_kv.py b/plugins/lookup/consul_kv.py index f8aadadc19..79eb65edb1 100644 --- a/plugins/lookup/consul_kv.py +++ b/plugins/lookup/consul_kv.py @@ -29,13 +29,17 @@ DOCUMENTATION = ''' 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. @@ -46,22 +50,26 @@ DOCUMENTATION = ''' 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 ssl connection or not. + 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 ssl connection. + description: The client cert to verify the TLS connection. + type: str env: - name: ANSIBLE_CONSUL_CLIENT_CERT ini: @@ -94,7 +102,7 @@ EXAMPLES = """ - 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') }}" + msg: "{{ lookup('community.general.consul_kv', 'my/key', host='10.10.10.10', port=2000) }}" """ RETURN = """ diff --git a/plugins/lookup/cyberarkpassword.py b/plugins/lookup/cyberarkpassword.py index c3cc427df8..6a08675b3b 100644 --- a/plugins/lookup/cyberarkpassword.py +++ b/plugins/lookup/cyberarkpassword.py @@ -17,19 +17,23 @@ DOCUMENTATION = ''' 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" diff --git a/plugins/lookup/dsv.py b/plugins/lookup/dsv.py index 2dbb7db3ea..5e26c43af4 100644 --- a/plugins/lookup/dsv.py +++ b/plugins/lookup/dsv.py @@ -22,6 +22,7 @@ options: required: true tenant: description: The first format parameter in the default O(url_template). + type: string env: - name: DSV_TENANT ini: @@ -32,6 +33,7 @@ options: 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: @@ -40,6 +42,7 @@ options: required: false client_id: description: The client_id with which to request the Access Grant. + type: string env: - name: DSV_CLIENT_ID ini: @@ -48,6 +51,7 @@ options: required: true client_secret: description: The client secret associated with the specific O(client_id). + type: string env: - name: DSV_CLIENT_SECRET ini: @@ -58,6 +62,7 @@ options: 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: diff --git a/plugins/lookup/etcd.py b/plugins/lookup/etcd.py index 5135e74877..1dec890b20 100644 --- a/plugins/lookup/etcd.py +++ b/plugins/lookup/etcd.py @@ -25,12 +25,14 @@ DOCUMENTATION = ''' 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 diff --git a/plugins/lookup/filetree.py b/plugins/lookup/filetree.py index 2131de99a5..ee7bfe27b7 100644 --- a/plugins/lookup/filetree.py +++ b/plugins/lookup/filetree.py @@ -17,8 +17,10 @@ description: 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 + description: Path(s) of files to read. required: true + type: list + elements: string ''' EXAMPLES = r""" diff --git a/plugins/lookup/hiera.py b/plugins/lookup/hiera.py index fa4d0a1999..02669c98dc 100644 --- a/plugins/lookup/hiera.py +++ b/plugins/lookup/hiera.py @@ -25,12 +25,14 @@ DOCUMENTATION = ''' 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 diff --git a/plugins/lookup/onepassword.py b/plugins/lookup/onepassword.py index 8ca95de0bc..f9b8c6dfa3 100644 --- a/plugins/lookup/onepassword.py +++ b/plugins/lookup/onepassword.py @@ -23,6 +23,8 @@ DOCUMENTATION = ''' _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: diff --git a/plugins/lookup/onepassword_doc.py b/plugins/lookup/onepassword_doc.py index ab24795df2..789e51c35a 100644 --- a/plugins/lookup/onepassword_doc.py +++ b/plugins/lookup/onepassword_doc.py @@ -24,6 +24,8 @@ DOCUMENTATION = ''' _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 diff --git a/plugins/lookup/onepassword_raw.py b/plugins/lookup/onepassword_raw.py index 3eef535a1c..dc3e590329 100644 --- a/plugins/lookup/onepassword_raw.py +++ b/plugins/lookup/onepassword_raw.py @@ -23,6 +23,8 @@ DOCUMENTATION = ''' _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: diff --git a/plugins/lookup/passwordstore.py b/plugins/lookup/passwordstore.py index 9814fe133b..a1b0842a7b 100644 --- a/plugins/lookup/passwordstore.py +++ b/plugins/lookup/passwordstore.py @@ -42,8 +42,9 @@ DOCUMENTATION = ''' default: false umask: description: - - Sets the umask for the created .gpg files. The first octed must be greater than 3 (user readable). + - 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 diff --git a/plugins/lookup/redis.py b/plugins/lookup/redis.py index 43b046a798..17cbf120e9 100644 --- a/plugins/lookup/redis.py +++ b/plugins/lookup/redis.py @@ -19,8 +19,11 @@ DOCUMENTATION = ''' 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 diff --git a/plugins/lookup/shelvefile.py b/plugins/lookup/shelvefile.py index 35f1097c8b..70d18338e9 100644 --- a/plugins/lookup/shelvefile.py +++ b/plugins/lookup/shelvefile.py @@ -15,11 +15,15 @@ DOCUMENTATION = ''' 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 ''' diff --git a/plugins/lookup/tss.py b/plugins/lookup/tss.py index 80105ff715..f2d79ed168 100644 --- a/plugins/lookup/tss.py +++ b/plugins/lookup/tss.py @@ -25,7 +25,8 @@ options: _terms: description: The integer ID of the secret. required: true - type: int + 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 @@ -52,6 +53,7 @@ options: 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: @@ -60,6 +62,7 @@ options: required: true username: description: The username with which to request the OAuth2 Access Grant. + type: string env: - name: TSS_USERNAME ini: @@ -69,6 +72,7 @@ options: description: - The password associated with the supplied username. - Required when O(token) is not provided. + type: string env: - name: TSS_PASSWORD ini: @@ -80,6 +84,7 @@ options: - 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: @@ -92,6 +97,7 @@ options: - 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: @@ -102,6 +108,7 @@ options: 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 @@ -109,6 +116,7 @@ options: 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