consolidate arg specs

plugins/doc_fragments/vmware.py

@@ -13,119 +13,62 @@
 class ModuleDocFragment(object):
     # Parameters for VMware modules
     DOCUMENTATION = r'''
-notes:
-  - All modules require API write access and hence is not supported on a free ESXi license.
-  - All variables and VMware object names are case sensitive.
-options:
-    hostname:
-      description:
-      - The hostname or IP address of the vSphere vCenter or ESXi server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_HOST) will be used instead.
-      type: str
-    username:
-      description:
-      - The username of the vSphere vCenter or ESXi server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_USER) will be used instead.
-      type: str
-      aliases: [ admin, user ]
-    password:
-      description:
-      - The password of the vSphere vCenter or ESXi server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PASSWORD) will be used instead.
-      type: str
-      aliases: [ pass, pwd ]
-    validate_certs:
-      description:
-      - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_VALIDATE_CERTS) will be used instead.
-      type: bool
-      default: true
-    port:
-      description:
-      - The port number of the vSphere vCenter or ESXi server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PORT) will be used instead.
-      type: int
-      default: 443
-    datacenter:
-      description:
-      - The datacenter to use when connecting to a vCenter.
-      type: str
-      aliases: [ datacenter_name ]
-    cluster:
-      description:
-      - The cluster to use when connecting to a vCenter.
-      type: str
-      aliases: [ cluster_name ]
-    proxy_host:
-      description:
-      - Address of a proxy that will receive all HTTPS requests and relay them.
-      - The format is a hostname or a IP.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_HOST) will be used instead.
-      type: str
-      required: false
-    proxy_port:
-      description:
-      - Port of the HTTP proxy that will receive all HTTPS requests and relay them.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
-      type: int
-      required: false
-'''
-
-    # This doc fragment is specific to vcenter modules like vcenter_license
-    VCENTER_DOCUMENTATION = r'''
-notes:
-  - All modules require API write access and hence is not supported on a free ESXi license.
-options:
-    hostname:
-      description:
-      - The hostname or IP address of the vSphere vCenter server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_HOST) will be used instead.
-      type: str
-    username:
-      description:
-      - The username of the vSphere vCenter server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_USER) will be used instead.
-      type: str
-      aliases: [ admin, user ]
-    password:
-      description:
-      - The password of the vSphere vCenter server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PASSWORD) will be used instead.
-      type: str
-      aliases: [ pass, pwd ]
-    validate_certs:
-      description:
-      - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_VALIDATE_CERTS) will be used instead.
-      type: bool
-      default: true
-    port:
-      description:
-      - The port number of the vSphere vCenter server.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PORT) will be used instead.
-      type: int
-      default: 443
-    datacenter:
-      description:
-      - The datacenter to use when connecting to a vCenter.
-      type: str
-      aliases: [ datacenter_name ]
-    cluster:
-      description:
-      - The cluster to use when connecting to a vCenter.
-      type: str
-      aliases: [ cluster_name ]
-    proxy_host:
-      description:
-      - Address of a proxy that will receive all HTTPS requests and relay them.
-      - The format is a hostname or a IP.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_HOST) will be used instead.
-      type: str
-      required: false
-    proxy_port:
-      description:
-      - Port of the HTTP proxy that will receive all HTTPS requests and relay them.
-      - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
-      type: int
-      required: false
+      notes:
+        - All modules require API write access and hence is not supported on a free ESXi license.
+        - All variables and VMware object names are case sensitive.
+        - >-
+            Modules may rely on the 'requests' python library, which does not use the system certificate store by default. You can
+            specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable.
+            Example: 'export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem'
+      options:
+        hostname:
+          description:
+            - The hostname or IP address of the vSphere vCenter server.
+            - If the value is not specified in the task, the value of environment variable E(VMWARE_HOST) will be used instead.
+          type: str
+        username:
+          description:
+            - The username of the vSphere vCenter server.
+            - If the value is not specified in the task, the value of environment variable E(VMWARE_USER) will be used instead.
+          type: str
+          aliases: [ admin, user ]
+        password:
+          description:
+            - The password of the vSphere vCenter server.
+            - If the value is not specified in the task, the value of environment variable E(VMWARE_PASSWORD) will be used instead.
+          type: str
+          aliases: [ pass, pwd ]
+        validate_certs:
+          description:
+            - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
+            - If the value is not specified in the task, the value of environment variable E(VMWARE_VALIDATE_CERTS) will be used instead.
+          type: bool
+          default: true
+        port:
+          description:
+            - The port number of the vSphere vCenter server.
+            - If the value is not specified in the task, the value of environment variable E(VMWARE_PORT) will be used instead.
+          type: int
+          default: 443
+        proxy_protocol:
+          description:
+            - The proxy connection protocol to use.
+            - This is option is used if the correct proxy protocol cannot be automatically determined.
+          type: str
+          choices: [ http, https ]
+          default: https
+          aliases: [protocol]
+        proxy_host:
+          description:
+            - Address of a proxy that will receive all HTTPS requests and relay them.
+            - The format is a hostname or a IP.
+            - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_HOST) will be used instead.
+          type: str
+          required: false
+        proxy_port:
+          description:
+          - Port of the HTTP proxy that will receive all HTTPS requests and relay them.
+          - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
+          type: int
+          required: false
     '''

plugins/module_utils/_vmware_argument_spec.py

