[PR #8626/daed4dcc backport][stable-9] Type options of lookup plugins (#8660)

Type options of lookup plugins (#8626)

Type options of lookup plugins.

(cherry picked from commit daed4dcc94)

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

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)."

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
 '''
 

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 = """

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.<property>, PasswordChangeInProcess"
+        type: string
         default: 'password'
       _extra:
         description: for extra_params values please check parameters for clipasswordsdk in CyberArk's "Credential Provider and ASCP Implementation Guide"

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:

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

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"""

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

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:

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

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:

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

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

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
 '''
 

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