common options - change ini section, deprecate old, separate plugin doc fragments

changelogs/fragments/144-deprecate-lookup-ini.yml

@@ -0,0 +1,3 @@
+---
+deprecated_features:
+  - lookup hashi_vault - the ``[lookup_hashi_vault]`` section in the ``ansible.cfg`` file is deprecated and will be removed in collection version ``3.0.0``. Instead, the section ``[hashi_vault_collection]`` can be used, which will apply to all plugins in the collection going forward (https://github.com/ansible-collections/community.hashi_vault/pull/144).

plugins/doc_fragments/auth.py

@@ -15,21 +15,6 @@ class ModuleDocFragment(object):
         description:
           - Authentication method to be used.
           - C(none) auth method was added in collection version C(1.2.0).
-        env:
-          - name: VAULT_AUTH_METHOD
-            deprecated:
-              why: standardizing environment variables
-              version: 2.0.0
-              collection_name: community.hashi_vault
-              alternatives: ANSIBLE_HASHI_VAULT_AUTH_METHOD
-          - name: ANSIBLE_HASHI_VAULT_AUTH_METHOD
-            version_added: '0.2.0'
-        ini:
-          - section: lookup_hashi_vault
-            key: auth_method
-        vars:
-          - name: ansible_hashi_vault_auth_method
-            version_added: '1.2.0'
         choices:
           - token
           - userpass
@@ -49,14 +34,52 @@ class ModuleDocFragment(object):
           - Vault token. Token may be specified explicitly, through the listed [env] vars, and also through the C(VAULT_TOKEN) env var.
           - If no token is supplied, explicitly or through env, then the plugin will check for a token file, as determined by I(token_path) and I(token_file).
           - The order of token loading (first found wins) is C(token param -> ansible var -> ANSIBLE_HASHI_VAULT_TOKEN -> VAULT_TOKEN -> token file).
+      token_path:
+        description: If no token is specified, will try to read the I(token_file) from this path.
+      token_file:
+        description: If no token is specified, will try to read the token from this file in I(token_path).
+        default: '.vault-token'
+      token_validate:
+        description:
+          - For token auth, will perform a C(lookup-self) operation to determine the token's validity before using it.
+          - Disable if your token doesn't have the C(lookup-self) capability.
+        type: boolean
+        default: true
+        version_added: 0.2.0
+      role_id:
+        description: Vault Role ID. Used in approle and aws_iam_login auth methods.
+      secret_id:
+        description: Secret ID to be used for Vault AppRole authentication.
+      jwt:
+        description: The JSON Web Token (JWT) to use for JWT authentication to Vault.
+    '''
+
+    PLUGINS = r'''
+    options:
+      auth_method:
+        env:
+          - name: VAULT_AUTH_METHOD
+            deprecated:
+              why: standardizing environment variables
+              version: 2.0.0
+              collection_name: community.hashi_vault
+              alternatives: ANSIBLE_HASHI_VAULT_AUTH_METHOD
+          - name: ANSIBLE_HASHI_VAULT_AUTH_METHOD
+            version_added: 0.2.0
+        ini:
+          - section: lookup_hashi_vault
+            key: auth_method
+        vars:
+          - name: ansible_hashi_vault_auth_method
+            version_added: 1.2.0
+      token:
         env:
           - name: ANSIBLE_HASHI_VAULT_TOKEN
-            version_added: '0.2.0'
+            version_added: 0.2.0
         vars:
           - name: ansible_hashi_vault_token
-            version_added: '1.2.0'
+            version_added: 1.2.0
       token_path:
-        description: If no token is specified, will try to read the I(token_file) from this path.
         env:
           - name: VAULT_TOKEN_PATH
             deprecated:
@@ -65,15 +88,14 @@ class ModuleDocFragment(object):
               collection_name: community.hashi_vault
               alternatives: ANSIBLE_HASHI_VAULT_TOKEN_PATH
           - name: ANSIBLE_HASHI_VAULT_TOKEN_PATH
-            version_added: '0.2.0'
+            version_added: 0.2.0
         ini:
           - section: lookup_hashi_vault
             key: token_path
         vars:
           - name: ansible_hashi_vault_token_path
-            version_added: '1.2.0'
+            version_added: 1.2.0
       token_file:
-        description: If no token is specified, will try to read the token from this file in I(token_path).
         env:
           - name: VAULT_TOKEN_FILE
             deprecated:
@@ -82,31 +104,23 @@ class ModuleDocFragment(object):
               collection_name: community.hashi_vault
               alternatives: ANSIBLE_HASHI_VAULT_TOKEN_FILE
           - name: ANSIBLE_HASHI_VAULT_TOKEN_FILE
-            version_added: '0.2.0'
+            version_added: 0.2.0
         ini:
           - section: lookup_hashi_vault
             key: token_file
         vars:
           - name: ansible_hashi_vault_token_file
-            version_added: '1.2.0'
-        default: '.vault-token'
+            version_added: 1.2.0
       token_validate:
-        description:
-          - For token auth, will perform a C(lookup-self) operation to determine the token's validity before using it.
-          - Disable if your token doesn't have the C(lookup-self) capability.
         env:
           - name: ANSIBLE_HASHI_VAULT_TOKEN_VALIDATE
         ini:
           - section: lookup_hashi_vault
             key: token_validate
         vars:
           - name: ansible_hashi_vault_token_validate
-            version_added: '1.2.0'
-        type: boolean
-        default: true
-        version_added: 0.2.0
+            version_added: 1.2.0
       role_id:
-        description: Vault Role ID. Used in approle and aws_iam_login auth methods.
         env:
           - name: VAULT_ROLE_ID
             deprecated:
@@ -115,15 +129,14 @@ class ModuleDocFragment(object):
               collection_name: community.hashi_vault
               alternatives: ANSIBLE_HASHI_VAULT_ROLE_ID
           - name: ANSIBLE_HASHI_VAULT_ROLE_ID
-            version_added: '0.2.0'
+            version_added: 0.2.0
         ini:
           - section: lookup_hashi_vault
             key: role_id
         vars:
           - name: ansible_hashi_vault_role_id
-            version_added: '1.2.0'
+            version_added: 1.2.0
       secret_id:
-        description: Secret ID to be used for Vault AppRole authentication.
         env:
           - name: VAULT_SECRET_ID
             deprecated:
@@ -132,12 +145,11 @@ class ModuleDocFragment(object):
               collection_name: community.hashi_vault
               alternatives: ANSIBLE_HASHI_VAULT_SECRET_ID
           - name: ANSIBLE_HASHI_VAULT_SECRET_ID
-            version_added: '0.2.0'
+            version_added: 0.2.0
         vars:
           - name: ansible_hashi_vault_secret_id
-            version_added: '1.2.0'
+            version_added: 1.2.0
       jwt:
-        description: The JSON Web Token (JWT) to use for JWT authentication to Vault.
         env:
           - name: ANSIBLE_HASHI_VAULT_JWT
     '''

plugins/doc_fragments/connection.py

@@ -16,17 +16,7 @@ class ModuleDocFragment(object):
           - URL to the Vault service.
           - If not specified by any other means, the value of the C(VAULT_ADDR) environment variable will be used.
           - If C(VAULT_ADDR) is also not defined then a default of C(http://127.0.0.1:8200) will be used.
-        env:
-          - name: ANSIBLE_HASHI_VAULT_ADDR
-            version_added: '0.2.0'
-        ini:
-          - section: lookup_hashi_vault
-            key: url
-        vars:
-          - name: ansible_hashi_vault_url
-            version_added: '1.2.0'
-          - name: ansible_hashi_vault_addr
-            version_added: '1.2.0'
+        type: str
       proxies:
         description:
           - URL(s) to the proxies used to access the Vault service.
@@ -36,69 +26,31 @@ class ModuleDocFragment(object):
           - A string that can be interpreted as a dictionary will be converted to one (see examples).
           - You can specify a different proxy for HTTP and HTTPS resources.
           - If not specified, L(environment variables from the Requests library,https://requests.readthedocs.io/en/master/user/advanced/#proxies) are used.
-        env:
-          - name: ANSIBLE_HASHI_VAULT_PROXIES
-        ini:
-          - section: lookup_hashi_vault
-            key: proxies
-        vars:
-          - name: ansible_hashi_vault_proxies
-            version_added: '1.2.0'
         type: raw
-        version_added: '1.1.0'
+        version_added: 1.1.0
       ca_cert:
         description:
           - Path to certificate to use for authentication.
           - If not specified by any other means, the C(VAULT_CACERT) environment variable will be used.
-        env:
-          - name: ANSIBLE_HASHI_VAULT_CA_CERT
-            version_added: '1.2.0'
-        ini:
-          - section: lookup_hashi_vault
-            key: ca_cert
-            version_added: '1.2.0'
-        vars:
-          - name: ansible_hashi_vault_ca_cert
-            version_added: '1.2.0'
         aliases: [ cacert ]
       validate_certs:
         description:
           - Controls verification and validation of SSL certificates, mostly you only want to turn off with self signed ones.
           - Will be populated with the inverse of C(VAULT_SKIP_VERIFY) if that is set and I(validate_certs) is not explicitly provided.
           - Will default to C(true) if neither I(validate_certs) or C(VAULT_SKIP_VERIFY) are set.
         type: boolean
-        vars:
-          - name: ansible_hashi_vault_validate_certs
-            version_added: '1.2.0'
       namespace:
         description:
           - Vault namespace where secrets reside. This option requires HVAC 0.7.0+ and Vault 0.11+.
           - Optionally, this may be achieved by prefixing the authentication mount point and/or secret path with the namespace
             (e.g C(mynamespace/secret/mysecret)).
           - If environment variable C(VAULT_NAMESPACE) is set, its value will be used last among all ways to specify I(namespace).
-        env:
-          - name: ANSIBLE_HASHI_VAULT_NAMESPACE
-            version_added: '0.2.0'
-        ini:
-          - section: lookup_hashi_vault
-            key: namespace
-            version_added: '0.2.0'
-        vars:
-          - name: ansible_hashi_vault_namespace
-            version_added: '1.2.0'
       timeout:
         description:
           - Sets the connection timeout in seconds.
           - If not set, then the C(hvac) library's default is used.
-        env:
-          - name: ANSIBLE_HASHI_VAULT_TIMEOUT
-        ini:
-          - section: lookup_hashi_vault
-            key: timeout
-        vars:
-          - name: ansible_hashi_vault_timeout
         type: int
-        version_added: '1.3.0'
+        version_added: 1.3.0
       retries:
         description:
           - "Allows for retrying on errors, based on
@@ -109,30 +61,98 @@ class ModuleDocFragment(object):
           - A number sets the total number of retries, and uses collection defaults for the other settings.
           - A dictionary value is used directly to initialize the C(Retry) class, so it can be used to fully customize retries.
           - For detailed information on retries, see the collection User Guide.
-        env:
-          - name: ANSIBLE_HASHI_VAULT_RETRIES
-        ini:
-          - section: lookup_hashi_vault
-            key: retries
-        vars:
-          - name: ansible_hashi_vault_retries
         type: raw
-        version_added: '1.3.0'
+        version_added: 1.3.0
       retry_action:
         description:
           - Controls whether and how to show messages on I(retries).
           - This has no effect if a request is not retried.
-        env:
-          - name: ANSIBLE_HASHI_VAULT_RETRY_ACTION
-        ini:
-          - section: lookup_hashi_vault
-            key: retry_action
-        vars:
-          - name: ansible_hashi_vault_retry_action
         type: str
         choices:
           - ignore
           - warn
         default: warn
-        version_added: '1.3.0'
+        version_added: 1.3.0
     '''
+
+    PLUGINS = r'''
+      options:
+        url:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_ADDR
+              version_added: 0.2.0
+          ini:
+            - section: hashi_vault_collection
+              key: url
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_url
+              version_added: 1.2.0
+            - name: ansible_hashi_vault_addr
+              version_added: 1.2.0
+        proxies:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_PROXIES
+          ini:
+            - section: hashi_vault_collection
+              key: proxies
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_proxies
+              version_added: 1.2.0
+          type: raw
+          version_added: 1.1.0
+        ca_cert:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_CA_CERT
+              version_added: 1.2.0
+          ini:
+            - section: hashi_vault_collection
+              key: ca_cert
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_ca_cert
+              version_added: 1.2.0
+        validate_certs:
+          vars:
+            - name: ansible_hashi_vault_validate_certs
+              version_added: 1.2.0
+        namespace:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_NAMESPACE
+              version_added: 0.2.0
+          ini:
+            - section: hashi_vault_collection
+              key: namespace
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_namespace
+              version_added: 1.2.0
+        timeout:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_TIMEOUT
+          ini:
+            - section: hashi_vault_collection
+              key: timeout
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_timeout
+        retries:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_RETRIES
+          ini:
+            - section: hashi_vault_collection
+              key: retries
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_retries
+        retry_action:
+          env:
+            - name: ANSIBLE_HASHI_VAULT_RETRY_ACTION
+          ini:
+            - section: hashi_vault_collection
+              key: retry_action
+              version_added: 1.4.0
+          vars:
+            - name: ansible_hashi_vault_retry_action
+      '''