@@ -0,0 +1,54 @@
+from ansible.module_utils.basic import env_fallback
+
+
+def base_arg_spec():
+    return dict(
+        hostname = dict(
+            type='str',
+            required=False,
+            fallback=(env_fallback, ['VMWARE_HOST']),
+        ),
+        username = dict(
+            type='str',
+            aliases=['user', 'admin'],
+            required=False,
+            fallback=(env_fallback, ['VMWARE_USER'])
+        ),
+        password=dict(
+            type='str',
+            aliases=['pass', 'pwd'],
+            required=False,
+            no_log=True,
+            fallback=(env_fallback, ['VMWARE_PASSWORD'])
+        ),
+        port = dict(
+            type='int',
+            default=443,
+            required=False,
+            fallback=(env_fallback, ['VMWARE_PORT'])
+        ),
+        validate_certs = dict(
+            type='bool',
+            required=False,
+            default=True,
+            fallback=(env_fallback, ['VMWARE_VALIDATE_CERTS'])
+        ),
+        proxy_protocol = dict(
+            type='str',
+            default='https',
+            choices=['https', 'http'],
+            aliases=['protocol']
+        ),
+        proxy_host = dict(
+            type='str',
+            required=False,
+            default=None,
+            fallback=(env_fallback, ['VMWARE_PROXY_HOST'])
+        ),
+        proxy_port = dict(
+            type='int',
+            required=False,
+            default=None,
+            fallback=(env_fallback, ['VMWARE_PROXY_PORT'])
+        ),
+    )

plugins/module_utils/_vmware.py → plugins/module_utils/_vmware_pyvmomi.py

@@ -14,72 +14,28 @@
 import ssl
 import traceback
 
+# requests is required for exception handling of the ConnectionError
 REQUESTS_IMP_ERR = None
 try:
-    # requests is required for exception handling of the ConnectionError
     import requests
-    HAS_REQUESTS = True
 except ImportError:
     REQUESTS_IMP_ERR = traceback.format_exc()
-    HAS_REQUESTS = False
 
 PYVMOMI_IMP_ERR = None
 try:
     from pyVim import connect
     from pyVmomi import vim, vmodl
-    HAS_PYVMOMI = True
 except ImportError:
     PYVMOMI_IMP_ERR = traceback.format_exc()
-    HAS_PYVMOMI = False
 
-from ansible.module_utils.basic import env_fallback, missing_required_lib
+from ansible.module_utils.basic import missing_required_lib
 
 
 class ApiAccessError(Exception):
     def __init__(self, *args, **kwargs):
         super(ApiAccessError, self).__init__(*args, **kwargs)
 
 
-def vmware_argument_spec():
-    return dict(
-        hostname=dict(type='str',
-                      required=False,
-                      fallback=(env_fallback, ['VMWARE_HOST']),
-                      ),
-        username=dict(type='str',
-                      aliases=['user', 'admin'],
-                      required=False,
-                      fallback=(env_fallback, ['VMWARE_USER'])),
-        password=dict(type='str',
-                      aliases=['pass', 'pwd'],
-                      required=False,
-                      no_log=True,
-                      fallback=(env_fallback, ['VMWARE_PASSWORD'])),
-        cluster=dict(type='str',
-                     aliases=['cluster_name'],
-                     required=False),
-        datacenter=dict(type='str',
-                        aliases=['datacenter_name'],
-                        required=False),
-        port=dict(type='int',
-                  default=443,
-                  fallback=(env_fallback, ['VMWARE_PORT'])),
-        validate_certs=dict(type='bool',
-                            required=False,
-                            default=True,
-                            fallback=(env_fallback, ['VMWARE_VALIDATE_CERTS'])
-                            ),
-        proxy_host=dict(type='str',
-                        required=False,
-                        default=None,
-                        fallback=(env_fallback, ['VMWARE_PROXY_HOST'])),
-        proxy_port=dict(type='int',
-                        required=False,
-                        default=None,
-                        fallback=(env_fallback, ['VMWARE_PROXY_PORT'])),
-    )
-
-
 def connect_to_api(module, disconnect_atexit=True, return_si=False, hostname=None, username=None, password=None,
                    port=None, validate_certs=None,
                    httpProxyHost=None, httpProxyPort=None):
@@ -192,11 +148,11 @@ def __init__(self, module):
         """
         Constructor
         """
-        if not HAS_REQUESTS:
+        if not REQUESTS_IMP_ERR:
             module.fail_json(msg=missing_required_lib('requests'),
                              exception=REQUESTS_IMP_ERR)
 
-        if not HAS_PYVMOMI:
+        if not PYVMOMI_IMP_ERR:
             module.fail_json(msg=missing_required_lib('PyVmomi'),
                              exception=PYVMOMI_IMP_ERR)
 

plugins/modules/cluster.py

@@ -91,10 +91,8 @@
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils._text import to_native
 
-from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
-)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_pymomi import PyVmomi
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import base_arg_spec
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
     RunningTaskMonitor
@@ -182,7 +180,7 @@ def get_cluster_outputs(self):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_arg_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name', 'name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
                 state=dict(type='str', default='present', choices=['absent', 'present']),

plugins/modules/cluster_dpm.py

@@ -109,10 +109,8 @@
     pass
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
-)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_pymomi import PyVmomi
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import base_arg_spec
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
     RunningTaskMonitor
@@ -208,7 +206,7 @@ def apply_dpm_configuration(self):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_arg_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
                 enable=dict(type='bool', default=True),

plugins/modules/cluster_drs.py

@@ -135,10 +135,9 @@
     pass
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
-)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_pymomi import PyVmomi
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import base_arg_spec
+
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
     RunningTaskMonitor
@@ -246,7 +245,7 @@ def apply_drs_configuration(self):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_arg_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
                 enable=dict(type='bool', default=True),